@buoy-gg/jotai 7.0.34 → 7.0.36

package/lib/commonjs/jotai/components/JotaiAtomBrowser.js

@@ -165,7 +165,7 @@ const styles = _reactNative.StyleSheet.create({
   absCountText: {
     fontSize: 9,
     fontWeight: "700",
-    fontFamily: "monospace"
+    fontFamily: _sharedUi.monoFont
   },
   scrollContent: {
     paddingTop: 8,
@@ -194,6 +194,6 @@ const styles = _reactNative.StyleSheet.create({
     fontSize: 10,
     fontWeight: "700",
     color: _sharedUi.night.color.accent,
-    fontFamily: "monospace"
+    fontFamily: _sharedUi.monoFont
   }
 });

package/lib/commonjs/jotai/components/JotaiAtomDetailContent.js

@@ -481,7 +481,7 @@ const styles = _reactNative.StyleSheet.create({
   valueLabel: {
     fontSize: 10,
     color: _sharedUi.night.color.textSecondary,
-    fontFamily: "monospace",
+    fontFamily: _sharedUi.monoFont,
     letterSpacing: 0.5,
     fontWeight: "600"
   },
@@ -498,7 +498,7 @@ const styles = _reactNative.StyleSheet.create({
   changeText: {
     fontSize: 9,
     fontWeight: "700",
-    fontFamily: "monospace",
+    fontFamily: _sharedUi.monoFont,
     letterSpacing: 0.3
   },
   typeBadge: {
@@ -511,7 +511,7 @@ const styles = _reactNative.StyleSheet.create({
     fontSize: 9,
     fontWeight: "600",
     color: _sharedUi.night.color.textTertiary,
-    fontFamily: "monospace"
+    fontFamily: _sharedUi.monoFont
   },
   valueBox: {
     // Inset code box — darker than the card, the night track color.
@@ -524,7 +524,7 @@ const styles = _reactNative.StyleSheet.create({
   valueText: {
     fontSize: 12,
     color: _sharedUi.night.color.text,
-    fontFamily: "monospace",
+    fontFamily: _sharedUi.monoFont,
     lineHeight: 18
   },
   diffContainer: {
@@ -542,7 +542,7 @@ const styles = _reactNative.StyleSheet.create({
   changeTextSmall: {
     fontSize: 8,
     fontWeight: "700",
-    fontFamily: "monospace"
+    fontFamily: _sharedUi.monoFont
   }
 });
 const infoStyles = _reactNative.StyleSheet.create({
@@ -588,7 +588,7 @@ const infoStyles = _reactNative.StyleSheet.create({
     fontWeight: "600",
     letterSpacing: 0.5,
     color: _sharedUi.night.color.accent,
-    fontFamily: "monospace"
+    fontFamily: _sharedUi.monoFont
   },
   cardContent: {
     padding: 14,
@@ -613,7 +613,7 @@ const infoStyles = _reactNative.StyleSheet.create({
     marginLeft: 12
   },
   infoValueMono: {
-    fontFamily: "monospace"
+    fontFamily: _sharedUi.monoFont
   },
   badgeRow: {
     flexDirection: "row",
@@ -673,7 +673,7 @@ const infoStyles = _reactNative.StyleSheet.create({
     fontSize: 11,
     fontWeight: "600",
     color: _sharedUi.night.color.accent,
-    fontFamily: "monospace"
+    fontFamily: _sharedUi.monoFont
   },
   countBadge: {
     paddingHorizontal: 8,
@@ -685,7 +685,7 @@ const infoStyles = _reactNative.StyleSheet.create({
     fontSize: 9,
     fontWeight: "700",
     color: _sharedUi.night.color.accent,
-    fontFamily: "monospace"
+    fontFamily: _sharedUi.monoFont
   },
   actionsRow: {
     flexDirection: "row",
@@ -704,7 +704,7 @@ const infoStyles = _reactNative.StyleSheet.create({
   actionButtonText: {
     fontSize: 10,
     fontWeight: "700",
-    fontFamily: "monospace",
+    fontFamily: _sharedUi.monoFont,
     letterSpacing: 0.3
   },
   dataViewerContainer: {

package/lib/commonjs/jotai/components/JotaiAtomValueDetailContent.js

@@ -364,7 +364,7 @@ const styles = _reactNative.StyleSheet.create({
     color: _sharedUi.night.color.accent,
     letterSpacing: 0.5,
     textTransform: "uppercase",
-    fontFamily: "monospace"
+    fontFamily: _sharedUi.monoFont
   },
   rawButton: {
     flexDirection: "row",
@@ -411,7 +411,7 @@ const styles = _reactNative.StyleSheet.create({
     borderBottomColor: _sharedUi.night.color.border,
     letterSpacing: 0.5,
     textTransform: "uppercase",
-    fontFamily: "monospace"
+    fontFamily: _sharedUi.monoFont
   },
   infoBody: {
     padding: 12,
@@ -424,13 +424,13 @@ const styles = _reactNative.StyleSheet.create({
   primitiveText: {
     color: _sharedUi.night.color.text,
     fontSize: 12,
-    fontFamily: "monospace",
+    fontFamily: _sharedUi.monoFont,
     padding: 14
   },
   valueTypeText: {
     color: _sharedUi.night.color.textTertiary,
     fontSize: 10,
-    fontFamily: "monospace",
+    fontFamily: _sharedUi.monoFont,
     marginLeft: 6
   },
   inlineLinkButton: {
@@ -439,6 +439,6 @@ const styles = _reactNative.StyleSheet.create({
   inlineLinkText: {
     fontSize: 10,
     fontWeight: "600",
-    fontFamily: "monospace"
+    fontFamily: _sharedUi.monoFont
   }
 });

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/components/JotaiAtomBrowser.js

@@ -11,7 +11,7 @@
 
 import { useMemo } from "react";
 import { View, Text, StyleSheet, ScrollView } from "react-native";
-import { CompactRow, night, ToolEmptyState, resolveListEmptyState } from "@buoy-gg/shared-ui";
+import { CompactRow, night, ToolEmptyState, resolveListEmptyState, monoFont } from "@buoy-gg/shared-ui";
 import { jotaiStateStore } from "../utils/jotaiStateStore";
 import { JOTAI_TEST_ID, atomRowTestID } from "../utils/testIDs";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
@@ -161,7 +161,7 @@ const styles = StyleSheet.create({
   absCountText: {
     fontSize: 9,
     fontWeight: "700",
-    fontFamily: "monospace"
+    fontFamily: monoFont
   },
   scrollContent: {
     paddingTop: 8,
@@ -190,6 +190,6 @@ const styles = StyleSheet.create({
     fontSize: 10,
     fontWeight: "700",
     color: night.color.accent,
-    fontFamily: "monospace"
+    fontFamily: monoFont
   }
 });

package/lib/module/jotai/components/JotaiAtomDetailContent.js

@@ -13,7 +13,7 @@
 
 import React, { memo, useState, useCallback, useMemo } from "react";
 import { View, Text, StyleSheet, ScrollView } from "react-native";
-import { buoyColors, night, EventStepperFooter, formatRelativeTime, parseValue, Info, Zap, FileText, Database, GitBranch, copyToClipboard, ProUpgradeModal, DiffModeTabs, CompareBar, DetailViewToggle } from "@buoy-gg/shared-ui";
+import { buoyColors, night, EventStepperFooter, formatRelativeTime, parseValue, Info, Zap, FileText, Database, GitBranch, copyToClipboard, ProUpgradeModal, DiffModeTabs, CompareBar, DetailViewToggle, monoFont } from "@buoy-gg/shared-ui";
 import { DataViewer, SplitDiffViewer, TreeDiffViewer, diffThemes } from "@buoy-gg/shared-ui/dataViewer";
 import { useIsPro } from "@buoy-gg/license";
 import { jotaiStateStore } from "../utils/jotaiStateStore";
@@ -476,7 +476,7 @@ const styles = StyleSheet.create({
   valueLabel: {
     fontSize: 10,
     color: night.color.textSecondary,
-    fontFamily: "monospace",
+    fontFamily: monoFont,
     letterSpacing: 0.5,
     fontWeight: "600"
   },
@@ -493,7 +493,7 @@ const styles = StyleSheet.create({
   changeText: {
     fontSize: 9,
     fontWeight: "700",
-    fontFamily: "monospace",
+    fontFamily: monoFont,
     letterSpacing: 0.3
   },
   typeBadge: {
@@ -506,7 +506,7 @@ const styles = StyleSheet.create({
     fontSize: 9,
     fontWeight: "600",
     color: night.color.textTertiary,
-    fontFamily: "monospace"
+    fontFamily: monoFont
   },
   valueBox: {
     // Inset code box — darker than the card, the night track color.
@@ -519,7 +519,7 @@ const styles = StyleSheet.create({
   valueText: {
     fontSize: 12,
     color: night.color.text,
-    fontFamily: "monospace",
+    fontFamily: monoFont,
     lineHeight: 18
   },
   diffContainer: {
@@ -537,7 +537,7 @@ const styles = StyleSheet.create({
   changeTextSmall: {
     fontSize: 8,
     fontWeight: "700",
-    fontFamily: "monospace"
+    fontFamily: monoFont
   }
 });
 const infoStyles = StyleSheet.create({
@@ -583,7 +583,7 @@ const infoStyles = StyleSheet.create({
     fontWeight: "600",
     letterSpacing: 0.5,
     color: night.color.accent,
-    fontFamily: "monospace"
+    fontFamily: monoFont
   },
   cardContent: {
     padding: 14,
@@ -608,7 +608,7 @@ const infoStyles = StyleSheet.create({
     marginLeft: 12
   },
   infoValueMono: {
-    fontFamily: "monospace"
+    fontFamily: monoFont
   },
   badgeRow: {
     flexDirection: "row",
@@ -668,7 +668,7 @@ const infoStyles = StyleSheet.create({
     fontSize: 11,
     fontWeight: "600",
     color: night.color.accent,
-    fontFamily: "monospace"
+    fontFamily: monoFont
   },
   countBadge: {
     paddingHorizontal: 8,
@@ -680,7 +680,7 @@ const infoStyles = StyleSheet.create({
     fontSize: 9,
     fontWeight: "700",
     color: night.color.accent,
-    fontFamily: "monospace"
+    fontFamily: monoFont
   },
   actionsRow: {
     flexDirection: "row",
@@ -699,7 +699,7 @@ const infoStyles = StyleSheet.create({
   actionButtonText: {
     fontSize: 10,
     fontWeight: "700",
-    fontFamily: "monospace",
+    fontFamily: monoFont,
     letterSpacing: 0.3
   },
   dataViewerContainer: {

package/lib/module/jotai/components/JotaiAtomValueDetailContent.js

@@ -34,7 +34,7 @@
 
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { ScrollView, StyleSheet, Text, TouchableOpacity, View } from "react-native";
-import { buoyColors, ExpandedInfoRow, FileJson, night, PillBadge, parseValue } from "@buoy-gg/shared-ui";
+import { buoyColors, ExpandedInfoRow, FileJson, night, PillBadge, parseValue, monoFont } from "@buoy-gg/shared-ui";
 import { DataViewer, LiveExplorer, ValueEditModal, updateNestedDataByPath, deleteNestedDataByPath } from "@buoy-gg/shared-ui/dataViewer";
 import { jotaiStateStore } from "../utils/jotaiStateStore";
 import { JOTAI_TEST_ID, atomRowTestID } from "../utils/testIDs";
@@ -362,7 +362,7 @@ const styles = StyleSheet.create({
     color: night.color.accent,
     letterSpacing: 0.5,
     textTransform: "uppercase",
-    fontFamily: "monospace"
+    fontFamily: monoFont
   },
   rawButton: {
     flexDirection: "row",
@@ -409,7 +409,7 @@ const styles = StyleSheet.create({
     borderBottomColor: night.color.border,
     letterSpacing: 0.5,
     textTransform: "uppercase",
-    fontFamily: "monospace"
+    fontFamily: monoFont
   },
   infoBody: {
     padding: 12,
@@ -422,13 +422,13 @@ const styles = StyleSheet.create({
   primitiveText: {
     color: night.color.text,
     fontSize: 12,
-    fontFamily: "monospace",
+    fontFamily: monoFont,
     padding: 14
   },
   valueTypeText: {
     color: night.color.textTertiary,
     fontSize: 10,
-    fontFamily: "monospace",
+    fontFamily: monoFont,
     marginLeft: 6
   },
   inlineLinkButton: {
@@ -437,6 +437,6 @@ const styles = StyleSheet.create({
   inlineLinkText: {
     fontSize: 10,
     fontWeight: "600",
-    fontFamily: "monospace"
+    fontFamily: monoFont
   }
 });

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/components/JotaiAtomBrowser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"JotaiAtomBrowser.d.ts","sourceRoot":"","sources":["../../../../src/jotai/components/JotaiAtomBrowser.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAeH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAI9C,UAAU,qBAAqB;IAC7B,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC;AAuDD,wBAAgB,gBAAgB,CAAC,EAC/B,KAAK,EACL,WAAW,EACX,UAAU,GACX,EAAE,qBAAqB,+BA4FvB"}
+{"version":3,"file":"JotaiAtomBrowser.d.ts","sourceRoot":"","sources":["../../../../src/jotai/components/JotaiAtomBrowser.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgBH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAI9C,UAAU,qBAAqB;IAC7B,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC;AAuDD,wBAAgB,gBAAgB,CAAC,EAC/B,KAAK,EACL,WAAW,EACX,UAAU,GACX,EAAE,qBAAqB,+BA4FvB"}

package/lib/typescript/jotai/components/JotaiAtomDetailContent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"JotaiAtomDetailContent.d.ts","sourceRoot":"","sources":["../../../../src/jotai/components/JotaiAtomDetailContent.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAA+C,MAAM,OAAO,CAAC;AA4BpE,OAAO,KAAK,EACV,eAAe,EAEf,mBAAmB,EACpB,MAAM,UAAU,CAAC;AAwOlB,UAAU,2BAA2B;IACnC,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;OAGG;IACH,WAAW,CAAC,EAAE,mBAAmB,CAAC;CACnC;AAED,wBAAgB,sBAAsB,CAAC,EACrC,MAAM,EACN,OAAO,EACP,aAAa,EACb,aAAa,EACb,qBAA6B,EAC7B,WAAsB,GACvB,EAAE,2BAA2B,qBAkL7B;AAED,wBAAgB,qBAAqB,CAAC,EACpC,MAAM,EACN,OAAO,EACP,aAAa,EACb,aAAa,GACd,EAAE;IACD,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC,4BAcA"}
+{"version":3,"file":"JotaiAtomDetailContent.d.ts","sourceRoot":"","sources":["../../../../src/jotai/components/JotaiAtomDetailContent.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAA+C,MAAM,OAAO,CAAC;AA6BpE,OAAO,KAAK,EACV,eAAe,EAEf,mBAAmB,EACpB,MAAM,UAAU,CAAC;AAwOlB,UAAU,2BAA2B;IACnC,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;OAGG;IACH,WAAW,CAAC,EAAE,mBAAmB,CAAC;CACnC;AAED,wBAAgB,sBAAsB,CAAC,EACrC,MAAM,EACN,OAAO,EACP,aAAa,EACb,aAAa,EACb,qBAA6B,EAC7B,WAAsB,GACvB,EAAE,2BAA2B,qBAkL7B;AAED,wBAAgB,qBAAqB,CAAC,EACpC,MAAM,EACN,OAAO,EACP,aAAa,EACb,aAAa,GACd,EAAE;IACD,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC,4BAcA"}

package/lib/typescript/jotai/components/JotaiAtomValueDetailContent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"JotaiAtomValueDetailContent.d.ts","sourceRoot":"","sources":["../../../../src/jotai/components/JotaiAtomValueDetailContent.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AA0BH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAoE9C,UAAU,gCAAgC;IACxC,IAAI,EAAE,aAAa,CAAC;IACpB,kEAAkE;IAClE,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C;AAED,wBAAgB,2BAA2B,CAAC,EAC1C,IAAI,EACJ,aAAa,GACd,EAAE,gCAAgC,+BA6OlC"}
+{"version":3,"file":"JotaiAtomValueDetailContent.d.ts","sourceRoot":"","sources":["../../../../src/jotai/components/JotaiAtomValueDetailContent.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AA2BH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAoE9C,UAAU,gCAAgC;IACxC,IAAI,EAAE,aAAa,CAAC;IACpB,kEAAkE;IAClE,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C;AAED,wBAAgB,2BAA2B,CAAC,EAC1C,IAAI,EACJ,aAAa,GACd,EAAE,gCAAgC,+BA6OlC"}

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.34",
+  "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.34",
-    "@buoy-gg/license": "^7.0.34"
+    "@buoy-gg/license": "^7.0.36",
+    "@buoy-gg/shared-ui": "^7.0.36"
   },
   "peerDependencies": {
     "jotai": ">=2.0.0",