@buoy-gg/storage 7.0.4 → 7.0.6

package/lib/module/storage/hooks/useSecureStoreKeys.js

@@ -1,6 +1,6 @@
 "use strict";
 
-import { useState, useEffect, useCallback } from "react";
+import { useState, useEffect, useCallback, useRef } from "react";
 import { secureStoreRegistry } from "../utils/SecureStoreRegistry";
 
 /**
@@ -9,6 +9,23 @@ import { secureStoreRegistry } from "../utils/SecureStoreRegistry";
  * auto-reads them — it just shows they exist.
  */
 const BIOMETRIC_PLACEHOLDER = "•••••• (biometric protected)";
+
+/**
+ * How often to re-read registered SecureStore values.
+ *
+ * SecureStore is the one backend with no change feed at all: AsyncStorage and
+ * MMKV writes are intercepted (and MMKV has a native value-changed listener),
+ * but the keychain gives no notification, so a value written by the app while
+ * the tool is open would otherwise stay stale until the browser remounts.
+ * Polling is the only option — kept cheap by re-reading a handful of registered
+ * keys and only committing state when a value actually changed.
+ */
+const DEFAULT_POLL_MS = 3000;
+/** Identity signature used to skip no-op state updates. */
+function signature(keys) {
+  return JSON.stringify(keys);
+}
+
 /**
  * Read all registered SecureStore keys into StorageKeyInfo[] for the browser.
  *
@@ -16,22 +33,47 @@ const BIOMETRIC_PLACEHOLDER = "•••••• (biometric protected)";
  * `registerSecureStoreKeys()` (see SecureStoreRegistry). Values are read with
  * the options each key was registered with (keychainService must match), and
  * biometric-protected keys are listed without being read.
+ *
+ * Values are re-read on a poll and whenever the registry changes, so the
+ * browser tracks writes the app makes while the tool is open.
  */
-export function useSecureStoreKeys() {
+export function useSecureStoreKeys(options = {}) {
+  const {
+    pollMs = DEFAULT_POLL_MS
+  } = options;
   const [storageKeys, setStorageKeys] = useState([]);
   const [isLoading, setIsLoading] = useState(true);
   const [error, setError] = useState(null);
+
+  // Last committed content, so a poll that finds nothing new costs zero
+  // renders (this hook feeds a non-virtualized list of every storage key).
+  const signatureRef = useRef(signature([]));
+  const hasLoadedRef = useRef(false);
+  const inFlightRef = useRef(false);
+  const commit = useCallback(keys => {
+    const next = signature(keys);
+    if (next === signatureRef.current) return;
+    signatureRef.current = next;
+    setStorageKeys(keys);
+  }, []);
   const fetchSecureStoreData = useCallback(async () => {
-    const module = secureStoreRegistry.getModule();
-    const entries = secureStoreRegistry.getAll();
-    if (!module || entries.length === 0) {
-      setStorageKeys([]);
-      setIsLoading(false);
-      return;
-    }
-    setIsLoading(true);
-    setError(null);
+    // Reads are async and the poll is unconditional — never stack them.
+    if (inFlightRef.current) return;
+    inFlightRef.current = true;
     try {
+      const module = secureStoreRegistry.getModule();
+      const entries = secureStoreRegistry.getAll();
+      if (!module || entries.length === 0) {
+        commit([]);
+        hasLoadedRef.current = true;
+        setIsLoading(false);
+        return;
+      }
+
+      // Only the first read is a "loading" state; polls refresh in place so the
+      // browser never flashes its spinner over data it already has.
+      if (!hasLoadedRef.current) setIsLoading(true);
+      setError(null);
       const keys = [];
       for (const entry of entries) {
         if (entry.options.requireAuthentication) {
@@ -79,19 +121,32 @@ export function useSecureStoreKeys() {
           })
         });
       }
-      setStorageKeys(keys);
+      commit(keys);
     } catch (err) {
       setError(err instanceof Error ? err : new Error("Failed to read SecureStore"));
-      setStorageKeys([]);
+      commit([]);
     } finally {
+      hasLoadedRef.current = true;
+      inFlightRef.current = false;
       setIsLoading(false);
     }
-  }, []);
+  }, [commit]);
 
