@rainbow-robotics/plugin-ui 0.1.2-dev.5 → 0.1.2-dev.50

package/README.md

@@ -1,85 +1,246 @@
 # @rainbow-robotics/plugin-ui
 
-Muscat plugin UI **contract** + sandbox/host bindings.
+# Muscat plugin UI contract and host mounting architecture
 
-External plugin source imports this package as `@rainbow-robotics/plugin-ui/*`, but
-`muscat-pk build` keeps it **external**. A plugin ZIP must not contain this
-runtime. Muscat/robot and preview-host provide their own matching
-`@rainbow-robotics/plugin-ui` browser runtime and render the real rb-components on the
-host side.
+A Muscat plugin is a plain React component exported as `export default App`.
 
-## Architecture
+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()
 ```
-sandbox (untrusted plugin)              host (nexus / Muscat)
-─────────────────────────              ─────────────────────
-import { Slider, Button, useRb }        import { PluginContent } from
-  from "@rainbow-robotics/plugin-ui/react"         "@rainbow-robotics/plugin-ui/host"
-
-<Slider/> → <rb-slider> ──mutations──▶  RemoteReceiver → RB_COMPONENT_MAP
-                                          → real RBSlider (rb-components)
-rb.action(id, payload) ──thread call──▶ host RbSdk.action → POST /plugin/:id/action
-host event (onChange…) ──thread call──▶ author onChange (RemoteEvent.detail)
+
+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
 ```
 
-- **Isolation**: the plugin runs in an `allow-scripts` iframe (opaque origin).
-- **Transport**: `@quilted/threads` (`ThreadWindow`). The **sandbox initiates**
-  the handshake by calling the host's exported `connect()` — threads does not
-  buffer a call made before the other side is listening, and the host has been
-  listening since it mounted the iframe.
-- **Rendering**: `@remote-dom/core` + `@remote-dom/react`. The sandbox streams
-  DOM mutations via `RemoteMutationObserver`; the host mirrors them with
-  `RemoteReceiver` + `RemoteRootRenderer`.
-
-## Entry points
-
-| Export | Used by | Notes |
-|---|---|---|
-| `./react` | plugin (sandbox) | author bindings: `Slider`, `Button`, `IconButton`, `Text`, `TextInput`, `Switch`, `Select`, `useRb` |
-| `./connect` | plugin (sandbox) | `connect(App)` bootstrap, called from `sandbox.html` |
-| `./sdk` | plugin (sandbox) | `useRb()`, `RbSdk` types |
-| `./elements` | both | rb-\* element contract |
-| `./host` | nexus only | `PluginContent`, `RB_COMPONENT_MAP` (maps rb-\* → real rb-components) |
-| `./manifest` | nexus + rby2 | manifest schema (single source of truth) |
-
-The plugin's production bundle must only import `./react` (+ `./connect`,
-`./sdk`); `./host` pulls in rb-components and is host-only.
-
-## rb-\* contract → rb-components mapping
-
-| element | host component | event prop |
-|---|---|---|
-| `rb-slider` | `RBSlider` | `onChange` (number) |
-| `rb-button` | `RBLabelButton` | `onPress` |
-| `rb-icon-button` | `RBIconButton` (icon from `RBIcons`) | `onPress` |
-| `rb-text` | plain text | — |
-| `rb-text-input` | `RBTextInput` | `onInput` (string) |
-| `rb-switch` | `RBSwitch` | `onChange` (boolean) |
-| `rb-select` | `RBSelectBox` | `onChange` (string) |
-
-> ⚠️ Author bindings and the host **must** declare matching `eventProps`.
-> `createRemoteComponent` / `createRemoteComponentRenderer` only treat a prop as
-> an event listener when it is in `eventProps`; they do **not** auto-derive from
-> the element's `remoteEvents`.
-
-## Verified versions
-
-`@remote-dom/core@^1.11` · `@remote-dom/react@^1.2` · `@quilted/threads@^4`.
-Notable corrections vs. early design notes: `RemoteMutationObserver` is from
-`@remote-dom/core/elements` (not `/core`); there is no `@remote-dom/core/messaging`
-— threading lives in `@quilted/threads`.
-
-## Demo (M1 end-to-end check)
-
-`demo/` is a standalone vite harness (excluded from build/lint/types). It serves
-a host page + sandbox page and verifies the full round-trip in a real browser:
-
-```bash
-# from repo root
-node_modules/.bin/vite --config packages/rb-plugin-kit/demo/vite.config.ts
-# then, with the server on :5199:
-node packages/rb-plugin-kit/demo/e2e.mjs
+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
 ```
 
