@particle-academy/agent-integrations 0.2.4 → 0.4.0

package/README.md

@@ -16,6 +16,26 @@ npm install @particle-academy/agent-integrations
 import "@particle-academy/agent-integrations/styles.css";
 ```
 
+## When you don't need an MCP server
+
+If your agent runs in the same JS process as the surfaces it drives (an embedded chat widget, an in-page worker, an SSR-time tool loop), you don't need any of MCP's JSON-RPC framing. Use **`ToolRegistry`** — a plain in-memory tool host that the bridges register against. Agents drive the surface with `host.callTool("sheet_set_cell", { … })` directly.
+
+```ts
+import {
+  ToolRegistry,
+  registerSheetsBridge,
+  useSheetsAdapter,
+} from "@particle-academy/agent-integrations";
+
+const host = new ToolRegistry();
+registerSheetsBridge(host, { adapter });
+
+// in-process agent:
+await host.callTool("sheet_set_cell", { address: "B3", value: 42 });
+```
+
+Need both? `MicroMcpServer` extends `ToolRegistry`, so the same instance serves direct in-process calls **and** SSE-relayed remote agents at the same time. Bridges accept either — every `register*Bridge(host, …)` signature takes a `ToolHost`.
+
 ## Architecture
 
 ```

package/dist/bridges/charts.d.cts

@@ -0,0 +1,39 @@
+import { T as ToolHost } from '../tool-host-BQuUygLF.cjs';
+import { B as Bridge } from '../types-CCSBGW9T.cjs';
+import '../types-aOQLTW0E.cjs';
+
+/**
+ * Adapter wires a single fancy-echarts chart to the bridge. Charts are
+ * already prop-driven, so the adapter just exposes the data + option
+ * setters and a way to read what's currently rendered.
+ */
+type ChartsBridgeAdapter = {
+    /** Stable id for this chart instance. */
+    id: string;
+    title?: string;
+    screenId?: string;
+    /** Read the current ECharts option object the chart is rendering. */
+    getOption: () => Record<string, unknown>;
+    /** Replace the entire option. */
+    setOption: (option: Record<string, unknown>) => void;
+    /** Convenience: shallow-merge a partial option update. */
+    updateOption?: (partial: Record<string, unknown>) => void;
+    /** Read just the data series (subset of option for quick agent reads). */
+    getData?: () => unknown;
+    /** Update only the data, leaving axes/colors/etc. alone. */
+    updateData?: (data: unknown) => void;
+};
+type ChartsBridgeOptions = {
+    adapter: ChartsBridgeAdapter;
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+};
+/**
+ * registerChartsBridge — schema-aware MCP access to a single chart.
+ */
+declare function registerChartsBridge(host: ToolHost, options: ChartsBridgeOptions): Bridge;
+
+export { type ChartsBridgeAdapter, type ChartsBridgeOptions, registerChartsBridge };

package/dist/bridges/charts.d.ts

@@ -0,0 +1,39 @@
+import { T as ToolHost } from '../tool-host-C8JMMGYq.js';
+import { B as Bridge } from '../types-DIVNcIQO.js';
+import '../types-aOQLTW0E.js';
+
+/**
+ * Adapter wires a single fancy-echarts chart to the bridge. Charts are
+ * already prop-driven, so the adapter just exposes the data + option
+ * setters and a way to read what's currently rendered.
+ */
+type ChartsBridgeAdapter = {
+    /** Stable id for this chart instance. */
+    id: string;
+    title?: string;
+    screenId?: string;
+    /** Read the current ECharts option object the chart is rendering. */
+    getOption: () => Record<string, unknown>;
+    /** Replace the entire option. */
+    setOption: (option: Record<string, unknown>) => void;
+    /** Convenience: shallow-merge a partial option update. */
+    updateOption?: (partial: Record<string, unknown>) => void;
+    /** Read just the data series (subset of option for quick agent reads). */
+    getData?: () => unknown;
+    /** Update only the data, leaving axes/colors/etc. alone. */
+    updateData?: (data: unknown) => void;
+};
+type ChartsBridgeOptions = {
+    adapter: ChartsBridgeAdapter;
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+};
+/**
+ * registerChartsBridge — schema-aware MCP access to a single chart.
+ */
+declare function registerChartsBridge(host: ToolHost, options: ChartsBridgeOptions): Bridge;
+
+export { type ChartsBridgeAdapter, type ChartsBridgeOptions, registerChartsBridge };