-  // Initial fetch (registration happens at app startup, before the tool opens)
+  // Initial fetch + poll. Registration usually happens at app startup, but the
+  // registry is also refilled on the dashboard every time a device syncs, so
+  // subscribe as well rather than assuming the key list is final at mount.
   useEffect(() => {
     fetchSecureStoreData();
-  }, [fetchSecureStoreData]);
+    const unsubscribe = secureStoreRegistry.subscribe(() => {
+      fetchSecureStoreData();
+    });
+    if (pollMs <= 0) return unsubscribe;
+    const interval = setInterval(fetchSecureStoreData, pollMs);
+    return () => {
+      unsubscribe();
+      clearInterval(interval);
+    };
+  }, [fetchSecureStoreData, pollMs]);
   return {
     storageKeys,
     isLoading,

package/lib/module/storage/hooks/useTreeDraft.js

@@ -0,0 +1,103 @@
+"use strict";
+
+/**
+ * A local draft of a storage value, edited in place and written ONCE.
+ *
+ * Applying each tree op straight to the device was the obvious first cut and it
+ * behaves badly for two compounding reasons:
+ *
+ * 1. **Every op is a round trip.** The write lands, the device emits a storage
+ *    event, a snapshot comes back, and the browser re-reads every backend — so
+ *    a six-tap reorder is six writes and six full refreshes. The tree rebuilds
+ *    under the user mid-gesture.
+ * 2. **The highlight and the value fall out of step.** Selection is local and
+ *    moves instantly; the value it points at only catches up when the round
+ *    trip completes, so for a beat the highlight sits on the old contents.
+ *
+ * Optimistic updates — the React Query pattern of rendering the expected result
+ * and reconciling later — fix (2) but not (1): they still write per change.
+ * Buffering fixes both, and it's what every editor that owns a document does
+ * (a form's dirty state, an IDE's unsaved buffer, JSON Editor's in-memory doc
+ * with an explicit save).
+ *
+ * The trade is that the buffer can go stale if the app writes the same key
+ * while you're editing. That's the same last-write-wins a text editor has, and
+ * `isDirty` at least makes it visible that you're holding unsaved changes.
+ */
+
+import { useCallback, useState } from "react";
+import { applyJsonOp, selectionPathAfterOp } from "@buoy-gg/shared-ui/dataViewer";
+/**
+ * @param liveValue  the value as storage currently holds it (already parsed)
+ * @param save       persists the serialized draft; rejecting keeps edit mode open
+ */
+export function useTreeDraft(liveValue, save) {
+  const [draft, setDraft] = useState(undefined);
+  const [isEditing, setIsEditing] = useState(false);
+  const [isSaving, setIsSaving] = useState(false);
+  const [error, setError] = useState(null);
+  const [selectPath, setSelectPath] = useState();
+  /**
+   * The value as it was when editing began. Compared against for dirtiness
+   * rather than against `liveValue`, which can move underneath us if the app
+   * writes the same key — that would otherwise flip a clean draft to dirty.
+   */
+  const [baseline, setBaseline] = useState("");
+  const value = isEditing && draft !== undefined ? draft : liveValue;
+  const isDirty = isEditing && JSON.stringify(draft) !== baseline;
+  const begin = useCallback(() => {
+    setDraft(liveValue);
+    setBaseline(JSON.stringify(liveValue));
+    setSelectPath(undefined);
+    setError(null);
+    setIsEditing(true);
+  }, [liveValue]);
+  const apply = useCallback(op => {
+    // Purely local — this is the whole point. No write, so no event, no
+    // snapshot, no refresh, and the tree re-renders from state synchronously.
+    setDraft(prev => applyJsonOp(prev, op));
+    const next = selectionPathAfterOp(op);
+    if (next !== undefined) setSelectPath(next);
+  }, []);
+  const selectAt = useCallback(path => {
+    setSelectPath(path);
+  }, []);
+  const reset = useCallback(() => {
+    setIsEditing(false);
+    setDraft(undefined);
+    setSelectPath(undefined);
+    setError(null);
+  }, []);
+  const commit = useCallback(async () => {
+    if (!isDirty || !save) {
+      reset();
+      return true;
+    }
+    setIsSaving(true);
+    setError(null);
+    try {
+      await save(JSON.stringify(draft));
+      reset();
+      return true;
+    } catch (e) {
+      // Stay in edit mode so the work isn't lost to a failed write.
+      setError(e instanceof Error ? e.message : String(e));
+      return false;
+    } finally {
+      setIsSaving(false);
+    }
+  }, [draft, isDirty, reset, save]);
+  return {
+    isEditing,
+    value,
+    isDirty,
+    isSaving,
+    error,
+    selectPath,
+    begin,
+    apply,
+    selectAt,
+    commit,
+    discard: reset
+  };
+}

package/lib/module/storage/index.js

@@ -8,6 +8,9 @@ export { StorageKeyStatsSection } from "./components/StorageKeyStats";
 export { StorageKeySection } from "./components/StorageKeySection";
 export { StorageBrowserMode } from "./components/StorageBrowserMode";
 export { StorageEventsSection } from "./components/StorageEventsSection";
+// The five display operations a storage event collapses onto — semantics, not
+// presentation, so hosts can filter or group by the same vocabulary the UI uses.
+export { STORAGE_OPS, storageOpOf, storageOpDot, isInitialScan } from "./utils/storageOps";
 export { StorageEventCard, getValueType } from "./components/StorageEventCard";
 export { StorageEventDetailContent, StorageEventDetailFooter } from "./components/StorageEventDetailContent";
 

package/lib/module/storage/stores/storageEventStore.js

@@ -98,7 +98,8 @@ class StorageEventStore extends BaseEventStore {
             data: {
               key,
               value,
-              valueType
+              valueType,
+              initialScan: true
             },
             storageType: "mmkv",
             id: nextStorageEventId()
@@ -125,7 +126,8 @@ class StorageEventStore extends BaseEventStore {
               timestamp: now,
               data: {
                 key,
-                value: rawValue ?? undefined
+                value: rawValue ?? undefined,
+                initialScan: true
               },
               storageType: "async",
               id: nextStorageEventId()

package/lib/module/storage/sync/storageSyncAdapter.js

@@ -5,6 +5,7 @@ import { isDevToolsStorageKey } from "@buoy-gg/shared-ui";
 import { readMany, writeMany, removeMany } from "../utils/asyncStorageCompat";
 import { storageEventStore } from "../stores/storageEventStore";
 import { clearAllAppStorage } from "../utils/clearAllStorage";
+import { undoOperation, jumpToState, canUndo } from "../utils/storageTimeTravelUtils";
 import { mmkvInstanceRegistry } from "../utils/MMKVInstanceRegistry";
 import { detectMMKVType } from "../utils/mmkvTypeDetection";
 import { secureStoreRegistry } from "../utils/SecureStoreRegistry";
@@ -13,6 +14,28 @@ import { secureStoreRegistry } from "../utils/SecureStoreRegistry";
 
 /** One MMKV instance in a `mmkv.snapshot` result. */
 
+/** One registered key in a `secure.snapshot` result. */
+
+/**
+ * Resolve an MMKV instance for WRITING, refusing the ones the app registered
+ * read-only.
+ *
+ * The registry has always tracked `readOnly`, but nothing enforced it: any sync
+ * client — dashboard or MCP — could write to an instance the app explicitly
+ * declared immutable. That was harmless while the tool could only read; it
+ * stops being harmless the moment there's an edit UI pointed at it.
+ */
+function assertMMKVWritable(instanceId) {
+  const registered = mmkvInstanceRegistry.get(instanceId);
+  if (!registered) {
+    throw new Error(`No MMKV instance registered as "${instanceId}"`);
+  }
+  if (registered.instance?.isReadOnly) {
+    throw new Error(`MMKV instance "${instanceId}" is registered read-only`);
+  }
+  return registered.instance;
+}
+
 /**
  * Sync adapter for the storage tool, consumed by @buoy-gg/external-sync's
  * `useExternalSync` (structurally matches its ToolSyncAdapter interface so
@@ -42,6 +65,58 @@ export const storageSyncAdapter = {
     },
     /** Clears all app storage keys, preserving dev tools settings. */
     clearAppStorage: () => clearAllAppStorage(),
+    // ── Time travel (same code path as the modal's UNDO / JUMP buttons) ──
+    // The UI swallows failures silently; these THROW so a caller (desktop, MCP)
+    // gets the actual reason back instead of a no-op.
+
+    /** Undo one event, addressed by the `id` the store assigned it. */
+    "timeTravel.undo": async params => {
+      const id = params?.id;
+      if (!id) throw new Error("timeTravel.undo requires an event `id`");
+      const event = storageEventStore.getEvents().find(e => e.id === id);
+      if (!event) throw new Error(`No storage event with id "${id}"`);
+      if (event.storageType === "mmkv") {
+        throw new Error("Time travel supports AsyncStorage events only");
+      }
+      const asyncEvent = event;
+      if (!canUndo(asyncEvent)) {
+        throw new Error(`Event "${id}" (${asyncEvent.action}) has no previous value captured, so it cannot be undone`);
+      }
+      await undoOperation(asyncEvent);
+      return {
+        undone: true,
+        action: asyncEvent.action,
+        key: asyncEvent.data?.key
+      };
+    },
+    /**
+     * Jump storage back to the state as of one event. `scope: "key"` (default)
+     * replays only that key's history, matching the modal's JUMP button;
+     * `scope: "all"` replays every captured AsyncStorage event.
+     */
+    "timeTravel.jump": async params => {
+      const {
+        id,
+        scope = "key"
+      } = params ?? {};
+      if (!id) throw new Error("timeTravel.jump requires an event `id`");
+
+      // Oldest-first, which is the order jumpToState replays in.
+      const all = storageEventStore.getEvents().filter(e => e.storageType !== "mmkv").slice().reverse();
+      const target = all.find(e => e.id === id);
+      if (!target) throw new Error(`No AsyncStorage event with id "${id}"`);
+      const timeline = scope === "all" ? all : all.filter(e => e.data?.key === target.data?.key);
+      const index = timeline.findIndex(e => e.id === id);
+      if (index === -1) throw new Error(`Event "${id}" is not in the timeline`);
+      await jumpToState(timeline, index);
+      return {
+        jumped: true,
+        scope,
+        replayed: index + 1,
+        of: timeline.length,
+        key: target.data?.key
+      };
+    },
     // ── Remote AsyncStorage proxy (desktop browse/edit mode) ──
     // Single-item methods share the same signature across async-storage v2/v3;
     // batch methods go through the compat helpers (which translate to v3's
@@ -104,16 +179,16 @@ export const storageSyncAdapter = {
         key,
         value
       } = params;
-      mmkvInstanceRegistry.get(instanceId)?.instance.set(key, value);
+      assertMMKVWritable(instanceId).set(key, value);
     },
     "mmkv.remove": params => {
       const {
         instanceId,
         key
       } = params;
-      const instance = mmkvInstanceRegistry.get(instanceId)?.instance;
+      const instance = assertMMKVWritable(instanceId);
       // v4 renamed delete() to remove() — support both
-      if (instance?.remove) instance.remove(key);else instance?.delete?.(key);
+      if (instance.remove) instance.remove(key);else instance.delete?.(key);
     },
     // ── Remote SecureStore proxy ──
     // Only registered keys are known (SecureStore has no enumeration API).
@@ -128,6 +203,40 @@ export const storageSyncAdapter = {
       keychainService: options.keychainService,
       requireAuthentication: options.requireAuthentication ?? false
     })),
