@buoy-gg/time-machine 7.0.22 → 7.0.23

package/src/components/preview/verdictMeta.ts

@@ -3,8 +3,8 @@
  * 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";
+import { tm } from "../../ui/tmTheme";
 
 export interface VerdictMeta {
   glyph: string;
@@ -15,25 +15,25 @@ export interface VerdictMeta {
 }
 
 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 },
+  added: { glyph: "+", color: tm.color.accent, label: "added", applies: true },
+  removed: { glyph: "−", color: tm.color.danger, label: "removed", applies: true },
+  changed: { glyph: "≈", color: tm.color.info, label: "changed", applies: true },
   "too-large": {
     glyph: "≈",
-    color: buoyColors.warning,
+    color: tm.color.warning,
     label: "changed (large)",
     applies: true,
   },
-  unchanged: { glyph: "=", color: buoyColors.textMuted, label: "unchanged", applies: false },
+  unchanged: { glyph: "=", color: tm.color.labelTertiary, label: "unchanged", applies: false },
   "wont-apply": {
     glyph: "⊘",
-    color: buoyColors.warning,
+    color: tm.color.warning,
     label: "won't apply",
     applies: false,
   },
   recomputes: {
     glyph: "↻",
-    color: buoyColors.textMuted,
+    color: tm.color.labelTertiary,
     label: "recomputes",
     applies: false,
   },

package/src/components/sources.ts

@@ -0,0 +1,92 @@
+/**
+ * What Time Machine can capture from, and how healthy each source is.
+ *
+ * On device these are live registry probes; on Buoy Desktop the same shapes
+ * arrive mirrored in the sync payload. Route is folded in as a source even
+ * though it is a device capability rather than a registered provider — from
+ * the user's side "can this snapshot take me back to that screen?" is the
+ * same question as "will my Redux store come back".
+ */
+import type { ComponentType } from "react";
+import {
+  JotaiIcon,
+  QueryIcon,
+  ReduxIcon,
+  RoutesIcon,
+  StorageIcon,
+  TimeMachineIcon,
+  ZustandIcon,
+} from "@buoy-gg/floating-tools-core";
+import { useSnapshotProviders, useTimeMachineState } from "../hooks/useTimeMachine";
+import { canNavigate } from "../store/routeRestore";
+
+export interface SourceStatus {
+  id: string;
+  label: string;
+  canCapture: boolean;
+  canRestore: boolean;
+  /** Why it is in this state — shown on the Sources screen. */
+  detail?: string;
+}
+
+/**
+ * Buoy icons paint their knock-out parts with `fill: "bg"`, defaulting to a
+ * near-black — so whatever surface an icon sits on has to be handed in as
+ * `bgColor` or those cut-outs read as black holes (storage's floppy slot and
+ * the route glyph are the two that use it).
+ */
+export type SourceIcon = ComponentType<{
+  size?: number;
+  color?: string;
+  bgColor?: string;
+}>;
+
+const ICONS: Record<string, SourceIcon> = {
+  storage: StorageIcon,
+  redux: ReduxIcon,
+  zustand: ZustandIcon,
+  jotai: JotaiIcon,
+  query: QueryIcon,
+  route: RoutesIcon,
+};
+
+export function sourceIcon(id: string): SourceIcon {
+  return ICONS[id] ?? TimeMachineIcon;
+}
+
+/** Id of the route tile — a device capability, not a snapshot provider. */
+export const ROUTE_SOURCE_ID = "route";
+
+export function useSourceStatuses(): SourceStatus[] {
+  const { remoteProviders, remoteRoute } = useTimeMachineState();
+  const localProviders = useSnapshotProviders();
+
+  const providers: SourceStatus[] =
+    remoteProviders ??
+    localProviders.map((p) => ({ id: p.id, label: p.label, ...p.status() }));
+
+  const routeAvailable = remoteProviders
+    ? remoteRoute?.available === true
+    : canNavigate();
+
+  return [
+    ...providers,
+    {
+      id: ROUTE_SOURCE_ID,
+      label: "Route",
+      canCapture: routeAvailable,
+      canRestore: routeAvailable,
+      // No live pathname here: these screens only re-render on store changes,
+      // so a route printed as status goes stale the moment you navigate with
+      // the tool still open. Each restore point shows the route it holds.
+      detail: routeAvailable
+        ? "Recorded with every snapshot — a restore can take you back"
+        : "No Expo Router detected — snapshots record no route",
+    },
+  ];
+}
+
+/** A source is "attached" when a snapshot would actually pick it up. */
+export function isAttached(source: SourceStatus): boolean {
+  return source.canCapture;
+}

package/src/store/snapshotVault.ts

