@particle-academy/agent-integrations 0.2.4 → 0.3.4

package/dist/bridges/charts.d.cts

@@ -0,0 +1,39 @@
+import { M as MicroMcpServer } from '../server-si-VvFxI.cjs';
+import { B as Bridge } from '../types-Bf1ZoGmI.cjs';
+import '../types-DksGd5Y7.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(server: MicroMcpServer, options: ChartsBridgeOptions): Bridge;
+
+export { type ChartsBridgeAdapter, type ChartsBridgeOptions, registerChartsBridge };

package/dist/bridges/charts.d.ts

@@ -0,0 +1,39 @@
+import { M as MicroMcpServer } from '../server-BJu_AMH3.js';
+import { B as Bridge } from '../types-DXKpLuia.js';
+import '../types-DksGd5Y7.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(server: MicroMcpServer, options: ChartsBridgeOptions): Bridge;
+
+export { type ChartsBridgeAdapter, type ChartsBridgeOptions, registerChartsBridge };

package/dist/bridges/code.d.cts

@@ -0,0 +1,47 @@
+import { M as MicroMcpServer } from '../server-si-VvFxI.cjs';
+import { B as Bridge } from '../types-Bf1ZoGmI.cjs';
+import '../types-DksGd5Y7.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(server: MicroMcpServer, options: CodeBridgeOptions): Bridge;
+
+export { type CodeBridgeAdapter, type CodeBridgeOptions, registerCodeBridge };

package/dist/bridges/code.d.ts

