@buoy-gg/time-machine 7.0.17 → 7.0.18

package/src/components/preview/verdictMeta.ts

@@ -0,0 +1,40 @@
+/**
+ * One place for the verdict → glyph/color/label mapping. Color is ALWAYS
+ * paired with a distinct glyph (true minus U+2212, approx U+2248) — the
+ * repo-wide accessibility convention for diff surfaces.
+ */
+import { buoyColors } from "@buoy-gg/shared-ui";
+import type { StateSnapshotPreviewVerdict } from "@buoy-gg/shared-ui";
+
+export interface VerdictMeta {
+  glyph: string;
+  color: string;
+  label: string;
+  /** Counts toward "will change" totals. */
+  applies: boolean;
+}
+
+export const VERDICT_META: Record<StateSnapshotPreviewVerdict, VerdictMeta> = {
+  added: { glyph: "+", color: buoyColors.success, label: "added", applies: true },
+  removed: { glyph: "−", color: buoyColors.error, label: "removed", applies: true },
+  changed: { glyph: "≈", color: buoyColors.info, label: "changed", applies: true },
+  "too-large": {
+    glyph: "≈",
+    color: buoyColors.warning,
+    label: "changed (large)",
+    applies: true,
+  },
+  unchanged: { glyph: "=", color: buoyColors.textMuted, label: "unchanged", applies: false },
+  "wont-apply": {
+    glyph: "⊘",
+    color: buoyColors.warning,
+    label: "won't apply",
+    applies: false,
+  },
+  recomputes: {
+    glyph: "↻",
+    color: buoyColors.textMuted,
+    label: "recomputes",
+    applies: false,
+  },
+};

package/src/preset.tsx

@@ -13,7 +13,8 @@ import {
   TimeMachineIcon,
   TIME_MACHINE_ICON_COLOR,
 } from "@buoy-gg/shared-ui";
