@rainbow-robotics/plugin-ui 0.1.0

package/src/elements.ts

@@ -0,0 +1,257 @@
+/**
+ * rb-* remote element contract — shared by the sandbox (plugin author) and the
+ * nexus host. This is the *stable* surface: it must only ever grow additively
+ * (new elements / new optional properties), never break existing shapes.
+ *
+ * Verified against @remote-dom/core@1.11.x:
+ *   - `RemoteElement` lives in `@remote-dom/core/elements`
+ *   - static `remoteProperties` (data) + static `remoteEvents` (callbacks)
+ */
+import { RemoteElement } from "@remote-dom/core/elements";
+
+type RbNoMethods = Record<never, never>;
+type RbNoSlots = Record<never, never>;
+type RbNoEvents = Record<never, never>;
+
+export interface RbSliderProps {
+  value?: number;
+  min?: number;
+  max?: number;
+  step?: number;
+  disabled?: boolean;
+}
+
+export interface RbButtonProps {
+  label?: string;
+  variant?: string;
+  size?: string;
+  disabled?: boolean;
+}
+
+export interface RbIconButtonProps {
+  icon?: string;
+  variant?: string;
+  size?: string;
+  disabled?: boolean;
+}
+
+export type RbTextProps = Record<never, never>;
+
+export interface RbTextInputProps {
+  value?: string;
+  placeholder?: string;
+  disabled?: boolean;
+}
+
+export interface RbSwitchProps {
+  checked?: boolean;
+  disabled?: boolean;
+}
+
+/** Option shape carried by `rb-select`'s `options` property. */
+export interface RbSelectOption {
+  value: string;
+  label: string;
+}
+
+export interface RbSelectProps {
+  value?: string;
+  options?: RbSelectOption[];
+  placeholder?: string;
+  disabled?: boolean;
+}
+
+export interface RbSliderEvents {
+  change(detail: number): void;
+}
+
+export interface RbPressEvents {
+  press(): void;
+}
+
+export interface RbTextInputEvents {
+  input(detail: string): void;
+}
+
+export interface RbSwitchEvents {
+  change(detail: boolean): void;
+}
+
+export interface RbSelectEvents {
+  change(detail: string): void;
+}
+
+/** Slider → host renders RBSlider (Radix array value, single-thumb contract). */
+export class RbSliderElement extends RemoteElement<
+  RbSliderProps,
+  RbNoMethods,
+  RbNoSlots,
+  RbSliderEvents
+> {
+  static get remoteProperties() {
+    return {
+      value: { type: Number },
+      min: { type: Number },
+      max: { type: Number },
+      step: { type: Number },
+      disabled: { type: Boolean },
+    };
+  }
+  static get remoteEvents() {
+    return ["change"] as const;
+  }
+}
+
+/** Button → host renders RBLabelButton. */
+export class RbButtonElement extends RemoteElement<
+  RbButtonProps,
+  RbNoMethods,
+  RbNoSlots,
+  RbPressEvents
+> {
+  static get remoteProperties() {
+    return {
+      label: { type: String },
+      variant: { type: String },
+      size: { type: String },
+      disabled: { type: Boolean },
+    };
+  }
+  static get remoteEvents() {
+    return ["press"] as const;
+  }
+}
+
+/** Icon button → host renders RBIconButton with an icon resolved from RBIcons. */
+export class RbIconButtonElement extends RemoteElement<
+  RbIconButtonProps,
+  RbNoMethods,
+  RbNoSlots,
+  RbPressEvents
+> {
+  static get remoteProperties() {
+    return {
+      icon: { type: String },
+      variant: { type: String },
+      size: { type: String },
+      disabled: { type: Boolean },
+    };
+  }
+  static get remoteEvents() {
+    return ["press"] as const;
+  }
+}
+
+/** Plain text — renders its children as text on the host. */
+export class RbTextElement extends RemoteElement<
+  RbTextProps,
+  RbNoMethods,
+  RbNoSlots,
+  RbNoEvents
+> {
+  static get remoteProperties() {
+    return {};
+  }
+}
+
+/** Text input → host renders RBTextInput. */
+export class RbTextInputElement extends RemoteElement<
+  RbTextInputProps,
+  RbNoMethods,
+  RbNoSlots,
+  RbTextInputEvents
+> {
+  static get remoteProperties() {
+    return {
+      value: { type: String },
+      placeholder: { type: String },
+      disabled: { type: Boolean },
+    };
+  }
+  static get remoteEvents() {
+    return ["input"] as const;
+  }
+}
+
+/** Switch → host renders RBSwitch. */
+export class RbSwitchElement extends RemoteElement<
+  RbSwitchProps,
+  RbNoMethods,
+  RbNoSlots,
+  RbSwitchEvents
+> {
+  static get remoteProperties() {
+    return {
+      checked: { type: Boolean },
+      disabled: { type: Boolean },
+    };
+  }
+  static get remoteEvents() {
+    return ["change"] as const;
+  }
+}
+
+/** Select → host renders RBSelectBox. `options` is `[{value,label}]`. */
+export class RbSelectElement extends RemoteElement<
+  RbSelectProps,
+  RbNoMethods,
+  RbNoSlots,
+  RbSelectEvents
+> {
+  static get remoteProperties() {
+    return {
+      value: { type: String },
+      options: { type: Array },
+      placeholder: { type: String },
+      disabled: { type: Boolean },
+    };
+  }
+  static get remoteEvents() {
+    return ["change"] as const;
+  }
+}
+
+/** Custom element tag names in the contract. */
+export const RB_ELEMENT_NAMES = [
+  "rb-slider",
+  "rb-button",
+  "rb-icon-button",
+  "rb-text",
+  "rb-text-input",
+  "rb-switch",
+  "rb-select",
+] as const;
+
+export type RbElementName = (typeof RB_ELEMENT_NAMES)[number];
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "rb-slider": RbSliderElement;
+    "rb-button": RbButtonElement;
+    "rb-icon-button": RbIconButtonElement;
+    "rb-text": RbTextElement;
+    "rb-text-input": RbTextInputElement;
+    "rb-switch": RbSwitchElement;
+    "rb-select": RbSelectElement;
+  }
+}
+
+let defined = false;
+
+/**
+ * Registers the rb-* custom elements. Safe to call multiple times; only the
+ * first call defines anything (subsequent calls are a no-op).
+ */
+export function defineElements(): void {
+  if (defined || typeof customElements === "undefined") return;
+
+  defined = true;
+
+  customElements.define("rb-slider", RbSliderElement);
+  customElements.define("rb-button", RbButtonElement);
+  customElements.define("rb-icon-button", RbIconButtonElement);
+  customElements.define("rb-text", RbTextElement);
+  customElements.define("rb-text-input", RbTextInputElement);
+  customElements.define("rb-switch", RbSwitchElement);
+  customElements.define("rb-select", RbSelectElement);
+}