-The demo renders unstyled (no Tailwind/postcss pipeline); styling is validated
-in nexus.
+So `./host` and `./vite-host` are never included in a plugin bundle.

package/build-dist.mjs

@@ -1,12 +1,8 @@
-// Builds @rainbow-robotics/plugin-ui for npm consumers (plugin authors).
-// Output: dist/*.js (ESM, deps external) + dist/*.d.ts (via tsc)
-//
-// host.tsx is intentionally excluded — it depends on @repo/rb-components
-// which is a Muscat-internal package. External devs never import ./host.
-//
-// Run: node libraries/plugin-ui/build-dist.mjs
 import { build } from "esbuild";
-import { execSync } from "node:child_process";
+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";
@@ -18,25 +14,67 @@ rmSync(resolve(here, "dist"), { recursive: true, force: true });
 // JS: transpile only (no bundling — consumers resolve deps themselves)
 await build({
   entryPoints: {
-    connect:  resolve(here, "src/connect.ts"),
-    react:    resolve(here, "src/react.tsx"),
-    sdk:      resolve(here, "src/sdk.ts"),
-    elements: resolve(here, "src/elements.ts"),
+    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
+  bundle: false, // each file transpiled independently, deps stay as imports
   platform: "neutral",
   target: "es2022",
   sourcemap: true,
   logLevel: "warning",
 });
 
-// Types: tsc --emitDeclarationOnly
-execSync("node ../../node_modules/typescript/bin/tsc -p tsconfig.build.json --emitDeclarationOnly --noEmit false", {
-  cwd: here,
-  stdio: "inherit",
+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");

package/dist/host-ui.d.ts

@@ -0,0 +1,49 @@
+import { ReactElement } from "react";
+export interface PluginUIServices {
+    alert: (params: {
+        title?: string;
+        message: string;
+        buttonText?: string;
+    }) => Promise<void>;
+    confirm: (params: {
+        title?: string;
+        message: string;
+        buttonText?: {
+            yes: string;
+            no: string;
+        };
+    }) => Promise<boolean>;
+    prompt: (params: {
+        title?: string;
+        message: string;
+        value?: string;
+        placeholder?: string;
+        buttonText?: {
+            yes: string;
+            no: string;
+        };
+    }) => Promise<string | undefined>;
+    toast: (params: {
+        title?: string;
+        message: string | ReactElement;
+        type?: "info" | "danger" | "warning" | "caution" | "success";
+        actionLabel?: string;
+        handleActionClick?: () => void;
+        closeOnActionClick?: boolean;
+        duration?: number;
+        onClose?: () => void;
+    }) => void;
+}
+/** Called by the host when it mounts a plugin. */
+export declare function setHostServices(next: PluginUIServices): void;
+/** Read the injected services, throwing a clear error if the host forgot. */
+export declare function getHostServices(): PluginUIServices;
+/** Open a host alert dialog from a plugin. */
+export declare function alert(params: Parameters<PluginUIServices["alert"]>[0]): Promise<void>;
+/** Open a host confirm dialog from a plugin. Resolves true/false. */
+export declare function confirm(params: Parameters<PluginUIServices["confirm"]>[0]): Promise<boolean>;
+/** Open a host prompt dialog from a plugin. Resolves the entered value, or undefined if cancelled. */
+export declare function prompt(params: Parameters<PluginUIServices["prompt"]>[0]): Promise<string | undefined>;
+/** Show a host toast from a plugin. */
+export declare function toast(params: Parameters<PluginUIServices["toast"]>[0]): void;
+//# sourceMappingURL=host-ui.d.ts.map

package/dist/host-ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-ui.d.ts","sourceRoot":"","sources":["../src/host-ui.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAErC,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,CAAC,MAAM,EAAE;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpB,OAAO,EAAE,CAAC,MAAM,EAAE;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE;YACX,GAAG,EAAE,MAAM,CAAC;YACZ,EAAE,EAAE,MAAM,CAAC;SACZ,CAAC;KACH,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACvB,MAAM,EAAE,CAAC,MAAM,EAAE;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,CAAC,EAAE;YACX,GAAG,EAAE,MAAM,CAAC;YACZ,EAAE,EAAE,MAAM,CAAC;SACZ,CAAC;KACH,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAClC,KAAK,EAAE,CAAC,MAAM,EAAE;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,GAAG,YAAY,CAAC;QAC/B,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;QAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,iBAAiB,CAAC,EAAE,MAAM,IAAI,CAAC;QAC/B,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;KACtB,KAAK,IAAI,CAAC;CACZ;AAID,kDAAkD;AAClD,wBAAgB,eAAe,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAE5D;AAED,6EAA6E;AAC7E,wBAAgB,eAAe,IAAI,gBAAgB,CAOlD;AAED,8CAA8C;AAC9C,wBAAgB,KAAK,CACnB,MAAM,EAAE,UAAU,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,GAC/C,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,qEAAqE;AACrE,wBAAgB,OAAO,CACrB,MAAM,EAAE,UAAU,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,GACjD,OAAO,CAAC,OAAO,CAAC,CAElB;AAED,sGAAsG;AACtG,wBAAgB,MAAM,CACpB,MAAM,EAAE,UAAU,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,GAChD,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAE7B;AAED,uCAAuC;AACvC,wBAAgB,KAAK,CAAC,MAAM,EAAE,UAAU,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAE5E"}

package/dist/host-ui.js

@@ -0,0 +1,33 @@
+let services = null;
+function setHostServices(next) {
+  services = next;
+}
+function getHostServices() {
+  if (!services) {
+    throw new Error(
+      "[plugin-ui] services not set \u2014 the plugin must be mounted by a Muscat host."
+    );
+  }
+  return services;
+}
+function alert(params) {
+  return getHostServices().alert(params);
+}
+function confirm(params) {
+  return getHostServices().confirm(params);
+}
+function prompt(params) {
+  return getHostServices().prompt(params);
+}
+function toast(params) {
+  getHostServices().toast(params);
+}
+export {
+  alert,
+  confirm,
+  getHostServices,
+  prompt,
+  setHostServices,
+  toast
+};
+//# sourceMappingURL=host-ui.js.map

package/dist/host-ui.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/host-ui.ts"],
+  "sourcesContent": ["import { ReactElement } from \"react\";\n\nexport interface PluginUIServices {\n  alert: (params: {\n    title?: string;\n    message: string;\n    buttonText?: string;\n  }) => Promise<void>;\n  confirm: (params: {\n    title?: string;\n    message: string;\n    buttonText?: {\n      yes: string;\n      no: string;\n    };\n  }) => Promise<boolean>;\n  prompt: (params: {\n    title?: string;\n    message: string;\n    value?: string;\n    placeholder?: string;\n    buttonText?: {\n      yes: string;\n      no: string;\n    };\n  }) => Promise<string | undefined>;\n  toast: (params: {\n    title?: string;\n    message: string | ReactElement;\n    type?: \"info\" | \"danger\" | \"warning\" | \"caution\" | \"success\";\n    actionLabel?: string;\n    handleActionClick?: () => void;\n    closeOnActionClick?: boolean;\n    duration?: number;\n    onClose?: () => void;\n  }) => void;\n}\n\nlet services: PluginUIServices | null = null;\n\n/** Called by the host when it mounts a plugin. */\nexport function setHostServices(next: PluginUIServices): void {\n  services = next;\n}\n\n/** Read the injected services, throwing a clear error if the host forgot. */\nexport function getHostServices(): PluginUIServices {\n  if (!services) {\n    throw new Error(\n      \"[plugin-ui] services not set \u2014 the plugin must be mounted by a Muscat host.\",\n    );\n  }\n  return services;\n}\n\n/** Open a host alert dialog from a plugin. */\nexport function alert(\n  params: Parameters<PluginUIServices[\"alert\"]>[0],\n): Promise<void> {\n  return getHostServices().alert(params);\n}\n\n/** Open a host confirm dialog from a plugin. Resolves true/false. */\nexport function confirm(\n  params: Parameters<PluginUIServices[\"confirm\"]>[0],\n): Promise<boolean> {\n  return getHostServices().confirm(params);\n}\n\n/** Open a host prompt dialog from a plugin. Resolves the entered value, or undefined if cancelled. */\nexport function prompt(\n  params: Parameters<PluginUIServices[\"prompt\"]>[0],\n): Promise<string | undefined> {\n  return getHostServices().prompt(params);\n}\n\n/** Show a host toast from a plugin. */\nexport function toast(params: Parameters<PluginUIServices[\"toast\"]>[0]): void {\n  getHostServices().toast(params);\n}\n"],
+  "mappings": "AAsCA,IAAI,WAAoC;AAGjC,SAAS,gBAAgB,MAA8B;AAC5D,aAAW;AACb;AAGO,SAAS,kBAAoC;AAClD,MAAI,CAAC,UAAU;AACb,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACA,SAAO;AACT;AAGO,SAAS,MACd,QACe;AACf,SAAO,gBAAgB,EAAE,MAAM,MAAM;AACvC;AAGO,SAAS,QACd,QACkB;AAClB,SAAO,gBAAgB,EAAE,QAAQ,MAAM;AACzC;AAGO,SAAS,OACd,QAC6B;AAC7B,SAAO,gBAAgB,EAAE,OAAO,MAAM;AACxC;AAGO,SAAS,MAAM,QAAwD;AAC5E,kBAAgB,EAAE,MAAM,MAAM;AAChC;",
+  "names": []
+}

package/dist/manifest.d.ts

@@ -5,19 +5,31 @@
  * Evolve additively only.
  */
 /** Known contribution points the host understands. */
-export declare const CONTRIBUTION_POINTS: readonly ["header.toolbar", "lnb", "move.panel", "program.panel"];
+export declare const CONTRIBUTION_POINTS: readonly ["toolbar", "lnb", "move.panel", "program.panel"];
 export type ContributionPoint = (typeof CONTRIBUTION_POINTS)[number];
 /** How a header.toolbar contribution opens when clicked. */
 export type ContributionOpens = "popover" | "panel" | "page";
 export interface PluginContribution {
     /** Where this contribution mounts. */
     point: ContributionPoint | (string & {});
+    /** UI entry name relative to ui/ (without extension). Defaults to "content". */
+    ui?: string;
     /** Icon path relative to the plugin root (e.g. "assets/icon.svg"). */
-    icon?: string;
+    icon?: string | {
+        "16"?: string;
+        "48"?: string;
+        "126"?: string;
+    };
     /** Display label. */
-    label?: string;
+    label?: string | Record<string, string>;
     /** For header.toolbar: how the contribution surfaces. */
     opens?: ContributionOpens;
+    commandInfo?: {
+        name: string;
+        icon: string;
+        funcName: string;
+        args?: Record<string, any>;
+    };
 }
 export interface PluginAction {
     /** Action id referenced by `rb.action(id, payload)`. */
@@ -48,7 +60,11 @@ export interface PluginManifest {
     /** Minimum host (Muscat) version this plugin supports. */
     minAppVersion?: string;
     /** Icon path relative to plugin root. */
-    icon?: string;
+    icons: string | {
+        "16"?: string;
+        "48"?: string;
+        "128"?: string;
+    };
     /** UI / chrome contributions. */
     contributes?: PluginContribution[];
     /** Host actions the plugin can invoke. */

package/dist/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,mEAKtB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAErE,4DAA4D;AAC5D,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;AAE7D,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,KAAK,EAAE,iBAAiB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACzC,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qBAAqB;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,KAAK,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IACE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,GAAG,QAAQ,CAAC;CAC/B,CAAC;AAEN,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC;IACX,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,WAAW,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACnC,0CAA0C;IAC1C,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,oCAAoC;IACpC,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAiBzD"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAEH,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,4DAKtB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAErE,4DAA4D;AAC5D,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;AAE7D,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,KAAK,EAAE,iBAAiB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACzC,gFAAgF;IAChF,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,IAAI,CAAC,EACD,MAAM,GACN;QACE,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACN,qBAAqB;IACrB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,yDAAyD;IACzD,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,WAAW,CAAC,EAAE;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAC5B,CAAC;CACH;AAED,MAAM,WAAW,YAAY;IAC3B,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IACE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,GAAG,QAAQ,CAAC;CAC/B,CAAC;AAEN,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC;IACX,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,KAAK,EACD,MAAM,GACN;QACE,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACN,iCAAiC;IACjC,WAAW,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACnC,0CAA0C;IAC1C,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,oCAAoC;IACpC,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAiBzD"}

package/dist/manifest.js

@@ -1,5 +1,5 @@
 const CONTRIBUTION_POINTS = [
-  "header.toolbar",
+  "toolbar",
   "lnb",
   "move.panel",
   "program.panel"

package/dist/manifest.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/manifest.ts"],
-  "sourcesContent": ["/**\n * Plugin manifest schema \u2014 the single source of truth shared by the front end\n * (nexus reads it) and the back end (rby2 mirrors it for validation).\n *\n * Evolve additively only.\n */\n\n/** Known contribution points the host understands. */\nexport const CONTRIBUTION_POINTS = [\n  \"header.toolbar\",\n  \"lnb\",\n  \"move.panel\",\n  \"program.panel\",\n] as const;\n\nexport type ContributionPoint = (typeof CONTRIBUTION_POINTS)[number];\n\n/** How a header.toolbar contribution opens when clicked. */\nexport type ContributionOpens = \"popover\" | \"panel\" | \"page\";\n\nexport interface PluginContribution {\n  /** Where this contribution mounts. */\n  point: ContributionPoint | (string & {});\n  /** Icon path relative to the plugin root (e.g. \"assets/icon.svg\"). */\n  icon?: string;\n  /** Display label. */\n  label?: string;\n  /** For header.toolbar: how the contribution surfaces. */\n  opens?: ContributionOpens;\n}\n\nexport interface PluginAction {\n  /** Action id referenced by `rb.action(id, payload)`. */\n  id: string;\n  /** Transport topic (Zenoh / ROS2) the back end routes to. */\n  topic: string;\n  /** Optional payload schema hint (field \u2192 type name). */\n  schema?: Record<string, string>;\n}\n\nexport type PluginRuntime =\n  | { type: \"none\" }\n  | { type: \"python\"; entry: string }\n  | {\n      type: \"ros2\";\n      package: string;\n      launch: string;\n      rosClient: \"rclpy\" | \"rclcpp\";\n    };\n\nexport interface PluginManifest {\n  /** Reverse-DNS unique id, e.g. \"com.rainbow.gripper-tool\". */\n  id: string;\n  /** Human-readable name. */\n  name: string;\n  /** Plugin version (semver). */\n  version: string;\n  /** Minimum host (Muscat) version this plugin supports. */\n  minAppVersion?: string;\n  /** Icon path relative to plugin root. */\n  icon?: string;\n  /** UI / chrome contributions. */\n  contributes?: PluginContribution[];\n  /** Host actions the plugin can invoke. */\n  actions?: PluginAction[];\n  /** Back-end runtime declaration. */\n  runtime?: PluginRuntime;\n}\n\n/**\n * Lightweight structural check. Returns the list of problems (empty = valid).\n * Kept dependency-free so both front and back ends can reuse it; richer\n * validation (zod) can layer on top later without breaking this contract.\n */\nexport function validateManifest(value: unknown): string[] {\n  const errors: string[] = [];\n  if (typeof value !== \"object\" || value === null) {\n    return [\"manifest must be an object\"];\n  }\n  const m = value as Record<string, unknown>;\n  if (typeof m.id !== \"string\" || m.id.length === 0)\n    errors.push(\"manifest.id is required (string)\");\n  if (typeof m.name !== \"string\" || m.name.length === 0)\n    errors.push(\"manifest.name is required (string)\");\n  if (typeof m.version !== \"string\" || m.version.length === 0)\n    errors.push(\"manifest.version is required (string)\");\n  if (m.contributes !== undefined && !Array.isArray(m.contributes))\n    errors.push(\"manifest.contributes must be an array\");\n  if (m.actions !== undefined && !Array.isArray(m.actions))\n    errors.push(\"manifest.actions must be an array\");\n  return errors;\n}\n"],
-  "mappings": "AAQO,MAAM,sBAAsB;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AA6DO,SAAS,iBAAiB,OAA0B;AACzD,QAAM,SAAmB,CAAC;AAC1B,MAAI,OAAO,UAAU,YAAY,UAAU,MAAM;AAC/C,WAAO,CAAC,4BAA4B;AAAA,EACtC;AACA,QAAM,IAAI;AACV,MAAI,OAAO,EAAE,OAAO,YAAY,EAAE,GAAG,WAAW;AAC9C,WAAO,KAAK,kCAAkC;AAChD,MAAI,OAAO,EAAE,SAAS,YAAY,EAAE,KAAK,WAAW;AAClD,WAAO,KAAK,oCAAoC;AAClD,MAAI,OAAO,EAAE,YAAY,YAAY,EAAE,QAAQ,WAAW;AACxD,WAAO,KAAK,uCAAuC;AACrD,MAAI,EAAE,gBAAgB,UAAa,CAAC,MAAM,QAAQ,EAAE,WAAW;AAC7D,WAAO,KAAK,uCAAuC;AACrD,MAAI,EAAE,YAAY,UAAa,CAAC,MAAM,QAAQ,EAAE,OAAO;AACrD,WAAO,KAAK,mCAAmC;AACjD,SAAO;AACT;",
+  "sourcesContent": ["/* eslint-disable @typescript-eslint/no-explicit-any */\n/**\n * Plugin manifest schema \u2014 the single source of truth shared by the front end\n * (nexus reads it) and the back end (rby2 mirrors it for validation).\n *\n * Evolve additively only.\n */\n\n/** Known contribution points the host understands. */\nexport const CONTRIBUTION_POINTS = [\n  \"toolbar\",\n  \"lnb\",\n  \"move.panel\",\n  \"program.panel\",\n] as const;\n\nexport type ContributionPoint = (typeof CONTRIBUTION_POINTS)[number];\n\n/** How a header.toolbar contribution opens when clicked. */\nexport type ContributionOpens = \"popover\" | \"panel\" | \"page\";\n\nexport interface PluginContribution {\n  /** Where this contribution mounts. */\n  point: ContributionPoint | (string & {});\n  /** UI entry name relative to ui/ (without extension). Defaults to \"content\". */\n  ui?: string;\n  /** Icon path relative to the plugin root (e.g. \"assets/icon.svg\"). */\n  icon?:\n    | string\n    | {\n        \"16\"?: string;\n        \"48\"?: string;\n        \"126\"?: string;\n      };\n  /** Display label. */\n  label?: string | Record<string, string>;\n  /** For header.toolbar: how the contribution surfaces. */\n  opens?: ContributionOpens;\n  commandInfo?: {\n    name: string;\n    icon: string;\n    funcName: string;\n    args?: Record<string, any>;\n  };\n}\n\nexport interface PluginAction {\n  /** Action id referenced by `rb.action(id, payload)`. */\n  id: string;\n  /** Transport topic (Zenoh / ROS2) the back end routes to. */\n  topic: string;\n  /** Optional payload schema hint (field \u2192 type name). */\n  schema?: Record<string, string>;\n}\n\nexport type PluginRuntime =\n  | { type: \"none\" }\n  | { type: \"python\"; entry: string }\n  | {\n      type: \"ros2\";\n      package: string;\n      launch: string;\n      rosClient: \"rclpy\" | \"rclcpp\";\n    };\n\nexport interface PluginManifest {\n  /** Reverse-DNS unique id, e.g. \"com.rainbow.gripper-tool\". */\n  id: string;\n  /** Human-readable name. */\n  name: string;\n  /** Plugin version (semver). */\n  version: string;\n  /** Minimum host (Muscat) version this plugin supports. */\n  minAppVersion?: string;\n  /** Icon path relative to plugin root. */\n  icons:\n    | string\n    | {\n        \"16\"?: string;\n        \"48\"?: string;\n        \"128\"?: string;\n      };\n  /** UI / chrome contributions. */\n  contributes?: PluginContribution[];\n  /** Host actions the plugin can invoke. */\n  actions?: PluginAction[];\n  /** Back-end runtime declaration. */\n  runtime?: PluginRuntime;\n}\n\n/**\n * Lightweight structural check. Returns the list of problems (empty = valid).\n * Kept dependency-free so both front and back ends can reuse it; richer\n * validation (zod) can layer on top later without breaking this contract.\n */\nexport function validateManifest(value: unknown): string[] {\n  const errors: string[] = [];\n  if (typeof value !== \"object\" || value === null) {\n    return [\"manifest must be an object\"];\n  }\n  const m = value as Record<string, unknown>;\n  if (typeof m.id !== \"string\" || m.id.length === 0)\n    errors.push(\"manifest.id is required (string)\");\n  if (typeof m.name !== \"string\" || m.name.length === 0)\n    errors.push(\"manifest.name is required (string)\");\n  if (typeof m.version !== \"string\" || m.version.length === 0)\n    errors.push(\"manifest.version is required (string)\");\n  if (m.contributes !== undefined && !Array.isArray(m.contributes))\n    errors.push(\"manifest.contributes must be an array\");\n  if (m.actions !== undefined && !Array.isArray(m.actions))\n    errors.push(\"manifest.actions must be an array\");\n  return errors;\n}\n"],
+  "mappings": "AASO,MAAM,sBAAsB;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAiFO,SAAS,iBAAiB,OAA0B;AACzD,QAAM,SAAmB,CAAC;AAC1B,MAAI,OAAO,UAAU,YAAY,UAAU,MAAM;AAC/C,WAAO,CAAC,4BAA4B;AAAA,EACtC;AACA,QAAM,IAAI;AACV,MAAI,OAAO,EAAE,OAAO,YAAY,EAAE,GAAG,WAAW;AAC9C,WAAO,KAAK,kCAAkC;AAChD,MAAI,OAAO,EAAE,SAAS,YAAY,EAAE,KAAK,WAAW;AAClD,WAAO,KAAK,oCAAoC;AAClD,MAAI,OAAO,EAAE,YAAY,YAAY,EAAE,QAAQ,WAAW;AACxD,WAAO,KAAK,uCAAuC;AACrD,MAAI,EAAE,gBAAgB,UAAa,CAAC,MAAM,QAAQ,EAAE,WAAW;AAC7D,WAAO,KAAK,uCAAuC;AACrD,MAAI,EAAE,YAAY,UAAa,CAAC,MAAM,QAAQ,EAAE,OAAO;AACrD,WAAO,KAAK,mCAAmC;AACjD,SAAO;AACT;",
   "names": []
 }