@buoy-gg/storage 7.0.17 → 7.0.18

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

@@ -7,6 +7,7 @@ exports.useAsyncStorageKeys = useAsyncStorageKeys;
 var _react = require("react");
 var _asyncStorage = _interopRequireDefault(require("@react-native-async-storage/async-storage"));
 var _asyncStorageCompat = require("../utils/asyncStorageCompat");
+var _requiredStorageKeyScope = require("../utils/requiredStorageKeyScope");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 function useAsyncStorageKeys(requiredStorageKeys = []) {
   // State management
@@ -53,8 +54,9 @@ function useAsyncStorageKeys(requiredStorageKeys = []) {
           }
         }
 
-        // Check if this is a required key
+        // Check if this is a required key scoped to AsyncStorage
         const requiredConfig = requiredStorageKeys.find(req => {
+          if (!(0, _requiredStorageKeyScope.requiredKeyAppliesTo)(req, 'async')) return false;
           if (typeof req === 'string') return req === key;
           return req.key === key;
         });
@@ -64,9 +66,9 @@ function useAsyncStorageKeys(requiredStorageKeys = []) {
         if (requiredConfig) {
           if (parsedValue === undefined || parsedValue === null) {
             status = 'required_missing';
-          } else if (typeof requiredConfig === 'object' && 'expectedValue' in requiredConfig) {
+          } else if (typeof requiredConfig === 'object' && requiredConfig.expectedValue !== undefined) {
             status = parsedValue === requiredConfig.expectedValue ? 'required_present' : 'required_wrong_value';
-          } else if (typeof requiredConfig === 'object' && 'expectedType' in requiredConfig) {
+          } else if (typeof requiredConfig === 'object' && requiredConfig.expectedType !== undefined) {
             const actualType = parsedValue === null ? 'null' : typeof parsedValue;
             status = actualType.toLowerCase() === requiredConfig.expectedType.toLowerCase() ? 'required_present' : 'required_wrong_type';
           } else {
@@ -79,21 +81,22 @@ function useAsyncStorageKeys(requiredStorageKeys = []) {
           storageType: 'async',
           status,
           category: requiredConfig ? 'required' : 'optional',
-          ...(typeof requiredConfig === 'object' && 'expectedValue' in requiredConfig && {
+          ...(typeof requiredConfig === 'object' && requiredConfig.expectedValue !== undefined && {
             expectedValue: requiredConfig.expectedValue
           }),
-          ...(typeof requiredConfig === 'object' && 'expectedType' in requiredConfig && {
+          ...(typeof requiredConfig === 'object' && requiredConfig.expectedType !== undefined && {
             expectedType: requiredConfig.expectedType
           }),
-          ...(typeof requiredConfig === 'object' && 'description' in requiredConfig && {
+          ...(typeof requiredConfig === 'object' && requiredConfig.description !== undefined && {
             description: requiredConfig.description
           })
         };
         allStorageKeys.push(keyInfo);
       });
 
-      // 4. Add missing required keys
+      // 4. Add missing required keys (Async-scoped only)
       requiredStorageKeys.forEach(req => {
+        if (!(0, _requiredStorageKeyScope.requiredKeyAppliesTo)(req, 'async')) return;
         const key = typeof req === 'string' ? req : req.key;
         const exists = allStorageKeys.some(k => k.key === key);
         if (!exists) {
@@ -103,13 +106,13 @@ function useAsyncStorageKeys(requiredStorageKeys = []) {
             storageType: 'async',
             status: 'required_missing',
             category: 'required',
-            ...(typeof req === 'object' && 'expectedValue' in req && {
+            ...(typeof req === 'object' && req.expectedValue !== undefined && {
               expectedValue: req.expectedValue
             }),
-            ...(typeof req === 'object' && 'expectedType' in req && {
+            ...(typeof req === 'object' && req.expectedType !== undefined && {
               expectedType: req.expectedType
             }),
-            ...(typeof req === 'object' && 'description' in req && {
+            ...(typeof req === 'object' && req.description !== undefined && {
               description: req.description
             })
           });

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

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 exports.useMMKVKeys = useMMKVKeys;
 exports.useMultiMMKVKeys = useMultiMMKVKeys;
 var _react = require("react");
+var _requiredStorageKeyScope = require("../utils/requiredStorageKeyScope");
 var _mmkvTypeDetection = require("../utils/mmkvTypeDetection");
 /**
  * useMMKVKeys Hook
@@ -97,12 +98,12 @@ function useMMKVKeys(instance, instanceId, requiredStorageKeys = []) {
       // 1. Get all keys from MMKV (synchronous)
       const allKeys = instance.getAllKeys();
       if (!allKeys || allKeys.length === 0) {
-        // Still need to check for missing required keys
-        const missingRequiredKeys = requiredStorageKeys.map(req => {
+        // Still need to check for missing required keys scoped to MMKV
+        const missingRequiredKeys = requiredStorageKeys.filter(req => (0, _requiredStorageKeyScope.requiredKeyAppliesTo)(req, 'mmkv')).map(req => {
           const key = typeof req === 'string' ? req : req.key;
-          const description = typeof req === 'object' && 'description' in req ? req.description : undefined;
-          const expectedValue = typeof req === 'object' && 'expectedValue' in req ? req.expectedValue : undefined;
-          const expectedType = typeof req === 'object' && 'expectedType' in req ? req.expectedType : undefined;
+          const description = typeof req === 'object' ? req.description : undefined;
+          const expectedValue = typeof req === 'object' ? req.expectedValue : undefined;
+          const expectedType = typeof req === 'object' ? req.expectedType : undefined;
           return {
             key,
             value: undefined,
@@ -130,8 +131,9 @@ function useMMKVKeys(instance, instanceId, requiredStorageKeys = []) {
           type
         } = (0, _mmkvTypeDetection.detectMMKVType)(instance, key);
 
-        // Check if this is a required key
+        // Check if this is a required key scoped to MMKV
         const requiredConfig = requiredStorageKeys.find(req => {
+          if (!(0, _requiredStorageKeyScope.requiredKeyAppliesTo)(req, 'mmkv')) return false;
           if (typeof req === 'string') return req === key;
           return req.key === key;
         });
@@ -141,10 +143,10 @@ function useMMKVKeys(instance, instanceId, requiredStorageKeys = []) {
         if (requiredConfig) {
           if (value === undefined) {
             status = 'required_missing';
-          } else if (typeof requiredConfig === 'object' && 'expectedValue' in requiredConfig) {
+          } else if (typeof requiredConfig === 'object' && requiredConfig.expectedValue !== undefined) {
             // Value validation
             status = String(value) === String(requiredConfig.expectedValue) ? 'required_present' : 'required_wrong_value';
-          } else if (typeof requiredConfig === 'object' && 'expectedType' in requiredConfig) {
+          } else if (typeof requiredConfig === 'object' && requiredConfig.expectedType !== undefined) {
             // Type validation
             status = (0, _mmkvTypeDetection.isTypeMatch)(type, requiredConfig.expectedType) ? 'required_present' : 'required_wrong_type';
           } else {
@@ -163,13 +165,13 @@ function useMMKVKeys(instance, instanceId, requiredStorageKeys = []) {
           status,
           category: requiredConfig ? 'required' : 'optional',
           lastUpdated: new Date(),
-          ...(typeof requiredConfig === 'object' && 'expectedValue' in requiredConfig && {
+          ...(typeof requiredConfig === 'object' && requiredConfig.expectedValue !== undefined && {
             expectedValue: requiredConfig.expectedValue
           }),
-          ...(typeof requiredConfig === 'object' && 'expectedType' in requiredConfig && {
+          ...(typeof requiredConfig === 'object' && requiredConfig.expectedType !== undefined && {
             expectedType: requiredConfig.expectedType
           }),
-          ...(typeof requiredConfig === 'object' && 'description' in requiredConfig && {
+          ...(typeof requiredConfig === 'object' && requiredConfig.description !== undefined && {
             description: requiredConfig.description
           })
         };
@@ -178,6 +180,7 @@ function useMMKVKeys(instance, instanceId, requiredStorageKeys = []) {
 
       // 3. Add missing required keys that weren't found in storage
       requiredStorageKeys.forEach(req => {
+        if (!(0, _requiredStorageKeyScope.requiredKeyAppliesTo)(req, 'mmkv')) return;
         const key = typeof req === 'string' ? req : req.key;
         const exists = allStorageKeys.some(k => k.key === key);
         if (!exists) {
@@ -189,13 +192,13 @@ function useMMKVKeys(instance, instanceId, requiredStorageKeys = []) {
             instanceId,
             status: 'required_missing',
             category: 'required',
-            ...(typeof req === 'object' && 'expectedValue' in req && {
+            ...(typeof req === 'object' && req.expectedValue !== undefined && {
               expectedValue: req.expectedValue
             }),
-            ...(typeof req === 'object' && 'expectedType' in req && {
+            ...(typeof req === 'object' && req.expectedType !== undefined && {
               expectedType: req.expectedType
             }),
-            ...(typeof req === 'object' && 'description' in req && {
+            ...(typeof req === 'object' && req.description !== undefined && {
               description: req.description
             })
           });
@@ -284,6 +287,7 @@ function useMultiMMKVKeys(instances, requiredStorageKeys = []) {
             type
           } = (0, _mmkvTypeDetection.detectMMKVType)(instance, key);
           const requiredConfig = requiredStorageKeys.find(req => {
+            if (!(0, _requiredStorageKeyScope.requiredKeyAppliesTo)(req, 'mmkv')) return false;
             if (typeof req === 'string') return req === key;
             return req.key === key;
           });
@@ -291,9 +295,9 @@ function useMultiMMKVKeys(instances, requiredStorageKeys = []) {
           if (requiredConfig) {
             if (value === undefined) {
               status = 'required_missing';
-            } else if (typeof requiredConfig === 'object' && 'expectedValue' in requiredConfig) {
+            } else if (typeof requiredConfig === 'object' && requiredConfig.expectedValue !== undefined) {
               status = String(value) === String(requiredConfig.expectedValue) ? 'required_present' : 'required_wrong_value';
-            } else if (typeof requiredConfig === 'object' && 'expectedType' in requiredConfig) {
+            } else if (typeof requiredConfig === 'object' && requiredConfig.expectedType !== undefined) {
               status = (0, _mmkvTypeDetection.isTypeMatch)(type, requiredConfig.expectedType) ? 'required_present' : 'required_wrong_type';
             } else {
               status = 'required_present';
@@ -308,13 +312,13 @@ function useMultiMMKVKeys(instances, requiredStorageKeys = []) {
             status,
             category: requiredConfig ? 'required' : 'optional',
             lastUpdated: new Date(),
-            ...(typeof requiredConfig === 'object' && 'expectedValue' in requiredConfig && {
+            ...(typeof requiredConfig === 'object' && requiredConfig.expectedValue !== undefined && {
               expectedValue: requiredConfig.expectedValue
             }),
-            ...(typeof requiredConfig === 'object' && 'expectedType' in requiredConfig && {
+            ...(typeof requiredConfig === 'object' && requiredConfig.expectedType !== undefined && {
               expectedType: requiredConfig.expectedType
             }),
-            ...(typeof requiredConfig === 'object' && 'description' in requiredConfig && {
+            ...(typeof requiredConfig === 'object' && requiredConfig.description !== undefined && {
               description: requiredConfig.description
             })
           };
@@ -322,8 +326,9 @@ function useMultiMMKVKeys(instances, requiredStorageKeys = []) {
         });
       });
 
-      // Add missing required keys
+      // Add missing required keys scoped to MMKV
       requiredStorageKeys.forEach(req => {
+        if (!(0, _requiredStorageKeyScope.requiredKeyAppliesTo)(req, 'mmkv')) return;
         const key = typeof req === 'string' ? req : req.key;
         const exists = allStorageKeys.some(k => k.key === key);
         if (!exists) {
@@ -338,13 +343,13 @@ function useMultiMMKVKeys(instances, requiredStorageKeys = []) {
             instanceId: firstInstanceId,
             status: 'required_missing',
             category: 'required',
-            ...(typeof req === 'object' && 'expectedValue' in req && {
+            ...(typeof req === 'object' && req.expectedValue !== undefined && {
               expectedValue: req.expectedValue
             }),
-            ...(typeof req === 'object' && 'expectedType' in req && {
+            ...(typeof req === 'object' && req.expectedType !== undefined && {
               expectedType: req.expectedType
             }),
-            ...(typeof req === 'object' && 'description' in req && {
+            ...(typeof req === 'object' && req.description !== undefined && {
               description: req.description
             })
           });

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

@@ -3,7 +3,10 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.subscribeToStorageEvents = exports.storageEventStore = exports.onStorageEvent = exports.isStorageCapturing = exports.getStorageEvents = exports.clearStorageEvents = void 0;
+exports.batchPairsOf = batchPairsOf;
+exports.isStorageCapturing = exports.getStorageEvents = exports.clearStorageEvents = void 0;
+exports.isValueOnDevice = isValueOnDevice;
+exports.subscribeToStorageEvents = exports.storageEventStore = exports.onStorageEvent = void 0;
 var _sharedUi = require("@buoy-gg/shared-ui");
 var _AsyncStorageListener = require("../utils/AsyncStorageListener");
 var _MMKVListener = require("../utils/MMKVListener");
@@ -38,6 +41,35 @@ var _mmkvTypeDetection = require("../utils/mmkvTypeDetection");
  * millisecond timestamp), and React keys must be unique per render.
  */
 
+/** True when a field is the wire-form VALUE_ON_DEVICE marker. */
+function isValueOnDevice(value) {
+  return !!value && typeof value === "object" && value.__buoyValueOnDevice === true;
+}
+
+/**
+ * `pairs` / `prevPairs` are AsyncStorage-only — they carry the batch
+ * operations (multiSet / multiRemove / multiMerge / clear), and MMKV has no
+ * batch API, so its `data` has no such fields. Reading them off the
+ * `StorageEvent` union needs narrowing, and this is the one place that does
+ * it; writing them unconditionally would also graft meaningless keys onto
+ * every MMKV event on the wire.
+ */
+function batchPairsOf(event) {
+  if (event.storageType !== "async" || !event.data) return {};
+  return {
+    pairs: event.data.pairs,
+    prevPairs: event.data.prevPairs
+  };
+}
+function eventHasOnDeviceValues(event) {
+  const data = event.data;
+  if (!data) return false;
+  const {
+    pairs,
+    prevPairs
+  } = batchPairsOf(event);
+  return isValueOnDevice(data.value) || isValueOnDevice(data.prevValue) || isValueOnDevice(pairs) || isValueOnDevice(prevPairs);
+}
 let storageEventIdCounter = 0;
 function nextStorageEventId() {
   return `se-${Date.now()}-${++storageEventIdCounter}`;
@@ -210,6 +242,58 @@ class StorageEventStore extends _sharedUi.BaseEventStore {
   getEventsByType(storageType) {
     return this.events.filter(event => event.storageType === storageType);
   }
+
+  /**
+   * Replace the event list, keeping values a remote mirror already hydrated.
+   * Wire-form snapshots always carry VALUE_ON_DEVICE markers for oversized
+   * payloads; a later snapshot must not blank the detail pane (or wipe
+   * `prevValue` that time-travel undo needs).
+   */
+  replaceEvents(events) {
+    const hydrated = new Map();
+    for (const existing of this.events) {
+      if (!eventHasOnDeviceValues(existing)) {
+        hydrated.set(existing.id, existing);
+      }
+    }
+    const merged = events.map(incoming => {
+      const kept = hydrated.get(incoming.id);
+      if (!kept || !eventHasOnDeviceValues(incoming)) return incoming;
+      // Restore only the fields this event's storage type actually has, so an
+      // MMKV event never grows `pairs`/`prevPairs` it has no meaning for.
+      return {
+        ...incoming,
+        data: {
+          ...incoming.data,
+          value: kept.data?.value,
+          prevValue: kept.data?.prevValue,
+          ...batchPairsOf(kept)
+        }
+      };
+    });
+    super.replaceEvents(merged);
+  }
+
+  /**
+   * Hydrate one mirrored event with real values fetched on demand from the
+   * device via the adapter's `getEventDetail`. Remote-mirror (desktop) only.
+   */
+  hydrateEvent(event) {
+    const index = this.events.findIndex(e => e.id === event.id);
+    if (index === -1) return;
+    const current = this.events[index];
+    const next = this.events.slice();
+    next[index] = {
+      ...current,
+      ...event,
+      timestamp: current.timestamp,
+      data: {
+        ...current.data,
+        ...event.data
+      }
+    };
+    super.replaceEvents(next);
+  }
 }
 
 // Singleton instance

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

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.storageSyncAdapter = void 0;
+exports.storageSyncAdapter = exports.VALUE_ON_DEVICE = exports.SNAPSHOT_VALUE_INLINE_LIMIT = exports.SNAPSHOT_EVENTS_BUDGET = void 0;
 var _asyncStorage = _interopRequireDefault(require("@react-native-async-storage/async-storage"));
 var _sharedUi = require("@buoy-gg/shared-ui");
 var _asyncStorageCompat = require("../utils/asyncStorageCompat");
@@ -14,6 +14,148 @@ var _MMKVInstanceRegistry = require("../utils/MMKVInstanceRegistry");
 var _mmkvTypeDetection = require("../utils/mmkvTypeDetection");
 var _SecureStoreRegistry = require("../utils/SecureStoreRegistry");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * Sentinel used in WIRE-FORM snapshots in place of oversized values.
+ * Storage events, MMKV browse dumps, and SecureStore dumps all reuse this
+ * marker. Dashboards fetch the real payload via `getEventDetail` / `mmkv.get`
+ * / `secure.get`.
+ */
+const VALUE_ON_DEVICE = exports.VALUE_ON_DEVICE = Object.freeze({
+  __buoyValueOnDevice: true,
+  note: "Value stays on the device — fetched on demand via getEventDetail / mmkv.get / secure.get."
+});
+
+/** Max serialized bytes of one storage value on the list snapshot. */
+const SNAPSHOT_VALUE_INLINE_LIMIT = exports.SNAPSHOT_VALUE_INLINE_LIMIT = 16 * 1024;
+
+/**
+ * Total inline budget for one snapshot's event list, held under the emit
+ * layer's 2MB so a snapshot is never DROPPED (a drop leaves the whole panel
+ * stale). Per-value caps alone don't get there: the store keeps 500 events, so
+ * 500 writes of an individually-legal 9KB value still total ~4.7MB. Newest
+ * events keep their values inline; once the budget is spent, older ones
+ * degrade to metadata + fetch-on-demand.
+ */
+const SNAPSHOT_EVENTS_BUDGET = exports.SNAPSHOT_EVENTS_BUDGET = 1.25 * 1024 * 1024;
+const MAX_EVENT_DETAIL_BYTES = 8 * 1024 * 1024;
+function toWireValue(value) {
+  if (value === undefined) return value;
+  return (0, _sharedUi.isOverWireBudget)(value, SNAPSHOT_VALUE_INLINE_LIMIT) ? VALUE_ON_DEVICE : value;
+}
+
+/**
+ * Apply `map` to every payload field an event carries, preserving object
+ * identity when nothing changed (the desktop mirror feeds these into effect
+ * dependencies, so a fresh object per snapshot would re-run them).
+ *
+ * The cast is deliberate and load-bearing: the wire form intentionally puts a
+ * marker OBJECT where the domain type declares a string, because the real
+ * value stayed on the device. `StorageEvent` describes on-device truth; this
+ * is its wire projection.
+ */
+function mapEventValues(event, map) {
+  const data = event.data;
+  if (!data) return event;
+  const value = map(data.value);
+  const prevValue = map(data.prevValue);
+  const batch = (0, _storageEventStore.batchPairsOf)(event);
+  const pairs = map(batch.pairs);
+  const prevPairs = map(batch.prevPairs);
+  if (value === data.value && prevValue === data.prevValue && pairs === batch.pairs && prevPairs === batch.prevPairs) {
+    return event;
+  }
+  return {
+    ...event,
+    data: {
+      ...data,
+      value,
+      prevValue,
+      // Only AsyncStorage events have these; see batchPairsOf.
+      ...(event.storageType === "async" ? {
+        pairs,
+        prevPairs
+      } : {})
+    }
+  };
+}
+function capDetailValue(value) {
+  if (value === undefined) return value;
+  if (!(0, _sharedUi.isOverWireBudget)(value, MAX_EVENT_DETAIL_BYTES)) return value;
+  return (0, _sharedUi.isJsonSerializable)(value) ? {
+    __buoyTruncated: true,
+    note: `Exceeds the ${MAX_EVENT_DETAIL_BYTES / (1024 * 1024)}MB detail limit — inspect it on-device.`
+  } : VALUE_ON_DEVICE;
+}
+
+/** One event's wire form plus its measured cost, so the budget pass is free. */
+
+/**
+ * Per-event wire cache. The store never mutates an event in place — `addEvent`
+ * prepends and `hydrateEvent` replaces — so keying on identity is correct and
+ * self-invalidating. Without it every value is re-measured on all ~5 snapshots
+ * per second for as long as it stays in the list, which for storage means
+ * re-walking megabytes of strings per tick.
+ */
+const wireCache = new WeakMap();
+const strippedCache = new WeakMap();
+function wireFor(event) {
+  const cached = wireCache.get(event);
+  if (cached) return cached;
+  let entry;
+  try {
+    const wire = mapEventValues(event, toWireValue);
+    entry = {
+      event: wire,
+      bytes: (0, _sharedUi.approxJsonSize)(wire, SNAPSHOT_EVENTS_BUDGET).bytes
+    };
+  } catch {
+    // A hostile getter can blow up the walk itself. Degrading this ONE event
+    // beats letting getSnapshot throw and taking the whole panel with it.
+    const wire = mapEventValues(event, () => VALUE_ON_DEVICE);
+    entry = {
+      event: wire,
+      bytes: 1024
+    };
+  }
+  wireCache.set(event, entry);
+  return entry;
+}
+
+/** Metadata-only form for the tail of the list once the budget is spent. */
+function strippedFor(event) {
+  const cached = strippedCache.get(event);
+  if (cached) return cached;
+  const wire = mapEventValues(event, v => v === undefined ? undefined : VALUE_ON_DEVICE);
+  const entry = {
+    event: wire,
+    bytes: (0, _sharedUi.approxJsonSize)(wire, SNAPSHOT_EVENTS_BUDGET).bytes
+  };
+  strippedCache.set(event, entry);
+  return entry;
+}
+
+/**
+ * Spend the snapshot budget newest-first. The store keeps events newest-first,
+ * so the developer keeps full detail on what they are actually looking at and
+ * the tail degrades rather than the whole panel being dropped.
+ */
+function fitEventsToBudget(events) {
+  const out = new Array(events.length);
+  let spent = 0;
+  for (let i = 0; i < events.length; i++) {
+    const full = wireFor(events[i]);
+    if (spent + full.bytes <= SNAPSHOT_EVENTS_BUDGET) {
+      out[i] = full.event;
+      spent += full.bytes;
+    } else {
+      const lean = strippedFor(events[i]);
+      out[i] = lean.event;
+      spent += lean.bytes;
+    }
+  }
+  return out;
+}
+
 /** One MMKV entry in a `mmkv.snapshot` result. */
 
 /** One MMKV instance in a `mmkv.snapshot` result. */
@@ -51,22 +193,53 @@ function assertMMKVWritable(instanceId) {
  *
  * The `async.*` actions mirror the AsyncStorage API so the desktop dashboard
  * can proxy its browse/edit mode against the device's real storage.
+ *
+ * v2: oversized / unserializable event values are replaced with
+ * VALUE_ON_DEVICE. Dashboards fetch them via `getEventDetail`.
  */
 const storageSyncAdapter = exports.storageSyncAdapter = {
-  version: 1,
+  // v3: a total snapshot budget, so a burst of individually-legal values
+  // degrades the oldest events instead of the emit layer dropping the panel.
+  version: 3,
   // Strip Buoy's OWN devtool keys (@react_buoy*, @buoy*, buoy-*, legacy) at the
   // source so no sync client (desktop, MCP, raw socket) ever sees them as if
   // they were app data — matching the tools' default key filters, but
   // authoritative instead of UI-only.
-  getSnapshot: () => _storageEventStore.storageEventStore.getEvents().filter(e => {
+  getSnapshot: () => fitEventsToBudget(_storageEventStore.storageEventStore.getEvents().filter(e => {
     const key = e.data?.key;
     return !(typeof key === "string" && (0, _sharedUi.isDevToolsStorageKey)(key));
-  }),
+  })),
   subscribe: onChange => _storageEventStore.storageEventStore.subscribeToEvents(onChange),
   actions: {
     clearEvents: () => {
       _storageEventStore.storageEventStore.clearEvents();
     },
+    /**
+     * On-demand detail: one event's real value/prevValue/pairs.
+     * The per-snapshot stream stays payload-light; this is the explicit,
+     * size-guarded channel for the detail pane (and for time-travel undo,
+     * which needs `prevValue`).
+     */
+    getEventDetail: params => {
+      const {
+        id
+      } = params ?? {};
+      if (!id) return {
+        found: false,
+        reason: "missing id"
+      };
+      const event = _storageEventStore.storageEventStore.getEvents().find(e => e.id === id);
+      if (!event) return {
+        found: false,
+        reason: "unknown id"
+      };
+      const detailed = mapEventValues(event, capDetailValue);
+      return {
+        found: true,
+        id,
+        event: detailed
+      };
+    },
     /** 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) ──
@@ -163,7 +336,7 @@ const storageSyncAdapter = exports.storageSyncAdapter = {
           } = (0, _mmkvTypeDetection.detectMMKVType)(instance, key);
           return {
             key,
-            value,
+            value: toWireValue(value),
             valueType
           };
         });
@@ -177,6 +350,41 @@ const storageSyncAdapter = exports.storageSyncAdapter = {
         entries
       };
     }),
+    /**
+     * On-demand MMKV value. `mmkv.snapshot` omits oversized strings so a
+     * browse poll cannot blow the action-result budget; this is the
+     * size-guarded channel for one key.
+     */
+    "mmkv.get": params => {
+      const {
+        instanceId,
+        key
+      } = params ?? {};
+      if (!instanceId || !key) {
+        return {
+          found: false,
+          reason: "missing instanceId/key"
+        };
+      }
+      const registered = _MMKVInstanceRegistry.mmkvInstanceRegistry.get(instanceId);
+      if (!registered) {
+        return {
+          found: false,
+          reason: "unknown instance"
+        };
+      }
+      const {
+        value,
+        type: valueType
+      } = (0, _mmkvTypeDetection.detectMMKVType)(registered.instance, key);
+      return {
+        found: true,
+        instanceId,
+        key,
+        value: capDetailValue(value),
+        valueType
+      };
+    },
     "mmkv.set": params => {
       const {
         instanceId,
@@ -236,7 +444,7 @@ const storageSyncAdapter = exports.storageSyncAdapter = {
           description,
           keychainService: options.keychainService,
           requireAuthentication: options.requireAuthentication ?? false,
-          value
+          value: value == null ? value : toWireValue(value)
         });
       }
       return result;

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

@@ -0,0 +1,17 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.requiredKeyAppliesTo = requiredKeyAppliesTo;
+/**
+ * Whether a required-key declaration should be enforced by a given backend
+ * hook. Explicit `storageType` wins; bare string keys default to AsyncStorage
+ * (the historical zero-config backend). Objects without `storageType` still
+ * apply to every backend — matching prior behavior for apps that never set it.
+ */
+function requiredKeyAppliesTo(req, backend) {
+  if (typeof req === "string") return backend === "async";
+  if (req.storageType) return req.storageType === backend;
+  return true;
+}