@particle-academy/agent-integrations 0.3.4 → 0.5.0

package/dist/sheets-adapter.cjs

@@ -0,0 +1,96 @@
+'use strict';
+
+var react = require('react');
+
+// src/sheets-adapter.ts
+
+// src/presence/registry.ts
+var listeners = /* @__PURE__ */ new Set();
+function onActivity(listener, filter) {
+  const wrapped = listener;
+  listeners.add(wrapped);
+  return () => listeners.delete(wrapped);
+}
+
+// src/sheets-adapter.ts
+function useSheetsAdapter(initial, options = {}) {
+  const [workbook, setWorkbook] = react.useState(initial);
+  const [activeCell, setActiveCellState] = react.useState(null);
+  const workbookRef = react.useRef(workbook);
+  workbookRef.current = workbook;
+  const setActiveCell = react.useCallback((sheetId, address) => {
+    setWorkbook((cur) => cur.activeSheetId === sheetId ? cur : { ...cur, activeSheetId: sheetId });
+    setActiveCellState(address);
+  }, []);
+  const onActiveCellChange = react.useCallback((address) => {
+    setActiveCellState(address);
+  }, []);
+  const setWorkbookRef = react.useRef(setWorkbook);
+  setWorkbookRef.current = setWorkbook;
+  const adapter = react.useMemo(
+    () => ({
+      screenId: options.screenId,
+      getWorkbook: () => workbookRef.current,
+      setWorkbook: (next) => setWorkbookRef.current(next),
+      setActiveCell
+    }),
+    [options.screenId, setActiveCell]
+  );
+  return {
+    workbook,
+    setWorkbook,
+    onActiveCellChange,
+    adapter,
+    setActiveCell,
+    activeCell
+  };
+}
+function useSheetsActivityHighlights(options = {}) {
+  const ttlMs = options.ttlMs ?? 2200;
+  const screenId = options.screenId;
+  const [, force] = react.useState(0);
+  const hitsRef = react.useRef(/* @__PURE__ */ new Map());
+  react.useEffect(() => {
+    const off = onActivity((event) => {
+      if (event.target?.kind !== "sheet") return;
+      if (screenId && event.target.screenId && event.target.screenId !== screenId) return;
+      const elementId = event.target.elementId;
+      if (!elementId || !elementId.includes("!")) return;
+      hitsRef.current.set(elementId, { event, expiresAt: Date.now() + ttlMs });
+      force((n) => n + 1);
+    });
+    return off;
+  }, [screenId, ttlMs]);
+  react.useEffect(() => {
+    const t = window.setInterval(() => {
+      const now = Date.now();
+      let dirty = false;
+      for (const [k, v] of hitsRef.current) {
+        if (v.expiresAt < now) {
+          hitsRef.current.delete(k);
+          dirty = true;
+        }
+      }
+      if (dirty) force((n) => n + 1);
+    }, 500);
+    return () => window.clearInterval(t);
+  }, []);
+  const out = {};
+  for (const [elementId, { event }] of hitsRef.current) {
+    const idx = elementId.indexOf("!");
+    const address = elementId.slice(idx + 1);
+    if (!address) continue;
+    const color = event.agentColor ?? "#a855f7";
+    out[address] = {
+      color,
+      backgroundColor: color + "33",
+      label: event.agentName ?? event.agentId ?? "agent"
+    };
+  }
+  return out;
+}
+
+exports.useSheetsActivityHighlights = useSheetsActivityHighlights;
+exports.useSheetsAdapter = useSheetsAdapter;
+//# sourceMappingURL=sheets-adapter.cjs.map
+//# sourceMappingURL=sheets-adapter.cjs.map