@@ -42,14 +42,37 @@ export interface SnapshotMeta {
    * 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.
+   *
+   * Set through the MCP/adapter `setScope` action. The tool's own UI writes
+   * `excludedKeys` instead — see there for why the two exist.
    */
   scope?: string[];
+  /**
+   * Items the user switched OFF in the restore preview and saved: compound
+   * "sourceId::itemKey" strings that every later restore of this snapshot
+   * leaves untouched, including the one-tap RESTORE on the list.
+   *
+   * The inverse of `scope`, and the right default for "I unchecked one of
+   * these ten keys": naming what to SKIP lets everything else through, so a
+   * key that only starts differing tomorrow is still restored. An include
+   * list built from today's diff would silently freeze the restore point to
+   * whatever happened to differ when it was saved.
+   */
+  excludedKeys?: string[];
   /**
    * The route the app was on when this snapshot was captured. Absent when the
    * app has no expo-router (nothing to return to). A restore can navigate back
    * to it — see routeRestore.ts.
    */
   route?: SnapshotRoute;
+  /**
+   * Whether restoring this point should also navigate back to `route`.
+   * Undefined means "yes, if there is a route" — the useful default, and the
+   * reason there is no longer a prompt on every restore.
+   */
+  restoreRoute?: boolean;
+  /** When this point was last restored, for the "restored 4m ago" marker. */
+  lastRestoredAt?: number;
   /** Source ids captured, with their capture warnings. */
   sources: Record<string, SnapshotSourceMeta>;
 }
@@ -114,18 +137,17 @@ export async function deleteSnapshot(
   return next;
 }
 
