@buoy-gg/external-sync 7.0.17 → 7.0.18

package/lib/commonjs/attachDeviceSync.js

@@ -0,0 +1,209 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.attachDeviceSync = attachDeviceSync;
+var _logger = require("./utils/logger");
+var _emitBudget = require("./emitBudget");
+var _types = require("./types");
+const LOG = "[ExternalSync]";
+
+/** Minimal socket surface the device-side bridge needs. */
+
+/**
+ * "capture" records into the tool's store without pushing snapshots; "stream"
+ * also emits on every change. See `DevToolWatchMessage.stream`.
+ */
+
+/**
+ * Device-side sync bridge (no React). A tool's adapter is only subscribed
+ * while a dashboard is watching it (`devtool-watch`).
+ */
+function attachDeviceSync({
+  socket,
+  deviceId,
+  getTools,
+  watched,
+  throttleMs = 200,
+  enableLogs = false
+}) {
+  const unsubs = new Map();
+  const lastEmit = {};
+  const timers = {};
+  const isForThisDevice = targetDeviceId => targetDeviceId === "All" || targetDeviceId === deviceId;
+  const safeEmit = (event, message) => {
+    try {
+      socket.emit(event, message);
+    } catch (error) {
+      (0, _logger.log)(`${LOG} Failed to emit "${event}": ${error}. Payload must be JSON-serializable.`, enableLogs, "error");
+    }
+  };
+  const warnedOversized = new Set();
+  const sendSnapshot = toolId => {
+    const tool = getTools()[toolId];
+    if (!tool) return;
+    lastEmit[toolId] = Date.now();
+    const payload = tool.getSnapshot();
+    const {
+      over,
+      approxBytes
+    } = (0, _emitBudget.approxSizeOver)(payload, _emitBudget.MAX_SNAPSHOT_EMIT_BYTES);
+    if (over) {
+      if (!warnedOversized.has(toolId)) {
+        warnedOversized.add(toolId);
+        console.warn(`${LOG} "${toolId}" snapshot ≈${(approxBytes / 1e6).toFixed(1)}MB exceeds the ${_emitBudget.MAX_SNAPSHOT_EMIT_BYTES / 1e6}MB sync budget — dropped (dashboard will be stale for this tool). The adapter should ship a wire-form snapshot (summaries + on-demand detail).`);
+      }
+      return;
+    }
+    const message = {
+      toolId,
+      persistentDeviceId: deviceId,
+      timestamp: lastEmit[toolId],
+      version: tool.version,
+      kind: "snapshot",
+      payload
+    };
+    safeEmit("devtool-sync", message);
+  };
+  const scheduleSnapshot = toolId => {
+    if (timers[toolId]) return;
+    const elapsed = Date.now() - (lastEmit[toolId] ?? 0);
+    if (elapsed >= throttleMs) {
+      sendSnapshot(toolId);
+      return;
+    }
+    timers[toolId] = setTimeout(() => {
+      delete timers[toolId];
+      sendSnapshot(toolId);
+    }, throttleMs - elapsed);
+  };
+
+  /** The mode each currently-subscribed tool is wired for. */
+  const activeModes = new Map();
+  const watchTool = (toolId, mode) => {
+    const tool = getTools()[toolId];
+    if (!tool) return;
+    if (unsubs.has(toolId)) {
+      if (activeModes.get(toolId) === mode) return;
+      // Mode changed (a streaming dashboard left, or arrived) — rewire, but
+      // do NOT drop the subscription in between: releasing it would take the
+      // store's subscriber count to 0 and stop capture mid-flight.
+      const previous = unsubs.get(toolId);
+      unsubs.set(toolId, tool.subscribe(mode === "stream" ? () => scheduleSnapshot(toolId) : () => {}));
+      activeModes.set(toolId, mode);
+      previous?.();
+      (0, _logger.log)(`${LOG} "${toolId}" watch mode → ${mode}`, enableLogs);
+      return;
+    }
+    unsubs.set(toolId, tool.subscribe(mode === "stream" ? () => scheduleSnapshot(toolId) : () => {}));
+    activeModes.set(toolId, mode);
+    (0, _logger.log)(`${LOG} Watching "${toolId}" (${mode})`, enableLogs);
+  };
+  const unwatchTool = toolId => {
+    unsubs.get(toolId)?.();
+    unsubs.delete(toolId);
+    activeModes.delete(toolId);
+    if (timers[toolId]) {
+      clearTimeout(timers[toolId]);
+      delete timers[toolId];
+    }
+    (0, _logger.log)(`${LOG} Stopped watching "${toolId}"`, enableLogs);
+  };
+  const sendCapabilities = () => {
+    const message = {
+      persistentDeviceId: deviceId,
+      protocolVersion: _types.SYNC_PROTOCOL_VERSION,
+      tools: Object.entries(getTools()).map(([toolId, tool]) => ({
+        toolId,
+        version: tool.version,
+        actions: Object.keys(tool.actions ?? {})
+      }))
+    };
+    safeEmit("devtool-capabilities", message);
+  };
+  const handleWatch = message => {
+    if (!isForThisDevice(message.targetDeviceId)) return;
+    if (message.watching) {
+      // `stream` is only trustworthy once a broker has merged every
+      // dashboard's request (see DevToolWatchMessage.consolidated). Without
+      // that, an unmerged capture request could quiet a dashboard that is
+      // actively painting, so default to streaming.
+      const mode = message.consolidated === true && message.stream === false ? "capture" : "stream";
+      watched.set(message.toolId, mode);
+      watchTool(message.toolId, mode);
+      // Only a streaming audience gets the priming snapshot. A capture-only
+      // client reads with `request-devtool-state` when it actually wants one;
+      // pushing here would hand it the very payload it asked not to receive.
+      if (mode === "stream") sendSnapshot(message.toolId);
+    } else {
+      watched.delete(message.toolId);
+      unwatchTool(message.toolId);
+    }
+  };
+  const handleRequest = message => {
+    if (!isForThisDevice(message.targetDeviceId)) return;
+    sendSnapshot(message.toolId);
+  };
+  const handleAction = async message => {
+    if (!isForThisDevice(message.targetDeviceId)) return;
+    const {
+      requestId,
+      toolId,
+      action,
+      params
+    } = message;
+    const result = {
+      requestId,
+      toolId,
+      action,
+      persistentDeviceId: deviceId,
+      timestamp: Date.now(),
+      ok: false
+    };
+    const tool = getTools()[toolId];
+    const fn = tool?.actions?.[action];
+    if (!fn) {
+      result.error = tool ? `Unknown action "${action}" on tool "${toolId}"` : `Unknown tool "${toolId}"`;
+      safeEmit("devtool-action-result", result);
+      return;
+    }
+    try {
+      result.result = await fn(params);
+      result.ok = true;
+    } catch (error) {
+      result.error = error instanceof Error ? error.message : String(error);
+    }
+    if (result.ok) {
+      const {
+        over,
+        approxBytes
+      } = (0, _emitBudget.approxSizeOver)(result.result, _emitBudget.MAX_ACTION_RESULT_BYTES);
+      if (over) {
+        result.ok = false;
+        result.result = undefined;
+        result.error = `Result ≈${(approxBytes / 1e6).toFixed(1)}MB exceeds the ${_emitBudget.MAX_ACTION_RESULT_BYTES / 1e6}MB sync budget. Narrow the request (e.g. includeValues:false, a limit, or a more specific action).`;
+      }
+    }
+    result.timestamp = Date.now();
+    safeEmit("devtool-action-result", result);
+  };
+  const handleConnect = () => {
+    sendCapabilities();
+  };
+  if (socket.connected) sendCapabilities();
+  for (const [toolId, mode] of watched) {
+    if (getTools()[toolId]) watchTool(toolId, mode);
+  }
+  socket.on("connect", handleConnect);
+  socket.on("devtool-watch", handleWatch);
+  socket.on("request-devtool-state", handleRequest);
+  socket.on("devtool-action", handleAction);
+  return () => {
+    socket.off("connect", handleConnect);
+    socket.off("devtool-watch", handleWatch);
+    socket.off("request-devtool-state", handleRequest);
+    socket.off("devtool-action", handleAction);
+    for (const toolId of [...unsubs.keys()]) unwatchTool(toolId);
+  };
+}