package/dist/sheets-adapter.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/presence/registry.ts","../src/sheets-adapter.ts"],"names":["useState","useRef","useCallback","useMemo","useEffect"],"mappings":"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","file":"sheets-adapter.cjs","sourcesContent":["import type { ActivityFilter, AgentActivityEvent, AgentActivityListener } from \"./types\";\n\n/**\n * In-process registry of agent activity events. Bridges call `emitActivity`\n * after a tool runs; React hooks + the SSE relay subscribe via\n * `onActivity()`.\n *\n * Holds a short scrollback of recent events (default 200) so newly-mounted\n * subscribers can render the recent past — useful for activity-log UIs\n * that rejoin a session mid-stream.\n */\n\nconst HISTORY_CAP = 200;\n\nconst listeners = new Set<AgentActivityListener>();\nconst history: AgentActivityEvent[] = [];\n\n/** Emit an activity event. All current listeners receive it synchronously. */\nexport function emitActivity(event: AgentActivityEvent): void {\n  history.push(event);\n  if (history.length > HISTORY_CAP) history.splice(0, history.length - HISTORY_CAP);\n  for (const l of listeners) l(event);\n}\n\n/**\n * Subscribe to all events (or a filtered subset). Returns an unsubscribe\n * function. Filter checks all provided keys with strict equality; omit a\n * key to ignore it.\n */\nexport function onActivity(listener: AgentActivityListener, filter?: ActivityFilter): () => void {\n  const wrapped: AgentActivityListener = filter\n    ? (e) => { if (matches(e, filter)) listener(e); }\n    : listener;\n  listeners.add(wrapped);\n  return () => listeners.delete(wrapped);\n}\n\n/** Read the recent history (newest last). Optional filter. */\nexport function readActivityHistory(filter?: ActivityFilter): AgentActivityEvent[] {\n  if (!filter) return history.slice();\n  return history.filter((e) => matches(e, filter));\n}\n\n/** Wipe history + clear listeners. Test/teardown helper. */\nexport function resetActivityRegistry(): void {\n  listeners.clear();\n  history.length = 0;\n}\n\nfunction matches(e: AgentActivityEvent, f: ActivityFilter): boolean {\n  if (f.agentId !== undefined && e.agentId !== f.agentId) return false;\n  if (f.screenId !== undefined && e.target.screenId !== f.screenId) return false;\n  if (f.kind !== undefined && e.target.kind !== f.kind) return false;\n  return true;\n}\n","import { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\nimport type { SheetsBridgeAdapter } from \"./bridges/sheets\";\nimport { onActivity } from \"./presence/registry\";\nimport type { AgentActivityEvent } from \"./presence/types\";\n\n/**\n * Shared-session helpers for `@particle-academy/fancy-sheets`.\n *\n * fancy-sheets' `SheetWorkbook` is already controlled (`data` + `onChange`).\n * The two missing pieces for a clean shared-session experience are:\n *\n *   1. an adapter object the host can hand to {@link registerSheetsBridge}\n *      without writing boilerplate, and\n *   2. a derived `CellHighlightMap` so agent edits visibly pulse on the\n *      humans' screens — wired from the presence registry's per-bridge\n *      activity stream.\n *\n * These are kept as host-side hooks (not part of the bridge itself) so\n * agent-integrations keeps zero hard deps on fancy-sheets. The host\n * imports SheetWorkbook directly and feeds these hooks' outputs into\n * its props.\n *\n *   const wb = useSheetsAdapter(initial, { screenId: \"deal-sheet\" });\n *   const highlights = useSheetsActivityHighlights({ screenId: \"deal-sheet\" });\n *\n *   useEffect(() => {\n *     const bridge = registerSheetsBridge(host, { adapter: wb.adapter });\n *     return bridge.dispose;\n *   }, [host, wb.adapter]);\n *\n *   <SheetWorkbook\n *     data={wb.workbook}\n *     onChange={wb.setWorkbook}\n *     highlights={highlights}\n *     onActiveCellChange={wb.onActiveCellChange}\n *   />\n */\n\n// Loose structural mirror of fancy-sheets' WorkbookData — kept local so\n// this helper doesn't pull a runtime dep on the package. The constraint\n// only names the fields the hook itself reads (`sheets` + `activeSheetId`);\n// it does NOT add a `[k: string]: unknown` index signature, so consumers\n// can pass the real `WorkbookData` from fancy-sheets through without\n// triggering an \"index signature missing\" error.\nexport type WorkbookLike = {\n  sheets: Array<{ id: string; name: string }>;\n  activeSheetId: string;\n};\n\nexport type SheetsAdapterOptions = {\n  /** Tags the bridge's screen id so presence events route correctly. */\n  screenId?: string;\n};\n\nexport type UseSheetsAdapterResult<W extends WorkbookLike> = {\n  /** Controlled workbook state. Wire to `<SheetWorkbook data={…} />`. */\n  workbook: W;\n  /** Setter for the controlled state. Wire to `<SheetWorkbook onChange={…} />`. */\n  setWorkbook: (next: W) => void;\n  /** Wire to `<SheetWorkbook onActiveCellChange={…} />` to track focus. */\n  onActiveCellChange: (address: string) => void;\n  /** Stable adapter to hand to `registerSheetsBridge({ adapter })`. */\n  adapter: SheetsBridgeAdapter;\n  /** Imperative: set the active sheet + cell. Mirrors the adapter's hook. */\n  setActiveCell: (sheetId: string, address: string) => void;\n  /** Read-only: the address last focused (any source). */\n  activeCell: string | null;\n};\n\n/**\n * useSheetsAdapter — one-liner glue between fancy-sheets' SheetWorkbook\n * and the sheets bridge.\n *\n *   const wb = useSheetsAdapter(initialWorkbook, { screenId: \"...\" });\n *\n *   useEffect(() => registerSheetsBridge(host, { adapter: wb.adapter }).dispose,\n *             [host, wb.adapter]);\n *\n *   <SheetWorkbook\n *     data={wb.workbook}\n *     onChange={wb.setWorkbook}\n *     onActiveCellChange={wb.onActiveCellChange}\n *   />\n */\nexport function useSheetsAdapter<W extends WorkbookLike>(\n  initial: W,\n  options: SheetsAdapterOptions = {},\n): UseSheetsAdapterResult<W> {\n  const [workbook, setWorkbook] = useState<W>(initial);\n  const [activeCell, setActiveCellState] = useState<string | null>(null);\n  const workbookRef = useRef(workbook);\n  workbookRef.current = workbook;\n\n  const setActiveCell = useCallback((sheetId: string, address: string) => {\n    setWorkbook((cur) => (cur.activeSheetId === sheetId ? cur : { ...cur, activeSheetId: sheetId }));\n    setActiveCellState(address);\n  }, []);\n\n  const onActiveCellChange = useCallback((address: string) => {\n    setActiveCellState(address);\n  }, []);\n\n  // Adapter must be stable across renders so the bridge's tool catalog\n  // doesn't churn — bind it to refs that hold the latest state + setter.\n  const setWorkbookRef = useRef(setWorkbook);\n  setWorkbookRef.current = setWorkbook;\n\n  const adapter = useMemo<SheetsBridgeAdapter>(\n    () => ({\n      screenId: options.screenId,\n      getWorkbook: () => workbookRef.current as unknown as ReturnType<SheetsBridgeAdapter[\"getWorkbook\"]>,\n      setWorkbook: (next) => setWorkbookRef.current(next as unknown as W),\n      setActiveCell,\n    }),\n    [options.screenId, setActiveCell],\n  );\n\n  return {\n    workbook,\n    setWorkbook,\n    onActiveCellChange,\n    adapter,\n    setActiveCell,\n    activeCell,\n  };\n}\n\n/**\n * Mirror of fancy-sheets' `CellHighlight` — structurally identical so the\n * map returned from {@link useSheetsActivityHighlights} can be passed\n * straight into `<SheetWorkbook highlights={…} />` without any casts.\n *\n * Fields match `@particle-academy/fancy-sheets` exactly:\n *   - `color: string` (required) — border/outline color\n *   - `backgroundColor?: string` — auto-derived from `color` if omitted\n *   - `label?: string` — small badge in the cell's top-left corner\n */\nexport type SheetsCellHighlight = {\n  /** Border/outline color (any CSS color value). Required. */\n  color: string;\n  /** Background tint; if omitted, derived from `color` at low alpha. */\n  backgroundColor?: string;\n  /** Optional label rendered in a chip on the cell. */\n  label?: string;\n};\n\nexport type SheetsCellHighlightMap = Record<string, SheetsCellHighlight>;\n\nexport type SheetsHighlightOptions = {\n  /** Only include events for this screen (recommended). */\n  screenId?: string;\n  /** Highlight TTL in ms before a hit fades from the map. Default 2200. */\n  ttlMs?: number;\n};\n\n/**\n * useSheetsActivityHighlights — subscribe to the presence registry,\n * produce a CellHighlightMap reflecting recent sheet-bridge activity.\n *\n * Pass the result straight into `<SheetWorkbook highlights={…} />`. Each\n * agent edit pulses in the agent's color for `ttlMs` then fades out.\n *\n * The bridge's target shape is `${sheetId}!${address}` — this hook\n * filters for the currently-active sheet and exposes only its cells.\n *\n *   const highlights = useSheetsActivityHighlights({ screenId: \"deal-sheet\" });\n *   <SheetWorkbook highlights={highlights} … />\n */\nexport function useSheetsActivityHighlights(\n  options: SheetsHighlightOptions = {},\n): SheetsCellHighlightMap {\n  const ttlMs = options.ttlMs ?? 2200;\n  const screenId = options.screenId;\n  const [, force] = useState(0);\n  const hitsRef = useRef<\n    Map<string, { event: AgentActivityEvent; expiresAt: number }>\n  >(new Map());\n\n  useEffect(() => {\n    const off = onActivity((event) => {\n      if (event.target?.kind !== \"sheet\") return;\n      if (screenId && event.target.screenId && event.target.screenId !== screenId) return;\n      const elementId = event.target.elementId;\n      if (!elementId || !elementId.includes(\"!\")) return;\n      hitsRef.current.set(elementId, { event, expiresAt: Date.now() + ttlMs });\n      force((n) => n + 1);\n    });\n    return off;\n  }, [screenId, ttlMs]);\n\n  // Periodic GC — drop expired entries and force a re-render.\n  useEffect(() => {\n    const t = window.setInterval(() => {\n      const now = Date.now();\n      let dirty = false;\n      for (const [k, v] of hitsRef.current) {\n        if (v.expiresAt < now) {\n          hitsRef.current.delete(k);\n          dirty = true;\n        }\n      }\n      if (dirty) force((n) => n + 1);\n    }, 500);\n    return () => window.clearInterval(t);\n  }, []);\n\n  // Re-derived on every render — the listener + GC timer above call\n  // `force` so renders happen exactly when the map changes.\n  const out: SheetsCellHighlightMap = {};\n  for (const [elementId, { event }] of hitsRef.current) {\n    const idx = elementId.indexOf(\"!\");\n    const address = elementId.slice(idx + 1);\n    if (!address) continue;\n    const color = event.agentColor ?? \"#a855f7\";\n    out[address] = {\n      color,\n      backgroundColor: color + \"33\",\n      label: event.agentName ?? event.agentId ?? \"agent\",\n    };\n  }\n  return out;\n}\n"]}

