@buoy-gg/zustand 7.0.29 → 7.0.31

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

@@ -0,0 +1,389 @@
+"use strict";
+
+/**
+ * Editing a store, on a screen of its own — the Storage key editor's shape,
+ * pointed at a live zustand store.
+ *
+ * Same reasoning as storage's editor screen: a tree, six structural actions
+ * and a keyboard don't fit inside an expanded card, so the card offers ONE
+ * edit button and the work happens here with the whole viewport. The tree,
+ * dock, draft and value modal are the shared-ui editor — one implementation,
+ * two tools.
+ *
+ * What is zustand-specific is the WRITE. Storage saves by replacing one key's
+ * serialized value; a store has no such luxury — its state holds the app's
+ * action functions, and a full `setState(draft, true)` replace would delete
+ * them (see `editableState.ts`). So Save diffs the draft against the state it
+ * was seeded from and writes ONE top-level merge:
+ *
+ *   store.api.setState(changedTopLevelKeys, false)
+ *
+ * which by construction cannot remove a key or touch a function. The two
+ * edits a merge cannot express — removing or renaming a top-level key — are
+ * disabled in the dock (`rootEntriesLocked`) and refused at save if they
+ * arrive through the raw-JSON escape hatch.
+ *
+ * On a desktop mirror the same line goes over the wire: the mirrored store's
+ * `api.setState` forwards to the device's sync adapter (the time-travel
+ * path). That write has no ack, so a remote save resolves optimistically and
+ * the next device snapshot is the confirmation.
+ */
+
+import { useCallback, useMemo, useState } from "react";
+import { Alert, ScrollView, StyleSheet, Text, TouchableOpacity, View } from "react-native";
+import { buoyColors, Database, FileJson, night, PillBadge, ToolBackground, useSafeAreaInsets, X } from "@buoy-gg/shared-ui";
+import { DataTreeActionDock, DataViewer, getAtPath, useTreeEditor, ValueEditModal } from "@buoy-gg/shared-ui/dataViewer";
+import { computeMergePartial, editableStateOf } from "../utils/editableState";
+import { ZUSTAND_TEST_ID } from "../utils/testIDs";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const EDITOR_ID = `${ZUSTAND_TEST_ID}-editor`;
+export function ZustandStoreEditorScreen({
+  store,
+  onClose,
+  applySafeAreaInset
+}) {
+  const insets = useSafeAreaInsets();
+  const bottomInset = applySafeAreaInset ? insets.bottom : 0;
+
+  // Seeded ONCE, when the editor opens — the draft is diffed against this at
+  // save, so the partial carries exactly what the user changed and a key the
+  // app wrote meanwhile (untouched here) keeps the app's value.
+  const [seed] = useState(() => editableStateOf(store.api.getState()));
+  const save = useCallback(async draft => {
+    if (seed.data === null) throw new Error("Store is not editable.");
+    const partial = computeMergePartial(seed.data, draft);
+    // A merge, never a replace — the entire reason this editor can exist.
+    // Empty partial = the draft circled back to the seed; nothing to write.
+    if (Object.keys(partial).length > 0) {
+      store.api.setState(partial, false);
+    }
+  }, [seed, store]);
+  const editor = useTreeEditor({
+    value: seed.data,
+    save,
+    onClose,
+    confirmDiscard: choices => Alert.alert("Unsaved changes", `"${store.name}" has edits that haven't been written to the store.`, [{
+      text: "Keep editing",
+      style: "cancel"
+    }, {
+      text: "Discard",
+      style: "destructive",
+      onPress: choices.discard
+    }, {
+      text: "Save",
+      onPress: choices.save
+    }])
+  });
+  const {
+    draft,
+    selection,
+    valuePath
+  } = editor;
+  const keyCount = useMemo(() => {
+    const v = draft.value;
+    return v !== null && typeof v === "object" ? Object.keys(v).length : 0;
+  }, [draft.value]);
+
+  // The card's gating means this can't normally be reached un-editable, but a
+  // remote mirror can theoretically drop hydration between tap and mount.
+  if (seed.data === null) {
+    return /*#__PURE__*/_jsxs(View, {
+      style: styles.screen,
+      children: [/*#__PURE__*/_jsx(ToolBackground, {}), /*#__PURE__*/_jsx(Text, {
+        style: styles.blockedText,
+        children: seed.blockedReason
+      })]
+    });
+  }
+  return /*#__PURE__*/_jsxs(View, {
+    style: styles.screen,
+    children: [/*#__PURE__*/_jsx(ToolBackground, {}), /*#__PURE__*/_jsxs(View, {
+      style: styles.header,
+      children: [/*#__PURE__*/_jsx(TouchableOpacity, {
+        onPress: editor.requestClose,
+        testID: `${EDITOR_ID}-close`,
+        accessibilityRole: "button",
+        accessibilityLabel: "Close editor",
+        style: styles.headerButton,
+        hitSlop: {
+          top: 8,
+          bottom: 8,
+          left: 8,
+          right: 8
+        },
+        children: /*#__PURE__*/_jsx(X, {
+          size: 16,
+          color: night.color.textSecondary
+        })
+      }), /*#__PURE__*/_jsxs(View, {
+        style: styles.headerTitle,
+        children: [/*#__PURE__*/_jsx(Text
+        // Which store this editor is pointed at — opening it on the wrong
+        // one looks exactly like the right one until a write lands
+        // somewhere unexpected.
+        , {
+          testID: `${EDITOR_ID}-store`,
+          style: styles.headerKey,
+          numberOfLines: 1,
+          children: store.name
+        }), /*#__PURE__*/_jsx(Text, {
+          style: [styles.headerState, draft.isDirty && styles.headerDirty],
+          children: draft.isSaving ? "Saving…" : draft.isDirty ? "Draft · unsaved" : "In sync with store"
+        })]
+      }), /*#__PURE__*/_jsxs(TouchableOpacity, {
+        onPress: editor.openRawEditor,
+        testID: `${EDITOR_ID}-raw`,
+        accessibilityRole: "button",
+        accessibilityLabel: "Edit raw JSON",
+        style: styles.headerButton,
+        hitSlop: {
+          top: 8,
+          bottom: 8,
+          left: 8,
+          right: 8
+        },
+        children: [/*#__PURE__*/_jsx(FileJson, {
+          size: 16,
+          color: night.color.accent
+        }), /*#__PURE__*/_jsx(Text, {
+          style: styles.headerRawText,
+          children: "Raw"
+        })]
+      })]
+    }), /*#__PURE__*/_jsxs(View, {
+      style: styles.metaRow,
+      children: [/*#__PURE__*/_jsx(PillBadge, {
+        color: buoyColors.info,
+        icon: store.isPersisted ? /*#__PURE__*/_jsx(Database, {
+          size: 9,
+          color: buoyColors.info
+        }) : undefined,
+        children: store.isPersisted ? store.persistName || "persisted" : "in-memory"
+      }), /*#__PURE__*/_jsxs(Text, {
+        style: styles.metaText,
+        children: [`object · ${keyCount} key${keyCount === 1 ? "" : "s"}`, seed.fnPaths.length > 0 ? ` · ${seed.fnPaths.length} action${seed.fnPaths.length === 1 ? "" : "s"} untouched` : ""]
+      })]
+    }), /*#__PURE__*/_jsxs(ScrollView, {
+      testID: `${EDITOR_ID}-scroll`,
+      style: styles.treeScroll,
+      contentContainerStyle: styles.treeContent,
+      keyboardShouldPersistTaps: "handled",
+      children: [/*#__PURE__*/_jsx(View, {
+        style: styles.treeCard,
+        children: /*#__PURE__*/_jsx(DataViewer, {
+          data: draft.value,
+          title: "",
+          rawMode: true,
+          initialExpanded: true
+          // Type filtering is a READING aid: the filtered view is a
+          // projection whose row paths don't address the real document, so
+          // the explorer stops reporting selection while one is active. An
+          // editor whose actions silently go dead isn't worth the filter.
+          ,
+          showTypeFilter: false,
+          onSelectionChange: editor.setSelection,
+          selectPath: draft.selectPath
+          // Its own handle root: the card that opened this editor is still
+          // mounted underneath, rendering the same value in its preview tree.
+          ,
+          testIDPrefix: `${EDITOR_ID}-row`,
+          onRequestInlineEdit: sel => editor.openValueEditor(sel.path)
+        })
+      }), /*#__PURE__*/_jsx(Text, {
+        style: styles.treeHint,
+        children: "Tap a row to select it \xB7 double-tap to edit its value \xB7 saves merge into the live store, so actions and untouched keys survive"
+      })]
+    }), draft.error ? /*#__PURE__*/_jsx(Text, {
+      style: styles.error,
+      numberOfLines: 3,
+      testID: `${EDITOR_ID}-error`,
+      children: draft.error
+    }) : null, /*#__PURE__*/_jsxs(View, {
+      style: [styles.footer, {
+        paddingBottom: bottomInset
+      }],
+      children: [/*#__PURE__*/_jsx(DataTreeActionDock, {
+        root: draft.value,
+        selection: selection,
+        onEdit: draft.apply,
+        onSelectPath: draft.selectAt
+        // Booleans never reach this — the dock applies their flip directly.
+        ,
+        onEditValue: () => editor.openValueEditor(selection?.path ?? [])
+        // A merge write can rewrite a top-level key but never delete one, so
+        // Remove is disabled at depth 1 — see `editableState.ts`.
+        ,
+        rootEntriesLocked: true
+      }), draft.isDirty ? /*#__PURE__*/_jsxs(View, {
+        style: styles.commitRow,
+        children: [/*#__PURE__*/_jsx(TouchableOpacity, {
+          onPress: draft.discard,
+          disabled: draft.isSaving,
+          testID: `${EDITOR_ID}-discard`,
+          accessibilityRole: "button",
+          accessibilityLabel: "Discard changes",
+          style: styles.discardButton,
+          children: /*#__PURE__*/_jsx(Text, {
+            style: styles.discardText,
+            children: "Discard"
+          })
+        }), /*#__PURE__*/_jsx(TouchableOpacity, {
+          onPress: editor.saveAndClose,
+          disabled: draft.isSaving,
+          testID: `${EDITOR_ID}-save`,
+          accessibilityRole: "button",
+          accessibilityLabel: "Save changes",
+          style: [styles.saveButton, draft.isSaving && styles.saveDisabled],
+          children: /*#__PURE__*/_jsx(Text, {
+            style: styles.saveText,
+            children: draft.isSaving ? "Saving…" : "Save changes"
+          })
+        })]
+      }) : null]
+    }), valuePath ? /*#__PURE__*/_jsx(ValueEditModal, {
+      path: valuePath,
+      value: getAtPath(draft.value, valuePath),
+      onSave: editor.applyValue,
+      onCancel: editor.closeValueEditor
+      // It only reaches the draft here — the single write happens on Save.
+      ,
+      saveLabel: "Apply",
+      testIDPrefix: `${ZUSTAND_TEST_ID}-value`
+    }) : null]
+  });
+}
+const styles = StyleSheet.create({
+  screen: {
+    flex: 1,
+    // Opaque on purpose: transparency here showed the whole store list
+    // through the editor, not just the sheet's backdrop. The screen paints
+    // its own ToolBackground instead — see the mount site above.
+    backgroundColor: night.color.bg
+  },
+  blockedText: {
+    color: night.color.textTertiary,
+    fontSize: 12,
+    padding: 20,
+    textAlign: "center",
+    lineHeight: 18
+  },
+  header: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 8,
+    paddingHorizontal: 10,
+    paddingVertical: 8,
+    borderBottomWidth: 1,
+    borderBottomColor: night.color.border
+  },
+  headerButton: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 4,
+    paddingVertical: 6,
+    paddingHorizontal: 4
+  },
+  headerRawText: {
+    color: night.color.accent,
+    fontSize: 12,
+    fontWeight: "700"
+  },
+  headerTitle: {
+    flex: 1,
+    alignItems: "center",
+    gap: 2
+  },
+  headerKey: {
+    color: night.color.text,
+    fontSize: 13,
+    fontWeight: "600",
+    fontFamily: "monospace"
+  },
+  headerState: {
+    color: night.color.textTertiary,
+    fontSize: 10
+  },
+  headerDirty: {
+    color: night.color.warning
+  },
+  metaRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 8,
+    paddingHorizontal: 12,
+    paddingVertical: 8
+  },
+  metaText: {
+    color: night.color.textTertiary,
+    fontSize: 11,
+    fontFamily: "monospace"
+  },
+  treeScroll: {
+    flex: 1
+  },
+  treeContent: {
+    paddingHorizontal: 12,
+    paddingBottom: 16
+  },
+  treeCard: {
+    backgroundColor: night.color.surface,
+    borderRadius: 10,
+    borderWidth: 1,
+    borderColor: night.color.border,
+    padding: 6
+  },
+  treeHint: {
+    color: night.color.textTertiary,
+    fontSize: 10,
+    paddingTop: 8,
+    paddingHorizontal: 4
+  },
+  error: {
+    color: night.color.danger,
+    fontSize: 11,
+    fontFamily: "monospace",
+    paddingHorizontal: 12,
+    paddingBottom: 6
+  },
+  footer: {
+    backgroundColor: night.color.surface
+  },
+  commitRow: {
+    flexDirection: "row",
+    gap: 8,
+    paddingHorizontal: 12,
+    paddingVertical: 10,
+    borderTopWidth: 1,
+    borderTopColor: night.color.border
+  },
+  discardButton: {
+    flex: 1,
+    minHeight: 44,
+    alignItems: "center",
+    justifyContent: "center",
+    borderRadius: 10,
+    borderWidth: 1,
+    borderColor: night.color.border
+  },
+  discardText: {
+    color: night.color.textSecondary,
+    fontSize: 14,
+    fontWeight: "600"
+  },
+  saveButton: {
+    flex: 1.4,
+    minHeight: 44,
+    alignItems: "center",
+    justifyContent: "center",
+    borderRadius: 10,
+    backgroundColor: night.color.accent
+  },
+  saveDisabled: {
+    opacity: 0.5
+  },
+  saveText: {
+    color: night.color.onAccent,
+    fontSize: 15,
+    fontWeight: "700"
+  }
+});

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