package/lib/commonjs/emitBudget.js

@@ -0,0 +1,57 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.MAX_SNAPSHOT_EMIT_BYTES = exports.MAX_ACTION_RESULT_BYTES = void 0;
+exports.approxSizeOver = approxSizeOver;
+/**
+ * Emit-layer byte budgets — the choke-point guard.
+ *
+ * Every adapter's snapshot and every action result funnels through
+ * socket.emit, whose serializer walks the ENTIRE payload synchronously on
+ * the JS thread (and JSON.stringify does not honor structural sharing).
+ * Per-adapter guards get missed — the redux adapter shipping raw state
+ * trees froze and native-OOM-crashed enterprise apps whenever a dashboard
+ * was connected. One budget here closes every adapter's hole at once:
+ * oversized payloads are dropped (snapshots) or replaced with an error
+ * (action results) instead of being serialized.
+ *
+ * The estimator is O(limit) — early-abort walk, O(1) for giant strings —
+ * never O(payload). Copied per-package by design (see events/redux copies).
+ */
+
+/** Max approx bytes for one tool snapshot emit. */
+const MAX_SNAPSHOT_EMIT_BYTES = exports.MAX_SNAPSHOT_EMIT_BYTES = 2 * 1024 * 1024;
+/** Max approx bytes for one action-result emit (explicit requests get more). */
+const MAX_ACTION_RESULT_BYTES = exports.MAX_ACTION_RESULT_BYTES = 8 * 1024 * 1024;
+function approxSizeOver(value, limit) {
+  let bytes = 0;
+  const stack = [value];
+  const seen = new Set();
+  while (stack.length > 0) {
+    if (bytes > limit) return {
+      over: true,
+      approxBytes: bytes
+    };
+    const v = stack.pop();
+    if (v === null || v === undefined) bytes += 4;else if (typeof v === "string") bytes += v.length + 2;else if (typeof v === "number") bytes += 8;else if (typeof v === "boolean") bytes += 5;else if (typeof v === "object") {
+      if (seen.has(v)) continue;
+      seen.add(v);
+      if (Array.isArray(v)) {
+        bytes += 2 + v.length;
+        for (let i = 0; i < v.length; i++) stack.push(v[i]);
+      } else {
+        bytes += 2;
+        for (const k in v) {
+          bytes += k.length + 4;
+          stack.push(v[k]);
+        }
+      }
+    } else bytes += 4;
+  }
+  return {
+    over: bytes > limit,
+    approxBytes: bytes
+  };
+}

package/lib/commonjs/types.js

@@ -61,7 +61,20 @@ const SYNC_PROTOCOL_VERSION = exports.SYNC_PROTOCOL_VERSION = 1;
 // DASHBOARD -> DEVICE MESSAGES
 // ============================================================
 
-/** Server-consolidated signal that a tool gained/lost its audience. */
+/**
+ * Server-consolidated signal that a tool gained/lost its audience.
+ *
+ * `watching` arms CAPTURE: the device subscribes to the tool, which is what
+ * makes its store start recording. `stream` decides whether the device also
+ * PUSHES a snapshot on every change (throttled), which is the expensive half —
+ * it serializes the whole payload on the JS thread ~5x/sec.
+ *
+ * Those are separate because their audiences are: a dashboard renders every
+ * snapshot, so it wants both. A request/response client (MCP) reads on demand
+ * via `request-devtool-state` and would throw the stream away — but it still
+ * needs the device to be RECORDING between its reads, or it only ever sees an
+ * empty list and concludes the app made no requests.
+ */
 
 /** Explicit request for a tool's current state (works even while unwatched). */
 

package/lib/commonjs/useExternalSync.js

@@ -5,61 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.useExternalSync = useExternalSync;
 var _react = require("react");
