@buoy-gg/zustand 7.0.40 → 7.0.42

package/lib/module/zustand/hooks/useZustandStateChanges.js

@@ -1,70 +1 @@
-"use strict";
-
-/**
- * Hook for consuming Zustand state changes from the store
- *
- * The subscribe / filter / pause / clear plumbing is shared `useChangeLog`;
- * this file owns the zustand-specific filter, stats and store registry.
- */
-
-import { useCallback, useMemo } from "react";
-import { useChangeLog, useSubscribedValue } from "@buoy-gg/shared-ui";
-import { zustandStateStore } from "../utils/zustandStateStore";
-function filterChanges(changes, filter) {
-  let filtered = changes;
-  if (filter.searchText) {
-    const search = filter.searchText.toLowerCase();
-    filtered = filtered.filter(c => c.storeName.toLowerCase().includes(search) || c.partialPreview.toLowerCase().includes(search) || c.changedKeys.some(k => k.toLowerCase().includes(search)));
-  }
-  if (filter.storeNames && filter.storeNames.length > 0) {
-    filtered = filtered.filter(c => filter.storeNames.includes(c.storeName));
-  }
-  if (filter.onlyWithChanges) {
-    filtered = filtered.filter(c => c.hasStateChange);
-  }
-  return filtered;
-}
-const readStores = () => zustandStateStore.getStores();
-const subscribeToStores = listener => zustandStateStore.subscribeToStores(listener);
-export function useZustandStateChanges() {
-  const log = useChangeLog(zustandStateStore, {
-    filterItems: filterChanges
-  });
-  const stores = useSubscribedValue(readStores, subscribeToStores);
-
-  // Get stats — derive directly from state
-  const stats = useMemo(() => {
-    const total = log.items.length;
-    const withChanges = log.items.filter(c => c.hasStateChange).length;
-    return {
-      totalChanges: total,
-      changesWithStateChange: withChanges,
-      changesWithoutStateChange: total - withChanges,
-      storeCount: stores.length,
-      averageDuration: 0
-    };
-  }, [log.items, stores]);
-
-  // Get unique store names
-  const storeNames = useMemo(() => {
-    return zustandStateStore.getUniqueStoreNames();
-  }, [stores]);
-  const getChangeById = useCallback(id => {
-    return zustandStateStore.getStateChangeById(id);
-  }, []);
-  return {
-    stateChanges: log.items,
-    filteredChanges: log.filteredItems,
-    filter: log.filter,
-    setFilter: log.setFilter,
-    stats,
-    stores,
-    // Not the shared log.clear: the store also owns each store's change
-    // count, and only clearStateChanges resets those with the list.
-    clearChanges: zustandStateStore.clearStateChanges.bind(zustandStateStore),
-    isEnabled: log.isEnabled,
-    toggleCapture: log.toggleCapture,
-    storeNames,
-    getChangeById
-  };
-}
+"use strict";import{useCallback as l,useMemo as g}from"react";import{useChangeLog as u,useSubscribedValue as c}from"@buoy-gg/shared-ui";import{zustandStateStore as r}from"../utils/zustandStateStore";function C(e,t){let s=e;if(t.searchText){const a=t.searchText.toLowerCase();s=s.filter(o=>o.storeName.toLowerCase().includes(a)||o.partialPreview.toLowerCase().includes(a)||o.changedKeys.some(n=>n.toLowerCase().includes(a)))}if(t.storeNames&&t.storeNames.length>0){s=s.filter(a=>t.storeNames.includes(a.storeName))}if(t.onlyWithChanges){s=s.filter(a=>a.hasStateChange)}return s}const m=()=>r.getStores();const d=e=>r.subscribeToStores(e);export function useZustandStateChanges(){const e=u(r,{filterItems:C});const t=c(m,d);const s=g(()=>{const n=e.items.length;const i=e.items.filter(h=>h.hasStateChange).length;return{totalChanges:n,changesWithStateChange:i,changesWithoutStateChange:n-i,storeCount:t.length,averageDuration:0}},[e.items,t]);const a=g(()=>{return r.getUniqueStoreNames()},[t]);const o=l(n=>{return r.getStateChangeById(n)},[]);return{stateChanges:e.items,filteredChanges:e.filteredItems,filter:e.filter,setFilter:e.setFilter,stats:s,stores:t,clearChanges:r.clearStateChanges.bind(r),isEnabled:e.isEnabled,toggleCapture:e.toggleCapture,storeNames:a,getChangeById:o}}

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

