@buoy-gg/jotai 3.0.1 → 4.0.1

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

@@ -1 +1,83 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.useJotaiAtomChanges=useJotaiAtomChanges;var _react=require("react"),_jotaiStateStore=require("../utils/jotaiStateStore");function useJotaiAtomChanges(){const[t,e]=(0,_react.useState)(()=>_jotaiStateStore.jotaiStateStore.getAtomChanges()),[a,o]=(0,_react.useState)(()=>_jotaiStateStore.jotaiStateStore.getAtoms()),[r,s]=(0,_react.useState)({}),[i,n]=(0,_react.useState)(()=>_jotaiStateStore.jotaiStateStore.getEnabled());(0,_react.useEffect)(()=>{const t=_jotaiStateStore.jotaiStateStore.subscribe(t=>{e(t)}),a=_jotaiStateStore.jotaiStateStore.subscribeToAtoms(t=>{o(t)});return()=>{t(),a()}},[]);const l=(0,_react.useMemo)(()=>{let e=t;if(r.searchText){const t=r.searchText.toLowerCase();e=e.filter(e=>e.atomLabel.toLowerCase().includes(t)||e.valuePreview.toLowerCase().includes(t)||e.changedKeys.some(e=>e.toLowerCase().includes(t)))}return r.atomLabels&&r.atomLabels.length>0&&(e=e.filter(t=>r.atomLabels.includes(t.atomLabel))),r.onlyWithChanges&&(e=e.filter(t=>t.hasValueChange)),e},[t,r]),S=(0,_react.useMemo)(()=>{const e=t.length,o=t.filter(t=>t.hasValueChange).length;return{totalChanges:e,changesWithValueChange:o,changesWithoutValueChange:e-o,atomCount:a.length}},[t,a]),u=(0,_react.useMemo)(()=>_jotaiStateStore.jotaiStateStore.getUniqueAtomLabels(),[a]),c=(0,_react.useCallback)(()=>{_jotaiStateStore.jotaiStateStore.clearAtomChanges()},[]),g=(0,_react.useCallback)(()=>{const t=!i;_jotaiStateStore.jotaiStateStore.setEnabled(t),n(t)},[i]),h=(0,_react.useCallback)(t=>_jotaiStateStore.jotaiStateStore.getAtomChangeById(t),[]);return{atomChanges:t,filteredChanges:l,filter:r,setFilter:s,stats:S,atoms:a,clearChanges:c,isEnabled:i,toggleCapture:g,atomLabels:u,getChangeById:h}}
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useJotaiAtomChanges = useJotaiAtomChanges;
+var _react = require("react");
+var _jotaiStateStore = require("../utils/jotaiStateStore");
+/**
+ * Hook for consuming Jotai atom changes from the store
+ *
+ * Mirrors useZustandStateChanges.ts from @buoy-gg/zustand
+ */
+
+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 stats = (0, _react.useMemo)(() => {
+    const total = atomChanges.length;
+    const withChanges = atomChanges.filter(c => c.hasValueChange).length;
+    return {
+      totalChanges: total,
+      changesWithValueChange: withChanges,
+      changesWithoutValueChange: total - withChanges,
+      atomCount: atoms.length
+    };
+  }, [atomChanges, 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,
+    stats,
+    atoms,
+    clearChanges,
+    isEnabled,
+    toggleCapture,
+    atomLabels,
+    getChangeById
+  };
+}

package/lib/commonjs/jotai/index.js