-var _logger = require("./utils/logger");
-var _types = require("./types");
-const LOG = "[ExternalSync]";
-
-// ==========================================================================
-// Emit-layer byte budgets — the choke-point guard.
-//
-// Every adapter's snapshot and every action result funnels through
-// socket.emit, whose serializer walks the ENTIRE payload synchronously on
-// the JS thread (and JSON.stringify does not honor structural sharing).
-// Per-adapter guards get missed — the redux adapter shipping raw state
-// trees froze and native-OOM-crashed enterprise apps whenever a dashboard
-// was connected. One budget here closes every adapter's hole at once:
-// oversized payloads are dropped (snapshots) or replaced with an error
-// (action results) instead of being serialized.
-//
-// The estimator is O(limit) — early-abort walk, O(1) for giant strings —
-// never O(payload). Copied per-package by design (see events/redux copies).
-// ==========================================================================
-
-/** Max approx bytes for one tool snapshot emit. */
-const MAX_SNAPSHOT_EMIT_BYTES = 2 * 1024 * 1024;
-/** Max approx bytes for one action-result emit (explicit requests get more). */
-const MAX_ACTION_RESULT_BYTES = 8 * 1024 * 1024;
-function approxSizeOver(value, limit) {
-  let bytes = 0;
-  const stack = [value];
-  const seen = new Set();
-  while (stack.length > 0) {
-    if (bytes > limit) return {
-      over: true,
-      approxBytes: bytes
-    };
-    const v = stack.pop();
-    if (v === null || v === undefined) bytes += 4;else if (typeof v === "string") bytes += v.length + 2;else if (typeof v === "number") bytes += 8;else if (typeof v === "boolean") bytes += 5;else if (typeof v === "object") {
-      if (seen.has(v)) continue;
-      seen.add(v);
-      if (Array.isArray(v)) {
-        bytes += 2 + v.length;
-        for (let i = 0; i < v.length; i++) stack.push(v[i]);
-      } else {
-        bytes += 2;
-        for (const k in v) {
-          bytes += k.length + 4;
-          stack.push(v[k]);
-        }
-      }
-    } else bytes += 4;
-  }
-  return {
-    over: bytes > limit,
-    approxBytes: bytes
-  };
-}
-
+var _attachDeviceSync = require("./attachDeviceSync");
 /**
  * Device-side sync bridge: syncs any number of dev tools to the desktop
  * dashboard and executes actions invoked remotely.
@@ -100,183 +46,21 @@ function useExternalSync({
 
   // Watch state persists across effect re-runs (e.g. when tools are
   // added/removed) so an already-watched tool stays subscribed.
-  const watchedRef = (0, _react.useRef)(new Set());
+  const watchedRef = (0, _react.useRef)(new Map());
 
   // Re-run the effect only when tools are added/removed, not on every
   // object-reference change.
   const toolIdsKey = Object.keys(tools).sort().join(",");
   (0, _react.useEffect)(() => {
     if (!socket || !deviceId || !enabled) return;
-    const unsubs = new Map();
-    const lastEmit = {};
-    const timers = {};
-    const isForThisDevice = targetDeviceId => targetDeviceId === "All" || targetDeviceId === deviceId;
-    const safeEmit = (event, message) => {
-      try {
-        socket.emit(event, message);
-      } catch (error) {
-        (0, _logger.log)(`${LOG} Failed to emit "${event}": ${error}. Payload must be JSON-serializable.`, enableLogs, "error");
-      }
-    };
-
-    // One warning per tool per session — the drop repeats every snapshot.
-    const warnedOversized = new Set();
-    const sendSnapshot = toolId => {
-      const tool = toolsRef.current[toolId];
-      if (!tool) return;
-      lastEmit[toolId] = Date.now();
-      const payload = tool.getSnapshot();
-
-      // Emit-layer budget: never hand an unbounded payload to the socket
-      // serializer. A dropped snapshot means a stale dashboard panel for
-      // that tool; serializing it would freeze (and can OOM-kill) the app.
-      const {
-        over,
-        approxBytes
-      } = approxSizeOver(payload, MAX_SNAPSHOT_EMIT_BYTES);
-      if (over) {
-        if (!warnedOversized.has(toolId)) {
-          warnedOversized.add(toolId);
-          console.warn(`${LOG} "${toolId}" snapshot ≈${(approxBytes / 1e6).toFixed(1)}MB exceeds the ${MAX_SNAPSHOT_EMIT_BYTES / 1e6}MB sync budget — dropped (dashboard will be stale for this tool). The adapter should ship a wire-form snapshot (summaries + on-demand detail).`);
-        }
-        return;
-      }
-      const message = {
-        toolId,
-        persistentDeviceId: deviceId,
-        timestamp: lastEmit[toolId],
-        version: tool.version,
-        kind: "snapshot",
-        payload
-      };
-      safeEmit("devtool-sync", message);
-    };
-
-    // Leading + trailing throttle: emit immediately when outside the window,
-    // otherwise schedule a flush for the window's end so the dashboard always
-    // converges to the latest state.
-    const scheduleSnapshot = toolId => {
-      if (timers[toolId]) return;
-      const elapsed = Date.now() - (lastEmit[toolId] ?? 0);
-      if (elapsed >= throttleMs) {
-        sendSnapshot(toolId);
-        return;
-      }
-      timers[toolId] = setTimeout(() => {
-        delete timers[toolId];
-        sendSnapshot(toolId);
-      }, throttleMs - elapsed);
-    };
-    const watchTool = toolId => {
-      const tool = toolsRef.current[toolId];
-      if (!tool || unsubs.has(toolId)) return;
-      unsubs.set(toolId, tool.subscribe(() => scheduleSnapshot(toolId)));
-      (0, _logger.log)(`${LOG} Watching "${toolId}"`, enableLogs);
-    };
-    const unwatchTool = toolId => {
-      unsubs.get(toolId)?.();
-      unsubs.delete(toolId);
-      if (timers[toolId]) {
-        clearTimeout(timers[toolId]);
-        delete timers[toolId];
-      }
-      (0, _logger.log)(`${LOG} Stopped watching "${toolId}"`, enableLogs);
-    };
-    const sendCapabilities = () => {
-      const message = {
-        persistentDeviceId: deviceId,
-        protocolVersion: _types.SYNC_PROTOCOL_VERSION,
-        tools: Object.entries(toolsRef.current).map(([toolId, tool]) => ({
-          toolId,
-          version: tool.version,
-          actions: Object.keys(tool.actions ?? {})
-        }))
-      };
-      safeEmit("devtool-capabilities", message);
-    };
-    const handleWatch = message => {
-      if (!isForThisDevice(message.targetDeviceId)) return;
-      if (message.watching) {
-        watchedRef.current.add(message.toolId);
-        watchTool(message.toolId);
-        sendSnapshot(message.toolId);
-      } else {
-        watchedRef.current.delete(message.toolId);
-        unwatchTool(message.toolId);
-      }
-    };
-    const handleRequest = message => {
-      if (!isForThisDevice(message.targetDeviceId)) return;
-      sendSnapshot(message.toolId);
-    };
-    const handleAction = async message => {
-      if (!isForThisDevice(message.targetDeviceId)) return;
-      const {
-        requestId,
-        toolId,
-        action,
-        params
-      } = message;
-      const result = {
-        requestId,
-        toolId,
-        action,
-        persistentDeviceId: deviceId,
-        timestamp: Date.now(),
-        ok: false
-      };
-      const tool = toolsRef.current[toolId];
-      const fn = tool?.actions?.[action];
-      if (!fn) {
-        result.error = tool ? `Unknown action "${action}" on tool "${toolId}"` : `Unknown tool "${toolId}"`;
-        safeEmit("devtool-action-result", result);
-        return;
-      }
-      try {
-        result.result = await fn(params);
-        result.ok = true;
-      } catch (error) {
-        result.error = error instanceof Error ? error.message : String(error);
-      }
-
-      // Same budget for action results: e.g. redux getState({includeValues:
-      // true}) on a huge tree would otherwise OOM through this exact emit.
-      if (result.ok) {
-        const {
-          over,
-          approxBytes
-        } = approxSizeOver(result.result, MAX_ACTION_RESULT_BYTES);
-        if (over) {
-          result.ok = false;
-          result.result = undefined;
-          result.error = `Result ≈${(approxBytes / 1e6).toFixed(1)}MB exceeds the ${MAX_ACTION_RESULT_BYTES / 1e6}MB sync budget. Narrow the request (e.g. includeValues:false, a limit, or a more specific action).`;
-        }
-      }
-      result.timestamp = Date.now();
-      safeEmit("devtool-action-result", result);
-    };
-    const handleConnect = () => {
-      // The server replies with current watch state for this device.
-      sendCapabilities();
-    };
-    if (socket.connected) sendCapabilities();
-
-    // Restore subscriptions for tools that were watched before this effect
-    // re-ran (or that arrived after the watch message).
-    for (const toolId of watchedRef.current) {
-      if (toolsRef.current[toolId]) watchTool(toolId);
-    }
-    socket.on("connect", handleConnect);
-    socket.on("devtool-watch", handleWatch);
-    socket.on("request-devtool-state", handleRequest);
-    socket.on("devtool-action", handleAction);
-    return () => {
-      socket.off("connect", handleConnect);
-      socket.off("devtool-watch", handleWatch);
-      socket.off("request-devtool-state", handleRequest);
-      socket.off("devtool-action", handleAction);
-      for (const toolId of [...unsubs.keys()]) unwatchTool(toolId);
-    };
+    return (0, _attachDeviceSync.attachDeviceSync)({
+      socket,
+      deviceId,
+      getTools: () => toolsRef.current,
+      watched: watchedRef.current,
+      throttleMs,
+      enableLogs
+    });
     // toolIdsKey stands in for `tools` (see comment above its definition).
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [socket, deviceId, enabled, throttleMs, enableLogs, toolIdsKey]);

package/lib/module/attachDeviceSync.js

@@ -0,0 +1,205 @@
+"use strict";
+
+import { log } from "./utils/logger";
+import { MAX_ACTION_RESULT_BYTES, MAX_SNAPSHOT_EMIT_BYTES, approxSizeOver } from "./emitBudget";
+import { SYNC_PROTOCOL_VERSION } from "./types";
+const LOG = "[ExternalSync]";
+
+/** Minimal socket surface the device-side bridge needs. */
+
+/**
+ * "capture" records into the tool's store without pushing snapshots; "stream"
+ * also emits on every change. See `DevToolWatchMessage.stream`.
+ */
+
+/**
+ * Device-side sync bridge (no React). A tool's adapter is only subscribed
+ * while a dashboard is watching it (`devtool-watch`).
+ */
+export function attachDeviceSync({
+  socket,
+  deviceId,
+  getTools,
+  watched,
+  throttleMs = 200,
+  enableLogs = false
+}) {
+  const unsubs = new Map();
+  const lastEmit = {};
+  const timers = {};
+  const isForThisDevice = targetDeviceId => targetDeviceId === "All" || targetDeviceId === deviceId;
+  const safeEmit = (event, message) => {
+    try {
+      socket.emit(event, message);
+    } catch (error) {
+      log(`${LOG} Failed to emit "${event}": ${error}. Payload must be JSON-serializable.`, enableLogs, "error");
+    }
+  };
+  const warnedOversized = new Set();
+  const sendSnapshot = toolId => {
+    const tool = getTools()[toolId];
+    if (!tool) return;
+    lastEmit[toolId] = Date.now();
+    const payload = tool.getSnapshot();
+    const {
+      over,
+      approxBytes
+    } = approxSizeOver(payload, MAX_SNAPSHOT_EMIT_BYTES);
+    if (over) {
+      if (!warnedOversized.has(toolId)) {
+        warnedOversized.add(toolId);
+        console.warn(`${LOG} "${toolId}" snapshot ≈${(approxBytes / 1e6).toFixed(1)}MB exceeds the ${MAX_SNAPSHOT_EMIT_BYTES / 1e6}MB sync budget — dropped (dashboard will be stale for this tool). The adapter should ship a wire-form snapshot (summaries + on-demand detail).`);
+      }
+      return;
+    }
+    const message = {
+      toolId,
+      persistentDeviceId: deviceId,
+      timestamp: lastEmit[toolId],
+      version: tool.version,
+      kind: "snapshot",
+      payload
+    };
+    safeEmit("devtool-sync", message);
+  };
+  const scheduleSnapshot = toolId => {
+    if (timers[toolId]) return;
+    const elapsed = Date.now() - (lastEmit[toolId] ?? 0);
+    if (elapsed >= throttleMs) {
+      sendSnapshot(toolId);
+      return;
+    }
+    timers[toolId] = setTimeout(() => {
+      delete timers[toolId];
+      sendSnapshot(toolId);
+    }, throttleMs - elapsed);
+  };
+
+  /** The mode each currently-subscribed tool is wired for. */
+  const activeModes = new Map();
+  const watchTool = (toolId, mode) => {
+    const tool = getTools()[toolId];
+    if (!tool) return;
+    if (unsubs.has(toolId)) {
+      if (activeModes.get(toolId) === mode) return;
+      // Mode changed (a streaming dashboard left, or arrived) — rewire, but
+      // do NOT drop the subscription in between: releasing it would take the
+      // store's subscriber count to 0 and stop capture mid-flight.
+      const previous = unsubs.get(toolId);
+      unsubs.set(toolId, tool.subscribe(mode === "stream" ? () => scheduleSnapshot(toolId) : () => {}));
+      activeModes.set(toolId, mode);
+      previous?.();
+      log(`${LOG} "${toolId}" watch mode → ${mode}`, enableLogs);
+      return;
+    }
+    unsubs.set(toolId, tool.subscribe(mode === "stream" ? () => scheduleSnapshot(toolId) : () => {}));
+    activeModes.set(toolId, mode);
+    log(`${LOG} Watching "${toolId}" (${mode})`, enableLogs);
+  };
+  const unwatchTool = toolId => {
+    unsubs.get(toolId)?.();
+    unsubs.delete(toolId);
+    activeModes.delete(toolId);
+    if (timers[toolId]) {
+      clearTimeout(timers[toolId]);
+      delete timers[toolId];
+    }
+    log(`${LOG} Stopped watching "${toolId}"`, enableLogs);
+  };
+  const sendCapabilities = () => {
+    const message = {
+      persistentDeviceId: deviceId,
+      protocolVersion: SYNC_PROTOCOL_VERSION,
+      tools: Object.entries(getTools()).map(([toolId, tool]) => ({
+        toolId,
+        version: tool.version,
+        actions: Object.keys(tool.actions ?? {})
+      }))
+    };
+    safeEmit("devtool-capabilities", message);
+  };
+  const handleWatch = message => {
+    if (!isForThisDevice(message.targetDeviceId)) return;
+    if (message.watching) {
+      // `stream` is only trustworthy once a broker has merged every
+      // dashboard's request (see DevToolWatchMessage.consolidated). Without
+      // that, an unmerged capture request could quiet a dashboard that is
+      // actively painting, so default to streaming.
+      const mode = message.consolidated === true && message.stream === false ? "capture" : "stream";
+      watched.set(message.toolId, mode);
+      watchTool(message.toolId, mode);
+      // Only a streaming audience gets the priming snapshot. A capture-only
+      // client reads with `request-devtool-state` when it actually wants one;
+      // pushing here would hand it the very payload it asked not to receive.
+      if (mode === "stream") sendSnapshot(message.toolId);
+    } else {
+      watched.delete(message.toolId);
+      unwatchTool(message.toolId);
+    }
+  };
+  const handleRequest = message => {
+    if (!isForThisDevice(message.targetDeviceId)) return;
+    sendSnapshot(message.toolId);
+  };
+  const handleAction = async message => {
+    if (!isForThisDevice(message.targetDeviceId)) return;
+    const {
+      requestId,
+      toolId,
+      action,
+      params
+    } = message;
+    const result = {
+      requestId,
+      toolId,
+      action,
+      persistentDeviceId: deviceId,
+      timestamp: Date.now(),
+      ok: false
+    };
+    const tool = getTools()[toolId];
+    const fn = tool?.actions?.[action];
+    if (!fn) {
+      result.error = tool ? `Unknown action "${action}" on tool "${toolId}"` : `Unknown tool "${toolId}"`;
+      safeEmit("devtool-action-result", result);
+      return;
+    }
+    try {
+      result.result = await fn(params);
+      result.ok = true;
+    } catch (error) {
+      result.error = error instanceof Error ? error.message : String(error);
+    }
+    if (result.ok) {
+      const {
+        over,
+        approxBytes
+      } = approxSizeOver(result.result, MAX_ACTION_RESULT_BYTES);
+      if (over) {
+        result.ok = false;
+        result.result = undefined;
+        result.error = `Result ≈${(approxBytes / 1e6).toFixed(1)}MB exceeds the ${MAX_ACTION_RESULT_BYTES / 1e6}MB sync budget. Narrow the request (e.g. includeValues:false, a limit, or a more specific action).`;
+      }
+    }
+    result.timestamp = Date.now();
+    safeEmit("devtool-action-result", result);
+  };
+  const handleConnect = () => {
+    sendCapabilities();
+  };
+  if (socket.connected) sendCapabilities();
+  for (const [toolId, mode] of watched) {
+    if (getTools()[toolId]) watchTool(toolId, mode);
+  }
+  socket.on("connect", handleConnect);
+  socket.on("devtool-watch", handleWatch);
+  socket.on("request-devtool-state", handleRequest);
+  socket.on("devtool-action", handleAction);
+  return () => {
+    socket.off("connect", handleConnect);
+    socket.off("devtool-watch", handleWatch);
+    socket.off("request-devtool-state", handleRequest);
+    socket.off("devtool-action", handleAction);
+    for (const toolId of [...unsubs.keys()]) unwatchTool(toolId);
+  };
+}

