@buoy-gg/time-machine 7.0.28 → 7.0.30

package/src/components/preview/verdictMeta.ts

@@ -1,40 +0,0 @@
-/**
- * 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 type { StateSnapshotPreviewVerdict } from "@buoy-gg/shared-ui";
-import { tm } from "../../ui/tmTheme";
-
-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: 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: tm.color.warning,
-    label: "changed (large)",
-    applies: true,
-  },
-  unchanged: { glyph: "=", color: tm.color.labelTertiary, label: "unchanged", applies: false },
-  "wont-apply": {
-    glyph: "⊘",
-    color: tm.color.warning,
-    label: "won't apply",
-    applies: false,
-  },
-  recomputes: {
-    glyph: "↻",
-    color: tm.color.labelTertiary,
-    label: "recomputes",
-    applies: false,
-  },
-};

package/src/components/sources.ts

@@ -1,92 +0,0 @@
-/**
- * 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/hooks/useTimeMachine.ts

@@ -1,26 +0,0 @@
-import { useEffect, useState, useSyncExternalStore } from "react";
-import {
-  getStateSnapshotProviders,
-  subscribeToStateSnapshotProviders,
-  type StateSnapshotProvider,
-} from "@buoy-gg/shared-ui";
-import { timeMachineStore } from "../store/timeMachineStore";
-import type { TimeMachineState } from "../store/timeMachineStore";
-
-export function useTimeMachineState(): TimeMachineState {
-  return useSyncExternalStore(timeMachineStore.subscribe, () =>
-    timeMachineStore.getState()
-  );
-}
-
-/** Registered snapshot providers (query registers late, hence the subscribe). */
-export function useSnapshotProviders(): StateSnapshotProvider[] {
-  const [providers, setProviders] = useState(getStateSnapshotProviders);
-  useEffect(() => {
-    setProviders(getStateSnapshotProviders());
-    return subscribeToStateSnapshotProviders(() =>
-      setProviders(getStateSnapshotProviders())
-    );
-  }, []);
-  return providers;
-}

package/src/index.tsx

@@ -1,68 +0,0 @@
-/**
- * @buoy-gg/time-machine
- *
- * Time Machine — snapshot & restore app state for React Native DevTools.
- *
- * Capture the complete client-side state of the app (storage, Redux,
- * Zustand, Jotai, React Query) as a named snapshot; restore any snapshot in
- * one tap to iterate on multi-step test flows without rebuilding state.
- *
- * 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";
-
-// Components
-export {
-  TimeMachineModal,
-  TimeMachineToolView,
-  type TimeMachineModalProps,
-} from "./components/TimeMachineModal";
-
-// External-sync adapter (auto-registered by @buoy-gg/core)
-export { timeMachineSyncAdapter } from "./sync/timeMachineSyncAdapter";
-
-// Programmatic snapshot control (also used by tests / power users)
-export {
-  timeMachineStore,
-  RESTORE_ORDER,
-  type RestoreMode,
-  type RestoreOptions,
-  type RestoreOutcome,
-  type TimeMachineState,
-  type RemoteProviderStatus,
-  type PreviewSource,
-} 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,
-  replaceTimeMachineFromSnapshot,
-} from "./store/timeMachineStore";
-export type {
-  SnapshotMeta,
-  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/preset.tsx

@@ -1,47 +0,0 @@
-/**
- * Pre-configured Time Machine tool for FloatingDevTools.
- *
- * @example
- * ```tsx
- * import { timeMachineToolPreset } from '@buoy-gg/time-machine';
- *
- * <FloatingDevTools apps={[timeMachineToolPreset]} />
- * ```
- */
-
-import {
-  TimeMachineIcon,
-  TIME_MACHINE_ICON_COLOR,
-} from "@buoy-gg/shared-ui";
-import { TimeMachineBody } from "./components/TimeMachineBody";
-import { HeaderReloadButton } from "./components/HeaderReloadButton";
-
-export const timeMachineToolPreset = {
-  id: "time-machine",
-  name: "TIME MACHINE",
-  description: "Snapshot & restore app state (storage, stores, query cache)",
-  slot: "both" as const,
-  icon: ({ size, color }: { size: number; color?: string }) => (
-    <TimeMachineIcon size={size} color={color || TIME_MACHINE_ICON_COLOR} />
-  ),
-  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. */
-export function createTimeMachineTool(
-  options: { name?: string; description?: string } = {}
-) {
-  return {
-    ...timeMachineToolPreset,
-    name: options.name ?? timeMachineToolPreset.name,
-    description: options.description ?? timeMachineToolPreset.description,
-  };
-}

package/src/store/routeRestore.ts

@@ -1,194 +0,0 @@
-/**
- * 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;
-}