@spooky-sync/core 0.0.1-canary.21 → 0.0.1-canary.211

package/src/services/blobs/blob.fixture.ts

@@ -0,0 +1,90 @@
+/**
+ * Test-only doubles for the blob cache. Follows the repo's convention of
+ * hand-rolled fakes at the module boundary (cf. `sqlite-transport.fixture.ts`)
+ * rather than pulling in a DOM or a fake-indexeddb: `BlobCache` is pure logic
+ * over `BlobStore` + `LocalStore`, so both can be faked in node.
+ */
+import { RecordId } from 'surrealdb';
+import type { Id, LocalStore, Row } from '../database/cache-engine';
+
+/** A `LocalStore` with only the three verbs `BlobManifest` uses. */
+export interface FakeLocalStore {
+  store: LocalStore;
+  rows: Map<string, Row>;
+  /** Counts, so a test can assert the manifest batched instead of write-storming. */
+  upserts: number;
+  deletes: number;
+  /** Make every read fail — the memory-fallback / wiped-store case. */
+  failReads: boolean;
+}
+
+function idOf(id: Id): string {
+  return id instanceof RecordId ? String(id.id) : String(id);
+}
+
+export function fakeLocalStore(): FakeLocalStore {
+  const state: FakeLocalStore = {
+    rows: new Map(),
+    upserts: 0,
+    deletes: 0,
+    failReads: false,
+    store: null as unknown as LocalStore,
+  };
+
+  state.store = {
+    async selectByIds(_table: string, ids: Id[]): Promise<Row[]> {
+      if (state.failReads) throw new Error('local store unavailable');
+      const out: Row[] = [];
+      for (const id of ids) {
+        const key = idOf(id);
+        const row = state.rows.get(key);
+        if (row) out.push({ ...row, id: new RecordId('_00_blob', key) });
+      }
+      return out;
+    },
+    async upsert(_table: string, id: Id, data: Row): Promise<void> {
+      state.upserts++;
+      state.rows.set(idOf(id), { ...data });
+    },
+    async delete(_table: string, id: Id): Promise<void> {
+      state.deletes++;
+      state.rows.delete(idOf(id));
+    },
+  } as unknown as LocalStore;
+
+  return state;
+}
+
+/** A logger that satisfies the `Logger` shape without printing. */
+export function silentLogger(): any {
+  const noop = () => {};
+  const logger: any = { debug: noop, info: noop, warn: noop, error: noop, fatal: noop, trace: noop };
+  logger.child = () => logger;
+  return logger;
+}
+
+/** Deterministic object-URL factory: no DOM needed, and revokes are countable. */
+export function fakeUrls() {
+  let next = 0;
+  const live = new Set<string>();
+  const revoked: string[] = [];
+  return {
+    live,
+    revoked,
+    factory: {
+      create: (_blob: Blob) => {
+        const url = `blob:fake/${next++}`;
+        live.add(url);
+        return url;
+      },
+      revoke: (url: string) => {
+        live.delete(url);
+        revoked.push(url);
+      },
+    },
+  };
+}
+
+export function bytes(size: number, fill = 'a'): Blob {
+  return new Blob([fill.repeat(size)]);
+}

package/src/services/blobs/index.ts

