@rainbow-robotics/plugin-ui 1.3.8-dev.4 → 1.10.1-dev.0

package/README.md

@@ -1,246 +1,246 @@
-# @rainbow-robotics/plugin-ui
-
-# Muscat plugin UI contract and host mounting architecture
-
-A Muscat plugin is a plain React component exported as `export default App`.
-
-Plugin mounting works through two paths, both handled by the `./host` package.
-
-## Dev environment: `muscat-pk dev`
-
-In dev, the plugin's own Vite dev server (using the plugin's `vite.config.ts`) serves a bootstrap module.
-
-The host dynamically imports that bootstrap module to run the plugin.
-
-Characteristics of this approach:
-
-* Full HMR support
-* The plugin runs as its own independent React root
-* The plugin uses its own React instance
-* The host's React tree and the plugin's React tree are separate
-
-In other words, in dev the plugin runs inside the host page, but it does not share the React runtime with the host.
-
-## Build & robot environment: `muscat-pk build`
-
-`muscat-pk build` is not its own bundler — it's a thin wrapper that **runs `vite build` using the plugin project's own `vite.config.ts`**
-(no `--config` is passed; it just sets `cwd` to the plugin root and runs `vite build` — Vite reads that directory's `vite.config.ts` on its own).
-
-The scaffolded `vite.config.ts` looks like this:
-
-```ts
-import { defineConfig } from "vite";
-import tailwindcss from "@tailwindcss/vite";
-import { muscat } from "@rainbow-robotics/muscat-plugin-kit/vite";
-export default defineConfig({ plugins: [tailwindcss(), muscat()] });
-```
-
-**The external list and rollup config live in `@rainbow-robotics/muscat-plugin-kit`'s `muscat()` preset (`cli/vite.mjs`), not in this package (`@rainbow-robotics/plugin-ui`).** The roles split as follows:
-
-| Package | Responsibility |
-|---|---|
-| `@rainbow-robotics/muscat-plugin-kit` | Build time — the `muscat()` preset (external list, entry discovery, rollup config) |
-| `@rainbow-robotics/plugin-ui` (this package) | Runtime — `./host` (mounting), `./vite-host` (import-map injection on the nexus side) |
-
-The `muscat()` preset leaves the following dependencies out of the plugin bundle as external bare specifiers:
-
-```text
-react
-react-dom
-@rainbow-robotics/plugin-ui/*
-@repo/rb-components
-```
-
-The host page includes an import map set up by `./vite-host`.
-
-This import map resolves those bare specifiers to the actual module instances the host has already loaded.
-
-So a plugin loaded in production behaves as follows:
-
-* Uses the same React instance as the host
-* Mounts as a real nested React tree inside the host's React tree
-* Shares `RbContext`
-* Shares the host's UI context
-* Minimizes the plugin bundle size
-
-In dev the plugin runs as its own independent React root; in build/robot environments it runs nested inside the host's React tree.
-
-### Plugins with no UI skip the vite build entirely
-
-`muscat-pk build` collects `contributes[].ui` from `manifest.json` and verifies that a matching `ui/{name}.tsx` (or `.ts`/`.jsx`/`.js`) file actually exists.
-
-* If `contributes` declares a `ui` but the file doesn't exist → build fails (clear error)
-* If `contributes` declares no `ui` and the `ui/` directory has no files either (a backend-only plugin) → **the vite build is skipped entirely.** `dist/` only contains manifest.json/assets/backend files.
-
-This logic lives in `buildPlugin()` in `libraries/muscat-plugin-kit/cli/src/build.mjs`.
-
-### When Node.js isn't available
-
-`muscat-pk build` isn't its own bundler — it **spawns `vite build` as a child process**, so a JS runtime must be available to run that child process.
-
-* **`muscat-pk` installed via npm** → already running under Node, so this issue never occurs.
-* **`muscat-pk` installed via the S3 self-contained binary (compiled with Bun)** → looks on PATH in order: `bun` → `node` → `nodejs`. If none are found:
-
-  ```
-  Node.js 20+ (or Bun) is required to build the plugin UI.
-    Install Node.js: https://nodejs.org
-    Then run: npm install  (inside the plugin directory)
-  ```
-
-  is printed and the process exits with `exitCode 1` quietly (no stack trace). This logic lives in `findJsRuntime()` / `runViteBuild()` in `build.mjs`.
-
-# Entry points
-
-## `./react`
-
-Used by:
-
-```text
-plugin
-```
-
-Re-exports every `new-components` export from `@repo/rb-components`, plus the `useRb`, `useRbFormData`, and `useRbSave` hooks from `./sdk`.
-
-Plugins should use UI components through this entry point rather than importing `@repo/rb-components` directly.
-
-`muscat-pk mcp` parses this package's `dist/react.d.ts` (a self-contained bundle of rb-components' types) to give AI coding agents component lists and prop info.
-
-## `./sdk`
-
-Used by:
-
-```text
-plugin
-```
-
-Provides `useRb()`.
-
-`useRb()` gives access to:
-
-* Zenoh-WebSocket-based robot publish
-* subscribe
-* action calls
-* serve
-* toast
-* alert
-* confirm
-* prompt
-
-Instead of implementing dialog/toast UI itself, a plugin delegates these requests to the host's real dialog and toast implementation.
-
-See `./host-ui` for the actual host UI service implementation.
-
-`useRbFormData()` / `useRbSave()` are also provided by `./sdk`. The host passes previously-saved `data` to the plugin, and the plugin registers a payload getter via `onSave` — form save/restore is owned by the host, not the plugin.
-
-## `./ws`
-
-Used by:
-
-```text
-plugin dev bootstrap only
-```
-
-Provides `RbWs`.
-
-`RbWs` is the WebSocket client `useRb()` uses internally.
-
-This entry point isn't used by a plugin's normal production code — it's only used by the dev-environment bootstrap module.
-
-## `./manifest`
-
-Used by:
-
-```text
-nexus
-muscat-pk
-```
-
-Provides the plugin manifest schema.
-
-Acts as the single source of truth for the manifest definition.
-
-`contributes[].point` (`CONTRIBUTION_POINTS`) has 4 possible values:
-
-| point | Description |
-|---|---|
-| `toolbar` | A live UI panel exposed in the top toolbar |
-| `lnb` | A live UI panel exposed in the left navigation bar (LNB) |
-| `move.panel` | A live UI panel exposed in the Move panel |
-| `program.panel` | A custom command the plugin defines for the Program page's rule-based sequence builder |
-
-`toolbar`/`lnb`/`move.panel` back ends use `RBManipulateSDK`/`RBAmrSDK` or `rb.action()` directly. `program.panel` declares `commandInfo` (`funcName: "rb_program_sdk.plugin_execute"`) and its backend runs through `PluginProgramContext` (`on_execute`, `check_stop`, `get_variable`, `set_variable`, `done`).
-
-## `./plugin-data`
-
-Used by:
-
-```text
-nexus only
-```
-
-Provides:
-
-```text
-PluginDataProvider
-usePluginData()
-```
-
-Decides where and how a plugin is loaded from.
-
-## `./host`
-
-Used by:
-
-```text
-nexus only
-```
-
-Provides `PluginHost`.
-
-`PluginHost` handles both mounting paths described above:
-
-* The dev environment's dynamic Vite bootstrap import
-* The build/robot environment's ESM module mount
-
-## `./vite-host`
-
-Used by:
-
-```text
-nexus vite.config.ts
-```
-
-Provides Vite plugins.
-
-Main responsibilities:
-
-* Injecting the import map
-* Supporting the plugin preview dev environment
-
-# Plugin production bundle rules
-
-A plugin's production bundle should only import these entry points:
-
-```text
-./react
-./sdk
-./host-ui
-```
-
-`./host-ui` is used optionally, only when needed.
-
-The following entry points, on the other hand, are host-only:
-
-```text
-./host
-./vite-host
-```
-
-These modules include host-only dependencies:
-
-```text
-@repo/rb-components
-vite
-```
-
-So `./host` and `./vite-host` are never included in a plugin bundle.
+# @rainbow-robotics/plugin-ui
+
+# Muscat plugin UI contract and host mounting architecture
+
+A Muscat plugin is a plain React component exported as `export default App`.
+
+Plugin mounting works through two paths, both handled by the `./host` package.
+
+## Dev environment: `muscat-pk dev`
+
+In dev, the plugin's own Vite dev server (using the plugin's `vite.config.ts`) serves a bootstrap module.
+
+The host dynamically imports that bootstrap module to run the plugin.
+
+Characteristics of this approach:
+
+* Full HMR support
+* The plugin runs as its own independent React root
+* The plugin uses its own React instance
+* The host's React tree and the plugin's React tree are separate
+
+In other words, in dev the plugin runs inside the host page, but it does not share the React runtime with the host.
+
+## Build & robot environment: `muscat-pk build`
+
+`muscat-pk build` is not its own bundler — it's a thin wrapper that **runs `vite build` using the plugin project's own `vite.config.ts`**
+(no `--config` is passed; it just sets `cwd` to the plugin root and runs `vite build` — Vite reads that directory's `vite.config.ts` on its own).
+
+The scaffolded `vite.config.ts` looks like this:
+
+```ts
+import { defineConfig } from "vite";
+import tailwindcss from "@tailwindcss/vite";
+import { muscat } from "@rainbow-robotics/muscat-plugin-kit/vite";
+export default defineConfig({ plugins: [tailwindcss(), muscat()] });
+```
+
+**The external list and rollup config live in `@rainbow-robotics/muscat-plugin-kit`'s `muscat()` preset (`cli/vite.mjs`), not in this package (`@rainbow-robotics/plugin-ui`).** The roles split as follows:
+
+| Package | Responsibility |
+|---|---|
+| `@rainbow-robotics/muscat-plugin-kit` | Build time — the `muscat()` preset (external list, entry discovery, rollup config) |
+| `@rainbow-robotics/plugin-ui` (this package) | Runtime — `./host` (mounting), `./vite-host` (import-map injection on the nexus side) |
+
+The `muscat()` preset leaves the following dependencies out of the plugin bundle as external bare specifiers:
+
+```text
+react
+react-dom
+@rainbow-robotics/plugin-ui/*
+@repo/rb-components
+```
+
+The host page includes an import map set up by `./vite-host`.
+
+This import map resolves those bare specifiers to the actual module instances the host has already loaded.
+
+So a plugin loaded in production behaves as follows:
+
+* Uses the same React instance as the host
+* Mounts as a real nested React tree inside the host's React tree
+* Shares `RbContext`
+* Shares the host's UI context
+* Minimizes the plugin bundle size
+
+In dev the plugin runs as its own independent React root; in build/robot environments it runs nested inside the host's React tree.
+
+### Plugins with no UI skip the vite build entirely
+
+`muscat-pk build` collects `contributes[].ui` from `manifest.json` and verifies that a matching `ui/{name}.tsx` (or `.ts`/`.jsx`/`.js`) file actually exists.
+
+* If `contributes` declares a `ui` but the file doesn't exist → build fails (clear error)
+* If `contributes` declares no `ui` and the `ui/` directory has no files either (a backend-only plugin) → **the vite build is skipped entirely.** `dist/` only contains manifest.json/assets/backend files.
+
+This logic lives in `buildPlugin()` in `libraries/muscat-plugin-kit/cli/src/build.mjs`.
+
+### When Node.js isn't available
+
+`muscat-pk build` isn't its own bundler — it **spawns `vite build` as a child process**, so a JS runtime must be available to run that child process.
+
+* **`muscat-pk` installed via npm** → already running under Node, so this issue never occurs.
+* **`muscat-pk` installed via the S3 self-contained binary (compiled with Bun)** → looks on PATH in order: `bun` → `node` → `nodejs`. If none are found:
+
+  ```
+  Node.js 20+ (or Bun) is required to build the plugin UI.
+    Install Node.js: https://nodejs.org
+    Then run: npm install  (inside the plugin directory)
+  ```
+
+  is printed and the process exits with `exitCode 1` quietly (no stack trace). This logic lives in `findJsRuntime()` / `runViteBuild()` in `build.mjs`.
+
+# Entry points
+
+## `./react`
+
+Used by:
+
+```text
+plugin
+```
+
+Re-exports every `new-components` export from `@repo/rb-components`, plus the `useRb`, `useRbFormData`, and `useRbSave` hooks from `./sdk`.
+
+Plugins should use UI components through this entry point rather than importing `@repo/rb-components` directly.
+
+`muscat-pk mcp` parses this package's `dist/react.d.ts` (a self-contained bundle of rb-components' types) to give AI coding agents component lists and prop info.
+
+## `./sdk`
+
+Used by:
+
+```text
+plugin
+```
+
+Provides `useRb()`.
+
+`useRb()` gives access to:
+
+* Zenoh-WebSocket-based robot publish
+* subscribe
+* action calls
+* serve
+* toast
+* alert
+* confirm
+* prompt
+
+Instead of implementing dialog/toast UI itself, a plugin delegates these requests to the host's real dialog and toast implementation.
+
+See `./host-ui` for the actual host UI service implementation.
+
+`useRbFormData()` / `useRbSave()` are also provided by `./sdk`. The host passes previously-saved `data` to the plugin, and the plugin registers a payload getter via `onSave` — form save/restore is owned by the host, not the plugin.
+
+## `./ws`
+
+Used by:
+
+```text
+plugin dev bootstrap only
+```
+
+Provides `RbWs`.
+
+`RbWs` is the WebSocket client `useRb()` uses internally.
+
+This entry point isn't used by a plugin's normal production code — it's only used by the dev-environment bootstrap module.
+
+## `./manifest`
+
+Used by:
+
+```text
+nexus
+muscat-pk
+```
+
+Provides the plugin manifest schema.
+
+Acts as the single source of truth for the manifest definition.
+
+`contributes[].point` (`CONTRIBUTION_POINTS`) has 4 possible values:
+
+| point | Description |
+|---|---|
+| `toolbar` | A live UI panel exposed in the top toolbar |
+| `lnb` | A live UI panel exposed in the left navigation bar (LNB) |
+| `move.panel` | A live UI panel exposed in the Move panel |
+| `program.panel` | A custom command the plugin defines for the Program page's rule-based sequence builder |
+
+`toolbar`/`lnb`/`move.panel` back ends use `RBManipulateSDK`/`RBAmrSDK` or `rb.action()` directly. `program.panel` declares `commandInfo` (`funcName: "rb_program_sdk.plugin_execute"`) and its backend runs through `PluginProgramContext` (`on_execute`, `check_stop`, `get_variable`, `set_variable`, `done`).
+
+## `./plugin-data`
+
+Used by:
+
+```text
+nexus only
+```
+
+Provides:
+
+```text
+PluginDataProvider
+usePluginData()
+```
+
+Decides where and how a plugin is loaded from.
+
+## `./host`
+
+Used by:
+
+```text
+nexus only
+```
+
+Provides `PluginHost`.
+
+`PluginHost` handles both mounting paths described above:
+
+* The dev environment's dynamic Vite bootstrap import
+* The build/robot environment's ESM module mount
+
+## `./vite-host`
+
+Used by:
+
+```text
+nexus vite.config.ts
+```
+
+Provides Vite plugins.
+
+Main responsibilities:
+
+* Injecting the import map
+* Supporting the plugin preview dev environment
+
+# Plugin production bundle rules
+
+A plugin's production bundle should only import these entry points:
+
+```text
+./react
+./sdk
+./host-ui
+```
+
+`./host-ui` is used optionally, only when needed.
+
+The following entry points, on the other hand, are host-only:
+
+```text
+./host
+./vite-host
+```
+
+These modules include host-only dependencies:
+
+```text
+@repo/rb-components
+vite
+```
+
+So `./host` and `./vite-host` are never included in a plugin bundle.

