@buoy-gg/sync-broker 7.0.17 → 7.0.18

package/dist/index.d.mts

@@ -113,11 +113,31 @@ 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, which starts the tool's
+ * store recording); `stream` decides whether it also PUSHES a snapshot on
+ * every change. A dashboard wants both; a request/response client (MCP) wants
+ * only the first, and reads via `request-devtool-state`.
+ *
+ * The SERVER consolidates these across dashboards — see `handleDevtoolWatch`.
+ * A capture-only watcher must never downgrade a streaming one, or opening an
+ * agent session would silently freeze the desktop's panel.
+ */
 interface DevToolWatchMessage {
     toolId: string;
     targetDeviceId: string;
     watching: boolean;
+    /** Push snapshots on change. Absent means TRUE (pre-`stream` dashboards). */
+    stream?: boolean;
+    /**
+     * Set by the BROKER on the message it sends the device, meaning "this is the
+     * merged mode". Devices ignore `stream` without it, so an old broker (which
+     * forwards a dashboard's message verbatim) can't let one client's
+     * capture-only request quiet another client's live panel.
+     */
+    consolidated?: boolean;
 }
 /** Explicit request for a tool's current state (works even while unwatched). */
 interface DevToolRequestMessage {

package/dist/index.d.ts

@@ -113,11 +113,31 @@ 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, which starts the tool's
+ * store recording); `stream` decides whether it also PUSHES a snapshot on
+ * every change. A dashboard wants both; a request/response client (MCP) wants
+ * only the first, and reads via `request-devtool-state`.
+ *
+ * The SERVER consolidates these across dashboards — see `handleDevtoolWatch`.
+ * A capture-only watcher must never downgrade a streaming one, or opening an
+ * agent session would silently freeze the desktop's panel.
+ */
 interface DevToolWatchMessage {
     toolId: string;
     targetDeviceId: string;
     watching: boolean;
+    /** Push snapshots on change. Absent means TRUE (pre-`stream` dashboards). */
+    stream?: boolean;
+    /**
+     * Set by the BROKER on the message it sends the device, meaning "this is the
+     * merged mode". Devices ignore `stream` without it, so an old broker (which
+     * forwards a dashboard's message verbatim) can't let one client's
+     * capture-only request quiet another client's live panel.
+     */
+    consolidated?: boolean;
 }
 /** Explicit request for a tool's current state (works even while unwatched). */
 interface DevToolRequestMessage {

package/dist/index.js

@@ -41,6 +41,88 @@ module.exports = __toCommonJS(index_exports);
 // src/protocol.ts
 var SYNC_PROTOCOL_VERSION = 1;
 
+// src/watchRegistry.ts
+var toWatchKey = (targetDeviceId, toolId) => JSON.stringify([targetDeviceId, toolId]);
+var fromWatchKey = (key) => JSON.parse(key);
+var WatchRegistry = class {
+  constructor() {
+    /** Per dashboard: the key it watches → the mode it asked for. */
+    this.byDashboard = /* @__PURE__ */ new Map();
+    this.streamCounts = /* @__PURE__ */ new Map();
+    this.captureCounts = /* @__PURE__ */ new Map();
+  }
+  counts(mode) {
+    return mode === "stream" ? this.streamCounts : this.captureCounts;
+  }
+  bump(mode, key, delta) {
+    const counts = this.counts(mode);
+    const next = (counts.get(key) ?? 0) + delta;
+    if (next > 0) counts.set(key, next);
+    else counts.delete(key);
+  }
+  /** The strongest mode any dashboard currently wants; null for nobody. */
+  effective(key) {
+    if ((this.streamCounts.get(key) ?? 0) > 0) return "stream";
+    if ((this.captureCounts.get(key) ?? 0) > 0) return "capture";
+    return null;
+  }
+  /** Every key with at least one watcher (for replay to a reconnecting device). */
+  activeKeys() {
+    return [
+      .../* @__PURE__ */ new Set([...this.streamCounts.keys(), ...this.captureCounts.keys()])
+    ];
+  }
+  /**
+   * Record a watch. Returns the mode to send the device — always non-null,
+   * because the device answers a watch with a snapshot and that is how a
+   * dashboard joining a quiet tool gets its first paint. Re-watching at the
+   * same mode is therefore NOT a no-op at the socket layer.
+   */
+  watch(dashboardId, key, mode) {
+    let held = this.byDashboard.get(dashboardId);
+    if (!held) {
+      held = /* @__PURE__ */ new Map();
+      this.byDashboard.set(dashboardId, held);
+    }
+    const previous = held.get(key);
+    if (previous !== mode) {
+      if (previous) this.bump(previous, key, -1);
+      this.bump(mode, key, 1);
+      held.set(key, mode);
+    }
+    return this.effective(key);
+  }
+  /**
+   * Drop one dashboard's claim. Returns the new effective mode ONLY when it
+   * changed — the device is left alone while someone else still wants the
+   * same thing.
+   */
+  unwatch(dashboardId, key) {
+    const held = this.byDashboard.get(dashboardId);
+    const mode = held?.get(key);
+    if (!held || !mode) return { changed: false, mode: this.effective(key) };
+    const before = this.effective(key);
+    held.delete(key);
+    this.bump(mode, key, -1);
+    const after = this.effective(key);
+    return { changed: after !== before, mode: after };
+  }
+  /** Release everything a disconnecting dashboard held. */
+  releaseDashboard(dashboardId) {
+    const held = this.byDashboard.get(dashboardId);
+    if (!held) return [];
+    this.byDashboard.delete(dashboardId);
+    const changes = [];
+    for (const [key, mode] of held) {
+      const before = this.effective(key);
+      this.bump(mode, key, -1);
+      const after = this.effective(key);
+      if (after !== before) changes.push({ key, mode: after });
+    }
+    return changes;
+  }
+};
+
 // src/socketHandle.ts
 var users = [];
 var allDevices = [];
@@ -48,10 +130,7 @@ var dashboardClients = [];
 var deviceIdMap = /* @__PURE__ */ new Map();
 var activeConnectionsMap = /* @__PURE__ */ new Map();
 var deviceCapabilities = /* @__PURE__ */ new Map();
-var dashboardWatches = /* @__PURE__ */ new Map();
-var watchCounts = /* @__PURE__ */ new Map();
-var toWatchKey = (targetDeviceId, toolId) => JSON.stringify([targetDeviceId, toolId]);
-var fromWatchKey = (key) => JSON.parse(key);
+var watches = new WatchRegistry();
 var brokerLogBuffer = [];
 var BROKER_LOG_BUFFER_MAX = 200;
 var MAX_OFFLINE_AGE_MS = 24 * 60 * 60 * 1e3;
@@ -299,54 +378,42 @@ function socketHandle({ io }) {
       }
     }
   }
