@rainbow-robotics/plugin-ui 0.1.2-dev.8 → 1.0.0

package/src/host.tsx

@@ -1,356 +1,277 @@
 /**
- * Host bindings — used by nexus (Muscat) only.
+ * Host mounting (nexus only). A plugin renders directly in the host document —
+ * no iframe. Two strategies, per `PluginModuleSource.kind` (see ./pluginData):
  *
- * Maps the rb-* remote element contract onto the *real* @repo/rb-components,
- * and renders a sandboxed plugin's remote tree with those real components.
- * The plugin never ships rb-components; it only emits rb-* name tags, which the
- * host resolves here. This keeps plugin bundles small and lets rb-components
- * evolve freely behind the stable contract.
+ * - "esm" (built plugin / robot runtime): dynamic `import()` of the plugin's
+ *   built entry. react / react-dom / rb-components / plugin-ui are external bare
+ *   specifiers, resolved by the host page's import map to the host's own loaded
+ *   instances (see ./viteHost.ts). So the plugin shares the host's React,
+ *   rb-components, and RbContext, with no duplicate React instance.
  *
- * Verified wiring (@remote-dom/react@1.2.x host + @quilted/threads@4.x):
- *   - `RemoteReceiver` / `RemoteRootRenderer` / `createRemoteComponentRenderer`
- *     from `@remote-dom/react/host`
- *   - host calls `thread.imports.render(receiver.connection, api)`; the sandbox
- *     (see ./connect) consumes that connection with a RemoteMutationObserver.
+ * - "dev" (`muscat-pk dev`): the plugin's Vite dev server serves a bootstrap
+ *   module exposing `mount(container, opts)`, mounted as an independent React
+ *   root using the plugin's own deps. HostServices passed in are plain
+ *   functions (see ./host-ui), so they cross the React-instance boundary safely.
  */
 import {
-  forwardRef,
+  useCallback,
   useEffect,
   useMemo,
   useRef,
+  useState,
   type ComponentType,
-  type ReactNode,
 } from "react";
-import {
-  RemoteReceiver,
-  RemoteRootRenderer,
-  createRemoteComponentRenderer,
-  type RemoteComponentRendererMap,
-} from "@remote-dom/react/host";
-import { ThreadWindow } from "@quilted/threads";
-import {
-  RBSlider,
-  RBLabelButton,
-  RBIconButton,
-  RBSwitch,
-  RBSelectBox,
-  RBSelectOption,
-  RBTextInput,
-  RBIcons,
-} from "@repo/rb-components/new_components";
-import type { RbSelectOption } from "./elements";
-import type { RbNotifyType } from "./sdk";
-
-type IconComponent = ComponentType<{ title?: string }>;
+// Import shared modules via the package specifier, NOT relative paths. This
+// file ships as source (exports "./host" -> src/host.tsx), while /sdk, /ws,
+// /host-ui ship as dist/*.js. A relative "./sdk" would bundle src/sdk.ts,
+// whereas the plugin (and nexus's pluginShared) load dist/sdk.js via the
+// import map — two RbContext instances, so the host's <RbContext.Provider>
+// and the plugin's useRb() would read different contexts and every rb.* call
+// would hit the no-op "outside of a host context" fallback.
+import type { RbSdk } from "@rainbow-robotics/plugin-ui/sdk";
+import { RbContext } from "@rainbow-robotics/plugin-ui/sdk";
+import { RbWs, createLazyRbSdk } from "@rainbow-robotics/plugin-ui/ws";
+import { getHostServices } from "@rainbow-robotics/plugin-ui/host-ui";
+import { usePluginData, type PluginModuleSource } from "./pluginData";
 
