@1agh/maude 0.22.2 → 0.24.0

package/plugins/design/dev-server/sync/atomic-write.ts

@@ -0,0 +1,103 @@
+// Atomic file writes for the bidirectional file sync agent (Phase 9 Task 4).
+//
+// fs.watch on macOS/Linux fires on rename, so a non-atomic write (open →
+// truncate → write chunks → close) emits multiple watch events with partial
+// content. The agent's echo guard hashes the final content, so a partial-write
+// event would miss the hash match and incorrectly bubble the (truncated) state
+// up to Y.Doc — corrupting the live state.
+//
+// Pattern: open `<path>.tmp.<random-128-bit>` with O_CREAT|O_EXCL ('wx' in
+// Node), write bytes, close, `renameSync` to the final path. POSIX rename is
+// atomic when source + destination are on the same filesystem; the watch sees
+// the final-content-already-present rename event rather than a stream of
+// in-flight chunks. O_EXCL + 128-bit suffix defeats pre-created symlinks on
+// shared-tenant hosts (DDR-054 §2c — closes attacker Chain C + defender L1).
+//
+// File mode 0o600 on the staging file so other tenants on shared hosts can't
+// read in-flight content before the rename.
+//
+// Windows note: rename of a file the watcher has open returns EBUSY. The
+// plan's Task 4 step 4 acknowledges this as a known minor risk for v1.1;
+// the agent treats EBUSY as a transient error and retries once after a 25ms
+// jitter.
+
+import { randomBytes } from 'node:crypto';
+import { closeSync, mkdirSync, openSync, renameSync, unlinkSync, writeSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+const RETRY_DELAY_MS = 25;
+// 'wx' = O_CREAT | O_EXCL — fails if the target already exists, including as
+// a dangling/live symlink. Plus O_TRUNC is implied; mode 0o600 sets owner-only.
+const TMP_OPEN_FLAGS = 'wx' as const;
+const TMP_OPEN_MODE = 0o600;
+
+/**
+ * Write `bytes` to `path` atomically. Returns the absolute path written
+ * (same as input — convenience for chaining).
+ *
+ * Bytes are written via Node's synchronous `openSync` with `O_CREAT|O_EXCL`
+ * (fails on pre-existing tmp / symlink), then `renameSync` moves it into
+ * place. 128-bit random suffix; mode 0o600. On POSIX the rename is atomic;
+ * on Windows there is a small window where the watcher may see a brief gap,
+ * retried once on EBUSY.
+ *
+ * `bytes` accepts string (UTF-8 encoded) or Uint8Array (written verbatim).
+ */
+export function atomicWrite(path: string, bytes: string | Uint8Array): string {
+  // Ensure the parent directory exists. Cheap (mkdirSync recursive is a no-op
+  // when present) and removes the per-canvas burden of creating _comments/
+  // before the agent's first flush.
+  mkdirSync(dirname(path), { recursive: true });
+  // 16 bytes = 32 hex chars = 128 bits. Unforgeable in practice against a
+  // local racer (vs. the prior 32-bit value which was brute-forceable in ms).
+  const suffix = randomBytes(16).toString('hex');
+  const tmp = `${path}.tmp.${suffix}`;
+  let fd: number | null = null;
+  try {
+    fd = openSync(tmp, TMP_OPEN_FLAGS, TMP_OPEN_MODE);
+    const buf = typeof bytes === 'string' ? Buffer.from(bytes, 'utf8') : Buffer.from(bytes);
+    writeSync(fd, buf, 0, buf.byteLength, 0);
+    closeSync(fd);
+    fd = null;
+    try {
+      renameSync(tmp, path);
+    } catch (err) {
+      if (isWindowsBusy(err)) {
+        // Brief retry — Windows watcher may hold a handle while reading the
+        // pre-rename target. 25ms is short enough to be invisible to the user
+        // and long enough to clear the typical fs.watch poll interval.
+        const start = Date.now();
+        while (Date.now() - start < RETRY_DELAY_MS) {
+          // Tight loop is OK for 25ms — keeps the call synchronous so callers
+          // can record the echo-guard hash before any fs event fires.
+        }
+        renameSync(tmp, path);
+      } else {
+        throw err;
+      }
+    }
+  } catch (err) {
+    // Best-effort cleanup of the .tmp + fd on failure — don't mask the
+    // original exception with a cleanup error.
+    if (fd !== null) {
+      try {
+        closeSync(fd);
+      } catch {
+        /* ignore */
+      }
+    }
+    try {
+      unlinkSync(tmp);
+    } catch {
+      /* ignore */
+    }
+    throw err;
+  }
+  return path;
+}
+
+function isWindowsBusy(err: unknown): boolean {
+  if (!err || typeof err !== 'object') return false;
+  const code = (err as { code?: string }).code;
+  return code === 'EBUSY' || code === 'EPERM' || code === 'EACCES';
+}

package/plugins/design/dev-server/sync/codec.ts

@@ -0,0 +1,324 @@
+// Y.Doc ↔ disk codecs for the bidirectional file sync agent (Phase 9 Task 4).
+//
+// The agent shuttles three classes of files between disk and the Y.Doc the
+// HocuspocusProvider holds:
+//
+//   `.design/<canvas>.html`             -> Y.Text     (Y_SYNC_TYPES.html)
+//   `.design/_comments/<slug>.json`     -> Y.Array    (Y_TYPES.comments  — Phase 6)
+//   `.design/<slug>.annotations.svg`    -> Y.Map.svg  (Y_TYPES.annotations — Phase 5)
+//
+// v1.1 design decision (plan §"Key insight"): HTML body is treated as opaque
+// Y.Text rather than structured Y.XmlFragment. Round-trip drift would
+// otherwise cause infinite sync churn — every time we serialize the structured
+// CRDT back to HTML the formatting whitespace would shift and re-enter the
+// system as a new mutation. Structured CRDT (true element-level co-editing) is
+// Phase 10 / v1.2.
+//
+// The "diff-aware" applyHtmlToDoc replaces the Y.Text contents using a
+// longest-common-prefix + suffix elimination so other peers see a minimal
+// op (e.g. "user changed character 42 only"). This isn't a true textual diff
+// (no LCS), but it's drastically cheaper for typical edits than `delete-all +
+// insert-all`, and crucially preserves cursor positions other peers may have
+// in the unchanged regions.
+
+import type * as Y from 'yjs';
+
+import { Y_TYPES } from '../collab/persistence.ts';
+
+/**
+ * Y.Doc shared-type names introduced by Task 4. Distinct namespace from
+ * Y_TYPES so existing comments / annotations stay untouched; new fields
+ * land here.
+ */
+export const Y_SYNC_TYPES = {
+  /** The canvas HTML body, as opaque Y.Text. */
+  html: 'html',
+  /** The canvas's sibling `.css` (e.g. `Kanban App.css`), as opaque Y.Text.
+   *  Edited via files (design:edit), not a live browser surface, so it mirrors
+   *  wholesale like the body — no per-user keys, no room-clobber. Phase 9.1
+   *  Gap 3. */
+  css: 'css',
+  /** The canvas `.meta.json` SHARED subset (layout/artboards/structure) as an
+   *  opaque canonical-JSON Y.Text. Per-user keys (viewport pan/zoom) + the
+   *  security opt-in (syncable) are stripped before sync — see META_LOCAL_KEYS
+   *  + sharedMetaCanonical. Phase 9.1 Gap 2. */
+  meta: 'meta',
+} as const;
+
+/**
+ * Hard caps on hub-pushed content (DDR-054 §2d — closes attacker F7). yjs
+ * has no upstream-enforced size cap; the codec is the consumer's guard.
+ * Mirrors the existing /_api/annotations 1 MB cap (api.ts) so the sync path
+ * doesn't bypass the HTTP-layer guard.
+ */
+export const MAX_HTML_BYTES = 4 * 1024 * 1024;
+export const MAX_COMMENTS_BYTES = 1 * 1024 * 1024;
+export const MAX_ANNOTATIONS_BYTES = 1 * 1024 * 1024;
+export const MAX_META_BYTES = 1 * 1024 * 1024;
+export const MAX_CSS_BYTES = 4 * 1024 * 1024;
+
+function byteLengthUtf8(s: string): number {
+  return Buffer.byteLength(s, 'utf8');
+}
+
+// DDR-054 §2g — strip dangerous keys at parse time so a hostile hub-pushed (or
+// planted-commit) payload can't seed `__proto__` / `constructor` / `prototype`
+// own-properties that yjs then serializes to other peers / writes to disk that
+// Claude reads. Mirrors the agent's comments reviver; applied to the `.meta.json`
+// parse paths (Phase D security re-audit finding A3 — the reviver had been
+// applied only to the comments lane, not the symmetric meta lane).
+function parseJsonSafe(s: string): unknown {
+  return JSON.parse(s, (key, value) => {
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype') return undefined;
+    return value;
+  });
+}
+
+/* ---------------------------------------------------------------- HTML */
+
+export function htmlFromDoc(doc: Y.Doc): string {
+  return doc.getText(Y_SYNC_TYPES.html).toString();
+}
+
+/**
+ * Apply `next` to the Y.Text inside `doc`. Uses a minimal common-prefix /
+ * common-suffix replace so peers see a small op rather than a full replace.
+ *
+ * Pass `origin` as the transaction origin so a downstream observer can
+ * distinguish self-originated updates from peer/remote ones.
+ */
+export function applyHtmlToDoc(doc: Y.Doc, next: string, origin?: unknown): boolean {
+  if (byteLengthUtf8(next) > MAX_HTML_BYTES) {
+    console.warn(
+      `[sync/codec] refusing HTML apply > ${MAX_HTML_BYTES} bytes (got ${byteLengthUtf8(next)}). DDR-054 §2d.`
+    );
+    return false;
+  }
+  const yText = doc.getText(Y_SYNC_TYPES.html);
+  const current = yText.toString();
+  if (current === next) return false;
+
+  // Find longest common prefix.
+  let prefix = 0;
+  const maxPrefix = Math.min(current.length, next.length);
+  while (prefix < maxPrefix && current.charCodeAt(prefix) === next.charCodeAt(prefix)) {
+    prefix++;
+  }
+  // Find longest common suffix that doesn't overlap the prefix.
+  let suffix = 0;
+  const maxSuffix = Math.min(current.length - prefix, next.length - prefix);
+  while (
+    suffix < maxSuffix &&
+    current.charCodeAt(current.length - 1 - suffix) === next.charCodeAt(next.length - 1 - suffix)
+  ) {
+    suffix++;
+  }
+
+  const deleteLen = current.length - prefix - suffix;
+  const insertStr = next.slice(prefix, next.length - suffix);
+
+  doc.transact(() => {
+    if (deleteLen > 0) yText.delete(prefix, deleteLen);
+    if (insertStr.length > 0) yText.insert(prefix, insertStr);
+  }, origin);
+
+  return true;
+}
+
+/* ---------------------------------------------------------------- comments */
+
+/**
+ * Comments JSON payload — opaque to the codec, just the array of objects the
+ * Y.Array holds.
+ */
+export type CommentsSnapshot = unknown[];
+
+export function commentsFromDoc(doc: Y.Doc): CommentsSnapshot {
+  const arr = doc.getArray(Y_TYPES.comments);
+  return arr.toArray();
+}
+
+export function applyCommentsToDoc(doc: Y.Doc, next: CommentsSnapshot, origin?: unknown): boolean {
+  const arr = doc.getArray(Y_TYPES.comments);
+  // Comments are LWW on the JSON file (the snapshot is the source of truth);
+  // collapse Y.Array to the new state. For v1.1 we just replace wholesale —
+  // structural comment-level merge is deferred along with structured HTML.
+  // Check whether anything actually changed to avoid no-op transactions
+  // (transactions still fire `update` events, which would re-enter the loop).
+  const before = JSON.stringify(arr.toArray());
+  const after = JSON.stringify(next);
+  if (byteLengthUtf8(after) > MAX_COMMENTS_BYTES) {
+    console.warn(
+      `[sync/codec] refusing comments apply > ${MAX_COMMENTS_BYTES} bytes (got ${byteLengthUtf8(after)}). DDR-054 §2d.`
+    );
+    return false;
+  }
+  if (before === after) return false;
+
+  doc.transact(() => {
+    if (arr.length > 0) arr.delete(0, arr.length);
+    if (next.length > 0) arr.push(next);
+  }, origin);
+  return true;
+}
+
+/* ---------------------------------------------------------------- annotations */
+
+/** Returns the annotations SVG string, or null if unset. */
+export function annotationsFromDoc(doc: Y.Doc): string | null {
+  const map = doc.getMap<unknown>(Y_TYPES.annotations);
+  const svg = map.get('svg');
+  return typeof svg === 'string' ? svg : null;
+}
+
+export function applyAnnotationsToDoc(doc: Y.Doc, next: string | null, origin?: unknown): boolean {
+  if (next !== null && byteLengthUtf8(next) > MAX_ANNOTATIONS_BYTES) {
+    console.warn(
+      `[sync/codec] refusing annotations apply > ${MAX_ANNOTATIONS_BYTES} bytes (got ${byteLengthUtf8(next)}). DDR-054 §2d.`
+    );
+    return false;
+  }
+  const map = doc.getMap<unknown>(Y_TYPES.annotations);
+  const current = map.get('svg');
+  const currentStr = typeof current === 'string' ? current : null;
+  if (currentStr === next) return false;
+
+  doc.transact(() => {
+    if (next === null || next === '') {
+      map.delete('svg');
+    } else {
+      map.set('svg', next);
+    }
+  }, origin);
+  return true;
+}
+
+/* ---------------------------------------------------------------- meta */
+
+/**
+ * Keys of a canvas `.meta.json` that are PER-MACHINE and MUST NOT cross the hub:
+ *   - `viewport`      — this user's pan/zoom; syncing it would yank a
+ *                        collaborator's camera around on every pan.
+ *   - `last_modified` — a local write timestamp; syncing it churns with no signal.
+ *   - `syncable`      — the security opt-in (DDR-054). A peer/hub must NEVER be
+ *                        able to flip another repo's sync gate, so it stays local
+ *                        and human-edited — same rationale that keeps it out of
+ *                        the /_api/canvas-meta PATCH whitelist.
+ * Everything else (title, sections/artboards, `layout` rects, css_mode, …) is
+ * shared canvas structure and DOES sync — that's how an artboard move on one
+ * machine reaches the other's disk.
+ */
+export const META_LOCAL_KEYS = ['viewport', 'last_modified', 'syncable'] as const;
+
+/** Canonical JSON of the SHARED subset of a parsed meta object: local keys
+ *  dropped, remaining keys sorted so equal content always serializes byte-equal
+ *  (stable → the no-op guards stay quiet and sync doesn't churn). */
+function sharedMetaCanonical(meta: Record<string, unknown>): string {
+  const out: Record<string, unknown> = {};
+  for (const k of Object.keys(meta).sort()) {
+    if ((META_LOCAL_KEYS as readonly string[]).includes(k)) continue;
+    out[k] = meta[k];
+  }
+  return JSON.stringify(out);
+}
+
+/** The synced shared-meta JSON string held in the doc, or null when unset. */
+export function metaFromDoc(doc: Y.Doc): string | null {
+  const s = doc.getText(Y_SYNC_TYPES.meta).toString();
+  return s.length > 0 ? s : null;
+}
+
+/**
+ * Apply a FULL `.meta.json` string to the doc as its shared subset: parse, strip
+ * per-user/security keys, store the canonical shared JSON in a Y.Text. Returns
+ * false on parse error / over-cap / no change.
+ */
+export function applyMetaToDoc(doc: Y.Doc, fullMetaJson: string, origin?: unknown): boolean {
+  let obj: unknown;
+  try {
+    obj = parseJsonSafe(fullMetaJson);
+  } catch {
+    return false;
+  }
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return false;
+  const shared = sharedMetaCanonical(obj as Record<string, unknown>);
+  if (byteLengthUtf8(shared) > MAX_META_BYTES) {
+    console.warn(
+      `[sync/codec] refusing meta apply > ${MAX_META_BYTES} bytes (got ${byteLengthUtf8(shared)}). DDR-054 §2d.`
+    );
+    return false;
+  }
+  const t = doc.getText(Y_SYNC_TYPES.meta);
+  if (t.toString() === shared) return false;
+  doc.transact(() => {
+    if (t.length > 0) t.delete(0, t.length);
+    t.insert(0, shared);
+  }, origin);
+  return true;
+}
+
+/**
+ * Merge the synced shared-meta into a local `.meta.json` string, PRESERVING the
+ * local per-user/security keys (META_LOCAL_KEYS). Shared keys become exactly
+ * what the doc holds (so a deletion on the source propagates); the local keys
+ * are layered back on top. Returns the merged JSON (2-space, trailing newline)
+ * ready to write, or null when the shared payload is unparseable.
+ */
+export function mergeSharedMetaIntoLocal(
+  localMetaJson: string | null,
+  sharedJson: string
+): string | null {
+  let shared: unknown;
+  try {
+    shared = parseJsonSafe(sharedJson);
+  } catch {
+    return null;
+  }
+  if (!shared || typeof shared !== 'object' || Array.isArray(shared)) return null;
+  let local: Record<string, unknown> = {};
+  if (localMetaJson) {
+    try {
+      const parsed = parseJsonSafe(localMetaJson);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        local = parsed as Record<string, unknown>;
+      }
+    } catch {
+      /* unparseable local meta — treat as empty; the shared subset becomes the base */
+    }
+  }
+  const merged: Record<string, unknown> = { ...(shared as Record<string, unknown>) };
+  for (const k of META_LOCAL_KEYS) {
+    if (k in local) merged[k] = local[k];
+  }
+  return `${JSON.stringify(merged, null, 2)}\n`;
+}
+
+/* ---------------------------------------------------------------- css */
+
+/** The synced canvas CSS string held in the doc, or null when unset/empty. */
+export function cssFromDoc(doc: Y.Doc): string | null {
+  const s = doc.getText(Y_SYNC_TYPES.css).toString();
+  return s.length > 0 ? s : null;
+}
+
+/**
+ * Apply the canvas's `.css` to the doc as opaque Y.Text (wholesale replace).
+ * CSS round-trips byte-identically (we write exactly the doc string back), so a
+ * wholesale delete+insert can't churn; the equality short-circuit keeps it quiet
+ * when unchanged. Returns false on over-cap / no change.
+ */
+export function applyCssToDoc(doc: Y.Doc, next: string, origin?: unknown): boolean {
+  if (byteLengthUtf8(next) > MAX_CSS_BYTES) {
+    console.warn(
+      `[sync/codec] refusing CSS apply > ${MAX_CSS_BYTES} bytes (got ${byteLengthUtf8(next)}). DDR-054 §2d.`
+    );
+    return false;
+  }
+  const t = doc.getText(Y_SYNC_TYPES.css);
+  if (t.toString() === next) return false;
+  doc.transact(() => {
+    if (t.length > 0) t.delete(0, t.length);
+    t.insert(0, next);
+  }, origin);
+  return true;
+}