+  function emitWatchState(key, mode) {
+    const [targetDeviceId, toolId] = fromWatchKey(key);
+    const message = mode === null ? { toolId, targetDeviceId, watching: false, consolidated: true } : {
+      toolId,
+      targetDeviceId,
+      watching: true,
+      stream: mode === "stream",
+      consolidated: true
+    };
+    withTargetUsers(
+      targetDeviceId,
+      (user) => io.to(user.id).emit("devtool-watch", message),
+      `devtool ${mode === null ? "unwatch" : `watch(${mode})`} ${toolId}`
+    );
+  }
   function handleDevtoolWatch(dashboardId, message) {
     const key = toWatchKey(message.targetDeviceId, message.toolId);
-    let watches = dashboardWatches.get(dashboardId);
-    if (!watches) {
-      watches = /* @__PURE__ */ new Set();
-      dashboardWatches.set(dashboardId, watches);
-    }
     if (message.watching) {
-      if (!watches.has(key)) {
-        watches.add(key);
-        watchCounts.set(key, (watchCounts.get(key) ?? 0) + 1);
-      }
+      const mode2 = message.stream === false ? "capture" : "stream";
+      const effective = watches.watch(dashboardId, key, mode2);
       console.log(
-        `${LOG_PREFIX} Dashboard ${dashboardId} watching "${message.toolId}" on ${message.targetDeviceId}`
-      );
-      withTargetUsers(
-        message.targetDeviceId,
-        (user) => io.to(user.id).emit("devtool-watch", message),
-        `devtool watch ${message.toolId}`
+        `${LOG_PREFIX} Dashboard ${dashboardId} watching "${message.toolId}" on ${message.targetDeviceId} (${mode2}, effective ${effective})`
       );
-    } else if (watches.has(key)) {
-      watches.delete(key);
-      decrementWatch(key);
-    }
-  }
-  function decrementWatch(key) {
-    const next = (watchCounts.get(key) ?? 1) - 1;
-    if (next > 0) {
-      watchCounts.set(key, next);
+      emitWatchState(key, effective);
       return;
     }
-    watchCounts.delete(key);
-    const [targetDeviceId, toolId] = fromWatchKey(key);
+    const { changed, mode } = watches.unwatch(dashboardId, key);
+    if (!changed) return;
     console.log(
-      `${LOG_PREFIX} Last dashboard stopped watching "${toolId}" on ${targetDeviceId}`
-    );
-    withTargetUsers(
-      targetDeviceId,
-      (user) => io.to(user.id).emit("devtool-watch", { toolId, targetDeviceId, watching: false }),
-      `devtool unwatch ${toolId}`
+      mode === null ? `${LOG_PREFIX} Last dashboard stopped watching "${message.toolId}" on ${message.targetDeviceId}` : `${LOG_PREFIX} "${message.toolId}" on ${message.targetDeviceId} downgraded to ${mode}`
     );
+    emitWatchState(key, mode);
   }
   function releaseDashboardWatches(dashboardId) {
-    const watches = dashboardWatches.get(dashboardId);
-    if (!watches) return;
-    dashboardWatches.delete(dashboardId);
-    for (const key of watches) {
-      decrementWatch(key);
+    for (const { key, mode } of watches.releaseDashboard(dashboardId)) {
+      emitWatchState(key, mode);
     }
   }
   io.on("connection", (socket) => {
@@ -424,15 +491,20 @@ function socketHandle({ io }) {
       }
       deviceCapabilities.set(message.persistentDeviceId, message);
       forwardToDashboards("devtool-capabilities", message);
-      for (const key of watchCounts.keys()) {
+      for (const key of watches.activeKeys()) {
         const [targetDeviceId, toolId] = fromWatchKey(key);
-        if (targetDeviceId === "All" || targetDeviceId === message.persistentDeviceId) {
-          socket.emit("devtool-watch", {
-            toolId,
-            targetDeviceId,
-            watching: true
-          });
+        if (targetDeviceId !== "All" && targetDeviceId !== message.persistentDeviceId) {
+          continue;
         }
+        const mode = watches.effective(key);
+        if (!mode) continue;
+        socket.emit("devtool-watch", {
+          toolId,
+          targetDeviceId,
+          watching: true,
+          stream: mode === "stream",
+          consolidated: true
+        });
       }
     });
     socket.on("devtool-sync", (message) => {

package/dist/index.mjs

@@ -1,6 +1,88 @@
 // src/protocol.ts
 var SYNC_PROTOCOL_VERSION = 1;
 
+// src/watchRegistry.ts
+var toWatchKey = (targetDeviceId, toolId) => JSON.stringify([targetDeviceId, toolId]);
+var fromWatchKey = (key) => JSON.parse(key);
+var WatchRegistry = class {
+  constructor() {
+    /** Per dashboard: the key it watches → the mode it asked for. */
+    this.byDashboard = /* @__PURE__ */ new Map();
+    this.streamCounts = /* @__PURE__ */ new Map();
+    this.captureCounts = /* @__PURE__ */ new Map();
+  }
+  counts(mode) {
+    return mode === "stream" ? this.streamCounts : this.captureCounts;
+  }
+  bump(mode, key, delta) {
+    const counts = this.counts(mode);
+    const next = (counts.get(key) ?? 0) + delta;
+    if (next > 0) counts.set(key, next);
+    else counts.delete(key);
+  }
+  /** The strongest mode any dashboard currently wants; null for nobody. */
+  effective(key) {
+    if ((this.streamCounts.get(key) ?? 0) > 0) return "stream";
+    if ((this.captureCounts.get(key) ?? 0) > 0) return "capture";
+    return null;
+  }
+  /** Every key with at least one watcher (for replay to a reconnecting device). */
+  activeKeys() {
+    return [
+      .../* @__PURE__ */ new Set([...this.streamCounts.keys(), ...this.captureCounts.keys()])
+    ];
+  }
+  /**
+   * Record a watch. Returns the mode to send the device — always non-null,
+   * because the device answers a watch with a snapshot and that is how a
+   * dashboard joining a quiet tool gets its first paint. Re-watching at the
+   * same mode is therefore NOT a no-op at the socket layer.
+   */
+  watch(dashboardId, key, mode) {
+    let held = this.byDashboard.get(dashboardId);
+    if (!held) {
+      held = /* @__PURE__ */ new Map();
+      this.byDashboard.set(dashboardId, held);
+    }
+    const previous = held.get(key);
+    if (previous !== mode) {
+      if (previous) this.bump(previous, key, -1);
+      this.bump(mode, key, 1);
+      held.set(key, mode);
+    }
+    return this.effective(key);
+  }
+  /**
+   * Drop one dashboard's claim. Returns the new effective mode ONLY when it
+   * changed — the device is left alone while someone else still wants the
+   * same thing.
+   */
+  unwatch(dashboardId, key) {
+    const held = this.byDashboard.get(dashboardId);
+    const mode = held?.get(key);
+    if (!held || !mode) return { changed: false, mode: this.effective(key) };
+    const before = this.effective(key);
+    held.delete(key);
+    this.bump(mode, key, -1);
+    const after = this.effective(key);
+    return { changed: after !== before, mode: after };
+  }
+  /** Release everything a disconnecting dashboard held. */
+  releaseDashboard(dashboardId) {
+    const held = this.byDashboard.get(dashboardId);
+    if (!held) return [];
+    this.byDashboard.delete(dashboardId);
+    const changes = [];
+    for (const [key, mode] of held) {
+      const before = this.effective(key);
+      this.bump(mode, key, -1);
+      const after = this.effective(key);
+      if (after !== before) changes.push({ key, mode: after });
+    }
+    return changes;
+  }
+};
+
 // src/socketHandle.ts
 var users = [];
 var allDevices = [];
@@ -8,10 +90,7 @@ var dashboardClients = [];
 var deviceIdMap = /* @__PURE__ */ new Map();
 var activeConnectionsMap = /* @__PURE__ */ new Map();
 var deviceCapabilities = /* @__PURE__ */ new Map();
-var dashboardWatches = /* @__PURE__ */ new Map();
-var watchCounts = /* @__PURE__ */ new Map();
-var toWatchKey = (targetDeviceId, toolId) => JSON.stringify([targetDeviceId, toolId]);
-var fromWatchKey = (key) => JSON.parse(key);
+var watches = new WatchRegistry();
 var brokerLogBuffer = [];
 var BROKER_LOG_BUFFER_MAX = 200;
 var MAX_OFFLINE_AGE_MS = 24 * 60 * 60 * 1e3;
@@ -259,54 +338,42 @@ function socketHandle({ io }) {
       }
     }
   }
+  function emitWatchState(key, mode) {
+    const [targetDeviceId, toolId] = fromWatchKey(key);
+    const message = mode === null ? { toolId, targetDeviceId, watching: false, consolidated: true } : {
+      toolId,
+      targetDeviceId,
+      watching: true,
+      stream: mode === "stream",
+      consolidated: true
+    };
+    withTargetUsers(
+      targetDeviceId,
+      (user) => io.to(user.id).emit("devtool-watch", message),
+      `devtool ${mode === null ? "unwatch" : `watch(${mode})`} ${toolId}`
+    );
+  }
   function handleDevtoolWatch(dashboardId, message) {
     const key = toWatchKey(message.targetDeviceId, message.toolId);
-    let watches = dashboardWatches.get(dashboardId);
-    if (!watches) {
-      watches = /* @__PURE__ */ new Set();
-      dashboardWatches.set(dashboardId, watches);
-    }
     if (message.watching) {
-      if (!watches.has(key)) {
-        watches.add(key);
-        watchCounts.set(key, (watchCounts.get(key) ?? 0) + 1);
-      }
+      const mode2 = message.stream === false ? "capture" : "stream";
+      const effective = watches.watch(dashboardId, key, mode2);
       console.log(
-        `${LOG_PREFIX} Dashboard ${dashboardId} watching "${message.toolId}" on ${message.targetDeviceId}`
-      );
-      withTargetUsers(
-        message.targetDeviceId,
-        (user) => io.to(user.id).emit("devtool-watch", message),
-        `devtool watch ${message.toolId}`
+        `${LOG_PREFIX} Dashboard ${dashboardId} watching "${message.toolId}" on ${message.targetDeviceId} (${mode2}, effective ${effective})`
       );
-    } else if (watches.has(key)) {
-      watches.delete(key);
-      decrementWatch(key);
-    }
-  }
-  function decrementWatch(key) {
-    const next = (watchCounts.get(key) ?? 1) - 1;
-    if (next > 0) {
-      watchCounts.set(key, next);
+      emitWatchState(key, effective);
       return;
     }
-    watchCounts.delete(key);
-    const [targetDeviceId, toolId] = fromWatchKey(key);
+    const { changed, mode } = watches.unwatch(dashboardId, key);
+    if (!changed) return;
     console.log(
-      `${LOG_PREFIX} Last dashboard stopped watching "${toolId}" on ${targetDeviceId}`
-    );
-    withTargetUsers(
-      targetDeviceId,
-      (user) => io.to(user.id).emit("devtool-watch", { toolId, targetDeviceId, watching: false }),
-      `devtool unwatch ${toolId}`
+      mode === null ? `${LOG_PREFIX} Last dashboard stopped watching "${message.toolId}" on ${message.targetDeviceId}` : `${LOG_PREFIX} "${message.toolId}" on ${message.targetDeviceId} downgraded to ${mode}`
     );
+    emitWatchState(key, mode);
   }
   function releaseDashboardWatches(dashboardId) {
-    const watches = dashboardWatches.get(dashboardId);
-    if (!watches) return;
-    dashboardWatches.delete(dashboardId);
-    for (const key of watches) {
-      decrementWatch(key);
+    for (const { key, mode } of watches.releaseDashboard(dashboardId)) {
+      emitWatchState(key, mode);
     }
   }
   io.on("connection", (socket) => {
@@ -384,15 +451,20 @@ function socketHandle({ io }) {
       }
       deviceCapabilities.set(message.persistentDeviceId, message);
       forwardToDashboards("devtool-capabilities", message);
-      for (const key of watchCounts.keys()) {
+      for (const key of watches.activeKeys()) {
         const [targetDeviceId, toolId] = fromWatchKey(key);
-        if (targetDeviceId === "All" || targetDeviceId === message.persistentDeviceId) {
-          socket.emit("devtool-watch", {
-            toolId,
-            targetDeviceId,
-            watching: true
-          });
+        if (targetDeviceId !== "All" && targetDeviceId !== message.persistentDeviceId) {
+          continue;
         }
+        const mode = watches.effective(key);
+        if (!mode) continue;
+        socket.emit("devtool-watch", {
+          toolId,
+          targetDeviceId,
+          watching: true,
+          stream: mode === "stream",
+          consolidated: true
+        });
       }
     });
     socket.on("devtool-sync", (message) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buoy-gg/sync-broker",
-  "version": "7.0.17",
+  "version": "7.0.18",
   "description": "Headless Socket.IO broker for the Buoy devtool sync protocol (v1) — routes messages between devices and dashboard/MCP clients",
   "main": "dist/index.js",
   "module": "dist/index.mjs",