@buoy-gg/jotai 7.0.38 → 7.0.39

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

@@ -1 +1,65 @@
-"use strict";import{useCallback,useMemo}from"react";import{useChangeLog,useSubscribedValue}from"@buoy-gg/shared-ui";import{jotaiStateStore}from"../utils/jotaiStateStore";function filterChanges(e,t){let a=e;if(t.searchText){const e=t.searchText.toLowerCase();a=a.filter(t=>t.atomLabel.toLowerCase().includes(e)||t.valuePreview.toLowerCase().includes(e)||t.changedKeys.some(t=>t.toLowerCase().includes(e)))}return t.atomLabels&&t.atomLabels.length>0&&(a=a.filter(e=>t.atomLabels.includes(e.atomLabel))),t.onlyWithChanges&&(a=a.filter(e=>e.hasValueChange)),a}const readAtoms=()=>jotaiStateStore.getAtoms(),subscribeToAtoms=e=>jotaiStateStore.subscribeToAtoms(e);export function useJotaiAtomChanges(){const e=useChangeLog(jotaiStateStore,{filterItems:filterChanges}),t=useSubscribedValue(readAtoms,subscribeToAtoms),a=useMemo(()=>{const a=e.items.length,o=e.items.filter(e=>e.hasValueChange).length;return{totalChanges:a,changesWithValueChange:o,changesWithoutValueChange:a-o,atomCount:t.length}},[e.items,t]),o=useMemo(()=>jotaiStateStore.getUniqueAtomLabels(),[t]),s=useCallback(e=>jotaiStateStore.getAtomChangeById(e),[]);return{atomChanges:e.items,filteredChanges:e.filteredItems,filter:e.filter,setFilter:e.setFilter,stats:a,atoms:t,clearChanges:jotaiStateStore.clearAtomChanges.bind(jotaiStateStore),isEnabled:e.isEnabled,toggleCapture:e.toggleCapture,atomLabels:o,getChangeById:s}}
+"use strict";
+
+/**
+ * Hook for consuming Jotai atom changes from the store
+ *
+ * The subscribe / filter / pause / clear plumbing is shared `useChangeLog`;
+ * this file owns the jotai-specific filter, stats and atom registry.
+ */
+
+import { useCallback, useMemo } from "react";
+import { useChangeLog, useSubscribedValue } from "@buoy-gg/shared-ui";
+import { jotaiStateStore } from "../utils/jotaiStateStore";
+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.getAtoms();
+const subscribeToAtoms = listener => jotaiStateStore.subscribeToAtoms(listener);
+export function useJotaiAtomChanges() {
+  const log = useChangeLog(jotaiStateStore, {
+    filterItems: filterChanges
+  });
+  const atoms = useSubscribedValue(readAtoms, subscribeToAtoms);
+  const stats = useMemo(() => {
+    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
+    };
+  }, [log.items, atoms]);
+  const atomLabels = useMemo(() => {
+    return jotaiStateStore.getUniqueAtomLabels();
+  }, [atoms]);
+  const getChangeById = useCallback(id => {
+    return jotaiStateStore.getAtomChangeById(id);
+  }, []);
+  return {
+    atomChanges: log.items,
+    filteredChanges: log.filteredItems,
+    filter: log.filter,
+    setFilter: log.setFilter,
+    stats,
+    atoms,
+    // Not the shared log.clear: the store also owns each atom's change
+    // count, and only clearAtomChanges resets those with the list.
+    clearChanges: jotaiStateStore.clearAtomChanges.bind(jotaiStateStore),
+    isEnabled: log.isEnabled,
+    toggleCapture: log.toggleCapture,
+    atomLabels,
+    getChangeById
+  };
+}

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