package/dist/bridges/code.d.cts

@@ -0,0 +1,47 @@
+import { T as ToolHost } from '../tool-host-BQuUygLF.cjs';
+import { B as Bridge } from '../types-CCSBGW9T.cjs';
+import '../types-aOQLTW0E.cjs';
+
+/**
+ * Adapter the host wires to a fancy-code CodeEditor (typically via the
+ * useCodeEditor hook's context value).
+ */
+type CodeBridgeAdapter = {
+    /** Stable id for this editor instance. */
+    id: string;
+    /** Display label. */
+    title?: string;
+    /** Optional fancy-screens screen id. */
+    screenId?: string;
+    /** Read the current document text. */
+    getValue: () => string;
+    /** Replace the document. */
+    setValue: (value: string) => void;
+    /** Read the current selection text (empty string if none). */
+    getSelection?: () => string;
+    /** Replace the current selection with text. */
+    replaceSelection?: (text: string) => void;
+    /** Programmatic focus. */
+    focus?: () => void;
+    /** Read / set the active language. */
+    getLanguage?: () => string;
+    /** Set the active language. */
+    setLanguage?: (lang: string) => void;
+};
+type CodeBridgeOptions = {
+    adapter: CodeBridgeAdapter;
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+};
+/**
+ * registerCodeBridge — schema-aware MCP access to a single CodeEditor.
+ * Tools cover read, full replace, append, selection replace, language
+ * switch, and a streaming append helper for "type characters into the
+ * editor over time" UX.
+ */
+declare function registerCodeBridge(host: ToolHost, options: CodeBridgeOptions): Bridge;
+
+export { type CodeBridgeAdapter, type CodeBridgeOptions, registerCodeBridge };

package/dist/bridges/code.d.ts

@@ -0,0 +1,47 @@
+import { T as ToolHost } from '../tool-host-C8JMMGYq.js';
+import { B as Bridge } from '../types-DIVNcIQO.js';
+import '../types-aOQLTW0E.js';
+
+/**
+ * Adapter the host wires to a fancy-code CodeEditor (typically via the
+ * useCodeEditor hook's context value).
+ */
+type CodeBridgeAdapter = {
+    /** Stable id for this editor instance. */
+    id: string;
+    /** Display label. */
+    title?: string;
+    /** Optional fancy-screens screen id. */
+    screenId?: string;
+    /** Read the current document text. */
+    getValue: () => string;
+    /** Replace the document. */
+    setValue: (value: string) => void;
+    /** Read the current selection text (empty string if none). */
+    getSelection?: () => string;
+    /** Replace the current selection with text. */
+    replaceSelection?: (text: string) => void;
+    /** Programmatic focus. */
+    focus?: () => void;
+    /** Read / set the active language. */
+    getLanguage?: () => string;
+    /** Set the active language. */
+    setLanguage?: (lang: string) => void;
+};
+type CodeBridgeOptions = {
+    adapter: CodeBridgeAdapter;
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+};
+/**
+ * registerCodeBridge — schema-aware MCP access to a single CodeEditor.
+ * Tools cover read, full replace, append, selection replace, language
+ * switch, and a streaming append helper for "type characters into the
+ * editor over time" UX.
+ */
+declare function registerCodeBridge(host: ToolHost, options: CodeBridgeOptions): Bridge;
+
+export { type CodeBridgeAdapter, type CodeBridgeOptions, registerCodeBridge };

package/dist/bridges/flow.d.cts