@@ -1 +1,85 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),Object.defineProperty(exports,"JOTAI_ICON_COLOR",{enumerable:!0,get:function(){return _JotaiIcon.JOTAI_ICON_COLOR}}),Object.defineProperty(exports,"JotaiAtomBrowser",{enumerable:!0,get:function(){return _JotaiAtomBrowser.JotaiAtomBrowser}}),Object.defineProperty(exports,"JotaiAtomChangeItem",{enumerable:!0,get:function(){return _JotaiAtomChangeItem.JotaiAtomChangeItem}}),Object.defineProperty(exports,"JotaiAtomDetailContent",{enumerable:!0,get:function(){return _JotaiAtomDetailContent.JotaiAtomDetailContent}}),Object.defineProperty(exports,"JotaiAtomDetailFooter",{enumerable:!0,get:function(){return _JotaiAtomDetailContent.JotaiAtomDetailFooter}}),Object.defineProperty(exports,"JotaiIcon",{enumerable:!0,get:function(){return _JotaiIcon.JotaiIcon}}),Object.defineProperty(exports,"JotaiModal",{enumerable:!0,get:function(){return _JotaiModal.JotaiModal}}),Object.defineProperty(exports,"isAtomWatched",{enumerable:!0,get:function(){return _watchAtoms.isAtomWatched}}),Object.defineProperty(exports,"jotaiStateStore",{enumerable:!0,get:function(){return _jotaiStateStore.jotaiStateStore}}),Object.defineProperty(exports,"useJotaiAtomChanges",{enumerable:!0,get:function(){return _useJotaiAtomChanges.useJotaiAtomChanges}}),Object.defineProperty(exports,"watchAtoms",{enumerable:!0,get:function(){return _watchAtoms.watchAtoms}}),Object.defineProperty(exports,"watchDefaultStoreAtoms",{enumerable:!0,get:function(){return _watchAtoms.watchDefaultStoreAtoms}});var _JotaiModal=require("./components/JotaiModal"),_JotaiIcon=require("./components/JotaiIcon"),_JotaiAtomChangeItem=require("./components/JotaiAtomChangeItem"),_JotaiAtomDetailContent=require("./components/JotaiAtomDetailContent"),_JotaiAtomBrowser=require("./components/JotaiAtomBrowser"),_jotaiStateStore=require("./utils/jotaiStateStore"),_watchAtoms=require("./utils/watchAtoms"),_useJotaiAtomChanges=require("./hooks/useJotaiAtomChanges");
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "JOTAI_ICON_COLOR", {
+  enumerable: true,
+  get: function () {
+    return _JotaiIcon.JOTAI_ICON_COLOR;
+  }
+});
+Object.defineProperty(exports, "JotaiAtomBrowser", {
+  enumerable: true,
+  get: function () {
+    return _JotaiAtomBrowser.JotaiAtomBrowser;
+  }
+});
+Object.defineProperty(exports, "JotaiAtomChangeItem", {
+  enumerable: true,
+  get: function () {
+    return _JotaiAtomChangeItem.JotaiAtomChangeItem;
+  }
+});
+Object.defineProperty(exports, "JotaiAtomDetailContent", {
+  enumerable: true,
+  get: function () {
+    return _JotaiAtomDetailContent.JotaiAtomDetailContent;
+  }
+});
+Object.defineProperty(exports, "JotaiAtomDetailFooter", {
+  enumerable: true,
+  get: function () {
+    return _JotaiAtomDetailContent.JotaiAtomDetailFooter;
+  }
+});
+Object.defineProperty(exports, "JotaiIcon", {
+  enumerable: true,
+  get: function () {
+    return _JotaiIcon.JotaiIcon;
+  }
+});
+Object.defineProperty(exports, "JotaiModal", {
+  enumerable: true,
+  get: function () {
+    return _JotaiModal.JotaiModal;
+  }
+});
+Object.defineProperty(exports, "isAtomWatched", {
+  enumerable: true,
+  get: function () {
+    return _watchAtoms.isAtomWatched;
+  }
+});
+Object.defineProperty(exports, "jotaiStateStore", {
+  enumerable: true,
+  get: function () {
+    return _jotaiStateStore.jotaiStateStore;
+  }
+});
+Object.defineProperty(exports, "useJotaiAtomChanges", {
+  enumerable: true,
+  get: function () {
+    return _useJotaiAtomChanges.useJotaiAtomChanges;
+  }
+});
+Object.defineProperty(exports, "watchAtoms", {
+  enumerable: true,
+  get: function () {
+    return _watchAtoms.watchAtoms;
+  }
+});
+Object.defineProperty(exports, "watchDefaultStoreAtoms", {
+  enumerable: true,
+  get: function () {
+    return _watchAtoms.watchDefaultStoreAtoms;
+  }
+});
+var _JotaiModal = require("./components/JotaiModal");
+var _JotaiIcon = require("./components/JotaiIcon");
+var _JotaiAtomChangeItem = require("./components/JotaiAtomChangeItem");
+var _JotaiAtomDetailContent = require("./components/JotaiAtomDetailContent");
+var _JotaiAtomBrowser = require("./components/JotaiAtomBrowser");
+var _jotaiStateStore = require("./utils/jotaiStateStore");
+var _watchAtoms = require("./utils/watchAtoms");
+var _useJotaiAtomChanges = require("./hooks/useJotaiAtomChanges");

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

