@buoy-gg/zustand 5.0.0 → 6.0.1

package/README.md

@@ -1,138 +1,66 @@
 # @buoy-gg/zustand
 
-Zustand store DevTools for React Native. Live state change monitoring, state inspection, and diff visualization for your Zustand stores.
+[![npm version](https://img.shields.io/npm/v/@buoy-gg/zustand?style=flat-square&labelColor=1c1c1c&color=10B981)](https://www.npmjs.com/package/@buoy-gg/zustand) [![npm downloads](https://img.shields.io/npm/dm/@buoy-gg/zustand?style=flat-square&labelColor=1c1c1c&color=10B981)](https://www.npmjs.com/package/@buoy-gg/zustand)
 
-## Setup
+**Zustand devtools on the device — state diffs, jump-to-state, and one-tap store reset with no middleware.**
+
+Part of [Buoy](https://github.com/Buoy-gg/buoy) — devtools that live inside your React Native app. Install it and it auto-appears in the floating menu from [`@buoy-gg/core`](https://www.npmjs.com/package/@buoy-gg/core).
+
+## Install
 
 ```bash
-npm install @buoy-gg/zustand
+npm install @buoy-gg/core @buoy-gg/zustand
 ```
 
-### One line — zero store modifications
+## Quick start
+
+Pass your stores to `FloatingDevTools` via the `zustandStores` prop — a named map of your store hooks. No middleware, no store changes; observation is subscribe-only, so your stores stay untouched.
 
 ```tsx
-import { watchStores } from '@buoy-gg/zustand';
+import { FloatingDevTools } from '@buoy-gg/core';
 import { useCounterStore } from './stores/counter';
 import { useAuthStore } from './stores/auth';
 import { useCartStore } from './stores/cart';
 
-// Call once at module scope (e.g. in _layout.tsx or App.tsx):
-watchStores({
-  counterStore: useCounterStore,
-  authStore: useAuthStore,
-  cartStore: useCartStore,
-});
+export default function App() {
+  return (
+    <>
+      <YourApp />
+      <FloatingDevTools
+        zustandStores={{
+          counterStore: useCounterStore,
+          authStore: useAuthStore,
+          cartStore: useCartStore,
+        }}
+      />
+    </>
+  );
+}
 ```
 
-That's it. The Zustand tool appears automatically in FloatingDevTools.
-
-Your stores stay completely untouched — `watchStores` uses Zustand's built-in `.subscribe()` to observe changes from the outside. It never modifies `setState` or any store internals.
+Prefer to wire it outside React? `watchStores({ counterStore: useCounterStore })` from `@buoy-gg/zustand` does the same thing at module scope.
 
-### Safe by design
+## What you get
 
-- **Add in seconds** — one import, one function call
-- **Remove in seconds** — delete those two lines, done
-- **Cannot break your stores** — all listener code is wrapped in try/catch. Even if our code has a bug, your stores keep working normally
-- **No monkey-patching** — we call `.subscribe()`, the same API your own components use
+- **Every state change, captured** — store name, update type (`setState`, `replace`, `persist`, `initial`), changed keys, and a diff summary
+- **Side-by-side diffs** — additions, removals, and modifications highlighted, in tree or split view
+- **Jump to state** — restore any store to a previously captured state instantly
+- **One-tap reset** — send any store back to its initial state without restarting the app
+- **Persist awareness** — stores using Zustand's `persist` middleware are auto-detected and tagged
+- **Store color coding** — each store keeps a consistent color across the UI for easy tracking
+- **Search & filter** — find changes by store name or changed keys, or show only updates that modified state
+- **Optional `buoyDevTools()` middleware** — wrap individual stores for partial-state capture and per-update timing (flags updates over the 16ms frame budget)
 
-### Cleanup (optional)
+## Desktop & AI
 
-```tsx
-const cleanup = watchStores({ ... });
+The same live session streams to [Buoy Desktop](https://github.com/Buoy-gg/Buoy-Desktop) (free, macOS/Windows/Linux) and to Claude Code or Cursor via the [Buoy MCP server](https://buoy.gg/buoy/latest/docs/mcp).
 
-// Later, to stop watching:
-cleanup();
-```
+## Free vs Pro
 
-## Advanced: middleware mode
+Every tool is free. [Pro](https://buoy.gg/pricing) unlocks production builds, the MCP server, and unlimited capture. Every weekend, Pro features unlock free for everyone.
 
-If you want extra detail (the exact partial passed to `setState` and precise timing), you can opt into the middleware approach per-store:
+---
 
-```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' }
-  )
-);
-```
+📚 [Full docs](https://buoy.gg/buoy/latest/docs/tools/zustand) · [All Buoy tools](https://github.com/Buoy-gg/buoy)
 
-This wraps `setState` internally, so it captures what was passed and how long it took. Works with middleware chaining (persist, immer, etc.):
-
-```tsx
-import { persist } from 'zustand/middleware';
-
-const useAuthStore = create(
-  buoyDevTools(
-    persist(
-      (set) => ({ user: null, login: (u) => set({ user: u }) }),
-      { name: 'auth-storage' }
-    ),
-    { name: 'authStore' }
-  )
-);
-```
-
-## Features
-
-- **Live state change capture** — every state update is recorded with prev/next state
-- **State inspection** — full JSON viewer for state after each change
-- **State diffing** — tree view and split view comparing previous vs. next state
-- **Changed keys tracking** — see exactly which top-level keys changed per update
-- **Store color coding** — each store gets a consistent color for easy visual tracking
-- **Performance monitoring** — updates slower than 16ms are flagged (middleware mode)
-- **Persist awareness** — auto-detects stores using Zustand's persist middleware
-- **Search & filter** — search by store name or changed keys, filter to only state-changing updates
-- **Jump to state** — restore any store to a previously captured state
-- **Reset store** — reset any store to its initial state
-- **Copy to clipboard** — copy state data (Pro)
-
-## Comparison
-
-| | `watchStores()` | `buoyDevTools()` middleware |
-|---|---|---|
-| Setup | One line, no store changes | Wrap each store's `create()` |
-| Risk | Zero — uses subscribe only | Low — wraps setState |
-| Captures partial | No | Yes |
-| Captures timing | No | Yes |
-| State diff | Yes | Yes |
-| Changed keys | Yes | Yes |
-| Persist detection | Yes | Yes |
-
-## Exports
-
-```tsx
-// Primary — non-intrusive
-import { watchStores } from '@buoy-gg/zustand';
-
-// Advanced — middleware
-import { buoyDevTools } from '@buoy-gg/zustand';
-
-// Preset
-import { zustandToolPreset, createZustandTool } from '@buoy-gg/zustand';
-
-// Hook
-import { useZustandStateChanges } from '@buoy-gg/zustand';
-
-// Components (for custom UIs)
-import {
-  ZustandModal,
-  ZustandStateChangeItem,
-  ZustandStateDetailContent,
-  ZustandIcon,
-} from '@buoy-gg/zustand';
-
-// Types
-import type {
-  ZustandStateChange,
-  ZustandStoreInfo,
-  ZustandFilter,
-  StateChangeCategory,
-} from '@buoy-gg/zustand';
-```
+Proprietary software. © Buoy LLC. [Terms](https://buoy.gg/terms)

package/lib/commonjs/zustand/components/ZustandModal.js

@@ -380,10 +380,10 @@ function ZustandModal({
         contentContainerStyle: styles.listContent,
         showsVerticalScrollIndicator: true,
         removeClippedSubviews: true,
-        initialNumToRender: 15,
-        maxToRenderPerBatch: 10,
-        windowSize: 10,
-        scrollEnabled: false
+        initialNumToRender: 12,
+        maxToRenderPerBatch: 8,
+        windowSize: 5,
+        updateCellsBatchingPeriod: 50
       }) : /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
         style: styles.emptyState,
         children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.Box, {
@@ -444,10 +444,10 @@ function ZustandModal({
         contentContainerStyle: styles.listContent,
         showsVerticalScrollIndicator: true,
         removeClippedSubviews: true,
-        initialNumToRender: 15,
-        maxToRenderPerBatch: 10,
-        windowSize: 10,
-        scrollEnabled: false
+        initialNumToRender: 12,
+        maxToRenderPerBatch: 8,
+        windowSize: 5,
+        updateCellsBatchingPeriod: 50
       }) : /*#__PURE__*/(0, _jsxRuntime.jsx)(EventsEmptyState, {
         isEnabled: isEnabled
       })]
@@ -462,6 +462,12 @@ function ZustandModal({
     onIndexChange: handleIndexChange
   }) : null;
   const footerHeight = selectedChange && activeChanges.length > 1 ? 68 : 0;
+
+  // The change lists own their scrolling so FlatList virtualization works
+  // (inside JsModal's ScrollView wrapper every row mounts — the Network
+  // tool measured 17 JS FPS / 133% CPU at max load from this exact
+  // pattern; see tool-bench batches 2026-07-06).
+  const listOwnsScroll = !showFilters && !(selectedChange && selectedChangeIndex !== null) && (selectedHistoryStore != null || activeTab === "events");
   return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_sharedUi.TickProvider, {
     children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.JsModal, {
       visible: visible,
@@ -476,6 +482,7 @@ function ZustandModal({
       enablePersistence: true,
       initialMode: "bottomSheet",
       enableGlitchEffects: true,
+      disableScrollWrapper: listOwnsScroll,
       styles: {},
       footer: footerNode,
       footerHeight: footerHeight,

package/lib/commonjs/zustand/components/ZustandStateChangeItem.js

@@ -3,7 +3,8 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.ZustandStateChangeItem = ZustandStateChangeItem;
+exports.ZustandStateChangeItem = void 0;
+var _react = require("react");
 var _reactNative = require("react-native");
 var _sharedUi = require("@buoy-gg/shared-ui");
 var _zustandStateStore = require("../utils/zustandStateStore");
@@ -88,7 +89,11 @@ function getPrimaryText(change) {
   }
   return change.partialPreview || "setState()";
 }
-function ZustandStateChangeItem({
+
+// Memo justified by profiling (tool-bench 2026-07-06): unmemoized, every
+// visible row re-rendered on each store emission. Leaf w/ stable props
+// ({change, onPress} — onPress is a stable useCallback in the modal).
+const ZustandStateChangeItem = exports.ZustandStateChangeItem = /*#__PURE__*/(0, _react.memo)(function ZustandStateChangeItem({
   change,
   onPress
 }) {
@@ -97,7 +102,6 @@ function ZustandStateChangeItem({
   const sublabel = getSublabel(change);
   const primaryText = getPrimaryText(change);
   const badgeText = getBadgeText(change);
-  const relativeTime = (0, _sharedUi.useRelativeTime)(change.timestamp);
   let customBadge = undefined;
   if (change.isSlowUpdate) {
     customBadge = /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
@@ -137,14 +141,16 @@ function ZustandStateChangeItem({
     statusLabel: statusLabel,
     statusSublabel: sublabel,
     primaryText: primaryText,
-    bottomRightText: relativeTime,
+    bottomRightText: /*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.RelativeTime, {
+      timestamp: change.timestamp
+    }),
     customBadge: customBadge,
     badgeText: customBadge ? undefined : badgeText,
     badgeColor: statusColor,
     showChevron: true,
     onPress: () => onPress(change)
   });
-}
+});
 const styles = _reactNative.StyleSheet.create({
   badgeContainer: {
     flexDirection: "row",

package/lib/module/zustand/components/ZustandModal.js

@@ -376,10 +376,10 @@ export function ZustandModal({
         contentContainerStyle: styles.listContent,
         showsVerticalScrollIndicator: true,
         removeClippedSubviews: true,
-        initialNumToRender: 15,
-        maxToRenderPerBatch: 10,
-        windowSize: 10,
-        scrollEnabled: false
+        initialNumToRender: 12,
+        maxToRenderPerBatch: 8,
+        windowSize: 5,
+        updateCellsBatchingPeriod: 50
       }) : /*#__PURE__*/_jsxs(View, {
         style: styles.emptyState,
         children: [/*#__PURE__*/_jsx(Box, {
@@ -440,10 +440,10 @@ export function ZustandModal({
         contentContainerStyle: styles.listContent,
         showsVerticalScrollIndicator: true,
         removeClippedSubviews: true,
-        initialNumToRender: 15,
-        maxToRenderPerBatch: 10,
-        windowSize: 10,
-        scrollEnabled: false
+        initialNumToRender: 12,
+        maxToRenderPerBatch: 8,
+        windowSize: 5,
+        updateCellsBatchingPeriod: 50
       }) : /*#__PURE__*/_jsx(EventsEmptyState, {
         isEnabled: isEnabled
       })]
@@ -458,6 +458,12 @@ export function ZustandModal({
     onIndexChange: handleIndexChange
   }) : null;
   const footerHeight = selectedChange && activeChanges.length > 1 ? 68 : 0;
+
+  // The change lists own their scrolling so FlatList virtualization works
+  // (inside JsModal's ScrollView wrapper every row mounts — the Network
+  // tool measured 17 JS FPS / 133% CPU at max load from this exact
+  // pattern; see tool-bench batches 2026-07-06).
+  const listOwnsScroll = !showFilters && !(selectedChange && selectedChangeIndex !== null) && (selectedHistoryStore != null || activeTab === "events");
   return /*#__PURE__*/_jsxs(TickProvider, {
     children: [/*#__PURE__*/_jsx(JsModal, {
       visible: visible,
@@ -472,6 +478,7 @@ export function ZustandModal({
       enablePersistence: true,
       initialMode: "bottomSheet",
       enableGlitchEffects: true,
+      disableScrollWrapper: listOwnsScroll,
       styles: {},
       footer: footerNode,
       footerHeight: footerHeight,

package/lib/module/zustand/components/ZustandStateChangeItem.js

@@ -6,8 +6,9 @@
  * Mirrors ReduxActionItem.tsx - uses shared CompactRow for consistent styling
  */
 
+import { memo } from "react";
 import { View, Text, StyleSheet } from "react-native";
-import { CompactRow, buoyColors, Zap, Clock, useRelativeTime } from "@buoy-gg/shared-ui";
+import { CompactRow, buoyColors, Zap, Clock, RelativeTime } from "@buoy-gg/shared-ui";
 import { zustandStateStore } from "../utils/zustandStateStore";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /**
@@ -84,7 +85,11 @@ function getPrimaryText(change) {
   }
   return change.partialPreview || "setState()";
 }
-export function ZustandStateChangeItem({
+
+// Memo justified by profiling (tool-bench 2026-07-06): unmemoized, every
+// visible row re-rendered on each store emission. Leaf w/ stable props
+// ({change, onPress} — onPress is a stable useCallback in the modal).
+export const ZustandStateChangeItem = /*#__PURE__*/memo(function ZustandStateChangeItem({
   change,
   onPress
 }) {
@@ -93,7 +98,6 @@ export function ZustandStateChangeItem({
   const sublabel = getSublabel(change);
   const primaryText = getPrimaryText(change);
   const badgeText = getBadgeText(change);
-  const relativeTime = useRelativeTime(change.timestamp);
   let customBadge = undefined;
   if (change.isSlowUpdate) {
     customBadge = /*#__PURE__*/_jsxs(View, {
@@ -133,14 +137,16 @@ export function ZustandStateChangeItem({
     statusLabel: statusLabel,
     statusSublabel: sublabel,
     primaryText: primaryText,
-    bottomRightText: relativeTime,
+    bottomRightText: /*#__PURE__*/_jsx(RelativeTime, {
+      timestamp: change.timestamp
+    }),
     customBadge: customBadge,
     badgeText: customBadge ? undefined : badgeText,
     badgeColor: statusColor,
     showChevron: true,
     onPress: () => onPress(change)
   });
-}
+});
 const styles = StyleSheet.create({
   badgeContainer: {
     flexDirection: "row",

package/lib/typescript/zustand/components/ZustandModal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ZustandModal.d.ts","sourceRoot":"","sources":["../../../../src/zustand/components/ZustandModal.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA2CH,OAAO,KAAK,EAAE,iBAAiB,EAAsB,MAAM,UAAU,CAAC;AAqBtE,wBAAgB,YAAY,CAAC,EAC3B,OAAO,EACP,OAAO,EACP,MAAM,EACN,UAAU,EACV,2BAAmC,GACpC,EAAE,iBAAiB,sCAuhBnB"}
+{"version":3,"file":"ZustandModal.d.ts","sourceRoot":"","sources":["../../../../src/zustand/components/ZustandModal.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA2CH,OAAO,KAAK,EAAE,iBAAiB,EAAsB,MAAM,UAAU,CAAC;AAqBtE,wBAAgB,YAAY,CAAC,EAC3B,OAAO,EACP,OAAO,EACP,MAAM,EACN,UAAU,EACV,2BAAmC,GACpC,EAAE,iBAAiB,sCAiiBnB"}

package/lib/typescript/zustand/components/ZustandStateChangeItem.d.ts

@@ -8,6 +8,6 @@ interface ZustandStateChangeItemProps {
     change: ZustandStateChange;
     onPress: (change: ZustandStateChange) => void;
 }
-export declare function ZustandStateChangeItem({ change, onPress, }: ZustandStateChangeItemProps): import("react").JSX.Element;
+export declare const ZustandStateChangeItem: import("react").NamedExoticComponent<ZustandStateChangeItemProps>;
 export {};
 //# sourceMappingURL=ZustandStateChangeItem.d.ts.map

package/lib/typescript/zustand/components/ZustandStateChangeItem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ZustandStateChangeItem.d.ts","sourceRoot":"","sources":["../../../../src/zustand/components/ZustandStateChangeItem.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAuB,MAAM,UAAU,CAAC;AAGxE,UAAU,2BAA2B;IACnC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAC;CAC/C;AAwFD,wBAAgB,sBAAsB,CAAC,EACrC,MAAM,EACN,OAAO,GACR,EAAE,2BAA2B,+BAgD7B"}
+{"version":3,"file":"ZustandStateChangeItem.d.ts","sourceRoot":"","sources":["../../../../src/zustand/components/ZustandStateChangeItem.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAAuB,MAAM,UAAU,CAAC;AAGxE,UAAU,2BAA2B;IACnC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAC;CAC/C;AA2FD,eAAO,MAAM,sBAAsB,mEAkDjC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buoy-gg/zustand",
-  "version": "5.0.0",
+  "version": "6.0.1",
   "description": "Zustand store DevTools for React Native",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -26,8 +26,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@buoy-gg/shared-ui": "5.0.0",
-    "@buoy-gg/license": "5.0.0"
+    "@buoy-gg/shared-ui": "6.0.1",
+    "@buoy-gg/license": "6.0.1"
   },
   "peerDependencies": {
     "react": "*",