package/src/host.tsx

@@ -0,0 +1,343 @@
+/**
+ * Host bindings — used by nexus (Muscat) only.
+ *
+ * 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.
+ *
+ * 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.
+ */
+import {
+  forwardRef,
+  useEffect,
+  useMemo,
+  useRef,
+  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 { RbSdk } from "./sdk";
+
+type IconComponent = ComponentType<{ title?: string }>;
+
+function resolveIcon(name?: string): ReactNode {
+  if (!name) return null;
+  const Icon = (RBIcons as Record<string, IconComponent | undefined>)[name];
+  return Icon ? <Icon /> : null;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Adapters: rb-* contract props → real rb-components props                    */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * `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>;
+}
+
+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 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>
+  );
+}
+
+function IconButtonAdapter({
+  icon,
+  variant,
+  size,
+  disabled,
+  onPress,
+}: {
+  icon?: string;
+  variant?: string;
+  size?: string;
+  disabled?: boolean;
+  onPress?: () => void;
+}) {
+  return (
+    <RBIconButton
+      icon={resolveIcon(icon)}
+      variant={variant as never}
+      size={size as never}
+      disabled={disabled}
+      onClick={() => onPress?.()}
+    />
+  );
+}
+
+function TextAdapter({ children }: { children?: ReactNode }) {
+  return <span>{children}</span>;
+}
+
+function TextInputAdapter({
+  value,
+  placeholder,
+  disabled,
+  onInput,
+}: {
+  value?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  onInput?: (value: string) => void;
+}) {
+  return (
+    <RBTextInput
+      value={value ?? ""}
+      placeholder={placeholder}
+      disabled={disabled}
+      onChange={(e) => onInput?.(e.target.value)}
+    />
+  );
+}
+
+function SwitchAdapter({
+  checked,
+  disabled,
+  onChange,
+}: {
+  checked?: boolean;
+  disabled?: boolean;
+  onChange?: (checked: boolean) => void;
+}) {
+  return (
+    <RBSwitch
+      checked={checked ?? false}
+      disabled={disabled}
+      onCheckedChange={(next) => onChange?.(next)}
+    />
+  );
+}
+
+function SelectAdapter({
+  value,
+  options = [],
+  placeholder,
+  disabled,
+  onChange,
+}: {
+  value?: string;
+  options?: RbSelectOption[];
+  placeholder?: string;
+  disabled?: boolean;
+  onChange?: (value: string) => void;
+}) {
+  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>
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/* 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" } },
+    }),
+  ],
+]);
+
+/* -------------------------------------------------------------------------- */
+/* Host SDK contract + mount component                                         */
+/* -------------------------------------------------------------------------- */
+
+export type RbSdkImpl = RbSdk;
+
+/** Shape the host exposes to the sandbox over the thread (see ./connect). */
+interface HostThreadExports {
+  connect: () => {
+    connection: {
+      mutate: (records: unknown) => void;
+      call: (id: string, method: string, ...args: unknown[]) => unknown;
+    };
+    action: (id: string, payload?: unknown) => Promise<unknown>;
+    notify: (message: string, type?: string) => void;
+  };
+}
+
+export interface PluginContentProps {
+  /** URL of the plugin sandbox document (e.g. /plugin/:id/sandbox.html). */
+  sandboxUrl: string;
+  /** Host SDK implementation handed to the plugin. */
+  rb: RbSdkImpl;
+}
+
+/**
+ * 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, rb }: PluginContentProps) {
+  const receiver = useMemo(() => new RemoteReceiver(), []);
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const rbRef = useRef(rb);
+  rbRef.current = rb;
+
+  useEffect(() => {
+    const iframe = iframeRef.current;
+    if (!iframe) return;
+
+    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),
+            },
+            action: (id: string, payload?: unknown) =>
+              rbRef.current.action(id, payload),
+            notify: (message: string, type?: string) =>
+              rbRef.current.notify(message, type as never),
+          };
+        },
+      },
+    });
+
+    return () => controller.abort();
+  }, [receiver]);
+
+  return (
+    <>
+      <iframe
+        ref={iframeRef}
+        src={sandboxUrl}
+        sandbox="allow-scripts"
+        hidden
+        title="rb-plugin-sandbox"
+      />
+      <RemoteRootRenderer receiver={receiver} components={RB_COMPONENT_MAP} />
+    </>
+  );
+}

package/src/manifest.ts

@@ -0,0 +1,92 @@
+/**
+ * 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).
+ *
+ * Evolve additively only.
+ */
+
+/** Known contribution points the host understands. */
+export const CONTRIBUTION_POINTS = [
+  "header.toolbar",
+  "lnb",
+  "move.panel",
+  "program.panel",
+] as const;
+
+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 & {});
+  /** Icon path relative to the plugin root (e.g. "assets/icon.svg"). */
+  icon?: string;
+  /** Display label. */
+  label?: string;
+  /** For header.toolbar: how the contribution surfaces. */
+  opens?: ContributionOpens;
+}
+
+export interface PluginAction {
+  /** Action id referenced by `rb.action(id, payload)`. */
+  id: string;
+  /** Transport topic (Zenoh / ROS2) the back end routes to. */
+  topic: string;
+  /** Optional payload schema hint (field → type name). */
+  schema?: Record<string, string>;
+}
+
+export type PluginRuntime =
+  | { type: "none" }
+  | { type: "python"; entry: string }
+  | {
+      type: "ros2";
+      package: string;
+      launch: string;
+      rosClient: "rclpy" | "rclcpp";
+    };
+
+export interface PluginManifest {
+  /** Reverse-DNS unique id, e.g. "com.rainbow.gripper-tool". */
+  id: string;
+  /** Human-readable name. */
+  name: string;
+  /** Plugin version (semver). */
+  version: string;
+  /** Minimum host (Muscat) version this plugin supports. */
+  minAppVersion?: string;
+  /** Icon path relative to plugin root. */
+  icon?: string;
+  /** UI / chrome contributions. */
+  contributes?: PluginContribution[];
+  /** Host actions the plugin can invoke. */
+  actions?: PluginAction[];
+  /** Back-end runtime declaration. */
+  runtime?: PluginRuntime;
+}
+
+/**
+ * Lightweight structural check. Returns the list of problems (empty = valid).
+ * Kept dependency-free so both front and back ends can reuse it; richer
+ * validation (zod) can layer on top later without breaking this contract.
+ */
+export function validateManifest(value: unknown): string[] {
+  const errors: string[] = [];
+  if (typeof value !== "object" || value === null) {
+    return ["manifest must be an object"];
+  }
+  const m = value as Record<string, unknown>;
+  if (typeof m.id !== "string" || m.id.length === 0)
+    errors.push("manifest.id is required (string)");
+  if (typeof m.name !== "string" || m.name.length === 0)
+    errors.push("manifest.name is required (string)");
+  if (typeof m.version !== "string" || m.version.length === 0)
+    errors.push("manifest.version is required (string)");
+  if (m.contributes !== undefined && !Array.isArray(m.contributes))
+    errors.push("manifest.contributes must be an array");
+  if (m.actions !== undefined && !Array.isArray(m.actions))
+    errors.push("manifest.actions must be an array");
+  return errors;
+}