gloomberb 0.9.4 → 0.9.6

package/src/remote/resources.ts

@@ -0,0 +1,186 @@
+import type { Dispatch } from "react";
+import type { PluginRegistry } from "../plugins/registry";
+import type { AppAction, AppState } from "../state/app/context";
+import type { PaneRuntimeState } from "../core/state/app/state";
+import { setPaneSettings } from "../pane-settings";
+import type { LayoutConfig } from "../types/config";
+import { commandBarResultsFromNodes, commandBarSnapshot } from "./command-bar";
+import type { RemoteUiRegistry } from "./semantic-tree";
+import { REMOTE_AGENT_HELP, remoteControlSchema } from "./schema";
+import type { RemoteIncludedState, RemoteStateInclude } from "./types";
+import {
+  activeLayoutRev,
+  normalizeIncludes,
+  paneSnapshot,
+  type PatchTarget,
+} from "./controller-utils";
+
+interface RemoteResourceContext {
+  dispatch: Dispatch<AppAction>;
+  getState: () => AppState;
+  pluginRegistry: PluginRegistry;
+  uiRegistry: RemoteUiRegistry | null;
+}
+
+export function createRemoteResources({
+  dispatch,
+  getState,
+  pluginRegistry,
+  uiRegistry,
+}: RemoteResourceContext) {
+  const getResource = (resource: string): unknown => {
+    const state = getState();
+    const uiNodes = uiRegistry?.snapshot() ?? [];
+    if (resource === "app://snapshot") {
+      return {
+        rev: activeLayoutRev(state),
+        app: {
+          activePanel: state.activePanel,
+          focusedPaneId: state.focusedPaneId,
+          previousFocusedPaneId: state.previousFocusedPaneId,
+          statusBarVisible: state.statusBarVisible,
+          commandBarOpen: state.commandBarOpen,
+          commandBarQuery: state.commandBarQuery,
+          initialized: state.initialized,
+        },
+        config: state.config,
+        panes: state.config.layout.instances.map((pane) => paneSnapshot(state, pane)),
+        commandBar: commandBarSnapshot(state, uiNodes),
+        ui: uiNodes,
+        schema: remoteControlSchema(),
+        help: REMOTE_AGENT_HELP,
+      };
+    }
+    if (resource === "app://config") return state.config;
+    if (resource === "app://layout/current") return state.config.layout;
+    if (resource === "app://layouts") return state.config.layouts;
+    if (resource === "app://panes") return state.config.layout.instances.map((pane) => paneSnapshot(state, pane));
+    if (resource === "app://pane-types") {
+      return [...pluginRegistry.panes.values()].map((pane) => ({
+        id: pane.id,
+        name: pane.name,
+        defaultPosition: pane.defaultPosition,
+        defaultMode: pane.defaultMode,
+        hasSettings: !!pane.settings,
+      }));
+    }
+    if (resource === "app://pane-templates") {
+      return [...pluginRegistry.paneTemplates.values()].map((template) => ({
+        id: template.id,
+        paneId: template.paneId,
+        label: template.label,
+        description: template.description,
+        shortcut: template.shortcut,
+      }));
+    }
+    if (resource.startsWith("app://pane-state/")) {
+      const paneId = decodeURIComponent(resource.slice("app://pane-state/".length));
+      return state.paneState[paneId] ?? {};
+    }
+    if (resource.startsWith("app://pane-settings/")) {
+      const paneId = decodeURIComponent(resource.slice("app://pane-settings/".length));
+      const descriptor = pluginRegistry.resolvePaneSettings(paneId);
+      if (!descriptor) throw new Error(`Pane "${paneId}" does not expose settings.`);
+      return {
+        paneId: descriptor.paneId,
+        settings: descriptor.context.settings,
+        fields: descriptor.settingsDef.fields,
+      };
+    }
+    if (resource === "app://commands") {
+      return [...pluginRegistry.commands.values()].map((command) => ({
+        id: command.id,
+        label: command.label,
+        description: command.description,
+        shortcut: command.shortcut,
+        hasWizard: !!command.wizard?.length,
+      }));
+    }
+    if (resource === "app://command-bar") return commandBarSnapshot(state, uiNodes);
+    if (resource === "app://command-bar/results") return commandBarResultsFromNodes(uiNodes);
+    if (resource === "app://capabilities") return pluginRegistry.capabilities.manifests();
+    if (resource === "app://remote/help") return REMOTE_AGENT_HELP;
+    if (resource === "ui://tree") return uiNodes;
+    throw new Error(`Unknown remote resource "${resource}".`);
+  };
+
+  const buildIncludedState = (include: RemoteStateInclude[] | undefined, defaults: RemoteStateInclude[] = []): RemoteIncludedState | undefined => {
+    const included = normalizeIncludes(include, defaults);
+    if (included.length === 0) return undefined;
+    const state = getState();
+    const uiNodes = uiRegistry?.snapshot() ?? [];
+    const result: RemoteIncludedState = {
+      rev: activeLayoutRev(state),
+      included,
+    };
+    if (included.includes("app")) {
+      result.app = {
+        activePanel: state.activePanel,
+        focusedPaneId: state.focusedPaneId,
+        previousFocusedPaneId: state.previousFocusedPaneId,
+        statusBarVisible: state.statusBarVisible,
+        commandBarOpen: state.commandBarOpen,
+        commandBarQuery: state.commandBarQuery,
+        initialized: state.initialized,
+        activeLayoutIndex: state.config.activeLayoutIndex,
+        activeLayoutName: state.config.layouts[state.config.activeLayoutIndex]?.name ?? null,
+      };
+    }
+    if (included.includes("layout")) result.layout = state.config.layout;
+    if (included.includes("panes")) {
+      result.panes = state.config.layout.instances.map((pane) => paneSnapshot(state, pane));
+    }
+    if (included.includes("commandBar") || included.includes("commandBar.results")) {
+      const commandBar = commandBarSnapshot(state, uiNodes);
+      result.commandBar = included.includes("commandBar")
+        ? commandBar
+        : { results: commandBar.results };
+    }
+    if (included.includes("ui")) result.ui = uiNodes;
+    if (included.includes("schema")) result.schema = remoteControlSchema();
+    if (included.includes("help")) result.help = REMOTE_AGENT_HELP;
+    return result;
+  };
+
+  const patchTarget = (resource: string): PatchTarget<unknown> => {
+    const state = getState();
+    if (resource === "app://config") {
+      return {
+        value: state.config,
+        apply: (value) => dispatch({ type: "SET_CONFIG", config: value as AppState["config"] }),
+      };
+    }
+    if (resource === "app://layout/current") {
+      return {
+        value: state.config.layout,
+        apply: (value) => pluginRegistry.updateLayoutFn(value as LayoutConfig),
+      };
+    }
+    if (resource.startsWith("app://pane-state/")) {
+      const paneId = decodeURIComponent(resource.slice("app://pane-state/".length));
+      return {
+        value: state.paneState[paneId] ?? {},
+        apply: (value) => dispatch({ type: "REPLACE_PANE_STATE", paneId, state: value as PaneRuntimeState }),
+      };
+    }
+    if (resource.startsWith("app://pane-settings/")) {
+      const paneId = decodeURIComponent(resource.slice("app://pane-settings/".length));
+      const descriptor = pluginRegistry.resolvePaneSettings(paneId);
+      if (!descriptor) throw new Error(`Pane "${paneId}" does not expose settings.`);
+      return {
+        value: descriptor.context.settings,
+        apply: (value) => {
+          const nextLayout = setPaneSettings(getState().config.layout, descriptor.paneId, value as Record<string, unknown>);
+          pluginRegistry.updateLayoutFn(nextLayout);
+        },
+      };
+    }
+    throw new Error(`Remote resource "${resource}" is not patchable.`);
+  };
+
+  return {
+    buildIncludedState,
+    getResource,
+    patchTarget,
+  };
+}

