@buoy-gg/time-machine 7.0.28 → 7.0.30

package/src/store/timeMachineStore.ts

@@ -1,881 +0,0 @@
-/**
- * Time Machine orchestrator — snapshot CRUD + capture/restore across every
- * registered StateSnapshotProvider (storage, redux, zustand, jotai, query,
- * plus any custom providers the app registers).
- *
- * Restore ordering is fixed: persisted storage FIRST (so store persist
- * middleware writing through after an in-memory restore converges with what
- * we just wrote), then redux → zustand → jotai, query LAST (restored queries
- * may derive from store state). Custom providers run after, in data order.
- *
- * Two restore modes:
- * - "live":   in-place state replacement, capability-gated per source.
- * - "reload": restore ONLY persisted storage, then reload the JS bundle —
- *             in-memory stores rebuild themselves from the restored storage.
- *             Baseline snapshots always use this path (clear + reload).
- */
-import {
-  getStateSnapshotProvider,
-  getStateSnapshotProviders,
-  scheduleReloadApp,
-  superJsonDeserialize,
-  superJsonSerialize,
-  type StateSnapshotRestoreResult,
-  type StateSnapshotPreview,
-  type StateSnapshotPreviewItem,
-  type SuperJSONResult,
-} from "@buoy-gg/shared-ui";
-import { objectDiff } from "@buoy-gg/shared-ui/dataViewer";
-import {
-  deleteSnapshot,
-  duplicateSnapshot,
-  loadIndex,
-  loadSnapshot,
-  markSnapshotRestored,
-  readSnapshot,
-  renameSnapshot,
-  restoreDeletedSnapshot,
-  saveSnapshot,
-  setSnapshotRestoreRoute,
-  setSnapshotScope,
-  setSnapshotExclusions,
-  type SnapshotMeta,
-  type StoredSnapshot,
-} from "./snapshotVault";
-import {
-  captureCurrentRoute,
-  navigateToRoute,
-  savePendingRoute,
-  type RouteRestoreResult,
-} from "./routeRestore";
-
-export const RESTORE_ORDER = ["storage", "redux", "zustand", "jotai", "query"];
-
-export type RestoreMode = "live" | "reload";
-
-export interface RestoreOutcome {
-  snapshotId: string;
-  snapshotName: string;
-  mode: RestoreMode;
-  at: number;
-  /** True when a JS reload was scheduled as part of this restore. */
-  willReload: boolean;
-  results: Record<string, StateSnapshotRestoreResult>;
-  /**
-   * Present when the caller asked to also return to the snapshot's route.
-   * "deferred" means the navigation is queued for the post-reload boot.
-   */
-  route?: RouteRestoreResult;
-}
-
-/**
- * What to call a capture nobody named. The screen you were on plus the time
- * is the pair that makes a restore point recognizable an hour later —
- * "Untitled snapshot" never was, and typing mid-flow is the friction that
- * produced it.
- */
-function defaultSnapshotName(route: { pathname: string } | null | undefined): string {
-  const now = new Date();
-  const clock = `${String(now.getHours()).padStart(2, "0")}:${String(
-    now.getMinutes()
-  ).padStart(2, "0")}`;
-  return route ? `${route.pathname} · ${clock}` : `Snapshot · ${clock}`;
-}
-
-/**
- * Will restoring this point also navigate back to its route? Having a route
- * means wanting it back unless the point says otherwise — the same rule
- * `restore` applies, exported so the UI can't drift from it.
- */
-export function willRestoreRoute(meta: SnapshotMeta): boolean {
-  return !!meta.route && (meta.restoreRoute ?? true);
-}
-
-/** Extra knobs a restore accepts beyond mode + exclusions. */
-export interface RestoreOptions {
-  /**
-   * Also navigate back to the route the snapshot was captured on. Ignored for
-   * snapshots with no captured route (and for baselines, which wipe to the
-   * app's own start route).
-   */
-  restoreRoute?: boolean;
-}
-
-/** Provider capability row as mirrored to a remote dashboard. */
-export interface RemoteProviderStatus {
-  id: string;
-  label: string;
-  canCapture: boolean;
-  canRestore: boolean;
-  detail?: string;
-}
-
-/** One side of a preview comparison. */
-export type PreviewSideRef = "current" | { snapshotId: string };
-
-export interface PreviewSource {
-  id: string;
-  label: string;
-  items: StateSnapshotPreviewItem[];
-  notes: string[];
-  error?: string;
-}
-
-export interface PreviewState {
-  left: PreviewSideRef;
-  right: PreviewSideRef;
-  /** True while the pipeline is still filling `sources` in. */
-  building: boolean;
-  builtAt: number;
-  sources: PreviewSource[];
-}
-
-export interface TimeMachineState {
-  snapshots: SnapshotMeta[];
-  hasLoaded: boolean;
-  busy: "capture" | "restore" | null;
-  lastOutcome: RestoreOutcome | null;
-  preview: PreviewState | null;
-  /**
-   * Non-null when this store is a REMOTE MIRROR (Buoy Desktop): provider
-   * statuses come from the device's sync payload instead of the local
-   * registry, and every operation forwards over the socket.
-   */
-  remoteProviders: RemoteProviderStatus[] | null;
-  /**
-   * Route capture/restore availability, mirrored from the device's payload
-   * (Buoy Desktop). Null on-device, where the live router is probed directly.
-   */
-  remoteRoute: RouteToolStatus | null;
-  /**
-   * The last deleted record, held in memory so the list can offer an undo.
-   * The vault row is already gone — this is the only copy until it expires.
-   */
-  recentlyDeleted: { stored: StoredSnapshot; at: number } | null;
-}
-
-/** Whether this device can capture and return to routes, and where it is now. */
-export interface RouteToolStatus {
-  available: boolean;
-  /** The route the app is on right now, when one can be read. */
-  current?: string;
-}
-
-type RemoteHandler = (
-  action: string,
-  params?: Record<string, unknown>
-) => Promise<unknown>;
-
-let remoteHandler: RemoteHandler | null = null;
-
-function skippedResult(reason: string): StateSnapshotRestoreResult {
-  return { ok: false, applied: 0, skipped: [{ id: "*", reason }], warnings: [] };
-}
-
-let idCounter = 0;
-function nextId(): string {
-  idCounter += 1;
-  return `snap_${Date.now().toString(36)}_${idCounter.toString(36)}`;
-}
-
-class TimeMachineStore {
-  private state: TimeMachineState = {
-    snapshots: [],
-    hasLoaded: false,
-    busy: null,
-    lastOutcome: null,
-    preview: null,
-    remoteProviders: null,
-    remoteRoute: null,
-    recentlyDeleted: null,
-  };
-  /** Monotonic token — a preview build checks it after every await and
-   * abandons itself when a newer build (or clearPreview) supersedes it. */
-  private previewRunId = 0;
-  private listeners = new Set<() => void>();
-  private loadPromise: Promise<void> | null = null;
-
-  getState(): TimeMachineState {
-    return this.state;
-  }
-
-  subscribe = (listener: () => void): (() => void) => {
-    this.listeners.add(listener);
-    void this.ensureLoaded();
-    return () => {
-      this.listeners.delete(listener);
-    };
-  };
-
-  private setState(patch: Partial<TimeMachineState>) {
-    this.state = { ...this.state, ...patch };
-    this.listeners.forEach((l) => {
-      try {
-        l();
-      } catch {
-        // listener errors must not break the store
-      }
-    });
-  }
-
-  ensureLoaded(): Promise<void> {
-    if (remoteHandler) return Promise.resolve(); // mirror mode — device owns the vault
-    if (!this.loadPromise) {
-      this.loadPromise = loadIndex().then((snapshots) => {
-        if (remoteHandler) return;
-        this.setState({ snapshots, hasLoaded: true });
-      });
-    }
-    return this.loadPromise;
-  }
-
-  /** @internal Buoy Desktop: mirror the device's synced metadata payload. */
-  replaceFromSnapshot(payload: {
-    snapshots?: SnapshotMeta[];
-    busy?: TimeMachineState["busy"];
-    lastOutcome?: RestoreOutcome | null;
-    providers?: RemoteProviderStatus[];
-    route?: RouteToolStatus;
-  }): void {
-    this.setState({
-      snapshots: payload.snapshots ?? [],
-      busy: payload.busy ?? null,
-      lastOutcome: payload.lastOutcome ?? null,
-      remoteProviders: payload.providers ?? [],
-      remoteRoute: payload.route ?? { available: false },
-      hasLoaded: true,
-    });
-  }
-
-  /** Capture all capturable sources (or a subset) into a named snapshot. */
-  async capture(name: string, sourceIds?: string[]): Promise<SnapshotMeta> {
-    if (remoteHandler) {
-      const result = (await remoteHandler("capture", { name, sourceIds })) as {
-        snapshot: SnapshotMeta;
-      };
-      return result.snapshot;
-    }
-    await this.ensureLoaded();
-    this.setState({ busy: "capture" });
-    try {
-      const providers = getStateSnapshotProviders().filter(
-        (p) =>
-          p.status().canCapture && (!sourceIds || sourceIds.includes(p.id))
-      );
-      const data: Record<string, SuperJSONResult> = {};
-      const sources: SnapshotMeta["sources"] = {};
-      for (const provider of providers) {
-        try {
-          const captured = await provider.capture();
-          data[provider.id] = superJsonSerialize(captured.data);
-          sources[provider.id] = { warnings: captured.warnings };
-        } catch (e) {
-          sources[provider.id] = {
-            warnings: [`capture failed: ${String(e)}`],
-          };
-        }
-      }
-      // Where the app was when this state was true — restoring can return here.
-      const route = captureCurrentRoute();
-      const snapshot: StoredSnapshot = {
-        meta: {
-          id: nextId(),
-          name: name.trim() || defaultSnapshotName(route),
-          createdAt: Date.now(),
-          sizeBytes: 0,
-          ...(route ? { route } : {}),
-          sources,
-        },
-        data,
-      };
-      const snapshots = await saveSnapshot(snapshot, this.state.snapshots);
-      this.setState({ snapshots });
-      return snapshot.meta;
-    } finally {
-      this.setState({ busy: null });
-    }
-  }
-
-  /**
-   * Capture the fresh-install baseline: an EMPTY snapshot whose restore
-   * wipes app state (clear + reload) — regardless of what state the app is
-   * in when the button is pressed.
-   */
-  async captureBaseline(): Promise<SnapshotMeta> {
-    if (remoteHandler) {
-      const result = (await remoteHandler("captureBaseline", {})) as {
-        snapshot: SnapshotMeta;
-      };
-      return result.snapshot;
-    }
-    await this.ensureLoaded();
-    const snapshot: StoredSnapshot = {
-      meta: {
-        id: nextId(),
-        name: "Fresh install",
-        createdAt: Date.now(),
-        sizeBytes: 0,
-        baseline: true,
-        sources: {},
-      },
-      data: {},
-    };
-    const snapshots = await saveSnapshot(snapshot, this.state.snapshots);
-    this.setState({ snapshots });
-    return snapshot.meta;
-  }
-
-  /**
-   * `excludeKeys` entries are compound `"sourceId::itemKey"` strings (the
-   * itemKey being what previewItems emitted) — split per source before each
-   * provider sees only its own keys.
-   */
-  async restore(
-    id: string,
-    mode: RestoreMode,
-    excludeKeys?: readonly string[],
-    options?: RestoreOptions
-  ): Promise<RestoreOutcome> {
-    if (remoteHandler) {
-      const outcome = (await remoteHandler("restore", {
-        id,
-        mode,
-        excludeKeys,
-        restoreRoute: options?.restoreRoute,
-      })) as RestoreOutcome;
-      this.setState({ lastOutcome: outcome });
-      return outcome;
-    }
-    await this.ensureLoaded();
-    this.setState({ busy: "restore" });
-    try {
-      const stored = await loadSnapshot(id);
-      if (!stored) throw new Error(`No snapshot with id "${id}"`);
-
-      const outcome: RestoreOutcome = {
-        snapshotId: id,
-        snapshotName: stored.meta.name,
-        mode,
-        at: Date.now(),
-        willReload: false,
-        results: {},
-      };
-
-      if (stored.meta.baseline) {
-        // Fresh install: wipe every clearable source, then reload so all
-        // in-memory state rebuilds from nothing.
-        for (const provider of getStateSnapshotProviders()) {
-          if (provider.clear) {
-            try {
-              outcome.results[provider.id] = await provider.clear();
-            } catch (e) {
-              outcome.results[provider.id] = skippedResult(String(e));
-            }
-          }
-        }
-        outcome.willReload = this.scheduleReload("buoy time-machine baseline");
-        this.setState({ lastOutcome: outcome });
-        return outcome;
-      }
-
-      const sourceIds = [
-        ...RESTORE_ORDER.filter((sid) => sid in stored.data),
-        ...Object.keys(stored.data).filter((sid) => !RESTORE_ORDER.includes(sid)),
-      ];
-
-      const splitCompound = (keys: readonly string[]) => {
-        const bySource = new Map<string, string[]>();
-        for (const compound of keys) {
-          const sep = compound.indexOf("::");
-          if (sep <= 0) continue;
-          const sid = compound.slice(0, sep);
-          const itemKey = compound.slice(sep + 2);
-          const list = bySource.get(sid) ?? [];
-          list.push(itemKey);
-          bySource.set(sid, list);
-        }
-        return bySource;
-      };
-
-      // No explicit list means "use what the user saved in the preview" —
-      // that is what makes an unchecked item stay unchecked forever, for the
-      // one-tap RESTORE on the list and for MCP alike.
-      const effectiveExcludes = excludeKeys ?? stored.meta.excludedKeys ?? [];
-      const excludeBySource = splitCompound(effectiveExcludes);
-      // A saved scope makes this a targeted restore point. An explicit
-      // exclusion list from the preview already reflects the scope (the
-      // preview seeds its selection from it), so it takes precedence.
-      const includeBySource =
-        !excludeKeys && stored.meta.scope?.length
-          ? splitCompound(stored.meta.scope)
-          : null;
-
-      // No prompt any more: the point carries its own answer, and having a
-      // route means wanting it back unless you said otherwise. An explicit
-      // option still wins, so MCP and the desktop can force either way.
-      const wantsRoute =
-        options?.restoreRoute ?? willRestoreRoute(stored.meta);
-
-      if (mode === "reload") {
-        // Storage only; everything in-memory rebuilds after the reload.
-        if (
-          stored.data.storage &&
-          (!includeBySource || includeBySource.has("storage"))
-        ) {
-          outcome.results.storage = await this.restoreSource(
-            "storage",
-            stored.data.storage,
-            excludeBySource.get("storage"),
-            includeBySource?.get("storage")
-          );
-        }
-        // Hand the route to the NEXT boot — this realm is about to die, so the
-        // slot must be written before the reload is armed.
-        if (wantsRoute) {
-          const route = stored.meta.route!;
-          try {
-            await savePendingRoute(route, stored.meta.name);
-            outcome.route = { ...route, status: "deferred" };
-          } catch (e) {
-            outcome.route = { ...route, status: "failed", error: String(e) };
-          }
-        }
-        outcome.willReload = this.scheduleReload("buoy time-machine restore");
-        // Stamped BEFORE the reload is armed — the JS realm is about to die.
-        this.setState({
-          lastOutcome: outcome,
-          snapshots: await markSnapshotRestored(id, outcome.at, this.state.snapshots),
-        });
-        return outcome;
-      }
-
-      for (const sid of sourceIds) {
-        // Sources entirely outside the scope are untouched and unreported.
-        if (includeBySource && !includeBySource.has(sid)) continue;
-        outcome.results[sid] = await this.restoreSource(
-          sid,
-          stored.data[sid],
-          excludeBySource.get(sid),
-          includeBySource?.get(sid)
-        );
-      }
-      // Navigate LAST — the screen we land on should read the restored state.
-      if (wantsRoute) {
-        outcome.route = navigateToRoute(stored.meta.route!);
-      }
-      this.setState({
-        lastOutcome: outcome,
-        snapshots: await markSnapshotRestored(id, outcome.at, this.state.snapshots),
-      });
-      return outcome;
-    } finally {
-      this.setState({ busy: null });
-    }
-  }
-
-  private async restoreSource(
-    sourceId: string,
-    payload: SuperJSONResult,
-    excludeKeys?: readonly string[],
-    includeKeys?: readonly string[]
-  ): Promise<StateSnapshotRestoreResult> {
-    const provider = getStateSnapshotProvider(sourceId);
-    if (!provider) {
-      return skippedResult("provider not available (package missing or not initialized)");
-    }
-    const status = provider.status();
-    if (!status.canRestore) {
-      return skippedResult(status.detail ?? "restore unavailable");
-    }
-    try {
-      const options =
-        excludeKeys?.length || includeKeys?.length
-          ? {
-              ...(excludeKeys?.length ? { excludeKeys } : {}),
-              ...(includeKeys?.length ? { includeKeys } : {}),
-            }
-          : undefined;
-      return await provider.restore(superJsonDeserialize(payload), options);
-    } catch (e) {
-      return skippedResult(String(e));
-    }
-  }
-
-  private scheduleReload(reason: string): boolean {
-    try {
-      scheduleReloadApp({ reason });
-      return true;
-    } catch {
-      // No reload mechanism (bare production build?) — restore still stands.
-      return false;
-    }
-  }
-
-  /**
-   * Delete, holding the whole record in memory so `undoDelete` can put it
-   * back. Swipe-and-tap is deliberate but not recoverable, and those are
-   * different properties — a restore point can represent state that takes
-   * ten minutes and a cooperative backend to rebuild.
-   */
-  async delete(id: string): Promise<void> {
-    if (remoteHandler) {
-      await remoteHandler("delete", { id });
-      return;
-    }
-    await this.ensureLoaded();
-    const stored = await readSnapshot(id);
-    const snapshots = await deleteSnapshot(id, this.state.snapshots);
-    this.setState({
-      snapshots,
-      recentlyDeleted: stored ? { stored, at: Date.now() } : null,
-    });
-  }
-
-  /** Put the last deleted point back. No-op once the window has passed. */
-  async undoDelete(): Promise<void> {
-    const held = this.state.recentlyDeleted;
-    if (!held) return;
-    const snapshots = await restoreDeletedSnapshot(
-      held.stored,
-      this.state.snapshots
-    );
-    this.setState({ snapshots, recentlyDeleted: null });
-  }
-
-  /** Drop the undo offer — on timeout, or when the user moves on. */
-  clearRecentlyDeleted(): void {
-    if (this.state.recentlyDeleted) this.setState({ recentlyDeleted: null });
-  }
-
-  /** Turn this point's route restore on or off. */
-  async setRestoreRoute(id: string, restoreRoute: boolean): Promise<void> {
-    if (remoteHandler) {
-      await remoteHandler("setRestoreRoute", { id, restoreRoute });
-      return;
-    }
-    await this.ensureLoaded();
-    const snapshots = await setSnapshotRestoreRoute(
-      id,
-      restoreRoute,
-      this.state.snapshots
-    );
-    this.setState({ snapshots });
-  }
-
-  /** Copy a point so a variation can start from a known-good base. */
-  async duplicate(id: string): Promise<SnapshotMeta | null> {
-    if (remoteHandler) {
-      const result = (await remoteHandler("duplicate", { id })) as {
-        snapshot: SnapshotMeta;
-      } | null;
-      return result?.snapshot ?? null;
-    }
-    await this.ensureLoaded();
-    const source = this.state.snapshots.find((s) => s.id === id);
-    if (!source) return null;
-    const result = await duplicateSnapshot(
-      id,
-      `${source.name} copy`,
-      this.state.snapshots
-    );
-    if (!result) return null;
-    this.setState({ snapshots: result.metas });
-    return result.meta;
-  }
-
-  async rename(id: string, name: string): Promise<void> {
-    if (remoteHandler) {
-      await remoteHandler("rename", { id, name });
-      return;
-    }
-    await this.ensureLoaded();
-    const snapshots = await renameSnapshot(id, name, this.state.snapshots);
-    this.setState({ snapshots });
-  }
-
-  /**
-   * Save (or clear with null/empty) a snapshot's restore scope — compound
-   * "sourceId::itemKey" strings. A scoped restore point only ever touches
-   * its scoped items.
-   */
-  async setScope(id: string, scope: string[] | null): Promise<void> {
-    if (remoteHandler) {
-      await remoteHandler("setScope", { id, scope });
-      return;
-    }
-    await this.ensureLoaded();
-    const snapshots = await setSnapshotScope(id, scope, this.state.snapshots);
-    this.setState({ snapshots });
-  }
-
-  /**
-   * Save (or clear with null/empty) the items every later restore of this
-   * snapshot must leave untouched — what the restore preview's checkboxes
-   * write when you save a selection.
-   */
-  async setExclusions(id: string, excludedKeys: string[] | null): Promise<void> {
-    if (remoteHandler) {
-      await remoteHandler("setExclusions", { id, excludedKeys });
-      return;
-    }
-    await this.ensureLoaded();
-    const snapshots = await setSnapshotExclusions(
-      id,
-      excludedKeys,
-      this.state.snapshots
-    );
-    this.setState({ snapshots });
-  }
-
-  clearLastOutcome(): void {
-    this.setState({ lastOutcome: null });
-  }
-
-  /**
-   * Wipe every clearable source to fresh-install state and reload — the
-   * standalone utility behind the home screen's "Wipe all app state" button
-   * (no baseline snapshot involved).
-   */
-  async wipeAll(): Promise<RestoreOutcome> {
-    if (remoteHandler) {
-      const outcome = (await remoteHandler("wipeAll", {})) as RestoreOutcome;
-      this.setState({ lastOutcome: outcome });
-      return outcome;
-    }
-    this.setState({ busy: "restore" });
-    try {
-      const outcome: RestoreOutcome = {
-        snapshotId: "wipe-all",
-        snapshotName: "Wipe all",
-        mode: "reload",
-        at: Date.now(),
-        willReload: false,
-        results: {},
-      };
-      for (const provider of getStateSnapshotProviders()) {
-        if (provider.clear) {
-          try {
-            outcome.results[provider.id] = await provider.clear();
-          } catch (e) {
-            outcome.results[provider.id] = skippedResult(String(e));
-          }
-        }
-      }
-      outcome.willReload = this.scheduleReload("buoy time-machine wipe all");
-      this.setState({ lastOutcome: outcome });
-      return outcome;
-    } finally {
-      this.setState({ busy: null });
-    }
-  }
-
-  clearPreview(): void {
-    this.previewRunId += 1;
-    this.setState({ preview: null });
-  }
-
-  /**
-   * Build (or rebuild) the restore preview: item-level verdicts per source,
-   * filled in incrementally with a frame yield between sources so a big app
-   * never freezes the JS thread in one go.
-   */
-  async buildPreview(
-    right: PreviewSideRef,
-    left: PreviewSideRef = "current"
-  ): Promise<void> {
-    if (remoteHandler) {
-      // Buoy Desktop: the device builds it; result mirrors into state.
-      const runId = ++this.previewRunId;
-      this.setState({
-        preview: { left, right, building: true, builtAt: Date.now(), sources: [] },
-      });
-      try {
-        const result = (await remoteHandler("preview", {
-          id: right === "current" ? undefined : right.snapshotId,
-          compareTo: left === "current" ? undefined : left.snapshotId,
-        })) as { sources: PreviewSource[] };
-        if (runId !== this.previewRunId) return;
-        this.setState({
-          preview: {
-            left,
-            right,
-            building: false,
-            builtAt: Date.now(),
-            sources: result.sources ?? [],
-          },
-        });
-      } catch (e) {
-        if (runId !== this.previewRunId) return;
-        this.setState({
-          preview: {
-            left,
-            right,
-            building: false,
-            builtAt: Date.now(),
-            sources: [
-              { id: "error", label: "Preview", items: [], notes: [], error: String(e) },
-            ],
-          },
-        });
-      }
-      return;
-    }
-
-    await this.ensureLoaded();
-    const runId = ++this.previewRunId;
-    this.setState({
-      preview: { left, right, building: true, builtAt: Date.now(), sources: [] },
-    });
-
-    const loadSide = async (
-      ref: PreviewSideRef
-    ): Promise<Record<string, SuperJSONResult> | null> => {
-      if (ref === "current") return null; // providers capture live themselves
-      const stored = await loadSnapshot(ref.snapshotId);
-      if (!stored) throw new Error(`No snapshot with id "${ref.snapshotId}"`);
-      return stored.data;
-    };
-
-    try {
-      if (right === "current") throw new Error("preview target must be a snapshot");
-      const [leftData, rightStored] = await Promise.all([
-        loadSide(left),
-        loadSnapshot(right.snapshotId),
-      ]);
-      if (runId !== this.previewRunId) return;
-      if (!rightStored) {
-        throw new Error(`No snapshot with id "${right.snapshotId}"`);
-      }
-      const rightData = rightStored.data;
-
-      // Baseline = empty target: preview every clearable source against live,
-      // so each live key naturally reads as "removed" — the informed wipe.
-      const isBaseline = rightStored.meta.baseline === true;
-      const sourceIds = isBaseline
-        ? getStateSnapshotProviders()
-            .filter((p) => p.clear)
-            .map((p) => p.id)
-        : [
-            ...RESTORE_ORDER.filter((sid) => sid in rightData),
-            ...Object.keys(rightData).filter(
-              (sid) => !RESTORE_ORDER.includes(sid)
-            ),
-          ];
-
-      const sources: PreviewSource[] = [];
-      for (const sid of sourceIds) {
-        // Yield a frame between sources — verdict passes are bounded but a
-        // five-source build shouldn't run as one synchronous block.
-        await new Promise((r) => setTimeout(r, 0));
-        if (runId !== this.previewRunId) return;
-
-        const provider = getStateSnapshotProvider(sid);
-        const label = provider?.label ?? sid;
-        try {
-          const targetData = isBaseline
-            ? undefined // provider treats an absent target as "empty"
-            : superJsonDeserialize(rightData[sid]);
-          const baseData =
-            leftData === null
-              ? undefined
-              : sid in leftData
-                ? superJsonDeserialize(leftData[sid])
-                : undefined;
-          let result: StateSnapshotPreview;
-          if (!provider) {
-            result = {
-              items: [
-                {
-                  key: sid,
-                  label,
-                  verdict: "wont-apply",
-                  reason: "tool not installed — restore skips this source",
-                },
-              ],
-              notes: [],
-            };
-          } else if (provider.previewItems) {
-            result = await provider.previewItems(targetData, baseData);
-          } else {
-            // Whole-source fallback for custom providers without previewItems.
-            const diff = objectDiff(baseData, targetData);
-            result = {
-              items: [
-                {
-                  key: sid,
-                  label,
-                  verdict: diff.equal ? "unchanged" : "changed",
-                  oldValue: baseData,
-                  newValue: targetData,
-                },
-              ],
-              notes: diff.truncated ? ["diff truncated (large value)"] : [],
-            };
-          }
-          if (runId !== this.previewRunId) return;
-          sources.push({ id: sid, label, ...result });
-        } catch (e) {
-          sources.push({ id: sid, label, items: [], notes: [], error: String(e) });
-        }
-        this.setState({
-          preview: {
-            left,
-            right,
-            building: true,
-            builtAt: Date.now(),
-            sources: [...sources],
-          },
-        });
-      }
-      if (runId !== this.previewRunId) return;
-      this.setState({
-        preview: {
-          left,
-          right,
-          building: false,
-          builtAt: Date.now(),
-          sources,
-        },
-      });
-    } catch (e) {
-      if (runId !== this.previewRunId) return;
-      this.setState({
-        preview: {
-          left,
-          right,
-          building: false,
-          builtAt: Date.now(),
-          sources: [
-            { id: "error", label: "Preview", items: [], notes: [], error: String(e) },
-          ],
-        },
-      });
-    }
-  }
-}
-
-export const timeMachineStore = new TimeMachineStore();
-
-/**
- * Buoy Desktop: route every Time Machine operation through a remote handler
- * (the device's sync adapter actions) instead of running locally. Pass null
- * to detach. While attached, feed device payloads to
- * {@link replaceTimeMachineFromSnapshot}.
- */
-export function setRemoteTimeMachineHandler(handler: RemoteHandler | null): void {
-  remoteHandler = handler;
-  if (!handler) {
-    timeMachineStore.replaceFromSnapshot({});
-  }
-}
-
-/** Buoy Desktop: mirror a device's synced Time Machine metadata payload. */
-export function replaceTimeMachineFromSnapshot(payload: {
-  snapshots?: SnapshotMeta[];
-  busy?: TimeMachineState["busy"];
-  lastOutcome?: RestoreOutcome | null;
-  providers?: RemoteProviderStatus[];
-  route?: RouteToolStatus;
-}): void {
-  timeMachineStore.replaceFromSnapshot(payload);
-}