@@ -0,0 +1,47 @@
+import { M as MicroMcpServer } from '../server-BJu_AMH3.js';
+import { B as Bridge } from '../types-DXKpLuia.js';
+import '../types-DksGd5Y7.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(server: MicroMcpServer, 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 { M as MicroMcpServer } from '../server-si-VvFxI.cjs';
+import { B as Bridge } from '../types-Bf1ZoGmI.cjs';
+import '../types-DksGd5Y7.cjs';
 
 type FlowNode = {
     id: string;

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 { M as MicroMcpServer } from '../server-BJu_AMH3.js';
+import { B as Bridge } from '../types-DXKpLuia.js';
+import '../types-DksGd5Y7.js';
 
 type FlowNode = {
     id: string;

package/dist/bridges/forms.d.cts

@@ -0,0 +1,76 @@
+import { M as MicroMcpServer } from '../server-si-VvFxI.cjs';
+import { B as Bridge } from '../types-Bf1ZoGmI.cjs';
+import '../types-DksGd5Y7.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(server: MicroMcpServer, options: FormBridgeOptions): Bridge;
+
+export { type FormBridgeAdapter, type FormBridgeOptions, type FormFieldDescriptor, registerFormBridge };

package/dist/bridges/forms.d.ts

@@ -0,0 +1,76 @@
+import { M as MicroMcpServer } from '../server-BJu_AMH3.js';
+import { B as Bridge } from '../types-DXKpLuia.js';
+import '../types-DksGd5Y7.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(server: MicroMcpServer, options: FormBridgeOptions): Bridge;
+
+export { type FormBridgeAdapter, type FormBridgeOptions, type FormFieldDescriptor, registerFormBridge };

package/dist/bridges/scene.d.cts

@@ -0,0 +1,54 @@
+import { M as MicroMcpServer } from '../server-si-VvFxI.cjs';
+import { B as Bridge } from '../types-Bf1ZoGmI.cjs';
+import '../types-DksGd5Y7.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(server: MicroMcpServer, 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 { M as MicroMcpServer } from '../server-BJu_AMH3.js';
+import { B as Bridge } from '../types-DXKpLuia.js';
+import '../types-DksGd5Y7.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(server: MicroMcpServer, options: SceneBridgeOptions): Bridge;
+
+export { type SceneBridgeAdapter, type SceneBridgeOptions, type SceneCamera, type SceneObject, type SceneObjectKind, type SceneState, registerSceneBridge };

package/dist/bridges/sheets.d.cts

@@ -0,0 +1,62 @@
+import { M as MicroMcpServer } from '../server-si-VvFxI.cjs';
+import { B as Bridge } from '../types-Bf1ZoGmI.cjs';
+import '../types-DksGd5Y7.cjs';
+
+/**
+ * Loose types — kept here so the bridge builds without a hard dep on
+ * @particle-academy/fancy-sheets. They mirror the public surface of
+ * `WorkbookData` / `SheetData` / `CellData` from that package.
+ */
+type CellValue = string | number | boolean | null;
+type CellData = {
+    address: string;
+    value: CellValue;
+    format?: unknown;
+    comment?: unknown;
+    computedValue?: CellValue;
+};
+type SheetData = {
+    id: string;
+    name: string;
+    cells: Record<string, CellData>;
+    columnWidths: Record<number, number>;
+    mergedRegions: Array<{
+        start: string;
+        end: string;
+    }>;
+    columnFilters: Record<number, string>;
+    sortColumn?: number;
+    sortDirection?: "asc" | "desc";
+    frozenRows: number;
+    frozenCols: number;
+};
+type WorkbookData = {
+    sheets: SheetData[];
+    activeSheetId: string;
+};
+type SheetsBridgeAdapter = {
+    /** fancy-screens screen id (optional) so activity events know which screen the sheet lives in. */
+    screenId?: string;
+    /** Read the current workbook. */
+    getWorkbook: () => WorkbookData;
+    /** Replace the workbook. Host wires this to its onChange. */
+    setWorkbook: (next: WorkbookData) => void;
+    /** Optional: programmatically change the active cell. */
+    setActiveCell?: (sheetId: string, address: string) => void;
+};
+type SheetsBridgeOptions = {
+    adapter: SheetsBridgeAdapter;
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+};
+/**
+ * registerSheetsBridge — schema-aware MCP access to a fancy-sheets workbook.
+ * Tools are sheet-aware (every mutator takes an explicit `sheet` id, defaulting
+ * to the active sheet when omitted) so an agent can author multi-sheet docs.
+ */
+declare function registerSheetsBridge(server: MicroMcpServer, options: SheetsBridgeOptions): Bridge;
+
+export { type SheetsBridgeAdapter, type SheetsBridgeOptions, registerSheetsBridge };

package/dist/bridges/sheets.d.ts

@@ -0,0 +1,62 @@
+import { M as MicroMcpServer } from '../server-BJu_AMH3.js';
+import { B as Bridge } from '../types-DXKpLuia.js';
+import '../types-DksGd5Y7.js';
+
+/**
+ * Loose types — kept here so the bridge builds without a hard dep on
+ * @particle-academy/fancy-sheets. They mirror the public surface of
+ * `WorkbookData` / `SheetData` / `CellData` from that package.
+ */
+type CellValue = string | number | boolean | null;
+type CellData = {
+    address: string;
+    value: CellValue;
+    format?: unknown;
+    comment?: unknown;
+    computedValue?: CellValue;
+};
+type SheetData = {
+    id: string;
+    name: string;
+    cells: Record<string, CellData>;
+    columnWidths: Record<number, number>;
+    mergedRegions: Array<{
+        start: string;
+        end: string;
+    }>;
+    columnFilters: Record<number, string>;
+    sortColumn?: number;
+    sortDirection?: "asc" | "desc";
+    frozenRows: number;
+    frozenCols: number;
+};
+type WorkbookData = {
+    sheets: SheetData[];
+    activeSheetId: string;
+};
+type SheetsBridgeAdapter = {
+    /** fancy-screens screen id (optional) so activity events know which screen the sheet lives in. */
+    screenId?: string;
+    /** Read the current workbook. */
+    getWorkbook: () => WorkbookData;
+    /** Replace the workbook. Host wires this to its onChange. */
+    setWorkbook: (next: WorkbookData) => void;
+    /** Optional: programmatically change the active cell. */
+    setActiveCell?: (sheetId: string, address: string) => void;
+};
+type SheetsBridgeOptions = {
+    adapter: SheetsBridgeAdapter;
+    agent?: {
+        id: string;
+        name?: string;
+        color?: string;
+    };
+};
+/**
+ * registerSheetsBridge — schema-aware MCP access to a fancy-sheets workbook.
+ * Tools are sheet-aware (every mutator takes an explicit `sheet` id, defaulting
+ * to the active sheet when omitted) so an agent can author multi-sheet docs.
+ */
+declare function registerSheetsBridge(server: MicroMcpServer, options: SheetsBridgeOptions): Bridge;
+
+export { type SheetsBridgeAdapter, type SheetsBridgeOptions, registerSheetsBridge };

package/dist/bridges/whiteboard.d.cts

@@ -1,6 +1,7 @@
 import { StickyNoteItem, ShapeItem, ConnectorItem, Stroke, Viewport, RemoteCursor } from '@particle-academy/fancy-whiteboard';
-import { M as MicroMcpServer } from '../server-Bv985us3.cjs';
-import { B as Bridge } from '../types-DR5AS6Rd.cjs';
+import { M as MicroMcpServer } from '../server-si-VvFxI.cjs';
+import { B as Bridge } from '../types-Bf1ZoGmI.cjs';
+import '../types-DksGd5Y7.cjs';
 
 /**
  * State accessors / mutators the bridge needs from the host. The host owns

package/dist/bridges/whiteboard.d.ts

@@ -1,6 +1,7 @@
 import { StickyNoteItem, ShapeItem, ConnectorItem, Stroke, Viewport, RemoteCursor } from '@particle-academy/fancy-whiteboard';
-import { M as MicroMcpServer } from '../server-Bv985us3.js';
-import { B as Bridge } from '../types-CRPA_D0z.js';
+import { M as MicroMcpServer } from '../server-BJu_AMH3.js';
+import { B as Bridge } from '../types-DXKpLuia.js';
+import '../types-DksGd5Y7.js';
 
 /**
  * State accessors / mutators the bridge needs from the host. The host owns