@buoy-gg/zustand 7.0.16 → 7.0.18

package/lib/commonjs/index.js

@@ -93,6 +93,7 @@ Object.defineProperty(exports, "zustandToolPreset", {
     return _preset.zustandToolPreset;
   }
 });
+require("./zustand/utils/snapshotProvider");
 var _preset = require("./preset");
 var _buoyZustandMiddleware = require("./zustand/utils/buoyZustandMiddleware");
 var _useZustandStateChanges = require("./zustand/hooks/useZustandStateChanges");

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

@@ -49,11 +49,16 @@ function ZustandModal({
   onMinimize,
   enableSharedModalDimensions = false,
   inline = false,
-  storesLoading = false
+  storesLoading = false,
+  initialTab = "stores",
+  initialSelectedChangeId,
+  initialDetailView,
+  onChangeSelect,
+  onStoreExpand
 }) {
   const isPro = (0, _license.useIsPro)();
   const [showProModal, setShowProModal] = (0, _react.useState)(false);
-  const [activeTab, setActiveTab] = (0, _react.useState)("stores");
+  const [activeTab, setActiveTab] = (0, _react.useState)(initialTab);
   const [selectedHistoryStore, setSelectedHistoryStore] = (0, _react.useState)(null);
   const [showFilters, setShowFilters] = (0, _react.useState)(false);
   const [ignoredPatterns, setIgnoredPatterns] = (0, _react.useState)(new Set());
@@ -108,6 +113,30 @@ 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 = (0, _react.useRef)(null);
+  (0, _react.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 = (0, _react.useRef)(null);
+  (0, _react.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] = (0, _react.useState)("");
   const [isSearchActive, setIsSearchActive] = (0, _react.useState)(false);
@@ -370,7 +399,8 @@ function ZustandModal({
         changes: activeChanges,
         selectedIndex: selectedChangeIndex,
         onIndexChange: handleIndexChange,
-        disableInternalFooter: true
+        disableInternalFooter: true,
+        initialView: initialDetailView
       });
     }
 
@@ -408,7 +438,8 @@ function ZustandModal({
         stores: displayedStores,
         searchQuery: searchText,
         onViewHistory: handleViewHistory,
-        isLoading: storesLoading
+        isLoading: storesLoading,
+        onStoreExpand: onStoreExpand
       });
     }
 

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

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

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