package/dist/sheets-adapter.d.cts

@@ -0,0 +1,119 @@
+import { SheetsBridgeAdapter } from './bridges/sheets.cjs';
+import './tool-host-BQuUygLF.cjs';
+import './types-aOQLTW0E.cjs';
+import './types-CCSBGW9T.cjs';
+
+/**
+ * Shared-session helpers for `@particle-academy/fancy-sheets`.
+ *
+ * fancy-sheets' `SheetWorkbook` is already controlled (`data` + `onChange`).
+ * The two missing pieces for a clean shared-session experience are:
+ *
+ *   1. an adapter object the host can hand to {@link registerSheetsBridge}
+ *      without writing boilerplate, and
+ *   2. a derived `CellHighlightMap` so agent edits visibly pulse on the
+ *      humans' screens — wired from the presence registry's per-bridge
+ *      activity stream.
+ *
+ * These are kept as host-side hooks (not part of the bridge itself) so
+ * agent-integrations keeps zero hard deps on fancy-sheets. The host
+ * imports SheetWorkbook directly and feeds these hooks' outputs into
+ * its props.
+ *
+ *   const wb = useSheetsAdapter(initial, { screenId: "deal-sheet" });
+ *   const highlights = useSheetsActivityHighlights({ screenId: "deal-sheet" });
+ *
+ *   useEffect(() => {
+ *     const bridge = registerSheetsBridge(host, { adapter: wb.adapter });
+ *     return bridge.dispose;
+ *   }, [host, wb.adapter]);
+ *
+ *   <SheetWorkbook
+ *     data={wb.workbook}
+ *     onChange={wb.setWorkbook}
+ *     highlights={highlights}
+ *     onActiveCellChange={wb.onActiveCellChange}
+ *   />
+ */
+type WorkbookLike = {
+    sheets: Array<{
+        id: string;
+        name: string;
+    }>;
+    activeSheetId: string;
+};
+type SheetsAdapterOptions = {
+    /** Tags the bridge's screen id so presence events route correctly. */
+    screenId?: string;
+};
+type UseSheetsAdapterResult<W extends WorkbookLike> = {
+    /** Controlled workbook state. Wire to `<SheetWorkbook data={…} />`. */
+    workbook: W;
+    /** Setter for the controlled state. Wire to `<SheetWorkbook onChange={…} />`. */
+    setWorkbook: (next: W) => void;
+    /** Wire to `<SheetWorkbook onActiveCellChange={…} />` to track focus. */
+    onActiveCellChange: (address: string) => void;
+    /** Stable adapter to hand to `registerSheetsBridge({ adapter })`. */
+    adapter: SheetsBridgeAdapter;
+    /** Imperative: set the active sheet + cell. Mirrors the adapter's hook. */
+    setActiveCell: (sheetId: string, address: string) => void;
+    /** Read-only: the address last focused (any source). */
+    activeCell: string | null;
+};
+/**
+ * useSheetsAdapter — one-liner glue between fancy-sheets' SheetWorkbook
+ * and the sheets bridge.
+ *
+ *   const wb = useSheetsAdapter(initialWorkbook, { screenId: "..." });
+ *
+ *   useEffect(() => registerSheetsBridge(host, { adapter: wb.adapter }).dispose,
+ *             [host, wb.adapter]);
+ *
+ *   <SheetWorkbook
+ *     data={wb.workbook}
+ *     onChange={wb.setWorkbook}
+ *     onActiveCellChange={wb.onActiveCellChange}
+ *   />
+ */
+declare function useSheetsAdapter<W extends WorkbookLike>(initial: W, options?: SheetsAdapterOptions): UseSheetsAdapterResult<W>;
+/**
+ * Mirror of fancy-sheets' `CellHighlight` — structurally identical so the
+ * map returned from {@link useSheetsActivityHighlights} can be passed
+ * straight into `<SheetWorkbook highlights={…} />` without any casts.
+ *
+ * Fields match `@particle-academy/fancy-sheets` exactly:
+ *   - `color: string` (required) — border/outline color
+ *   - `backgroundColor?: string` — auto-derived from `color` if omitted
+ *   - `label?: string` — small badge in the cell's top-left corner
+ */
+type SheetsCellHighlight = {
+    /** Border/outline color (any CSS color value). Required. */
+    color: string;
+    /** Background tint; if omitted, derived from `color` at low alpha. */
+    backgroundColor?: string;
+    /** Optional label rendered in a chip on the cell. */
+    label?: string;
+};
+type SheetsCellHighlightMap = Record<string, SheetsCellHighlight>;
+type SheetsHighlightOptions = {
+    /** Only include events for this screen (recommended). */
+    screenId?: string;
+    /** Highlight TTL in ms before a hit fades from the map. Default 2200. */
+    ttlMs?: number;
+};
+/**
+ * useSheetsActivityHighlights — subscribe to the presence registry,
+ * produce a CellHighlightMap reflecting recent sheet-bridge activity.
+ *
+ * Pass the result straight into `<SheetWorkbook highlights={…} />`. Each
+ * agent edit pulses in the agent's color for `ttlMs` then fades out.
+ *
+ * The bridge's target shape is `${sheetId}!${address}` — this hook
+ * filters for the currently-active sheet and exposes only its cells.
+ *
+ *   const highlights = useSheetsActivityHighlights({ screenId: "deal-sheet" });
+ *   <SheetWorkbook highlights={highlights} … />
+ */
+declare function useSheetsActivityHighlights(options?: SheetsHighlightOptions): SheetsCellHighlightMap;
+
+export { type SheetsAdapterOptions, type SheetsCellHighlight, type SheetsCellHighlightMap, type SheetsHighlightOptions, type UseSheetsAdapterResult, type WorkbookLike, useSheetsActivityHighlights, useSheetsAdapter };