@@ -0,0 +1,70 @@
+import type { Logger } from '../logger/index';
+import type { LocalStore } from '../database/cache-engine';
+import type { BlobCacheOptions } from './blob-cache';
+import { BlobCache } from './blob-cache';
+import { BlobManifest } from './blob-manifest';
+import type { BlobStore } from './blob-store';
+import { MemoryBlobStore, OpfsBlobStore, opfsWritableSupported } from './blob-store';
+
+export type { BlobKey, BlobStat, BlobStore } from './blob-store';
+export { BLOB_ROOT_DIR, BlobKeyError, MemoryBlobStore, OpfsBlobStore, blobKeyId, opfsWritableSupported } from './blob-store';
+export type { BlobEntry } from './blob-manifest';
+export { BLOB_TABLE, BlobManifest } from './blob-manifest';
+export type { BlobCacheOptions, BlobCacheStats, BlobReadOptions, BlobUrlLease } from './blob-cache';
+export { BlobCache } from './blob-cache';
+
+/** Ceiling on the default budget, before the quota fraction is applied. */
+const MAX_DEFAULT_BUDGET_BYTES = 512 * 1024 * 1024;
+/** Share of the origin quota the blob cache may claim by default. The local
+ *  database, the SQLite pool and any app storage share the same quota. */
+const QUOTA_FRACTION = 0.25;
+/** Used until `resolveBlobBudget()` reports back, and when there is no
+ *  `navigator.storage.estimate()` to ask. */
+export const FALLBACK_BLOB_BUDGET_BYTES = 128 * 1024 * 1024;
+
+/**
+ * Budget from the real origin quota when the browser will tell us, otherwise a
+ * conservative constant. Async because `estimate()` is; call it once at init
+ * and hand the result to {@link BlobCache.setMaxBytes}.
+ */
+export async function resolveBlobBudget(configured?: number): Promise<number> {
+  if (typeof configured === 'number' && configured > 0) return configured;
+  try {
+    const { quota } = (await navigator.storage.estimate()) ?? {};
+    if (typeof quota === 'number' && quota > 0) {
+      return Math.min(MAX_DEFAULT_BUDGET_BYTES, Math.floor(quota * QUOTA_FRACTION));
+    }
+  } catch {
+    /* private mode, or no Storage API: fall through */
+  }
+  return FALLBACK_BLOB_BUDGET_BYTES;
+}
+
+export interface CreateBlobCacheOptions {
+  local: LocalStore;
+  namespace: string;
+  logger: Logger;
+  fetchRemote: BlobCacheOptions['fetchRemote'];
+  headRemote?: BlobCacheOptions['headRemote'];
+  maxBytes?: number;
+  /** Force a store instead of feature-detecting. Tests and custom engines. */
+  store?: BlobStore;
+}
+
+/**
+ * Build the cache for a client. Falls back to an in-memory store when OPFS
+ * cannot be written (Safari before `createWritable`, private modes, non-browser
+ * hosts): the cache still dedupes and serves within the tab, which is exactly
+ * the behaviour that existed before it — nothing regresses, nothing persists.
+ */
+export function createBlobCache(opts: CreateBlobCacheOptions): BlobCache {
+  const store = opts.store ?? (opfsWritableSupported() ? new OpfsBlobStore(opts.namespace) : new MemoryBlobStore(opts.namespace));
+  return new BlobCache({
+    store,
+    manifest: new BlobManifest(opts.local),
+    fetchRemote: opts.fetchRemote,
+    headRemote: opts.headRemote,
+    logger: opts.logger,
+    maxBytes: opts.maxBytes ?? FALLBACK_BLOB_BUDGET_BYTES,
+  });
+}

package/src/services/database/cache-engine.ts