package/build-dist.mjs

@@ -1,80 +1,80 @@
-import { build } from "esbuild";
-import { rollup } from "rollup";
-import dts from "rollup-plugin-dts";
-import { nodeResolve } from "@rollup/plugin-node-resolve";
-import { spawnSync } from "node:child_process";
-import { rmSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const here = dirname(fileURLToPath(import.meta.url));
-
-rmSync(resolve(here, "dist"), { recursive: true, force: true });
-
-// JS: transpile only (no bundling — consumers resolve deps themselves)
-await build({
-  entryPoints: {
-    react: resolve(here, "src/react.tsx"),
-    sdk: resolve(here, "src/sdk.ts"),
-    manifest: resolve(here, "src/manifest.ts"),
-    viteHost: resolve(here, "src/viteHost.ts"),
-    "host-ui": resolve(here, "src/host-ui.ts"),
-    // ws is used by the dev bootstrap + host.tsx to build the rb sdk.
-    ws: resolve(here, "src/ws.ts"),
-  },
-  outdir: resolve(here, "dist"),
-  format: "esm",
-  bundle: false, // each file transpiled independently, deps stay as imports
-  platform: "neutral",
-  target: "es2022",
-  sourcemap: true,
-  logLevel: "warning",
-});
-
-const tsc = spawnSync(
-  "node",
-  [
-    "../../node_modules/typescript/bin/tsc",
-    "-p",
-    "tsconfig.build.json",
-    "--emitDeclarationOnly",
-    "--noEmit",
-    "false",
-  ],
-  { cwd: here, stdio: "inherit" },
-);
-if (tsc.status !== 0) {
-  console.warn(
-    "[plugin-ui] tsc reported errors during declaration emit (likely the known rb-providers/rb-utils " +
-      "global.d.ts gap, unrelated to plugin-ui) — .d.ts files were still written; continuing.",
-  );
-}
-
-const reactExternal = (id) =>
-  /^react($|\/)/.test(id) || /^react-dom($|\/)/.test(id);
-
-const ASSET_RE =
-  /\.(css|scss|sass|less|svg|png|jpe?g|gif|webp|woff2?)(\?\w+)?$|^swiper\/css/;
-const stubAssets = {
-  name: "stub-assets-for-dts",
-  resolveId: (id) => (ASSET_RE.test(id) ? "\0asset-stub" : null),
-  load: (id) => (id === "\0asset-stub" ? "export default undefined;" : null),
-};
-const dtsBundle = await rollup({
-  input: resolve(here, "src/react.tsx"),
-  external: reactExternal,
-  plugins: [
-    stubAssets,
-    nodeResolve({ extensions: [".d.ts", ".ts", ".tsx", ".js", ".jsx"] }),
-    dts({ respectExternal: false }),
-  ],
-  onwarn: () => {},
-});
-await dtsBundle.write({
-  file: resolve(here, "dist/react.d.ts"),
-  format: "es",
-});
-await dtsBundle.close();
-rmSync(resolve(here, "dist/react.d.ts.map"), { force: true });
-
-console.log("[plugin-ui] dist/ ready");
+import { build } from "esbuild";
+import { rollup } from "rollup";
+import dts from "rollup-plugin-dts";
+import { nodeResolve } from "@rollup/plugin-node-resolve";
+import { spawnSync } from "node:child_process";
+import { rmSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+rmSync(resolve(here, "dist"), { recursive: true, force: true });
+
+// JS: transpile only (no bundling — consumers resolve deps themselves)
+await build({
+  entryPoints: {
+    react: resolve(here, "src/react.tsx"),
+    sdk: resolve(here, "src/sdk.ts"),
+    manifest: resolve(here, "src/manifest.ts"),
+    viteHost: resolve(here, "src/viteHost.ts"),
+    "host-ui": resolve(here, "src/host-ui.ts"),
+    // ws is used by the dev bootstrap + host.tsx to build the rb sdk.
+    ws: resolve(here, "src/ws.ts"),
+  },
+  outdir: resolve(here, "dist"),
+  format: "esm",
+  bundle: false, // each file transpiled independently, deps stay as imports
+  platform: "neutral",
+  target: "es2022",
+  sourcemap: true,
+  logLevel: "warning",
+});
+
+const tsc = spawnSync(
+  "node",
+  [
+    "../../node_modules/typescript/bin/tsc",
+    "-p",
+    "tsconfig.build.json",
+    "--emitDeclarationOnly",
+    "--noEmit",
+    "false",
+  ],
+  { cwd: here, stdio: "inherit" },
+);
+if (tsc.status !== 0) {
+  console.warn(
+    "[plugin-ui] tsc reported errors during declaration emit (likely the known rb-providers/rb-utils " +
+      "global.d.ts gap, unrelated to plugin-ui) — .d.ts files were still written; continuing.",
+  );
+}
+
+const reactExternal = (id) =>
+  /^react($|\/)/.test(id) || /^react-dom($|\/)/.test(id);
+
+const ASSET_RE =
+  /\.(css|scss|sass|less|svg|png|jpe?g|gif|webp|woff2?)(\?\w+)?$|^swiper\/css/;
+const stubAssets = {
+  name: "stub-assets-for-dts",
+  resolveId: (id) => (ASSET_RE.test(id) ? "\0asset-stub" : null),
+  load: (id) => (id === "\0asset-stub" ? "export default undefined;" : null),
+};
+const dtsBundle = await rollup({
+  input: resolve(here, "src/react.tsx"),
+  external: reactExternal,
+  plugins: [
+    stubAssets,
+    nodeResolve({ extensions: [".d.ts", ".ts", ".tsx", ".js", ".jsx"] }),
+    dts({ respectExternal: false }),
+  ],
+  onwarn: () => {},
+});
+await dtsBundle.write({
+  file: resolve(here, "dist/react.d.ts"),
+  format: "es",
+});
+await dtsBundle.close();
+rmSync(resolve(here, "dist/react.d.ts.map"), { force: true });
+
+console.log("[plugin-ui] dist/ ready");