-import { TimeMachineModal } from "./components/TimeMachineModal";
+import { TimeMachineBody } from "./components/TimeMachineBody";
+import { HeaderReloadButton } from "./components/HeaderReloadButton";
 
 export const timeMachineToolPreset = {
   id: "time-machine",
@@ -23,7 +24,15 @@ export const timeMachineToolPreset = {
   icon: ({ size, color }: { size: number; color?: string }) => (
     <TimeMachineIcon size={size} color={color || TIME_MACHINE_ICON_COLOR} />
   ),
-  component: TimeMachineModal,
+  component: TimeMachineBody,
+  // Declarative chrome: core's ToolModalShell provides the JsModal, the
+  // managed header (screens override it via useToolHeader) and header search.
+  modal: {
+    subtitle: "snapshot & restore app state",
+    searchable: true,
+    searchPlaceholder: "Filter…",
+    headerActions: <HeaderReloadButton />,
+  },
 };
 
 /** Create a custom Time Machine tool configuration. */

package/src/store/snapshotVault.ts

@@ -37,6 +37,12 @@ export interface SnapshotMeta {
    * fresh-install state (clear + reload).
    */
   baseline?: boolean;
+  /**
+   * User-saved restore scope: compound "sourceId::itemKey" strings. When set,
+   * restoring this snapshot touches ONLY these items — "this restore point
+   * means just my cart". Absent = full restore.
+   */
+  scope?: string[];
   /** Source ids captured, with their capture warnings. */
   sources: Record<string, SnapshotSourceMeta>;
 }
@@ -101,6 +107,28 @@ export async function deleteSnapshot(
   return next;
 }
 
+export async function setSnapshotScope(
+  id: string,
+  scope: string[] | null,
+  metas: SnapshotMeta[]
+): Promise<SnapshotMeta[]> {
+  const apply = (m: SnapshotMeta): SnapshotMeta => {
+    if (m.id !== id) return m;
+    const next = { ...m };
+    if (scope && scope.length > 0) next.scope = scope;
+    else delete next.scope;
+    return next;
+  };
+  const next = metas.map(apply);
+  await persistentStorage.setItem(INDEX_KEY, JSON.stringify(next));
+  const stored = await loadSnapshot(id);
+  if (stored) {
+    stored.meta = apply(stored.meta);
+    await persistentStorage.setItem(SNAP_PREFIX + id, JSON.stringify(stored));
+  }
+  return next;
+}
+
 export async function renameSnapshot(
   id: string,
   name: string,

package/src/store/timeMachineStore.ts

@@ -21,14 +21,18 @@ import {
   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,
   loadIndex,
   loadSnapshot,
   renameSnapshot,
   saveSnapshot,
+  setSnapshotScope,
   type SnapshotMeta,
   type StoredSnapshot,
 } from "./snapshotVault";
@@ -56,11 +60,32 @@ export interface RemoteProviderStatus {
   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
@@ -92,8 +117,12 @@ class TimeMachineStore {
     hasLoaded: false,
     busy: null,
     lastOutcome: null,
+    preview: null,
     remoteProviders: 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;
 
@@ -222,9 +251,22 @@ class TimeMachineStore {
     return snapshot.meta;
   }
 
-  async restore(id: string, mode: RestoreMode): Promise<RestoreOutcome> {
+  /**
+   * `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[]
+  ): Promise<RestoreOutcome> {
     if (remoteHandler) {
-      const outcome = (await remoteHandler("restore", { id, mode })) as RestoreOutcome;
+      const outcome = (await remoteHandler("restore", {
+        id,
+        mode,
+        excludeKeys,
+      })) as RestoreOutcome;
       this.setState({ lastOutcome: outcome });
       return outcome;
     }
@@ -265,12 +307,40 @@ class TimeMachineStore {
         ...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;
+      };
+
+      const excludeBySource = splitCompound(excludeKeys ?? []);
+      // 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;
+
       if (mode === "reload") {
         // Storage only; everything in-memory rebuilds after the reload.
-        if (stored.data.storage) {
+        if (
+          stored.data.storage &&
+          (!includeBySource || includeBySource.has("storage"))
+        ) {
           outcome.results.storage = await this.restoreSource(
             "storage",
-            stored.data.storage
+            stored.data.storage,
+            excludeBySource.get("storage"),
+            includeBySource?.get("storage")
           );
         }
         outcome.willReload = this.scheduleReload("buoy time-machine restore");
@@ -279,7 +349,14 @@ class TimeMachineStore {
       }
 
       for (const sid of sourceIds) {
-        outcome.results[sid] = await this.restoreSource(sid, stored.data[sid]);
+        // 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)
+        );
       }
       this.setState({ lastOutcome: outcome });
       return outcome;
@@ -290,7 +367,9 @@ class TimeMachineStore {
 
   private async restoreSource(
     sourceId: string,
-    payload: SuperJSONResult
+    payload: SuperJSONResult,
+    excludeKeys?: readonly string[],
+    includeKeys?: readonly string[]
   ): Promise<StateSnapshotRestoreResult> {
     const provider = getStateSnapshotProvider(sourceId);
     if (!provider) {
@@ -301,7 +380,14 @@ class TimeMachineStore {
       return skippedResult(status.detail ?? "restore unavailable");
     }
     try {
-      return await provider.restore(superJsonDeserialize(payload));
+      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));
     }
@@ -337,9 +423,246 @@ class TimeMachineStore {
     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 });
+  }
+
   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();

package/src/sync/timeMachineSyncAdapter.ts

@@ -16,7 +16,12 @@ import {
   subscribeToStateSnapshotProviders,
   superJsonDeserialize,
 } from "@buoy-gg/shared-ui";
-import { timeMachineStore, type RestoreMode } from "../store/timeMachineStore";
+import { jsonLikelyLargerThan } from "@buoy-gg/shared-ui/dataViewer";
+import {
+  timeMachineStore,
+  type PreviewSideRef,
+  type RestoreMode,
+} from "../store/timeMachineStore";
 import { loadSnapshot } from "../store/snapshotVault";
 
 interface CaptureParams {
@@ -26,6 +31,8 @@ interface CaptureParams {
 interface RestoreParams {
   id: string;
   mode?: RestoreMode;
+  /** Compound "sourceId::itemKey" strings — items the caller opted out of. */
+  excludeKeys?: string[];
 }
 interface IdParams {
   id: string;
@@ -82,13 +89,16 @@ export const timeMachineSyncAdapter = {
       return { captured: true, snapshot: meta };
     },
 
+    /** Wipe every clearable source to fresh-install state, then reload. */
+    wipeAll: async () => await timeMachineStore.wipeAll(),
+
     /** mode "live" (default) replaces state in place; "reload" restores
      * persisted storage then reloads the JS bundle (always the path for
      * baseline snapshots). */
     restore: async (params: unknown) => {
-      const { id, mode = "live" } = (params as RestoreParams) ?? {};
+      const { id, mode = "live", excludeKeys } = (params as RestoreParams) ?? {};
       if (!id) throw new Error("restore requires a snapshot `id`");
-      return await timeMachineStore.restore(id, mode);
+      return await timeMachineStore.restore(id, mode, excludeKeys);
     },
 
     delete: async (params: unknown) => {
@@ -105,6 +115,56 @@ export const timeMachineSyncAdapter = {
       return { renamed: true, id, name };
     },
 
+    /** Save (or clear with null/empty) a snapshot's targeted-restore scope. */
+    setScope: async (params: unknown) => {
+      const { id, scope } =
+        (params as { id?: string; scope?: string[] | null }) ?? {};
+      if (!id) throw new Error("setScope requires a snapshot `id`");
+      await timeMachineStore.setScope(id, scope ?? null);
+      return { scoped: true, id, count: scope?.length ?? 0 };
+    },
+
+    /**
+     * Item-level restore preview, computed ON-DEVICE. Values above ~4KB per
+     * item are omitted (valueOmitted) so the result stays far under the 8MB
+     * action budget on any app size.
+     */
+    preview: async (params: unknown) => {
+      const { id, compareTo } =
+        (params as { id?: string; compareTo?: string }) ?? {};
+      if (!id) throw new Error("preview requires a snapshot `id`");
+      const right: PreviewSideRef = { snapshotId: id };
+      const left: PreviewSideRef = compareTo
+        ? { snapshotId: compareTo }
+        : "current";
+      await timeMachineStore.buildPreview(right, left);
+      const preview = timeMachineStore.getState().preview;
+      if (!preview) throw new Error("preview build produced no result");
+      const VALUE_BUDGET = 4 * 1024;
+      return {
+        left,
+        right,
+        builtAt: preview.builtAt,
+        sources: preview.sources.map((src) => ({
+          ...src,
+          items: src.items.map((item) => {
+            const oldBig =
+              item.oldValue !== undefined &&
+              jsonLikelyLargerThan(item.oldValue, VALUE_BUDGET);
+            const newBig =
+              item.newValue !== undefined &&
+              jsonLikelyLargerThan(item.newValue, VALUE_BUDGET);
+            return {
+              ...item,
+              oldValue: oldBig ? undefined : item.oldValue,
+              newValue: newBig ? undefined : item.newValue,
+              ...(oldBig || newBig ? { valueOmitted: true } : {}),
+            };
+          }),
+        })),
+      };
+    },
+
     /** One source's captured payload, deserialized — for remote inspection. */
     inspect: async (params: unknown) => {
       const { id, sourceId } = (params as InspectParams) ?? {};