@@ -179,6 +179,7 @@ export const zustandSyncAdapter = {
         changes: s.stateChangeCount,
         isPersisted: s.isPersisted,
         persistName: s.persistName,
+        canRehydrate: s.canRehydrate,
         ...(includeValues ? {
           currentState: s.currentState
         } : {
@@ -211,6 +212,59 @@ export const zustandSyncAdapter = {
       return {
         ok: true
       };
+    },
+    /**
+     * Re-read a persisted store's saved value and merge it into the live store.
+     *
+     * This is what makes editing a store's storage key mean anything. The app
+     * reads that key once at startup and then holds the state in memory, so an
+     * outside write — the Storage tool, a scenario, an agent — changes the disk
+     * and nothing else, and the next time the store saves it writes its own
+     * copy straight back over the edit.
+     *
+     * `persist.rehydrate()` is plain zustand, not a devtools hook, so unlike
+     * reloading the app this also works in a release build. It merges the saved
+     * value OVER current state (zustand's default merge is
+     * `{...current, ...persisted}`), so the store's action functions survive,
+     * and it does not write back to storage unless a version migration ran —
+     * the edit stays exactly as it was typed.
+     *
+     * Two honest limits, both inherent to persist rather than to this action:
+     * a key the store's `partialize` excludes is not in the saved value and so
+     * cannot be applied, and because the merge is shallow, DELETING a top-level
+     * key from the saved JSON does not remove it from the live store.
+     */
+    rehydrate: async params => {
+      const {
+        storeName
+      } = params ?? {};
+      if (!storeName) return {
+        ok: false,
+        error: "Missing storeName."
+      };
+      const store = zustandStateStore.getStore(storeName);
+      if (!store) return {
+        ok: false,
+        error: `No store named "${storeName}".`
+      };
+      if (!store.isPersisted) {
+        return {
+          ok: false,
+          error: `"${storeName}" is not a persisted store — it has no saved copy to re-read.`
+        };
+      }
+      if (!store.rehydrate) {
+        return {
+          ok: false,
+          error: `"${storeName}" is persisted but Buoy has no rehydrate handle for it. It was probably registered before the app's persist middleware attached.`
+        };
+      }
+      await store.rehydrate();
+      return {
+        ok: true,
+        storeName,
+        persistName: store.persistName
+      };
     }
   }
 };

package/lib/module/zustand/utils/buoyZustandMiddleware.js

@@ -18,6 +18,8 @@ import { zustandStateStore } from "./zustandStateStore";
 /** Symbol to mark stores that have been watched/instrumented */
 const WATCHED_SYMBOL = Symbol.for("@@buoy-zustand/watched");
 
+/** The slice of zustand's persist API this module uses. */
+
 /**
  * Detect if a store is using the persist middleware by checking for persist API
  */
@@ -27,7 +29,8 @@ function detectPersist(store) {
     const options = persist.getOptions();
     return {
       isPersisted: true,
-      persistName: options?.name
+      persistName: options?.name,
+      persistApi: persist
     };
   }
   return {
@@ -78,7 +81,8 @@ export function watchStores(stores) {
     storeAny[WATCHED_SYMBOL] = true;
     const {
       isPersisted,
-      persistName
+      persistName,
+      persistApi
     } = detectPersist(store);
 
     // Register the store for overview
@@ -89,12 +93,36 @@ export function watchStores(stores) {
       subscribe: store.subscribe
     }, {
       isPersisted,
-      persistName
+      persistName,
+      // Was detected and thrown away. Without it nothing can re-read the
+      // saved copy after an outside edit — see ZustandStoreInfo.rehydrate.
+      rehydrate: typeof persistApi?.rehydrate === "function" ? () => persistApi.rehydrate() : undefined
     });
 
+    // The rehydration is a state change nobody's code asked for — the store
+    // simply becomes what the disk said, seconds into the process. Drawn as an
+    // ordinary setState it is the most surprising row in the list and the one
+    // that looks most like a bug, so it gets its own category. Recognised
+    // rather than announced: `hasHydrated()` is still false while the
+    // rehydrating `set` is running, and this listener runs inside it.
+    let sawHydration = false;
+
     // Subscribe to state changes — completely external, never touches setState
     const unsubscribe = store.subscribe((state, prevState) => {
       try {
+        let category;
+        if (!sawHydration && isPersisted) {
+          let hydrating = false;
+          try {
+            hydrating = persistApi?.hasHydrated?.() === false;
+          } catch {
+            // An older persist API without hasHydrated — no worse than before.
+          }
+          if (hydrating) {
+            sawHydration = true;
+            category = "persist";
+          }
+        }
         zustandStateStore.addStateChange({
           storeName: name,
           partial: undefined,
@@ -104,6 +132,7 @@ export function watchStores(stores) {
           nextState: state,
           duration: undefined,
           // Not available in subscribe-only mode
+          category,
           isPersisted
         });
       } catch {
@@ -154,17 +183,36 @@ let unnamedCounter = 0;
  * );
  * ```
  */
+/**
+ * Zustand's own `set` shape (v5 types): with `replace: true` the argument must
+ * be a FULL state, so a single `(partial, replace?: boolean)` signature is
+ * incompatible in both directions — zustand's set is not assignable to it,
+ * which made `create(buoyDevTools(...))` fail to typecheck for every strict-TS
+ * user. Mirroring the overloads keeps buoyDevTools a drop-in for `create()`.
+ */
+
+/**
+ * The store api object zustand hands a middleware, described structurally so
+ * this package never has to import zustand's own types (which differ between
+ * v4 and v5). `Record<string, unknown>` was wrong here: `StoreApi<T>` has no
+ * index signature, so `create(buoyDevTools(...))` failed to typecheck.
+ */
+
 export function buoyDevTools(config, options) {
   return (set, get, api) => {
     const storeName = options?.name ?? `store-${++unnamedCounter}`;
     const enabled = options?.enabled !== false;
+
+    // Forwarding a plain `replace?: boolean` through the overloads needs one
+    // widening cast; runtime behavior is unchanged.
+    const rawSet = set;
     const instrumentedSet = (partial, replace) => {
       if (!enabled) {
-        return set(partial, replace);
+        return rawSet(partial, replace);
       }
       const startTime = performance.now();
       const prevState = get();
-      set(partial, replace);
+      rawSet(partial, replace);
       const nextState = get();
       const duration = performance.now() - startTime;
       const resolvedPartial = typeof partial === "function" ? "(updater fn)" : partial;
@@ -175,7 +223,14 @@ export function buoyDevTools(config, options) {
         prevState,
         nextState,
         duration,
-        isPersisted: false
+        // Read back off the registry rather than hardcoded false. Persistence
+        // is a property of the STORE, and this middleware can be wrapped
+        // around a persisted one — every change on such a store used to be
+        // drawn as un-persisted, which is the opposite of what the badge is
+        // for. Registration happens a tick after creation, so a set fired in
+        // that first tick still reports false; the alternative is re-sniffing
+        // `api.persist` on every set.
+        isPersisted: zustandStateStore.getStore(storeName)?.isPersisted ?? false
       });
     };
     const result = config(instrumentedSet, get, api);
@@ -191,7 +246,16 @@ export function buoyDevTools(config, options) {
       zustandStateStore.registerStore(storeName, {
         getState: get,
         getInitialState: api.getInitialState,
-        setState: set,
+        // The INSTRUMENTED set, not the raw one.
+        //
+        // This handle is what the tool's own JUMP and RESET STORE call, and
+        // registering the raw `set` here made both of them invisible: the
+        // store changed, the app re-rendered, and nothing appeared in the
+        // log — so the newest row's "state after change" no longer described
+        // the store, and the next diff compared against a state the device
+        // had never been in. The watch path never had this problem, because
+        // it observes the store from outside and cannot be gone around.
+        setState: instrumentedSet,
         subscribe: api.subscribe
       }, {
         isPersisted,