-function resolveIcon(name?: string): ReactNode {
-  if (!name) return null;
-  const Icon = (RBIcons as Record<string, IconComponent | undefined>)[name];
-  return Icon ? <Icon /> : null;
+function pluginRootAttrs(pluginId: string) {
+  return {
+    "data-muscat-plugin-root": "",
+    "data-muscat-plugin-id": pluginId,
+  };
 }
 
 /* -------------------------------------------------------------------------- */
-/* Adapters: rb-* contract props → real rb-components props                    */
+/* rb sdk — pub/sub/action/serve over the plugin's Zenoh WebSocket             */
 /* -------------------------------------------------------------------------- */
 
-/**
- * `createRemoteComponentRenderer` forwards a ref to the wrapped component. Our
- * elements expose no remote methods, so wrap each adapter in `forwardRef` (the
- * ref is intentionally unused) to avoid React's "function components cannot be
- * given refs" warning.
- */
-function adapt<P extends object>(
-  Component: (props: P) => ReactNode,
-): ComponentType<P> {
-  const Wrapped = forwardRef<unknown, P>(function Adapted(props, _ref) {
-    return Component(props as P);
-  });
-  return Wrapped as unknown as ComponentType<P>;
-}
+/** Per-mount host-provided bits (initial data + save registration). */
+type PluginMount = {
+  data?: unknown;
+  onSave: (getPayload: () => unknown) => () => void;
+};
 
-function SliderAdapter({
-  value,
-  min = 0,
-  max = 100,
-  step,
-  disabled,
-  onChange,
-}: {
-  value?: number;
-  min?: number;
-  max?: number;
-  step?: number;
-  disabled?: boolean;
-  onChange?: (value: number) => void;
-}) {
-  return (
-    <RBSlider
-      value={[value ?? min]}
-      min={min}
-      max={max}
-      step={step}
-      disabled={disabled}
-      onValueChange={(values) => onChange?.(values[0] ?? min)}
-    />
-  );
-}
+function useRbSdk(
+  socketUrl: string,
+  pluginId: string,
+  mount: PluginMount,
+): RbSdk {
+  const wsRef = useRef<Promise<RbWs> | null>(null);
+  const keyRef = useRef("");
+  const key = `${socketUrl}::${pluginId}`;
+  if (keyRef.current !== key) {
+    keyRef.current = key;
+    wsRef.current = RbWs.connect(socketUrl, pluginId);
+  }
 
-function ButtonAdapter({
-  label,
-  variant,
-  size,
-  disabled,
-  onPress,
-  children,
-}: {
-  label?: string;
-  variant?: string;
-  size?: string;
-  disabled?: boolean;
-  onPress?: () => void;
-  children?: ReactNode;
-}) {
-  return (
-    <RBLabelButton
-      variant={variant as never}
-      size={size as never}
-      disabled={disabled}
-      onClick={() => onPress?.()}
-    >
-      {label ?? children}
-    </RBLabelButton>
+  return useMemo<RbSdk>(
+    // `mount.data` is captured at first render (stable for a form's lifetime);
+    // `mount.onSave` is a stable callback. Both intentionally out of deps.
+    () => createLazyRbSdk(wsRef.current!, getHostServices(), mount),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [key],
   );
 }
 
-function IconButtonAdapter({
-  icon,
-  variant,
-  size,
-  disabled,
-  onPress,
+/* -------------------------------------------------------------------------- */
+/* ESM mount (prod / robot runtime — import map resolves shared externals)      */
+/* -------------------------------------------------------------------------- */
+
+function EsmPluginHost({
+  source,
+  socketUrl,
+  pluginId,
+  mount,
 }: {
-  icon?: string;
-  variant?: string;
-  size?: string;
-  disabled?: boolean;
-  onPress?: () => void;
+  source: Extract<PluginModuleSource, { kind: "esm" }>;
+  socketUrl: string;
+  pluginId: string;
+  mount: PluginMount;
 }) {
-  return (
-    <RBIconButton
-      icon={resolveIcon(icon)}
-      variant={variant as never}
-      size={size as never}
-      disabled={disabled}
-      onClick={() => onPress?.()}
-    />
-  );
-}
+  const rb = useRbSdk(socketUrl, pluginId, mount);
+  const [App, setApp] = useState<ComponentType | null>(null);
+  const [error, setError] = useState<Error | null>(null);
 
-function TextAdapter({ children }: { children?: ReactNode }) {
-  return <span>{children}</span>;
-}
+  useEffect(() => {
+    let cancelled = false;
+    setApp(null);
+    setError(null);
+    import(/* @vite-ignore */ source.entryUrl)
+      .then((mod: { default?: ComponentType }) => {
+        if (cancelled) return;
+        if (!mod.default) {
+          throw new Error(
+            `plugin entry ${source.entryUrl} has no default export`,
+          );
+        }
+        setApp(() => mod.default!);
+      })
+      .catch((e: unknown) => {
+        if (!cancelled) setError(e instanceof Error ? e : new Error(String(e)));
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [source.entryUrl]);
 
-function TextInputAdapter({
-  value,
-  placeholder,
-  disabled,
-  onInput,
-}: {
-  value?: string;
-  placeholder?: string;
-  disabled?: boolean;
-  onInput?: (value: string) => void;
-}) {
+  if (error) {
+    return (
+      <div className="text-fg-danger p-4 text-sm">
+        Failed to load plugin: {error.message}
+      </div>
+    );
+  }
+  if (!App) {
+    return (
+      <div className="flex items-center justify-center p-4">
+        <div className="border-default size-5 animate-spin rounded-full border-2 border-t-transparent" />
+      </div>
+    );
+  }
   return (
-    <RBTextInput
-      value={value ?? ""}
-      placeholder={placeholder}
-      disabled={disabled}
-      onChange={(e) => onInput?.(e.target.value)}
-    />
+    <div {...pluginRootAttrs(pluginId)}>
+      <RbContext.Provider value={rb}>
+        <App />
+      </RbContext.Provider>
+    </div>
   );
 }
 
-function SwitchAdapter({
-  checked,
-  disabled,
-  onChange,
-}: {
-  checked?: boolean;
-  disabled?: boolean;
-  onChange?: (checked: boolean) => void;
-}) {
-  return (
-    <RBSwitch
-      checked={checked ?? false}
-      disabled={disabled}
-      onCheckedChange={(next) => onChange?.(next)}
-    />
-  );
+/* -------------------------------------------------------------------------- */
+/* Dev mount (muscat-pk dev)                                                    */
+/* -------------------------------------------------------------------------- */
+
+interface DevBootstrapModule {
+  mount: (
+    container: HTMLElement,
+    opts: {
+      socketUrl: string;
+      pluginId: string;
+      hostServices: ReturnType<typeof getHostServices>;
+      data?: unknown;
+      onSave: PluginMount["onSave"];
+    },
+  ) => () => void;
 }
 
-function SelectAdapter({
-  value,
-  options = [],
-  placeholder,
-  disabled,
-  onChange,
+function DevPluginHost({
+  source,
+  socketUrl,
+  pluginId,
+  mount,
 }: {
-  value?: string;
-  options?: RbSelectOption[];
-  placeholder?: string;
-  disabled?: boolean;
-  onChange?: (value: string) => void;
+  source: Extract<PluginModuleSource, { kind: "dev" }>;
+  socketUrl: string;
+  pluginId: string;
+  mount: PluginMount;
 }) {
-  return (
-    <RBSelectBox
-      value={value ?? ""}
-      placeholder={placeholder}
-      disabled={disabled}
-      onChange={(e) => onChange?.((e.target as HTMLInputElement).value)}
-    >
-      {options.map((option) => (
-        <RBSelectOption key={option.value} value={option.value}>
-          {option.label}
-        </RBSelectOption>
-      ))}
-    </RBSelectBox>
-  );
-}
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [error, setError] = useState<Error | null>(null);
 
-/* -------------------------------------------------------------------------- */
-/* Component map: tag → renderer                                               */
-/* -------------------------------------------------------------------------- */
-
-export const RB_COMPONENT_MAP: RemoteComponentRendererMap = new Map([
-  [
-    "rb-slider",
-    createRemoteComponentRenderer(adapt(SliderAdapter), {
-      eventProps: { onChange: { event: "change" } },
-    }),
-  ],
-  [
-    "rb-button",
-    createRemoteComponentRenderer(adapt(ButtonAdapter), {
-      eventProps: { onPress: { event: "press" } },
-    }),
-  ],
-  [
-    "rb-icon-button",
-    createRemoteComponentRenderer(adapt(IconButtonAdapter), {
-      eventProps: { onPress: { event: "press" } },
-    }),
-  ],
-  ["rb-text", createRemoteComponentRenderer(adapt(TextAdapter))],
-  [
-    "rb-text-input",
-    createRemoteComponentRenderer(adapt(TextInputAdapter), {
-      eventProps: { onInput: { event: "input" } },
-    }),
-  ],
-  [
-    "rb-switch",
-    createRemoteComponentRenderer(adapt(SwitchAdapter), {
-      eventProps: { onChange: { event: "change" } },
-    }),
-  ],
-  [
-    "rb-select",
-    createRemoteComponentRenderer(adapt(SelectAdapter), {
-      eventProps: { onChange: { event: "change" } },
-    }),
-  ],
-]);
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+    let unmount: (() => void) | undefined;
+    let cancelled = false;
+    const deferUnmount = () => queueMicrotask(() => unmount?.());
 
-/* -------------------------------------------------------------------------- */
-/* Host SDK contract + mount component                                         */
-/* -------------------------------------------------------------------------- */
+    import(/* @vite-ignore */ source.bootstrapUrl)
+      .then((mod: DevBootstrapModule) => {
+        if (cancelled) return;
+        unmount = mod.mount(container, {
+          socketUrl,
+          pluginId,
+          hostServices: getHostServices(),
+          data: mount.data,
+          onSave: mount.onSave,
+        });
+      })
+      .catch((e: unknown) => {
+        if (!cancelled) setError(e instanceof Error ? e : new Error(String(e)));
+      });
 
-/**
- * Shape the host exposes to the sandbox over the thread (see ./connect).
- * The sandbox opens its own Socket.IO connection from `socketUrl` + `pluginId`
- * and implements pub/sub/action/serve directly; the host only forwards the
- * remote-dom connection, the Socket.IO config, and toast().
- */
-interface HostThreadExports {
-  connect: () => {
-    connection: {
-      mutate: (records: unknown) => void;
-      call: (id: string, method: string, ...args: unknown[]) => unknown;
+    return () => {
+      cancelled = true;
+      deferUnmount();
     };
-    toast: (message: string, type?: RbNotifyType) => void;
-    socketUrl: string;
-    pluginId: string;
-  };
-}
+  }, [source.bootstrapUrl, socketUrl, pluginId]);
 
-export interface PluginContentProps {
-  /** URL of the plugin sandbox document (e.g. /plugin/:id/sandbox.html). */
-  sandboxUrl: string;
-  /** Zenoh router URL the sandbox connects to. */
-  socketUrl: string;
-  /** Plugin id — used for Zenoh topic namespacing inside the sandbox. */
-  pluginId: string;
-  /** Host toast notification handed to the plugin. */
-  toast: (message: string, type?: RbNotifyType) => void;
+  if (error) {
+    return (
+      <div className="text-fg-danger p-4 text-sm">
+        Failed to load plugin (dev): {error.message}
+      </div>
+    );
+  }
+  return <div ref={containerRef} {...pluginRootAttrs(pluginId)} />;
 }
 
-/**
- * Renders a sandboxed plugin: spins up a hidden iframe running the plugin's
- * remote tree, and mirrors that tree with real rb-components in the host.
- */
-export function PluginContent({
-  sandboxUrl,
-  socketUrl,
+/* -------------------------------------------------------------------------- */
+/* Entry point                                                                  */
+/* -------------------------------------------------------------------------- */
+
+/** Renders a plugin's UI. Requires a `PluginDataProvider` above. */
+export function PluginHost({
   pluginId,
-  toast,
-}: PluginContentProps) {
-  const receiver = useMemo(() => new RemoteReceiver(), []);
-  const iframeRef = useRef<HTMLIFrameElement>(null);
-  const toastRef = useRef(toast);
-  toastRef.current = toast;
+  ui,
+  data,
+  onRegisterSave,
+}: {
+  pluginId: string;
+  ui: string;
+  /** Initial data handed to the plugin (e.g. previously-saved form values). */
+  data?: unknown;
+  /**
+   * Called once with a getter the host can invoke (e.g. from a Save button) to
+   * collect the plugin's current payload — `undefined` until the plugin
+   * registers via `useRbSave`, or if it never does.
+   */
+  onRegisterSave?: (getPayload: () => unknown) => void;
+}) {
+  const { getModuleSource, getSocketUrl } = usePluginData();
+  const source = useMemo(
+    () => getModuleSource(pluginId, ui),
+    [getModuleSource, pluginId, ui],
+  );
+  const socketUrl = getSocketUrl(pluginId);
 
-  useEffect(() => {
-    const iframe = iframeRef.current;
-    if (!iframe) return;
+  // The plugin registers its payload getter here; the host reads it back
+  // through the stable getter handed to `onRegisterSave`.
+  const saveRef = useRef<(() => unknown) | null>(null);
+  const registerSave = useCallback((getPayload: () => unknown) => {
+    saveRef.current = getPayload;
+    return () => {
+      if (saveRef.current === getPayload) saveRef.current = null;
+    };
+  }, []);
 
-    const controller = new AbortController();
-    // Host listens from mount; the sandbox calls connect() once it is ready.
-    ThreadWindow.iframe<Record<string, never>, HostThreadExports>(iframe, {
-      targetOrigin: "*",
-      signal: controller.signal,
-      exports: {
-        connect() {
-          return {
-            // forward the receiver's low-level connection across the boundary
-            connection: {
-              mutate: (records: unknown) =>
-                receiver.connection.mutate(records as never),
-              call: (id: string, method: string, ...args: unknown[]) =>
-                receiver.connection.call(id, method, ...args),
-            },
-            toast: (message: string, type?: RbNotifyType) =>
-              toastRef.current(message, type),
-            socketUrl,
-            pluginId,
-          };
-        },
-      },
-    });
+  useEffect(() => {
+    onRegisterSave?.(() => saveRef.current?.());
+  }, [onRegisterSave]);
 
-    return () => controller.abort();
-  }, [receiver, socketUrl, pluginId]);
+  const mount = useMemo<PluginMount>(
+    // data captured once (stable per form lifetime); registerSave is stable.
+    () => ({ data, onSave: registerSave }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [registerSave],
+  );
 
-  return (
-    <>
-      <iframe
-        ref={iframeRef}
-        src={sandboxUrl}
-        sandbox="allow-scripts"
-        hidden
-        title="rb-plugin-sandbox"
+  if (source.kind === "dev") {
+    return (
+      <DevPluginHost
+        source={source}
+        socketUrl={socketUrl}
+        pluginId={pluginId}
+        mount={mount}
       />
-      <RemoteRootRenderer receiver={receiver} components={RB_COMPONENT_MAP} />
-    </>
+    );
+  }
+  return (
+    <EsmPluginHost
+      source={source}
+      socketUrl={socketUrl}
+      pluginId={pluginId}
+      mount={mount}
+    />
   );
 }

package/src/index.d.ts

@@ -0,0 +1 @@
+/// <reference types="@repo/typescript-config" />

package/src/manifest.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
 /**
  * Plugin manifest schema — the single source of truth shared by the front end
  * (nexus reads it) and the back end (rby2 mirrors it for validation).
@@ -7,7 +8,7 @@
 
 /** Known contribution points the host understands. */
 export const CONTRIBUTION_POINTS = [
-  "header.toolbar",
+  "toolbar",
   "lnb",
   "move.panel",
   "program.panel",
@@ -21,12 +22,26 @@ 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 {
@@ -58,7 +73,13 @@ 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. */