@spooky-sync/core 0.0.1-canary.155 → 0.0.1-canary.157

package/dist/index.d.ts

@@ -140,6 +140,11 @@ declare class StreamProcessorService {
   private stateKeySuffix;
   private stateGeneration;
   private persistState;
+  private persistCircuit;
+  private checkpointMs;
+  private checkpointTimer;
+  private snapshotDirty;
+  private pagehideHandler;
   constructor(events: EventSystem<StreamProcessorEvents>, db: LocalStore, persistenceClient: PersistenceClient, logger: Logger);
   /**
    * Add a receiver for stream updates.
@@ -200,8 +205,34 @@ declare class StreamProcessorService {
    * afterwards (a fresh circuit default-denies every table).
    */
   reset(): Promise<void>;
+  /**
+   * Release the wasm circuit and stop checkpointing. Call when the client is
+   * torn down; a recreated client (provider remount, HMR) would otherwise stack
+   * one full circuit per instance.
+   */
+  dispose(): void;
+  /**
+   * Explicitly run the wasm-bindgen destructor. Guarded: stale wasm builds may
+   * not expose `free`, and a double free must not take the app down.
+   */
+  private freeProcessor;
   /** Toggle circuit-state persistence (shared-tabs follower/leader role). */
   setPersistenceEnabled(enabled: boolean): void;
+  /**
+   * Opt into snapshot persistence (`persistCircuit`). Off by default: see the
+   * `persistCircuit` field comment for why per-ingest snapshots were removed.
+   * Must be called before `init()` for a snapshot to be restored at boot.
+   */
+  configureCircuitPersistence(enabled: boolean, checkpointMs?: number): void;
+  /**
+   * Record that the circuit changed. Cheap and O(1), the expensive snapshot is
+   * deferred to the checkpoint timer, and skipped entirely when
+   * `persistCircuit` is off (the default).
+   */
+  private markSnapshotDirty;
+  private startCheckpoints;
+  /** Stop checkpointing and drop the `pagehide` listener. */
+  stopCheckpoints(): void;
   loadState(): Promise<void>;
   /**
    * Seed per-table `select` permission predicates ({ [table]: whereText }).

package/dist/index.js

@@ -5694,16 +5694,20 @@ async function walkOpfs(maxEntries = 2e3, maxDepth = 8) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.155";
-const WASM_VERSION = "0.0.1-canary.155";
+const CORE_VERSION = "0.0.1-canary.157";
+const WASM_VERSION = "0.0.1-canary.157";
 const SURREAL_VERSION = "3.0.3";
-var DevToolsService = class {
+var DevToolsService = class DevToolsService {
 	eventsHistory = [];
 	eventIdCounter = 0;
 	version = CORE_VERSION;
 	backendInfo = emptyBackendInfo();
 	enabled = false;
-	/** Shared-tabs snapshot for the panel, wired by Sp00kyClient when active. */
+	static NOTIFY_MIN_INTERVAL_MS = 250;
+	notifyTimer = null;
+	lastNotifyAt = 0;
+	/** Shared-tabs snapshot for the panel, wired by Sp00kyClient whenever the
+	*  feature was REQUESTED (so an inactive/degraded tab still reports why). */
 	tabsInfoProvider = null;
 	setTabsInfoProvider(provider) {
 		this.tabsInfoProvider = provider;
@@ -5925,6 +5929,7 @@ var DevToolsService = class {
 				status: "unknown",
 				fallback: false
 			},
+			tabs: this.tabsInfoProvider?.() ?? null,
 			browser: {},
 			opfs: {
 				supported: false,
@@ -5969,9 +5974,30 @@ var DevToolsService = class {
 			return { granted: false };
 		}
 	}
+	/**
+	* Request a state push. Coalesced (see {@link NOTIFY_MIN_INTERVAL_MS}): the
+	* first call after an idle period pushes straight away so the panel stays
+	* responsive, and any calls during the window collapse into ONE trailing push
+	* that serializes the state as of the flush, not as of the request. Callers
+	* stay fire-and-forget.
+	*/
 	notifyDevTools() {
 		if (!this.enabled) return;
-		if (typeof window !== "undefined") window.postMessage({
+		if (typeof window === "undefined") return;
+		if (this.notifyTimer !== null) return;
+		const waited = Date.now() - this.lastNotifyAt;
+		if (waited >= DevToolsService.NOTIFY_MIN_INTERVAL_MS) {
+			this.flushNotify();
+			return;
+		}
+		this.notifyTimer = setTimeout(() => {
+			this.notifyTimer = null;
+			if (this.enabled) this.flushNotify();
+		}, DevToolsService.NOTIFY_MIN_INTERVAL_MS - waited);
+	}
+	flushNotify() {
+		this.lastNotifyAt = Date.now();
+		window.postMessage({
 			type: "SP00KY_STATE_CHANGED",
 			source: "sp00ky-devtools-page",
 			state: this.getState()
@@ -6296,6 +6322,14 @@ var AuthService = class {
 
 //#endregion
 //#region src/services/stream-processor/index.ts
+/**
+* Read a circuit snapshot out of the pre-`persistCircuit` persisted shape
+* (`[[{ state }]]`, a raw SurrealDB result). Returns null for anything else.
+*/
+function extractLegacyState(result) {
+	if (Array.isArray(result) && Array.isArray(result[0]) && typeof result[0][0]?.state === "string") return result[0][0].state;
+	return null;
+}
 var StreamProcessorService = class {
 	logger;
 	processor;
@@ -6310,6 +6344,11 @@ var StreamProcessorService = class {
 	stateKeySuffix = "";
 	stateGeneration = 0;
 	persistState = true;
+	persistCircuit = false;
+	checkpointMs = 3e4;
+	checkpointTimer = null;
+	snapshotDirty = false;
+	pagehideHandler = null;
 	constructor(events, db, persistenceClient, logger) {
 		this.events = events;
 		this.db = db;
@@ -6390,7 +6429,7 @@ var StreamProcessorService = class {
 		const buffered = Array.from(this.batchBuffer.values());
 		this.batchBuffer.clear();
 		if (buffered.length > 0) this.dispatchUpdates(buffered);
-		this.saveState();
+		this.markSnapshotDirty();
 	}
 	/**
 	* Initialize the WASM module and processor.
@@ -6434,19 +6473,99 @@ var StreamProcessorService = class {
 		this.stateGeneration++;
 		this.batching = false;
 		this.batchBuffer.clear();
+		this.snapshotDirty = false;
+		const previous = this.processor;
 		this.processor = new Sp00kyProcessor();
+		this.freeProcessor(previous);
 		this.logger.info({ Category: "sp00ky-client::StreamProcessorService::reset" }, "Stream processor reset (fresh circuit)");
 	}
+	/**
+	* Release the wasm circuit and stop checkpointing. Call when the client is
+	* torn down; a recreated client (provider remount, HMR) would otherwise stack
+	* one full circuit per instance.
+	*/
+	dispose() {
+		this.stopCheckpoints();
+		const previous = this.processor;
+		this.processor = void 0;
+		this.isInitialized = false;
+		this.batching = false;
+		this.batchBuffer.clear();
+		this.receivers = [];
+		this.freeProcessor(previous);
+	}
+	/**
+	* Explicitly run the wasm-bindgen destructor. Guarded: stale wasm builds may
+	* not expose `free`, and a double free must not take the app down.
+	*/
+	freeProcessor(processor) {
+		if (!processor || typeof processor.free !== "function") return;
+		try {
+			processor.free();
+		} catch (e) {
+			this.logger.debug({
+				error: e,
+				Category: "sp00ky-client::StreamProcessorService::freeProcessor"
+			}, "Failed to free previous wasm circuit");
+		}
+	}
 	/** Toggle circuit-state persistence (shared-tabs follower/leader role). */
 	setPersistenceEnabled(enabled) {
 		this.persistState = enabled;
+		if (!enabled) this.stopCheckpoints();
+	}
+	/**
+	* Opt into snapshot persistence (`persistCircuit`). Off by default: see the
+	* `persistCircuit` field comment for why per-ingest snapshots were removed.
+	* Must be called before `init()` for a snapshot to be restored at boot.
+	*/
+	configureCircuitPersistence(enabled, checkpointMs) {
+		this.persistCircuit = enabled;
+		if (checkpointMs && checkpointMs > 0) this.checkpointMs = checkpointMs;
+		if (!enabled) this.stopCheckpoints();
+	}
+	/**
+	* Record that the circuit changed. Cheap and O(1), the expensive snapshot is
+	* deferred to the checkpoint timer, and skipped entirely when
+	* `persistCircuit` is off (the default).
+	*/
+	markSnapshotDirty() {
+		if (!this.persistCircuit || !this.persistState) return;
+		this.snapshotDirty = true;
+		this.startCheckpoints();
+	}
+	startCheckpoints() {
+		if (this.checkpointTimer) return;
+		this.checkpointTimer = setInterval(() => {
+			if (!this.snapshotDirty) return;
+			this.snapshotDirty = false;
+			this.saveState();
+		}, this.checkpointMs);
+		if (typeof window !== "undefined" && !this.pagehideHandler) {
+			this.pagehideHandler = () => {
+				if (!this.snapshotDirty) return;
+				this.snapshotDirty = false;
+				this.saveState();
+			};
+			window.addEventListener("pagehide", this.pagehideHandler);
+		}
+	}
+	/** Stop checkpointing and drop the `pagehide` listener. */
+	stopCheckpoints() {
+		if (this.checkpointTimer) {
+			clearInterval(this.checkpointTimer);
+			this.checkpointTimer = null;
+		}
+		if (this.pagehideHandler && typeof window !== "undefined") window.removeEventListener("pagehide", this.pagehideHandler);
+		this.pagehideHandler = null;
+		this.snapshotDirty = false;
 	}
 	async loadState() {
-		if (!this.processor || !this.persistState) return;
+		if (!this.processor || !this.persistState || !this.persistCircuit) return;
 		try {
 			const result = await this.persistenceClient.get(this.stateKey());
-			if (Array.isArray(result) && result.length > 0 && Array.isArray(result[0]) && result[0].length > 0 && result[0][0]?.state) {
-				const state = result[0][0].state;
+			const state = typeof result === "string" ? result : extractLegacyState(result);
+			if (state) {
 				this.logger.info({
 					stateLength: state.length,
 					Category: "sp00ky-client::StreamProcessorService::loadState"
@@ -6500,7 +6619,7 @@ var StreamProcessorService = class {
 		}, "Session auth context updated");
 	}
 	async saveState() {
-		if (!this.processor || !this.persistState) return;
+		if (!this.processor || !this.persistState || !this.persistCircuit) return;
 		const generation = this.stateGeneration;
 		try {
 			if (typeof this.processor.save_state === "function") {
@@ -6559,7 +6678,7 @@ var StreamProcessorService = class {
 				}));
 				this.notifyUpdates(updates);
 			}
-			if (!this.batching) this.saveState();
+			if (!this.batching) this.markSnapshotDirty();
 			return rawUpdates;
 		} catch (e) {
 			this.logger.error({
@@ -6612,7 +6731,7 @@ var StreamProcessorService = class {
 					snapshotMs: initialUpdate.timing_snapshot_ms ?? 0
 				}
 			};
-			this.saveState();
+			this.markSnapshotDirty();
 			this.logger.debug({
 				queryHash: queryPlan.queryHash,
 				surql: queryPlan.surql,
@@ -6635,7 +6754,7 @@ var StreamProcessorService = class {
 		if (!this.processor) return;
 		try {
 			this.processor.unregister_view(queryHash);
-			this.saveState();
+			this.markSnapshotDirty();
 		} catch (e) {
 			this.logger.error({
 				error: e,
@@ -8757,6 +8876,7 @@ var Sp00kyClient = class {
 		else this.persistenceClient = config.persistenceClient;
 		this.persistenceClient = new ResilientPersistenceClient(this.persistenceClient, logger);
 		this.streamProcessor = new StreamProcessorService(new EventSystem(["stream_update"]), this.local, this.persistenceClient, logger);
+		this.streamProcessor.configureCircuitPersistence(config.persistCircuit ?? false, config.circuitCheckpointMs);
 		this.migrator = new LocalMigrator(this.local, logger);
 		this.cache = new CacheModule(this.local, this.streamProcessor, (update) => {
 			this.dataModule.onStreamUpdate(update);
@@ -8784,24 +8904,33 @@ var Sp00kyClient = class {
 		this.devTools = new DevToolsService(this.local, this.remote, logger, this.config.schema, this.auth, this.dataModule);
 		this.streamProcessor.addReceiver(this.devTools);
 		this.setupCallbacks();
-		if (tabsSupport.supported) {
-			this.tabsCoordinator = this.buildTabsCoordinator();
+		if (tabsSupport.supported) this.tabsCoordinator = this.buildTabsCoordinator();
+		else if (this.config.sharedTabs) this.logger.info({
+			reason: tabsSupport.reason,
+			Category: "sp00ky-client::Sp00kyClient::tabs"
+		}, "sharedTabs requested but unsupported here; running solo");
+		if (this.config.sharedTabs) {
+			const unsupportedReason = tabsSupport.supported ? void 0 : tabsSupport.reason;
 			this.devTools.setTabsInfoProvider(() => {
-				if (!this.sharedActive || !this.tabsCoordinator) return null;
 				const c = this.tabsCoordinator;
+				if (!this.sharedActive || !c) return {
+					active: false,
+					reason: unsupportedReason ?? "fell-back"
+				};
+				const hub = c.syncHub;
 				return {
+					active: true,
 					role: c.role,
 					tabId: c.tabId,
 					leadershipId: c.leadershipId,
-					leaderTabId: c.leaderTabId,
-					followers: c.syncHub?.followerCount ?? null,
-					relayedBatches: c.syncHub?.relayedBatches ?? null
+					leaderTabId: c.role === "leader" ? c.tabId : c.leaderTabId,
+					...hub ? {
+						followers: hub.followerCount,
+						relayedBatches: hub.relayedBatches
+					} : {}
 				};
 			});
-		} else if (this.config.sharedTabs) this.logger.info({
-			reason: tabsSupport.reason,
-			Category: "sp00ky-client::Sp00kyClient::tabs"
-		}, "sharedTabs requested but unsupported here; running solo");
+		}
 	}
 	/** The shared-tabs role machinery, wired to this client's modules. */
 	buildTabsCoordinator() {
@@ -8810,7 +8939,7 @@ var Sp00kyClient = class {
 		return new TabsCoordinator({
 			tabId,
 			fingerprint: computeTabsFingerprint({
-				coreVersion: "0.0.1-canary.155",
+				coreVersion: "0.0.1-canary.157",
 				schemaHash: hash53(this.config.schemaSurql),
 				endpoint: this.config.database.endpoint ?? "",
 				namespace: this.config.database.namespace,
@@ -9106,6 +9235,7 @@ var Sp00kyClient = class {
 		if (this.tabsCoordinator) await this.tabsCoordinator.stop();
 		await this.local.close();
 		await this.remote.close();
+		this.streamProcessor.dispose();
 	}
 	/**
 	* Subscribe to a feature flag for the current user. Returns a

package/dist/types.d.ts

@@ -199,6 +199,13 @@ interface EngineStorageDiagnostics {
   }[];
   error?: string;
 }
+/**
+ * Shared-tabs coordination state. Reported ONLY when `sharedTabs: true` was
+ * configured (apps that never asked for it get `null`, so the panel shows
+ * nothing). `active: false` with a `reason` is itself the useful signal: the
+ * app asked to share one store and this tab is not, so it owns or contends for
+ * the OPFS pool alone.
+ */
 //#endregion
 //#region src/services/database/cache-engine.d.ts
 /**
@@ -488,6 +495,29 @@ interface Sp00kyConfig<S extends SchemaStructure> {
    * Inspect via `window.__00__.getState().database.tabs` and `__sqliteStats`.
    */
   sharedTabs?: boolean;
+  /**
+   * Persist the in-browser SSP circuit (store + view caches) as a snapshot so a
+   * reload can restore it instead of re-materializing. Default `false`, and
+   * that default is deliberate.
+   *
+   * The circuit is DERIVED state: the durable local store (OPFS SQLite) is the
+   * source of truth, and every first paint already reads row bodies from it
+   * (`DataManager.createNewQuery` / `materializeRecords`) using the circuit only
+   * for row identity and ordering. A snapshot buys nothing on reload while
+   * costing a full deep clone of every row of every ingested table plus a JSON
+   * encode of the result, `Circuit::save` in the Rust core, mirroring the
+   * server's rule in `ssp-node`: *never per-ingest*.
+   *
+   * When enabled, snapshots are written on a checkpoint interval
+   * ({@link circuitCheckpointMs}) and on `pagehide`, never per ingest or per
+   * query registration. Enable only for a workload that has measured a win.
+   */
+  persistCircuit?: boolean;
+  /**
+   * Checkpoint interval in milliseconds for {@link persistCircuit}. Defaults to
+   * 30000. Ignored when `persistCircuit` is off.
+   */
+  circuitCheckpointMs?: number;
   /** A pino browser transmit object for forwarding logs (e.g. via @spooky-sync/core/otel). */
   otelTransmit?: PinoTransmit;
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.155",
+  "version": "0.0.1-canary.157",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -60,8 +60,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.155",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.155",
+    "@spooky-sync/query-builder": "0.0.1-canary.157",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.157",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "fast-json-patch": "^3.1.1",

package/src/modules/devtools/index.ts

@@ -22,7 +22,7 @@ import {
   parseBackendInfo,
   UNAVAILABLE,
 } from './versions';
-import { walkOpfs, type StorageInfo } from './storage-info';
+import { walkOpfs, type SharedTabsInfo, type StorageInfo } from './storage-info';
 
 // Real bundled frontend versions, injected at build time by tsdown's
 // version-define plugin (see tsdown.config.ts). The `typeof` guard keeps these
@@ -51,10 +51,23 @@ export class DevToolsService implements StreamUpdateReceiver {
   // (the on-demand GET_STATE pull) still works before the push channel turns on.
   private enabled = false;
 
-  /** Shared-tabs snapshot for the panel, wired by Sp00kyClient when active. */
-  private tabsInfoProvider: (() => Record<string, unknown> | null) | null = null;
-
-  setTabsInfoProvider(provider: () => Record<string, unknown> | null): void {
+  // A state push serializes EVERY active query's full record set (see
+  // `getActiveQueries`) and postMessage clones it again, so its cost scales with
+  // the whole client dataset — and it is triggered per event, including one per
+  // local DB query (`DATABASE_LOCAL_QUERY` → `logEvent`). Unthrottled, a single
+  // page load's few hundred local queries turn a handful of MB of rows into GBs
+  // of short-lived large-object garbage and OOM the renderer (V8
+  // "young object promotion failed"). Coalesce instead: push immediately when
+  // idle, then at most once per window, always serializing the LATEST state.
+  private static readonly NOTIFY_MIN_INTERVAL_MS = 250;
+  private notifyTimer: ReturnType<typeof setTimeout> | null = null;
+  private lastNotifyAt = 0;
+
+  /** Shared-tabs snapshot for the panel, wired by Sp00kyClient whenever the
+   *  feature was REQUESTED (so an inactive/degraded tab still reports why). */
+  private tabsInfoProvider: (() => SharedTabsInfo | null) | null = null;
+
+  setTabsInfoProvider(provider: () => SharedTabsInfo | null): void {
     this.tabsInfoProvider = provider;
   }
 
@@ -357,6 +370,7 @@ export class DevToolsService implements StreamUpdateReceiver {
         bucketId: this.databaseService.currentBucketId,
       },
       health: this.databaseService.storageHealth ?? { status: 'unknown', fallback: false },
+      tabs: this.tabsInfoProvider?.() ?? null,
       browser: {},
       opfs: { supported: false, entries: [], totalBytes: 0, truncated: false },
     };
@@ -406,19 +420,42 @@ export class DevToolsService implements StreamUpdateReceiver {
     }
   }
 
+  /**
+   * Request a state push. Coalesced (see {@link NOTIFY_MIN_INTERVAL_MS}): the
+   * first call after an idle period pushes straight away so the panel stays
+   * responsive, and any calls during the window collapse into ONE trailing push
+   * that serializes the state as of the flush, not as of the request. Callers
+   * stay fire-and-forget.
+   */
   private notifyDevTools() {
     // No consumer attached → no getState() serialization, no postMessage broadcast.
     if (!this.enabled) return;
-    if (typeof window !== 'undefined') {
-      window.postMessage(
-        {
-          type: 'SP00KY_STATE_CHANGED',
-          source: 'sp00ky-devtools-page',
-          state: this.getState(),
-        },
-        '*'
-      );
+    if (typeof window === 'undefined') return;
+    // A trailing push is already queued; it will carry this change too.
+    if (this.notifyTimer !== null) return;
+
+    const waited = Date.now() - this.lastNotifyAt;
+    if (waited >= DevToolsService.NOTIFY_MIN_INTERVAL_MS) {
+      this.flushNotify();
+      return;
     }
+    this.notifyTimer = setTimeout(() => {
+      this.notifyTimer = null;
+      // Still gated on `enabled`: the panel may have disconnected while queued.
+      if (this.enabled) this.flushNotify();
+    }, DevToolsService.NOTIFY_MIN_INTERVAL_MS - waited);
+  }
+
+  private flushNotify() {
+    this.lastNotifyAt = Date.now();
+    window.postMessage(
+      {
+        type: 'SP00KY_STATE_CHANGED',
+        source: 'sp00ky-devtools-page',
+        state: this.getState(),
+      },
+      '*'
+    );
   }
 
   private serializeForDevTools(data: any, seen = new WeakSet<object>()): any {

package/src/modules/devtools/notify-throttle.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { RecordId } from 'surrealdb';
+import { DevToolsService } from './index';
+
+/**
+ * A state push serializes EVERY active query's full record set and postMessage
+ * clones it again, so its cost scales with the whole client dataset. It is
+ * requested per event — including one per local DB query — so without
+ * coalescing a page load's few hundred local queries turn a few MB of rows into
+ * GBs of short-lived large-object garbage and OOM the renderer. These tests pin
+ * the coalescing, not the payload.
+ */
+
+function harness(recordCount = 500) {
+  const posted: any[] = [];
+  const listeners: ((e: any) => void)[] = [];
+  const fakeWindow: any = {
+    postMessage: (msg: any) => posted.push(msg),
+    addEventListener: (_type: string, cb: (e: any) => void) => listeners.push(cb),
+    dispatchEvent: () => true,
+  };
+  fakeWindow.self = fakeWindow;
+  vi.stubGlobal('window', fakeWindow);
+  vi.stubGlobal('CustomEvent', class {
+    type: string;
+    constructor(type: string) {
+      this.type = type;
+    }
+  });
+
+  const noop = () => {};
+  const logger: any = { debug: noop, info: noop, warn: noop, error: noop, trace: noop };
+  logger.child = () => logger;
+
+  const local: any = {
+    query: async () => [],
+    getConfig: () => ({ store: 'memory' }),
+    currentBucketId: 'anon',
+    storageHealth: { status: 'memory', fallback: false },
+  };
+  const remote: any = { query: async () => [] };
+  const auth: any = {
+    isAuthenticated: false,
+    currentUser: undefined,
+    eventSystem: { subscribe: noop },
+  };
+  // One query holding a lot of rows: the thing whose repeated serialization is
+  // what actually blows the heap.
+  const records = Array.from({ length: recordCount }, (_, i) => ({ id: `game:${i}`, pgn: 'x' }));
+  const dataManager: any = {
+    getActiveQueries: () => [
+      {
+        config: { id: new RecordId('_00_query', 'q1'), params: {} },
+        status: 'idle',
+        records,
+        updateCount: 1,
+      },
+    ],
+    phaseTimings: () => ({}),
+  };
+
+  const service = new DevToolsService(local, remote, logger, { tables: [] } as any, auth, dataManager);
+  // Announce a consumer, exactly like the extension's page-script does.
+  for (const cb of listeners) {
+    cb({ source: fakeWindow, data: { type: 'SP00KY_DEVTOOLS_CONNECT' } });
+  }
+  const statePushes = () => posted.filter((m) => m.type === 'SP00KY_STATE_CHANGED');
+  return { service, statePushes, posted };
+}
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+});
+
+describe('DevToolsService state-push coalescing', () => {
+  it('pushes once immediately on connect', () => {
+    vi.useFakeTimers();
+    const { statePushes } = harness();
+    expect(statePushes().length).toBe(1);
+  });
+
+  it('collapses a burst of per-query events into ONE trailing push', () => {
+    vi.useFakeTimers();
+    const { service, statePushes } = harness();
+    const before = statePushes().length;
+
+    // What a page load looks like: hundreds of LOCAL_QUERY events, each of which
+    // used to serialize the entire query state.
+    for (let i = 0; i < 400; i++) {
+      (service as any).logEvent('LOCAL_QUERY', { query: 'SELECT * FROM game', vars: {} });
+    }
+    // Nothing extra yet — the burst is queued, not serialized 400 times.
+    expect(statePushes().length).toBe(before);
+
+    vi.advanceTimersByTime(300);
+    expect(statePushes().length).toBe(before + 1);
+  });
+
+  it('still pushes again once the window has passed', () => {
+    vi.useFakeTimers();
+    const { service, statePushes } = harness();
+    const before = statePushes().length;
+
+    (service as any).logEvent('A', {});
+    vi.advanceTimersByTime(300);
+    expect(statePushes().length).toBe(before + 1);
+
+    // An event arriving right after that flush is still inside the window, so it
+    // queues rather than pushing again...
+    (service as any).logEvent('B', {});
+    expect(statePushes().length).toBe(before + 1);
+    vi.advanceTimersByTime(300);
+    expect(statePushes().length).toBe(before + 2);
+
+    // ...but once the tab has been idle past the window, the next event pushes
+    // straight away, so the panel never waits on a quiet app.
+    vi.advanceTimersByTime(1000);
+    (service as any).logEvent('C', {});
+    expect(statePushes().length).toBe(before + 3);
+  });
+
+  it('drops a queued push when the consumer disconnects mid-window', () => {
+    vi.useFakeTimers();
+    const { service, statePushes, posted } = harness();
+    const before = statePushes().length;
+
+    (service as any).logEvent('A', {});
+    (service as any).enabled = false; // panel closed while the push was queued
+    vi.advanceTimersByTime(300);
+    expect(statePushes().length).toBe(before);
+    expect(posted.some((m) => m.type === 'SP00KY_STATE_CHANGED' && m.state === undefined)).toBe(false);
+  });
+
+  it('serializes the LATEST state at flush time, not at request time', () => {
+    vi.useFakeTimers();
+    const { service, statePushes } = harness();
+
+    (service as any).logEvent('FIRST', {});
+    (service as any).logEvent('SECOND', {});
+    vi.advanceTimersByTime(300);
+
+    const last = statePushes().at(-1);
+    const types = last.state.eventsHistory.map((e: any) => e.eventType);
+    // Both events of the coalesced window are present in the single push.
+    expect(types).toContain('FIRST');
+    expect(types).toContain('SECOND');
+  });
+});