+    /**
+     * Every registered key WITH its value, in one round trip — the SecureStore
+     * counterpart to `mmkv.snapshot`. The dashboard polls this (the keychain
+     * has no change feed) and serves the browser from the result, instead of
+     * firing one `secure.get` per key per refresh.
+     */
+    "secure.snapshot": async () => {
+      const module = secureStoreRegistry.getModule();
+      const entries = secureStoreRegistry.getAll();
+      const result = [];
+      for (const {
+        key,
+        options,
+        description
+      } of entries) {
+        let value = null;
+        // Biometric-protected keys are never read — that would fire an auth prompt.
+        if (module && !options.requireAuthentication) {
+          try {
+            value = await module.getItemAsync(key, options);
+          } catch {
+            // Unreadable (e.g. keychain state changed) — report as unset
+          }
+        }
+        result.push({
+          key,
+          description,
+          keychainService: options.keychainService,
+          requireAuthentication: options.requireAuthentication ?? false,
+          value
+        });
+      }
+      return result;
+    },
     "secure.get": params => {
       const {
         key
@@ -139,6 +248,19 @@ export const storageSyncAdapter = {
       }
       return module.getItemAsync(key, entry.options);
     },
+    /**
+     * Write a registered SecureStore key. Goes through the registry so the
+     * value is written with the SAME options it was registered with — writing
+     * with different `keychainService` options creates a second entry the app
+     * can't read. Biometric-protected keys throw rather than prompting.
+     */
+    "secure.set": params => {
+      const {
+        key,
+        value
+      } = params;
+      return secureStoreRegistry.setValue(key, value);
+    },
     "secure.delete": params => secureStoreRegistry.deleteValue(params.key)
   }
 };

