@buoy-gg/shared-ui 7.0.33 → 7.0.34

package/lib/commonjs/JsModal.js

@@ -606,7 +606,6 @@ const JsModalComponent = ({
   // ============================================================================
   // REFS for values we need to track
   // ============================================================================
-  const isExternallyControlled = !!externalAnimatedHeight;
   const effectiveMaxHeight = maxHeight || SCREEN.height - insets.top;
 
   // Mode toggle handler
@@ -728,29 +727,57 @@ const JsModalComponent = ({
   // ============================================================================
   // EFFECT: Visibility Animations - All using native driver!
   // ============================================================================
+  const snapVisibility = shown => {
+    if (shown) {
+      if (mode === "bottomSheet") {
+        bottomSheetTranslateY.setValue(0);
+      } else {
+        floatingScale.setValue(1);
+        floatingPosition.setValue({
+          x: currentDimensionsRef.current.left,
+          y: currentDimensionsRef.current.top
+        });
+      }
+      visibilityProgress.setValue(1);
+    } else {
+      if (mode === "bottomSheet") {
+        bottomSheetTranslateY.setValue(SCREEN.height);
+      }
+      visibilityProgress.setValue(0);
+    }
+  };
+
+  /**
+   * Snap DURING RENDER when `visible` flips, not only in the effect below.
+   *
+   * These values drive the sheet's opacity/translate through the native
+   * driver. The React commit for a `visible` change carries whatever the
+   * JS-side values are at render time — the OLD, hidden ones when the snap
+   * only happens in the effect — and on Fabric that commit's mount can land
+   * on the main thread AFTER the effect's native `setValue`, overwriting it.
+   * The Animated node then says "shown" while the UIView sits at opacity 0,
+   * until some unrelated re-render commits the JS-side values again. That
+   * is how "restore tool A: nothing; restore tool B: A appears; hide B: now
+   * B appears" happened — every restore was one commit behind.
+   *
+   * Setting the values before the render's props are computed makes the
+   * commit and the native node agree, whichever lands last. `setValue` is
+   * idempotent, so a re-run render is harmless.
+   */
+  const snappedVisibleRef = (0, _react.useRef)(null);
+  if (INSTANT_MODAL_ENTRANCE && snappedVisibleRef.current !== visible) {
+    snappedVisibleRef.current = visible;
+    snapVisibility(visible);
+  }
   (0, _react.useEffect)(() => {
     // Visibility effect
     let openAnimation = null;
     let closeAnimation = null;
     if (INSTANT_MODAL_ENTRANCE) {
-      // Snap to the final state — no animation in either direction.
-      if (visible) {
-        if (mode === "bottomSheet") {
-          bottomSheetTranslateY.setValue(0);
-        } else {
-          floatingScale.setValue(1);
-          floatingPosition.setValue({
-            x: currentDimensionsRef.current.left,
-            y: currentDimensionsRef.current.top
-          });
-        }
-        visibilityProgress.setValue(1);
-      } else {
-        if (mode === "bottomSheet") {
-          bottomSheetTranslateY.setValue(SCREEN.height);
-        }
-        visibilityProgress.setValue(0);
-      }
+      // Snap to the final state — no animation in either direction. The
+      // render-phase snap above already did this for a `visible` flip; this
+      // re-applies it for a `mode` change while shown.
+      snapVisibility(visible);
       return;
     }
     if (visible) {
@@ -915,8 +942,15 @@ const JsModalComponent = ({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [benchMotion, visible]);
   const bottomSheetPanResponder = (0, _react.useMemo)(() => _reactNative.PanResponder.create({
-    onStartShouldSetPanResponder: () => !isExternallyControlled && mode === "bottomSheet",
-    onMoveShouldSetPanResponder: (evt, gestureState) => !isExternallyControlled && mode === "bottomSheet" && Math.abs(gestureState.dy) > 3,
+    // An external `animatedHeight` used to disable this responder
+    // outright ("externally controlled"), which left Ask Buoy's sheet —
+    // the one host that passes one, for its peek animation — with a
+    // header that could not be dragged in bottom-sheet mode. The move
+    // and release handlers below already write every height into the
+    // external value, so the host and the finger share one number; the
+    // grab just has to stop whatever the host is animating first.
+    onStartShouldSetPanResponder: () => mode === "bottomSheet",
+    onMoveShouldSetPanResponder: (evt, gestureState) => mode === "bottomSheet" && Math.abs(gestureState.dy) > 3,
     onPanResponderTerminationRequest: () => false,
     onPanResponderGrant: evt => {
       setIsResizing(true);
@@ -928,6 +962,7 @@ const JsModalComponent = ({
       animatedBottomPosition.stopAnimation(val => {
         currentHeightRef.current = val;
       });
+      externalAnimatedHeight?.stopAnimation();
       bottomSheetTranslateY.stopAnimation();
     },
     onPanResponderMove: evt => {
@@ -974,7 +1009,7 @@ const JsModalComponent = ({
       setIsResizing(false);
       // snap back to the last stable height if you want; otherwise no-op
     }
-  }), [mode, isExternallyControlled, minHeight, effectiveMaxHeight, animatedBottomPosition, externalAnimatedHeight, bottomSheetTranslateY, visibilityProgress, onClose]);
+  }), [mode, minHeight, effectiveMaxHeight, animatedBottomPosition, externalAnimatedHeight, bottomSheetTranslateY, visibilityProgress, onClose]);
 
   // ============================================================================
   // CREATE RESIZE HANDLER: For 4-corner resize in floating mode (fixed geometry)

package/lib/commonjs/hooks/index.js

@@ -21,12 +21,30 @@ Object.defineProperty(exports, "logDeviceInfo", {
     return _useDeviceInfo.logDeviceInfo;
   }
 });
+Object.defineProperty(exports, "resetPersistedStateCache", {
+  enumerable: true,
+  get: function () {
+    return _usePersistedState.resetPersistedStateCache;
+  }
+});
+Object.defineProperty(exports, "useChangeLog", {
+  enumerable: true,
+  get: function () {
+    return _useChangeLog.useChangeLog;
+  }
+});
 Object.defineProperty(exports, "useDeviceInfo", {
   enumerable: true,
   get: function () {
     return _useDeviceInfo.useDeviceInfo;
   }
 });
+Object.defineProperty(exports, "useEventStoreEvents", {
+  enumerable: true,
+  get: function () {
+    return _useEventStoreEvents.useEventStoreEvents;
+  }
+});
 Object.defineProperty(exports, "useFilterManager", {
   enumerable: true,
   get: function () {
@@ -45,7 +63,15 @@ Object.defineProperty(exports, "useSafeAreaInsets", {
     return _useSafeAreaInsets.useSafeAreaInsets;
   }
 });
+Object.defineProperty(exports, "useSubscribedValue", {
+  enumerable: true,
+  get: function () {
+    return _useChangeLog.useSubscribedValue;
+  }
+});
 var _useFilterManager = require("./useFilterManager.js");
 var _usePersistedState = require("./usePersistedState.js");
+var _useChangeLog = require("./useChangeLog.js");
+var _useEventStoreEvents = require("./useEventStoreEvents.js");
 var _useSafeAreaInsets = require("./useSafeAreaInsets.js");
 var _useDeviceInfo = require("./useDeviceInfo.js");

package/lib/commonjs/hooks/safe-area-impl.js

@@ -7,7 +7,7 @@ exports.useNativeSafeAreaInsets = exports.safeAreaType = exports.hasSafeAreaPack
 /**
  * Auto-generated safe area implementation
  * Detected: none
- * Generated at: 2026-09-02T23:25:39.783Z
+ * Generated at: 2026-09-04T01:21:28.486Z
  *
  * DO NOT EDIT - This file is generated by scripts/detect-safe-area.js
  *

package/lib/commonjs/hooks/useChangeLog.js

@@ -0,0 +1,55 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useChangeLog = useChangeLog;
+exports.useSubscribedValue = useSubscribedValue;
+var _react = require("react");
+/**
+ * React bindings for `ChangeLog` — what useReduxActions, useZustandStateChanges
+ * and useJotaiAtomChanges each re-derived: seed state from the log, subscribe
+ * for the lifetime of the component, hold a filter, memoize the filtered
+ * list, and expose clear / pause / lookup.
+ *
+ * Tool-specific stats and registries (stores, atoms) compose on top — see
+ * `useSubscribedValue` for the registry half.
+ */
+
+function useChangeLog(log, options = {}) {
+  const [items, setItems] = (0, _react.useState)(() => log.getAll());
+  const [filter, setFilter] = (0, _react.useState)(() => options.initialFilter ?? {});
+  const [isEnabled, setIsEnabled] = (0, _react.useState)(() => log.getEnabled());
+  (0, _react.useEffect)(() => log.subscribe(setItems), [log]);
+  const filterItems = options.filterItems;
+  const filteredItems = (0, _react.useMemo)(() => filterItems ? filterItems(items, filter) : items, [items, filter, filterItems]);
+  const clear = (0, _react.useCallback)(() => {
+    log.clear();
+  }, [log]);
+  const toggleCapture = (0, _react.useCallback)(() => {
+    const next = !isEnabled;
+    log.setEnabled(next);
+    setIsEnabled(next);
+  }, [log, isEnabled]);
+  const getById = (0, _react.useCallback)(id => log.getById(id), [log]);
+  return {
+    items,
+    filteredItems,
+    filter,
+    setFilter,
+    isEnabled,
+    toggleCapture,
+    clear,
+    getById
+  };
+}
+
+/**
+ * Hold a value that a store pushes through a `(value) => void` listener —
+ * a registry of stores, atoms, sources. Seeded synchronously from `read`.
+ */
+function useSubscribedValue(read, subscribe) {
+  const [value, setValue] = (0, _react.useState)(read);
+  (0, _react.useEffect)(() => subscribe(setValue), [subscribe]);
+  return value;
+}

package/lib/commonjs/hooks/useEventStoreEvents.js

@@ -0,0 +1,65 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useEventStoreEvents = useEventStoreEvents;
+var _react = require("react");
+/**
+ * React bindings for a `BaseEventStore` — what useRouteEvents and
+ * useStorageEvents each hand-rolled: subscribe while enabled (which
+ * auto-starts the store's capture), coalesce bursts onto one animation
+ * frame so a storm of writes is one commit instead of one per emission,
+ * select/limit the list, and report whether capture is live.
+ */
+
+function useEventStoreEvents(store, options = {}) {
+  const {
+    enabled = true,
+    maxEvents = 500,
+    select
+  } = options;
+  const [events, setEvents] = (0, _react.useState)([]);
+  // Tracked locally so it updates reactively with the subscription.
+  const [isActive, setIsActive] = (0, _react.useState)(enabled);
+  (0, _react.useEffect)(() => {
+    if (!enabled) {
+      setIsActive(false);
+      return;
+    }
+
+    // Frame-coalesced: bursts land as ONE commit per frame instead of one
+    // per emission — the dominant live-churn cost measured on the network
+    // tool (tool-bench 2026-07-06).
+    let rafId = null;
+    let pending = null;
+    const unsubscribe = store.subscribeToEvents(all => {
+      pending = all;
+      if (rafId != null) return;
+      rafId = requestAnimationFrame(() => {
+        rafId = null;
+        if (!pending) return;
+        let next = pending;
+        pending = null;
+        if (select) next = select(next);
+        if (next.length > maxEvents) next = next.slice(0, maxEvents);
+        setEvents(next);
+      });
+    });
+    setIsActive(true);
+    return () => {
+      unsubscribe();
+      if (rafId != null) cancelAnimationFrame(rafId);
+      // Not setting isActive=false here: a dependency change re-subscribes
+      // immediately, and that is not "stopped".
+    };
+  }, [store, enabled, maxEvents, select]);
+  const clearEvents = (0, _react.useCallback)(() => {
+    store.clearEvents();
+  }, [store]);
+  return {
+    events,
+    clearEvents,
+    isActive
+  };
+}

package/lib/commonjs/hooks/usePersistedState.js

@@ -3,6 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+exports.resetPersistedStateCache = resetPersistedStateCache;
 exports.usePersistedState = usePersistedState;
 var _react = require("react");
 var _persistentStorage = require("../utils/persistentStorage.js");
@@ -13,25 +14,43 @@ var _persistentStorage = require("../utils/persistentStorage.js");
  */
 const hydratedCache = new Map();
 
+/** The two calls a backend needs. `persistentStorage` and AsyncStorage both fit. */
+
+function defaultParse(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * `useState` persisted through `persistentStorage` (FileSystem → AsyncStorage
  * → memory). Replaces the load-then-`hasLoaded`-guard `useEffect` pattern
  * every tool used to hand-roll.
  *
- * Values are JSON-serialized; the default is returned until hydration
- * completes (subsequent mounts of the same key hydrate synchronously from an
- * in-memory cache). The third tuple element reports hydration so callers can
- * defer writes that must not clobber a not-yet-loaded value.
+ * Values are JSON-serialized by default; the default is returned until
+ * hydration completes (subsequent mounts of the same key hydrate synchronously
+ * from an in-memory cache). The third tuple element reports hydration so
+ * callers can defer writes that must not clobber a not-yet-loaded value.
  *
  * ```tsx
  * const [tab, setTab, tabHydrated] = usePersistedState("@react_buoy_custom_flags_tab", "flags");
+ *
+ * // A Set, stored as an array:
+ * const [pins, setPins] = usePersistedState(key, new Set<string>(), {
+ *   parse: (raw) => new Set(JSON.parse(raw) as string[]),
+ *   serialize: (set) => JSON.stringify([...set]),
+ * });
  * ```
  */
-function usePersistedState(key, defaultValue) {
+function usePersistedState(key, defaultValue, options = {}) {
   const [value, setValue] = (0, _react.useState)(() => hydratedCache.has(key) ? hydratedCache.get(key) : defaultValue);
   const [hydrated, setHydrated] = (0, _react.useState)(() => hydratedCache.has(key));
   const keyRef = (0, _react.useRef)(key);
   keyRef.current = key;
+  const optionsRef = (0, _react.useRef)(options);
+  optionsRef.current = options;
   (0, _react.useEffect)(() => {
     if (hydratedCache.has(key)) {
       setValue(hydratedCache.get(key));
@@ -39,17 +58,22 @@ function usePersistedState(key, defaultValue) {
       return;
     }
     let cancelled = false;
-    _persistentStorage.persistentStorage.getItem(key).then(raw => {
+    const storage = optionsRef.current.storage ?? _persistentStorage.persistentStorage;
+    const parse = optionsRef.current.parse ?? defaultParse;
+    storage.getItem(key).then(raw => {
       if (cancelled) return;
       if (raw != null) {
+        let parsed;
         try {
-          const parsed = JSON.parse(raw);
-          hydratedCache.set(key, parsed);
-          setValue(parsed);
+          parsed = parse(raw);
         } catch {
           // Corrupt payload — fall back to the default and let the next
           // write repair it.
         }
+        if (parsed !== undefined) {
+          hydratedCache.set(key, parsed);
+          setValue(parsed);
+        }
       }
       setHydrated(true);
     }).catch(() => {
@@ -63,9 +87,20 @@ function usePersistedState(key, defaultValue) {
     setValue(prev => {
       const resolved = typeof next === "function" ? next(prev) : next;
       hydratedCache.set(keyRef.current, resolved);
-      _persistentStorage.persistentStorage.setItem(keyRef.current, JSON.stringify(resolved)).catch(() => {});
+      const storage = optionsRef.current.storage ?? _persistentStorage.persistentStorage;
+      const serialize = optionsRef.current.serialize ?? JSON.stringify;
+      try {
+        storage.setItem(keyRef.current, serialize(resolved)).catch(() => {});
+      } catch {
+        // Unserializable value — keep it in memory, skip the write.
+      }
       return resolved;
     });
   }, []);
   return [value, set, hydrated];
+}
+
+/** Test seam: forget every hydrated value. */
+function resetPersistedStateCache() {
+  hydratedCache.clear();
 }

package/lib/commonjs/index.js

@@ -52,10 +52,25 @@ var _exportNames = {
   getSafeCurrentPathname: true,
   getSafeCurrentRoute: true,
   isExpoRouterAvailable: true,
+  PREVIEW_ITEM_RENDER_BYTE_LIMIT: true,
+  createRestoreScope: true,
+  emptyRestoreResult: true,
+  failedRestore: true,
+  skippedRestore: true,
+  classifyPreviewItem: true,
+  wontApply: true,
+  unionKeys: true,
+  entityColor: true,
+  formatValuePreview: true,
+  shallowDiffSummary: true,
   isPlainObjectUtil: true,
   useSafeAreaInsets: true,
   useFilterManager: true,
   usePersistedState: true,
+  resetPersistedStateCache: true,
+  useChangeLog: true,
+  useSubscribedValue: true,
+  useEventStoreEvents: true,
   useDeviceInfo: true,
   getDeviceInfo: true,
   logDeviceInfo: true,
@@ -222,6 +237,12 @@ Object.defineProperty(exports, "NightSwitch", {
     return _primitives.NightSwitch;
   }
 });
+Object.defineProperty(exports, "PREVIEW_ITEM_RENDER_BYTE_LIMIT", {
+  enumerable: true,
+  get: function () {
+    return _snapshotProviderKit.PREVIEW_ITEM_RENDER_BYTE_LIMIT;
+  }
+});
 Object.defineProperty(exports, "ProBadge", {
   enumerable: true,
   get: function () {
@@ -282,6 +303,18 @@ Object.defineProperty(exports, "buoyColors", {
     return _gameUIColors.buoyColors;
   }
 });
+Object.defineProperty(exports, "classifyPreviewItem", {
+  enumerable: true,
+  get: function () {
+    return _snapshotProviderKit.classifyPreviewItem;
+  }
+});
+Object.defineProperty(exports, "createRestoreScope", {
+  enumerable: true,
+  get: function () {
+    return _snapshotProviderKit.createRestoreScope;
+  }
+});
 Object.defineProperty(exports, "dialColors", {
   enumerable: true,
   get: function () {
@@ -294,6 +327,24 @@ Object.defineProperty(exports, "displayValue", {
     return _index3.displayValue;
   }
 });
+Object.defineProperty(exports, "emptyRestoreResult", {
+  enumerable: true,
+  get: function () {
+    return _snapshotProviderKit.emptyRestoreResult;
+  }
+});
+Object.defineProperty(exports, "entityColor", {
+  enumerable: true,
+  get: function () {
+    return _stateTools.entityColor;
+  }
+});
+Object.defineProperty(exports, "failedRestore", {
+  enumerable: true,
+  get: function () {
+    return _snapshotProviderKit.failedRestore;
+  }
+});
 Object.defineProperty(exports, "flattenObject", {
   enumerable: true,
   get: function () {
@@ -312,6 +363,12 @@ Object.defineProperty(exports, "formatValue", {
     return _index3.formatValue;
   }
 });
+Object.defineProperty(exports, "formatValuePreview", {
+  enumerable: true,
+  get: function () {
+    return _stateTools.formatValuePreview;
+  }
+});
 Object.defineProperty(exports, "freeKeyRaises", {
   enumerable: true,
   get: function () {
@@ -546,6 +603,12 @@ Object.defineProperty(exports, "reloadApp", {
     return _index3.reloadApp;
   }
 });
+Object.defineProperty(exports, "resetPersistedStateCache", {
+  enumerable: true,
+  get: function () {
+    return _index1.resetPersistedStateCache;
+  }
+});
 Object.defineProperty(exports, "resolveEffectiveTier", {
   enumerable: true,
   get: function () {
@@ -576,6 +639,18 @@ Object.defineProperty(exports, "setRenderCaptureProvider", {
     return _index3.setRenderCaptureProvider;
   }
 });
+Object.defineProperty(exports, "shallowDiffSummary", {
+  enumerable: true,
+  get: function () {
+    return _stateTools.shallowDiffSummary;
+  }
+});
+Object.defineProperty(exports, "skippedRestore", {
+  enumerable: true,
+  get: function () {
+    return _snapshotProviderKit.skippedRestore;
+  }
+});
 Object.defineProperty(exports, "subscribeToStateSnapshotProviders", {
   enumerable: true,
   get: function () {
@@ -612,12 +687,30 @@ Object.defineProperty(exports, "truncateText", {
     return _index3.truncateText;
   }
 });
+Object.defineProperty(exports, "unionKeys", {
+  enumerable: true,
+  get: function () {
+    return _snapshotProviderKit.unionKeys;
+  }
+});
+Object.defineProperty(exports, "useChangeLog", {
+  enumerable: true,
+  get: function () {
+    return _index1.useChangeLog;
+  }
+});
 Object.defineProperty(exports, "useDeviceInfo", {
   enumerable: true,
   get: function () {
     return _index1.useDeviceInfo;
   }
 });
+Object.defineProperty(exports, "useEventStoreEvents", {
+  enumerable: true,
+  get: function () {
+    return _index1.useEventStoreEvents;
+  }
+});
 Object.defineProperty(exports, "useFeatureGate", {
   enumerable: true,
   get: function () {
@@ -684,6 +777,18 @@ Object.defineProperty(exports, "useSafeSegments", {
     return _index3.useSafeSegments;
   }
 });
+Object.defineProperty(exports, "useSubscribedValue", {
+  enumerable: true,
+  get: function () {
+    return _index1.useSubscribedValue;
+  }
+});
+Object.defineProperty(exports, "wontApply", {
+  enumerable: true,
+  get: function () {
+    return _snapshotProviderKit.wontApply;
+  }
+});
 var _index = require("./ui/index.js");
 Object.keys(_index).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;
@@ -720,6 +825,42 @@ Object.keys(_wireBudget).forEach(function (key) {
     }
   });
 });
+var _wireForm = require("./sync/wireForm.js");
+Object.keys(_wireForm).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _wireForm[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _wireForm[key];
+    }
+  });
+});
+var _toolSyncAdapter = require("./sync/toolSyncAdapter.js");
+Object.keys(_toolSyncAdapter).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _toolSyncAdapter[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _toolSyncAdapter[key];
+    }
+  });
+});
+var _defineTool = require("./tools/defineTool.js");
+Object.keys(_defineTool).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _defineTool[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _defineTool[key];
+    }
+  });
+});
 var _toolActionRegistry = require("./sync/toolActionRegistry.js");
 Object.keys(_toolActionRegistry).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;
@@ -745,6 +886,8 @@ Object.keys(_toolUiBridge).forEach(function (key) {
   });
 });
 var _index3 = require("./utils/index.js");
+var _snapshotProviderKit = require("./utils/snapshotProviderKit.js");
+var _stateTools = require("./utils/stateTools.js");
 var _index4 = require("./utils/formatting/index.js");
 Object.keys(_index4).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;

package/lib/commonjs/storage/definePersistedSetting.js

@@ -0,0 +1,67 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.definePersistedSetting = definePersistedSetting;
+var _persistentStorage = require("../utils/persistentStorage.js");
+/**
+ * definePersistedSetting — the `load / save / clear` triple every tool wrote
+ * for its module-level settings (copy settings, HUD prefs, JS TOP prefs, …).
+ *
+ * Contract, the same one all of them followed:
+ *  - `load()` never throws and never returns a partial object: the stored
+ *    value is merged OVER the defaults so fields added in a later release
+ *    get their default instead of `undefined`, then `sanitize` gets the last
+ *    word (drop values the UI no longer offers, coerce types).
+ *  - `save()` and `clear()` are best-effort; persistence is optional.
+ *  - `loadOrNull()` distinguishes "nothing saved yet" from the defaults, for
+ *    callers that treat first launch differently.
+ */
+
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function definePersistedSetting(key, defaults, options = {}) {
+  const storage = options.storage ?? _persistentStorage.persistentStorage;
+  const parse = options.parse ?? (raw => JSON.parse(raw));
+  const serialize = options.serialize ?? (value => JSON.stringify(value));
+  function resolve(stored) {
+    const merged = isPlainObject(defaults) && isPlainObject(stored) ? {
+      ...defaults,
+      ...stored
+    } : stored;
+    return options.sanitize ? options.sanitize(merged, stored) : merged;
+  }
+  async function loadOrNull() {
+    try {
+      const raw = await storage.getItem(key);
+      if (raw == null || raw === "") return null;
+      return resolve(parse(raw));
+    } catch {
+      return null;
+    }
+  }
+  return {
+    key,
+    defaults,
+    loadOrNull,
+    async load() {
+      return (await loadOrNull()) ?? defaults;
+    },
+    async save(value) {
+      try {
+        await storage.setItem(key, serialize(value));
+      } catch {
+        // Persistence is best-effort.
+      }
+    },
+    async clear() {
+      try {
+        await storage.removeItem(key);
+      } catch {
+        // Persistence is best-effort.
+      }
+    }
+  };
+}