@buoy-gg/jotai 7.0.33 → 7.0.34

package/lib/commonjs/jotai/hooks/useJotaiAtomChanges.js

@@ -5,78 +5,62 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.useJotaiAtomChanges = useJotaiAtomChanges;
 var _react = require("react");
+var _sharedUi = require("@buoy-gg/shared-ui");
 var _jotaiStateStore = require("../utils/jotaiStateStore");
 /**
  * Hook for consuming Jotai atom changes from the store
  *
- * Mirrors useZustandStateChanges.ts from @buoy-gg/zustand
+ * The subscribe / filter / pause / clear plumbing is shared `useChangeLog`;
+ * this file owns the jotai-specific filter, stats and atom registry.
  */
 
+function filterChanges(changes, filter) {
+  let filtered = changes;
+  if (filter.searchText) {
+    const search = filter.searchText.toLowerCase();
+    filtered = filtered.filter(c => c.atomLabel.toLowerCase().includes(search) || c.valuePreview.toLowerCase().includes(search) || c.changedKeys.some(k => k.toLowerCase().includes(search)));
+  }
+  if (filter.atomLabels && filter.atomLabels.length > 0) {
+    filtered = filtered.filter(c => filter.atomLabels.includes(c.atomLabel));
+  }
+  if (filter.onlyWithChanges) {
+    filtered = filtered.filter(c => c.hasValueChange);
+  }
+  return filtered;
+}
+const readAtoms = () => _jotaiStateStore.jotaiStateStore.getAtoms();
+const subscribeToAtoms = listener => _jotaiStateStore.jotaiStateStore.subscribeToAtoms(listener);
 function useJotaiAtomChanges() {
-  const [atomChanges, setAtomChanges] = (0, _react.useState)(() => _jotaiStateStore.jotaiStateStore.getAtomChanges());
-  const [atoms, setAtoms] = (0, _react.useState)(() => _jotaiStateStore.jotaiStateStore.getAtoms());
-  const [filter, setFilter] = (0, _react.useState)({});
-  const [isEnabled, setIsEnabled] = (0, _react.useState)(() => _jotaiStateStore.jotaiStateStore.getEnabled());
-  (0, _react.useEffect)(() => {
-    const unsubChanges = _jotaiStateStore.jotaiStateStore.subscribe(newChanges => {
-      setAtomChanges(newChanges);
-    });
-    const unsubAtoms = _jotaiStateStore.jotaiStateStore.subscribeToAtoms(newAtoms => {
-      setAtoms(newAtoms);
-    });
-    return () => {
-      unsubChanges();
-      unsubAtoms();
-    };
-  }, []);
-  const filteredChanges = (0, _react.useMemo)(() => {
-    let filtered = atomChanges;
-    if (filter.searchText) {
-      const search = filter.searchText.toLowerCase();
-      filtered = filtered.filter(c => c.atomLabel.toLowerCase().includes(search) || c.valuePreview.toLowerCase().includes(search) || c.changedKeys.some(k => k.toLowerCase().includes(search)));
-    }
-    if (filter.atomLabels && filter.atomLabels.length > 0) {
-      filtered = filtered.filter(c => filter.atomLabels.includes(c.atomLabel));
-    }
-    if (filter.onlyWithChanges) {
-      filtered = filtered.filter(c => c.hasValueChange);
-    }
-    return filtered;
-  }, [atomChanges, filter]);
+  const log = (0, _sharedUi.useChangeLog)(_jotaiStateStore.jotaiStateStore, {
+    filterItems: filterChanges
+  });
+  const atoms = (0, _sharedUi.useSubscribedValue)(readAtoms, subscribeToAtoms);
   const stats = (0, _react.useMemo)(() => {
-    const total = atomChanges.length;
-    const withChanges = atomChanges.filter(c => c.hasValueChange).length;
+    const total = log.items.length;
+    const withChanges = log.items.filter(c => c.hasValueChange).length;
     return {
       totalChanges: total,
       changesWithValueChange: withChanges,
       changesWithoutValueChange: total - withChanges,
       atomCount: atoms.length
     };
-  }, [atomChanges, atoms]);
+  }, [log.items, atoms]);
   const atomLabels = (0, _react.useMemo)(() => {
     return _jotaiStateStore.jotaiStateStore.getUniqueAtomLabels();
   }, [atoms]);
