@rainbow-robotics/preview-host

@rainbow-robotics/preview-host is a standalone mini-Muscat (nexus) shell for previewing Muscat plugins without a robot or backend.

It's built by building apps/web/nexus in plugin-preview mode.

This preview shell provides a UI as close as possible to the real Muscat environment.

• Real Header
• Real LNB
• Real panel structure
• Real rb-components
• Plugin manifest-based loading

Robot- and backend-related dependencies, on the other hand, are all mocked.

• No robot connection required
• No backend server required
• API-failure toasts hidden
• Query retry disabled
• RB static resources served locally

This package is used by muscat-plugin-kit's:

muscat-pk dev:ui

This lets external plugin developers preview their plugin in a Muscat-like environment without the web-rainbow-ui monorepo source.

Build

node build.mjs

Builds nexus in plugin-preview mode, then assembles the files needed to run into the ./dist directory.

If nexus has already been built, you can use:

node build.mjs --skip-build

This skips rebuilding nexus and only reassembles ./dist from the existing build output.

The generated dist/ directory is excluded from Git.

dist/ is structured to be runnable standalone.

Main contents:

• nexus bundle
• RB static resources
• images
• fonts
• other runtime resources

Static resources are served at the same paths used at real runtime.

/imgs
/fonts
...

Run

rb-preview-host --plugin <built-plugin-dir> [--port 4180] [--dist <dir>]

Options

--plugin points to a plugin build directory produced by muscat-pk build.

rb-preview-host --plugin ./dist/plugin

--port sets the port preview-host runs on.

Defaults to 4180.

rb-preview-host \
  --plugin ./dist/plugin \
  --port 4180

--dist overrides the preview-host static bundle directory.

rb-preview-host \
  --plugin ./dist/plugin \
  --dist ./preview-host-dist

The following options are also supported (all optional — muscat-pk dev fills them in internally).

• --socket-url: the Socket.IO URL the plugin connects to (window.__RB_PLUGIN_PREVIEW_SOCKET_URL__)
• --robot-host: robot host override (window.__RB_ROBOT_HOST__)
• --dev-server-url: the plugin's own Vite dev server URL (window.__RB_PLUGIN_DEV_SERVER_URL__) — used when mounting a dev UI entry directly

Plugin build directory requirements

The directory passed to --plugin must be an output directory from muscat-pk build.

It must contain:

manifest.json
<ui-entry>.js  (e.g. content.js — one is generated per manifest contributes[].ui entry)
assets/

The host mounts <ui-entry>.js by importing it directly as a plain ESM module — no sandbox.html/iframe is involved.

assets/ is only present if the plugin uses its own static resources.

The plugin directory you specify is mounted in preview host at:

/plugin-dev/

The preview shell resolves the plugin and static-resource locations through the global variables serve.mjs injects.

Global variables

window.__RB_PLUGIN_PREVIEW_HOST__

Activates preview-host mode.

window.__RB_PLUGIN_PREVIEW_HOST__ = true;

When set, nexus runs against a mock environment instead of the real backend.

Typical effects:

• Mocked robot connection
• Mocked backend API
• Suppressed API-failure toasts
• Disabled query retry

window.__RB_PLUGIN_PREVIEW_BASE__

The base URL the plugin is served from.

Defaults to:

/plugin-dev

Example:

window.__RB_PLUGIN_PREVIEW_BASE__ = "/plugin-dev";

The preview shell reads the following files relative to this path:

/plugin-dev/manifest.json
/plugin-dev/<ui-entry>.js
/plugin-dev/assets/*

window.__RB_ASSETS_BASE_URL__

The origin RB static resources are served from.

Example:

window.__RB_ASSETS_BASE_URL__ = "http://localhost:4180";

This lets preview host load the static resources used by nexus and rb-components.

Typical resource paths:

/imgs
/fonts

Global variable summary

| Global variable | Meaning | | ----------------------------------- | --------------------------------------- | | window.__RB_PLUGIN_PREVIEW_HOST__ | Activates preview-host mode and mocks backend dependencies | | window.__RB_PLUGIN_PREVIEW_BASE__ | Base URL the plugin is mounted at. Defaults to /plugin-dev | | window.__RB_ASSETS_BASE_URL__ | Origin serving RB images, fonts, and other static resources |

Relationship to dev mode

muscat-pk dev:ui runs nexus's Vite dev server directly.

vite --mode plugin-preview

This is a dev-mode preview-host runtime with HMR enabled.

In other words, muscat-pk dev:ui and @rainbow-robotics/preview-host aren't separate implementations — they're the same preview-host runtime used in two different forms.

muscat-pk dev:ui

Runs the Vite dev server directly against the monorepo source.

Characteristics:

• Vite-based dev server
• HMR support
• Source changes reflected immediately
• Suited for development

@rainbow-robotics/preview-host

The same runtime packaged as a static bundle for distribution.

Characteristics:

• No monorepo source required
• Uses a prebuilt nexus bundle
• Runs standalone
• Distributable to external plugin developers

The overall relationship:

apps/web/nexus
  └─ plugin-preview mode
      ├─ muscat-pk dev:ui
      │   └─ runs the Vite dev server directly
      │       └─ HMR support
      │
      └─ @rainbow-robotics/preview-host
          └─ packaged as a static bundle
              └─ runs without the monorepo source

As a result, external developers get a Muscat-like preview environment — without holding a copy of the web-rainbow-ui source — that includes:

• Real nexus layout
• Real Header and LNB
• Real panels
• Real rb-components
• Real manifest-based plugin loading
• Mocked robot and backend environment