@@ -0,0 +1,193 @@
+import type { QueryPlan, RelationPlan, WhereNode } from '@spooky-sync/query-builder';
+import type { SealedQuery } from '../../utils/surql';
+import type { DatabaseEventSystem } from './events/index';
+import type { Sp00kyConfig, StorageHealth } from '../../types';
+import type { EngineStorageDiagnostics } from '../../modules/devtools/storage-info';
+
+/**
+ * A materialized row. Keys are field names; values are already decoded to the
+ * client's runtime shapes (RecordId stays a RecordId, bytes a Uint8Array, …) so
+ * every backend hands `DataModule` the same shape SurrealDB does today.
+ */
+export type Row = Record<string, unknown>;
+
+/** A record identifier — a `RecordId` or its stable string form (`table:id`). */
+export type Id = unknown;
+
+/** How an order clause is expressed everywhere in the engine layer. */
+export type OrderBy = [field: string, direction: 'asc' | 'desc'][];
+
+/**
+ * Batched relation fetch: "give me every row of `table` whose `matchField` is
+ * one of `keys`, filtered by `where`, ordered by `orderBy`". This is the single
+ * primitive relation decomposition (§3) leans on — implemented as
+ * `SELECT … WHERE <matchField> IN (…)` on SQLite, `SELECT … FROM $keys` /
+ * `WHERE <matchField> IN $keys` on SurrealDB, or an index scan elsewhere. Order
+ * here is a hint; the resolver re-applies order+limit PER PARENT after grouping.
+ */
+export interface RelationFetch {
+  table: string;
+  matchField: string;
+  keys: Id[];
+  where?: WhereNode[];
+  orderBy?: OrderBy;
+  select?: string[];
+}
+
+/**
+ * The read side of an engine, minus relation resolution — the surface a
+ * {@link RelationResolver} needs. Kept separate so the resolver can be unit
+ * tested against an in-memory fake without a full engine.
+ */
+export interface RowFetcher {
+  /** Batched fan-out fetch. See {@link RelationFetch}. */
+  fetchRelation(req: RelationFetch): Promise<Row[]>;
+}
+
+/** A transaction handle — the same verbs as the engine, but atomic. */
+export interface EngineTx {
+  upsert(table: string, id: Id, data: Row, mode: 'replace' | 'merge'): Promise<void>;
+  patch(table: string, id: Id, patches: unknown[]): Promise<void>;
+  delete(table: string, id: Id): Promise<void>;
+}
+
+/**
+ * A pluggable local cache backend. SurrealDB (the default) and SQLite both
+ * implement this; the rest of the client talks verbs, never SurrealQL.
+ *
+ * Reactivity is NOT part of this contract: the local cache is passive. The SSP
+ * (remote) drives change; `DataModule` writes rows here and re-reads them. The
+ * `epoch` field preserves the existing bucket-switch fencing (see
+ * `LocalDatabaseService.epoch`): an async chain captures it at start and its
+ * write is dropped if the epoch moved (a bucket switch) in between.
+ */
+export interface LocalCacheEngine extends RowFetcher {
+  /** Monotonic store generation; bumped on every bucket switch. */
+  readonly epoch: number;
+
+  connect(bucketId: string): Promise<void>;
+  switchBucket(bucketId: string): Promise<void>;
+  close(): Promise<void>;
+
+  /** Run `fn` inside a single atomic transaction. */
+  transaction<T>(fn: (tx: EngineTx) => Promise<T>): Promise<T>;
+
+  /**
+   * Materialize a query, including its `.related()` tree (via §3
+   * decomposition). Params bind `where` `paramRef`s and any windowing id-set.
+   */
+  select(plan: QueryPlan, params?: Record<string, unknown>): Promise<Row[]>;
+
+  /** Fetch rows by primary id, preserving `ids` order; missing ids are skipped. */
+  selectByIds(table: string, ids: Id[], opts?: { select?: string[]; orderBy?: OrderBy }): Promise<Row[]>;
+
+  /** Single-record read by primary id, or `null`. */
+  getById(table: string, id: Id): Promise<Row | null>;
+
+  upsert(table: string, id: Id, data: Row, mode: 'replace' | 'merge'): Promise<void>;
+  patch(table: string, id: Id, patches: unknown[]): Promise<void>;
+  delete(table: string, id: Id): Promise<void>;
+}
+
+/**
+ * The full surface the client's `this.local` field depends on: the
+ * engine-neutral {@link LocalCacheEngine} verbs PLUS the legacy
+ * SurrealQL/lifecycle methods the not-yet-migrated call sites still use.
+ * `SurrealCacheEngine` (subclass of `LocalDatabaseService`) and
+ * `SqliteCacheEngine` (via a SurrealQL-vocabulary shim) both satisfy this, so
+ * either can back `this.local`.
+ *
+ * `getClient()` returns the underlying SurrealDB `Surreal` handle where one
+ * exists (SurrealDB backend); backends without one (SQLite) throw — it is only
+ * used by advanced/DevTools paths, never on the hot path.
+ */
+export interface LocalStore extends LocalCacheEngine {
+  /**
+   * Whether this engine needs SurrealQL schema provisioning (`DEFINE TABLE`,
+   * `DEFINE FIELD`, …) run against it at init / bucket switch. SurrealDB → true;
+   * schemaless engines (SQLite creates tables lazily) → false, so the client
+   * skips the `LocalMigrator` entirely for them.
+   */
+  readonly usesSurqlSchema: boolean;
+  query<T extends unknown[]>(
+    query: string,
+    vars?: Record<string, unknown>,
+    opts?: { epoch?: number }
+  ): Promise<T>;
+  execute<T>(query: SealedQuery<T>, vars?: Record<string, unknown>, opts?: { epoch?: number }): Promise<T>;
+  queryUngated<T extends unknown[]>(query: string, vars?: Record<string, unknown>): Promise<T>;
+  switchStore(bucketId: string): Promise<void>;
+  beginSwitch(): () => void;
+  getEvents(): DatabaseEventSystem;
+  getClient(): unknown;
+  getConfig(): Sp00kyConfig<any>['database'];
+  readonly currentBucketId: string;
+  /** Which built-in backend this is. OPTIONAL: absent (custom engines) is
+   *  reported as `'custom'` by DevTools. More robust than `instanceof` for
+   *  engines constructed outside this package. */
+  readonly engineKind?: 'surrealdb' | 'sqlite';
+  /** Engine-specific storage numbers for DevTools (DB file size, per-table
+   *  row counts). OPTIONAL: only engines with something to report implement it. */
+  getStorageDiagnostics?(opts?: { tableCounts?: boolean }): Promise<EngineStorageDiagnostics>;
+  /**
+   * Durability of this engine's local store. OPTIONAL: engines that don't
+   * report it (SurrealDB, custom engines) are treated as `'unknown'` by the
+   * client facade, so adding this needs no change on their side.
+   */
+  readonly storageHealth?: StorageHealth;
+  /** Fires immediately with the current snapshot, then on every change.
+   *  Returns an unsubscribe function. */
+  subscribeToStorageHealth?(cb: (health: StorageHealth) => void): () => void;
+  /**
+   * Every cached row's `(id, _00_rv)` per table, ids in stable `table:id`
+   * form. The in-browser circuit primes and reconciles itself from this on
+   * boot instead of re-downloading the working set. OPTIONAL: an engine
+   * without it boots the circuit empty, as before.
+   */
+  scanVersions?(tables: string[]): Promise<Record<string, [string, number][]>>;
+  /**
+   * Circuit snapshot storage, keyed. Lives in the same durable store as the
+   * rows (OPFS SQLite), so it is per-bucket by construction, atomic, and
+   * readable by follower tabs over the port transport. OPTIONAL: an engine
+   * without it primes from `scanVersions` alone.
+   */
+  getSnapshot?(key: string): Promise<StoredSnapshot | null>;
+  putSnapshot?(key: string, bytes: Uint8Array, meta: SnapshotMeta): Promise<void>;
+  deleteSnapshot?(key: string): Promise<void>;
+}
+
+/** Describes a stored circuit snapshot; what decides whether it is usable. */
+export interface SnapshotMeta {
+  /** Bump when the wire shape the circuit reads changes. */
+  formatVersion: number;
+  /** Hash of the schema the rows were projected under. */
+  schemaHash: string;
+  savedAt: number;
+  /** Highest `_00_rv` per table at save time (diagnostics). */
+  maxRv?: Record<string, number>;
+  [key: string]: unknown;
+}
+
+export interface StoredSnapshot {
+  bytes: Uint8Array;
+  meta: SnapshotMeta;
+}
+
+/** Selected local cache backend. Mirrors the `persistenceClient` config pattern. */
+export type LocalEngineChoice = 'surrealdb' | 'sqlite' | LocalStore;
+
+/** Thrown when relation decomposition nests past {@link MAX_RELATION_DEPTH} —
+ *  a guard against a cyclic schema producing unbounded fan-out. */
+export class RelationCycleError extends Error {
+  constructor(path: string[]) {
+    super(`Relation nesting exceeded safe depth; possible cyclic schema: ${path.join(' -> ')}`);
+    this.name = 'RelationCycleError';
+  }
+}
+
+/** Defensive ceiling on relation nesting depth. A finite plan tree never hits
+ *  this in practice; it exists so a malformed/cyclic plan fails loudly instead
+ *  of running away. */
+export const MAX_RELATION_DEPTH = 12;
+
+export type { QueryPlan, RelationPlan, WhereNode };

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

