@buoy-gg/storage 7.0.4 → 7.0.6

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

@@ -12,6 +12,23 @@ var _SecureStoreRegistry = require("../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.
  *
@@ -19,22 +36,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.
  */
-function useSecureStoreKeys() {
+function useSecureStoreKeys(options = {}) {
+  const {
+    pollMs = DEFAULT_POLL_MS
+  } = options;
   const [storageKeys, setStorageKeys] = (0, _react.useState)([]);
   const [isLoading, setIsLoading] = (0, _react.useState)(true);
   const [error, setError] = (0, _react.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 = (0, _react.useRef)(signature([]));
+  const hasLoadedRef = (0, _react.useRef)(false);
+  const inFlightRef = (0, _react.useRef)(false);
+  const commit = (0, _react.useCallback)(keys => {
+    const next = signature(keys);
+    if (next === signatureRef.current) return;
+    signatureRef.current = next;
+    setStorageKeys(keys);
+  }, []);
   const fetchSecureStoreData = (0, _react.useCallback)(async () => {
-    const module = _SecureStoreRegistry.secureStoreRegistry.getModule();
-    const entries = _SecureStoreRegistry.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.secureStoreRegistry.getModule();
+      const entries = _SecureStoreRegistry.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) {
@@ -82,19 +124,32 @@ 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.
   (0, _react.useEffect)(() => {
     fetchSecureStoreData();
-  }, [fetchSecureStoreData]);
+    const unsubscribe = _SecureStoreRegistry.secureStoreRegistry.subscribe(() => {
+      fetchSecureStoreData();
+    });
+    if (pollMs <= 0) return unsubscribe;
+    const interval = setInterval(fetchSecureStoreData, pollMs);
+    return () => {
+      unsubscribe();
+      clearInterval(interval);
+    };
+  }, [fetchSecureStoreData, pollMs]);
   return {
     storageKeys,
     isLoading,

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

@@ -0,0 +1,107 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useTreeDraft = useTreeDraft;
+var _react = require("react");
+var _dataViewer = require("@buoy-gg/shared-ui/dataViewer");
+/**
+ * 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.
+ */
+
+/**
+ * @param liveValue  the value as storage currently holds it (already parsed)
+ * @param save       persists the serialized draft; rejecting keeps edit mode open
+ */
+function useTreeDraft(liveValue, save) {
+  const [draft, setDraft] = (0, _react.useState)(undefined);
+  const [isEditing, setIsEditing] = (0, _react.useState)(false);
+  const [isSaving, setIsSaving] = (0, _react.useState)(false);
+  const [error, setError] = (0, _react.useState)(null);
+  const [selectPath, setSelectPath] = (0, _react.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] = (0, _react.useState)("");
+  const value = isEditing && draft !== undefined ? draft : liveValue;
+  const isDirty = isEditing && JSON.stringify(draft) !== baseline;
+  const begin = (0, _react.useCallback)(() => {
+    setDraft(liveValue);
+    setBaseline(JSON.stringify(liveValue));
+    setSelectPath(undefined);
+    setError(null);
+    setIsEditing(true);
+  }, [liveValue]);
+  const apply = (0, _react.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 => (0, _dataViewer.applyJsonOp)(prev, op));
+    const next = (0, _dataViewer.selectionPathAfterOp)(op);
+    if (next !== undefined) setSelectPath(next);
+  }, []);
+  const selectAt = (0, _react.useCallback)(path => {
+    setSelectPath(path);
+  }, []);
+  const reset = (0, _react.useCallback)(() => {
+    setIsEditing(false);
+    setDraft(undefined);
+    setSelectPath(undefined);
+    setError(null);
+  }, []);
+  const commit = (0, _react.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/commonjs/storage/index.js

@@ -11,6 +11,10 @@ var _exportNames = {
   StorageKeySection: true,
   StorageBrowserMode: true,
   StorageEventsSection: true,
+  STORAGE_OPS: true,
+  storageOpOf: true,
+  storageOpDot: true,
+  isInitialScan: true,
   StorageEventCard: true,
   getValueType: true,
   StorageEventDetailContent: true,
@@ -43,6 +47,12 @@ Object.defineProperty(exports, "MMKVInstanceSelector", {
     return _MMKVInstanceSelector.MMKVInstanceSelector;
   }
 });
+Object.defineProperty(exports, "STORAGE_OPS", {
+  enumerable: true,
+  get: function () {
+    return _storageOps.STORAGE_OPS;
+  }
+});
 Object.defineProperty(exports, "StorageBrowserMode", {
   enumerable: true,
   get: function () {
@@ -121,6 +131,12 @@ Object.defineProperty(exports, "getValueType", {
     return _StorageEventCard.getValueType;
   }
 });
+Object.defineProperty(exports, "isInitialScan", {
+  enumerable: true,
+  get: function () {
+    return _storageOps.isInitialScan;
+  }
+});
 Object.defineProperty(exports, "isStorageCapturing", {
   enumerable: true,
   get: function () {
@@ -139,6 +155,18 @@ Object.defineProperty(exports, "storageEventStore", {
     return _storageEventStore.storageEventStore;
   }
 });
+Object.defineProperty(exports, "storageOpDot", {
+  enumerable: true,
+  get: function () {
+    return _storageOps.storageOpDot;
+  }
+});
+Object.defineProperty(exports, "storageOpOf", {
+  enumerable: true,
+  get: function () {
+    return _storageOps.storageOpOf;
+  }
+});
 Object.defineProperty(exports, "subscribeToStorageEvents", {
   enumerable: true,
   get: function () {
@@ -194,6 +222,7 @@ var _StorageKeyStats = require("./components/StorageKeyStats");
 var _StorageKeySection = require("./components/StorageKeySection");
 var _StorageBrowserMode = require("./components/StorageBrowserMode");
 var _StorageEventsSection = require("./components/StorageEventsSection");
+var _storageOps = require("./utils/storageOps");
 var _StorageEventCard = require("./components/StorageEventCard");
 var _StorageEventDetailContent = require("./components/StorageEventDetailContent");
 var _useAsyncStorageKeys = require("./hooks/useAsyncStorageKeys");

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

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

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

@@ -9,6 +9,7 @@ var _sharedUi = require("@buoy-gg/shared-ui");
 var _asyncStorageCompat = require("../utils/asyncStorageCompat");
 var _storageEventStore = require("../stores/storageEventStore");
 var _clearAllStorage = require("../utils/clearAllStorage");
+var _storageTimeTravelUtils = require("../utils/storageTimeTravelUtils");
 var _MMKVInstanceRegistry = require("../utils/MMKVInstanceRegistry");
 var _mmkvTypeDetection = require("../utils/mmkvTypeDetection");
 var _SecureStoreRegistry = require("../utils/SecureStoreRegistry");
@@ -17,6 +18,28 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
 
 /** 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.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
@@ -46,6 +69,58 @@ const storageSyncAdapter = exports.storageSyncAdapter = {
     },
     /** Clears all app storage keys, preserving dev tools settings. */
     clearAppStorage: () => (0, _clearAllStorage.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.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 (!(0, _storageTimeTravelUtils.canUndo)(asyncEvent)) {
+        throw new Error(`Event "${id}" (${asyncEvent.action}) has no previous value captured, so it cannot be undone`);
+      }
+      await (0, _storageTimeTravelUtils.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.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 (0, _storageTimeTravelUtils.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
@@ -108,16 +183,16 @@ const storageSyncAdapter = exports.storageSyncAdapter = {
         key,
         value
       } = params;
-      _MMKVInstanceRegistry.mmkvInstanceRegistry.get(instanceId)?.instance.set(key, value);
+      assertMMKVWritable(instanceId).set(key, value);
     },
     "mmkv.remove": params => {
       const {
         instanceId,
         key
       } = params;
-      const instance = _MMKVInstanceRegistry.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).
@@ -132,6 +207,40 @@ const storageSyncAdapter = exports.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.secureStoreRegistry.getModule();
+      const entries = _SecureStoreRegistry.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
@@ -143,6 +252,19 @@ const storageSyncAdapter = exports.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.secureStoreRegistry.setValue(key, value);
+    },
     "secure.delete": params => _SecureStoreRegistry.secureStoreRegistry.deleteValue(params.key)
   }
 };

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

@@ -9,6 +9,28 @@ var _asyncStorageCompat = require("./asyncStorageCompat");
 
 // 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
 
 /**
@@ -93,6 +115,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
    *
@@ -109,29 +150,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 (_asyncStorageCompat.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 = _asyncStorageCompat.asyncStorage.setItem.bind(_asyncStorageCompat.asyncStorage);
-    this.originalRemoveItem = _asyncStorageCompat.asyncStorage.removeItem.bind(_asyncStorageCompat.asyncStorage);
-    this.originalClear = _asyncStorageCompat.asyncStorage.clear.bind(_asyncStorageCompat.asyncStorage);
+    const originals = {
+      setItem: _asyncStorageCompat.asyncStorage.setItem.bind(_asyncStorageCompat.asyncStorage),
+      removeItem: _asyncStorageCompat.asyncStorage.removeItem.bind(_asyncStorageCompat.asyncStorage),
+      clear: _asyncStorageCompat.asyncStorage.clear.bind(_asyncStorageCompat.asyncStorage),
+      mergeItem: null,
+      multiSet: null,
+      multiRemove: null,
+      multiMerge: null,
+      setMany: null,
+      removeMany: null
+    };
     if (_asyncStorageCompat.asyncStorageCaps.hasLegacyMultiApi) {
       // v2: multiSet/multiRemove + merge API
-      this.originalMultiSet = _asyncStorageCompat.asyncStorage.multiSet.bind(_asyncStorageCompat.asyncStorage);
-      this.originalMultiRemove = _asyncStorageCompat.asyncStorage.multiRemove.bind(_asyncStorageCompat.asyncStorage);
-      this.originalMergeItem = _asyncStorageCompat.asyncStorage.mergeItem.bind(_asyncStorageCompat.asyncStorage);
-      this.originalMultiMerge = _asyncStorageCompat.asyncStorage.multiMerge ? _asyncStorageCompat.asyncStorage.multiMerge.bind(_asyncStorageCompat.asyncStorage) : null;
+      originals.multiSet = _asyncStorageCompat.asyncStorage.multiSet.bind(_asyncStorageCompat.asyncStorage);
+      originals.multiRemove = _asyncStorageCompat.asyncStorage.multiRemove.bind(_asyncStorageCompat.asyncStorage);
+      originals.mergeItem = _asyncStorageCompat.asyncStorage.mergeItem.bind(_asyncStorageCompat.asyncStorage);
+      originals.multiMerge = _asyncStorageCompat.asyncStorage.multiMerge ? _asyncStorageCompat.asyncStorage.multiMerge.bind(_asyncStorageCompat.asyncStorage) : null;
     } else {
       // v3: setMany/removeMany; merge API was removed (nothing to capture)
-      this.originalSetMany = _asyncStorageCompat.asyncStorage.setMany.bind(_asyncStorageCompat.asyncStorage);
-      this.originalRemoveMany = _asyncStorageCompat.asyncStorage.removeMany.bind(_asyncStorageCompat.asyncStorage);
+      originals.setMany = _asyncStorageCompat.asyncStorage.setMany.bind(_asyncStorageCompat.asyncStorage);
+      originals.removeMany = _asyncStorageCompat.asyncStorage.removeMany.bind(_asyncStorageCompat.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/commonjs/storage/utils/MMKVInstanceRegistry.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 exports.mmkvInstanceRegistry = void 0;
 exports.registerMMKVInstance = registerMMKVInstance;
 exports.unregisterMMKVInstance = unregisterMMKVInstance;
+var _MMKVListener = require("./MMKVListener");
 /**
  * MMKV Instance Registry
  *
@@ -16,6 +17,13 @@ exports.unregisterMMKVInstance = unregisterMMKVInstance;
  * @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.
+
 /**
  * Type-safe representation of an MMKV instance.
  * Uses conditional typing to avoid hard dependency on react-native-mmkv.
@@ -167,11 +175,7 @@ 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);
+  _MMKVListener.mmkvListener.addInstance(instance, id);
 }
 
 /**
@@ -192,10 +196,7 @@ function registerMMKVInstance(id, instance, config) {
  */
 function unregisterMMKVInstance(id) {
   // Remove listener first
-  const {
-    mmkvListener
-  } = require('./MMKVListener');
-  mmkvListener.removeInstance(id);
+  _MMKVListener.mmkvListener.removeInstance(id);
 
   // Then remove from registry
   mmkvInstanceRegistry.unregister(id);