-  const clearChanges = (0, _react.useCallback)(() => {
-    _jotaiStateStore.jotaiStateStore.clearAtomChanges();
-  }, []);
-  const toggleCapture = (0, _react.useCallback)(() => {
-    const newEnabled = !isEnabled;
-    _jotaiStateStore.jotaiStateStore.setEnabled(newEnabled);
-    setIsEnabled(newEnabled);
-  }, [isEnabled]);
   const getChangeById = (0, _react.useCallback)(id => {
     return _jotaiStateStore.jotaiStateStore.getAtomChangeById(id);
   }, []);
   return {
-    atomChanges,
-    filteredChanges,
-    filter,
-    setFilter,
+    atomChanges: log.items,
+    filteredChanges: log.filteredItems,
+    filter: log.filter,
+    setFilter: log.setFilter,
     stats,
     atoms,
-    clearChanges,
-    isEnabled,
-    toggleCapture,
+    clearChanges: log.clear,
+    isEnabled: log.isEnabled,
+    toggleCapture: log.toggleCapture,
     atomLabels,
     getChangeById
   };

package/lib/commonjs/jotai/sync/jotaiSyncAdapter.js

@@ -11,36 +11,21 @@ var _sharedUi = require("@buoy-gg/shared-ui");
  * Same hazard as redux/zustand: up to 200 changes × 2 values on every
  * snapshot. Dashboards fetch values via `getChangeDetail`.
  */
-const VALUE_ON_DEVICE = exports.VALUE_ON_DEVICE = Object.freeze({
-  __buoyValueOnDevice: true,
-  note: "Atom values stay on the device — fetched on demand via getChangeDetail / getAtomValue."
-});
-const MAX_CHANGE_DETAIL_BYTES = 8 * 1024 * 1024;
-const MAX_WIRE_PAYLOAD_BYTES = 16 * 1024;
+const VALUE_ON_DEVICE = exports.VALUE_ON_DEVICE = (0, _sharedUi.onDeviceMarker)("Value", "Atom values stay on the device — fetched on demand via getChangeDetail / getAtomValue.");
 /**
  * Per-change wire cache — the store prepends and never mutates a recorded
  * change, so identity is a correct, self-invalidating key.
  */
-const changeCache = new WeakMap();
-function toWireChange(change) {
-  const cached = changeCache.get(change);
-  if (cached) return cached;
-  const wire = {
-    ...change,
-    prevValue: VALUE_ON_DEVICE,
-    nextValue: VALUE_ON_DEVICE
-  };
-  changeCache.set(change, wire);
-  return wire;
-}
-function toWireValue(value) {
-  return (0, _sharedUi.isOverWireBudget)(value, MAX_WIRE_PAYLOAD_BYTES) ? VALUE_ON_DEVICE : value;
-}
+const toWireChange = (0, _sharedUi.memoByIdentity)(change => ({
+  ...change,
+  prevValue: VALUE_ON_DEVICE,
+  nextValue: VALUE_ON_DEVICE
+}));
+const toWireValue = value => (0, _sharedUi.toWire)(value, VALUE_ON_DEVICE);
 
 /**
  * Sync adapter for the jotai tool, consumed by @buoy-gg/external-sync's
- * `useExternalSync` (structurally matches its ToolSyncAdapter interface so
- * this package doesn't need a dependency on it).
+ * `useExternalSync`.
  *
  * Atom changes are captured by watchAtoms(), independent of whether a
  * dashboard is watching — subscribing here only streams what the store
@@ -52,7 +37,7 @@ function toWireValue(value) {
  * Dashboards fetch values via `getChangeDetail`. Oversized / unserializable
  * `atoms[].currentValue` uses the same marker and is fetched via `getAtomValue`.
  */