package/plugins/design/dev-server/sync/connection-state.ts

@@ -0,0 +1,203 @@
+// Hub connection state machine — Phase 9 Task 8 (hub-down offline mode).
+//
+// The sync runtime owns one monitor for the whole linked session. Each
+// HocuspocusProvider reports its WS status ('connected' | 'connecting' |
+// 'disconnected'); the monitor aggregates them into a single hub-reachability
+// view and drives the user-facing offline UX:
+//
+//   online        — hub reachable, edits flow live.
+//   connecting    — WS dropped, inside the reconnect grace window. No banner yet
+//                   (transient blips shouldn't flash UI).
+//   offline       — still not reconnected after graceMs (default 30s). Local
+//                   edits keep working + queue; yellow banner.
+//   offline-long  — offline > escalateMs (default 24h). Red banner: "consider
+//                   git commit && push as backup".
+//
+// On reconnect from any offline state the monitor emits a transient `flash:
+// 'synced'` (green, flashMs default 3s) then settles back to online with
+// queuedOps reset (the provider replays the buffered ops to the hub).
+//
+// Timers + clock are injectable so the state machine is fully unit-testable
+// without real wall-clock waits.
+
+export type ProviderStatus = 'connected' | 'connecting' | 'disconnected';
+export type SyncState = 'online' | 'connecting' | 'offline' | 'offline-long';
+
+export interface SyncStatusSnapshot {
+  state: SyncState;
+  /** Local edits made since the hub went unreachable (replayed on reconnect). */
+  queuedOps: number;
+  /** ms epoch of the last successful hub sync, or null if never synced. */
+  lastSyncAt: number | null;
+  /** ms epoch the current offline streak began, or null when online. */
+  offlineSince: number | null;
+  /** Transient 'synced' signal (green flash) right after a reconnect. */
+  flash: 'synced' | null;
+  /** ms epoch this snapshot was produced. */
+  updatedAt: number;
+}
+
+type TimerHandle = ReturnType<typeof setTimeout>;
+
+export interface ConnectionMonitorOptions {
+  /** ms disconnected before declaring offline. Default 30_000. */
+  graceMs?: number;
+  /** ms offline before escalating to offline-long. Default 24h. */
+  escalateMs?: number;
+  /** ms the green "synced" flash stays up after reconnect. Default 3_000. */
+  flashMs?: number;
+  now?: () => number;
+  setTimer?: (cb: () => void, ms: number) => TimerHandle;
+  clearTimer?: (h: TimerHandle) => void;
+  /** Called on every observable state change (including flash set/clear). */
+  onChange?: (snapshot: SyncStatusSnapshot) => void;
+}
+
+export interface ConnectionMonitor {
+  /** Aggregate a single provider's status into the session view. */
+  noteProviderStatus(providerId: string, status: ProviderStatus): void;
+  /** A local edit happened — counts toward queuedOps while not online. */
+  noteLocalEdit(): void;
+  /** Current snapshot (defensive copy). */
+  snapshot(): SyncStatusSnapshot;
+  /** Tear down timers. */
+  stop(): void;
+}
+
+const DEFAULT_GRACE_MS = 30_000;
+const DEFAULT_ESCALATE_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_FLASH_MS = 3_000;
+
+export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): ConnectionMonitor {
+  const graceMs = opts.graceMs ?? DEFAULT_GRACE_MS;
+  const escalateMs = opts.escalateMs ?? DEFAULT_ESCALATE_MS;
+  const flashMs = opts.flashMs ?? DEFAULT_FLASH_MS;
+  const now = opts.now ?? Date.now;
+  const setTimer = opts.setTimer ?? ((cb, ms) => setTimeout(cb, ms));
+  const clearTimer = opts.clearTimer ?? ((h) => clearTimeout(h));
+  const onChange = opts.onChange;
+
+  const providerStatuses = new Map<string, ProviderStatus>();
+
+  let state: SyncState = 'online';
+  let queuedOps = 0;
+  let lastSyncAt: number | null = null;
+  let offlineSince: number | null = null;
+  let flash: 'synced' | null = null;
+
+  let graceTimer: TimerHandle | null = null;
+  let escalateTimer: TimerHandle | null = null;
+  let flashTimer: TimerHandle | null = null;
+  let stopped = false;
+
+  function snapshot(): SyncStatusSnapshot {
+    return { state, queuedOps, lastSyncAt, offlineSince, flash, updatedAt: now() };
+  }
+
+  function emit(): void {
+    onChange?.(snapshot());
+  }
+
+  function clearAllTimers(): void {
+    if (graceTimer !== null) {
+      clearTimer(graceTimer);
+      graceTimer = null;
+    }
+    if (escalateTimer !== null) {
+      clearTimer(escalateTimer);
+      escalateTimer = null;
+    }
+  }
+
+  /** Aggregate provider statuses: connected if ANY is connected, else
+   *  connecting if ANY is connecting, else disconnected. An empty map (no
+   *  providers yet) is treated as connecting (boot, pre-handshake). */
+  function aggregate(): ProviderStatus {
+    if (providerStatuses.size === 0) return 'connecting';
+    let anyConnecting = false;
+    for (const s of providerStatuses.values()) {
+      if (s === 'connected') return 'connected';
+      if (s === 'connecting') anyConnecting = true;
+    }
+    return anyConnecting ? 'connecting' : 'disconnected';
+  }
+
+  function goOnline(): void {
+    const wasOffline = state === 'offline' || state === 'offline-long';
+    clearAllTimers();
+    state = 'online';
+    lastSyncAt = now();
+    offlineSince = null;
+    queuedOps = 0;
+    if (wasOffline) {
+      flash = 'synced';
+      if (flashTimer !== null) clearTimer(flashTimer);
+      flashTimer = setTimer(() => {
+        flashTimer = null;
+        flash = null;
+        if (!stopped) emit();
+      }, flashMs);
+    }
+    emit();
+  }
+
+  function enterGrace(): void {
+    // Already counting down or already offline — don't restart the clock.
+    if (state !== 'online') return;
+    state = 'connecting';
+    if (graceTimer !== null) clearTimer(graceTimer);
+    graceTimer = setTimer(() => {
+      graceTimer = null;
+      goOffline();
+    }, graceMs);
+    emit();
+  }
+
+  function goOffline(): void {
+    state = 'offline';
+    offlineSince = now();
+    if (escalateTimer !== null) clearTimer(escalateTimer);
+    escalateTimer = setTimer(() => {
+      escalateTimer = null;
+      state = 'offline-long';
+      emit();
+    }, escalateMs);
+    emit();
+  }
+
+  return {
+    noteProviderStatus(providerId, status) {
+      if (stopped) return;
+      providerStatuses.set(providerId, status);
+      const agg = aggregate();
+      if (agg === 'connected') {
+        if (state !== 'online') goOnline();
+        return;
+      }
+      // Aggregate is connecting or disconnected → start (or continue) the
+      // grace countdown. Once offline/offline-long we stay there until a
+      // provider reports 'connected' again.
+      if (state === 'online') enterGrace();
+    },
+
+    noteLocalEdit() {
+      if (stopped) return;
+      // Only count edits made while the hub is unreachable — those are the
+      // ones queued for replay. Edits while online flush immediately.
+      if (state === 'online') return;
+      queuedOps += 1;
+      emit();
+    },
+
+    snapshot,
+
+    stop() {
+      stopped = true;
+      clearAllTimers();
+      if (flashTimer !== null) {
+        clearTimer(flashTimer);
+        flashTimer = null;
+      }
+    },
+  };
+}