package/dist/sheets-adapter.d.ts

@@ -0,0 +1,119 @@
+import { SheetsBridgeAdapter } from './bridges/sheets.js';
+import './tool-host-C8JMMGYq.js';
+import './types-aOQLTW0E.js';
+import './types-DIVNcIQO.js';
+
+/**
+ * Shared-session helpers for `@particle-academy/fancy-sheets`.
+ *
+ * fancy-sheets' `SheetWorkbook` is already controlled (`data` + `onChange`).
+ * The two missing pieces for a clean shared-session experience are:
+ *
+ *   1. an adapter object the host can hand to {@link registerSheetsBridge}
+ *      without writing boilerplate, and
+ *   2. a derived `CellHighlightMap` so agent edits visibly pulse on the
+ *      humans' screens — wired from the presence registry's per-bridge
+ *      activity stream.
+ *
+ * These are kept as host-side hooks (not part of the bridge itself) so
+ * agent-integrations keeps zero hard deps on fancy-sheets. The host
+ * imports SheetWorkbook directly and feeds these hooks' outputs into
+ * its props.
+ *
+ *   const wb = useSheetsAdapter(initial, { screenId: "deal-sheet" });
+ *   const highlights = useSheetsActivityHighlights({ screenId: "deal-sheet" });
+ *
+ *   useEffect(() => {
+ *     const bridge = registerSheetsBridge(host, { adapter: wb.adapter });
+ *     return bridge.dispose;
+ *   }, [host, wb.adapter]);
+ *
+ *   <SheetWorkbook
+ *     data={wb.workbook}
+ *     onChange={wb.setWorkbook}
+ *     highlights={highlights}
+ *     onActiveCellChange={wb.onActiveCellChange}
+ *   />
+ */
+type WorkbookLike = {
+    sheets: Array<{
+        id: string;
+        name: string;
+    }>;
+    activeSheetId: string;
+};
+type SheetsAdapterOptions = {
+    /** Tags the bridge's screen id so presence events route correctly. */
+    screenId?: string;
+};
+type UseSheetsAdapterResult<W extends WorkbookLike> = {
+    /** Controlled workbook state. Wire to `<SheetWorkbook data={…} />`. */
+    workbook: W;
+    /** Setter for the controlled state. Wire to `<SheetWorkbook onChange={…} />`. */
+    setWorkbook: (next: W) => void;
+    /** Wire to `<SheetWorkbook onActiveCellChange={…} />` to track focus. */
+    onActiveCellChange: (address: string) => void;
+    /** Stable adapter to hand to `registerSheetsBridge({ adapter })`. */
+    adapter: SheetsBridgeAdapter;
+    /** Imperative: set the active sheet + cell. Mirrors the adapter's hook. */
+    setActiveCell: (sheetId: string, address: string) => void;
+    /** Read-only: the address last focused (any source). */
+    activeCell: string | null;
+};
+/**
+ * useSheetsAdapter — one-liner glue between fancy-sheets' SheetWorkbook
+ * and the sheets bridge.
+ *
+ *   const wb = useSheetsAdapter(initialWorkbook, { screenId: "..." });
+ *
+ *   useEffect(() => registerSheetsBridge(host, { adapter: wb.adapter }).dispose,
+ *             [host, wb.adapter]);
+ *
+ *   <SheetWorkbook
+ *     data={wb.workbook}
+ *     onChange={wb.setWorkbook}
+ *     onActiveCellChange={wb.onActiveCellChange}
+ *   />
+ */
+declare function useSheetsAdapter<W extends WorkbookLike>(initial: W, options?: SheetsAdapterOptions): UseSheetsAdapterResult<W>;
+/**
+ * Mirror of fancy-sheets' `CellHighlight` — structurally identical so the
+ * map returned from {@link useSheetsActivityHighlights} can be passed
+ * straight into `<SheetWorkbook highlights={…} />` without any casts.
+ *
+ * Fields match `@particle-academy/fancy-sheets` exactly:
+ *   - `color: string` (required) — border/outline color
+ *   - `backgroundColor?: string` — auto-derived from `color` if omitted
+ *   - `label?: string` — small badge in the cell's top-left corner
+ */
+type SheetsCellHighlight = {
+    /** Border/outline color (any CSS color value). Required. */
+    color: string;
+    /** Background tint; if omitted, derived from `color` at low alpha. */
+    backgroundColor?: string;
+    /** Optional label rendered in a chip on the cell. */
+    label?: string;
+};
+type SheetsCellHighlightMap = Record<string, SheetsCellHighlight>;
+type SheetsHighlightOptions = {
+    /** Only include events for this screen (recommended). */
+    screenId?: string;
+    /** Highlight TTL in ms before a hit fades from the map. Default 2200. */
+    ttlMs?: number;
+};
+/**
+ * useSheetsActivityHighlights — subscribe to the presence registry,
+ * produce a CellHighlightMap reflecting recent sheet-bridge activity.
+ *
+ * Pass the result straight into `<SheetWorkbook highlights={…} />`. Each
+ * agent edit pulses in the agent's color for `ttlMs` then fades out.
+ *
+ * The bridge's target shape is `${sheetId}!${address}` — this hook
+ * filters for the currently-active sheet and exposes only its cells.
+ *
+ *   const highlights = useSheetsActivityHighlights({ screenId: "deal-sheet" });
+ *   <SheetWorkbook highlights={highlights} … />
+ */
+declare function useSheetsActivityHighlights(options?: SheetsHighlightOptions): SheetsCellHighlightMap;
+
+export { type SheetsAdapterOptions, type SheetsCellHighlight, type SheetsCellHighlightMap, type SheetsHighlightOptions, type UseSheetsAdapterResult, type WorkbookLike, useSheetsActivityHighlights, useSheetsAdapter };