@@ -26,6 +26,9 @@ var _jsxRuntime = require("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 => {
@@ -146,7 +149,8 @@ function ZustandStoreBrowser({
   stores,
   searchQuery,
   onViewHistory,
-  isLoading = false
+  isLoading = false,
+  onStoreExpand
 }) {
   const [expandedStore, setExpandedStore] = (0, _react.useState)(null);
 
@@ -157,8 +161,12 @@ function ZustandStoreBrowser({
     return stores.filter(s => s.name.toLowerCase().includes(search) || s.persistName && s.persistName.toLowerCase().includes(search));
   }, [stores, searchQuery]);
   const handleStorePress = (0, _react.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__*/(0, _jsxRuntime.jsx)(LoadingBrowserState, {}) : /*#__PURE__*/(0, _jsxRuntime.jsx)(EmptyBrowserState, {});
   }

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

@@ -3,12 +3,84 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.zustandSyncAdapter = void 0;
+exports.zustandSyncAdapter = exports.STATE_ON_DEVICE = exports.PAYLOAD_ON_DEVICE = void 0;
 var _zustandStateStore = require("../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`.
+ */
+const STATE_ON_DEVICE = exports.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). */
+const PAYLOAD_ON_DEVICE = exports.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
@@ -21,13 +93,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.
  */
 const zustandSyncAdapter = exports.zustandSyncAdapter = {
-  version: 1,
+  version: 2,
   getSnapshot: () => ({
-    changes: _zustandStateStore.zustandStateStore.getStateChanges(),
-    stores: _zustandStateStore.zustandStateStore.getStoreSnapshots()
+    changes: _zustandStateStore.zustandStateStore.getStateChanges().map(toWireChange),
+    stores: _zustandStateStore.zustandStateStore.getStoreSnapshots().map(store => ({
+      ...store,
+      currentState: toWireState(store.currentState)
+    }))
   }),
   subscribe: onChange => {
     const unsubscribeChanges = _zustandStateStore.zustandStateStore.subscribe(onChange);
@@ -41,6 +121,86 @@ const zustandSyncAdapter = exports.zustandSyncAdapter = {
     clearEvents: () => {
       _zustandStateStore.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.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.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
@@ -77,8 +237,20 @@ const zustandSyncAdapter = exports.zustandSyncAdapter = {
         storeName,
         state,
         replace
-      } = params;
-      _zustandStateStore.zustandStateStore.getStore(storeName)?.api.setState(state, replace ?? true);
+      } = params ?? {};
+      if (!storeName) return {
+        ok: false,
+        error: "Missing storeName."
+      };
+      const store = _zustandStateStore.zustandStateStore.getStore(storeName);
+      if (!store) return {
+        ok: false,
+        error: `No store named "${storeName}".`
+      };
+      store.api.setState(state, replace ?? true);
+      return {
+        ok: true
+      };
     }
   }
 };

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

@@ -0,0 +1,279 @@
+"use strict";
+
+var _sharedUi = require("@buoy-gg/shared-ui");
+var _dataViewer = require("@buoy-gg/shared-ui/dataViewer");
+var _zustandStateStore = require("./zustandStateStore");
+/**
+ * Time Machine snapshot provider for Zustand.
+ *
+ * Registered into @buoy-gg/shared-ui's stateSnapshotRegistry at module init;
+ * consumed by @buoy-gg/time-machine. Neither package imports the other.
+ *
+ * The Zustand-specific hazard: stores conventionally keep their action
+ * functions IN state (`increment: () => ...`). Functions don't survive
+ * serialization, and a full `setState(snapshot, true)` replace would wipe
+ * them, breaking every `useStore(s => s.increment)` call site. So capture
+ * strips functions (recording where they were), and restore re-grafts the
+ * LIVE store's functions onto the snapshot before replacing.
+ */
+
+const MAX_DEPTH = 8;
+function isPlainObjectLike(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Clone `value` without functions, recording their paths. */
+function stripFunctions(value, path, fnPaths, seen, depth) {
+  if (typeof value === "function") {
+    fnPaths.push(path);
+    return undefined;
+  }
+  if (typeof value !== "object" || value === null || depth >= MAX_DEPTH) {
+    return value;
+  }
+  if (seen.has(value)) return undefined; // cycle — drop the back-reference
+  seen.add(value);
+  if (Array.isArray(value)) {
+    return value.map((item, i) => typeof item === "function" ? (fnPaths.push(`${path}[${i}]`), null) : stripFunctions(item, `${path}[${i}]`, fnPaths, seen, depth + 1));
+  }
+  if (!isPlainObjectLike(value)) return value; // Date/Map/Set/etc. — superjson handles
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (typeof v === "function") {
+      fnPaths.push(path ? `${path}.${k}` : k);
+      continue;
+    }
+    out[k] = stripFunctions(v, path ? `${path}.${k}` : k, fnPaths, seen, depth + 1);
+  }
+  return out;
+}
+
+/**
+ * Copy every function-valued property from the LIVE state onto the restored
+ * snapshot (creating containers as needed), so store actions keep working
+ * after a full replace.
+ */
+function graftFunctions(target, live, seen, depth) {
+  if (!isPlainObjectLike(live) || !isPlainObjectLike(target)) return;
+  if (depth >= MAX_DEPTH || seen.has(live)) return;
+  seen.add(live);
+  for (const [k, v] of Object.entries(live)) {
+    if (typeof v === "function") {
+      target[k] = v;
+    } else if (isPlainObjectLike(v)) {
+      if (!isPlainObjectLike(target[k])) {
+        // Branch missing from the snapshot — only recreate it if it holds
+        // functions somewhere; otherwise the snapshot's absence wins.
+        if (!containsFunction(v, new WeakSet(), depth + 1)) continue;
+        target[k] = {};
+      }
+      graftFunctions(target[k], v, seen, depth + 1);
+    }
+  }
+}
+function containsFunction(value, seen, depth) {
+  if (depth >= MAX_DEPTH || seen.has(value)) return false;
+  seen.add(value);
+  for (const v of Object.values(value)) {
+    if (typeof v === "function") return true;
+    if (isPlainObjectLike(v) && containsFunction(v, seen, depth + 1)) return true;
+  }
+  return false;
+}
+function status() {
+  const count = _zustandStateStore.zustandStateStore.getStores().length;
+  if (count === 0) {
+    return {
+      canCapture: false,
+      canRestore: false,
+      detail: "No Zustand stores registered — pass `zustandStores` to FloatingDevTools or add the buoyDevTools middleware"
+    };
+  }
+  return {
+    canCapture: true,
+    canRestore: true
+  };
+}
+async function capture() {
+  const warnings = [];
+  const stores = {};
+  for (const info of _zustandStateStore.zustandStateStore.getStores()) {
+    const fnPaths = [];
+    let state;
+    try {
+      state = stripFunctions(info.api.getState(), "", fnPaths, new WeakSet(), 0);
+    } catch (e) {
+      warnings.push(`store "${info.name}": capture failed (${String(e)})`);
+      continue;
+    }
+    stores[info.name] = {
+      state,
+      fnPaths
+    };
+  }
+  return {
+    data: {
+      stores
+    },
+    warnings
+  };
+}
+async function restore(data, options) {
+  const snapshot = data;
+  const excludedSet = new Set(options?.excludeKeys ?? []);
+  const includedSet = options?.includeKeys ? new Set(options.includeKeys) : null;
+  const touch = key => !excludedSet.has(key) && (!includedSet || includedSet.has(key));
+  let excludedHits = 0;
+  const result = {
+    ok: true,
+    applied: 0,
+    skipped: [],
+    warnings: []
+  };
+  if (!snapshot?.stores) {
+    return {
+      ok: false,
+      applied: 0,
+      skipped: [],
+      warnings: ["empty zustand snapshot"]
+    };
+  }
+  for (const [name, envelope] of Object.entries(snapshot.stores)) {
+    if (!touch(name)) {
+      excludedHits += 1;
+      continue;
+    }
+    const info = _zustandStateStore.zustandStateStore.getStore(name);
+    if (!info) {
+      result.skipped.push({
+        id: name,
+        reason: "store not registered (renamed, or created after snapshot?)"
+      });
+      continue;
+    }
+    try {
+      const next = envelope.state;
+      graftFunctions(next, info.api.getState(), new WeakSet(), 0);
+      info.api.setState(next, true);
+      if (info.api.getState() === next) {
+        result.applied += 1;
+      } else {
+        result.warnings.push(`store "${name}": setState did not take effect`);
+        result.ok = false;
+      }
+    } catch (e) {
+      result.skipped.push({
+        id: name,
+        reason: String(e)
+      });
+      result.ok = false;
+    }
+  }
+  if (excludedHits > 0) {
+    result.warnings.push(`${excludedHits} store(s) excluded by you`);
+  }
+  return result;
+}
+const ITEM_RENDER_BYTE_LIMIT = 256 * 1024;
+
+/**
+ * Per-store restore preview. Both sides are function-stripped through the
+ * SAME depth-8 normalizer as capture — diffing snapshot-vs-RAW-live would
+ * report every stripped function and every beyond-depth subtree as removed.
+ */
+async function previewItems(target, base) {
+  const targetStores = target?.stores ?? {};
+  const liveMode = base === undefined;
+  const baseStores = {};
+  if (liveMode) {
+    for (const info of _zustandStateStore.zustandStateStore.getStores()) {
+      const fnPaths = [];
+      try {
+        baseStores[info.name] = {
+          state: stripFunctions(info.api.getState(), "", fnPaths, new WeakSet(), 0),
+          fnPaths
+        };
+      } catch {
+        // unreadable live store — treated as absent
+      }
+    }
+  } else {
+    Object.assign(baseStores, base?.stores ?? {});
+  }
+  const items = [];
+  const notes = [];
+  let preservedFns = 0;
+  const names = new Set([...Object.keys(baseStores), ...Object.keys(targetStores)]);
+  for (const name of names) {
+    const inTarget = name in targetStores;
+    const inBase = name in baseStores;
+    if (!inTarget) {
+      // Restore never touches stores the snapshot doesn't know about.
+      if (liveMode) notes.push(`store "${name}" not in snapshot — untouched`);else items.push({
+        key: name,
+        label: name,
+        verdict: "removed",
+        oldValue: baseStores[name].state
+      });
+      continue;
+    }
+    preservedFns += targetStores[name].fnPaths?.length ?? 0;
+    if (liveMode && !_zustandStateStore.zustandStateStore.getStore(name)) {
+      items.push({
+        key: name,
+        label: name,
+        verdict: "wont-apply",
+        reason: "store not registered (renamed, or created after snapshot?)"
+      });
+      continue;
+    }
+    if (!inBase) {
+      items.push({
+        key: name,
+        label: name,
+        verdict: "added",
+        newValue: targetStores[name].state
+      });
+      continue;
+    }
+    const oldState = baseStores[name].state;
+    const newState = targetStores[name].state;
+    if ((0, _dataViewer.boundedDeepEqual)(oldState, newState)) {
+      items.push({
+        key: name,
+        label: name,
+        verdict: "unchanged"
+      });
+    } else if ((0, _dataViewer.jsonLikelyLargerThan)(oldState, ITEM_RENDER_BYTE_LIMIT) || (0, _dataViewer.jsonLikelyLargerThan)(newState, ITEM_RENDER_BYTE_LIMIT)) {
+      items.push({
+        key: name,
+        label: name,
+        verdict: "too-large",
+        reason: "store too large to render a diff — restore still applies it"
+      });
+    } else {
+      items.push({
+        key: name,
+        label: name,
+        verdict: "changed",
+        oldValue: oldState,
+        newValue: newState
+      });
+    }
+  }
+  if (preservedFns > 0) {
+    notes.push(`${preservedFns} store action function${preservedFns === 1 ? "" : "s"} preserved on restore (not diffed)`);
+  }
+  return {
+    items,
+    notes
+  };
+}
+(0, _sharedUi.registerStateSnapshotProvider)({
+  id: "zustand",
+  label: "Zustand",
+  status,
+  capture,
+  restore,
+  previewItems
+});