@buoy-gg/zustand 7.0.35 → 7.0.36

package/lib/commonjs/zustand/sync/zustandSyncAdapter.js

@@ -4,8 +4,8 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.zustandSyncAdapter = exports.STATE_ON_DEVICE = exports.PAYLOAD_ON_DEVICE = void 0;
-var _zustandStateStore = require("../utils/zustandStateStore");
 var _sharedUi = require("@buoy-gg/shared-ui");
+var _zustandStateStore = require("../utils/zustandStateStore");
 /**
  * Sentinel used in WIRE-FORM snapshots in place of raw prevState/nextState.
  * Same hazard as redux: up to 200 changes × 2 full trees on every snapshot
@@ -15,6 +15,23 @@ const STATE_ON_DEVICE = exports.STATE_ON_DEVICE = (0, _sharedUi.onDeviceMarker)(
 
 /** Wire-form sentinel for an oversized `partial` (replace can carry a whole tree). */
 const PAYLOAD_ON_DEVICE = exports.PAYLOAD_ON_DEVICE = (0, _sharedUi.onDeviceMarker)("Payload", "Partial stays on the device — fetched on demand via getChangeDetail.");
+const isPlainObject = v => !!v && typeof v === "object" && !Array.isArray(v);
+/**
+ * Does this patch write into the list at `path`? Only then is an unchecked-shape
+ * warning about that list worth saying — a patch that changes `promoCode` should
+ * not be told about an empty `lines`.
+ */
+function touchesList(patch, path) {
+  let cur = patch;
+  for (const seg of path.split(".")) {
+    if (!cur || typeof cur !== "object" || Array.isArray(cur)) return false;
+    if (!(seg in cur)) return false;
+    cur = cur[seg];
+  }
+  // An empty list stays empty; there is no new item to be unsure about.
+  return Array.isArray(cur) ? cur.length > 0 : !!cur && typeof cur === "object";
+}
+
 /** Top-level keys of an object state, for the compact (no-values) view. */
 function topLevelKeys(state) {
   return state && typeof state === "object" && !Array.isArray(state) ? Object.keys(state) : undefined;
@@ -80,7 +97,8 @@ const zustandSyncAdapter = exports.zustandSyncAdapter = (0, _sharedUi.createSync
      */
     getStoreState: params => {
       const {
-        storeName
+        storeName,
+        path
       } = (0, _sharedUi.readParams)(params);
       if (!storeName) return {
         found: false,
@@ -97,16 +115,46 @@ const zustandSyncAdapter = exports.zustandSyncAdapter = (0, _sharedUi.createSync
       } catch {
         currentState = undefined;
       }
+      // One slice instead of the whole store. 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, which is the failure this
+      // whole surface keeps producing.
+      if (path) {
+        const at = (0, _sharedUi.readPath)(currentState, path);
+        if (!at.ok) return {
+          found: false,
+          reason: at.error
+        };
+        return {
+          found: true,
+          storeName,
+          path,
+          shape: (0, _sharedUi.shapeSummary)(at.value),
+          currentState: at.value
+        };
+      }
+      // The sketch goes BEFORE currentState, deliberately. The engine truncates
+      // a result by slicing the encoded string at 24,000 characters, so whatever
+      // is serialised first is what survives — and the reads most in need of a
+      // shape are exactly the long ones that get cut. It costs ~150 characters
+      // and does not grow with the data.
+      const shape = (0, _sharedUi.shapeSummary)(currentState);
       if (!(0, _sharedUi.isOverWireBudget)(currentState, _sharedUi.WIRE_DETAIL_LIMIT_BYTES)) {
         return {
           found: true,
           storeName,
+          ...(shape ? {
+            shape
+          } : {}),
           currentState
         };
       }
       return {
         found: true,
         storeName,
+        ...(shape ? {
+          shape
+        } : {}),
         currentState: (0, _sharedUi.isJsonSerializable)(currentState) ? (0, _sharedUi.truncatedNote)(_sharedUi.WIRE_DETAIL_LIMIT_BYTES) : STATE_ON_DEVICE
       };
     },
@@ -133,7 +181,13 @@ const zustandSyncAdapter = exports.zustandSyncAdapter = (0, _sharedUi.createSync
           currentState: s.currentState
         } : {
           keys: topLevelKeys(s.currentState)
-        })
+        }),
+        // Cheap enough to always include: this is the compact view a caller
+        // reaches for precisely because it does not want to pull the data, and
+        // the item shape of a list is the one thing it cannot infer without it.
+        ...((0, _sharedUi.shapeSummary)(s.currentState) ? {
+          shape: (0, _sharedUi.shapeSummary)(s.currentState)
+        } : {})
       }));
       return {
         stores,
@@ -146,8 +200,14 @@ const zustandSyncAdapter = exports.zustandSyncAdapter = (0, _sharedUi.createSync
       const {
         storeName,
         state,
-        replace
+        replace,
+        force,
+        path,
+        value
       } = (0, _sharedUi.readParams)(params);
+      let effective = state;
+      let keyedNotes = [];
+      let unchecked = [];
       if (!storeName) return {
         ok: false,
         error: "Missing storeName."
@@ -157,9 +217,112 @@ const zustandSyncAdapter = exports.zustandSyncAdapter = (0, _sharedUi.createSync
         ok: false,
         error: `No store named "${storeName}".`
       };
-      store.api.setState(state, replace ?? true);
+      // `path` is sugar over a merge: it can only ever produce a patch, which
+      // then goes through the guard below like any other. Its value is that
+      // there is no nesting depth for the caller to get wrong.
+      // `state` is no longer schema-required, because `path`+`value` is a valid
+      // alternative — so the handler has to be the thing that rejects NEITHER.
+      // Without this, `state` arrives undefined and falls through to
+      // `setState(undefined, true)`, which is zustand's whole-state replace: the
+      // store's data AND its action functions, gone, from a call that looks like
+      // a typo. This is the most destructive thing in this file.
+      if (state === undefined && path === undefined) {
+        return {
+          ok: false,
+          error: `Refused: no change was described. Send \`state\` with the fields to merge, or \`path\` and \`value\` to set one value.`
+        };
+      }
+      let pathed = false;
+      if (path !== undefined) {
+        if (value === undefined) {
+          return {
+            ok: false,
+            error: `Refused: sent \`path\` without \`value\`. Say what to set "${path}" to; if you mean to clear it, send value:null and the field must already be nullable.`
+          };
+        }
+        let currentForPath;
+        try {
+          currentForPath = store.api.getState();
+        } catch {
+          currentForPath = undefined;
+        }
+        const built = (0, _sharedUi.patchFromPath)(currentForPath, path, value);
+        if (!built.ok) return {
+          ok: false,
+          error: `Refused: ${built.error}`
+        };
+        effective = built.patch;
+        pathed = true;
+      }
+      // On a MERGE (replace:false), constrain it to a typed edit so a remote
+      // caller can't hand the store a field of the wrong type or a malformed
+      // new list item — the same protection the query cache has. A replace
+      // (whole-store reset) and an explicit `force` skip this.
+      if (!force && (replace === false || pathed)) {
+        let current;
+        try {
+          current = store.api.getState();
+        } catch {
+          current = undefined;
+        }
+        // Expand id-addressed list edits BEFORE validating, so the typed-edit
+        // guard below sees a real array and every existing protection still
+        // applies to the result.
+        if (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;
+        }
+        // The guard builds its template from `list[0]`, so a list that is EMPTY
+        // has no template and an added item is written with nothing to check it
+        // against. That is not a rare corner: it is every "add the first thing"
+        // flow, and it is where models invent shapes, because on an empty list
+        // the item shape genuinely exists nowhere in the running app. We cannot
+        // refuse it — refusing would break adding the first item to anything —
+        // so we say so instead of letting the guess through unremarked.
+        if (current !== undefined) {
+          unchecked = (0, _sharedUi.unshapedLists)(current).filter(path => touchesList(effective, path));
+        }
+        if (current !== undefined) {
+          const violations = (0, _sharedUi.typedEditViolations)(current, effective, {
+            noun: "store"
+          });
+          if (violations.length > 0) {
+            return {
+              ok: false,
+              error: (0, _sharedUi.refusalText)(violations, "store", (0, _sharedUi.suggestedPatch)(effective, violations)),
+              ...((0, _sharedUi.suggestedPatch)(effective, violations) ? {
+                suggestedState: (0, _sharedUi.suggestedPatch)(effective, violations)
+              } : {}),
+              violations
+            };
+          }
+        }
+      }
+      // A pathed write is a merge by construction — it names one value, so it
+      // must never fall through to zustand's default whole-state replace.
+      store.api.setState(effective, pathed ? false : replace ?? true);
+      // Say what an addressed edit resolved to. A caller that meant to change one
+      // line and sees "17 item(s) remain" has caught its own mistake.
       return {
-        ok: true
+        ok: true,
+        ...(path !== undefined ? {
+          path
+        } : {}),
+        ...(keyedNotes.length ? {
+          keyed: keyedNotes
+        } : {}),
+        ...(unchecked.length ? {
+          unchecked: unchecked.map(path => `\`${path}\` was empty, so nothing in the app knows what its items look like and the shape of what you added was NOT checked. If the app renders a field you left out, it will render undefined — read the store back and compare against how the screen uses it.`)
+        } : {})
       };
     },
     /**

package/lib/module/zustand/sync/zustandSyncAdapter.js

@@ -1,5 +1,6 @@
 "use strict";
 
+import { expandKeyedArrays, patchFromPath, readPath, refusalText, shapeSummary, suggestedPatch, typedEditViolations, unshapedLists } from "@buoy-gg/shared-ui";
 import { zustandStateStore } from "../utils/zustandStateStore";
 import { WIRE_DETAIL_LIMIT_BYTES, createSyncAdapter, detailByIdAction, isJsonSerializable, isOverWireBudget, memoByIdentity, onDeviceMarker, readParams, toWire, truncatedNote } from "@buoy-gg/shared-ui";
 
@@ -12,6 +13,23 @@ export const STATE_ON_DEVICE = onDeviceMarker("State", "State trees stay on the
 
 /** Wire-form sentinel for an oversized `partial` (replace can carry a whole tree). */
 export const PAYLOAD_ON_DEVICE = onDeviceMarker("Payload", "Partial stays on the device — fetched on demand via getChangeDetail.");
+const isPlainObject = v => !!v && typeof v === "object" && !Array.isArray(v);
+/**
+ * Does this patch write into the list at `path`? Only then is an unchecked-shape
+ * warning about that list worth saying — a patch that changes `promoCode` should
+ * not be told about an empty `lines`.
+ */
+function touchesList(patch, path) {
+  let cur = patch;
+  for (const seg of path.split(".")) {
+    if (!cur || typeof cur !== "object" || Array.isArray(cur)) return false;
+    if (!(seg in cur)) return false;
+    cur = cur[seg];
+  }
+  // An empty list stays empty; there is no new item to be unsure about.
+  return Array.isArray(cur) ? cur.length > 0 : !!cur && typeof cur === "object";
+}
+
 /** Top-level keys of an object state, for the compact (no-values) view. */
 function topLevelKeys(state) {
   return state && typeof state === "object" && !Array.isArray(state) ? Object.keys(state) : undefined;
@@ -77,7 +95,8 @@ export const zustandSyncAdapter = createSyncAdapter({
      */
     getStoreState: params => {
       const {
-        storeName
+        storeName,
+        path
       } = readParams(params);
       if (!storeName) return {
         found: false,
@@ -94,16 +113,46 @@ export const zustandSyncAdapter = createSyncAdapter({
       } catch {
         currentState = undefined;
       }
+      // One slice instead of the whole store. 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, which is the failure this
+      // whole surface keeps producing.
+      if (path) {
+        const at = readPath(currentState, path);
+        if (!at.ok) return {
+          found: false,
+          reason: at.error
+        };
+        return {
+          found: true,
+          storeName,
+          path,
+          shape: shapeSummary(at.value),
+          currentState: at.value
+        };
+      }
+      // The sketch goes BEFORE currentState, deliberately. The engine truncates
+      // a result by slicing the encoded string at 24,000 characters, so whatever
+      // is serialised first is what survives — and the reads most in need of a
+      // shape are exactly the long ones that get cut. It costs ~150 characters
+      // and does not grow with the data.
+      const shape = shapeSummary(currentState);
       if (!isOverWireBudget(currentState, WIRE_DETAIL_LIMIT_BYTES)) {
         return {
           found: true,
           storeName,
+          ...(shape ? {
+            shape
+          } : {}),
           currentState
         };
       }
       return {
         found: true,
         storeName,
+        ...(shape ? {
+          shape
+        } : {}),
         currentState: isJsonSerializable(currentState) ? truncatedNote(WIRE_DETAIL_LIMIT_BYTES) : STATE_ON_DEVICE
       };
     },
@@ -130,7 +179,13 @@ export const zustandSyncAdapter = createSyncAdapter({
           currentState: s.currentState
         } : {
           keys: topLevelKeys(s.currentState)
-        })
+        }),
+        // Cheap enough to always include: this is the compact view a caller
+        // reaches for precisely because it does not want to pull the data, and
+        // the item shape of a list is the one thing it cannot infer without it.
+        ...(shapeSummary(s.currentState) ? {
+          shape: shapeSummary(s.currentState)
+        } : {})
       }));
       return {
         stores,
@@ -143,8 +198,14 @@ export const zustandSyncAdapter = createSyncAdapter({
       const {
         storeName,
         state,
-        replace
+        replace,
+        force,
+        path,
+        value
       } = readParams(params);
+      let effective = state;
+      let keyedNotes = [];
+      let unchecked = [];
       if (!storeName) return {
         ok: false,
         error: "Missing storeName."
@@ -154,9 +215,112 @@ export const zustandSyncAdapter = createSyncAdapter({
         ok: false,
         error: `No store named "${storeName}".`
       };
-      store.api.setState(state, replace ?? true);
+      // `path` is sugar over a merge: it can only ever produce a patch, which
+      // then goes through the guard below like any other. Its value is that
+      // there is no nesting depth for the caller to get wrong.
+      // `state` is no longer schema-required, because `path`+`value` is a valid
+      // alternative — so the handler has to be the thing that rejects NEITHER.
+      // Without this, `state` arrives undefined and falls through to
+      // `setState(undefined, true)`, which is zustand's whole-state replace: the
+      // store's data AND its action functions, gone, from a call that looks like
+      // a typo. This is the most destructive thing in this file.
+      if (state === undefined && path === undefined) {
+        return {
+          ok: false,
+          error: `Refused: no change was described. Send \`state\` with the fields to merge, or \`path\` and \`value\` to set one value.`
+        };
+      }
+      let pathed = false;
+      if (path !== undefined) {
+        if (value === undefined) {
+          return {
+            ok: false,
+            error: `Refused: sent \`path\` without \`value\`. Say what to set "${path}" to; if you mean to clear it, send value:null and the field must already be nullable.`
+          };
+        }
+        let currentForPath;
+        try {
+          currentForPath = store.api.getState();
+        } catch {
+          currentForPath = undefined;
+        }
+        const built = patchFromPath(currentForPath, path, value);
+        if (!built.ok) return {
+          ok: false,
+          error: `Refused: ${built.error}`
+        };
+        effective = built.patch;
+        pathed = true;
+      }
+      // On a MERGE (replace:false), constrain it to a typed edit so a remote
+      // caller can't hand the store a field of the wrong type or a malformed
+      // new list item — the same protection the query cache has. A replace
+      // (whole-store reset) and an explicit `force` skip this.
+      if (!force && (replace === false || pathed)) {
+        let current;
+        try {
+          current = store.api.getState();
+        } catch {
+          current = undefined;
+        }
+        // Expand id-addressed list edits BEFORE validating, so the typed-edit
+        // guard below sees a real array and every existing protection still
+        // applies to the result.
+        if (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;
+        }
+        // The guard builds its template from `list[0]`, so a list that is EMPTY
+        // has no template and an added item is written with nothing to check it
+        // against. That is not a rare corner: it is every "add the first thing"
+        // flow, and it is where models invent shapes, because on an empty list
+        // the item shape genuinely exists nowhere in the running app. We cannot
+        // refuse it — refusing would break adding the first item to anything —
+        // so we say so instead of letting the guess through unremarked.
+        if (current !== undefined) {
+          unchecked = unshapedLists(current).filter(path => touchesList(effective, path));
+        }
+        if (current !== undefined) {
+          const violations = typedEditViolations(current, effective, {
+            noun: "store"
+          });
+          if (violations.length > 0) {
+            return {
+              ok: false,
+              error: refusalText(violations, "store", suggestedPatch(effective, violations)),
+              ...(suggestedPatch(effective, violations) ? {
+                suggestedState: suggestedPatch(effective, violations)
+              } : {}),
+              violations
+            };
+          }
+        }
+      }
+      // A pathed write is a merge by construction — it names one value, so it
+      // must never fall through to zustand's default whole-state replace.
+      store.api.setState(effective, pathed ? false : replace ?? true);
+      // Say what an addressed edit resolved to. A caller that meant to change one
+      // line and sees "17 item(s) remain" has caught its own mistake.
       return {
-        ok: true
+        ok: true,
+        ...(path !== undefined ? {
+          path
+        } : {}),
+        ...(keyedNotes.length ? {
+          keyed: keyedNotes
+        } : {}),
+        ...(unchecked.length ? {
+          unchecked: unchecked.map(path => `\`${path}\` was empty, so nothing in the app knows what its items look like and the shape of what you added was NOT checked. If the app renders a field you left out, it will render undefined — read the store back and compare against how the screen uses it.`)
+        } : {})
       };
     },
     /**

package/lib/typescript/zustand/sync/zustandSyncAdapter.d.ts

@@ -63,12 +63,29 @@ export declare const zustandSyncAdapter: import("@buoy-gg/shared-ui").SyncAdapte
         found: false;
         reason: string;
         storeName?: undefined;
+        path?: undefined;
+        shape?: undefined;
         currentState?: undefined;
     } | {
         found: true;
         storeName: string;
+        path: string;
+        shape: {
+            shape: string;
+            lists?: import("@buoy-gg/shared-ui").ListShape[];
+        } | undefined;
         currentState: unknown;
         reason?: undefined;
+    } | {
+        currentState: unknown;
+        shape?: {
+            shape: string;
+            lists?: import("@buoy-gg/shared-ui").ListShape[];
+        } | undefined;
+        found: true;
+        storeName: string;
+        reason?: undefined;
+        path?: undefined;
     };
     /**
      * Compact current-state reader for a remote driver (MCP/LLM): the registered
@@ -78,6 +95,10 @@ export declare const zustandSyncAdapter: import("@buoy-gg/shared-ui").SyncAdapte
      */
     listStores: (params?: unknown) => {
         stores: ({
+            shape?: {
+                shape: string;
+                lists?: import("@buoy-gg/shared-ui").ListShape[];
+            } | undefined;
             currentState: unknown;
             name: string;
             changes: number;
@@ -85,6 +106,10 @@ export declare const zustandSyncAdapter: import("@buoy-gg/shared-ui").SyncAdapte
             persistName: string | undefined;
             canRehydrate: boolean | undefined;
         } | {
+            shape?: {
+                shape: string;
+                lists?: import("@buoy-gg/shared-ui").ListShape[];
+            } | undefined;
             keys: string[] | undefined;
             name: string;
             changes: number;
@@ -100,7 +125,15 @@ export declare const zustandSyncAdapter: import("@buoy-gg/shared-ui").SyncAdapte
         ok: boolean;
         error: string;
     } | {
+        violations: import("@buoy-gg/shared-ui").EditViolation[];
+        suggestedState?: Record<string, unknown> | undefined;
         ok: boolean;
+        error: string;
+    } | {
+        unchecked?: string[] | undefined;
+        keyed?: string[] | undefined;
+        path?: string | undefined;
+        ok: true;
         error?: undefined;
     };
     /**

package/lib/typescript/zustand/sync/zustandSyncAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zustandSyncAdapter.d.ts","sourceRoot":"","sources":["../../../../src/zustand/sync/zustandSyncAdapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAenD;;;;GAIG;AACH,eAAO,MAAM,eAAe;;;;EAG3B,CAAC;AAEF,sFAAsF;AACtF,eAAO,MAAM,iBAAiB;;;;EAG7B,CAAC;AAsCF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;IAiB3B;;;;OAIG;;;;;;IASH;;;OAGG;6BACsB,OAAO;;;;;;;;;;;IAsBhC;;;;;OAKG;0BACmB,OAAO;;;;;;;;;;;;;;;;;;;;wBAsBT,OAAO;;;;;;;IAQ3B;;;;;;;;;;;;;;;;;;;;OAoBG;yBACwB,OAAO;;;;;;;;;;;EAqBV,CAAC"}
+{"version":3,"file":"zustandSyncAdapter.d.ts","sourceRoot":"","sources":["../../../../src/zustand/sync/zustandSyncAdapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAenD;;;;GAIG;AACH,eAAO,MAAM,eAAe;;;;EAG3B,CAAC;AAEF,sFAAsF;AACtF,eAAO,MAAM,iBAAiB;;;;EAG7B,CAAC;AAuEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;IAiB3B;;;;OAIG;;;;;;IASH;;;OAGG;6BACsB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAsChC;;;;;OAKG;0BACmB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBA0BT,OAAO;;;;;;;;;;;;;;;IAwG3B;;;;;;;;;;;;;;;;;;;;OAoBG;yBACwB,OAAO;;;;;;;;;;;EAqBV,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buoy-gg/zustand",
-  "version": "7.0.35",
+  "version": "7.0.36",
   "description": "Zustand devtools inside your React Native app — state diffs, jump-to-state & one-tap store reset, no middleware. 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/shared-ui": "^7.0.36",
+    "@buoy-gg/license": "^7.0.36"
   },
   "peerDependencies": {
     "react": "*",