@buoy-gg/time-machine 7.0.21 → 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/index.tsx

@@ -10,6 +10,8 @@
  * PUBLIC API - Only these exports are supported for external use.
  */
 
+import { armPendingRouteRestore as armPendingRouteRestoreOnLoad } from "./store/routeRestore";
+
 // Tool preset for FloatingDevTools
 export { timeMachineToolPreset, createTimeMachineTool } from "./preset";
 
@@ -28,11 +30,23 @@ export {
   timeMachineStore,
   RESTORE_ORDER,
   type RestoreMode,
+  type RestoreOptions,
   type RestoreOutcome,
   type TimeMachineState,
   type RemoteProviderStatus,
 } from "./store/timeMachineStore";
 
+// Route capture / restore ("also take me back to the screen I was on")
+export {
+  armPendingRouteRestore,
+  captureCurrentRoute,
+  navigateToRoute,
+  canNavigate as canRestoreRoute,
+  type SnapshotRoute,
+  type RouteRestoreResult,
+  type RouteRestoreStatus,
+} from "./store/routeRestore";
+
 // Buoy Desktop remote-mirror seam
 export {
   setRemoteTimeMachineHandler,
@@ -43,3 +57,11 @@ export type {
   SnapshotSourceMeta,
   StoredSnapshot,
 } from "./store/snapshotVault";
+
+// A reload-mode restore that also restores the route can't navigate itself —
+// the JS realm dies with the reload. It parks the route in storage; this picks
+// it up on the next boot. Core requires this module while mounting the
+// floating menu, which is the earliest point we're guaranteed to run.
+// Idempotent: repeated imports (or a host calling it explicitly) arm once.
+armPendingRouteRestoreOnLoad();
+

package/src/store/routeRestore.ts

@@ -0,0 +1,194 @@
+/**
+ * Route capture & restore for Time Machine.
+ *
+ * A restore point is only half the story: state without the screen you were
+ * on drops you into the right data on the wrong page. Every snapshot records
+ * the route it was captured on, and a restore can navigate back to it.
+ *
+ * Two navigation paths, because a "reload" restore kills the JS realm:
+ * - LIVE restore: navigate immediately once the sources are applied.
+ * - RELOAD restore: persist the route BEFORE the reload is scheduled, then
+ *   {@link armPendingRouteRestore} picks it up on the next boot, waits for the
+ *   router to come online, and navigates.
+ *
+ * Everything here is best-effort: apps without expo-router capture no route,
+ * so the UI simply never offers the option.
+ */
+import {
+  getSafeCurrentRoute,
+  getSafeRouter,
+  persistentStorage,
+  type SafeRouteLocation,
+} from "@buoy-gg/shared-ui";
+
+/**
+ * The route a snapshot was captured on. Only the URL is stored — imperative
+ * params passed as objects (`navigate(path, { user })`) are not part of a
+ * route and are not restored.
+ */
+export interface SnapshotRoute {
+  /** Pathname with dynamic segments resolved, e.g. `/pokemon/25`. */
+  pathname: string;
+  /** What we navigate to — pathname plus search params. */
+  href: string;
+}
+
+/** How a restore's route leg ended, reported back in the RestoreOutcome. */
+export type RouteRestoreStatus =
+  | "navigated"
+  | "deferred"
+  | "failed"
+  | "unavailable";
+
+export interface RouteRestoreResult {
+  pathname: string;
+  href: string;
+  status: RouteRestoreStatus;
+  /** Present when status is "failed" / "unavailable". */
+  error?: string;
+}
+
+/**
+ * Same `@react_buoy` family as the snapshot vault, so every tool's
+ * isDevToolsStorageKey filter (and therefore every wipe/restore) leaves it
+ * alone — a pending route must survive the storage restore that precedes the
+ * reload it's waiting on.
+ */
+const PENDING_KEY = "@react_buoy_time_machine:pending-route";
+
+/**
+ * A pending route older than this belongs to a reload that never happened
+ * (the app was killed, the user moved on). Boot-time navigation into a screen
+ * someone left minutes ago is worse than doing nothing.
+ */
+export const PENDING_ROUTE_TTL_MS = 60_000;
+
+/** How long to wait at boot for the router to come online. */
+const ROUTER_READY_TIMEOUT_MS = 8_000;
+
+/** Settle window after the router appears, so the initial route mounts first. */
+const ROUTER_SETTLE_MS = 250;
+
+interface PendingRoute extends SnapshotRoute {
+  savedAt: number;
+  snapshotName?: string;
+}
+
+function toSnapshotRoute(location: SafeRouteLocation): SnapshotRoute {
+  return { pathname: location.pathname, href: location.href };
+}
+
+/** The route to stamp on a snapshot being captured, or null when unavailable. */
+export function captureCurrentRoute(): SnapshotRoute | null {
+  const current = getSafeCurrentRoute();
+  return current ? toSnapshotRoute(current) : null;
+}
+
+/** The live route, for "you're already here" checks in the UI. */
+export function currentRoute(): SnapshotRoute | null {
+  return captureCurrentRoute();
+}
+
+/** True when imperative navigation is possible on this device. */
+export function canNavigate(): boolean {
+  return getSafeRouter() != null;
+}
+
+/**
+ * Navigate to a captured route now. Uses `navigate` (not `push`) so restoring
+ * the same route twice doesn't stack duplicate screens.
+ */
+export function navigateToRoute(route: SnapshotRoute): RouteRestoreResult {
+  const base = { pathname: route.pathname, href: route.href };
+  const router = getSafeRouter();
+  if (!router?.navigate) {
+    return {
+      ...base,
+      status: "unavailable",
+      error: "expo-router is not available on this device",
+    };
+  }
+  try {
+    router.navigate(route.href);
+    return { ...base, status: "navigated" };
+  } catch (e) {
+    return { ...base, status: "failed", error: String(e) };
+  }
+}
+
+// ── Pending route (survives the reload) ──────────────────────────────────────
+
+export async function savePendingRoute(
+  route: SnapshotRoute,
+  snapshotName?: string
+): Promise<void> {
+  const pending: PendingRoute = {
+    ...route,
+    savedAt: Date.now(),
+    ...(snapshotName ? { snapshotName } : {}),
+  };
+  await persistentStorage.setItem(PENDING_KEY, JSON.stringify(pending));
+}
+
+export async function clearPendingRoute(): Promise<void> {
+  try {
+    await persistentStorage.removeItem(PENDING_KEY);
+  } catch {
+    // best-effort — a stale key is dropped by the TTL check anyway
+  }
+}
+
+async function loadPendingRoute(): Promise<PendingRoute | null> {
+  try {
+    const raw = await persistentStorage.getItem(PENDING_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as Partial<PendingRoute>;
+    if (typeof parsed?.href !== "string" || !parsed.href) return null;
+    if (typeof parsed.savedAt !== "number") return null;
+    return {
+      pathname:
+        typeof parsed.pathname === "string" ? parsed.pathname : parsed.href,
+      href: parsed.href,
+      savedAt: parsed.savedAt,
+      snapshotName:
+        typeof parsed.snapshotName === "string" ? parsed.snapshotName : undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
+let armed = false;
+
+/**
+ * Boot-time consumer of a pending route: called once when the package loads
+ * (core requires it while mounting the floating menu), it navigates to the
+ * route a reload-mode restore asked for and clears the slot.
+ *
+ * Idempotent and self-limiting — the slot is cleared before navigating, so a
+ * route that crashes the app on arrival can't put it in a boot loop.
+ */
+export function armPendingRouteRestore(): void {
+  if (armed) return;
+  armed = true;
+  void (async () => {
+    const pending = await loadPendingRoute();
+    if (!pending) return;
+    // Clear FIRST: whatever happens next, this route is spent.
+    await clearPendingRoute();
+    if (Date.now() - pending.savedAt > PENDING_ROUTE_TTL_MS) return;
+
+    const deadline = Date.now() + ROUTER_READY_TIMEOUT_MS;
+    while (!canNavigate() && Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 100));
+    }
+    if (!canNavigate()) return;
+    await new Promise((r) => setTimeout(r, ROUTER_SETTLE_MS));
+    navigateToRoute({ pathname: pending.pathname, href: pending.href });
+  })();
+}
+
+/** @internal test seam — re-arms the boot-time consumer. */
+export function resetPendingRouteArm(): void {
+  armed = false;
+}

package/src/store/snapshotVault.ts

@@ -18,6 +18,7 @@ import {
   persistentStorage,
   type SuperJSONResult,
 } from "@buoy-gg/shared-ui";
+import type { SnapshotRoute } from "./routeRestore";
 
 const INDEX_KEY = "@react_buoy_time_machine:index";
 const SNAP_PREFIX = "@react_buoy_time_machine:snap:";
@@ -41,8 +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>;
 }
@@ -107,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);
@@ -129,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,