@spooky-sync/core 0.0.1-canary.161 → 0.0.1-canary.162

package/src/modules/sync/sync.reconnect.test.ts

@@ -0,0 +1,145 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Sp00kySync } from './sync';
+
+// The reconnect handler re-registers active queries and re-issues the ref LIVE.
+// It must fire on BOTH drop paths, and the distinction is the whole bug:
+//
+//   - recovered drop:  error -> reconnecting -> connected   (no `disconnected`!)
+//   - gave-up drop:    error -> disconnected -> (supervisor) -> connected
+//
+// Watching only `disconnected` therefore misses every *successful* reconnect —
+// the common case — and leaves the dead server-side LIVE in place with the
+// list_ref poll silently the only sync path.
+
+/** Minimal stand-in for the SDK's event publisher. */
+function makeClient() {
+  const listeners = new Map<string, Array<(...a: any[]) => void>>();
+  return {
+    subscribe(event: string, cb: (...a: any[]) => void) {
+      const arr = listeners.get(event) ?? [];
+      arr.push(cb);
+      listeners.set(event, arr);
+      return () => {
+        /* noop */
+      };
+    },
+    emit(event: string, ...args: any[]) {
+      for (const cb of listeners.get(event) ?? []) cb(...args);
+    },
+    liveOf: async () => ({ subscribe: () => () => {} }),
+  };
+}
+
+function makeSync(hashes: string[], userId: string | null = 'user:alice') {
+  const logger: any = {
+    child: () => logger,
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    trace: () => {},
+  };
+  const client = makeClient();
+  const status = { value: 'connected' as string };
+  const remote: any = {
+    query: vi.fn().mockResolvedValue(['live-uuid']),
+    getClient: () => client,
+    getStatus: () => status.value,
+  };
+  const dataModule: any = {
+    getActiveQueryHashes: () => hashes,
+    getCurrentUserId: () => userId,
+  };
+
+  const sync = new Sp00kySync({} as any, remote, {} as any, dataModule, {} as any, logger);
+
+  // `subscribeToReconnect` is normally wired from init(), which would also start
+  // timers and load the outbox. Call it directly instead.
+  (sync as any).currentUserId = userId;
+  (sync as any).subscribeToReconnect();
+
+  const enqueued: any[] = [];
+  (sync as any).scheduler = { enqueueDownEvent: (e: any) => enqueued.push(e) };
+
+  return { sync, client, remote, enqueued, status };
+}
+
+/** Let the `connected` handler's un-awaited `restartRefLiveQuery()` chain run. */
+const flush = () => new Promise((r) => setTimeout(r, 0));
+
+describe('sync reconnect re-subscription', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('re-registers queries and restarts LIVE on a recovered drop (reconnecting -> connected)', async () => {
+    const { client, remote, enqueued } = makeSync(['h1', 'h2']);
+
+    // The SDK's own reconnect: no `disconnected` is ever published.
+    client.emit('reconnecting');
+    client.emit('connected');
+    await flush();
+
+    expect(enqueued).toEqual([
+      { type: 'register', payload: { hash: 'h1' } },
+      { type: 'register', payload: { hash: 'h2' } },
+    ]);
+    const sqls = (remote.query as any).mock.calls.map((c: any[]) => c[0]);
+    expect(sqls.some((s: string) => s.startsWith('LIVE SELECT'))).toBe(true);
+  });
+
+  it('re-registers queries and restarts LIVE after the SDK gives up (disconnected -> connected)', async () => {
+    const { client, remote, enqueued } = makeSync(['h1']);
+
+    client.emit('disconnected');
+    client.emit('connected');
+    await flush();
+
+    expect(enqueued).toEqual([{ type: 'register', payload: { hash: 'h1' } }]);
+    const sqls = (remote.query as any).mock.calls.map((c: any[]) => c[0]);
+    expect(sqls.some((s: string) => s.startsWith('LIVE SELECT'))).toBe(true);
+  });
+
+  it('does nothing on the initial connect', async () => {
+    const { client, remote, enqueued } = makeSync(['h1']);
+
+    client.emit('connected');
+    await flush();
+
+    expect(enqueued).toEqual([]);
+    expect(remote.query).not.toHaveBeenCalled();
+  });
+
+  it('only reacts once per drop', async () => {
+    const { client, enqueued } = makeSync(['h1']);
+
+    client.emit('reconnecting');
+    client.emit('connected');
+    await flush();
+    // A spurious second `connected` (e.g. a re-published event) must not
+    // trigger a second refetch storm.
+    client.emit('connected');
+    await flush();
+
+    expect(enqueued).toHaveLength(1);
+  });
+
+  it("does not KILL the dead session's LIVE uuid on reconnect", async () => {
+    const { sync, client, remote } = makeSync(['h1']);
+    // A LIVE was running before the drop. Its uuid belongs to the old
+    // WebSocket session, so KILLing it on the new socket is pointless work
+    // queued ahead of the restart that actually matters.
+    const unsub = vi.fn();
+    (sync as any).currentLiveQueryUuid = 'stale-uuid';
+    (sync as any).liveQueryUnsubscribe = unsub;
+
+    client.emit('reconnecting');
+    expect(unsub).toHaveBeenCalled();
+    expect((sync as any).currentLiveQueryUuid).toBeNull();
+
+    client.emit('connected');
+    await flush();
+
+    const sqls = (remote.query as any).mock.calls.map((c: any[]) => c[0]);
+    expect(sqls.some((q: string) => q.includes('KILL'))).toBe(false);
+    expect(sqls.some((q: string) => q.startsWith('LIVE SELECT'))).toBe(true);
+  });
+});

