@rainbow-robotics/preview-host 1.3.8-dev.2 → 1.10.1-dev.0

package/README.md

@@ -1,254 +1,254 @@
-# `@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:
-
-```bash
-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
-
-```bash
-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:
-
-```bash
-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.
-
-```text
-/imgs
-/fonts
-...
-```
-
-## Run
-
-```bash
-rb-preview-host --plugin <built-plugin-dir> [--port 4180] [--dist <dir>]
-```
-
-### Options
-
-`--plugin` points to a plugin build directory produced by `muscat-pk build`.
-
-```bash
-rb-preview-host --plugin ./dist/plugin
-```
-
-`--port` sets the port preview-host runs on.
-
-Defaults to `4180`.
-
-```bash
-rb-preview-host \
-  --plugin ./dist/plugin \
-  --port 4180
-```
-
-`--dist` overrides the preview-host static bundle directory.
-
-```bash
-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:
-
-```text
-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:
-
-```text
-/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.
-
-```ts
-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:
-
-```text
-/plugin-dev
-```
-
-Example:
-
-```ts
-window.__RB_PLUGIN_PREVIEW_BASE__ = "/plugin-dev";
-```
-
-The preview shell reads the following files relative to this path:
-
-```text
-/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:
-
-```ts
-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:
-
-```text
-/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.
-
-```bash
-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:
-
-```text
-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
+# `@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:
+
+```bash
+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
+
+```bash
+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:
+
+```bash
+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.
+
+```text
+/imgs
+/fonts
+...
+```
+
+## Run
+
+```bash
+rb-preview-host --plugin <built-plugin-dir> [--port 4180] [--dist <dir>]
+```
+
+### Options
+
+`--plugin` points to a plugin build directory produced by `muscat-pk build`.
+
+```bash
+rb-preview-host --plugin ./dist/plugin
+```
+
+`--port` sets the port preview-host runs on.
+
+Defaults to `4180`.
+
+```bash
+rb-preview-host \
+  --plugin ./dist/plugin \
+  --port 4180
+```
+
+`--dist` overrides the preview-host static bundle directory.
+
+```bash
+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:
+
+```text
+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:
+
+```text
+/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.
+
+```ts
+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:
+
+```text
+/plugin-dev
+```
+
+Example:
+
+```ts
+window.__RB_PLUGIN_PREVIEW_BASE__ = "/plugin-dev";
+```
+
+The preview shell reads the following files relative to this path:
+
+```text
+/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:
+
+```ts
+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:
+
+```text
+/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.
+
+```bash
+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:
+
+```text
+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

package/build.mjs

@@ -1,53 +1,53 @@
-// Builds the standalone preview-host bundle.
-//
-// 1. Builds nexus in `plugin-preview` mode (standalone mini-Muscat shell with
-//    the preview-host runtime flag baked into index.html).
-// 2. Assembles a self-contained `dist/` here: the nexus bundle plus the rb
-//    static assets (imgs/fonts/...) served at their runtime paths.
-//
-// Run: node libraries/preview-host/build.mjs [--skip-build]
-import { execSync } from "node:child_process";
-import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-// This file lives at <repo>/libraries/preview-host/build.mjs
-const here = dirname(fileURLToPath(import.meta.url));
-const repoRoot = resolve(here, "../..");
-const nexusDir = resolve(repoRoot, "apps/web/nexus");
-const nexusDist = resolve(nexusDir, "dist-preview");
-const assetsPublic = resolve(repoRoot, "apps/web/assets/public");
-const outDir = resolve(here, "dist");
-
-const skipBuild = process.argv.includes("--skip-build");
-
-if (!skipBuild) {
-  console.log("[preview-host] building mini-muscat (plugin-preview)…");
-  execSync("yarn workspace @app/nexus build:preview", {
-    cwd: repoRoot,
-    stdio: "inherit",
-    env: { ...process.env, VITE_PLUGIN_PREVIEW: "true" },
-  });
-}
-
-if (!existsSync(nexusDist)) {
-  throw new Error(
-    `nexus preview build not found at ${nexusDist}. Run without --skip-build.`,
-  );
-}
-
-console.log("[preview-host] assembling dist…");
-rmSync(outDir, { recursive: true, force: true });
-mkdirSync(outDir, { recursive: true });
-
-// nexus bundle (index.html + assets/)
-cpSync(nexusDist, outDir, { recursive: true });
-
-// rb static assets served at runtime (/imgs, /fonts, ...)
-// models/ excluded — too large for npm (700MB+), 3D robot view unavailable in external preview
-for (const dir of ["imgs", "fonts", "sounds", "data"]) {
-  const src = resolve(assetsPublic, dir);
-  if (existsSync(src)) cpSync(src, resolve(outDir, dir), { recursive: true });
-}
-
-console.log("[preview-host] dist ready →", outDir);
+// Builds the standalone preview-host bundle.
+//
+// 1. Builds nexus in `plugin-preview` mode (standalone mini-Muscat shell with
+//    the preview-host runtime flag baked into index.html).
+// 2. Assembles a self-contained `dist/` here: the nexus bundle plus the rb
+//    static assets (imgs/fonts/...) served at their runtime paths.
+//
+// Run: node libraries/preview-host/build.mjs [--skip-build]
+import { execSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// This file lives at <repo>/libraries/preview-host/build.mjs
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(here, "../..");
+const nexusDir = resolve(repoRoot, "apps/web/nexus");
+const nexusDist = resolve(nexusDir, "dist-preview");
+const assetsPublic = resolve(repoRoot, "apps/web/assets/public");
+const outDir = resolve(here, "dist");
+
+const skipBuild = process.argv.includes("--skip-build");
+
+if (!skipBuild) {
+  console.log("[preview-host] building mini-muscat (plugin-preview)…");
+  execSync("yarn workspace @app/nexus build:preview", {
+    cwd: repoRoot,
+    stdio: "inherit",
+    env: { ...process.env, VITE_PLUGIN_PREVIEW: "true" },
+  });
+}
+
+if (!existsSync(nexusDist)) {
+  throw new Error(
+    `nexus preview build not found at ${nexusDist}. Run without --skip-build.`,
+  );
+}
+
+console.log("[preview-host] assembling dist…");
+rmSync(outDir, { recursive: true, force: true });
+mkdirSync(outDir, { recursive: true });
+
+// nexus bundle (index.html + assets/)
+cpSync(nexusDist, outDir, { recursive: true });
+
+// rb static assets served at runtime (/imgs, /fonts, ...)
+// models/ excluded — too large for npm (700MB+), 3D robot view unavailable in external preview
+for (const dir of ["imgs", "fonts", "sounds", "data"]) {
+  const src = resolve(assetsPublic, dir);
+  if (existsSync(src)) cpSync(src, resolve(outDir, dir), { recursive: true });
+}
+
+console.log("[preview-host] dist ready →", outDir);