package/dist/sheets-adapter.js

@@ -0,0 +1,4 @@
+export { useSheetsActivityHighlights, useSheetsAdapter } from './chunk-5XELJIJR.js';
+import './chunk-JU2N4KK6.js';
+//# sourceMappingURL=sheets-adapter.js.map
+//# sourceMappingURL=sheets-adapter.js.map

package/dist/sheets-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"sheets-adapter.js"}

package/dist/token-CrJF76oH.d.cts

@@ -0,0 +1,34 @@
+/**
+ * Session-token utilities. The token is a high-entropy secret; possession
+ * grants read/write on the session. We don't HMAC frames — frames carry
+ * the token directly (which is fine for in-process / same-origin / TLS
+ * transports). For lower-trust transports, host apps can layer signing
+ * on top of the BroadcastChannelTransport.
+ */
+type SessionDescriptor = {
+    /** Stable session identifier. Channel name = `fai:share:${id}`. */
+    id: string;
+    /** Secret token. Treat as a password — anyone with it can read/write. */
+    token: string;
+    /** Pretty hash for display (first 8 chars of token). */
+    display: string;
+};
+declare function createSessionDescriptor(): SessionDescriptor;
+declare function describeSession(id: string, token: string): SessionDescriptor;
+/** Build the shareable URL for the current page (preserves path, adds session+token). */
+declare function buildShareUrl(descriptor: SessionDescriptor, baseUrl?: string): string;
+/** Build the JSON config form (suitable for Claude Desktop / Cline / etc.). */
+declare function buildShareConfig(descriptor: SessionDescriptor, transport?: string): {
+    name: string;
+    transport: string;
+    session: string;
+    token: string;
+    channel: string;
+    protocol_version: string;
+};
+/** Read session descriptor from current URL, or null if not a shared link. */
+declare function readSessionFromUrl(): SessionDescriptor | null;
+/** Constant-time string compare so a mismatched token leaks no timing info. */
+declare function constantTimeEqual(a: string, b: string): boolean;
+
+export { type SessionDescriptor as S, buildShareUrl as a, buildShareConfig as b, createSessionDescriptor as c, describeSession as d, constantTimeEqual as e, readSessionFromUrl as r };