package/src/modules/sync/sync.ts

@@ -1,5 +1,10 @@
-import type { LocalStore, RemoteDatabaseService } from '../../services/database/index';
 import type {
+  ConnectionSupervisor,
+  LocalStore,
+  RemoteDatabaseService,
+} from '../../services/database/index';
+import type {
+  ConnectionState,
   RecordVersionArray,
   RecordVersionDiff,
   SyncHealth,
@@ -11,6 +16,7 @@ import type { DownEvent, UpEvent } from './queue/index';
 import { DownQueue, UpQueue } from './queue/index';
 import type { RecordId, Uuid } from 'surrealdb';
 import {
+  applyRecordVersionDiff,
   ArraySyncer,
   buildListRefSelect,
   buildSubqueryListRefSelect,
@@ -31,6 +37,7 @@ import {
   extractIdPart,
   extractTablePart,
   surql,
+  withTimeout,
 } from '../../utils/index';
 import { ANON_USER_ID, DEFAULT_REF_MODE, listRefTableFor, RefMode } from '../ref-tables';
 import { mutationOwnerTabId } from '../data/mutation-id';
@@ -66,6 +73,13 @@ export interface Sp00kySyncOptions {
    * up-queue for the session. Defaults to 30000; `0` disables the timeout.
    */
   pushTimeoutMs?: number;
+  /**
+   * Transport supervisor. Sync reads its state to report `connection` in
+   * {@link SyncHealth} so a UI can show "reconnecting…" the instant the socket
+   * drops, without waiting for the degrade threshold. Optional: omitted in
+   * tests, where `connection` then reports `connected`.
+   */
+  connectionSupervisor?: ConnectionSupervisor;
 }
 
 /**
@@ -87,7 +101,12 @@ export class Sp00kySync<S extends SchemaStructure> {
     return this.syncEngine.events;
   }
   private scheduler: SyncScheduler;
-  private wasDisconnected: boolean = false;
+  /**
+   * Set by any event that means the socket we registered on is gone, so the
+   * next `connected` knows it must re-subscribe rather than treat itself as the
+   * initial connect. See {@link subscribeToReconnect}.
+   */
+  private needsResubscribe: boolean = false;
   public events = createSyncEventSystem();
 
   // Auth identity that drives per-user `_00_list_ref_user_<id>` routing
@@ -216,6 +235,18 @@ export class Sp00kySync<S extends SchemaStructure> {
   private static readonly SELF_HEAL_BASE_MS = 2_000;
   private static readonly SELF_HEAL_MAX_MS = 30_000;
 
+  /**
+   * Transport supervisor, when one was supplied. Sync only reads state from it;
+   * it never drives reconnects itself.
+   */
+  private readonly connectionSupervisor?: ConnectionSupervisor;
+  /**
+   * Mirror of the supervisor's state. Defaults to `connected` so a client
+   * constructed without a supervisor (tests, embedders) reports the same health
+   * shape it always has rather than a permanent false "disconnected".
+   */
+  private connectionState: ConnectionState = 'connected';
+
   /** Current sync-health snapshot. */
   get syncHealth(): SyncHealth {
     return {
@@ -224,6 +255,7 @@ export class Sp00kySync<S extends SchemaStructure> {
       kind: this.syncHealthStatus === 'degraded' ? this.lastSyncErrorKind : undefined,
       error: this.syncHealthStatus === 'degraded' ? this.lastSyncErrorMessage : undefined,
       everConnected: this.hasSyncedOnce,
+      connection: this.connectionState,
     };
   }
 
@@ -244,6 +276,25 @@ export class Sp00kySync<S extends SchemaStructure> {
     this.events.emit(SyncEventTypes.SyncHealthChanged, this.syncHealth);
   }
 
+  /**
+   * Mirror the supervisor's transport state into {@link SyncHealth} and emit on
+   * every change, so a UI can react to a dropped socket immediately instead of
+   * waiting for `degradeAfterFailures` failed rounds. `status` is untouched:
+   * a brief reconnect is not a degradation.
+   *
+   * No explicit unsubscribe: the supervisor is owned by the same client and
+   * drops all subscribers in its own `dispose()`, which `Sp00kyClient.close()`
+   * calls first.
+   */
+  private subscribeToConnectionState(): void {
+    if (!this.connectionSupervisor) return;
+    this.connectionSupervisor.subscribe((state) => {
+      if (this.connectionState === state) return;
+      this.connectionState = state;
+      this.emitSyncHealth();
+    });
+  }
+
   /**
    * Fed by the scheduler once per drained sync round. Individual failures are
    * absorbed by the queue's retry; only a run of `degradeAfterFailures`
@@ -392,6 +443,7 @@ export class Sp00kySync<S extends SchemaStructure> {
     this.anonLiveEnabled = options?.anonymousLiveQueries ?? false;
     this.degradeAfterFailures = Math.max(0, options?.degradeAfterConsecutiveFailures ?? 3);
     this.pushTimeoutMs = Math.max(0, options?.pushTimeoutMs ?? 30_000);
+    this.connectionSupervisor = options?.connectionSupervisor;
   }
 
   /**
@@ -404,6 +456,7 @@ export class Sp00kySync<S extends SchemaStructure> {
     this.isInit = true;
     await this.scheduler.init({ loadOutbox: this.tabRole !== 'follower' });
     this.subscribeToReconnect();
+    this.subscribeToConnectionState();
     void this.scheduler.syncUp();
     void this.scheduler.syncDown();
     // No initial LIVE subscription — wait for `setCurrentUserId` to fire
@@ -905,13 +958,20 @@ export class Sp00kySync<S extends SchemaStructure> {
       this.liveQueryUnsubscribe = null;
     }
     if (this.currentLiveQueryUuid !== null) {
-      try {
-        await this.remote.query('KILL $u', { u: this.currentLiveQueryUuid });
-      } catch (err) {
-        this.logger.debug(
-          { err, Category: 'sp00ky-client::Sp00kySync::killRefLiveQuery' },
-          'Prior LIVE KILL failed; continuing'
-        );
+      // A LIVE subscription is scoped to its WebSocket session, so after a
+      // reconnect the server-side one is already gone and there is nothing to
+      // KILL. Sending it anyway either fails (no connection) or races the fresh
+      // socket's readiness while holding up the restart behind it. Local
+      // bookkeeping is cleared either way.
+      if (this.remote.getStatus() === 'connected') {
+        try {
+          await this.remote.query('KILL $u', { u: this.currentLiveQueryUuid });
+        } catch (err) {
+          this.logger.debug(
+            { err, Category: 'sp00ky-client::Sp00kySync::killRefLiveQuery' },
+            'Prior LIVE KILL failed; continuing'
+          );
+        }
       }
       this.currentLiveQueryUuid = null;
     }
@@ -922,21 +982,58 @@ export class Sp00kySync<S extends SchemaStructure> {
     await this.startRefLiveQueries();
   }
 
-  // Only the connect that follows a prior disconnect counts as a
-  // reconnect; the initial connect after init() must not trigger a
-  // refetch storm.
+  /**
+   * Drop local LIVE bookkeeping without issuing a `KILL`.
+   *
+   * Called when the socket dies. The server-side subscription is scoped to that
+   * WebSocket session and died with it, so there is nothing left to kill — and
+   * by the time the reconnect handler runs, the client reports `connected`
+   * again, which would otherwise send a `KILL` for a stale uuid on the *new*
+   * session and hold up the restart queued behind it.
+   */
+  private invalidateRefLiveQuery(): void {
+    if (this.liveQueryUnsubscribe) {
+      try {
+        this.liveQueryUnsubscribe();
+      } catch {
+        /* ignore */
+      }
+      this.liveQueryUnsubscribe = null;
+    }
+    this.currentLiveQueryUuid = null;
+  }
+
+  // Only the connect that follows a prior drop counts as a reconnect; the
+  // initial connect after init() must not trigger a refetch storm.
+  //
+  // Both drop events have to be watched. The SDK publishes `disconnected` ONLY
+  // when it has given up entirely (attempts exhausted, or the engine
+  // terminated); an ordinary recovered drop goes `error` -> `reconnecting` ->
+  // `connected` and never touches `disconnected`. Listening for `disconnected`
+  // alone therefore misses every successful reconnect — the exact case this
+  // handler exists for — and leaves the dead server-side LIVE in place with the
+  // poll as the only sync path.
   private subscribeToReconnect() {
     const client = this.remote.getClient();
     client.subscribe('disconnected', () => {
-      this.wasDisconnected = true;
+      this.needsResubscribe = true;
+      this.invalidateRefLiveQuery();
       this.logger.info(
         { Category: 'sp00ky-client::Sp00kySync::onDisconnect' },
         'Remote disconnected'
       );
     });
+    client.subscribe('reconnecting', () => {
+      this.needsResubscribe = true;
+      this.invalidateRefLiveQuery();
+      this.logger.info(
+        { Category: 'sp00ky-client::Sp00kySync::onReconnecting' },
+        'Remote socket dropped; awaiting reconnect'
+      );
+    });
     client.subscribe('connected', () => {
-      if (!this.wasDisconnected) return;
-      this.wasDisconnected = false;
+      if (!this.needsResubscribe) return;
+      this.needsResubscribe = false;
       this.logger.info(
         { Category: 'sp00ky-client::Sp00kySync::onReconnect' },
         'Remote reconnected, refetching active queries'
@@ -1082,7 +1179,29 @@ export class Sp00kySync<S extends SchemaStructure> {
     // `config.id` is `_00_query:<hash>`, so its id-part IS the query hash
     // (a SHA-256 over query content + sessionId) — the key DataModule uses.
     const hash = extractIdPart(existing.config.id);
+
+    // Apply the event to `remoteArray` — the authoritative membership rows are
+    // now rendered FROM. Only registration and the poll used to write it, so a
+    // LIVE removal left the departed id in the list (in memory and persisted)
+    // until the next poll tick, which is up to 5s of showing a deleted row. This
+    // also persists the durable `_00_window` mirror, so the removal survives a
+    // reload with no network.
+    if (existing.config.membershipKnown && (diff.removed.length || diff.added.length)) {
+      const next = applyRecordVersionDiff(existing.config.remoteArray ?? [], diff);
+      if (!recordVersionArraysEqual(next, existing.config.remoteArray ?? [])) {
+        await this.dataModule.updateQueryRemoteArray(hash, next);
+      }
+    }
+
     await this.runSyncForQuery(hash, diff);
+
+    // A removal-only diff sets `fetching` false in `runSyncForQuery`, so it gets
+    // no `flushPendingStreamUpdate`/`endFetching` re-render — and a removal needs
+    // no record fetch to trigger one either. Force it, mirroring what the poll
+    // path already does for its own removals (`refetchListRefForQuery`).
+    if (diff.removed.length > 0 && diff.added.length === 0 && diff.updated.length === 0) {
+      await this.dataModule.notifyQuerySynced(hash);
+    }
   }
 
   /**
@@ -1156,22 +1275,11 @@ export class Sp00kySync<S extends SchemaStructure> {
    * retries rather than rolling the mutation back.
    */
   private withPushTimeout<T>(promise: Promise<T>, label: string): Promise<T> {
-    if (!(this.pushTimeoutMs > 0)) return promise;
-    return new Promise<T>((resolve, reject) => {
-      const timer = setTimeout(() => {
-        reject(new Error(`Mutation push timed out after ${this.pushTimeoutMs}ms (${label})`));
-      }, this.pushTimeoutMs);
-      promise.then(
-        (value) => {
-          clearTimeout(timer);
-          resolve(value);
-        },
-        (err) => {
-          clearTimeout(timer);
-          reject(err);
-        }
-      );
-    });
+    return withTimeout(
+      promise,
+      this.pushTimeoutMs,
+      `Mutation push timed out after ${this.pushTimeoutMs}ms (${label})`
+    );
   }
 
   private async processUpEvent(event: UpEvent) {
@@ -1424,18 +1532,10 @@ export class Sp00kySync<S extends SchemaStructure> {
    * would otherwise resurrect a just-deleted record.
    */
   private async getPendingDeleteIds(): Promise<Set<string>> {
-    try {
-      const [rows] = await this.local.query<[{ recordId: RecordId<string> }[]]>(
-        "SELECT recordId FROM _00_pending_mutations WHERE mutationType = 'delete'"
-      );
-      return new Set((rows ?? []).map((r) => encodeRecordId(r.recordId)));
-    } catch (err) {
-      this.logger.warn(
-        { err, Category: 'sp00ky-client::Sp00kySync::getPendingDeleteIds' },
-        'Failed to read pending deletes; sync may briefly resurrect a just-deleted record'
-      );
-      return new Set();
-    }
+    // Single implementation, shared with the render path: `materializeRecords`
+    // subtracts the same set so a row whose DELETE is still in the outbox is
+    // neither re-fetched here nor rendered there.
+    return (await this.dataModule.getPendingRecordIds()).deletes;
   }
 
   /**

package/src/services/database/connection-supervisor.test.ts

@@ -0,0 +1,255 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { ConnectionSupervisor } from './connection-supervisor';
+import type { ReconnectConfig } from '../../types';
+
+// The supervisor covers the two failure modes the SDK's own reconnect cannot:
+//   - it stopped trying (attempts exhausted, or its post-reconnect handshake
+//     threw and it terminated the engine) — nothing else would ever reconnect
+//   - the socket never closed at all (half-open: peer gone, readyState OPEN,
+//     no `close` event, so no reconnect is ever triggered)
+
+const CONFIG: Required<ReconnectConfig> = {
+  attempts: -1,
+  retryDelayMax: 8_000,
+  heartbeatIntervalMs: 1_000,
+  heartbeatTimeoutMs: 500,
+  superviseRetryDelayMaxMs: 4_000,
+};
+
+function makeRemote() {
+  const handlers = new Map<string, Array<(...a: any[]) => void>>();
+  const state = { status: 'connected' as string };
+  const remote: any = {
+    getStatus: () => state.status,
+    getReconnectConfig: () => CONFIG,
+    subscribeConnection: (event: string, cb: (...a: any[]) => void) => {
+      const arr = handlers.get(event) ?? [];
+      arr.push(cb);
+      handlers.set(event, arr);
+      return () => {
+        handlers.set(
+          event,
+          (handlers.get(event) ?? []).filter((h) => h !== cb)
+        );
+      };
+    },
+    connect: vi.fn().mockImplementation(async () => {
+      state.status = 'connected';
+    }),
+    forceClose: vi.fn().mockImplementation(async () => {
+      state.status = 'disconnected';
+      emit('disconnected');
+    }),
+    query: vi.fn().mockResolvedValue([true]),
+  };
+  function emit(event: string, ...args: any[]) {
+    for (const cb of Array.from(handlers.get(event) ?? [])) cb(...args);
+  }
+  return { remote, emit, state, handlerCount: () => handlers.size };
+}
+
+const silentLogger: any = (() => {
+  const l: any = {
+    child: () => l,
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    trace: () => {},
+  };
+  return l;
+})();
+
+function makeSupervisor(remote: any) {
+  return new ConnectionSupervisor(remote, silentLogger, CONFIG);
+}
+
+describe('ConnectionSupervisor', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.clearAllMocks();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+  });
+
+  it('reconnects after the SDK gives up, retrying on backoff until it succeeds', async () => {
+    const { remote, emit, state } = makeRemote();
+    // Two failures, then success — proves the loop keeps going rather than
+    // giving up like the SDK does.
+    remote.connect
+      .mockRejectedValueOnce(new Error('refused'))
+      .mockRejectedValueOnce(new Error('refused'))
+      .mockImplementationOnce(async () => {
+        state.status = 'connected';
+        emit('connected');
+      });
+
+    const sup = makeSupervisor(remote);
+    sup.start();
+
+    state.status = 'disconnected';
+    emit('disconnected');
+    expect(sup.connection).toBe('disconnected');
+
+    // 1s, then 2s, then 4s (capped at superviseRetryDelayMaxMs).
+    await vi.advanceTimersByTimeAsync(1_000);
+    expect(remote.connect).toHaveBeenCalledTimes(1);
+    expect(sup.connection).toBe('reconnecting');
+
+    await vi.advanceTimersByTimeAsync(2_000);
+    expect(remote.connect).toHaveBeenCalledTimes(2);
+
+    await vi.advanceTimersByTimeAsync(4_000);
+    expect(remote.connect).toHaveBeenCalledTimes(3);
+    expect(sup.connection).toBe('connected');
+
+    // Recovered: no further attempts.
+    await vi.advanceTimersByTimeAsync(30_000);
+    expect(remote.connect).toHaveBeenCalledTimes(3);
+
+    sup.dispose();
+  });
+
+  it('does not reconnect while the SDK is still retrying', async () => {
+    const { remote, emit, state } = makeRemote();
+    const sup = makeSupervisor(remote);
+    sup.start();
+
+    state.status = 'reconnecting';
+    emit('reconnecting');
+    expect(sup.connection).toBe('reconnecting');
+
+    await vi.advanceTimersByTimeAsync(30_000);
+    // The SDK owns the socket during its own retry loop; racing it would open
+    // a second connection.
+    expect(remote.connect).not.toHaveBeenCalled();
+
+    sup.dispose();
+  });
+
+  it('forces a teardown when a heartbeat never answers (half-open socket)', async () => {
+    const { remote, emit } = makeRemote();
+    // The defining symptom: the RPC never settles and no `close` ever fires.
+    remote.query.mockImplementation(() => new Promise(() => {}));
+
+    const sup = makeSupervisor(remote);
+    emit('connected');
+    sup.start();
+
+    await vi.advanceTimersByTimeAsync(CONFIG.heartbeatIntervalMs);
+    expect(remote.query).toHaveBeenCalledWith('RETURN true');
+    expect(remote.forceClose).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(CONFIG.heartbeatTimeoutMs);
+    expect(remote.forceClose).toHaveBeenCalledTimes(1);
+
+    // The forced close published `disconnected`, so the revive loop takes over.
+    await vi.advanceTimersByTimeAsync(1_000);
+    expect(remote.connect).toHaveBeenCalled();
+
+    sup.dispose();
+  });
+
+  it('keeps heartbeating while the connection is healthy', async () => {
+    const { remote, emit } = makeRemote();
+    const sup = makeSupervisor(remote);
+    emit('connected');
+    sup.start();
+
+    await vi.advanceTimersByTimeAsync(CONFIG.heartbeatIntervalMs * 3 + 10);
+    expect(remote.query.mock.calls.length).toBeGreaterThanOrEqual(3);
+    expect(remote.forceClose).not.toHaveBeenCalled();
+    expect(sup.connection).toBe('connected');
+
+    sup.dispose();
+  });
+
+  it('parks reconnects while the browser reports offline, and resumes on online', async () => {
+    const listeners = new Map<string, Array<() => void>>();
+    vi.stubGlobal('window', {
+      addEventListener: (e: string, cb: () => void) => {
+        listeners.set(e, [...(listeners.get(e) ?? []), cb]);
+      },
+      removeEventListener: () => {},
+    });
+    const { remote, emit, state } = makeRemote();
+    const sup = makeSupervisor(remote);
+    sup.start();
+
+    state.status = 'disconnected';
+    emit('disconnected');
+    listeners.get('offline')?.forEach((cb) => cb());
+
+    // Retrying a socket against a down interface only burns backoff.
+    await vi.advanceTimersByTimeAsync(30_000);
+    expect(remote.connect).not.toHaveBeenCalled();
+
+    // `online` is the strongest available hint a reconnect will now work, so it
+    // probes immediately rather than waiting out a backoff.
+    listeners.get('online')?.forEach((cb) => cb());
+    await vi.advanceTimersByTimeAsync(0);
+    expect(remote.connect).toHaveBeenCalledTimes(1);
+
+    sup.dispose();
+  });
+
+  it('probes immediately when a hidden tab becomes visible', async () => {
+    const listeners = new Map<string, Array<() => void>>();
+    vi.stubGlobal('document', {
+      visibilityState: 'visible',
+      addEventListener: (e: string, cb: () => void) => {
+        listeners.set(e, [...(listeners.get(e) ?? []), cb]);
+      },
+      removeEventListener: () => {},
+    });
+    const { remote, emit } = makeRemote();
+    const sup = makeSupervisor(remote);
+    emit('connected');
+    sup.start();
+
+    listeners.get('visibilitychange')?.forEach((cb) => cb());
+    await vi.advanceTimersByTimeAsync(0);
+    // Connected-looking socket: probe it rather than reconnect. A sleep/wake
+    // cycle is exactly how you get a socket that looks fine and isn't.
+    expect(remote.query).toHaveBeenCalledWith('RETURN true');
+
+    sup.dispose();
+  });
+
+  it('dispose stops every timer and unsubscribes', async () => {
+    const { remote, emit, state } = makeRemote();
+    const sup = makeSupervisor(remote);
+    emit('connected');
+    sup.start();
+
+    sup.dispose();
+    state.status = 'disconnected';
+    emit('disconnected');
+
+    await vi.advanceTimersByTimeAsync(60_000);
+    expect(remote.connect).not.toHaveBeenCalled();
+    expect(remote.query).not.toHaveBeenCalled();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it('reports state changes to subscribers', () => {
+    const { remote, emit, state } = makeRemote();
+    const sup = makeSupervisor(remote);
+    sup.start();
+
+    const seen: string[] = [];
+    sup.subscribe((s) => seen.push(s));
+    // Fires immediately with the current value.
+    expect(seen).toEqual(['connected']);
+
+    state.status = 'reconnecting';
+    emit('reconnecting');
+    state.status = 'connected';
+    emit('connected');
+    expect(seen).toEqual(['connected', 'reconnecting', 'connected']);
+
+    sup.dispose();
+  });
+});