@@ -0,0 +1,38 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.jotaiSyncAdapter = void 0;
+var _jotaiStateStore = require("../utils/jotaiStateStore");
+/**
+ * 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).
+ *
+ * Atom changes are captured by watchAtoms(), independent of whether a
+ * dashboard is watching — subscribing here only streams what the store
+ * already records. The snapshot carries both the change timeline and the
+ * atom registry (with each atom's current value) so the dashboard can render
+ * the atom browser.
+ */
+const jotaiSyncAdapter = exports.jotaiSyncAdapter = {
+  version: 1,
+  getSnapshot: () => ({
+    changes: _jotaiStateStore.jotaiStateStore.getAtomChanges(),
+    atoms: _jotaiStateStore.jotaiStateStore.getAtomSnapshots()
+  }),
+  subscribe: onChange => {
+    const unsubscribeChanges = _jotaiStateStore.jotaiStateStore.subscribe(onChange);
+    const unsubscribeAtoms = _jotaiStateStore.jotaiStateStore.subscribeToAtoms(onChange);
+    return () => {
+      unsubscribeChanges();
+      unsubscribeAtoms();
+    };
+  },
+  actions: {
+    clearEvents: () => {
+      _jotaiStateStore.jotaiStateStore.clearAtomChanges();
+    }
+  }
+};

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

