@buoy-gg/time-machine 7.0.20 → 7.0.22

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:";
@@ -43,6 +44,12 @@ export interface SnapshotMeta {
    * means just my cart". Absent = full restore.
    */
   scope?: 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;
   /** Source ids captured, with their capture warnings. */
   sources: Record<string, SnapshotSourceMeta>;
 }

package/src/store/timeMachineStore.ts

@@ -36,6 +36,12 @@ import {
   type SnapshotMeta,
   type StoredSnapshot,
 } from "./snapshotVault";
+import {
+  captureCurrentRoute,
+  navigateToRoute,
+  savePendingRoute,
+  type RouteRestoreResult,
+} from "./routeRestore";
 
 export const RESTORE_ORDER = ["storage", "redux", "zustand", "jotai", "query"];
 
@@ -49,6 +55,21 @@ export interface RestoreOutcome {
   /** 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;
+}
+
+/** 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. */
@@ -92,6 +113,18 @@ export interface TimeMachineState {
    * 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;
+}
+
+/** 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 = (
@@ -119,6 +152,7 @@ class TimeMachineStore {
     lastOutcome: null,
     preview: null,
     remoteProviders: null,
+    remoteRoute: null,
   };
   /** Monotonic token — a preview build checks it after every await and
    * abandons itself when a newer build (or clearPreview) supersedes it. */
@@ -166,12 +200,14 @@ class TimeMachineStore {
     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,
     });
   }
@@ -204,12 +240,15 @@ class TimeMachineStore {
           };
         }
       }
+      // 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() || "Untitled snapshot",
           createdAt: Date.now(),
           sizeBytes: 0,
+          ...(route ? { route } : {}),
           sources,
         },
         data,
@@ -259,13 +298,15 @@ class TimeMachineStore {
   async restore(
     id: string,
     mode: RestoreMode,
-    excludeKeys?: readonly string[]
+    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;
@@ -330,6 +371,8 @@ class TimeMachineStore {
           ? splitCompound(stored.meta.scope)
           : null;
 
+      const wantsRoute = options?.restoreRoute === true && !!stored.meta.route;
+
       if (mode === "reload") {
         // Storage only; everything in-memory rebuilds after the reload.
         if (
@@ -343,6 +386,17 @@ class TimeMachineStore {
             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");
         this.setState({ lastOutcome: outcome });
         return outcome;
@@ -358,6 +412,10 @@ class TimeMachineStore {
           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 });
       return outcome;
     } finally {
@@ -686,6 +744,7 @@ export function replaceTimeMachineFromSnapshot(payload: {
   busy?: TimeMachineState["busy"];
   lastOutcome?: RestoreOutcome | null;
   providers?: RemoteProviderStatus[];
+  route?: RouteToolStatus;
 }): void {
   timeMachineStore.replaceFromSnapshot(payload);
 }

package/src/sync/timeMachineSyncAdapter.ts

@@ -23,6 +23,7 @@ import {
   type RestoreMode,
 } from "../store/timeMachineStore";
 import { loadSnapshot } from "../store/snapshotVault";
+import { canNavigate, currentRoute } from "../store/routeRestore";
 
 interface CaptureParams {
   name?: string;
@@ -33,6 +34,8 @@ interface RestoreParams {
   mode?: RestoreMode;
   /** Compound "sourceId::itemKey" strings — items the caller opted out of. */
   excludeKeys?: string[];
+  /** Also navigate back to the route the snapshot was captured on. */
+  restoreRoute?: boolean;
 }
 interface IdParams {
   id: string;
@@ -61,11 +64,24 @@ function providerStatuses() {
 
 function metadata() {
   const { snapshots, busy, lastOutcome } = timeMachineStore.getState();
-  return { snapshots, busy, lastOutcome, providers: providerStatuses() };
+  const current = currentRoute();
+  return {
+    snapshots,
+    busy,
+    lastOutcome,
+    providers: providerStatuses(),
+    // Route capture/restore is a device capability, not a snapshot provider —
+    // a dashboard has no router of its own to probe, so it's mirrored here.
+    route: {
+      available: canNavigate(),
+      ...(current ? { current: current.href } : {}),
+    },
+  };
 }
 
 export const timeMachineSyncAdapter = {
-  version: 1,
+  // v2 adds `route` (device route capability) and `snapshots[].route`.
+  version: 2,
   getSnapshot: () => metadata(),
   subscribe: (onChange: () => void) => {
     const unsubStore = timeMachineStore.subscribe(onChange);
@@ -96,9 +112,16 @@ export const timeMachineSyncAdapter = {
      * persisted storage then reloads the JS bundle (always the path for
      * baseline snapshots). */
     restore: async (params: unknown) => {
-      const { id, mode = "live", excludeKeys } = (params as RestoreParams) ?? {};
+      const {
+        id,
+        mode = "live",
+        excludeKeys,
+        restoreRoute,
+      } = (params as RestoreParams) ?? {};
       if (!id) throw new Error("restore requires a snapshot `id`");
-      return await timeMachineStore.restore(id, mode, excludeKeys);
+      return await timeMachineStore.restore(id, mode, excludeKeys, {
+        restoreRoute,
+      });
     },
 
     delete: async (params: unknown) => {