@@ -1,380 +1 @@
-"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";
-
-/**
- * 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
- * freeze/OOM-killed large apps. Dashboards fetch trees via `getChangeDetail`.
- */
-export const STATE_ON_DEVICE = onDeviceMarker("State", "State trees stay on the device — fetched on demand via getChangeDetail / getStoreState.");
-
-/** 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;
-}
-
-/**
- * Per-change wire cache. The store prepends and never mutates a recorded
- * change, so keying on identity is correct and self-invalidating — without it
- * every `partial` in the list is re-measured on all ~5 snapshots per second.
- */
-const toWireChange = memoByIdentity(change => ({
-  ...change,
-  prevState: STATE_ON_DEVICE,
-  nextState: STATE_ON_DEVICE,
-  partial: toWire(change.partial, PAYLOAD_ON_DEVICE)
-}));
-const toWireState = value => toWire(value, STATE_ON_DEVICE);
-
-/**
- * Sync adapter for the zustand tool, consumed by @buoy-gg/external-sync's
- * `useExternalSync`.
- *
- * State changes are captured by the middleware (watchStores/buoyDevTools),
- * 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 store registry (with each store's current state)
- * so the dashboard can render the store browser.
- *
- * v2: change-log prevState/nextState are replaced with on-device markers
- * (see STATE_ON_DEVICE). Dashboards fetch trees via `getChangeDetail`.
- * Oversized / unserializable `stores[].currentState` uses the same marker
- * and is fetched via `getStoreState`.
- *
- * The `setState` action powers remote time-travel/reset from the dashboard.
- */
-export const zustandSyncAdapter = createSyncAdapter({
-  version: 2,
-  getSnapshot: () => ({
-    changes: zustandStateStore.getStateChanges().map(toWireChange),
-    stores: zustandStateStore.getStoreSnapshots().map(store => ({
-      ...store,
-      currentState: toWireState(store.currentState)
-    }))
-  }),
-  subscribe: [onChange => zustandStateStore.subscribe(onChange), onChange => zustandStateStore.subscribeToStores(onChange)],
-  actions: {
-    clearEvents: () => {
-      zustandStateStore.clearStateChanges();
-    },
-    /**
-     * On-demand detail: one change's real prevState/nextState/partial.
-     * The per-snapshot stream stays tree-free; this is the explicit,
-     * size-guarded channel for the detail pane.
-     */
-    getChangeDetail: detailByIdAction(id => zustandStateStore.getStateChangeById(id), (change, cap) => ({
-      prevState: cap(change.prevState),
-      nextState: cap(change.nextState),
-      partial: cap(change.partial)
-    })),
-    /**
-     * On-demand current state for one store. Wire-form snapshots replace
-     * oversized / unserializable `currentState` with STATE_ON_DEVICE.
-     */
-    getStoreState: params => {
-      const {
-        storeName,
-        path
-      } = readParams(params);
-      if (!storeName) return {
-        found: false,
-        reason: "missing storeName"
-      };
-      const store = zustandStateStore.getStore(storeName);
-      if (!store) return {
-        found: false,
-        reason: "unknown storeName"
-      };
-      let currentState;
-      try {
-        currentState = store.api.getState();
-      } 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
-      };
-    },
-    /**
-     * Compact current-state reader for a remote driver (MCP/LLM): the registered
-     * stores with light metadata; each store's full `currentState` object stays
-     * on the device unless `includeValues` is set (compact view returns just the
-     * top-level `keys` so the shape is visible cheaply).
-     */
-    listStores: params => {
-      const {
-        includeValues = false,
-        limit
-      } = readParams(params);
-      const all = zustandStateStore.getStoreSnapshots();
-      const capped = typeof limit === "number" && limit > 0 ? all.slice(0, limit) : all;
-      const stores = capped.map(s => ({
-        name: s.name,
-        changes: s.stateChangeCount,
-        isPersisted: s.isPersisted,
-        persistName: s.persistName,
-        canRehydrate: s.canRehydrate,
-        ...(includeValues ? {
-          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,
-        total: all.length,
-        returned: stores.length,
-        includedValues: includeValues
-      };
-    },
-    setState: params => {
-      const {
-        storeName,
-        state,
-        replace,
-        force,
-        path,
-        value
-      } = readParams(params);
-      let effective = state;
-      let keyedNotes = [];
-      let unchecked = [];
-      if (!storeName) return {
-        ok: false,
-        error: "Missing storeName."
-      };
-      const store = zustandStateStore.getStore(storeName);
-      if (!store) return {
-        ok: false,
-        error: `No store named "${storeName}".`
-      };
-      // `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,
-        ...(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.`)
-        } : {})
-      };
-    },
-    /**
-     * Re-read a persisted store's saved value and merge it into the live store.
-     *
-     * This is what makes editing a store's storage key mean anything. The app
-     * reads that key once at startup and then holds the state in memory, so an
-     * outside write — the Storage tool, a scenario, an agent — changes the disk
-     * and nothing else, and the next time the store saves it writes its own
-     * copy straight back over the edit.
-     *
-     * `persist.rehydrate()` is plain zustand, not a devtools hook, so unlike
-     * reloading the app this also works in a release build. It merges the saved
-     * value OVER current state (zustand's default merge is
-     * `{...current, ...persisted}`), so the store's action functions survive,
-     * and it does not write back to storage unless a version migration ran —
-     * the edit stays exactly as it was typed.
-     *
-     * Two honest limits, both inherent to persist rather than to this action:
-     * a key the store's `partialize` excludes is not in the saved value and so
-     * cannot be applied, and because the merge is shallow, DELETING a top-level
-     * key from the saved JSON does not remove it from the live store.
-     */
-    rehydrate: async params => {
-      const {
-        storeName
-      } = readParams(params);
-      if (!storeName) return {
-        ok: false,
-        error: "Missing storeName."
-      };
-      const store = zustandStateStore.getStore(storeName);
-      if (!store) return {
-        ok: false,
-        error: `No store named "${storeName}".`
-      };
-      if (!store.isPersisted) {
-        return {
-          ok: false,
-          error: `"${storeName}" is not a persisted store — it has no saved copy to re-read.`
-        };
-      }
-      if (!store.rehydrate) {
-        return {
-          ok: false,
-          error: `"${storeName}" is persisted but Buoy has no rehydrate handle for it. It was probably registered before the app's persist middleware attached.`
-        };
-      }
-      await store.rehydrate();
-      return {
-        ok: true,
-        storeName,
-        persistName: store.persistName
-      };
-    }
-  }
-});
+"use strict";import{expandKeyedArrays as I,patchFromPath as O,readPath as j,refusalText as C,shapeSummary as l,suggestedPatch as k,typedEditViolations as E,unshapedLists as x}from"@buoy-gg/shared-ui";import{zustandStateStore as f}from"../utils/zustandStateStore";import{WIRE_DETAIL_LIMIT_BYTES as A,createSyncAdapter as D,detailByIdAction as R,isJsonSerializable as T,isOverWireBudget as $,memoByIdentity as _,onDeviceMarker as N,readParams as p,toWire as w,truncatedNote as B}from"@buoy-gg/shared-ui";const h=e=>typeof e==="object"&&e!==null&&!Array.isArray(e)&&Object.getPrototypeOf(e)===Object.prototype;function P(e,r){if(!h(e)||!h(r))return r;const t={...e};for(const[o,i]of Object.entries(r))t[o]=o in e?P(e[o],i):i;return t}export const STATE_ON_DEVICE=N("State","State trees stay on the device \u2014 fetched on demand via getChangeDetail / getStoreState.");export const PAYLOAD_ON_DEVICE=N("Payload","Partial stays on the device \u2014 fetched on demand via getChangeDetail.");const Y=e=>!!e&&typeof e==="object"&&!Array.isArray(e);function L(e,r){let t=e;for(const o of r.split(".")){if(!t||typeof t!=="object"||Array.isArray(t))return false;if(!(o in t))return false;t=t[o]}return Array.isArray(t)?t.length>0:!!t&&typeof t==="object"}function M(e){return e&&typeof e==="object"&&!Array.isArray(e)?Object.keys(e):void 0}const V=_(e=>({...e,prevState:STATE_ON_DEVICE,nextState:STATE_ON_DEVICE,partial:w(e.partial,PAYLOAD_ON_DEVICE)}));const W=e=>w(e,STATE_ON_DEVICE);export const zustandSyncAdapter=D({version:2,getSnapshot:()=>({changes:f.getStateChanges().map(V),stores:f.getStoreSnapshots().map(e=>({...e,currentState:W(e.currentState)}))}),subscribe:[e=>f.subscribe(e),e=>f.subscribeToStores(e)],actions:{clearEvents:()=>{f.clearStateChanges()},getChangeDetail:R(e=>f.getStateChangeById(e),(e,r)=>({prevState:r(e.prevState),nextState:r(e.nextState),partial:r(e.partial)})),getStoreState:e=>{const{storeName:r,path:t}=p(e);if(!r)return{found:false,reason:"missing storeName"};const o=f.getStore(r);if(!o)return{found:false,reason:"unknown storeName"};let i;try{i=o.api.getState()}catch{i=void 0}if(t){const s=j(i,t);if(!s.ok)return{found:false,reason:s.error};return{found:true,storeName:r,path:t,shape:l(s.value),currentState:s.value}}const d=l(i);if(!$(i,A)){return{found:true,storeName:r,...d?{shape:d}:{},currentState:i}}return{found:true,storeName:r,...d?{shape:d}:{},currentState:T(i)?B(A):STATE_ON_DEVICE}},listStores:e=>{const{includeValues:r=false,limit:t}=p(e);const o=f.getStoreSnapshots();const i=typeof t==="number"&&t>0?o.slice(0,t):o;const d=i.map(s=>({name:s.name,changes:s.stateChangeCount,isPersisted:s.isPersisted,persistName:s.persistName,canRehydrate:s.canRehydrate,...r?{currentState:s.currentState}:{keys:M(s.currentState)},...l(s.currentState)?{shape:l(s.currentState)}:{}}));return{stores:d,total:o.length,returned:d.length,includedValues:r}},setState:e=>{const{storeName:r,state:t,replace:o,force:i,path:d,value:s}=p(e);let u=t;let y=[];let S=[];if(!r)return{ok:false,error:"Missing storeName."};const c=f.getStore(r);if(!c)return{ok:false,error:`No store named "${r}".`};if(t===void 0&&d===void 0){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 g=false;if(d!==void 0){if(s===void 0){return{ok:false,error:`Refused: sent \`path\` without \`value\`. Say what to set "${d}" to; if you mean to clear it, send value:null and the field must already be nullable.`}}let a;try{a=c.api.getState()}catch{a=void 0}const n=O(a,d,s);if(!n.ok)return{ok:false,error:`Refused: ${n.error}`};u=n.patch;g=true}if(!i&&(o===false||g)){let a;try{a=c.api.getState()}catch{a=void 0}if(a!==void 0){const n=I(a,u);if(n.error){return{ok:false,error:`Refused: ${n.error}`}}u=n.patch;y=n.notes}if(a!==void 0){S=x(a).filter(n=>L(u,n))}if(a!==void 0){const n=E(a,u,{noun:"store"});if(n.length>0){return{ok:false,error:C(n,"store",k(u,n)),...k(u,n)?{suggestedState:k(u,n)}:{},violations:n}}}}const b=g||o===false;if(b){let a;try{a=c.api.getState()}catch{a=void 0}if(h(a)&&h(u)){const n={};for(const[m,v]of Object.entries(u))n[m]=m in a?P(a[m],v):v;u=n}}c.api.setState(u,b?false:o??true);return{ok:true,...d!==void 0?{path:d}:{},...y.length?{keyed:y}:{},...S.length?{unchecked:S.map(a=>`\`${a}\` 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 \u2014 read the store back and compare against how the screen uses it.`)}:{}}},rehydrate:async e=>{const{storeName:r}=p(e);if(!r)return{ok:false,error:"Missing storeName."};const t=f.getStore(r);if(!t)return{ok:false,error:`No store named "${r}".`};if(!t.isPersisted){return{ok:false,error:`"${r}" is not a persisted store \u2014 it has no saved copy to re-read.`}}if(!t.rehydrate){return{ok:false,error:`"${r}" is persisted but Buoy has no rehydrate handle for it. It was probably registered before the app's persist middleware attached.`}}await t.rehydrate();return{ok:true,storeName:r,persistName:t.persistName}}}});

package/lib/module/zustand/types/index.js

@@ -1 +1 @@
-"use strict";
+"use strict";