@@ -0,0 +1,289 @@
+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();
+
+    // One failure is inconclusive — the probe shares a queue with ordinary
+    // traffic, so it re-probes rather than tearing down a possibly-fine socket.
+    await vi.advanceTimersByTimeAsync(CONFIG.heartbeatTimeoutMs);
+    expect(remote.forceClose).not.toHaveBeenCalled();
+
+    // The second consecutive failure is the one that tears it down.
+    await vi.advanceTimersByTimeAsync(5_000 + 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('does not tear down a healthy socket after a single slow probe', async () => {
+    // The regression this guards: the heartbeat rides the same serialized queue
+    // as every other RPC, so one busy window (a big sync burst) used to
+    // force-close a working connection — and the reconnect then re-registered
+    // every active query about a second later.
+    const { remote, emit } = makeRemote();
+    let calls = 0;
+    remote.query.mockImplementation(() => {
+      calls++;
+      // First probe hangs past its deadline, the next answers normally.
+      return calls === 1 ? new Promise(() => {}) : Promise.resolve(true);
+    });
+
+    const sup = makeSupervisor(remote);
+    emit('connected');
+    sup.start();
+
+    await vi.advanceTimersByTimeAsync(CONFIG.heartbeatIntervalMs + CONFIG.heartbeatTimeoutMs);
+    expect(remote.forceClose).not.toHaveBeenCalled();
+
+    // The retry succeeds, so the socket survives and heartbeating continues.
+    await vi.advanceTimersByTimeAsync(5_000 + CONFIG.heartbeatIntervalMs * 2);
+    expect(remote.forceClose).not.toHaveBeenCalled();
+    expect(sup.connection).toBe('connected');
+
+    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();
+  });
+});