package/src/remote/revision.ts

@@ -0,0 +1,18 @@
+export function stableStringify(value: unknown): string {
+  if (value == null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+  const object = value as Record<string, unknown>;
+  return `{${Object.keys(object).sort().map((key) => (
+    `${JSON.stringify(key)}:${stableStringify(object[key])}`
+  )).join(",")}}`;
+}
+
+export function revisionFor(value: unknown): string {
+  const input = stableStringify(value);
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < input.length; index += 1) {
+    hash ^= input.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}

package/src/remote/schema.ts

@@ -0,0 +1,143 @@
+import type { RemoteControlSchema, RemoteOperationSchema, RemoteResourceSchema } from "./types";
+
+export const REMOTE_RESOURCES: RemoteResourceSchema[] = [
+  { uri: "app://snapshot", description: "Current app snapshot including layout, focus, panes, command bar, and plugin/capability catalogs." },
+  { uri: "app://config", description: "Current app config.", patchable: true },
+  { uri: "app://layout/current", description: "Current active layout.", patchable: true },
+  { uri: "app://layouts", description: "Saved layouts." },
+  { uri: "app://panes", description: "Current pane instances with placement and runtime state." },
+  { uri: "app://pane-types", description: "Registered pane types from core and plugins." },
+  { uri: "app://pane-templates", description: "Registered pane templates from core and plugins." },
+  { uri: "app://pane-state/{paneId}", description: "Runtime state for a pane instance.", patchable: true },
+  { uri: "app://pane-settings/{paneId}", description: "Persisted settings for a pane instance.", patchable: true },
+  { uri: "app://commands", description: "Registered command-bar commands." },
+  { uri: "app://command-bar", description: "Current command-bar state and semantic result rows." },
+  { uri: "app://command-bar/results", description: "Current semantic command-bar result rows." },
+  { uri: "app://capabilities", description: "Registered plugin capability manifests." },
+  { uri: "app://remote/help", description: "Agent-oriented remote usage guide with efficient recipes and caveats." },
+  { uri: "ui://tree", description: "Live semantic UI node tree populated by shared controls and interactive primitives." },
+];
+
+export const REMOTE_OPERATIONS: RemoteOperationSchema[] = [
+  op("app.openCommandBar", "Open the command bar with an optional query and optional mode.", "{ query?: string, mode?: 'command' | 'ticker' }", "local-write"),
+  op("app.closeCommandBar", "Close the command bar.", "{}", "local-write"),
+  op("app.setCommandBarQuery", "Set the command bar query.", "{ query: string }", "local-write"),
+  op("app.search", "Open command-bar search without requiring UI prefix syntax.", "{ mode: 'command' | 'ticker', query?: string }", "local-write"),
+  op("app.switchPanel", "Switch the active panel.", "{ panel: 'left' | 'right' }", "local-write"),
+  op("app.notify", "Show an in-app notification.", "{ body: string, type?: string }", "local-write"),
+  op("commandBar.activateResult", "Activate a visible command-bar result by zero-based index, node id, item id, or label.", "{ index?: number, nodeId?: string, itemId?: string, label?: string }", "local-write"),
+  op("pane.show", "Show or focus a pane type.", "{ paneId: string }", "local-write"),
+  op("pane.focus", "Focus a pane instance or pane type.", "{ paneId: string }", "local-write"),
+  op("pane.close", "Close a pane instance or pane type.", "{ paneId: string }", "local-write"),
+  op("pane.createFromTemplate", "Create a pane from a registered template.", "{ templateId: string, options?: object }", "local-write"),
+  op("pane.setState", "Patch pane runtime state.", "{ paneId: string, patch: object }", "local-write"),
+  op("pane.setSetting", "Set one pane setting using the pane's registered setting field when available.", "{ paneId: string, key: string, value: any }", "local-write"),
+  op("ticker.navigate", "Navigate a ticker into the best available ticker research target.", "{ symbol: string, sourcePaneId?: string }", "local-write"),
+  op("ticker.pin", "Open or focus a fixed ticker research pane.", "{ symbol: string, floating?: boolean, forceNewPane?: boolean, paneType?: string }", "local-write"),
+  op("ticker.select", "Select a ticker in a target pane.", "{ symbol: string, paneId?: string }", "local-write"),
+  op("ticker.switchTab", "Switch ticker research tab.", "{ tabId: string, paneId?: string }", "local-write"),
+  op("layout.switch", "Switch active layout by index.", "{ index: number }", "local-write"),
+  op("layout.new", "Create a new blank layout.", "{ name: string }", "local-write"),
+  op("layout.rename", "Rename a layout.", "{ index: number, name: string }", "local-write"),
+  op("layout.duplicate", "Duplicate a layout.", "{ index: number }", "local-write"),
+  op("layout.delete", "Delete a layout.", "{ index: number }", "local-write"),
+  op("layout.undo", "Undo last layout change.", "{}", "local-write"),
+  op("layout.redo", "Redo last layout change.", "{}", "local-write"),
+  op("layout.gridlock", "Gridlock all visible panes into a dense layout.", "{}", "local-write"),
+  op("layout.closeFloating", "Close all floating panes in the active layout.", "{}", "local-write"),
+  op("layout.placePane", "Move a pane to a layout region.", "{ paneId: string, region: 'left' | 'right' | 'top' | 'bottom' | 'floating', relativeTo?: string }", "local-write"),
+  op("layout.focusRegion", "Focus a pane by visual layout region.", "{ region: 'left' | 'right' | 'top' | 'bottom' | 'center' }", "local-write"),
+  op("layout.setGrid", "Dock visible or specified panes into a simple grid.", "{ paneIds?: string[], columns?: number }", "local-write"),
+  op("desktop.popOutPane", "Pop a pane into a detached desktop window.", "{ paneId: string }", "local-write"),
+  op("desktop.dockPane", "Dock a detached desktop pane.", "{ paneId: string }", "local-write"),
+  op("desktop.closeDetachedPane", "Close a detached desktop pane.", "{ paneId: string }", "local-write"),
+  op("desktop.focusDetachedPane", "Focus a detached desktop pane.", "{ paneId: string }", "local-write"),
+  op("capability.invoke", "Invoke a registered plugin capability operation.", "{ capabilityId: string, operationId: string, payload?: object }", "local-write"),
+  op("ui.invoke", "Invoke an action on a live semantic UI node.", "{ nodeId: string, action?: string, input?: any }", "local-write"),
+  op("ui.invokeMatching", "Invoke an action on the first semantic UI node matching role, label, index, or metadata.", "{ role?: string, label?: string, contains?: string, index?: number, action?: string, input?: any, metadata?: object }", "local-write"),
+];
+
+export const REMOTE_AGENT_HELP = {
+  title: "Gloomberb remote control guide",
+  quickStart: [
+    "Read app://snapshot once to orient; it includes schema, current layout, panes, command bar state, and semantic UI nodes.",
+    "Prefer app-level operations such as app.search, layout.setGrid, layout.closeFloating, and ticker.pin before falling back to ui.invoke.",
+    "Use commandBar.activateResult with label, itemId, or index after app.search; avoid raw node ids unless there is no stable semantic selector.",
+    "For list-like surfaces, prefer semantic list activation through commandBar.activateResult or ui.invokeMatching.",
+    "Use batch for multi-step flows; steps run sequentially and can return a compact final state so a separate read is not required.",
+  ],
+  resources: [
+    { uri: "app://command-bar", use: "Current command-bar query, open state, selected row, and semantic result rows." },
+    { uri: "app://command-bar/results", use: "Just the visible command-bar result/list rows." },
+    { uri: "ui://tree", use: "Low-level live semantic controls; use when no app-level operation exists." },
+    { uri: "app://panes", use: "Pane instances, placement, focus, and runtime state." },
+  ],
+  recipes: [
+    {
+      goal: "Search for a ticker and open the first result",
+      requests: [
+        { type: "call", operation: "app.search", input: { mode: "ticker", query: "google" } },
+        { type: "call", operation: "commandBar.activateResult", input: { index: 0 } },
+      ],
+      batch: {
+        type: "batch",
+        include: ["commandBar", "panes"],
+        requests: [
+          { type: "call", operation: "app.search", input: { mode: "ticker", query: "google" } },
+          { type: "call", operation: "commandBar.activateResult", input: { index: 0 } },
+        ],
+      },
+    },
+    {
+      goal: "Run a command-bar command",
+      requests: [
+        { type: "call", operation: "app.search", input: { mode: "command", query: "theme" } },
+        { type: "call", operation: "commandBar.activateResult", input: { label: "Change Theme" } },
+      ],
+    },
+    {
+      goal: "Activate a visible semantic control without knowing its node id",
+      request: { type: "call", operation: "ui.invokeMatching", input: { role: "button", label: "Done", action: "press" } },
+    },
+    {
+      goal: "Arrange current panes",
+      request: { type: "call", operation: "layout.setGrid", input: { columns: 2 }, include: ["layout", "panes"] },
+    },
+    {
+      goal: "Move a chart cursor without mouse/keyboard control",
+      request: { type: "call", operation: "ui.invokeMatching", input: { role: "chart", action: "moveCursor", input: { x: 20, y: 4 } } },
+    },
+    {
+      goal: "Pan a chart through its semantic scroll action",
+      request: { type: "call", operation: "ui.invokeMatching", input: { role: "chart", action: "scroll", input: { direction: "down", delta: 3 } } },
+    },
+  ],
+  batching: {
+    requestShape: "{ type: 'batch', requests: RemoteControlRequest[], haltOnError?: boolean, settle?: 'none' | 'afterEach' | 'afterBatch', include?: RemoteStateInclude[] }",
+    behavior: "Requests run sequentially. By default the batch stops on the first failed step and returns a compact final state.",
+  },
+  caveats: [
+    "Capability manifests are for plugin services; UI control should rely on app-level operations and shared semantic UI nodes so plugins remain remote-agnostic.",
+    "If an operation changes UI, request include: ['commandBar'] or use batch include to avoid a follow-up get.",
+    "For charts, use visible semantic chart nodes with actions such as moveCursor, press, drag, release, and scroll.",
+    "Use ui.invokeMatching only after checking app-level operations; it is intentionally generic and depends on visible semantic controls.",
+  ],
+};
+
+export function remoteControlSchema(): RemoteControlSchema {
+  return {
+    protocolVersion: 1,
+    resources: REMOTE_RESOURCES,
+    operations: REMOTE_OPERATIONS,
+    help: REMOTE_AGENT_HELP,
+  };
+}
+
+function op(
+  id: string,
+  description: string,
+  inputShape: string,
+  sideEffectLevel: RemoteOperationSchema["sideEffectLevel"],
+): RemoteOperationSchema {
+  return { id, description, inputShape, sideEffectLevel, dryRun: sideEffectLevel !== "none" };
+}

package/src/remote/semantic-helpers.ts

@@ -0,0 +1,161 @@
+export function remoteEvent(input?: unknown) {
+  return {
+    input,
+    preventDefault() {},
+    stopPropagation() {},
+  };
+}
+
+export function remoteStringValue(input: unknown): string;
+export function remoteStringValue<T extends string | undefined>(input: unknown, fallback: T): string | T;
+export function remoteStringValue(input: unknown, fallback?: string): string | undefined {
+  if (typeof input === "string") return input;
+  if (input && typeof input === "object" && typeof (input as { value?: unknown }).value === "string") {
+    return (input as { value: string }).value;
+  }
+  return arguments.length >= 2 ? fallback : "";
+}
+
+export function remoteNumberValue(input: unknown, keys: string[], fallback = 0): number {
+  if (typeof input === "number") return input;
+  if (input && typeof input === "object") {
+    const record = input as Record<string, unknown>;
+    for (const key of keys) {
+      if (typeof record[key] === "number") return record[key];
+    }
+  }
+  return fallback;
+}
+
+export function remoteOptionalNumberValue(input: unknown, keys: string[]): number | undefined {
+  if (typeof input === "number") return input;
+  if (input && typeof input === "object") {
+    const record = input as Record<string, unknown>;
+    for (const key of keys) {
+      if (typeof record[key] === "number") return record[key];
+    }
+  }
+  return undefined;
+}
+
+export function remoteChartEvent(input: unknown, renderable: unknown, width?: number, height?: number) {
+  const record = input && typeof input === "object" ? input as Record<string, unknown> : {};
+  const resolvedWidth = Math.max(1, width ?? remoteNumberProp(renderable, "width") ?? remoteNumberProp(remoteObjectProp(renderable, "absoluteBounds"), "width") ?? 1);
+  const resolvedHeight = Math.max(1, height ?? remoteNumberProp(renderable, "height") ?? remoteNumberProp(remoteObjectProp(renderable, "absoluteBounds"), "height") ?? 1);
+  const x = clampRemoteCoordinate(remoteOptionalNumberValue(input, ["x", "cellX", "column"]), resolvedWidth);
+  const y = clampRemoteCoordinate(remoteOptionalNumberValue(input, ["y", "cellY", "row"]), resolvedHeight);
+  const originX = remoteNumberProp(renderable, "absoluteX")
+    ?? remoteNumberProp(remoteObjectProp(renderable, "absoluteBounds"), "x")
+    ?? remoteNumberProp(renderable, "x")
+    ?? 0;
+  const originY = remoteNumberProp(renderable, "absoluteY")
+    ?? remoteNumberProp(remoteObjectProp(renderable, "absoluteBounds"), "y")
+    ?? remoteNumberProp(renderable, "y")
+    ?? 0;
+  return {
+    input,
+    x: originX + x,
+    y: originY + y,
+    preciseX: originX + x,
+    preciseY: originY + y,
+    pixelX: remoteOptionalNumberValue(input, ["pixelX"]),
+    pixelY: remoteOptionalNumberValue(input, ["pixelY"]),
+    button: typeof record.button === "number" ? record.button : 0,
+    modifiers: {
+      shift: record.shift === true,
+      alt: record.alt === true,
+      ctrl: record.ctrl === true,
+    },
+    scroll: remoteChartScroll(input),
+    preventDefault() {},
+    stopPropagation() {},
+  };
+}
+
+export function remotePropLabel(props: Record<string, unknown>): string | undefined {
+  for (const key of ["aria-label", "title", "label", "placeholder"]) {
+    const value = props[key];
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return undefined;
+}
+
+export function remotePropRole(props: Record<string, unknown>, fallback: string): string {
+  const explicit = props["data-gloom-role"];
+  return typeof explicit === "string" && explicit.trim() ? explicit.trim() : fallback;
+}
+
+export function remoteMetadataFromProps(props: Record<string, unknown>): Record<string, unknown> {
+  const metadata: Record<string, unknown> = {};
+  const scope = props["data-gloom-remote-scope"];
+  const surface = props["data-gloom-remote-surface"];
+  const kind = props["data-gloom-remote-kind"];
+  if (typeof scope === "string" && scope.trim()) metadata.scope = scope.trim();
+  if (typeof surface === "string" && surface.trim()) metadata.surface = surface.trim();
+  if (typeof kind === "string" && kind.trim()) metadata.kind = kind.trim();
+  return metadata;
+}
+
+type RemoteItemSelector<T> = (item: T, index: number) => string | undefined;
+
+interface RemoteIndexSelectors<T> {
+  id?: RemoteItemSelector<T>;
+  key?: RemoteItemSelector<T>;
+  label?: RemoteItemSelector<T>;
+  value?: RemoteItemSelector<T>;
+}
+
+export function resolveRemoteItemIndex<T>(
+  input: unknown,
+  items: readonly T[],
+  selectors: RemoteIndexSelectors<T>,
+): number {
+  if (typeof input === "number") return input;
+  if (typeof input === "string") return findRemoteItemIndex(input, items, Object.values(selectors));
+  if (input && typeof input === "object") {
+    const record = input as Record<string, unknown>;
+    if (typeof record.index === "number") return record.index;
+    for (const key of ["id", "key", "label", "value"] as const) {
+      if (typeof record[key] !== "string") continue;
+      const selector = selectors[key];
+      if (!selector) continue;
+      return findRemoteItemIndex(record[key], items, [selector]);
+    }
+  }
+  return -1;
+}
+
+function remoteChartScroll(input: unknown) {
+  if (!input || typeof input !== "object") return undefined;
+  const record = input as Record<string, unknown>;
+  const direction = record.direction;
+  if (direction !== "up" && direction !== "down" && direction !== "left" && direction !== "right") return undefined;
+  return {
+    direction,
+    delta: typeof record.delta === "number" ? record.delta : 1,
+  };
+}
+
+function remoteObjectProp(value: unknown, key: string): unknown {
+  return value && typeof value === "object" ? (value as Record<string, unknown>)[key] : undefined;
+}
+
+function remoteNumberProp(value: unknown, key: string): number | undefined {
+  const prop = remoteObjectProp(value, key);
+  return typeof prop === "number" ? prop : undefined;
+}
+
+function clampRemoteCoordinate(value: number | undefined, extent: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return Math.max(0, (extent - 1) / 2);
+  return Math.max(0, Math.min(value, Math.max(extent - 1, 0)));
+}
+
+function findRemoteItemIndex<T>(
+  value: string,
+  items: readonly T[],
+  selectors: Array<RemoteItemSelector<T> | undefined>,
+): number {
+  const activeSelectors = selectors.filter((selector): selector is RemoteItemSelector<T> => !!selector);
+  if (activeSelectors.length === 0) return -1;
+  return items.findIndex((item, index) => activeSelectors.some((selector) => selector(item, index) === value));
+}

package/src/remote/semantic-tree.tsx

@@ -0,0 +1,112 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  type ReactNode,
+} from "react";
+import type { RemoteUiNodeSnapshot } from "./types";
+
+type RemoteUiAction = (input?: unknown) => unknown | Promise<unknown>;
+
+export interface RemoteUiNodeRegistration {
+  role: string;
+  label?: string;
+  disabled?: boolean;
+  actions?: Record<string, RemoteUiAction | undefined>;
+  metadata?: Record<string, unknown>;
+}
+
+interface RegisteredRemoteUiNode extends RemoteUiNodeRegistration {
+  id: string;
+  actions: Record<string, RemoteUiAction>;
+}
+
+export interface RemoteUiRegistry {
+  register(id: string, registration: RemoteUiNodeRegistration): void;
+  unregister(id: string): void;
+  snapshot(): RemoteUiNodeSnapshot[];
+  invoke(nodeId: string, action: string, input?: unknown): Promise<unknown>;
+}
+
+const RemoteUiRegistryContext = createContext<RemoteUiRegistry | null>(null);
+
+function createRemoteUiRegistry(): RemoteUiRegistry {
+  const nodes = new Map<string, RegisteredRemoteUiNode>();
+
+  return {
+    register(id, registration) {
+      nodes.set(id, {
+        ...registration,
+        id,
+        actions: Object.fromEntries(
+          Object.entries(registration.actions ?? {})
+            .filter((entry): entry is [string, RemoteUiAction] => typeof entry[1] === "function"),
+        ),
+      });
+    },
+    unregister(id) {
+      nodes.delete(id);
+    },
+    snapshot() {
+      return [...nodes.values()].map((node) => ({
+        id: node.id,
+        role: node.role,
+        label: node.label,
+        disabled: node.disabled,
+        actions: Object.keys(node.actions).sort(),
+        metadata: node.metadata,
+      }));
+    },
+    async invoke(nodeId, action, input) {
+      const node = nodes.get(nodeId);
+      if (!node) throw new Error(`Unknown UI node "${nodeId}".`);
+      if (node.disabled) throw new Error(`UI node "${nodeId}" is disabled.`);
+      const handler = node.actions[action];
+      if (!handler) throw new Error(`UI node "${nodeId}" does not expose action "${action}".`);
+      return await handler(input);
+    },
+  };
+}
+
+export function RemoteUiRegistryProvider({ children }: { children: ReactNode }) {
+  const registryRef = useRef<RemoteUiRegistry | null>(null);
+  if (!registryRef.current) {
+    registryRef.current = createRemoteUiRegistry();
+  }
+  return (
+    <RemoteUiRegistryContext value={registryRef.current}>
+      {children}
+    </RemoteUiRegistryContext>
+  );
+}
+
+export function useRemoteUiRegistry(): RemoteUiRegistry | null {
+  return useContext(RemoteUiRegistryContext);
+}
+
+export function useRemoteUiNode(registration: RemoteUiNodeRegistration | null | undefined): string | null {
+  const registry = useRemoteUiRegistry();
+  const generatedId = useId();
+  const nodeId = useMemo(() => `ui:${generatedId.replace(/:/g, "")}`, [generatedId]);
+
+  useEffect(() => {
+    if (!registry) return;
+    if (!registration) {
+      registry.unregister(nodeId);
+      return;
+    }
+    registry.register(nodeId, registration);
+  });
+
+  useEffect(() => {
+    return () => registry?.unregister(nodeId);
+  }, [
+    nodeId,
+    registry,
+  ]);
+
+  return registry && registration ? nodeId : null;
+}

package/src/remote/server.test.ts

@@ -0,0 +1,50 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import { readRemoteEndpoint, remoteEndpointPath } from "./endpoint";
+import { sendRemoteControlRequest } from "./client";
+import { startRemoteControlServer, type RemoteControlServer } from "./server";
+
+describe("remote control server", () => {
+  const tempDirs: string[] = [];
+  const servers: RemoteControlServer[] = [];
+
+  afterEach(async () => {
+    await Promise.all(servers.splice(0).map((server) => server.close().catch(() => {})));
+    await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+  });
+
+  test("writes an endpoint and serves authenticated RPC requests", async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), "gloom-remote-"));
+    tempDirs.push(dataDir);
+    const server = await startRemoteControlServer({
+      dataDir,
+      appKind: "tui",
+      handle: async (request) => ({ ok: true, data: { type: request.type } }),
+    });
+    servers.push(server);
+
+    const defaultEndpoint = await readRemoteEndpoint(dataDir);
+    const tuiEndpoint = await readRemoteEndpoint(dataDir, "tui");
+    expect(defaultEndpoint.port).toBe(server.endpoint.port);
+    expect(tuiEndpoint.token).toBe(server.endpoint.token);
+
+    const response = await sendRemoteControlRequest({ type: "schema" }, { dataDir, appKind: "tui" });
+    expect(response).toEqual({ ok: true, data: { type: "schema" } });
+  });
+
+  test("removes endpoint files on close", async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), "gloom-remote-"));
+    tempDirs.push(dataDir);
+    const server = await startRemoteControlServer({
+      dataDir,
+      appKind: "desktop",
+      handle: async () => ({ ok: true, data: null }),
+    });
+    await server.close();
+
+    expect(await Bun.file(remoteEndpointPath(dataDir)).exists()).toBe(false);
+    expect(await Bun.file(remoteEndpointPath(dataDir, "desktop")).exists()).toBe(false);
+  });
+});