package/dist/token-CrJF76oH.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Session-token utilities. The token is a high-entropy secret; possession
+ * grants read/write on the session. We don't HMAC frames — frames carry
+ * the token directly (which is fine for in-process / same-origin / TLS
+ * transports). For lower-trust transports, host apps can layer signing
+ * on top of the BroadcastChannelTransport.
+ */
+type SessionDescriptor = {
+    /** Stable session identifier. Channel name = `fai:share:${id}`. */
+    id: string;
+    /** Secret token. Treat as a password — anyone with it can read/write. */
+    token: string;
+    /** Pretty hash for display (first 8 chars of token). */
+    display: string;
+};
+declare function createSessionDescriptor(): SessionDescriptor;
+declare function describeSession(id: string, token: string): SessionDescriptor;
+/** Build the shareable URL for the current page (preserves path, adds session+token). */
+declare function buildShareUrl(descriptor: SessionDescriptor, baseUrl?: string): string;
+/** Build the JSON config form (suitable for Claude Desktop / Cline / etc.). */
+declare function buildShareConfig(descriptor: SessionDescriptor, transport?: string): {
+    name: string;
+    transport: string;
+    session: string;
+    token: string;
+    channel: string;
+    protocol_version: string;
+};
+/** Read session descriptor from current URL, or null if not a shared link. */
+declare function readSessionFromUrl(): SessionDescriptor | null;
+/** Constant-time string compare so a mismatched token leaks no timing info. */
+declare function constantTimeEqual(a: string, b: string): boolean;
+
+export { type SessionDescriptor as S, buildShareUrl as a, buildShareConfig as b, createSessionDescriptor as c, describeSession as d, constantTimeEqual as e, readSessionFromUrl as r };

package/dist/tool-host-BQuUygLF.d.cts

@@ -0,0 +1,60 @@
+import { T as ToolDefinition, b as ToolHandler, R as RegisteredTool, c as JsonObject, C as CallToolResult } from './types-aOQLTW0E.cjs';
+
+/**
+ * ToolHost — the minimal surface a bridge needs to register its tools.
+ *
+ * Bridges (whiteboard, flow, sheets, code, charts, screens, scene, form)
+ * speak only through this interface. The MCP server implements it
+ * alongside its transport / JSON-RPC duties, and the standalone
+ * {@link ToolRegistry} implements it for in-process agents that don't
+ * need any of MCP's wire framing.
+ *
+ * Net effect: every bridge works equally well behind an MCP server
+ * (browser ↔ external agents over SSE) or behind a plain registry
+ * (in-process agent calling `host.callTool("sheet_set_cell", { … })`).
+ */
+interface ToolHost {
+    /** Register a tool. Returns a disposer that unregisters it. */
+    registerTool(definition: ToolDefinition, handler: ToolHandler): () => void;
+    /** Look up an already-registered tool's definition + handler, or null. */
+    getTool(name: string): RegisteredTool | null;
+    /** Snapshot of all currently-registered tool definitions. */
+    listTools(): ToolDefinition[];
+    /**
+     * Invoke a registered tool directly, bypassing any transport layer.
+     * Throws if no tool is registered under `name`.
+     *
+     * This is the single entry point in-process agents use to drive the
+     * surface — no JSON-RPC framing, no transport plumbing.
+     */
+    callTool(name: string, args?: JsonObject): Promise<CallToolResult>;
+}
+/**
+ * Standalone in-memory ToolHost. Use this when no MCP server is needed —
+ * e.g. an in-process agent that just wants to register the same bridges
+ * and call them directly.
+ *
+ * Example:
+ *
+ *   const host = new ToolRegistry();
+ *   registerSheetsBridge(host, { adapter });
+ *   const result = await host.callTool("sheet_set_cell", { address: "B3", value: 42 });
+ *
+ * Pair with a MicroMcpServer in the same app to expose the same tools
+ * to remote agents over SSE while in-process agents still get
+ * zero-overhead direct calls.
+ */
+declare class ToolRegistry implements ToolHost {
+    protected readonly tools: Map<string, RegisteredTool>;
+    registerTool(definition: ToolDefinition, handler: ToolHandler): () => void;
+    getTool(name: string): RegisteredTool | null;
+    listTools(): ToolDefinition[];
+    callTool(name: string, args?: JsonObject): Promise<CallToolResult>;
+    /**
+     * Hook for subclasses (e.g. MicroMcpServer) to notify subscribers
+     * when the tool catalog changes. Default no-op.
+     */
+    protected onToolsChanged(): void;
+}
+
+export { type ToolHost as T, ToolRegistry as a };