package/lib/module/emitBudget.js

@@ -0,0 +1,52 @@
+"use strict";
+
+/**
+ * Emit-layer byte budgets — the choke-point guard.
+ *
+ * Every adapter's snapshot and every action result funnels through
+ * socket.emit, whose serializer walks the ENTIRE payload synchronously on
+ * the JS thread (and JSON.stringify does not honor structural sharing).
+ * Per-adapter guards get missed — the redux adapter shipping raw state
+ * trees froze and native-OOM-crashed enterprise apps whenever a dashboard
+ * was connected. One budget here closes every adapter's hole at once:
+ * oversized payloads are dropped (snapshots) or replaced with an error
+ * (action results) instead of being serialized.
+ *
+ * The estimator is O(limit) — early-abort walk, O(1) for giant strings —
+ * never O(payload). Copied per-package by design (see events/redux copies).
+ */
+
+/** Max approx bytes for one tool snapshot emit. */
+export const MAX_SNAPSHOT_EMIT_BYTES = 2 * 1024 * 1024;
+/** Max approx bytes for one action-result emit (explicit requests get more). */
+export const MAX_ACTION_RESULT_BYTES = 8 * 1024 * 1024;
+export function approxSizeOver(value, limit) {
+  let bytes = 0;
+  const stack = [value];
+  const seen = new Set();
+  while (stack.length > 0) {
+    if (bytes > limit) return {
+      over: true,
+      approxBytes: bytes
+    };
+    const v = stack.pop();
+    if (v === null || v === undefined) bytes += 4;else if (typeof v === "string") bytes += v.length + 2;else if (typeof v === "number") bytes += 8;else if (typeof v === "boolean") bytes += 5;else if (typeof v === "object") {
+      if (seen.has(v)) continue;
+      seen.add(v);
+      if (Array.isArray(v)) {
+        bytes += 2 + v.length;
+        for (let i = 0; i < v.length; i++) stack.push(v[i]);
+      } else {
+        bytes += 2;
+        for (const k in v) {
+          bytes += k.length + 4;
+          stack.push(v[k]);
+        }
+      }
+    } else bytes += 4;
+  }
+  return {
+    over: bytes > limit,
+    approxBytes: bytes
+  };
+}

