@buoy-gg/external-sync 7.0.21 → 7.0.22

package/lib/commonjs/attachDeviceSync.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.attachDeviceSync = attachDeviceSync;
 var _logger = require("./utils/logger");
+var _crashFlush = require("./crashFlush");
 var _emitBudget = require("./emitBudget");
 var _types = require("./types");
 const LOG = "[ExternalSync]";
@@ -79,6 +80,31 @@ function attachDeviceSync({
     }, throttleMs - elapsed);
   };
 
+  /**
+   * Emit a tool's snapshot immediately, cancelling any throttled push.
+   * The escape hatch for "the tree is about to die, get this out now" — see
+   * ./crashFlush. Ignores watch MODE: a crash flush is worth sending even to a
+   * dashboard that only asked to record.
+   *
+   * It does NOT ignore "is anyone there". Building a snapshot is the expensive
+   * part of this tool (deep-copying every captured entry, then walking it to
+   * price it), and `socket.emit` on a disconnected socket queues into
+   * socket.io's unbounded send buffer. Without these two guards, an app logging
+   * errors in a loop with no dashboard attached would pay that cost several
+   * times a second and grow the buffer until it ran out of memory — in a
+   * customer's app, for no observer.
+   */
+  const flushNow = toolId => {
+    if (!socket.connected) return;
+    if (!unsubs.has(toolId)) return; // nobody is watching this tool
+    if (timers[toolId]) {
+      clearTimeout(timers[toolId]);
+      delete timers[toolId];
+    }
+    sendSnapshot(toolId);
+  };
+  (0, _crashFlush.registerToolFlusher)(flushNow);
+
   /** The mode each currently-subscribed tool is wired for. */
   const activeModes = new Map();
   const watchTool = (toolId, mode) => {
@@ -200,6 +226,7 @@ function attachDeviceSync({
   socket.on("request-devtool-state", handleRequest);
   socket.on("devtool-action", handleAction);
   return () => {
+    (0, _crashFlush.unregisterToolFlusher)(flushNow);
     socket.off("connect", handleConnect);
     socket.off("devtool-watch", handleWatch);
     socket.off("request-devtool-state", handleRequest);

package/lib/commonjs/crashFlush.js

@@ -0,0 +1,73 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.flushToolSyncNow = flushToolSyncNow;
+exports.registerToolFlusher = registerToolFlusher;
+exports.unregisterToolFlusher = unregisterToolFlusher;
+/**
+ * crashFlush — a global "push this tool's snapshot RIGHT NOW" seam.
+ *
+ * Why a global and not an import: the device sync bridge lives in the React
+ * tree (`useExternalSync`), but the moment worth capturing most — a fatal
+ * render error — is the moment that tree dies. React unmounts the root right
+ * after the error is reported, which detaches the bridge and cancels the
+ * normal throttled snapshot push, so the crash never reaches the dashboard or
+ * the MCP server. The app then looks like it simply stopped answering.
+ *
+ * A tool that knows it is about to lose the tree (see @buoy-gg/console's fatal
+ * hook) calls {@link flushToolSyncNow} synchronously from its error handler,
+ * while the socket is still attached, and the snapshot goes out immediately.
+ *
+ * It is a global because the tools deliberately do NOT depend on this package
+ * (their adapters are duck-typed and picked up by auto-discovery), so there is
+ * no import edge to hang a registry on. Callers must treat it as best-effort:
+ * absent bridge = no-op.
+ */
+
+const FLUSH_KEY = "__buoyFlushToolSync";
+
+/** Emit `toolId`'s current snapshot now, bypassing the throttle. */
+
+/**
+ * A SET, not a single slot: React can mount a second provider (or re-run the
+ * attach effect setup before the old one's cleanup) so two bridges are briefly
+ * live at once. A last-writer-wins slot would let the second registration
+ * silently disable the first's crash flush — failing in exactly the moment it
+ * is the only thing that gets the crash out, with no error and no log.
+ */
+
+function flushers() {
+  const g = globalThis;
+  if (!g[FLUSH_KEY]) g[FLUSH_KEY] = new Set();
+  return g[FLUSH_KEY];
+}
+
+/** Install a bridge's flusher. Called by `attachDeviceSync`. */
+function registerToolFlusher(flush) {
+  flushers().add(flush);
+}
+
+/** Remove one bridge's flusher, leaving any others intact. */
+function unregisterToolFlusher(flush) {
+  flushers().delete(flush);
+}
+
+/**
+ * Push a tool's snapshot immediately through every attached sync bridge.
+ * Never throws — a crash path must not crash.
+ */
+function flushToolSyncNow(toolId) {
+  try {
+    for (const flush of flushers()) {
+      try {
+        flush(toolId);
+      } catch {
+        // One bad bridge must not stop the others.
+      }
+    }
+  } catch {
+    // Best-effort by design.
+  }
+}

package/lib/commonjs/index.js

@@ -15,6 +15,12 @@ Object.defineProperty(exports, "SYNC_PROTOCOL_VERSION", {
     return _types.SYNC_PROTOCOL_VERSION;
   }
 });
+Object.defineProperty(exports, "flushToolSyncNow", {
+  enumerable: true,
+  get: function () {
+    return _crashFlush.flushToolSyncNow;
+  }
+});
 Object.defineProperty(exports, "getDefaultSocketURL", {
   enumerable: true,
   get: function () {
@@ -33,6 +39,12 @@ Object.defineProperty(exports, "getSyncStatus", {
     return _syncStatusStore.getSyncStatus;
   }
 });
+Object.defineProperty(exports, "registerToolFlusher", {
+  enumerable: true,
+  get: function () {
+    return _crashFlush.registerToolFlusher;
+  }
+});
 Object.defineProperty(exports, "setSyncStatus", {
   enumerable: true,
   get: function () {
@@ -45,6 +57,12 @@ Object.defineProperty(exports, "subscribeSyncStatus", {
     return _syncStatusStore.subscribeSyncStatus;
   }
 });
+Object.defineProperty(exports, "unregisterToolFlusher", {
+  enumerable: true,
+  get: function () {
+    return _crashFlush.unregisterToolFlusher;
+  }
+});
 Object.defineProperty(exports, "useExternalSync", {
   enumerable: true,
   get: function () {
@@ -60,5 +78,6 @@ Object.defineProperty(exports, "useExternalSyncSocket", {
 var _useExternalSync = require("./useExternalSync");
 var _useExternalSyncSocket = require("./useExternalSyncSocket");
 var _getDefaultSocketURL = require("./utils/getDefaultSocketURL");
+var _crashFlush = require("./crashFlush");
 var _syncStatusStore = require("./syncStatusStore");
 var _types = require("./types");

package/lib/module/attachDeviceSync.js

@@ -1,6 +1,7 @@
 "use strict";
 
 import { log } from "./utils/logger";
+import { registerToolFlusher, unregisterToolFlusher } from "./crashFlush";
 import { MAX_ACTION_RESULT_BYTES, MAX_SNAPSHOT_EMIT_BYTES, approxSizeOver } from "./emitBudget";
 import { SYNC_PROTOCOL_VERSION } from "./types";
 const LOG = "[ExternalSync]";
@@ -75,6 +76,31 @@ export function attachDeviceSync({
     }, throttleMs - elapsed);
   };
 
+  /**
+   * Emit a tool's snapshot immediately, cancelling any throttled push.
+   * The escape hatch for "the tree is about to die, get this out now" — see
+   * ./crashFlush. Ignores watch MODE: a crash flush is worth sending even to a
+   * dashboard that only asked to record.
+   *
+   * It does NOT ignore "is anyone there". Building a snapshot is the expensive
+   * part of this tool (deep-copying every captured entry, then walking it to
+   * price it), and `socket.emit` on a disconnected socket queues into
+   * socket.io's unbounded send buffer. Without these two guards, an app logging
+   * errors in a loop with no dashboard attached would pay that cost several
+   * times a second and grow the buffer until it ran out of memory — in a
+   * customer's app, for no observer.
+   */
+  const flushNow = toolId => {
+    if (!socket.connected) return;
+    if (!unsubs.has(toolId)) return; // nobody is watching this tool
+    if (timers[toolId]) {
+      clearTimeout(timers[toolId]);
+      delete timers[toolId];
+    }
+    sendSnapshot(toolId);
+  };
+  registerToolFlusher(flushNow);
+
   /** The mode each currently-subscribed tool is wired for. */
   const activeModes = new Map();
   const watchTool = (toolId, mode) => {
@@ -196,6 +222,7 @@ export function attachDeviceSync({
   socket.on("request-devtool-state", handleRequest);
   socket.on("devtool-action", handleAction);
   return () => {
+    unregisterToolFlusher(flushNow);
     socket.off("connect", handleConnect);
     socket.off("devtool-watch", handleWatch);
     socket.off("request-devtool-state", handleRequest);

package/lib/module/crashFlush.js

@@ -0,0 +1,67 @@
+"use strict";
+
+/**
+ * crashFlush — a global "push this tool's snapshot RIGHT NOW" seam.
+ *
+ * Why a global and not an import: the device sync bridge lives in the React
+ * tree (`useExternalSync`), but the moment worth capturing most — a fatal
+ * render error — is the moment that tree dies. React unmounts the root right
+ * after the error is reported, which detaches the bridge and cancels the
+ * normal throttled snapshot push, so the crash never reaches the dashboard or
+ * the MCP server. The app then looks like it simply stopped answering.
+ *
+ * A tool that knows it is about to lose the tree (see @buoy-gg/console's fatal
+ * hook) calls {@link flushToolSyncNow} synchronously from its error handler,
+ * while the socket is still attached, and the snapshot goes out immediately.
+ *
+ * It is a global because the tools deliberately do NOT depend on this package
+ * (their adapters are duck-typed and picked up by auto-discovery), so there is
+ * no import edge to hang a registry on. Callers must treat it as best-effort:
+ * absent bridge = no-op.
+ */
+
+const FLUSH_KEY = "__buoyFlushToolSync";
+
+/** Emit `toolId`'s current snapshot now, bypassing the throttle. */
+
+/**
+ * A SET, not a single slot: React can mount a second provider (or re-run the
+ * attach effect setup before the old one's cleanup) so two bridges are briefly
+ * live at once. A last-writer-wins slot would let the second registration
+ * silently disable the first's crash flush — failing in exactly the moment it
+ * is the only thing that gets the crash out, with no error and no log.
+ */
+
+function flushers() {
+  const g = globalThis;
+  if (!g[FLUSH_KEY]) g[FLUSH_KEY] = new Set();
+  return g[FLUSH_KEY];
+}
+
+/** Install a bridge's flusher. Called by `attachDeviceSync`. */
+export function registerToolFlusher(flush) {
+  flushers().add(flush);
+}
+
+/** Remove one bridge's flusher, leaving any others intact. */
+export function unregisterToolFlusher(flush) {
+  flushers().delete(flush);
+}
+
+/**
+ * Push a tool's snapshot immediately through every attached sync bridge.
+ * Never throws — a crash path must not crash.
+ */
+export function flushToolSyncNow(toolId) {
+  try {
+    for (const flush of flushers()) {
+      try {
+        flush(toolId);
+      } catch {
+        // One bad bridge must not stop the others.
+      }
+    }
+  } catch {
+    // Best-effort by design.
+  }
+}

package/lib/module/index.js

@@ -11,6 +11,10 @@ export { useExternalSyncSocket } from "./useExternalSyncSocket";
 // ============================================================
 export { getDefaultSocketURL, getMetroHost, DEFAULT_BROKER_PORT } from "./utils/getDefaultSocketURL";
 
+// ============================================================
+// CRASH FLUSH (get a tool's snapshot out before the tree dies)
+// ============================================================
+export { flushToolSyncNow, registerToolFlusher, unregisterToolFlusher } from "./crashFlush";
 // ============================================================
 // SYNC STATUS (read by the floating menu's settings modal)
 // ============================================================

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

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

package/lib/typescript/crashFlush.d.ts

@@ -0,0 +1,31 @@
+/**
+ * crashFlush — a global "push this tool's snapshot RIGHT NOW" seam.
+ *
+ * Why a global and not an import: the device sync bridge lives in the React
+ * tree (`useExternalSync`), but the moment worth capturing most — a fatal
+ * render error — is the moment that tree dies. React unmounts the root right
+ * after the error is reported, which detaches the bridge and cancels the
+ * normal throttled snapshot push, so the crash never reaches the dashboard or
+ * the MCP server. The app then looks like it simply stopped answering.
+ *
+ * A tool that knows it is about to lose the tree (see @buoy-gg/console's fatal
+ * hook) calls {@link flushToolSyncNow} synchronously from its error handler,
+ * while the socket is still attached, and the snapshot goes out immediately.
+ *
+ * It is a global because the tools deliberately do NOT depend on this package
+ * (their adapters are duck-typed and picked up by auto-discovery), so there is
+ * no import edge to hang a registry on. Callers must treat it as best-effort:
+ * absent bridge = no-op.
+ */
+/** Emit `toolId`'s current snapshot now, bypassing the throttle. */
+export type ToolFlusher = (toolId: string) => void;
+/** Install a bridge's flusher. Called by `attachDeviceSync`. */
+export declare function registerToolFlusher(flush: ToolFlusher): void;
+/** Remove one bridge's flusher, leaving any others intact. */
+export declare function unregisterToolFlusher(flush: ToolFlusher): void;
+/**
+ * Push a tool's snapshot immediately through every attached sync bridge.
+ * Never throws — a crash path must not crash.
+ */
+export declare function flushToolSyncNow(toolId: string): void;
+//# sourceMappingURL=crashFlush.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"crashFlush.d.ts","sourceRoot":"","sources":["../../src/crashFlush.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,oEAAoE;AACpE,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;AAiBnD,gEAAgE;AAChE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAE5D;AAED,8DAA8D;AAC9D,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAE9D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAYrD"}

package/lib/typescript/index.d.ts

@@ -1,6 +1,8 @@
 export { useExternalSync } from "./useExternalSync";
 export { useExternalSyncSocket } from "./useExternalSyncSocket";
 export { getDefaultSocketURL, getMetroHost, DEFAULT_BROKER_PORT, } from "./utils/getDefaultSocketURL";
+export { flushToolSyncNow, registerToolFlusher, unregisterToolFlusher, } from "./crashFlush";
+export type { ToolFlusher } from "./crashFlush";
 export { getSyncStatus, setSyncStatus, subscribeSyncStatus, } from "./syncStatusStore";
 export type { SyncStatus } from "./syncStatusStore";
 export { SYNC_PROTOCOL_VERSION } from "./types";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAKhE,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,mBAAmB,GACpB,MAAM,6BAA6B,CAAC;AAKrC,OAAO,EACL,aAAa,EACb,aAAa,EACb,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAKpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAKhD,YAAY,EACV,eAAe,EACf,UAAU,EACV,cAAc,EACd,QAAQ,EACR,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EACzB,kBAAkB,EAClB,oBAAoB,EACpB,0BAA0B,EAC1B,mBAAmB,EACnB,qBAAqB,EACrB,UAAU,GACX,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAKhE,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,mBAAmB,GACpB,MAAM,6BAA6B,CAAC;AAKrC,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAKhD,OAAO,EACL,aAAa,EACb,aAAa,EACb,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAKpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAKhD,YAAY,EACV,eAAe,EACf,UAAU,EACV,cAAc,EACd,QAAQ,EACR,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EACzB,kBAAkB,EAClB,oBAAoB,EACpB,0BAA0B,EAC1B,mBAAmB,EACnB,qBAAqB,EACrB,UAAU,GACX,MAAM,SAAS,CAAC"}

package/package.json

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