@@ -1 +1,303 @@
-"use strict";import{jotaiStateStore}from"../utils/jotaiStateStore";import{WIRE_DETAIL_LIMIT_BYTES,createSyncAdapter,capDetail,detailByIdAction,expandKeyedArrays,memoByIdentity,onDeviceMarker,patchFromPath,readParams,readPath,refusalText,shapeSummary,suggestedPatch,toWire,typedEditViolations,unshapedLists}from"@buoy-gg/shared-ui";export const VALUE_ON_DEVICE=onDeviceMarker("Value","Atom values stay on the device — fetched on demand via getChangeDetail / getAtomValue.");const isPlainObj=e=>!!e&&"object"==typeof e&&!Array.isArray(e);function deepMergeInto(e,t){if(!isPlainObj(e)||!isPlainObj(t))return t;const a={...e};for(const[r,o]of Object.entries(t))a[r]=r in e?deepMergeInto(e[r],o):o;return a}function touchesList(e,t){let a=e;for(const e of t.split(".")){if(!isPlainObj(a))return!1;if(!(e in a))return!1;a=a[e]}return Array.isArray(a)?a.length>0:!!a&&"object"==typeof a}const toWireChange=memoByIdentity(e=>({...e,prevValue:VALUE_ON_DEVICE,nextValue:VALUE_ON_DEVICE})),toWireValue=e=>toWire(e,VALUE_ON_DEVICE);export const jotaiSyncAdapter=createSyncAdapter({version:2,getSnapshot:()=>({changes:jotaiStateStore.getAtomChanges().map(toWireChange),atoms:jotaiStateStore.getAtomSnapshots().map(e=>({...e,currentValue:toWireValue(e.currentValue)}))}),subscribe:[e=>jotaiStateStore.subscribe(e),e=>jotaiStateStore.subscribeToAtoms(e)],actions:{clearEvents:()=>{jotaiStateStore.clearAtomChanges()},getChangeDetail:detailByIdAction(e=>jotaiStateStore.getAtomChangeById(e),(e,t)=>({prevValue:t(e.prevValue),nextValue:t(e.nextValue)})),getAtomValue:e=>{const{label:t,path:a}=readParams(e);if(!t)return{found:!1,reason:"missing label"};const r=jotaiStateStore.getAtom(t);if(!r)return{found:!1,reason:"unknown label"};let o;try{o=r.getValue()}catch{o=void 0}try{JSON.stringify(o)}catch{return{found:!0,label:t,currentValue:VALUE_ON_DEVICE}}if(a){const e=readPath(o,a);return e.ok?{found:!0,label:t,path:a,shape:shapeSummary(e.value),currentValue:e.value}:{found:!1,reason:e.error}}return{found:!0,label:t,...shapeSummary(o)?{shape:shapeSummary(o)}:{},currentValue:capDetail(o,WIRE_DETAIL_LIMIT_BYTES)}},listAtoms:e=>{const{includeValues:t=!1,limit:a}=readParams(e),r=jotaiStateStore.getAtoms(),o=("number"==typeof a&&a>0?r.slice(0,a):r).map(e=>{let a,r;if(t)try{a=e.getValue()}catch{a=void 0}try{r=shapeSummary(e.getValue())}catch{r=void 0}return{label:e.label,changes:e.changeCount,writable:"function"==typeof e.setValue,...r?{shape:r}:{},...t?{currentValue:a}:{}}});return{atoms:o,total:r.length,returned:o.length,includedValues:t}},setAtom:e=>{const{label:t,value:a,merge:r,path:o,force:n}=readParams(e);if(!t)throw new Error("setAtom requires a `label`");const s=jotaiStateStore.getAtom(t);let i;try{i=s?.getValue()}catch{i=void 0}let u=a,l=[],c=[];const d=!0===r||void 0!==o;if(void 0!==o){if(void 0===a)return{ok:!1,error:`Refused: sent \`path\` without \`value\`. Say what to set "${o}" to.`};const e=patchFromPath(i,o,a);if(!e.ok)return{ok:!1,error:`Refused: ${e.error}`};u=e.patch}if(!n&&d&&void 0!==i){const e=expandKeyedArrays(i,u);if(e.error)return{ok:!1,error:`Refused: ${e.error}`};u=e.patch,l=e.notes,c=unshapedLists(i).filter(e=>touchesList(u,e));const t=typedEditViolations(i,u,{noun:"atom"});if(t.length){const e=suggestedPatch(u,t);return{ok:!1,error:refusalText(t,"atom",e),violations:t,...e?{suggestedValue:e}:{}}}}return jotaiStateStore.setAtomValue(t,d?deepMergeInto(i,u):u),{ok:!0,...void 0!==o?{path:o}:{},...l.length?{keyed:l}:{},...c.length?{unchecked:c.map(e=>`\`${e}\` was empty, so nothing knows what its items look like and the shape of what you added was NOT checked.`)}:{}}}}});
+"use strict";
+
+import { jotaiStateStore } from "../utils/jotaiStateStore";
+import { WIRE_DETAIL_LIMIT_BYTES, createSyncAdapter, capDetail, detailByIdAction, expandKeyedArrays, memoByIdentity, onDeviceMarker, patchFromPath, readParams, readPath, refusalText, shapeSummary, suggestedPatch, toWire, typedEditViolations, unshapedLists } from "@buoy-gg/shared-ui";
+
+/**
+ * Sentinel used in WIRE-FORM snapshots in place of raw prevValue/nextValue.
+ * Same hazard as redux/zustand: up to 200 changes × 2 values on every
+ * snapshot. Dashboards fetch values via `getChangeDetail`.
+ */
+export const VALUE_ON_DEVICE = onDeviceMarker("Value", "Atom values stay on the device — fetched on demand via getChangeDetail / getAtomValue.");
+const isPlainObj = v => !!v && typeof v === "object" && !Array.isArray(v);
+
+/**
+ * Merge a patch into an atom's value.
+ *
+ * An atom is not always an object — plenty hold a number, a string or a list —
+ * so a merge only means anything when BOTH sides are plain objects. Anything
+ * else replaces, which is what a caller asking to merge a scalar can only have
+ * meant. Arrays replace too: the id-addressed form has already been expanded to
+ * a whole array by the time this runs, so merging element-wise here would undo
+ * the deletion half of that expansion.
+ */
+function deepMergeInto(base, patch) {
+  if (!isPlainObj(base) || !isPlainObj(patch)) return patch;
+  const out = {
+    ...base
+  };
+  for (const [k, v] of Object.entries(patch)) out[k] = k in base ? deepMergeInto(base[k], v) : v;
+  return out;
+}
+
+/**
+ * Does this patch write into the list at `path`? Only then is an
+ * unchecked-shape warning about that list worth saying.
+ */
+function touchesList(patch, path) {
+  let cur = patch;
+  for (const seg of path.split(".")) {
+    if (!isPlainObj(cur)) return false;
+    if (!(seg in cur)) return false;
+    cur = cur[seg];
+  }
+  return Array.isArray(cur) ? cur.length > 0 : !!cur && typeof cur === "object";
+}
+
+/**
+ * Per-change wire cache — the store prepends and never mutates a recorded
+ * change, so identity is a correct, self-invalidating key.
+ */
+const toWireChange = memoByIdentity(change => ({
+  ...change,
+  prevValue: VALUE_ON_DEVICE,
+  nextValue: VALUE_ON_DEVICE
+}));
+const toWireValue = value => toWire(value, VALUE_ON_DEVICE);
+
+/**
+ * Sync adapter for the jotai tool, consumed by @buoy-gg/external-sync's
+ * `useExternalSync`.
+ *
+ * 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.
+ *
+ * v2: change-log prevValue/nextValue are replaced with on-device markers.
+ * Dashboards fetch values via `getChangeDetail`. Oversized / unserializable
+ * `atoms[].currentValue` uses the same marker and is fetched via `getAtomValue`.
+ */
+export const jotaiSyncAdapter = createSyncAdapter({
+  version: 2,
+  getSnapshot: () => ({
+    changes: jotaiStateStore.getAtomChanges().map(toWireChange),
+    atoms: jotaiStateStore.getAtomSnapshots().map(atom => ({
+      ...atom,
+      currentValue: toWireValue(atom.currentValue)
+    }))
+  }),
+  subscribe: [onChange => jotaiStateStore.subscribe(onChange), onChange => jotaiStateStore.subscribeToAtoms(onChange)],
+  actions: {
+    clearEvents: () => {
+      jotaiStateStore.clearAtomChanges();
+    },
+    /**
+     * On-demand detail: one change's real prevValue/nextValue.
+     * The per-snapshot stream stays value-free; this is the explicit,
+     * size-guarded channel for the detail pane.
+     */
+    getChangeDetail: detailByIdAction(id => 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.
+     */
+    getAtomValue: params => {
+      const {
+        label,
+        path
+      } = readParams(params);
+      if (!label) return {
+        found: false,
+        reason: "missing label"
+      };
+      const atom = jotaiStateStore.getAtom(label);
+      if (!atom) return {
+        found: false,
+        reason: "unknown label"
+      };
+      let currentValue;
+      try {
+        currentValue = atom.getValue();
+      } catch {
+        currentValue = undefined;
+      }
+      try {
+        JSON.stringify(currentValue);
+      } catch {
+        return {
+          found: true,
+          label,
+          currentValue: VALUE_ON_DEVICE
+        };
+      }
+      // One slice instead of the whole atom, when asked. The reason to want it
+      // is the engine's 24,000-character result cap: a caller that never saw the
+      // field it means to edit is left inventing a shape.
+      if (path) {
+        const at = readPath(currentValue, path);
+        if (!at.ok) return {
+          found: false,
+          reason: at.error
+        };
+        return {
+          found: true,
+          label,
+          path,
+          shape: shapeSummary(at.value),
+          currentValue: at.value
+        };
+      }
+      // `shape` BEFORE `currentValue`: a result is truncated by slicing the
+      // encoded string, so what is serialised first is what survives the cut,
+      // and the sketch does not grow with the data.
+      return {
+        found: true,
+        label,
+        ...(shapeSummary(currentValue) ? {
+          shape: shapeSummary(currentValue)
+        } : {}),
+        currentValue: capDetail(currentValue, WIRE_DETAIL_LIMIT_BYTES)
+      };
+    },
+    /**
+     * Compact current-value reader for a remote driver (MCP/LLM): registered
+     * atoms with light metadata; each atom's `currentValue` stays on the device
+     * unless `includeValues` is set. `writable` tells the caller which atoms
+     * can be set via `setAtom`.
+     */
+    listAtoms: params => {
+      const {
+        includeValues = false,
+        limit
+      } = readParams(params);
+      const all = jotaiStateStore.getAtoms();
+      const capped = typeof limit === "number" && limit > 0 ? all.slice(0, limit) : all;
+      const atoms = capped.map(a => {
+        let value;
+        if (includeValues) {
+          try {
+            value = a.getValue();
+          } catch {
+            value = undefined;
+          }
+        }
+        // The compact view is what a caller reaches for precisely because it
+        // does not want the data; the item shape of a list is the one thing it
+        // cannot infer without it, and it costs a line.
+        let shape;
+        try {
+          shape = shapeSummary(a.getValue());
+        } catch {
+          shape = undefined;
+        }
+        return {
+          label: a.label,
+          changes: a.changeCount,
+          writable: typeof a.setValue === "function",
+          ...(shape ? {
+            shape
+          } : {}),
+          ...(includeValues ? {
+            currentValue: value
+          } : {})
+        };
+      });
+      return {
+        atoms,
+        total: all.length,
+        returned: atoms.length,
+        includedValues: includeValues
+      };
+    },
+    /**
+     * Write to a writable atom (throws for unknown/read-only atoms).
+     *
+     * THIS USED TO BE FOUR LINES WITH NO GUARD. `setAtom` took whatever it was
+     * given and wrote it: a string over a number, `null` over a list the screen
+     * maps, a one-item array over a fifty-item one — every failure mode the
+     * zustand and react-query adapters refuse, jotai accepted silently. It was
+     * the only writable state tool with no protection at all, and it had never
+     * had an eval case, so nothing had ever measured it.
+     *
+     * It now takes the same three forms as `zustand.setState`, backed by the
+     * same shared implementations:
+     *   { value }                    replace (guarded unless force)
+     *   { value, merge: true }       merge a patch, id-addressed lists allowed
+     *   { path, value }              set one value; no depth to get wrong
+     */
+    setAtom: params => {
+      const {
+        label,
+        value,
+        merge,
+        path,
+        force
+      } = readParams(params);
+      if (!label) throw new Error("setAtom requires a `label`");
+      const atom = jotaiStateStore.getAtom(label);
+      let current;
+      try {
+        current = atom?.getValue();
+      } catch {
+        current = undefined;
+      }
+
+      // A replace with no guard is the old behaviour; keep it reachable via
+      // `force`, and keep it the ONLY way to get it.
+      let effective = value;
+      let keyedNotes = [];
+      let unchecked = [];
+      const merging = merge === true || path !== undefined;
+      if (path !== undefined) {
+        if (value === undefined) {
+          return {
+            ok: false,
+            error: `Refused: sent \`path\` without \`value\`. Say what to set "${path}" to.`
+          };
+        }
+        const built = patchFromPath(current, path, value);
+        if (!built.ok) return {
+          ok: false,
+          error: `Refused: ${built.error}`
+        };
+        effective = built.patch;
+      }
+      if (!force && merging && current !== undefined) {
+        const expanded = expandKeyedArrays(current, effective);
+        // See keyedArrays.ts: an added item whose id disagrees with the key it
+        // was sent under is ambiguous, and only this layer can say so.
+        if (expanded.error) {
+          return {
+            ok: false,
+            error: `Refused: ${expanded.error}`
+          };
+        }
+        effective = expanded.patch;
+        keyedNotes = expanded.notes;
+        unchecked = unshapedLists(current).filter(p => touchesList(effective, p));
+        const violations = typedEditViolations(current, effective, {
+          noun: "atom"
+        });
+        if (violations.length) {
+          const suggestion = suggestedPatch(effective, violations);
+          return {
+            ok: false,
+            error: refusalText(violations, "atom", suggestion),
+            violations,
+            ...(suggestion ? {
+              suggestedValue: suggestion
+            } : {})
+          };
+        }
+      }
+      jotaiStateStore.setAtomValue(label, merging ? deepMergeInto(current, effective) : effective);
+      return {
+        ok: true,
+        ...(path !== undefined ? {
+          path
+        } : {}),
+        ...(keyedNotes.length ? {
+          keyed: keyedNotes
+        } : {}),
+        ...(unchecked.length ? {
+          unchecked: unchecked.map(p => `\`${p}\` was empty, so nothing knows what its items look like and the shape of what you added was NOT checked.`)
+        } : {})
+      };
+    }
+  }
+});

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

@@ -1 +1,317 @@
-"use strict";import{ChangeLog,entityColor,formatValuePreview as sharedFormatValuePreview,shallowDiffSummary}from"@buoy-gg/shared-ui";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(e){return entityColor(e,ATOM_COLORS)}function formatValuePreview(e,t=40){return sharedFormatValuePreview(e,{maxLength:t,functionLabel:"(fn)"})}const getValueDiffSummary=shallowDiffSummary;class JotaiStateStore extends ChangeLog{atoms=new Map;atomListeners=new Set;addAtomChange(e){if(!this.canRecord())return;const{atomLabel:t,prevValue:a,nextValue:o,category:s="write"}=e,r=a!==o,{summary:n,changedKeys:i,changedCount:l}=getValueDiffSummary(a,o),u=formatValuePreview(o),h={id:this.nextId(),atomLabel:t,timestamp:Date.now(),prevValue:a,nextValue:o,hasValueChange:r,category:s,changedKeys:i,changedKeysCount:l,diffSummary:n,valuePreview:u,isSlowUpdate:!1};this.push(h);const m=this.atoms.get(t);m&&m.changeCount++,this.notifyListeners(),this.notifyAtomListeners()}getAtomChanges(){return this.getAll()}getAtomChangeById(e){return this.getById(e)}clearAtomChanges(){for(const e of this.atoms.values())e.changeCount=0;this.clear(),this.notifyAtomListeners()}getAtomSnapshots(){return Array.from(this.atoms.values()).map(e=>{let t;try{t=e.getValue()}catch{t=void 0}return{label:e.label,changeCount:e.changeCount,color:e.color,currentValue:t,writeKind:e.writeKind}})}replaceFromSnapshot(e,t){if(!this.getEnabled())return;const a=new Map;for(const e of this.items){const t=e.prevValue;t&&!0===t.__buoyValueOnDevice||a.set(e.id,e)}const o=e.slice(0,this.max).map(e=>{const t=a.get(e.id),o=e.prevValue;return t&&!0===o?.__buoyValueOnDevice?{...e,prevValue:t.prevValue,nextValue:t.nextValue}:e}),s=new Map;for(const[e,t]of this.atoms)try{const a=t.getValue();a&&!0===a.__buoyValueOnDevice||s.set(e,a)}catch{}this.atoms=new Map(t.map(e=>{const t=e.currentValue,a=s.get(e.label),o=void 0!==a&&!0===t?.__buoyValueOnDevice?a:e.currentValue;return[e.label,{label:e.label,changeCount:e.changeCount,color:e.color,getValue:()=>o,writeKind:e.writeKind}]})),this.setItems(o),this.notifyAtomListeners()}hydrateChange(e,t){this.hydrateById(e,t)}hydrateAtomValue(e,t){const a=this.atoms.get(e);a&&(this.atoms.set(e,{...a,getValue:()=>t}),this.notifyAtomListeners())}registerAtom(e,t,a,o){if(this.atoms.has(e))return;const s={label:e,changeCount:0,color:getAtomColor(e),getValue:t,setValue:a,writeKind:o};this.atoms.set(e,s),this.notifyAtomListeners()}setAtomValue(e,t){const a=this.atoms.get(e);if(!a)throw new Error(`Atom "${e}" is not registered`);if(!a.setValue)throw new Error(`Atom "${e}" is read-only (derived) — cannot set`);a.setValue(t)}unregisterAtom(e){this.atoms.delete(e),this.notifyAtomListeners()}getAtoms(){return Array.from(this.atoms.values())}getAtom(e){return this.atoms.get(e)}getAtomColor(e){return this.atoms.get(e)?.color??getAtomColor(e)}filterAtomChanges(e){let t=this.getAll();if(e.searchText){const a=e.searchText.toLowerCase();t=t.filter(e=>e.atomLabel.toLowerCase().includes(a)||e.valuePreview.toLowerCase().includes(a)||e.changedKeys.some(e=>e.toLowerCase().includes(a)))}return e.atomLabels&&e.atomLabels.length>0&&(t=t.filter(t=>e.atomLabels.includes(t.atomLabel))),e.onlyWithChanges&&(t=t.filter(e=>e.hasValueChange)),t}getStats(){const e=this.items.length,t=this.items.filter(e=>e.hasValueChange).length;return{totalChanges:e,changesWithValueChange:t,changesWithoutValueChange:e-t,atomCount:this.atoms.size}}getUniqueAtomLabels(){return Array.from(this.atoms.keys()).sort()}setMaxChanges(e){this.setMax(e)}subscribeToAtoms(e){return this.atomListeners.add(e),()=>this.atomListeners.delete(e)}notifyAtomListeners(){const e=this.getAtoms();this.atomListeners.forEach(t=>t(e))}}export const jotaiStateStore=new JotaiStateStore;
+"use strict";
+
+/**
+ * Jotai state store — captures and stores Jotai atom changes
+ *
+ * Mirrors the architecture of zustandStateStore.ts from @buoy-gg/zustand
+ */
+
+import { ChangeLog, entityColor, formatValuePreview as sharedFormatValuePreview, shallowDiffSummary } from "@buoy-gg/shared-ui";
+// ============================================
+// 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) {
+  return entityColor(label, ATOM_COLORS);
+}
+
+// ============================================
+// Helper Functions
+// ============================================
+
+function formatValuePreview(value, maxLength = 40) {
+  return sharedFormatValuePreview(value, {
+    maxLength,
+    functionLabel: "(fn)"
+  });
+}
+const getValueDiffSummary = shallowDiffSummary;
+
+// ============================================
+// Jotai State Store
+// ============================================
+
+class JotaiStateStore extends ChangeLog {
+  atoms = new Map();
+  atomListeners = new Set();
+
+  // ---- Change Tracking ----
+
+  addAtomChange(params) {
+    if (!this.canRecord()) 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: this.nextId(),
+      atomLabel,
+      timestamp: Date.now(),
+      prevValue,
+      nextValue,
+      hasValueChange,
+      category,
+      changedKeys,
+      changedKeysCount: changedCount,
+      diffSummary: summary,
+      valuePreview,
+      isSlowUpdate: false
+    };
+    this.push(change);
+    const atomInfo = this.atoms.get(atomLabel);
+    if (atomInfo) {
+      atomInfo.changeCount++;
+    }
+    this.notifyListeners();
+    this.notifyAtomListeners();
+  }
+  getAtomChanges() {
+    return this.getAll();
+  }
+  getAtomChangeById(id) {
+    return this.getById(id);
+  }
+  clearAtomChanges() {
+    for (const atom of this.atoms.values()) {
+      atom.changeCount = 0;
+    }
+    this.clear();
+    this.notifyAtomListeners();
+  }
+
+  // ---- Remote Mirror Mode ----
+
+  /**
+   * 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,
+        writeKind: atom.writeKind
+      };
+    });
+  }
+
+  /**
+   * 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.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.items) {
+      const prev = existing.prevValue;
+      if (!prev || prev.__buoyValueOnDevice !== true) {
+        hydrated.set(existing.id, existing);
+      }
+    }
+    const merged = changes.slice(0, this.max).map(change => {
+      const kept = hydrated.get(change.id);
+      const incoming = change.prevValue;
+      return kept && incoming?.__buoyValueOnDevice === true ? {
+        ...change,
+        prevValue: kept.prevValue,
+        nextValue: kept.nextValue
+      } : change;
+    });
+
+    // Preserve currentValue a remote mirror already hydrated — oversized
+    // atoms arrive as VALUE_ON_DEVICE markers on every snapshot.
+    const hydratedAtoms = new Map();
+    for (const [label, atom] of this.atoms) {
+      try {
+        const value = atom.getValue();
+        const marker = value;
+        if (!marker || marker.__buoyValueOnDevice !== true) {
+          hydratedAtoms.set(label, value);
+        }
+      } catch {
+        // ignore
+      }
+    }
+    this.atoms = new Map(atomSnapshots.map(snapshot => {
+      const incoming = snapshot.currentValue;
+      const kept = hydratedAtoms.get(snapshot.label);
+      const currentValue = kept !== undefined && incoming?.__buoyValueOnDevice === true ? kept : snapshot.currentValue;
+      return [snapshot.label, {
+        label: snapshot.label,
+        changeCount: snapshot.changeCount,
+        color: snapshot.color,
+        getValue: () => currentValue,
+        // No setValue: the mirror has no wire back to the device from
+        // this entry (yet) — the detail screen renders read-only there.
+        writeKind: snapshot.writeKind
+      }];
+    }));
+    this.setItems(merged);
+    this.notifyAtomListeners();
+  }
+
+  /**
+   * Hydrate one mirrored change with real values fetched on demand from the
+   * device via the adapter's `getChangeDetail`. Remote-mirror (desktop) only.
+   */
+  hydrateChange(id, patch) {
+    this.hydrateById(id, patch);
+  }
+
+  /**
+   * Hydrate one mirrored atom's currentValue fetched on demand from the
+   * device via the adapter's `getAtomValue`. Remote-mirror (desktop) only.
+   */
+  hydrateAtomValue(label, currentValue) {
+    const atom = this.atoms.get(label);
+    if (!atom) return;
+    this.atoms.set(label, {
+      ...atom,
+      getValue: () => currentValue
+    });
+    this.notifyAtomListeners();
+  }
+
+  // ---- Atom Registry ----
+
+  registerAtom(label, getValue, setValue, writeKind) {
+    if (this.atoms.has(label)) return;
+    const atomInfo = {
+      label,
+      changeCount: 0,
+      color: getAtomColor(label),
+      getValue,
+      setValue,
+      writeKind
+    };
+    this.atoms.set(label, atomInfo);
+    this.notifyAtomListeners();
+  }
+
+  /**
+   * Write a value to a registered atom (remote write from the dashboard/MCP).
+   * Throws if the atom is unknown or read-only (derived atoms have no setter).
+   */
+  setAtomValue(label, value) {
+    const atom = this.atoms.get(label);
+    if (!atom) {
+      throw new Error(`Atom "${label}" is not registered`);
+    }
+    if (!atom.setValue) {
+      throw new Error(`Atom "${label}" is read-only (derived) — cannot set`);
+    }
+    atom.setValue(value);
+  }
+  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.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)));
+    }
+    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.items.length;
+    const withChanges = this.items.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 ----
+
+  setMaxChanges(max) {
+    this.setMax(max);
+  }
+
+  // ---- Subscriptions ----
+
+  subscribeToAtoms(listener) {
+    this.atomListeners.add(listener);
+    return () => this.atomListeners.delete(listener);
+  }
+  notifyAtomListeners() {
+    const atoms = this.getAtoms();
+    this.atomListeners.forEach(listener => listener(atoms));
+  }
+}
+export const jotaiStateStore = new JotaiStateStore();