@rainbow-robotics/plugin-ui 0.1.2-dev.43 → 0.1.2-dev.45

package/README.md

@@ -1,85 +1,232 @@
 # @rainbow-robotics/plugin-ui
 
-Muscat plugin UI **contract** + sandbox/host bindings.
+# Muscat 플러그인 UI 계약 및 호스트 마운팅 구조
 
-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.
+Muscat 플러그인은 `export default App` 형태로 내보내는 일반 React 컴포넌트입니다.
 
-## Architecture
+플러그인 마운팅은 두 가지 경로로 동작하며, 두 경로 모두 `./host` 패키지에서 처리합니다.
 
+## 개발 환경: `muscat-pk dev`
+
+개발 환경에서는 플러그인 자체의 vite.config.ts를 이용하여 Vite 개발 서버가 bootstrap 모듈을 제공합니다.
+
+호스트는 해당 bootstrap 모듈을 동적으로 import하여 플러그인을 실행합니다.
+
+이 방식의 특징은 다음과 같습니다.
+
+* 전체 HMR 지원
+* 플러그인은 독립적인 React Root로 실행
+* 플러그인이 자체 React 인스턴스를 사용
+* 호스트 React 트리와 플러그인 React 트리가 분리됨
+
+즉, 개발 환경에서는 플러그인이 호스트 페이지 내부에서 실행되지만 React 런타임 자체는 호스트와 공유하지 않습니다.
+
+## 빌드 및 로봇 환경: `muscat-pk build`
+
+`muscat-pk build`는 자체 번들러가 아니라, **플러그인 프로젝트 자신의 `vite.config.ts`로 `vite build`를 실행**하는 얇은 래퍼입니다
+(`--config` 지정 없이 `cwd`만 플러그인 루트로 잡고 `vite build`를 실행 — Vite가 그 디렉토리의 `vite.config.ts`를 알아서 읽습니다).
+
+스캐폴딩되는 `vite.config.ts`는 이렇게 생겼습니다.
+
+```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()] });
+```
+
+**external 목록과 rollup 설정은 이 패키지(`@rainbow-robotics/plugin-ui`)가 아니라 `@rainbow-robotics/muscat-plugin-kit`의 `muscat()` preset(`cli/vite.mjs`)에 정의돼 있습니다.** 역할이 이렇게 나뉩니다.
+
+| 패키지 | 담당 |
+|---|---|
+| `@rainbow-robotics/muscat-plugin-kit` | 빌드 타임 — `muscat()` preset (external 목록, entry 탐색, rollup 설정) |
+| `@rainbow-robotics/plugin-ui` (이 패키지) | 런타임 — `./host`(마운트), `./vite-host`(nexus 쪽 import map 주입) |
+
+`muscat()` preset이 다음 의존성을 플러그인 번들에 포함하지 않고 external bare specifier로 남겨둡니다.
+
+```text
+react
+react-dom
+@rainbow-robotics/plugin-ui/*
+@repo/rb-components
+```
+
+호스트 페이지에는 `./vite-host`에서 설정한 import map이 포함되어 있습니다.
+
+이 import map은 위 bare specifier들을 호스트가 이미 로드한 실제 모듈 인스턴스로 연결합니다.
+
+따라서 프로덕션 환경에서 로드된 플러그인은 다음과 같이 동작합니다.
+
+* 호스트와 동일한 React 인스턴스 사용
+* 호스트 React 트리 내부에 실제 중첩 React 트리로 마운트
+* `RbContext` 공유
+* 호스트 UI 컨텍스트 공유
+* 플러그인 번들 크기 최소화
+
+개발 환경에서는 플러그인이 독립적인 React Root로 실행되지만, 빌드 및 로봇 환경에서는 호스트 React 트리 내부에 중첩되어 실행됩니다.
+
+### UI가 없는 플러그인은 vite build 자체를 건너뜀
+
+`muscat-pk build`는 `manifest.json`의 `contributes[].ui`를 모아서 실제로 `ui/{name}.tsx`(또는 `.ts`/`.jsx`/`.js`) 파일이 있는지 검증합니다.
+
+* `contributes`에 `ui`가 하나라도 선언돼 있는데 해당 파일이 없으면 → 빌드 실패(명확한 에러)
+* `contributes`에 선언된 `ui`가 없고 `ui/` 디렉토리에 파일도 없으면(백엔드 전용 플러그인) → **vite build를 아예 건너뜁니다.** `dist/`엔 manifest.json/assets/백엔드 파일만 들어갑니다.
+
+로직은 `libraries/muscat-plugin-kit/cli/src/build.mjs`의 `buildPlugin()`에 있습니다.
+
+### Node.js가 없을 때
+
+`muscat-pk build`는 자체 번들러가 아니라 `vite build`를 **자식 프로세스로 스폰**하므로, 그 자식 프로세스를 실행할 JS 런타임이 있어야 합니다.
+
+* **npm으로 설치한 `muscat-pk`** → 이미 Node로 실행 중이므로 이 문제 자체가 발생하지 않습니다.
+* **S3 self-contained 바이너리(Bun으로 컴파일됨)로 설치한 `muscat-pk`** → PATH에서 `bun` → `node` → `nodejs` 순서로 찾습니다. 셋 다 없으면:
+
+  ```
+  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)
+  ```
+
+  를 출력하고 `exitCode 1`로 조용히 종료합니다(스택트레이스 없음). 로직은 `build.mjs`의 `findJsRuntime()` / `runViteBuild()`에 있습니다.
+
+# 엔트리 포인트
+
+## `./react`
+
+사용 대상:
+
+```text
+plugin
+```
+
+실제 `@repo/rb-components`에서 `new-components` 전부 플러그인에 export합니다.
+
+
+플러그인은 `@repo/rb-components`를 직접 import하기보다 이 엔트리 포인트를 통해 UI 컴포넌트를 사용합니다.
+
+## `./sdk`
+
+사용 대상:
+
+```text
+plugin
+```
+
+`useRb()`를 제공합니다.
+
+`useRb()`를 통해 다음 기능을 사용할 수 있습니다.
+
+* Zenoh WebSocket 기반 로봇 publish
+* subscribe
+* action 호출
+* serve
+* toast
+* alert
+* confirm
+* prompt
+
+이 API들은 플러그인 내부에서 직접 UI를 구현하는 대신, 호스트가 실제로 사용하는 dialog, toast 기능에 요청을 위임합니다.
+
+실제 호스트 UI 서비스 구현은 `./host-ui`를 참고합니다.
+
+## `./ws`
+
+사용 대상:
+
+```text
+plugin dev bootstrap only
+```
+
+`RbWs`를 제공합니다.
+
+`RbWs`는 `useRb()`가 내부적으로 사용하는 WebSocket 클라이언트입니다.
+
+이 엔트리 포인트는 플러그인의 일반 프로덕션 코드에서 사용하는 것이 아니라, 개발 환경의 bootstrap 모듈에서만 사용합니다.
+
+## `./manifest`
+
+사용 대상:
+
+```text
+nexus
+muscat-pk
+```
+
+플러그인 manifest 스키마를 제공합니다.
+
+manifest 정의의 단일 진실 공급원, 즉 Single Source of Truth 역할을 합니다.
+
+## `./plugin-data`
+
+사용 대상:
+
+```text
+nexus only
+```
+
+다음 API를 제공합니다.
+
+```text
+PluginDataProvider
+usePluginData()
+```
+
+플러그인을 어디에서, 어떤 방식으로 불러올지 결정합니다.
+
+## `./host`
+
+사용 대상:
+
+```text
+nexus only
+```
+
+`PluginHost`를 제공합니다.
+
+`PluginHost`는 앞에서 설명한 두 가지 마운트 경로를 모두 처리합니다.
+
+* 개발 환경의 Vite bootstrap 동적 import 방식
+* 빌드 및 로봇 환경의 ESM 모듈 마운트 방식
+
+## `./vite-host`
+
+사용 대상:
+
+```text
+nexus vite.config.ts
 ```
-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)
+
+Vite 플러그인을 제공합니다.
+
+주요 역할은 다음과 같습니다.
+
+* import map 삽입
+* 플러그인 preview 개발 환경 지원
+
+# 플러그인 프로덕션 번들 규칙
+
+플러그인의 프로덕션 번들은 다음 엔트리 포인트만 import합니다.
+
+```text
+./react
+./sdk
+./host-ui
 ```
 
-- **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
+`./host-ui`는 필요한 경우에만 선택적으로 사용합니다.
+
+반면 다음 엔트리 포인트는 호스트 전용입니다.
+
+```text
+./host
+./vite-host
+```
+
+이 모듈들은 다음과 같은 호스트 전용 의존성을 포함합니다.
+
+```text
+@repo/rb-components
+vite
 ```
 
-The demo renders unstyled (no Tailwind/postcss pipeline); styling is validated
-in nexus.
+따라서 `./host`와 `./vite-host`는 플러그인 번들에 포함되지 않습니다.

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": []
 }