package/lib/module/storage/utils/AsyncStorageListener.js

@@ -6,6 +6,28 @@ import { asyncStorage as AsyncStorage, asyncStorageCaps, readMany } from "./asyn
 
 // v3-only batch methods (replace multiSet/multiRemove)
 
+/**
+ * The pristine (un-swizzled) AsyncStorage methods, stashed on globalThis under a
+ * cross-realm Symbol.
+ *
+ * Why this exists: the listener below is a module-scope singleton. Metro Fast
+ * Refresh re-evaluates the module and builds a NEW instance whose `original*`
+ * fields are all null — but `AsyncStorage.setItem` still points at the OLD
+ * instance's `swizzled_setItem`. Without a stash, `initialize()` sees the
+ * existing swizzle, has no way to recover the real methods, and bails; the
+ * listener then never attaches, so storage events stop for the rest of the
+ * session (writes still work, they just go unrecorded). Keeping the originals
+ * off the instance lets a fresh instance re-attach cleanly.
+ */
+
+const ORIGINALS_KEY = Symbol.for("@buoy-gg/storage.asyncStorageOriginals");
+function readStashedOriginals() {
+  return globalThis[ORIGINALS_KEY] ?? null;
+}
+function stashOriginals(originals) {
+  globalThis[ORIGINALS_KEY] = originals;
+}
+
 // Event types for AsyncStorage operations
 
 /**
@@ -90,6 +112,25 @@ class AsyncStorageListener {
     return false;
   }
 
+  /**
+   * Copy a set of pristine methods onto this instance's `original*` fields.
+   *
+   * Used both when capturing them for the first time and when adopting the
+   * global stash after a Fast Refresh, so `restoreOriginalMethods()` and the
+   * swizzles always have real methods to call through to.
+   */
+  adoptOriginals(originals) {
+    this.originalSetItem = originals.setItem;
+    this.originalRemoveItem = originals.removeItem;
+    this.originalClear = originals.clear;
+    this.originalMergeItem = originals.mergeItem;
+    this.originalMultiSet = originals.multiSet;
+    this.originalMultiRemove = originals.multiRemove;
+    this.originalMultiMerge = originals.multiMerge;
+    this.originalSetMany = originals.setMany;
+    this.originalRemoveMany = originals.removeMany;
+  }
+
   /**
    * Initialize the listener by loading AsyncStorage and storing original methods
    *
@@ -106,29 +147,52 @@ class AsyncStorageListener {
       return true;
     }
 
-    // Check if methods are already swizzled by checking the function name
+    // Already swizzled — by a previous instance of this class that Fast Refresh
+    // replaced, or by a duplicate copy of the package. Adopt the stashed
+    // originals so this instance can restore + re-swizzle. Bailing here is what
+    // used to kill storage events until a full app reload.
     if (AsyncStorage.setItem.name === "swizzled_setItem") {
-      // Don't store swizzled methods as originals
-      return false;
+      const stashed = readStashedOriginals();
+      if (!stashed) {
+        // Swizzled by something we didn't install and whose originals we never
+        // captured — taking the current methods as "originals" would bake the
+        // foreign swizzle in permanently, so stay out of the way.
+        return false;
+      }
+      this.adoptOriginals(stashed);
+      this.isInitialized = true;
+      return true;
     }
 
     // Store original methods (these should be the real AsyncStorage methods).
     // Single-item + clear are identical across v2/v3.
-    this.originalSetItem = AsyncStorage.setItem.bind(AsyncStorage);
-    this.originalRemoveItem = AsyncStorage.removeItem.bind(AsyncStorage);
-    this.originalClear = AsyncStorage.clear.bind(AsyncStorage);
+    const originals = {
+      setItem: AsyncStorage.setItem.bind(AsyncStorage),
+      removeItem: AsyncStorage.removeItem.bind(AsyncStorage),
+      clear: AsyncStorage.clear.bind(AsyncStorage),
+      mergeItem: null,
+      multiSet: null,
+      multiRemove: null,
+      multiMerge: null,
+      setMany: null,
+      removeMany: null
+    };
     if (asyncStorageCaps.hasLegacyMultiApi) {
       // v2: multiSet/multiRemove + merge API
-      this.originalMultiSet = AsyncStorage.multiSet.bind(AsyncStorage);
-      this.originalMultiRemove = AsyncStorage.multiRemove.bind(AsyncStorage);
-      this.originalMergeItem = AsyncStorage.mergeItem.bind(AsyncStorage);
-      this.originalMultiMerge = AsyncStorage.multiMerge ? AsyncStorage.multiMerge.bind(AsyncStorage) : null;
+      originals.multiSet = AsyncStorage.multiSet.bind(AsyncStorage);
+      originals.multiRemove = AsyncStorage.multiRemove.bind(AsyncStorage);
+      originals.mergeItem = AsyncStorage.mergeItem.bind(AsyncStorage);
+      originals.multiMerge = AsyncStorage.multiMerge ? AsyncStorage.multiMerge.bind(AsyncStorage) : null;
     } else {
       // v3: setMany/removeMany; merge API was removed (nothing to capture)
-      this.originalSetMany = AsyncStorage.setMany.bind(AsyncStorage);
-      this.originalRemoveMany = AsyncStorage.removeMany.bind(AsyncStorage);
+      originals.setMany = AsyncStorage.setMany.bind(AsyncStorage);
+      originals.removeMany = AsyncStorage.removeMany.bind(AsyncStorage);
     }
 
+    // Keep them reachable across a module re-evaluation, then adopt.
+    stashOriginals(originals);
+    this.adoptOriginals(originals);
+
     // Original methods stored successfully
     this.isInitialized = true;
     return true;

package/lib/module/storage/utils/MMKVInstanceRegistry.js

@@ -10,6 +10,14 @@
  * @since 1.0.0
  */
 
