@buoy-gg/jotai 7.0.35 → 7.0.36

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

@@ -12,6 +12,41 @@ var _sharedUi = require("@buoy-gg/shared-ui");
  * snapshot. Dashboards fetch values via `getChangeDetail`.
  */
 const VALUE_ON_DEVICE = exports.VALUE_ON_DEVICE = (0, _sharedUi.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.
@@ -66,7 +101,8 @@ const jotaiSyncAdapter = exports.jotaiSyncAdapter = (0, _sharedUi.createSyncAdap
      */
     getAtomValue: params => {
       const {
-        label
+        label,
+        path
       } = (0, _sharedUi.readParams)(params);
       if (!label) return {
         found: false,
@@ -92,9 +128,32 @@ const jotaiSyncAdapter = exports.jotaiSyncAdapter = (0, _sharedUi.createSyncAdap
           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 = (0, _sharedUi.readPath)(currentValue, path);
+        if (!at.ok) return {
+          found: false,
+          reason: at.error
+        };
+        return {
+          found: true,
+          label,
+          path,
+          shape: (0, _sharedUi.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,
+        ...((0, _sharedUi.shapeSummary)(currentValue) ? {
+          shape: (0, _sharedUi.shapeSummary)(currentValue)
+        } : {}),
         currentValue: (0, _sharedUi.capDetail)(currentValue, _sharedUi.WIRE_DETAIL_LIMIT_BYTES)
       };
     },
@@ -120,10 +179,22 @@ const jotaiSyncAdapter = exports.jotaiSyncAdapter = (0, _sharedUi.createSyncAdap
             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 = (0, _sharedUi.shapeSummary)(a.getValue());
+        } catch {
+          shape = undefined;
+        }
         return {
           label: a.label,
           changes: a.changeCount,
           writable: typeof a.setValue === "function",
+          ...(shape ? {
+            shape
+          } : {}),
           ...(includeValues ? {
             currentValue: value
           } : {})
@@ -136,14 +207,100 @@ const jotaiSyncAdapter = exports.jotaiSyncAdapter = (0, _sharedUi.createSyncAdap
         includedValues: includeValues
       };
     },
-    /** Write a value to a writable atom (throws for unknown/read-only atoms). */
+    /**
+     * 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
+        value,
+        merge,
+        path,
+        force
       } = (0, _sharedUi.readParams)(params);
       if (!label) throw new Error("setAtom requires a `label`");
-      _jotaiStateStore.jotaiStateStore.setAtomValue(label, value);
+      const atom = _jotaiStateStore.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 = (0, _sharedUi.patchFromPath)(current, path, value);
+        if (!built.ok) return {
+          ok: false,
+          error: `Refused: ${built.error}`
+        };
+        effective = built.patch;
+      }
+      if (!force && merging && current !== undefined) {
+        const expanded = (0, _sharedUi.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 = (0, _sharedUi.unshapedLists)(current).filter(p => touchesList(effective, p));
+        const violations = (0, _sharedUi.typedEditViolations)(current, effective, {
+          noun: "atom"
+        });
+        if (violations.length) {
+          const suggestion = (0, _sharedUi.suggestedPatch)(effective, violations);
+          return {
+            ok: false,
+            error: (0, _sharedUi.refusalText)(violations, "atom", suggestion),
+            violations,
+            ...(suggestion ? {
+              suggestedValue: suggestion
+            } : {})
+          };
+        }
+      }
+      _jotaiStateStore.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/sync/jotaiSyncAdapter.js

@@ -1,7 +1,7 @@
 "use strict";
 
 import { jotaiStateStore } from "../utils/jotaiStateStore";
-import { WIRE_DETAIL_LIMIT_BYTES, createSyncAdapter, capDetail, detailByIdAction, memoByIdentity, onDeviceMarker, readParams, toWire } from "@buoy-gg/shared-ui";
+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.
@@ -9,6 +9,41 @@ import { WIRE_DETAIL_LIMIT_BYTES, createSyncAdapter, capDetail, detailByIdAction
  * 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.
@@ -63,7 +98,8 @@ export const jotaiSyncAdapter = createSyncAdapter({
      */
     getAtomValue: params => {
       const {
-        label
+        label,
+        path
       } = readParams(params);
       if (!label) return {
         found: false,
@@ -89,9 +125,32 @@ export const jotaiSyncAdapter = createSyncAdapter({
           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)
       };
     },
@@ -117,10 +176,22 @@ export const jotaiSyncAdapter = createSyncAdapter({
             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
           } : {})
@@ -133,14 +204,100 @@ export const jotaiSyncAdapter = createSyncAdapter({
         includedValues: includeValues
       };
     },
-    /** Write a value to a writable atom (throws for unknown/read-only atoms). */
+    /**
+     * 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
+        value,
+        merge,
+        path,
+        force
       } = readParams(params);
       if (!label) throw new Error("setAtom requires a `label`");
-      jotaiStateStore.setAtomValue(label, value);
+      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/typescript/jotai/sync/jotaiSyncAdapter.d.ts

@@ -51,12 +51,29 @@ export declare const jotaiSyncAdapter: import("@buoy-gg/shared-ui").SyncAdapter<
         found: false;
         reason: string;
         label?: undefined;
+        path?: undefined;
+        shape?: undefined;
         currentValue?: undefined;
     } | {
         found: true;
         label: string;
+        path: string;
+        shape: {
+            shape: string;
+            lists?: import("@buoy-gg/shared-ui").ListShape[];
+        } | undefined;
         currentValue: unknown;
         reason?: undefined;
+    } | {
+        currentValue: unknown;
+        shape?: {
+            shape: string;
+            lists?: import("@buoy-gg/shared-ui").ListShape[];
+        } | undefined;
+        found: true;
+        label: string;
+        reason?: undefined;
+        path?: undefined;
     };
     /**
      * Compact current-value reader for a remote driver (MCP/LLM): registered
@@ -67,6 +84,10 @@ export declare const jotaiSyncAdapter: import("@buoy-gg/shared-ui").SyncAdapter<
     listAtoms: (params?: unknown) => {
         atoms: {
             currentValue?: unknown;
+            shape?: {
+                shape: string;
+                lists?: import("@buoy-gg/shared-ui").ListShape[];
+            } | undefined;
             label: string;
             changes: number;
             writable: boolean;
@@ -75,7 +96,36 @@ export declare const jotaiSyncAdapter: import("@buoy-gg/shared-ui").SyncAdapter<
         returned: number;
         includedValues: boolean;
     };
-    /** Write a value to a writable atom (throws for unknown/read-only atoms). */
-    setAtom: (params?: unknown) => void;
+    /**
+     * 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?: unknown) => {
+        ok: false;
+        error: string;
+    } | {
+        suggestedValue?: Record<string, unknown> | undefined;
+        ok: false;
+        error: string;
+        violations: import("@buoy-gg/shared-ui").EditViolation[];
+    } | {
+        unchecked?: string[] | undefined;
+        keyed?: string[] | undefined;
+        path?: string | undefined;
+        ok: true;
+        error?: undefined;
+    };
 }>;
 //# sourceMappingURL=jotaiSyncAdapter.d.ts.map

package/lib/typescript/jotai/sync/jotaiSyncAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jotaiSyncAdapter.d.ts","sourceRoot":"","sources":["../../../../src/jotai/sync/jotaiSyncAdapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAahD;;;;GAIG;AACH,eAAO,MAAM,eAAe;;;;EAG3B,CAAC;AA4BF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;IAiBzB;;;;OAIG;;;;;IAQH;;;OAGG;4BACqB,OAAO;;;;;;;;;;;IA0B/B;;;;;OAKG;yBACkB,OAAO;;;;;;;;;;;IA4B5B,6EAA6E;uBAC1D,OAAO;EAMF,CAAC"}
+{"version":3,"file":"jotaiSyncAdapter.d.ts","sourceRoot":"","sources":["../../../../src/jotai/sync/jotaiSyncAdapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAqBhD;;;;GAIG;AACH,eAAO,MAAM,eAAe;;;;EAG3B,CAAC;AAmFF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;IAiBzB;;;;OAIG;;;;;IAQH;;;OAGG;4BACqB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAsC/B;;;;;OAKG;yBACkB,OAAO;;;;;;;;;;;;;;;IAsC5B;;;;;;;;;;;;;;;OAeG;uBACgB,OAAO;;;;;;;;;;;;;;;EAiEF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buoy-gg/jotai",
-  "version": "7.0.35",
+  "version": "7.0.36",
   "description": "Jotai devtools inside your React Native app — every atom write shows prev → next, with per-atom history & live values. Part of Buoy devtools.",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -29,8 +29,8 @@
     "**/snapshotProvider.ts"
   ],
   "dependencies": {
-    "@buoy-gg/shared-ui": "^7.0.35",
-    "@buoy-gg/license": "^7.0.35"
+    "@buoy-gg/license": "^7.0.36",
+    "@buoy-gg/shared-ui": "^7.0.36"
   },
   "peerDependencies": {
     "jotai": ">=2.0.0",