package/dist/tool-host-C8JMMGYq.d.ts

@@ -0,0 +1,60 @@
+import { T as ToolDefinition, b as ToolHandler, R as RegisteredTool, c as JsonObject, C as CallToolResult } from './types-aOQLTW0E.js';
+
+/**
+ * ToolHost — the minimal surface a bridge needs to register its tools.
+ *
+ * Bridges (whiteboard, flow, sheets, code, charts, screens, scene, form)
+ * speak only through this interface. The MCP server implements it
+ * alongside its transport / JSON-RPC duties, and the standalone
+ * {@link ToolRegistry} implements it for in-process agents that don't
+ * need any of MCP's wire framing.
+ *
+ * Net effect: every bridge works equally well behind an MCP server
+ * (browser ↔ external agents over SSE) or behind a plain registry
+ * (in-process agent calling `host.callTool("sheet_set_cell", { … })`).
+ */
+interface ToolHost {
+    /** Register a tool. Returns a disposer that unregisters it. */
+    registerTool(definition: ToolDefinition, handler: ToolHandler): () => void;
+    /** Look up an already-registered tool's definition + handler, or null. */
+    getTool(name: string): RegisteredTool | null;
+    /** Snapshot of all currently-registered tool definitions. */
+    listTools(): ToolDefinition[];
+    /**
+     * Invoke a registered tool directly, bypassing any transport layer.
+     * Throws if no tool is registered under `name`.
+     *
+     * This is the single entry point in-process agents use to drive the
+     * surface — no JSON-RPC framing, no transport plumbing.
+     */
+    callTool(name: string, args?: JsonObject): Promise<CallToolResult>;
+}
+/**
+ * Standalone in-memory ToolHost. Use this when no MCP server is needed —
+ * e.g. an in-process agent that just wants to register the same bridges
+ * and call them directly.
+ *
+ * Example:
+ *
+ *   const host = new ToolRegistry();
+ *   registerSheetsBridge(host, { adapter });
+ *   const result = await host.callTool("sheet_set_cell", { address: "B3", value: 42 });
+ *
+ * Pair with a MicroMcpServer in the same app to expose the same tools
+ * to remote agents over SSE while in-process agents still get
+ * zero-overhead direct calls.
+ */
+declare class ToolRegistry implements ToolHost {
+    protected readonly tools: Map<string, RegisteredTool>;
+    registerTool(definition: ToolDefinition, handler: ToolHandler): () => void;
+    getTool(name: string): RegisteredTool | null;
+    listTools(): ToolDefinition[];
+    callTool(name: string, args?: JsonObject): Promise<CallToolResult>;
+    /**
+     * Hook for subclasses (e.g. MicroMcpServer) to notify subscribers
+     * when the tool catalog changes. Default no-op.
+     */
+    protected onToolsChanged(): void;
+}
+
+export { type ToolHost as T, ToolRegistry as a };

package/dist/{types-DXKpLuia.d.ts → types-CCSBGW9T.d.cts}

@@ -1,4 +1,4 @@
-import { M as MicroMcpServer } from './server-BJu_AMH3.js';
+import { T as ToolHost } from './tool-host-BQuUygLF.cjs';
 
 /**
  * Bridge — registers a cohesive set of MCP tools/resources for a single
@@ -13,6 +13,6 @@ type Bridge = {
     /** Disposes the bridge. Must remove every tool it registered. */
     dispose: () => void;
 };
-type BridgeFactory<TOptions> = (server: MicroMcpServer, options: TOptions) => Bridge;
+type BridgeFactory<TOptions> = (host: ToolHost, options: TOptions) => Bridge;
 
 export type { Bridge as B, BridgeFactory as a };

package/dist/{types-Bf1ZoGmI.d.cts → types-DIVNcIQO.d.ts}

@@ -1,4 +1,4 @@
-import { M as MicroMcpServer } from './server-si-VvFxI.cjs';
+import { T as ToolHost } from './tool-host-C8JMMGYq.js';
 
 /**
  * Bridge — registers a cohesive set of MCP tools/resources for a single
@@ -13,6 +13,6 @@ type Bridge = {
     /** Disposes the bridge. Must remove every tool it registered. */
     dispose: () => void;
 };