+// Static ESM import. This was previously a dynamic `require('./MMKVListener')`
+// inside register/unregister "to avoid a circular dependency" — but MMKVListener
+// imports only ./mmkvTypeDetection, never this file, so there is no cycle. The
+// require() form threw `ReferenceError: require is not defined` when this source
+// is bundled as ESM (the desktop dashboard imports it through Vite), crashing on
+// StorageInline unmount. A static import behaves identically on Metro and Vite.
+import { mmkvListener } from "./MMKVListener";
+
 /**
  * Type-safe representation of an MMKV instance.
  * Uses conditional typing to avoid hard dependency on react-native-mmkv.
@@ -161,10 +169,6 @@ export function registerMMKVInstance(id, instance, config) {
 
   // Add listener for real-time monitoring (CRITICAL: enables event emission)
   // v4: Use ONLY native listener (addOnValueChangedListener), skip method wrapping
-  // Import mmkvListener dynamically to avoid circular dependency
-  const {
-    mmkvListener
-  } = require('./MMKVListener');
   mmkvListener.addInstance(instance, id);
 }
 
@@ -186,9 +190,6 @@ export function registerMMKVInstance(id, instance, config) {
  */
 export function unregisterMMKVInstance(id) {
   // Remove listener first
-  const {
-    mmkvListener
-  } = require('./MMKVListener');
   mmkvListener.removeInstance(id);
 
   // Then remove from registry