@buoy-gg/zustand 7.0.38 → 7.0.40

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

@@ -1 +1,380 @@
-"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";export const STATE_ON_DEVICE=onDeviceMarker("State","State trees stay on the device — fetched on demand via getChangeDetail / getStoreState.");export const PAYLOAD_ON_DEVICE=onDeviceMarker("Payload","Partial stays on the device — fetched on demand via getChangeDetail.");const isPlainObject=e=>!!e&&"object"==typeof e&&!Array.isArray(e);function touchesList(e,t){let r=e;for(const e of t.split(".")){if(!r||"object"!=typeof r||Array.isArray(r))return!1;if(!(e in r))return!1;r=r[e]}return Array.isArray(r)?r.length>0:!!r&&"object"==typeof r}function topLevelKeys(e){return e&&"object"==typeof e&&!Array.isArray(e)?Object.keys(e):void 0}const toWireChange=memoByIdentity(e=>({...e,prevState:STATE_ON_DEVICE,nextState:STATE_ON_DEVICE,partial:toWire(e.partial,PAYLOAD_ON_DEVICE)})),toWireState=e=>toWire(e,STATE_ON_DEVICE);export const zustandSyncAdapter=createSyncAdapter({version:2,getSnapshot:()=>({changes:zustandStateStore.getStateChanges().map(toWireChange),stores:zustandStateStore.getStoreSnapshots().map(e=>({...e,currentState:toWireState(e.currentState)}))}),subscribe:[e=>zustandStateStore.subscribe(e),e=>zustandStateStore.subscribeToStores(e)],actions:{clearEvents:()=>{zustandStateStore.clearStateChanges()},getChangeDetail:detailByIdAction(e=>zustandStateStore.getStateChangeById(e),(e,t)=>({prevState:t(e.prevState),nextState:t(e.nextState),partial:t(e.partial)})),getStoreState:e=>{const{storeName:t,path:r}=readParams(e);if(!t)return{found:!1,reason:"missing storeName"};const a=zustandStateStore.getStore(t);if(!a)return{found:!1,reason:"unknown storeName"};let s;try{s=a.api.getState()}catch{s=void 0}if(r){const e=readPath(s,r);return e.ok?{found:!0,storeName:t,path:r,shape:shapeSummary(e.value),currentState:e.value}:{found:!1,reason:e.error}}const o=shapeSummary(s);return isOverWireBudget(s,WIRE_DETAIL_LIMIT_BYTES)?{found:!0,storeName:t,...o?{shape:o}:{},currentState:isJsonSerializable(s)?truncatedNote(WIRE_DETAIL_LIMIT_BYTES):STATE_ON_DEVICE}:{found:!0,storeName:t,...o?{shape:o}:{},currentState:s}},listStores:e=>{const{includeValues:t=!1,limit:r}=readParams(e),a=zustandStateStore.getStoreSnapshots(),s=("number"==typeof r&&r>0?a.slice(0,r):a).map(e=>({name:e.name,changes:e.stateChangeCount,isPersisted:e.isPersisted,persistName:e.persistName,canRehydrate:e.canRehydrate,...t?{currentState:e.currentState}:{keys:topLevelKeys(e.currentState)},...shapeSummary(e.currentState)?{shape:shapeSummary(e.currentState)}:{}}));return{stores:s,total:a.length,returned:s.length,includedValues:t}},setState:e=>{const{storeName:t,state:r,replace:a,force:s,path:o,value:n}=readParams(e);let i=r,d=[],u=[];if(!t)return{ok:!1,error:"Missing storeName."};const c=zustandStateStore.getStore(t);if(!c)return{ok:!1,error:`No store named "${t}".`};if(void 0===r&&void 0===o)return{ok:!1,error:"Refused: no change was described. Send `state` with the fields to merge, or `path` and `value` to set one value."};let h=!1;if(void 0!==o){if(void 0===n)return{ok:!1,error:`Refused: sent \`path\` without \`value\`. Say what to set "${o}" to; if you mean to clear it, send value:null and the field must already be nullable.`};let e;try{e=c.api.getState()}catch{e=void 0}const t=patchFromPath(e,o,n);if(!t.ok)return{ok:!1,error:`Refused: ${t.error}`};i=t.patch,h=!0}if(!s&&(!1===a||h)){let e;try{e=c.api.getState()}catch{e=void 0}if(void 0!==e){const t=expandKeyedArrays(e,i);if(t.error)return{ok:!1,error:`Refused: ${t.error}`};i=t.patch,d=t.notes}if(void 0!==e&&(u=unshapedLists(e).filter(e=>touchesList(i,e))),void 0!==e){const t=typedEditViolations(e,i,{noun:"store"});if(t.length>0)return{ok:!1,error:refusalText(t,"store",suggestedPatch(i,t)),...suggestedPatch(i,t)?{suggestedState:suggestedPatch(i,t)}:{},violations:t}}}return c.api.setState(i,!h&&(a??!0)),{ok:!0,...void 0!==o?{path:o}:{},...d.length?{keyed:d}:{},...u.length?{unchecked:u.map(e=>`\`${e}\` 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.`)}:{}}},rehydrate:async e=>{const{storeName:t}=readParams(e);if(!t)return{ok:!1,error:"Missing storeName."};const r=zustandStateStore.getStore(t);return r?r.isPersisted?r.rehydrate?(await r.rehydrate(),{ok:!0,storeName:t,persistName:r.persistName}):{ok:!1,error:`"${t}" is persisted but Buoy has no rehydrate handle for it. It was probably registered before the app's persist middleware attached.`}:{ok:!1,error:`"${t}" is not a persisted store — it has no saved copy to re-read.`}:{ok:!1,error:`No store named "${t}".`}}}});
+"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
+      };
+    }
+  }
+});