-type BridgeFactory<TOptions> = (server: MicroMcpServer, options: TOptions) => Bridge;
+type BridgeFactory<TOptions> = (host: ToolHost, options: TOptions) => Bridge;
 
 export type { Bridge as B, BridgeFactory as a };

package/dist/{types-DksGd5Y7.d.cts → types-aOQLTW0E.d.cts}

@@ -109,4 +109,4 @@ type RegisteredTool = {
 };
 declare const MCP_PROTOCOL_VERSION = "2025-06-18";
 
-export { type CallToolResult as C, type InitializeResult as I, type JsonRpcMessage as J, MCP_PROTOCOL_VERSION as M, type RegisteredTool as R, type ServerInfo as S, type ToolDefinition as T, type ServerCapabilities as a, type ToolHandler as b, type ContentBlock as c, type JsonObject as d, type JsonRpcNotification as e, type JsonRpcRequest as f, type JsonValue as g, JSONRPC_INTERNAL_ERROR as h, JSONRPC_INVALID_PARAMS as i, JSONRPC_INVALID_REQUEST as j, JSONRPC_METHOD_NOT_FOUND as k, JSONRPC_PARSE_ERROR as l, type JsonRpcError as m, type JsonRpcId as n, type JsonRpcSuccess as o, type ToolInputSchema as p };
+export { type CallToolResult as C, type InitializeResult as I, type JsonRpcMessage as J, MCP_PROTOCOL_VERSION as M, type RegisteredTool as R, type ServerInfo as S, type ToolDefinition as T, type ServerCapabilities as a, type ToolHandler as b, type JsonObject as c, type ContentBlock as d, type JsonRpcNotification as e, type JsonRpcRequest as f, type JsonValue as g, JSONRPC_INTERNAL_ERROR as h, JSONRPC_INVALID_PARAMS as i, JSONRPC_INVALID_REQUEST as j, JSONRPC_METHOD_NOT_FOUND as k, JSONRPC_PARSE_ERROR as l, type JsonRpcError as m, type JsonRpcId as n, type JsonRpcSuccess as o, type ToolInputSchema as p };

package/dist/{types-DksGd5Y7.d.ts → types-aOQLTW0E.d.ts}

@@ -109,4 +109,4 @@ type RegisteredTool = {
 };
 declare const MCP_PROTOCOL_VERSION = "2025-06-18";
 
-export { type CallToolResult as C, type InitializeResult as I, type JsonRpcMessage as J, MCP_PROTOCOL_VERSION as M, type RegisteredTool as R, type ServerInfo as S, type ToolDefinition as T, type ServerCapabilities as a, type ToolHandler as b, type ContentBlock as c, type JsonObject as d, type JsonRpcNotification as e, type JsonRpcRequest as f, type JsonValue as g, JSONRPC_INTERNAL_ERROR as h, JSONRPC_INVALID_PARAMS as i, JSONRPC_INVALID_REQUEST as j, JSONRPC_METHOD_NOT_FOUND as k, JSONRPC_PARSE_ERROR as l, type JsonRpcError as m, type JsonRpcId as n, type JsonRpcSuccess as o, type ToolInputSchema as p };
+export { type CallToolResult as C, type InitializeResult as I, type JsonRpcMessage as J, MCP_PROTOCOL_VERSION as M, type RegisteredTool as R, type ServerInfo as S, type ToolDefinition as T, type ServerCapabilities as a, type ToolHandler as b, type JsonObject as c, type ContentBlock as d, type JsonRpcNotification as e, type JsonRpcRequest as f, type JsonValue as g, JSONRPC_INTERNAL_ERROR as h, JSONRPC_INVALID_PARAMS as i, JSONRPC_INVALID_REQUEST as j, JSONRPC_METHOD_NOT_FOUND as k, JSONRPC_PARSE_ERROR as l, type JsonRpcError as m, type JsonRpcId as n, type JsonRpcSuccess as o, type ToolInputSchema as p };

package/dist/undo/index.d.cts

@@ -1,5 +1,5 @@
-import { M as MicroMcpServer } from '../server-si-VvFxI.cjs';
-import '../types-DksGd5Y7.cjs';
+import { T as ToolHost } from '../tool-host-BQuUygLF.cjs';
+import '../types-aOQLTW0E.cjs';
 
 /**
  * Generic undo/redo stack keyed by `agentId`. Each entry holds:
@@ -48,12 +48,12 @@ type UndoToolsOptions = {
  * ensureUndoToolsRegistered — bridges call this on construction. Safe to
  * call repeatedly with the same server; subsequent calls are no-ops.
  */
-declare function ensureUndoToolsRegistered(server: MicroMcpServer, options?: UndoToolsOptions): void;
+declare function ensureUndoToolsRegistered(host: ToolHost, options?: UndoToolsOptions): void;
 /**
  * registerUndoTools — add agent_undo / agent_redo / agent_history to the
  * server. Returns a disposer that unregisters all three.
  */
-declare function registerUndoTools(server: MicroMcpServer, options?: UndoToolsOptions): () => void;
+declare function registerUndoTools(host: ToolHost, options?: UndoToolsOptions): () => void;
 
 /**
  * useUndoStack — minimal React snapshot of an agent's history. Polls every