-const jotaiSyncAdapter = exports.jotaiSyncAdapter = {
+const jotaiSyncAdapter = exports.jotaiSyncAdapter = (0, _sharedUi.createSyncAdapter)({
   version: 2,
   getSnapshot: () => ({
     changes: _jotaiStateStore.jotaiStateStore.getAtomChanges().map(toWireChange),
@@ -61,14 +46,7 @@ const jotaiSyncAdapter = exports.jotaiSyncAdapter = {
       currentValue: toWireValue(atom.currentValue)
     }))
   }),
-  subscribe: onChange => {
-    const unsubscribeChanges = _jotaiStateStore.jotaiStateStore.subscribe(onChange);
-    const unsubscribeAtoms = _jotaiStateStore.jotaiStateStore.subscribeToAtoms(onChange);
-    return () => {
-      unsubscribeChanges();
-      unsubscribeAtoms();
-    };
-  },
+  subscribe: [onChange => _jotaiStateStore.jotaiStateStore.subscribe(onChange), onChange => _jotaiStateStore.jotaiStateStore.subscribeToAtoms(onChange)],
   actions: {
     clearEvents: () => {
       _jotaiStateStore.jotaiStateStore.clearAtomChanges();
@@ -78,31 +56,10 @@ const jotaiSyncAdapter = exports.jotaiSyncAdapter = {
      * The per-snapshot stream stays value-free; this is the explicit,
      * size-guarded channel for the detail pane.
      */
-    getChangeDetail: params => {
-      const {
-        id
-      } = params ?? {};
-      if (!id) return {
-        found: false,
-        reason: "missing id"
-      };
-      const change = _jotaiStateStore.jotaiStateStore.getAtomChangeById(id);
-      if (!change) return {
-        found: false,
-        reason: "unknown id"
-      };
-      const cappedNote = {
-        __buoyTruncated: true,
-        note: `Exceeds the ${MAX_CHANGE_DETAIL_BYTES / (1024 * 1024)}MB detail limit — inspect it on-device.`
-      };
-      const cap = value => (0, _sharedUi.isOverWireBudget)(value, MAX_CHANGE_DETAIL_BYTES) ? cappedNote : value;
-      return {
-        found: true,
-        id,
-        prevValue: cap(change.prevValue),
-        nextValue: cap(change.nextValue)
-      };
-    },
+    getChangeDetail: (0, _sharedUi.detailByIdAction)(id => _jotaiStateStore.jotaiStateStore.getAtomChangeById(id), (change, cap) => ({
+      prevValue: cap(change.prevValue),
+      nextValue: cap(change.nextValue)
+    })),
     /**
      * On-demand current value for one atom. Wire-form snapshots replace
      * oversized / unserializable `currentValue` with VALUE_ON_DEVICE.
@@ -110,7 +67,7 @@ const jotaiSyncAdapter = exports.jotaiSyncAdapter = {
     getAtomValue: params => {
       const {
         label
-      } = params ?? {};
+      } = (0, _sharedUi.readParams)(params);
       if (!label) return {
         found: false,
         reason: "missing label"
@@ -126,10 +83,6 @@ const jotaiSyncAdapter = exports.jotaiSyncAdapter = {
       } catch {
         currentValue = undefined;
       }
-      const cappedNote = {
-        __buoyTruncated: true,
-        note: `Exceeds the ${MAX_CHANGE_DETAIL_BYTES / (1024 * 1024)}MB detail limit — inspect it on-device.`
-      };
       try {
         JSON.stringify(currentValue);
       } catch {
@@ -142,7 +95,7 @@ const jotaiSyncAdapter = exports.jotaiSyncAdapter = {
       return {
         found: true,
         label,
-        currentValue: (0, _sharedUi.isOverWireBudget)(currentValue, MAX_CHANGE_DETAIL_BYTES) ? cappedNote : currentValue
+        currentValue: (0, _sharedUi.capDetail)(currentValue, _sharedUi.WIRE_DETAIL_LIMIT_BYTES)
       };
     },
     /**
@@ -155,7 +108,7 @@ const jotaiSyncAdapter = exports.jotaiSyncAdapter = {
       const {
         includeValues = false,
         limit
-      } = params ?? {};
+      } = (0, _sharedUi.readParams)(params);
       const all = _jotaiStateStore.jotaiStateStore.getAtoms();
       const capped = typeof limit === "number" && limit > 0 ? all.slice(0, limit) : all;
       const atoms = capped.map(a => {
@@ -188,9 +141,9 @@ const jotaiSyncAdapter = exports.jotaiSyncAdapter = {
       const {
         label,
         value
-      } = params ?? {};
+      } = (0, _sharedUi.readParams)(params);
       if (!label) throw new Error("setAtom requires a `label`");
       _jotaiStateStore.jotaiStateStore.setAtomValue(label, value);
     }
   }
-};
+});

package/lib/commonjs/jotai/utils/jotaiStateStore.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.jotaiStateStore = void 0;
+var _sharedUi = require("@buoy-gg/shared-ui");
 /**
  * Jotai state store — captures and stores Jotai atom changes
  *
@@ -40,44 +41,7 @@ const ATOM_COLORS = {
   filter: "#84CC16" // lime
 };
 function getAtomColor(label) {
-  const lower = label.toLowerCase();
-  if (ATOM_COLORS[lower]) return ATOM_COLORS[lower];
-  for (const [key, color] of Object.entries(ATOM_COLORS)) {
-    if (lower.includes(key)) return color;
-  }
-
-  // Generate consistent hex from name hash
-  const hash = label.split("").reduce((acc, char) => acc + char.charCodeAt(0), 0);
-  const hue = hash * 137 % 360;
-  const s = 0.7;
-  const l = 0.6;
-  const c = (1 - Math.abs(2 * l - 1)) * s;
-  const x = c * (1 - Math.abs(hue / 60 % 2 - 1));
-  const m = l - c / 2;
-  let r = 0,
-    g = 0,
-    b = 0;
-  if (hue < 60) {
-    r = c;
-    g = x;
-  } else if (hue < 120) {
-    r = x;
-    g = c;
-  } else if (hue < 180) {
-    g = c;
-    b = x;
-  } else if (hue < 240) {
-    g = x;
-    b = c;
-  } else if (hue < 300) {
-    r = x;
-    b = c;
-  } else {
-    r = c;
-    b = x;
-  }
-  const toHex = v => Math.round((v + m) * 255).toString(16).padStart(2, "0");
-  return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+  return (0, _sharedUi.entityColor)(label, ATOM_COLORS);
 }
 
 // ============================================
@@ -85,97 +49,25 @@ function getAtomColor(label) {
 // ============================================
 
 function formatValuePreview(value, maxLength = 40) {
-  if (value === undefined) return "undefined";
-  if (value === null) return "null";
-  try {
-    if (typeof value === "function") return "(fn)";
-    if (typeof value === "string") {
-      return value.length > maxLength ? `"${value.slice(0, maxLength - 3)}..."` : `"${value}"`;
-    }
-    if (typeof value === "number" || typeof value === "boolean") {
-      return String(value);
-    }
-    if (Array.isArray(value)) {
-      if (value.length === 0) return "[]";
-      const preview = JSON.stringify(value);
-      return preview.length > maxLength ? `[${value.length} items]` : preview;
-    }
-    if (typeof value === "object") {
-      const keys = Object.keys(value);
-      if (keys.length === 0) return "{}";
-      const preview = JSON.stringify(value);
-      if (preview.length <= maxLength) return preview;
-      return `{ ${keys.length} keys }`;
-    }
-    return String(value).slice(0, maxLength);
-  } catch {
-    return "[complex]";
-  }
-}
-function getValueDiffSummary(prevValue, nextValue) {
-  if (prevValue === nextValue) {
-    return {
-      summary: "no change",
-      changedKeys: [],
-      changedCount: 0
-    };
-  }
-  if (typeof prevValue !== "object" || typeof nextValue !== "object" || prevValue === null || nextValue === null) {
-    return {
-      summary: "changed",
-      changedKeys: [],
-      changedCount: 0
-    };
-  }
-  const prevKeys = Object.keys(prevValue);
-  const nextKeys = Object.keys(nextValue);
-  const added = nextKeys.filter(k => !prevKeys.includes(k));
-  const removed = prevKeys.filter(k => !nextKeys.includes(k));
-  const changed = [];
-  for (const key of prevKeys) {
-    if (nextKeys.includes(key) && prevValue[key] !== nextValue[key]) {
-      changed.push(key);
-    }
-  }
-  const allChangedKeys = [...added, ...removed, ...changed];
-  const parts = [];
-  if (added.length > 0) parts.push(`+${added.length}`);
-  if (removed.length > 0) parts.push(`-${removed.length}`);
-  if (changed.length > 0) parts.push(`~${changed.length}`);
-  const total = allChangedKeys.length;
-  if (parts.length === 0) {
-    return {
-      summary: "nested change",
-      changedKeys: [],
-      changedCount: 0
-    };
-  }
-  return {
-    summary: `${parts.join(" ")} ${total === 1 ? "key" : "keys"}`,
-    changedKeys: allChangedKeys,
-    changedCount: total
-  };
+  return (0, _sharedUi.formatValuePreview)(value, {
+    maxLength,
+    functionLabel: "(fn)"
+  });
 }
+const getValueDiffSummary = _sharedUi.shallowDiffSummary;
 
 // ============================================
 // Jotai State Store
 // ============================================
 
-class JotaiStateStore {
-  atomChanges = [];
+class JotaiStateStore extends _sharedUi.ChangeLog {
   atoms = new Map();
-  listeners = new Set();
   atomListeners = new Set();
-  clearListeners = new Set();
-  maxChanges = 200;
-  idCounter = 0;
-  isEnabled = true;
-  captureSuppressed = false;
 
   // ---- Change Tracking ----
 
   addAtomChange(params) {
-    if (!this.isEnabled || this.captureSuppressed) return;
+    if (!this.canRecord()) return;
     const {
       atomLabel,
       prevValue,
@@ -190,7 +82,7 @@ class JotaiStateStore {
     } = getValueDiffSummary(prevValue, nextValue);
     const valuePreview = formatValuePreview(nextValue);
     const change = {
-      id: `${Date.now()}-${++this.idCounter}`,
+      id: this.nextId(),
       atomLabel,
       timestamp: Date.now(),
       prevValue,
@@ -203,7 +95,7 @@ class JotaiStateStore {
       valuePreview,
       isSlowUpdate: false
     };
-    this.atomChanges = [change, ...this.atomChanges].slice(0, this.maxChanges);
+    this.push(change);
     const atomInfo = this.atoms.get(atomLabel);
     if (atomInfo) {
       atomInfo.changeCount++;
@@ -212,54 +104,21 @@ class JotaiStateStore {
     this.notifyAtomListeners();
   }
   getAtomChanges() {
-    return [...this.atomChanges];
+    return this.getAll();
   }
   getAtomChangeById(id) {
-    return this.atomChanges.find(c => c.id === id);
+    return this.getById(id);
   }
   clearAtomChanges() {
-    this.atomChanges = [];
     for (const atom of this.atoms.values()) {
       atom.changeCount = 0;
     }
-    this.notifyListeners();
+    this.clear();
     this.notifyAtomListeners();
-    this.clearListeners.forEach(listener => {
-      try {
-        listener();
-      } catch {
-        // Ignore listener errors
-      }
-    });
-  }
-
-  /**
-   * Listen for clearAtomChanges() calls. Used in remote mirror mode to
-   * forward a clear performed in the dashboard UI to the synced device.
-   */
-  onClear(listener) {
-    this.clearListeners.add(listener);
-    return () => {
-      this.clearListeners.delete(listener);
-    };
   }
 
   // ---- Remote Mirror Mode ----
 
-  /**
-   * Permanently suppress local capture. Use when this store acts as a mirror
-   * of a remote device's atom changes (e.g. the desktop dashboard): data
-   * arrives via replaceFromSnapshot() and local watchers must never record.
-   */
-  disableCapture() {
-    this.captureSuppressed = true;
-  }
-
-  /** Whether the store is in remote mirror mode (capture suppressed). */
-  isCaptureSuppressed() {
-    return this.captureSuppressed;
-  }
-
   /**
    * Serializable snapshot of the tracked atoms (registry metadata plus each
    * atom's current value). Used by the sync adapter on the device side —
@@ -290,18 +149,18 @@ class JotaiStateStore {
    * freezes the mirror.
    */
   replaceFromSnapshot(changes, atomSnapshots) {
-    if (!this.isEnabled) return;
+    if (!this.getEnabled()) return;
 
     // Preserve values a remote mirror already hydrated — wire-form snapshots
     // always carry markers, and a later snapshot must not blank the detail pane.
     const hydrated = new Map();
-    for (const existing of this.atomChanges) {
+    for (const existing of this.items) {
       const prev = existing.prevValue;
       if (!prev || prev.__buoyValueOnDevice !== true) {
         hydrated.set(existing.id, existing);
       }
     }
-    this.atomChanges = changes.slice(0, this.maxChanges).map(change => {
+    const merged = changes.slice(0, this.max).map(change => {
       const kept = hydrated.get(change.id);
       const incoming = change.prevValue;
       return kept && incoming?.__buoyValueOnDevice === true ? {
@@ -339,7 +198,7 @@ class JotaiStateStore {
         writeKind: snapshot.writeKind
       }];
     }));
-    this.notifyListeners();
+    this.setItems(merged);
     this.notifyAtomListeners();
   }
 
@@ -348,13 +207,7 @@ class JotaiStateStore {
    * device via the adapter's `getChangeDetail`. Remote-mirror (desktop) only.
    */
   hydrateChange(id, patch) {
-    const index = this.atomChanges.findIndex(c => c.id === id);
-    if (index === -1) return;
-    this.atomChanges = [...this.atomChanges.slice(0, index), {
-      ...this.atomChanges[index],
-      ...patch
-    }, ...this.atomChanges.slice(index + 1)];
-    this.notifyListeners();
+    this.hydrateById(id, patch);
   }
 
   /**
@@ -418,7 +271,7 @@ class JotaiStateStore {
   // ---- Filtering ----
 
   filterAtomChanges(filter) {
-    let filtered = [...this.atomChanges];
+    let filtered = this.getAll();
     if (filter.searchText) {
       const search = filter.searchText.toLowerCase();
       filtered = filtered.filter(c => c.atomLabel.toLowerCase().includes(search) || c.valuePreview.toLowerCase().includes(search) || c.changedKeys.some(k => k.toLowerCase().includes(search)));
@@ -435,8 +288,8 @@ class JotaiStateStore {
   // ---- Stats ----
 
   getStats() {
-    const total = this.atomChanges.length;
-    const withChanges = this.atomChanges.filter(c => c.hasValueChange).length;
+    const total = this.items.length;
+    const withChanges = this.items.filter(c => c.hasValueChange).length;
     return {
       totalChanges: total,
       changesWithValueChange: withChanges,
@@ -450,34 +303,16 @@ class JotaiStateStore {
 
   // ---- Enable / Disable ----
 
-  setEnabled(enabled) {
-    this.isEnabled = enabled;
-  }
-  getEnabled() {
-    return this.isEnabled;
-  }
   setMaxChanges(max) {
-    this.maxChanges = max;
-    if (this.atomChanges.length > max) {
-      this.atomChanges = this.atomChanges.slice(0, max);
-      this.notifyListeners();
-    }
+    this.setMax(max);
   }
 
   // ---- Subscriptions ----
 
-  subscribe(listener) {
-    this.listeners.add(listener);
-    return () => this.listeners.delete(listener);
-  }
   subscribeToAtoms(listener) {
     this.atomListeners.add(listener);
     return () => this.atomListeners.delete(listener);
   }
-  notifyListeners() {
-    const changes = this.getAtomChanges();
-    this.listeners.forEach(listener => listener(changes));
-  }
   notifyAtomListeners() {
     const atoms = this.getAtoms();
     this.atomListeners.forEach(listener => listener(atoms));

package/lib/commonjs/jotai/utils/snapshotProvider.js

@@ -65,30 +65,14 @@ async function capture() {
 }
 async function restore(data, options) {
   const snapshot = data;
-  const excludedSet = new Set(options?.excludeKeys ?? []);
-  const includedSet = options?.includeKeys ? new Set(options.includeKeys) : null;
-  const touch = key => !excludedSet.has(key) && (!includedSet || includedSet.has(key));
-  let excludedHits = 0;
-  const result = {
-    ok: true,
-    applied: 0,
-    skipped: [],
-    warnings: []
-  };
+  const scope = (0, _sharedUi.createRestoreScope)(options);
+  const result = (0, _sharedUi.emptyRestoreResult)();
   if (!snapshot?.atoms) {
-    return {
-      ok: false,
-      applied: 0,
-      skipped: [],
-      warnings: ["empty jotai snapshot"]
-    };
+    return (0, _sharedUi.failedRestore)("empty jotai snapshot");
   }
   let derived = 0;
   for (const [label, entry] of Object.entries(snapshot.atoms)) {
-    if (!touch(label)) {
-      excludedHits += 1;
-      continue;
-    }
+    if (!scope.allows(label)) continue;
     if (!entry.writable) {
       derived += 1;
       continue;
@@ -122,9 +106,8 @@ async function restore(data, options) {
   if (derived > 0) {
     result.warnings.push(`${derived} derived atom(s) left to recompute`);
   }
-  if (excludedHits > 0) {
-    result.warnings.push(`${excludedHits} atom(s) excluded by you`);
-  }
+  const excludedWarning = scope.excludedWarning("atom(s)");
+  if (excludedWarning) result.warnings.push(excludedWarning);
   return result;
 }
 
@@ -149,8 +132,7 @@ async function previewItems(target, base) {
   }
   const items = [];
   const notes = [];
-  const labels = new Set([...Object.keys(baseAtoms), ...Object.keys(targetAtoms)]);
-  for (const label of labels) {
+  for (const label of (0, _sharedUi.unionKeys)(baseAtoms, targetAtoms)) {
     const inTarget = label in targetAtoms;
     if (!inTarget) {
       if (liveMode) notes.push(`atom "${label}" not in snapshot — untouched`);else items.push({