@@ -1,5 +1,6 @@
-import { M as MicroMcpServer } from '../server-Bv985us3.cjs';
-import { B as Bridge } from '../types-DR5AS6Rd.cjs';
+import { T as ToolHost } from '../tool-host-BQuUygLF.cjs';
+import { B as Bridge } from '../types-CCSBGW9T.cjs';
+import '../types-aOQLTW0E.cjs';
 
 type FlowNode = {
     id: string;
@@ -67,6 +68,6 @@ type FlowBridgeOptions = {
  * mutation tools (add / update / delete nodes + edges), and optional
  * run/cancel if the host provides those callbacks.
  */
-declare function registerFlowBridge(server: MicroMcpServer, options: FlowBridgeOptions): Bridge;
+declare function registerFlowBridge(host: ToolHost, options: FlowBridgeOptions): Bridge;
 
 export { type FlowBridgeAdapter, type FlowBridgeOptions, registerFlowBridge };

package/dist/bridges/flow.d.ts

@@ -1,5 +1,6 @@
-import { M as MicroMcpServer } from '../server-Bv985us3.js';
-import { B as Bridge } from '../types-CRPA_D0z.js';
+import { T as ToolHost } from '../tool-host-C8JMMGYq.js';
+import { B as Bridge } from '../types-DIVNcIQO.js';
+import '../types-aOQLTW0E.js';
 
 type FlowNode = {
     id: string;
@@ -67,6 +68,6 @@ type FlowBridgeOptions = {
  * mutation tools (add / update / delete nodes + edges), and optional
  * run/cancel if the host provides those callbacks.
  */
-declare function registerFlowBridge(server: MicroMcpServer, options: FlowBridgeOptions): Bridge;
+declare function registerFlowBridge(host: ToolHost, options: FlowBridgeOptions): Bridge;
 
 export { type FlowBridgeAdapter, type FlowBridgeOptions, registerFlowBridge };

package/dist/bridges/forms.d.cts

@@ -0,0 +1,76 @@
+import { T as ToolHost } from '../tool-host-BQuUygLF.cjs';
+import { B as Bridge } from '../types-CCSBGW9T.cjs';
+import '../types-aOQLTW0E.cjs';
+
+/**
+ * Field descriptor — what the host says about each form field. Mirrors the
+ * subset of HTML / react-fancy input shapes agents care about.
+ */
+type FormFieldDescriptor = {
+    /** Form-local field name. Matches the key the host uses in its values map. */
+    name: string;
+    /** Display label. */
+    label?: string;
+    /** Logical type. Drives validation + agent expectations. */
+    type: "text" | "textarea" | "number" | "email" | "password" | "url" | "date" | "select" | "multi-select" | "checkbox" | "switch" | "radio" | "file" | "json";
+    /** Allowed values for select / radio. */
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    /** Whether the field must be filled before submit. */
+    required?: boolean;
+    /** Free-text hint surfaced to the agent. */
+    description?: string;
+    /** Default value (presented in get_value when nothing set). */
+    defaultValue?: unknown;
+};
+/**
+ * Adapter the host wires per form. Matches the controlled-state pattern
+ * react-fancy already uses (`value` / `onValueChange`); this adapter just
+ * exposes those state slots in a form-shaped way the bridge can call.
+ */
+type FormBridgeAdapter = {
+    /** Stable id for the form (used in form_describe + presence target). */
+    id: string;
+    /** Display title for human-readable logs. */
+    title?: string;
+    /** Optional fancy-screens screen id this form belongs to. */
+    screenId?: string;
+    /** Field descriptors. The bridge uses these for schema introspection
+     *  (form_describe). Agents call this first to know what to fill. */
+    getFields: () => FormFieldDescriptor[];
+    /** Read a single field's current value. */
+    getValue: (name: string) => unknown;
+    /** Read all values as { fieldName: value }. */
+    getValues: () => Record<string, unknown>;
+    /** Set a single field's value. The host wires this to its setState. */
+    setValue: (name: string, value: unknown) => void;
+    /** Set many at once. Defaults to calling setValue in a loop. */
+    setValues?: (values: Record<string, unknown>) => void;
+    /** Programmatically focus a field (host implements DOM focus). Optional. */
+    focus?: (name: string) => void;
+    /** Submit the form. Returns the values that were submitted (or rejection). */
+    submit?: () => Promise<{
+        ok: boolean;
+        values?: Record<string, unknown>;
+        error?: string;
+    }>;
+};
+type FormBridgeOptions = {
+    adapter: FormBridgeAdapter;
+    /** Identity tagged into activity events. */
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+};
+/**
+ * registerFormBridge — wires schema-driven MCP access to a single form.
+ * Hosts can register multiple bridges (one per form on the screen) by
+ * giving each adapter a distinct `id`.
+ */
+declare function registerFormBridge(host: ToolHost, options: FormBridgeOptions): Bridge;
+
+export { type FormBridgeAdapter, type FormBridgeOptions, type FormFieldDescriptor, registerFormBridge };

package/dist/bridges/forms.d.ts

@@ -0,0 +1,76 @@
+import { T as ToolHost } from '../tool-host-C8JMMGYq.js';
+import { B as Bridge } from '../types-DIVNcIQO.js';
+import '../types-aOQLTW0E.js';
+
+/**
+ * Field descriptor — what the host says about each form field. Mirrors the
+ * subset of HTML / react-fancy input shapes agents care about.
+ */
+type FormFieldDescriptor = {
+    /** Form-local field name. Matches the key the host uses in its values map. */
+    name: string;
+    /** Display label. */
+    label?: string;
+    /** Logical type. Drives validation + agent expectations. */
+    type: "text" | "textarea" | "number" | "email" | "password" | "url" | "date" | "select" | "multi-select" | "checkbox" | "switch" | "radio" | "file" | "json";
+    /** Allowed values for select / radio. */
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    /** Whether the field must be filled before submit. */
+    required?: boolean;
+    /** Free-text hint surfaced to the agent. */
+    description?: string;
+    /** Default value (presented in get_value when nothing set). */
+    defaultValue?: unknown;
+};
+/**
+ * Adapter the host wires per form. Matches the controlled-state pattern
+ * react-fancy already uses (`value` / `onValueChange`); this adapter just
+ * exposes those state slots in a form-shaped way the bridge can call.
+ */
+type FormBridgeAdapter = {
+    /** Stable id for the form (used in form_describe + presence target). */
+    id: string;
+    /** Display title for human-readable logs. */
+    title?: string;
+    /** Optional fancy-screens screen id this form belongs to. */
+    screenId?: string;
+    /** Field descriptors. The bridge uses these for schema introspection
+     *  (form_describe). Agents call this first to know what to fill. */
+    getFields: () => FormFieldDescriptor[];
+    /** Read a single field's current value. */
+    getValue: (name: string) => unknown;
+    /** Read all values as { fieldName: value }. */
+    getValues: () => Record<string, unknown>;
+    /** Set a single field's value. The host wires this to its setState. */
+    setValue: (name: string, value: unknown) => void;
+    /** Set many at once. Defaults to calling setValue in a loop. */
+    setValues?: (values: Record<string, unknown>) => void;
+    /** Programmatically focus a field (host implements DOM focus). Optional. */
+    focus?: (name: string) => void;
+    /** Submit the form. Returns the values that were submitted (or rejection). */
+    submit?: () => Promise<{
+        ok: boolean;
+        values?: Record<string, unknown>;
+        error?: string;
+    }>;
+};
+type FormBridgeOptions = {
+    adapter: FormBridgeAdapter;
+    /** Identity tagged into activity events. */
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+};
+/**
+ * registerFormBridge — wires schema-driven MCP access to a single form.
+ * Hosts can register multiple bridges (one per form on the screen) by
+ * giving each adapter a distinct `id`.
+ */
+declare function registerFormBridge(host: ToolHost, options: FormBridgeOptions): Bridge;
+
+export { type FormBridgeAdapter, type FormBridgeOptions, type FormFieldDescriptor, registerFormBridge };

package/dist/bridges/scene.d.cts

@@ -0,0 +1,54 @@
+import { T as ToolHost } from '../tool-host-BQuUygLF.cjs';
+import { B as Bridge } from '../types-CCSBGW9T.cjs';
+import '../types-aOQLTW0E.cjs';
+
+/**
+ * Loose Scene types — mirror the public surface of fancy-3d's Scene
+ * descriptor (engine-agnostic JSON the package's adapters consume).
+ */
+type SceneObjectKind = "box" | "sphere" | "cylinder" | "plane" | "screen" | "group" | "custom";
+type SceneObject = {
+    id: string;
+    kind: SceneObjectKind | string;
+    position?: [number, number, number];
+    rotation?: [number, number, number];
+    scale?: [number, number, number];
+    color?: string;
+    /** Free-form per-kind config (e.g. text content for screens). */
+    props?: Record<string, unknown>;
+    children?: SceneObject[];
+};
+type SceneCamera = {
+    position?: [number, number, number];
+    target?: [number, number, number];
+    fov?: number;
+};
+type SceneState = {
+    objects: SceneObject[];
+    camera?: SceneCamera;
+    background?: string;
+};
+type SceneBridgeAdapter = {
+    id: string;
+    title?: string;
+    screenId?: string;
+    getScene: () => SceneState;
+    setScene: (next: SceneState) => void;
+    /** Convenience: set just the camera without touching objects. */
+    setCamera?: (next: SceneCamera) => void;
+};
+type SceneBridgeOptions = {
+    adapter: SceneBridgeAdapter;
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+};
+/**
+ * registerSceneBridge — schema-aware MCP access to a fancy-3d Scene.
+ * Tools cover read, add/update/delete object, set camera, set background.
+ */
+declare function registerSceneBridge(host: ToolHost, options: SceneBridgeOptions): Bridge;
+
+export { type SceneBridgeAdapter, type SceneBridgeOptions, type SceneCamera, type SceneObject, type SceneObjectKind, type SceneState, registerSceneBridge };

package/dist/bridges/scene.d.ts

@@ -0,0 +1,54 @@
+import { T as ToolHost } from '../tool-host-C8JMMGYq.js';
+import { B as Bridge } from '../types-DIVNcIQO.js';
+import '../types-aOQLTW0E.js';
+
+/**
+ * Loose Scene types — mirror the public surface of fancy-3d's Scene
+ * descriptor (engine-agnostic JSON the package's adapters consume).
+ */
+type SceneObjectKind = "box" | "sphere" | "cylinder" | "plane" | "screen" | "group" | "custom";
+type SceneObject = {
+    id: string;
+    kind: SceneObjectKind | string;
+    position?: [number, number, number];
+    rotation?: [number, number, number];
+    scale?: [number, number, number];
+    color?: string;
+    /** Free-form per-kind config (e.g. text content for screens). */
+    props?: Record<string, unknown>;
+    children?: SceneObject[];
+};
+type SceneCamera = {
+    position?: [number, number, number];
+    target?: [number, number, number];
+    fov?: number;
+};
+type SceneState = {
+    objects: SceneObject[];
+    camera?: SceneCamera;
+    background?: string;
+};
+type SceneBridgeAdapter = {
+    id: string;
+    title?: string;
+    screenId?: string;
+    getScene: () => SceneState;
+    setScene: (next: SceneState) => void;
+    /** Convenience: set just the camera without touching objects. */
+    setCamera?: (next: SceneCamera) => void;
+};
+type SceneBridgeOptions = {
+    adapter: SceneBridgeAdapter;
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+};
+/**
+ * registerSceneBridge — schema-aware MCP access to a fancy-3d Scene.
+ * Tools cover read, add/update/delete object, set camera, set background.
+ */
+declare function registerSceneBridge(host: ToolHost, options: SceneBridgeOptions): Bridge;
+
+export { type SceneBridgeAdapter, type SceneBridgeOptions, type SceneCamera, type SceneObject, type SceneObjectKind, type SceneState, registerSceneBridge };

package/dist/bridges/screens.d.cts

@@ -0,0 +1,78 @@
+import { T as ToolHost } from '../tool-host-BQuUygLF.cjs';
+import { B as Bridge } from '../types-CCSBGW9T.cjs';
+import '../types-aOQLTW0E.cjs';
+
+/**
+ * Loose snapshot of a screen — what's in fancy-screens' ScreenMeta plus
+ * the host's optional activity status. Kept here so this bridge has no
+ * hard dep on fancy-screens.
+ */
+type ScreenSnapshot = {
+    id: string;
+    title?: string;
+    /** Whether this screen is the one the human / agent is looking at. */
+    active: boolean;
+    /** Optional category / kind (e.g. "form", "whiteboard"). */
+    kind?: string;
+};
+/**
+ * Spec for a dynamically-created screen. The host's `createScreen`
+ * implementation looks up `kind` in its template registry and instantiates
+ * the matching surface (form / whiteboard / sheet / chart / markdown / etc.).
+ */
+type ScreenCreateSpec = {
+    id: string;
+    title?: string;
+    /** Template kind. Hosts decide the catalog. */
+    kind: string;
+    /** Template-specific config. Form: { fields }. Sheet: { headers }. etc. */
+    config?: Record<string, unknown>;
+};
+/**
+ * Adapter exposes the host's screen-navigation surface to the bridge.
+ * Hosts wire this up against react-router, a custom tab state, or the
+ * fancy-screens registry — wherever "current screen" lives.
+ *
+ * The optional create / destroy / update hooks let agents author screens
+ * dynamically against a host-defined template catalog.
+ */
+type ScreensBridgeAdapter = {
+    /** List every available screen. */
+    listScreens: () => ScreenSnapshot[];
+    /** Read which screen is currently active. */
+    getActive: () => string | null;
+    /** Navigate to a screen by id. Host updates router / tab state. */
+    setActive: (screenId: string) => void;
+    /** Optional: instantiate a new screen from a template + config. */
+    createScreen?: (spec: ScreenCreateSpec) => void;
+    /** Optional: remove a previously-created screen. */
+    destroyScreen?: (screenId: string) => void;
+    /** Optional: shallow-merge new config into an existing screen. */
+    updateScreenContent?: (screenId: string, partial: Record<string, unknown>) => void;
+    /** Optional: enumerate the kinds the host knows how to instantiate. */
+    listKinds?: () => Array<{
+        kind: string;
+        label?: string;
+        description?: string;
+        configSchema?: unknown;
+    }>;
+};
+type ScreensBridgeOptions = {
+    adapter: ScreensBridgeAdapter;
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+};
+/**
+ * registerScreensBridge — top-level navigation bridge so agents can
+ * switch between screens (`screens_navigate`) and discover what surfaces
+ * exist (`screens_list`, `screens_describe_active`).
+ *
+ * Pair with the per-surface bridges (whiteboard, form, sheet, etc.) so
+ * the agent has both navigation and per-screen control.
+ */
+declare function registerScreensBridge(host: ToolHost, options: ScreensBridgeOptions): Bridge;
+
+export { type ScreenCreateSpec, type ScreenSnapshot, type ScreensBridgeAdapter, type ScreensBridgeOptions, registerScreensBridge };

package/dist/bridges/screens.d.ts

@@ -0,0 +1,78 @@
+import { T as ToolHost } from '../tool-host-C8JMMGYq.js';
+import { B as Bridge } from '../types-DIVNcIQO.js';
+import '../types-aOQLTW0E.js';
+
+/**
+ * Loose snapshot of a screen — what's in fancy-screens' ScreenMeta plus
+ * the host's optional activity status. Kept here so this bridge has no
+ * hard dep on fancy-screens.
+ */
+type ScreenSnapshot = {
+    id: string;
+    title?: string;
+    /** Whether this screen is the one the human / agent is looking at. */
+    active: boolean;
+    /** Optional category / kind (e.g. "form", "whiteboard"). */
+    kind?: string;
+};
+/**
+ * Spec for a dynamically-created screen. The host's `createScreen`
+ * implementation looks up `kind` in its template registry and instantiates
+ * the matching surface (form / whiteboard / sheet / chart / markdown / etc.).
+ */
+type ScreenCreateSpec = {
+    id: string;
+    title?: string;
+    /** Template kind. Hosts decide the catalog. */
+    kind: string;
+    /** Template-specific config. Form: { fields }. Sheet: { headers }. etc. */
+    config?: Record<string, unknown>;
+};
+/**
+ * Adapter exposes the host's screen-navigation surface to the bridge.
+ * Hosts wire this up against react-router, a custom tab state, or the
+ * fancy-screens registry — wherever "current screen" lives.
+ *
+ * The optional create / destroy / update hooks let agents author screens
+ * dynamically against a host-defined template catalog.
+ */
+type ScreensBridgeAdapter = {
+    /** List every available screen. */
+    listScreens: () => ScreenSnapshot[];
+    /** Read which screen is currently active. */
+    getActive: () => string | null;
+    /** Navigate to a screen by id. Host updates router / tab state. */
+    setActive: (screenId: string) => void;
+    /** Optional: instantiate a new screen from a template + config. */
+    createScreen?: (spec: ScreenCreateSpec) => void;
+    /** Optional: remove a previously-created screen. */
+    destroyScreen?: (screenId: string) => void;
+    /** Optional: shallow-merge new config into an existing screen. */
+    updateScreenContent?: (screenId: string, partial: Record<string, unknown>) => void;
+    /** Optional: enumerate the kinds the host knows how to instantiate. */
+    listKinds?: () => Array<{
+        kind: string;
+        label?: string;
+        description?: string;
+        configSchema?: unknown;
+    }>;
+};
+type ScreensBridgeOptions = {
+    adapter: ScreensBridgeAdapter;
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+};
+/**
+ * registerScreensBridge — top-level navigation bridge so agents can
+ * switch between screens (`screens_navigate`) and discover what surfaces
+ * exist (`screens_list`, `screens_describe_active`).
+ *
+ * Pair with the per-surface bridges (whiteboard, form, sheet, etc.) so
+ * the agent has both navigation and per-screen control.
+ */
+declare function registerScreensBridge(host: ToolHost, options: ScreensBridgeOptions): Bridge;
+
+export { type ScreenCreateSpec, type ScreenSnapshot, type ScreensBridgeAdapter, type ScreensBridgeOptions, registerScreensBridge };