package/lib/module/types.js

@@ -57,7 +57,20 @@ export const SYNC_PROTOCOL_VERSION = 1;
 // DASHBOARD -> DEVICE MESSAGES
 // ============================================================
 
-/** Server-consolidated signal that a tool gained/lost its audience. */
+/**
+ * Server-consolidated signal that a tool gained/lost its audience.
+ *
+ * `watching` arms CAPTURE: the device subscribes to the tool, which is what
+ * makes its store start recording. `stream` decides whether the device also
+ * PUSHES a snapshot on every change (throttled), which is the expensive half —
+ * it serializes the whole payload on the JS thread ~5x/sec.
+ *
+ * Those are separate because their audiences are: a dashboard renders every
+ * snapshot, so it wants both. A request/response client (MCP) reads on demand
+ * via `request-devtool-state` and would throw the stream away — but it still
+ * needs the device to be RECORDING between its reads, or it only ever sees an
+ * empty list and concludes the app made no requests.
+ */
 
 /** Explicit request for a tool's current state (works even while unwatched). */
 

package/lib/module/useExternalSync.js

@@ -1,61 +1,7 @@
 "use strict";
 
 import { useEffect, useRef } from "react";
-import { log } from "./utils/logger";
-import { SYNC_PROTOCOL_VERSION } from "./types";
-const LOG = "[ExternalSync]";
-
-// ==========================================================================
-// Emit-layer byte budgets — the choke-point guard.
-//
-// Every adapter's snapshot and every action result funnels through
-// socket.emit, whose serializer walks the ENTIRE payload synchronously on
-// the JS thread (and JSON.stringify does not honor structural sharing).
-// Per-adapter guards get missed — the redux adapter shipping raw state
-// trees froze and native-OOM-crashed enterprise apps whenever a dashboard
-// was connected. One budget here closes every adapter's hole at once:
-// oversized payloads are dropped (snapshots) or replaced with an error
-// (action results) instead of being serialized.
-//
-// The estimator is O(limit) — early-abort walk, O(1) for giant strings —
-// never O(payload). Copied per-package by design (see events/redux copies).
-// ==========================================================================
-
-/** Max approx bytes for one tool snapshot emit. */
-const MAX_SNAPSHOT_EMIT_BYTES = 2 * 1024 * 1024;
-/** Max approx bytes for one action-result emit (explicit requests get more). */
-const MAX_ACTION_RESULT_BYTES = 8 * 1024 * 1024;
-function approxSizeOver(value, limit) {
-  let bytes = 0;
-  const stack = [value];
-  const seen = new Set();
-  while (stack.length > 0) {
-    if (bytes > limit) return {
-      over: true,
-      approxBytes: bytes
-    };
-    const v = stack.pop();
-    if (v === null || v === undefined) bytes += 4;else if (typeof v === "string") bytes += v.length + 2;else if (typeof v === "number") bytes += 8;else if (typeof v === "boolean") bytes += 5;else if (typeof v === "object") {
-      if (seen.has(v)) continue;
-      seen.add(v);
-      if (Array.isArray(v)) {
-        bytes += 2 + v.length;
-        for (let i = 0; i < v.length; i++) stack.push(v[i]);
-      } else {
-        bytes += 2;
-        for (const k in v) {
-          bytes += k.length + 4;
-          stack.push(v[k]);
-        }
-      }
-    } else bytes += 4;
-  }
-  return {
-    over: bytes > limit,
-    approxBytes: bytes
-  };
-}
-
+import { attachDeviceSync } from "./attachDeviceSync";
 /**
  * Device-side sync bridge: syncs any number of dev tools to the desktop
  * dashboard and executes actions invoked remotely.
@@ -96,183 +42,21 @@ export function useExternalSync({
 
   // Watch state persists across effect re-runs (e.g. when tools are
   // added/removed) so an already-watched tool stays subscribed.
-  const watchedRef = useRef(new Set());
+  const watchedRef = useRef(new Map());
 
   // Re-run the effect only when tools are added/removed, not on every
   // object-reference change.
   const toolIdsKey = Object.keys(tools).sort().join(",");
   useEffect(() => {
     if (!socket || !deviceId || !enabled) return;
-    const unsubs = new Map();
-    const lastEmit = {};
-    const timers = {};
-    const isForThisDevice = targetDeviceId => targetDeviceId === "All" || targetDeviceId === deviceId;
-    const safeEmit = (event, message) => {
-      try {
-        socket.emit(event, message);
-      } catch (error) {
-        log(`${LOG} Failed to emit "${event}": ${error}. Payload must be JSON-serializable.`, enableLogs, "error");
-      }
-    };
-
-    // One warning per tool per session — the drop repeats every snapshot.
-    const warnedOversized = new Set();
-    const sendSnapshot = toolId => {
-      const tool = toolsRef.current[toolId];
-      if (!tool) return;
-      lastEmit[toolId] = Date.now();
-      const payload = tool.getSnapshot();
-
-      // Emit-layer budget: never hand an unbounded payload to the socket
-      // serializer. A dropped snapshot means a stale dashboard panel for
-      // that tool; serializing it would freeze (and can OOM-kill) the app.
-      const {
-        over,
-        approxBytes
-      } = approxSizeOver(payload, MAX_SNAPSHOT_EMIT_BYTES);
-      if (over) {
-        if (!warnedOversized.has(toolId)) {
-          warnedOversized.add(toolId);
-          console.warn(`${LOG} "${toolId}" snapshot ≈${(approxBytes / 1e6).toFixed(1)}MB exceeds the ${MAX_SNAPSHOT_EMIT_BYTES / 1e6}MB sync budget — dropped (dashboard will be stale for this tool). The adapter should ship a wire-form snapshot (summaries + on-demand detail).`);
-        }
-        return;
-      }
-      const message = {
-        toolId,
-        persistentDeviceId: deviceId,
-        timestamp: lastEmit[toolId],
-        version: tool.version,
-        kind: "snapshot",
-        payload
-      };
-      safeEmit("devtool-sync", message);
-    };
-
-    // Leading + trailing throttle: emit immediately when outside the window,
-    // otherwise schedule a flush for the window's end so the dashboard always
-    // converges to the latest state.
-    const scheduleSnapshot = toolId => {
-      if (timers[toolId]) return;
-      const elapsed = Date.now() - (lastEmit[toolId] ?? 0);
-      if (elapsed >= throttleMs) {
-        sendSnapshot(toolId);
-        return;
-      }
-      timers[toolId] = setTimeout(() => {
-        delete timers[toolId];
-        sendSnapshot(toolId);
-      }, throttleMs - elapsed);
-    };
-    const watchTool = toolId => {
-      const tool = toolsRef.current[toolId];
-      if (!tool || unsubs.has(toolId)) return;
-      unsubs.set(toolId, tool.subscribe(() => scheduleSnapshot(toolId)));
-      log(`${LOG} Watching "${toolId}"`, enableLogs);
-    };
-    const unwatchTool = toolId => {
-      unsubs.get(toolId)?.();
-      unsubs.delete(toolId);
-      if (timers[toolId]) {
-        clearTimeout(timers[toolId]);
-        delete timers[toolId];
-      }
-      log(`${LOG} Stopped watching "${toolId}"`, enableLogs);
-    };
-    const sendCapabilities = () => {
-      const message = {
-        persistentDeviceId: deviceId,
-        protocolVersion: SYNC_PROTOCOL_VERSION,
-        tools: Object.entries(toolsRef.current).map(([toolId, tool]) => ({
-          toolId,
-          version: tool.version,
-          actions: Object.keys(tool.actions ?? {})
-        }))
-      };
-      safeEmit("devtool-capabilities", message);
-    };
-    const handleWatch = message => {
-      if (!isForThisDevice(message.targetDeviceId)) return;
-      if (message.watching) {
-        watchedRef.current.add(message.toolId);
-        watchTool(message.toolId);
-        sendSnapshot(message.toolId);
-      } else {
-        watchedRef.current.delete(message.toolId);
-        unwatchTool(message.toolId);
-      }
-    };
-    const handleRequest = message => {
-      if (!isForThisDevice(message.targetDeviceId)) return;
-      sendSnapshot(message.toolId);
-    };
-    const handleAction = async message => {
-      if (!isForThisDevice(message.targetDeviceId)) return;
-      const {
-        requestId,
-        toolId,
-        action,
-        params
-      } = message;
-      const result = {
-        requestId,
-        toolId,
-        action,
-        persistentDeviceId: deviceId,
-        timestamp: Date.now(),
-        ok: false
-      };
-      const tool = toolsRef.current[toolId];
-      const fn = tool?.actions?.[action];
-      if (!fn) {
-        result.error = tool ? `Unknown action "${action}" on tool "${toolId}"` : `Unknown tool "${toolId}"`;
-        safeEmit("devtool-action-result", result);
-        return;
-      }
-      try {
-        result.result = await fn(params);
-        result.ok = true;
-      } catch (error) {
-        result.error = error instanceof Error ? error.message : String(error);
-      }
-
-      // Same budget for action results: e.g. redux getState({includeValues:
-      // true}) on a huge tree would otherwise OOM through this exact emit.
-      if (result.ok) {
-        const {
-          over,
-          approxBytes
-        } = approxSizeOver(result.result, MAX_ACTION_RESULT_BYTES);
-        if (over) {
-          result.ok = false;
-          result.result = undefined;
-          result.error = `Result ≈${(approxBytes / 1e6).toFixed(1)}MB exceeds the ${MAX_ACTION_RESULT_BYTES / 1e6}MB sync budget. Narrow the request (e.g. includeValues:false, a limit, or a more specific action).`;
-        }
-      }
-      result.timestamp = Date.now();
-      safeEmit("devtool-action-result", result);
-    };
-    const handleConnect = () => {
-      // The server replies with current watch state for this device.
-      sendCapabilities();
-    };
-    if (socket.connected) sendCapabilities();
-
-    // Restore subscriptions for tools that were watched before this effect
-    // re-ran (or that arrived after the watch message).
-    for (const toolId of watchedRef.current) {
-      if (toolsRef.current[toolId]) watchTool(toolId);
-    }
-    socket.on("connect", handleConnect);
-    socket.on("devtool-watch", handleWatch);
-    socket.on("request-devtool-state", handleRequest);
-    socket.on("devtool-action", handleAction);
-    return () => {
-      socket.off("connect", handleConnect);
-      socket.off("devtool-watch", handleWatch);
-      socket.off("request-devtool-state", handleRequest);
-      socket.off("devtool-action", handleAction);
-      for (const toolId of [...unsubs.keys()]) unwatchTool(toolId);
-    };
+    return attachDeviceSync({
+      socket,
+      deviceId,
+      getTools: () => toolsRef.current,
+      watched: watchedRef.current,
+      throttleMs,
+      enableLogs
+    });
     // toolIdsKey stands in for `tools` (see comment above its definition).
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [socket, deviceId, enabled, throttleMs, enableLogs, toolIdsKey]);

package/lib/typescript/attachDeviceSync.d.ts

@@ -0,0 +1,32 @@
+import { type ToolSyncAdapter } from "./types";
+/** Minimal socket surface the device-side bridge needs. */
+export type SyncSocket = {
+    connected: boolean;
+    emit: (event: string, ...args: unknown[]) => unknown;
+    on: (event: string, listener: (...args: any[]) => void) => unknown;
+    off: (event: string, listener: (...args: any[]) => void) => unknown;
+};
+/**
+ * "capture" records into the tool's store without pushing snapshots; "stream"
+ * also emits on every change. See `DevToolWatchMessage.stream`.
+ */
+export type WatchMode = "capture" | "stream";
+export type AttachDeviceSyncOptions = {
+    socket: SyncSocket;
+    deviceId: string;
+    getTools: () => Record<string, ToolSyncAdapter>;
+    /**
+     * Survives attach/detach so an already-watched tool stays subscribed — and
+     * at the same MODE, or a re-attach would silently start streaming to a
+     * client that only asked to record.
+     */
+    watched: Map<string, WatchMode>;
+    throttleMs?: number;
+    enableLogs?: boolean;
+};
+/**
+ * Device-side sync bridge (no React). A tool's adapter is only subscribed
+ * while a dashboard is watching it (`devtool-watch`).
+ */
+export declare function attachDeviceSync({ socket, deviceId, getTools, watched, throttleMs, enableLogs, }: AttachDeviceSyncOptions): () => void;
+//# sourceMappingURL=attachDeviceSync.d.ts.map

