@buoy-gg/zustand 7.0.16 → 7.0.18

package/lib/commonjs/zustand/utils/zustandStateStore.js

@@ -276,6 +276,27 @@ class ZustandStateStore {
 
   // ---- Remote Mirror Mode ----
 
+  /**
+   * Replace the change log without touching the store registry. Used when a
+   * host keeps real registered stores (JUMP / RESET stay wired) but needs to
+   * reseed the event list — the docs live tour, or any mirror that already
+   * called `registerStore`. Does not fire `onClear`. Respects the enabled
+   * flag so the UI's pause button freezes the reseed.
+   */
+  replaceStateChanges(changes) {
+    if (!this.isEnabled) return;
+    this.stateChanges = changes.slice(0, this.maxChanges);
+    for (const store of this.stores.values()) {
+      store.stateChangeCount = 0;
+    }
+    for (const change of this.stateChanges) {
+      const store = this.stores.get(change.storeName);
+      if (store) store.stateChangeCount++;
+    }
+    this.notifyListeners();
+    this.notifyStoreListeners();
+  }
+
   /**
    * Permanently suppress local capture. Use when this store acts as a mirror
    * of a remote device's state changes (e.g. the desktop dashboard): data
@@ -330,22 +351,92 @@ class ZustandStateStore {
    */
   replaceFromSnapshot(changes, storeSnapshots) {
     if (!this.isEnabled) return;
-    this.stateChanges = changes.slice(0, this.maxChanges);
-    this.stores = new Map(storeSnapshots.map(snapshot => [snapshot.name, {
-      name: snapshot.name,
-      api: {
-        getState: () => snapshot.currentState,
-        setState: (partial, replace) => {
-          this.remoteSetStateHandler?.(snapshot.name, partial, replace);
+
+    // Preserve trees a remote mirror already hydrated — wire-form snapshots
+    // always carry markers, and a later snapshot must not blank the detail pane.
+    const hydrated = new Map();
+    for (const existing of this.stateChanges) {
+      const prev = existing.prevState;
+      if (!prev || prev.__buoyStateOnDevice !== true) {
+        hydrated.set(existing.id, existing);
+      }
+    }
+    this.stateChanges = changes.slice(0, this.maxChanges).map(change => {
+      const kept = hydrated.get(change.id);
+      const incoming = change.prevState;
+      return kept && incoming?.__buoyStateOnDevice === true ? {
+        ...change,
+        prevState: kept.prevState,
+        nextState: kept.nextState,
+        partial: kept.partial
+      } : change;
+    });
+
+    // Preserve currentState a remote mirror already hydrated — oversized
+    // stores arrive as STATE_ON_DEVICE markers on every snapshot.
+    const hydratedStores = new Map();
+    for (const [name, store] of this.stores) {
+      try {
+        const state = store.api.getState();
+        const marker = state;
+        if (!marker || marker.__buoyStateOnDevice !== true) {
+          hydratedStores.set(name, state);
+        }
+      } catch {
+        // ignore
+      }
+    }
+    this.stores = new Map(storeSnapshots.map(snapshot => {
+      const incoming = snapshot.currentState;
+      const kept = hydratedStores.get(snapshot.name);
+      const currentState = kept !== undefined && incoming?.__buoyStateOnDevice === true ? kept : snapshot.currentState;
+      return [snapshot.name, {
+        name: snapshot.name,
+        api: {
+          getState: () => currentState,
+          setState: (partial, replace) => {
+            this.remoteSetStateHandler?.(snapshot.name, partial, replace);
+          },
+          subscribe: () => () => {}
         },
-        subscribe: () => () => {}
-      },
-      stateChangeCount: snapshot.stateChangeCount,
-      isPersisted: snapshot.isPersisted,
-      persistName: snapshot.persistName,
-      color: snapshot.color
-    }]));
+        stateChangeCount: snapshot.stateChangeCount,
+        isPersisted: snapshot.isPersisted,
+        persistName: snapshot.persistName,
+        color: snapshot.color
+      }];
+    }));
+    this.notifyListeners();
+    this.notifyStoreListeners();
+  }
+
+  /**
+   * Hydrate one mirrored change with real trees fetched on demand from the
+   * device via the adapter's `getChangeDetail`. Remote-mirror (desktop) only.
+   */
+  hydrateChange(id, patch) {
+    const index = this.stateChanges.findIndex(c => c.id === id);
+    if (index === -1) return;
+    this.stateChanges = [...this.stateChanges.slice(0, index), {
+      ...this.stateChanges[index],
+      ...patch
+    }, ...this.stateChanges.slice(index + 1)];
     this.notifyListeners();
+  }
+
+  /**
+   * Hydrate one mirrored store's currentState fetched on demand from the
+   * device via the adapter's `getStoreState`. Remote-mirror (desktop) only.
+   */
+  hydrateStoreState(storeName, currentState) {
+    const store = this.stores.get(storeName);
+    if (!store) return;
+    this.stores.set(storeName, {
+      ...store,
+      api: {
+        ...store.api,
+        getState: () => currentState
+      }
+    });
     this.notifyStoreListeners();
   }
 

package/lib/module/index.js

@@ -37,6 +37,9 @@
  * ```
  */
 
+// Side-effect: registers the Time Machine snapshot provider
+import "./zustand/utils/snapshotProvider";
+
 // =============================================================================
 // PRESET (Primary entry point for FloatingDevTools)
 // =============================================================================

package/lib/module/zustand/components/ZustandModal.js

@@ -8,7 +8,7 @@
  * - Events tab: Live state change monitoring with diffs
  */
 
-import { useState, useMemo, useRef, useCallback } from "react";
+import { useState, useMemo, useRef, useCallback, useEffect } from "react";
 import { View, Text, StyleSheet, FlatList, TextInput, TouchableOpacity } from "react-native";
 import { JsModal, ModalHeader, TabSelector, macOSColors, buoyColors, Search, Filter, Power, X, Lock, Box, devToolsStorageKeys, ProUpgradeModal, PowerToggleButton, ToolbarCopyButton, ToolbarClearButton, truncatePayload, TickProvider } from "@buoy-gg/shared-ui";
 import { useIsPro } from "@buoy-gg/license";
@@ -44,11 +44,16 @@ export function ZustandModal({
   onMinimize,
   enableSharedModalDimensions = false,
   inline = false,
-  storesLoading = false
+  storesLoading = false,
+  initialTab = "stores",
+  initialSelectedChangeId,
+  initialDetailView,
+  onChangeSelect,
+  onStoreExpand
 }) {
   const isPro = useIsPro();
   const [showProModal, setShowProModal] = useState(false);
-  const [activeTab, setActiveTab] = useState("stores");
+  const [activeTab, setActiveTab] = useState(initialTab);
   const [selectedHistoryStore, setSelectedHistoryStore] = useState(null);
   const [showFilters, setShowFilters] = useState(false);
   const [ignoredPatterns, setIgnoredPatterns] = useState(new Set());
@@ -103,6 +108,30 @@ export function ZustandModal({
   }, [selectedChangeId, activeChanges]);
   const selectedChange = selectedChangeIndex !== null ? activeChanges[selectedChangeIndex] : null;
 
+  // Notify the host on selection (keyed by change id so re-renders with the
+  // same selection don't re-fire; remote mirrors fetch state trees here).
+  const lastNotifiedSelectionRef = useRef(null);
+  useEffect(() => {
+    if (!onChangeSelect) return;
+    const id = selectedChange?.id ?? null;
+    if (id === null || id === lastNotifiedSelectionRef.current) return;
+    lastNotifiedSelectionRef.current = id;
+    onChangeSelect(selectedChange);
+  }, [selectedChange, onChangeSelect]);
+
+  // Deep link into a change's detail (see initialSelectedChangeId). Applied
+  // at most once per id, so the list re-rendering — or the user pressing Back
+  // — never re-opens it.
+  const appliedInitialSelectionRef = useRef(null);
+  useEffect(() => {
+    if (!initialSelectedChangeId) return;
+    if (appliedInitialSelectionRef.current === initialSelectedChangeId) return;
+    const exists = activeChanges.some(c => c.id === initialSelectedChangeId);
+    if (!exists) return;
+    appliedInitialSelectionRef.current = initialSelectedChangeId;
+    setSelectedChangeId(initialSelectedChangeId);
+  }, [initialSelectedChangeId, activeChanges]);
+
   // Search state — shared across tabs
   const [searchText, setSearchText] = useState("");
   const [isSearchActive, setIsSearchActive] = useState(false);
@@ -365,7 +394,8 @@ export function ZustandModal({
         changes: activeChanges,
         selectedIndex: selectedChangeIndex,
         onIndexChange: handleIndexChange,
-        disableInternalFooter: true
+        disableInternalFooter: true,
+        initialView: initialDetailView
       });
     }
 
@@ -403,7 +433,8 @@ export function ZustandModal({
         stores: displayedStores,
         searchQuery: searchText,
         onViewHistory: handleViewHistory,
-        isLoading: storesLoading
+        isLoading: storesLoading,
+        onStoreExpand: onStoreExpand
       });
     }
 

package/lib/module/zustand/components/ZustandStateDetailContent.js

@@ -62,9 +62,10 @@ export function ZustandStateDetailContent({
   changes,
   selectedIndex,
   onIndexChange,
-  disableInternalFooter = false
+  disableInternalFooter = false,
+  initialView = "change"
 }) {
-  const [activeView, setActiveView] = useState("change");
+  const [activeView, setActiveView] = useState(initialView);
   const [diffMode, setDiffMode] = useState("tree");
   const totalChanges = changes.length;
   const changeColor = getChangeColor(change);

package/lib/module/zustand/components/ZustandStoreBrowser.js

@@ -22,6 +22,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 function getKeysPreview(store) {
   try {
     const state = store.api.getState();
+    if (state && typeof state === "object" && state.__buoyStateOnDevice === true) {
+      return "on device";
+    }
     if (state && typeof state === "object") {
       const keys = Object.keys(state);
       const dataKeys = keys.filter(k => {
@@ -142,7 +145,8 @@ export function ZustandStoreBrowser({
   stores,
   searchQuery,
   onViewHistory,
-  isLoading = false
+  isLoading = false,
+  onStoreExpand
 }) {
   const [expandedStore, setExpandedStore] = useState(null);
 
@@ -153,8 +157,12 @@ export function ZustandStoreBrowser({
     return stores.filter(s => s.name.toLowerCase().includes(search) || s.persistName && s.persistName.toLowerCase().includes(search));
   }, [stores, searchQuery]);
   const handleStorePress = useCallback(store => {
-    setExpandedStore(prev => prev === store.name ? null : store.name);
-  }, []);
+    setExpandedStore(prev => {
+      const next = prev === store.name ? null : store.name;
+      if (next) onStoreExpand?.(store.name);
+      return next;
+    });
+  }, [onStoreExpand]);
   if (filteredStores.length === 0 && !searchQuery) {
     return isLoading ? /*#__PURE__*/_jsx(LoadingBrowserState, {}) : /*#__PURE__*/_jsx(EmptyBrowserState, {});
   }

package/lib/module/zustand/sync/zustandSyncAdapter.js

@@ -1,10 +1,82 @@
 "use strict";
 
 import { zustandStateStore } from "../utils/zustandStateStore";
+/**
+ * Sentinel used in WIRE-FORM snapshots in place of raw prevState/nextState.
+ * Same hazard as redux: up to 200 changes × 2 full trees on every snapshot
+ * freeze/OOM-killed large apps. Dashboards fetch trees via `getChangeDetail`.
+ */
+export const STATE_ON_DEVICE = Object.freeze({
+  __buoyStateOnDevice: true,
+  note: "State trees stay on the device — fetched on demand via getChangeDetail / getStoreState."
+});
+
+/** Wire-form sentinel for an oversized `partial` (replace can carry a whole tree). */
+export const PAYLOAD_ON_DEVICE = Object.freeze({
+  __buoyPayloadOnDevice: true,
+  note: "Partial stays on the device — fetched on demand via getChangeDetail."
+});
+const MAX_CHANGE_DETAIL_BYTES = 8 * 1024 * 1024;
+const MAX_WIRE_PAYLOAD_BYTES = 16 * 1024;
+function jsonLongerThan(value, limit) {
+  let bytes = 0;
+  const stack = [value];
+  const seen = new Set();
+  while (stack.length > 0) {
+    if (bytes > limit) return true;
+    const v = stack.pop();
+    if (v === null || v === undefined) bytes += 4;else if (typeof v === "string") bytes += v.length + 2;else if (typeof v === "number") bytes += 8;else if (typeof v === "boolean") bytes += 5;else if (typeof v === "object") {
+      if (seen.has(v)) continue;
+      seen.add(v);
+      if (Array.isArray(v)) {
+        bytes += 2 + v.length;
+        for (let i = 0; i < v.length; i++) stack.push(v[i]);
+      } else {
+        bytes += 2;
+        for (const k in v) {
+          bytes += k.length + 4;
+          stack.push(v[k]);
+        }
+      }
+    } else bytes += 4;
+  }
+  return bytes > limit;
+}
 /** Top-level keys of an object state, for the compact (no-values) view. */
 function topLevelKeys(state) {
   return state && typeof state === "object" && !Array.isArray(state) ? Object.keys(state) : undefined;
 }
+function toWireChange(change) {
+  return {
+    ...change,
+    prevState: STATE_ON_DEVICE,
+    nextState: STATE_ON_DEVICE,
+    partial: toWirePartial(change.partial)
+  };
+}
+function toWirePartial(value) {
+  if (value === undefined) return value;
+  try {
+    JSON.stringify(value);
+  } catch {
+    return PAYLOAD_ON_DEVICE;
+  }
+  if (jsonLongerThan(value, MAX_WIRE_PAYLOAD_BYTES)) {
+    return PAYLOAD_ON_DEVICE;
+  }
+  return value;
+}
+function toWireState(value) {
+  try {
+    JSON.stringify(value);
+  } catch {
+    return STATE_ON_DEVICE;
+  }
+  if (jsonLongerThan(value, MAX_WIRE_PAYLOAD_BYTES)) {
+    return STATE_ON_DEVICE;
+  }
+  return value;
+}
 
 /**
  * Sync adapter for the zustand tool, consumed by @buoy-gg/external-sync's
@@ -17,13 +89,21 @@ function topLevelKeys(state) {
  * change timeline and the store registry (with each store's current state)
  * so the dashboard can render the store browser.
  *
+ * v2: change-log prevState/nextState are replaced with on-device markers
+ * (see STATE_ON_DEVICE). Dashboards fetch trees via `getChangeDetail`.
+ * Oversized / unserializable `stores[].currentState` uses the same marker
+ * and is fetched via `getStoreState`.
+ *
  * The `setState` action powers remote time-travel/reset from the dashboard.
  */
 export const zustandSyncAdapter = {
-  version: 1,
+  version: 2,
   getSnapshot: () => ({
-    changes: zustandStateStore.getStateChanges(),
-    stores: zustandStateStore.getStoreSnapshots()
+    changes: zustandStateStore.getStateChanges().map(toWireChange),
+    stores: zustandStateStore.getStoreSnapshots().map(store => ({
+      ...store,
+      currentState: toWireState(store.currentState)
+    }))
   }),
   subscribe: onChange => {
     const unsubscribeChanges = zustandStateStore.subscribe(onChange);
@@ -37,6 +117,86 @@ export const zustandSyncAdapter = {
     clearEvents: () => {
       zustandStateStore.clearStateChanges();
     },
+    /**
+     * On-demand detail: one change's real prevState/nextState/partial.
+     * The per-snapshot stream stays tree-free; this is the explicit,
+     * size-guarded channel for the detail pane.
+     */
+    getChangeDetail: params => {
+      const {
+        id
+      } = params ?? {};
+      if (!id) return {
+        found: false,
+        reason: "missing id"
+      };
+      const change = zustandStateStore.getStateChangeById(id);
+      if (!change) return {
+        found: false,
+        reason: "unknown id"
+      };
+      const cappedNote = {
+        __buoyTruncated: true,
+        note: `Exceeds the ${MAX_CHANGE_DETAIL_BYTES / (1024 * 1024)}MB detail limit — inspect it on-device.`
+      };
+      const cap = value => {
+        try {
+          JSON.stringify(value);
+        } catch {
+          return cappedNote;
+        }
+        return jsonLongerThan(value, MAX_CHANGE_DETAIL_BYTES) ? cappedNote : value;
+      };
+      return {
+        found: true,
+        id,
+        prevState: cap(change.prevState),
+        nextState: cap(change.nextState),
+        partial: cap(change.partial)
+      };
+    },
+    /**
+     * On-demand current state for one store. Wire-form snapshots replace
+     * oversized / unserializable `currentState` with STATE_ON_DEVICE.
+     */
+    getStoreState: params => {
+      const {
+        storeName
+      } = params ?? {};
+      if (!storeName) return {
+        found: false,
+        reason: "missing storeName"
+      };
+      const store = zustandStateStore.getStore(storeName);
+      if (!store) return {
+        found: false,
+        reason: "unknown storeName"
+      };
+      let currentState;
+      try {
+        currentState = store.api.getState();
+      } catch {
+        currentState = undefined;
+      }
+      const cappedNote = {
+        __buoyTruncated: true,
+        note: `Exceeds the ${MAX_CHANGE_DETAIL_BYTES / (1024 * 1024)}MB detail limit — inspect it on-device.`
+      };
+      try {
+        JSON.stringify(currentState);
+      } catch {
+        return {
+          found: true,
+          storeName,
+          currentState: STATE_ON_DEVICE
+        };
+      }
+      return {
+        found: true,
+        storeName,
+        currentState: jsonLongerThan(currentState, MAX_CHANGE_DETAIL_BYTES) ? cappedNote : currentState
+      };
+    },
     /**
      * Compact current-state reader for a remote driver (MCP/LLM): the registered
      * stores with light metadata; each store's full `currentState` object stays
@@ -73,8 +233,20 @@ export const zustandSyncAdapter = {
         storeName,
         state,
         replace
-      } = params;
-      zustandStateStore.getStore(storeName)?.api.setState(state, replace ?? true);
+      } = params ?? {};
+      if (!storeName) return {
+        ok: false,
+        error: "Missing storeName."
+      };
+      const store = zustandStateStore.getStore(storeName);
+      if (!store) return {
+        ok: false,
+        error: `No store named "${storeName}".`
+      };
+      store.api.setState(state, replace ?? true);
+      return {
+        ok: true
+      };
     }
   }
 };