@@ -1 +1,399 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.jotaiStateStore=void 0;const ATOM_COLORS={count:"#10B981",auth:"#8B5CF6",user:"#3B82F6",cart:"#EC4899",app:"#6366F1",ui:"#F59E0B",settings:"#14B8A6",theme:"#06B6D4",nav:"#F97316",form:"#EF4444",modal:"#A855F7",filter:"#84CC16"};function getAtomColor(t){const e=t.toLowerCase();if(ATOM_COLORS[e])return ATOM_COLORS[e];for(const[t,s]of Object.entries(ATOM_COLORS))if(e.includes(t))return s;const s=137*t.split("").reduce((t,e)=>t+e.charCodeAt(0),0)%360,n=.7*(1-Math.abs(1.2-1)),a=n*(1-Math.abs(s/60%2-1)),o=.6-n/2;let r=0,i=0,h=0;s<60?(r=n,i=a):s<120?(r=a,i=n):s<180?(i=n,h=a):s<240?(i=a,h=n):s<300?(r=a,h=n):(r=n,h=a);const l=t=>Math.round(255*(t+o)).toString(16).padStart(2,"0");return`#${l(r)}${l(i)}${l(h)}`}function formatValuePreview(t,e=40){if(void 0===t)return"undefined";if(null===t)return"null";try{if("function"==typeof t)return"(fn)";if("string"==typeof t)return t.length>e?`"${t.slice(0,e-3)}..."`:`"${t}"`;if("number"==typeof t||"boolean"==typeof t)return String(t);if(Array.isArray(t)){if(0===t.length)return"[]";const s=JSON.stringify(t);return s.length>e?`[${t.length} items]`:s}if("object"==typeof t){const s=Object.keys(t);if(0===s.length)return"{}";const n=JSON.stringify(t);return n.length<=e?n:`{ ${s.length} keys }`}return String(t).slice(0,e)}catch{return"[complex]"}}function getValueDiffSummary(t,e){if(t===e)return{summary:"no change",changedKeys:[],changedCount:0};if("object"!=typeof t||"object"!=typeof e||null===t||null===e)return{summary:"changed",changedKeys:[],changedCount:0};const s=Object.keys(t),n=Object.keys(e),a=n.filter(t=>!s.includes(t)),o=s.filter(t=>!n.includes(t)),r=[];for(const a of s)n.includes(a)&&t[a]!==e[a]&&r.push(a);const i=[...a,...o,...r],h=[];a.length>0&&h.push(`+${a.length}`),o.length>0&&h.push(`-${o.length}`),r.length>0&&h.push(`~${r.length}`);const l=i.length;return 0===h.length?{summary:"nested change",changedKeys:[],changedCount:0}:{summary:`${h.join(" ")} ${1===l?"key":"keys"}`,changedKeys:i,changedCount:l}}class JotaiStateStore{atomChanges=[];atoms=new Map;listeners=new Set;atomListeners=new Set;maxChanges=200;idCounter=0;isEnabled=!0;addAtomChange(t){if(!this.isEnabled)return;const{atomLabel:e,prevValue:s,nextValue:n,category:a="write"}=t,o=s!==n,{summary:r,changedKeys:i,changedCount:h}=getValueDiffSummary(s,n),l=formatValuePreview(n),u={id:`${Date.now()}-${++this.idCounter}`,atomLabel:e,timestamp:Date.now(),prevValue:s,nextValue:n,hasValueChange:o,category:a,changedKeys:i,changedKeysCount:h,diffSummary:r,valuePreview:l,isSlowUpdate:!1};this.atomChanges=[u,...this.atomChanges].slice(0,this.maxChanges);const g=this.atoms.get(e);g&&g.changeCount++,this.notifyListeners(),this.notifyAtomListeners()}getAtomChanges(){return[...this.atomChanges]}getAtomChangeById(t){return this.atomChanges.find(e=>e.id===t)}clearAtomChanges(){this.atomChanges=[];for(const t of this.atoms.values())t.changeCount=0;this.notifyListeners(),this.notifyAtomListeners()}registerAtom(t,e){if(this.atoms.has(t))return;const s={label:t,changeCount:0,color:getAtomColor(t),getValue:e};this.atoms.set(t,s),this.notifyAtomListeners()}unregisterAtom(t){this.atoms.delete(t),this.notifyAtomListeners()}getAtoms(){return Array.from(this.atoms.values())}getAtom(t){return this.atoms.get(t)}getAtomColor(t){return this.atoms.get(t)?.color??getAtomColor(t)}filterAtomChanges(t){let e=[...this.atomChanges];if(t.searchText){const s=t.searchText.toLowerCase();e=e.filter(t=>t.atomLabel.toLowerCase().includes(s)||t.valuePreview.toLowerCase().includes(s)||t.changedKeys.some(t=>t.toLowerCase().includes(s)))}return t.atomLabels&&t.atomLabels.length>0&&(e=e.filter(e=>t.atomLabels.includes(e.atomLabel))),t.onlyWithChanges&&(e=e.filter(t=>t.hasValueChange)),e}getStats(){const t=this.atomChanges.length,e=this.atomChanges.filter(t=>t.hasValueChange).length;return{totalChanges:t,changesWithValueChange:e,changesWithoutValueChange:t-e,atomCount:this.atoms.size}}getUniqueAtomLabels(){return Array.from(this.atoms.keys()).sort()}setEnabled(t){this.isEnabled=t}getEnabled(){return this.isEnabled}setMaxChanges(t){this.maxChanges=t,this.atomChanges.length>t&&(this.atomChanges=this.atomChanges.slice(0,t),this.notifyListeners())}subscribe(t){return this.listeners.add(t),()=>this.listeners.delete(t)}subscribeToAtoms(t){return this.atomListeners.add(t),()=>this.atomListeners.delete(t)}notifyListeners(){const t=this.getAtomChanges();this.listeners.forEach(e=>e(t))}notifyAtomListeners(){const t=this.getAtoms();this.atomListeners.forEach(e=>e(t))}}const jotaiStateStore=exports.jotaiStateStore=new JotaiStateStore;
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.jotaiStateStore = void 0;
+/**
+ * Jotai state store — captures and stores Jotai atom changes
+ *
+ * Mirrors the architecture of zustandStateStore.ts from @buoy-gg/zustand
+ */
+
+// ============================================
+// Atom Color Palette
+// ============================================
+
+const ATOM_COLORS = {
+  count: "#10B981",
+  // emerald
+  auth: "#8B5CF6",
+  // purple
+  user: "#3B82F6",
+  // blue
+  cart: "#EC4899",
+  // pink
+  app: "#6366F1",
+  // indigo
+  ui: "#F59E0B",
+  // amber
+  settings: "#14B8A6",
+  // teal
+  theme: "#06B6D4",
+  // cyan
+  nav: "#F97316",
+  // orange
+  form: "#EF4444",
+  // red
+  modal: "#A855F7",
+  // violet
+  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)}`;
+}
+
+// ============================================
+// Helper Functions
+// ============================================
+
+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
+  };
+}
+
+// ============================================
+// Jotai State Store
+// ============================================
+
+class JotaiStateStore {
+  atomChanges = [];
+  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;
+    const {
+      atomLabel,
+      prevValue,
+      nextValue,
+      category = "write"
+    } = params;
+    const hasValueChange = prevValue !== nextValue;
+    const {
+      summary,
+      changedKeys,
+      changedCount
+    } = getValueDiffSummary(prevValue, nextValue);
+    const valuePreview = formatValuePreview(nextValue);
+    const change = {
+      id: `${Date.now()}-${++this.idCounter}`,
+      atomLabel,
+      timestamp: Date.now(),
+      prevValue,
+      nextValue,
+      hasValueChange,
+      category,
+      changedKeys,
+      changedKeysCount: changedCount,
+      diffSummary: summary,
+      valuePreview,
+      isSlowUpdate: false
+    };
+    this.atomChanges = [change, ...this.atomChanges].slice(0, this.maxChanges);
+    const atomInfo = this.atoms.get(atomLabel);
+    if (atomInfo) {
+      atomInfo.changeCount++;
+    }
+    this.notifyListeners();
+    this.notifyAtomListeners();
+  }
+  getAtomChanges() {
+    return [...this.atomChanges];
+  }
+  getAtomChangeById(id) {
+    return this.atomChanges.find(c => c.id === id);
+  }
+  clearAtomChanges() {
+    this.atomChanges = [];
+    for (const atom of this.atoms.values()) {
+      atom.changeCount = 0;
+    }
+    this.notifyListeners();
+    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 —
+   * the live `getValue` handles can't go over the wire.
+   */
+  getAtomSnapshots() {
+    return Array.from(this.atoms.values()).map(atom => {
+      let currentValue;
+      try {
+        currentValue = atom.getValue();
+      } catch {
+        currentValue = undefined;
+      }
+      return {
+        label: atom.label,
+        changeCount: atom.changeCount,
+        color: atom.color,
+        currentValue
+      };
+    });
+  }
+
+  /**
+   * Replace the entire mirror contents from a synced device snapshot. The
+   * rebuilt registry entries get stub `getValue` handles serving the
+   * snapshotted value. Respects the enabled flag so the UI's pause button
+   * freezes the mirror.
+   */
+  replaceFromSnapshot(changes, atomSnapshots) {
+    if (!this.isEnabled) return;
+    this.atomChanges = changes.slice(0, this.maxChanges);
+    this.atoms = new Map(atomSnapshots.map(snapshot => [snapshot.label, {
+      label: snapshot.label,
+      changeCount: snapshot.changeCount,
+      color: snapshot.color,
+      getValue: () => snapshot.currentValue
+    }]));
+    this.notifyListeners();
+    this.notifyAtomListeners();
+  }
+
+  // ---- Atom Registry ----
+
+  registerAtom(label, getValue) {
+    if (this.atoms.has(label)) return;
+    const atomInfo = {
+      label,
+      changeCount: 0,
+      color: getAtomColor(label),
+      getValue
+    };
+    this.atoms.set(label, atomInfo);
+    this.notifyAtomListeners();
+  }
+  unregisterAtom(label) {
+    this.atoms.delete(label);
+    this.notifyAtomListeners();
+  }
+  getAtoms() {
+    return Array.from(this.atoms.values());
+  }
+  getAtom(label) {
+    return this.atoms.get(label);
+  }
+  getAtomColor(label) {
+    return this.atoms.get(label)?.color ?? getAtomColor(label);
+  }
+
+  // ---- Filtering ----
+
+  filterAtomChanges(filter) {
+    let filtered = [...this.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;
+  }
+
+  // ---- Stats ----
+
+  getStats() {
+    const total = this.atomChanges.length;
+    const withChanges = this.atomChanges.filter(c => c.hasValueChange).length;
+    return {
+      totalChanges: total,
+      changesWithValueChange: withChanges,
+      changesWithoutValueChange: total - withChanges,
+      atomCount: this.atoms.size
+    };
+  }
+  getUniqueAtomLabels() {
+    return Array.from(this.atoms.keys()).sort();
+  }
+
+  // ---- 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();
+    }
+  }
+
+  // ---- 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));
+  }
+}
+const jotaiStateStore = exports.jotaiStateStore = new JotaiStateStore();