package/lib/typescript/attachDeviceSync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachDeviceSync.d.ts","sourceRoot":"","sources":["../../src/attachDeviceSync.ts"],"names":[],"mappings":"AAMA,OAAO,EAQL,KAAK,eAAe,EACrB,MAAM,SAAS,CAAC;AAIjB,2DAA2D;AAC3D,MAAM,MAAM,UAAU,GAAG;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IACrD,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,KAAK,OAAO,CAAC;IACnE,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,KAAK,OAAO,CAAC;CACrE,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE7C,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAChD;;;;OAIG;IACH,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,UAAgB,EAChB,UAAkB,GACnB,EAAE,uBAAuB,GAAG,MAAM,IAAI,CA2NtC"}

package/lib/typescript/emitBudget.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Emit-layer byte budgets — the choke-point guard.
+ *
+ * Every adapter's snapshot and every action result funnels through
+ * socket.emit, whose serializer walks the ENTIRE payload synchronously on
+ * the JS thread (and JSON.stringify does not honor structural sharing).
+ * Per-adapter guards get missed — the redux adapter shipping raw state
+ * trees froze and native-OOM-crashed enterprise apps whenever a dashboard
+ * was connected. One budget here closes every adapter's hole at once:
+ * oversized payloads are dropped (snapshots) or replaced with an error
+ * (action results) instead of being serialized.
+ *
+ * The estimator is O(limit) — early-abort walk, O(1) for giant strings —
+ * never O(payload). Copied per-package by design (see events/redux copies).
+ */
+/** Max approx bytes for one tool snapshot emit. */
+export declare const MAX_SNAPSHOT_EMIT_BYTES: number;
+/** Max approx bytes for one action-result emit (explicit requests get more). */
+export declare const MAX_ACTION_RESULT_BYTES: number;
+export declare function approxSizeOver(value: unknown, limit: number): {
+    over: boolean;
+    approxBytes: number;
+};
+//# sourceMappingURL=emitBudget.d.ts.map