package/lib/module/zustand/utils/buoyZustandMiddleware.js

@@ -1 +1,278 @@
-"use strict";import{zustandStateStore}from"./zustandStateStore";const WATCHED_SYMBOL=Symbol.for("@@buoy-zustand/watched");function detectPersist(t){const e=t.persist;if(e&&"function"==typeof e.getOptions){const t=e.getOptions();return{isPersisted:!0,persistName:t?.name,persistApi:e}}return{isPersisted:!1}}export function watchStores(t){const e=[];for(const[s,r]of Object.entries(t)){const t=r;if(t[WATCHED_SYMBOL])continue;t[WATCHED_SYMBOL]=!0;const{isPersisted:a,persistName:i,persistApi:n}=detectPersist(r);zustandStateStore.registerStore(s,{getState:r.getState,getInitialState:r.getInitialState,setState:r.setState,subscribe:r.subscribe},{isPersisted:a,persistName:i,rehydrate:"function"==typeof n?.rehydrate?()=>n.rehydrate():void 0});let o=!1;const S=r.subscribe((t,e)=>{try{let r;if(!o&&a){let t=!1;try{t=!1===n?.hasHydrated?.()}catch{}t&&(o=!0,r="persist")}zustandStateStore.addStateChange({storeName:s,partial:void 0,replace:!1,prevState:e,nextState:t,duration:void 0,category:r,isPersisted:a})}catch{}});e.push(()=>{S(),delete r[WATCHED_SYMBOL],zustandStateStore.unregisterStore(s)})}return()=>{e.forEach(t=>t())}}let unnamedCounter=0;export function buoyDevTools(t,e){return(s,r,a)=>{const i=e?.name??"store-"+ ++unnamedCounter,n=!1!==e?.enabled,o=s,S=(t,e)=>{if(!n)return o(t,e);const s=performance.now(),a=r();o(t,e);const S=r(),u=performance.now()-s,c="function"==typeof t?"(updater fn)":t;zustandStateStore.addStateChange({storeName:i,partial:c,replace:e??!1,prevState:a,nextState:S,duration:u,isPersisted:zustandStateStore.getStore(i)?.isPersisted??!1})},u=t(S,r,a);return setTimeout(()=>{if(a[WATCHED_SYMBOL])return;a[WATCHED_SYMBOL]=!0;const{isPersisted:t,persistName:e}=detectPersist(a);zustandStateStore.registerStore(i,{getState:r,getInitialState:a.getInitialState,setState:S,subscribe:a.subscribe},{isPersisted:t,persistName:e})},0),u}}export function isStoreInstrumented(t){return!0===t[WATCHED_SYMBOL]}
+"use strict";
+
+/**
+ * Buoy Zustand DevTools — Store instrumentation
+ *
+ * Two approaches, from easiest to most detailed:
+ *
+ * 1. watchStores() — RECOMMENDED. One line, zero store modifications.
+ *    Uses store.subscribe() externally. Never touches setState.
+ *    Safe to add/remove — cannot break your stores even if our code has bugs.
+ *
+ * 2. buoyDevTools() — Opt-in middleware for advanced use.
+ *    Wraps setState to capture the partial argument and timing.
+ *    Requires modifying each store's create() call.
+ */
+
+import { zustandStateStore } from "./zustandStateStore";
+/** Symbol to mark stores that have been watched/instrumented */
+const WATCHED_SYMBOL = Symbol.for("@@buoy-zustand/watched");
+
+/** The slice of zustand's persist API this module uses. */
+
+/**
+ * Detect if a store is using the persist middleware by checking for persist API
+ */
+function detectPersist(store) {
+  const persist = store.persist;
+  if (persist && typeof persist.getOptions === "function") {
+    const options = persist.getOptions();
+    return {
+      isPersisted: true,
+      persistName: options?.name,
+      persistApi: persist
+    };
+  }
+  return {
+    isPersisted: false
+  };
+}
+
+// =============================================================================
+// watchStores — Primary, non-intrusive approach
+// =============================================================================
+
+/** Minimal store shape — what Zustand's create() returns */
+
+/**
+ * Watch multiple Zustand stores for state changes.
+ *
+ * This is the recommended, non-intrusive approach. It uses each store's
+ * `.subscribe()` method to observe changes from the outside — it never
+ * modifies `setState` or any store internals.
+ *
+ * **Safe by design:** Even if our listener code has a bug, it cannot break
+ * your stores. All listener code is wrapped in try/catch.
+ *
+ * @example
+ * ```tsx
+ * // In your _layout.tsx or App.tsx — ONE line:
+ * import { watchStores } from '@buoy-gg/zustand';
+ * import { useCounterStore } from './stores/counter';
+ * import { useAuthStore } from './stores/auth';
+ * import { useCartStore } from './stores/cart';
+ *
+ * watchStores({
+ *   counterStore: useCounterStore,
+ *   authStore: useAuthStore,
+ *   cartStore: useCartStore,
+ * });
+ * ```
+ *
+ * @param stores - Object mapping store names to Zustand store hooks
+ * @returns Cleanup function that removes all subscriptions
+ */
+export function watchStores(stores) {
+  const cleanups = [];
+  for (const [name, store] of Object.entries(stores)) {
+    // Skip if already watched
+    const storeAny = store;
+    if (storeAny[WATCHED_SYMBOL]) continue;
+    storeAny[WATCHED_SYMBOL] = true;
+    const {
+      isPersisted,
+      persistName,
+      persistApi
+    } = detectPersist(store);
+
+    // Register the store for overview
+    zustandStateStore.registerStore(name, {
+      getState: store.getState,
+      getInitialState: store.getInitialState,
+      setState: store.setState,
+      subscribe: store.subscribe
+    }, {
+      isPersisted,
+      persistName,
+      // Was detected and thrown away. Without it nothing can re-read the
+      // saved copy after an outside edit — see ZustandStoreInfo.rehydrate.
+      rehydrate: typeof persistApi?.rehydrate === "function" ? () => persistApi.rehydrate() : undefined
+    });
+
+    // The rehydration is a state change nobody's code asked for — the store
+    // simply becomes what the disk said, seconds into the process. Drawn as an
+    // ordinary setState it is the most surprising row in the list and the one
+    // that looks most like a bug, so it gets its own category. Recognised
+    // rather than announced: `hasHydrated()` is still false while the
+    // rehydrating `set` is running, and this listener runs inside it.
+    let sawHydration = false;
+
+    // Subscribe to state changes — completely external, never touches setState
+    const unsubscribe = store.subscribe((state, prevState) => {
+      try {
+        let category;
+        if (!sawHydration && isPersisted) {
+          let hydrating = false;
+          try {
+            hydrating = persistApi?.hasHydrated?.() === false;
+          } catch {
+            // An older persist API without hasHydrated — no worse than before.
+          }
+          if (hydrating) {
+            sawHydration = true;
+            category = "persist";
+          }
+        }
+        zustandStateStore.addStateChange({
+          storeName: name,
+          partial: undefined,
+          // Not available in subscribe-only mode
+          replace: false,
+          prevState,
+          nextState: state,
+          duration: undefined,
+          // Not available in subscribe-only mode
+          category,
+          isPersisted
+        });
+      } catch {
+        // Silently catch — our bug must never propagate into the store
+      }
+    });
+    cleanups.push(() => {
+      unsubscribe();
+      delete store[WATCHED_SYMBOL];
+      zustandStateStore.unregisterStore(name);
+    });
+  }
+  return () => {
+    cleanups.forEach(fn => fn());
+  };
+}
+
+// =============================================================================
+// buoyDevTools — Opt-in middleware (advanced, more detail)
+// =============================================================================
+
+/** Auto-incrementing store name counter for unnamed stores */
+let unnamedCounter = 0;
+
+/**
+ * Zustand middleware that instruments a store for Buoy DevTools.
+ *
+ * This is the advanced approach — it wraps setState to capture:
+ * - The partial argument passed to setState
+ * - Precise timing of each setState call
+ *
+ * Use this when you want maximum detail. For most cases, `watchStores()`
+ * is simpler and safer.
+ *
+ * @example
+ * ```tsx
+ * import { create } from 'zustand';
+ * import { buoyDevTools } from '@buoy-gg/zustand';
+ *
+ * const useCounterStore = create(
+ *   buoyDevTools(
+ *     (set) => ({
+ *       count: 0,
+ *       increment: () => set((s) => ({ count: s.count + 1 })),
+ *     }),
+ *     { name: 'counterStore' }
+ *   )
+ * );
+ * ```
+ */
+/**
+ * Zustand's own `set` shape (v5 types): with `replace: true` the argument must
+ * be a FULL state, so a single `(partial, replace?: boolean)` signature is
+ * incompatible in both directions — zustand's set is not assignable to it,
+ * which made `create(buoyDevTools(...))` fail to typecheck for every strict-TS
+ * user. Mirroring the overloads keeps buoyDevTools a drop-in for `create()`.
+ */
+
+/**
+ * The store api object zustand hands a middleware, described structurally so
+ * this package never has to import zustand's own types (which differ between
+ * v4 and v5). `Record<string, unknown>` was wrong here: `StoreApi<T>` has no
+ * index signature, so `create(buoyDevTools(...))` failed to typecheck.
+ */
+
+export function buoyDevTools(config, options) {
+  return (set, get, api) => {
+    const storeName = options?.name ?? `store-${++unnamedCounter}`;
+    const enabled = options?.enabled !== false;
+
+    // Forwarding a plain `replace?: boolean` through the overloads needs one
+    // widening cast; runtime behavior is unchanged.
+    const rawSet = set;
+    const instrumentedSet = (partial, replace) => {
+      if (!enabled) {
+        return rawSet(partial, replace);
+      }
+      const startTime = performance.now();
+      const prevState = get();
+      rawSet(partial, replace);
+      const nextState = get();
+      const duration = performance.now() - startTime;
+      const resolvedPartial = typeof partial === "function" ? "(updater fn)" : partial;
+      zustandStateStore.addStateChange({
+        storeName,
+        partial: resolvedPartial,
+        replace: replace ?? false,
+        prevState,
+        nextState,
+        duration,
+        // Read back off the registry rather than hardcoded false. Persistence
+        // is a property of the STORE, and this middleware can be wrapped
+        // around a persisted one — every change on such a store used to be
+        // drawn as un-persisted, which is the opposite of what the badge is
+        // for. Registration happens a tick after creation, so a set fired in
+        // that first tick still reports false; the alternative is re-sniffing
+        // `api.persist` on every set.
+        isPersisted: zustandStateStore.getStore(storeName)?.isPersisted ?? false
+      });
+    };
+    const result = config(instrumentedSet, get, api);
+
+    // Register the store after creation
+    setTimeout(() => {
+      if (api[WATCHED_SYMBOL]) return;
+      api[WATCHED_SYMBOL] = true;
+      const {
+        isPersisted,
+        persistName
+      } = detectPersist(api);
+      zustandStateStore.registerStore(storeName, {
+        getState: get,
+        getInitialState: api.getInitialState,
+        // The INSTRUMENTED set, not the raw one.
+        //
+        // This handle is what the tool's own JUMP and RESET STORE call, and
+        // registering the raw `set` here made both of them invisible: the
+        // store changed, the app re-rendered, and nothing appeared in the
+        // log — so the newest row's "state after change" no longer described
+        // the store, and the next diff compared against a state the device
+        // had never been in. The watch path never had this problem, because
+        // it observes the store from outside and cannot be gone around.
+        setState: instrumentedSet,
+        subscribe: api.subscribe
+      }, {
+        isPersisted,
+        persistName
+      });
+    }, 0);
+    return result;
+  };
+}
+
+// =============================================================================
+// Utility
+// =============================================================================
+
+/**
+ * Check if a store is being watched/instrumented
+ */
+export function isStoreInstrumented(store) {
+  return store[WATCHED_SYMBOL] === true;
+}