-export async function setSnapshotScope(
+/**
+ * Rewrite one snapshot's metadata in BOTH places it lives — the index and the
+ * snapshot's own record — so a reload can't resurrect the old value from
+ * whichever one was missed.
+ */
+async function patchMeta(
   id: string,
-  scope: string[] | null,
+  patch: (meta: SnapshotMeta) => SnapshotMeta,
   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 apply = (m: SnapshotMeta): SnapshotMeta => (m.id === id ? patch(m) : m);
   const next = metas.map(apply);
   await persistentStorage.setItem(INDEX_KEY, JSON.stringify(next));
   const stored = await loadSnapshot(id);
@@ -136,6 +158,106 @@ export async function setSnapshotScope(
   return next;
 }
 
+/** Set (or clear with null/empty) the "only these items" restore scope. */
+export function setSnapshotScope(
+  id: string,
+  scope: string[] | null,
+  metas: SnapshotMeta[]
+): Promise<SnapshotMeta[]> {
+  return patchMeta(
+    id,
+    (m) => {
+      const next = { ...m };
+      if (scope && scope.length > 0) next.scope = scope;
+      else delete next.scope;
+      return next;
+    },
+    metas
+  );
+}
+
+/**
+ * Set (or clear with null/empty) the items a restore of this snapshot must
+ * leave alone. Saving exclusions also clears any legacy `scope`: the two
+ * answer the same question in opposite directions, and the one the user just
+ * chose in the preview wins.
+ */
+export function setSnapshotExclusions(
+  id: string,
+  excludedKeys: string[] | null,
+  metas: SnapshotMeta[]
+): Promise<SnapshotMeta[]> {
+  return patchMeta(
+    id,
+    (m) => {
+      const next = { ...m };
+      delete next.scope;
+      if (excludedKeys && excludedKeys.length > 0)
+        next.excludedKeys = excludedKeys;
+      else delete next.excludedKeys;
+      return next;
+    },
+    metas
+  );
+}
+
+/** Turn this point's route restore on or off — the row's route toggle. */
+export function setSnapshotRestoreRoute(
+  id: string,
+  restoreRoute: boolean,
+  metas: SnapshotMeta[]
+): Promise<SnapshotMeta[]> {
+  return patchMeta(id, (m) => ({ ...m, restoreRoute }), metas);
+}
+
+/** Stamp a restore so the list can say which point you are currently in. */
+export function markSnapshotRestored(
+  id: string,
+  at: number,
+  metas: SnapshotMeta[]
+): Promise<SnapshotMeta[]> {
+  return patchMeta(id, (m) => ({ ...m, lastRestoredAt: at }), metas);
+}
+
+/**
+ * Copy a stored snapshot under a new id and name. The payload is copied by
+ * reference into a fresh record — the vault serializes it on write, so the
+ * two never share mutable state.
+ */
+export async function duplicateSnapshot(
+  id: string,
+  name: string,
+  metas: SnapshotMeta[]
+): Promise<{ metas: SnapshotMeta[]; meta: SnapshotMeta } | null> {
+  const stored = await loadSnapshot(id);
+  if (!stored) return null;
+  const copy: StoredSnapshot = {
+    meta: {
+      ...stored.meta,
+      id: `${stored.meta.id}_copy_${Date.now().toString(36)}`,
+      name,
+      createdAt: Date.now(),
+      lastRestoredAt: undefined,
+    },
+    data: stored.data,
+  };
+  delete copy.meta.lastRestoredAt;
+  return { metas: await saveSnapshot(copy, metas), meta: copy.meta };
+}
+
+/** Read a whole record so a delete can be held in memory and undone. */
+export async function readSnapshot(id: string): Promise<StoredSnapshot | null> {
+  return loadSnapshot(id);
+}
+
+/** Put a held record back exactly as it was. */
+export async function restoreDeletedSnapshot(
+  stored: StoredSnapshot,
+  metas: SnapshotMeta[]
+): Promise<SnapshotMeta[]> {
+  return saveSnapshot(stored, metas);
+}
+
 export async function renameSnapshot(
   id: string,
   name: string,

package/src/store/timeMachineStore.ts

@@ -28,11 +28,17 @@ import {
 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";
@@ -62,6 +68,29 @@ export interface RestoreOutcome {
   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 {
   /**
@@ -118,6 +147,11 @@ export interface TimeMachineState {
    * (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. */
@@ -153,6 +187,7 @@ class TimeMachineStore {
     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. */
@@ -245,7 +280,7 @@ class TimeMachineStore {
       const snapshot: StoredSnapshot = {
         meta: {
           id: nextId(),
-          name: name.trim() || "Untitled snapshot",
+          name: name.trim() || defaultSnapshotName(route),
           createdAt: Date.now(),
           sizeBytes: 0,
           ...(route ? { route } : {}),
@@ -362,7 +397,11 @@ class TimeMachineStore {
         return bySource;
       };
 
-      const excludeBySource = splitCompound(excludeKeys ?? []);
+      // 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.
@@ -371,7 +410,11 @@ class TimeMachineStore {
           ? splitCompound(stored.meta.scope)
           : null;
 
-      const wantsRoute = options?.restoreRoute === true && !!stored.meta.route;
+      // 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.
@@ -398,7 +441,11 @@ class TimeMachineStore {
           }
         }
         outcome.willReload = this.scheduleReload("buoy time-machine restore");
-        this.setState({ lastOutcome: outcome });
+        // 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;
       }
 
@@ -416,7 +463,10 @@ class TimeMachineStore {
       if (wantsRoute) {
         outcome.route = navigateToRoute(stored.meta.route!);
       }
-      this.setState({ lastOutcome: outcome });
+      this.setState({
+        lastOutcome: outcome,
+        snapshots: await markSnapshotRestored(id, outcome.at, this.state.snapshots),
+      });
       return outcome;
     } finally {
       this.setState({ busy: null });
@@ -461,16 +511,78 @@ class TimeMachineStore {
     }
   }
 
+  /**
+   * 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 });
@@ -496,6 +608,25 @@ class TimeMachineStore {
     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 });
   }

package/src/sync/timeMachineSyncAdapter.ts

@@ -138,6 +138,36 @@ export const timeMachineSyncAdapter = {
       return { renamed: true, id, name };
     },
 
+    /**
+     * Save (or clear with null/empty) the items a restore of this snapshot
+     * must leave alone — the persisted form of the preview's checkboxes.
+     */
+    setExclusions: async (params: unknown) => {
+      const { id, excludedKeys } =
+        (params as { id?: string; excludedKeys?: string[] | null }) ?? {};
+      if (!id) throw new Error("setExclusions requires `id`");
+      await timeMachineStore.setExclusions(id, excludedKeys ?? null);
+      return { id, excluded: excludedKeys?.length ?? 0 };
+    },
+
+    /** Turn a restore point's route restore on or off. */
+    setRestoreRoute: async (params: unknown) => {
+      const { id, restoreRoute } =
+        (params as { id?: string; restoreRoute?: boolean }) ?? {};
+      if (!id) throw new Error("setRestoreRoute requires `id`");
+      await timeMachineStore.setRestoreRoute(id, restoreRoute !== false);
+      return { id, restoreRoute: restoreRoute !== false };
+    },
+
+    /** Copy a restore point so a variation can start from a known base. */
+    duplicate: async (params: unknown) => {
+      const { id } = (params as { id?: string }) ?? {};
+      if (!id) throw new Error("duplicate requires `id`");
+      const snapshot = await timeMachineStore.duplicate(id);
+      if (!snapshot) throw new Error(`No snapshot with id "${id}"`);
+      return { snapshot };
+    },
+
     /** Save (or clear with null/empty) a snapshot's targeted-restore scope. */
     setScope: async (params: unknown) => {
       const { id, scope } =