package/lib/typescript/emitBudget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitBudget.d.ts","sourceRoot":"","sources":["../../src/emitBudget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,mDAAmD;AACnD,eAAO,MAAM,uBAAuB,QAAkB,CAAC;AACvD,gFAAgF;AAChF,eAAO,MAAM,uBAAuB,QAAkB,CAAC;AAEvD,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,GACZ;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CA2BxC"}

package/lib/typescript/types.d.ts

@@ -60,11 +60,44 @@ export interface DevToolActionResultMessage {
     /** Present when not ok. */
     error?: string;
 }
-/** Server-consolidated signal that a tool gained/lost its audience. */
+/**
+ * Server-consolidated signal that a tool gained/lost its audience.
+ *
+ * `watching` arms CAPTURE: the device subscribes to the tool, which is what
+ * makes its store start recording. `stream` decides whether the device also
+ * PUSHES a snapshot on every change (throttled), which is the expensive half —
+ * it serializes the whole payload on the JS thread ~5x/sec.
+ *
+ * Those are separate because their audiences are: a dashboard renders every
+ * snapshot, so it wants both. A request/response client (MCP) reads on demand
+ * via `request-devtool-state` and would throw the stream away — but it still
+ * needs the device to be RECORDING between its reads, or it only ever sees an
+ * empty list and concludes the app made no requests.
+ */
 export interface DevToolWatchMessage {
     toolId: string;
     targetDeviceId: string;
     watching: boolean;
+    /**
+     * Push snapshots on change. Defaults to TRUE when absent, so a dashboard
+     * that predates this field behaves exactly as before.
+     *
+     * Only honored alongside `consolidated` — see below.
+     */
+    stream?: boolean;
+    /**
+     * Set by the BROKER to mean "I merged every dashboard's request and this is
+     * the mode the device should be in".
+     *
+     * It exists because the desktop and the MCP server each embed their own copy
+     * of the broker and ship on separate cycles, so a new client can end up
+     * talking through an old broker. An old broker forwards a dashboard's watch
+     * message verbatim — it has no idea modes exist — so an agent's
+     * `stream: false` would reach the device unmerged and silently stop the
+     * developer's panel from updating. Requiring this flag makes that
+     * combination degrade to plain streaming (today's behavior) instead.
+     */
+    consolidated?: boolean;
 }
 /** Explicit request for a tool's current state (works even while unwatched). */
 export interface DevToolRequestMessage {

package/lib/typescript/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/lib/typescript/useExternalSync.d.ts

@@ -1,4 +1,4 @@
-import { type UseExternalSyncProps } from "./types";
+import type { UseExternalSyncProps } from "./types";
 /**
  * Device-side sync bridge: syncs any number of dev tools to the desktop
  * dashboard and executes actions invoked remotely.

package/lib/typescript/useExternalSync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useExternalSync.d.ts","sourceRoot":"","sources":["../../src/useExternalSync.ts"],"names":[],"mappings":"AAEA,OAAO,EAQL,KAAK,oBAAoB,EAC1B,MAAM,SAAS,CAAC;AAyDjB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,eAAe,CAAC,EAC9B,KAAK,EACL,MAAM,EACN,QAAQ,EACR,OAAc,EACd,UAAgB,EAChB,UAAkB,GACnB,EAAE,oBAAoB,QAkNtB"}
+{"version":3,"file":"useExternalSync.d.ts","sourceRoot":"","sources":["../../src/useExternalSync.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,eAAe,CAAC,EAC9B,KAAK,EACL,MAAM,EACN,QAAQ,EACR,OAAc,EACd,UAAgB,EAChB,UAAkB,GACnB,EAAE,oBAAoB,QA0BtB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buoy-gg/external-sync",
-  "version": "7.0.17",
+  "version": "7.0.18",
   "description": "Generic device-to-desktop sync for Buoy dev tools",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",