@buoy-gg/redux 7.0.5 → 7.0.7

package/README.md

@@ -14,7 +14,7 @@ npm install @buoy-gg/core @buoy-gg/redux
 
 ## Quick start
 
-Zero config. Your existing store works as-is — no middleware, no wrapper. The tool auto-instruments the store when `FloatingDevTools` mounts.
+Zero config. Your existing store works as-is — no middleware, no wrapper. Buoy hooks the store at creation via the official Redux DevTools integration point (which Redux Toolkit enables by default), so actions are captured from your app's very first dispatch — including everything dispatched inside thunks and RTK Query.
 
 ```tsx
 import { configureStore } from '@reduxjs/toolkit';
@@ -33,9 +33,28 @@ export default function App() {
 }
 ```
 
+### How capture works (and how to guarantee full capture)
+
+Buoy binds to your store the earliest way available, in this order:
+
+1. **Store-creation hook (default, full capture)** — importing `@buoy-gg/redux` claims the Redux DevTools global that RTK checks by default. If the package loads before your store module, Buoy is inside the store from creation: every action (thunk-internal, RTK Query) is captured and time travel is real. To **guarantee** this ordering, make it the first import of your app entry:
+
+   ```tsx
+   // index.js — first line
+   import '@buoy-gg/redux';
+   ```
+
+2. **Middleware (explicit full capture)** — one line if you prefer being explicit:
+
+   ```tsx
+   middleware: (getDefault) => getDefault().concat(buoyReduxMiddleware),
+   ```
+
+3. **Startup fallback** — if your store was created before Buoy loaded, `FloatingDevTools` binds it automatically at app mount. Top-level dispatches are captured from startup; actions dispatched *inside* thunks/middleware aren't visible to this mode (the tool tells you when it's in it).
+
 ### Optional: full time travel
 
-To jump back to past states (not just view them), wrap your reducer:
+Time travel works out of the box on path 1. On the middleware path, wrap your reducer:
 
 ```tsx
 import { withBuoyDevTools } from '@buoy-gg/redux';

package/lib/commonjs/index.js

@@ -45,6 +45,12 @@ Object.defineProperty(exports, "ReduxActionItem", {
     return _ReduxActionItem.ReduxActionItem;
   }
 });
+Object.defineProperty(exports, "ReduxAutoInstrument", {
+  enumerable: true,
+  get: function () {
+    return _ReduxAutoInstrument.ReduxAutoInstrument;
+  }
+});
 Object.defineProperty(exports, "ReduxIcon", {
   enumerable: true,
   get: function () {
@@ -63,12 +69,24 @@ Object.defineProperty(exports, "ReduxToolView", {
     return _ReduxModal.ReduxToolView;
   }
 });
+Object.defineProperty(exports, "buoyDevtoolsEnhancer", {
+  enumerable: true,
+  get: function () {
+    return _devtoolsHook.buoyDevtoolsEnhancer;
+  }
+});
 Object.defineProperty(exports, "buoyReduxMiddleware", {
   enumerable: true,
   get: function () {
     return _buoyReduxMiddleware.buoyReduxMiddleware;
   }
 });
+Object.defineProperty(exports, "claimDevtoolsHook", {
+  enumerable: true,
+  get: function () {
+    return _devtoolsHook.claimDevtoolsHook;
+  }
+});
 Object.defineProperty(exports, "createBuoyReduxMiddleware", {
   enumerable: true,
   get: function () {
@@ -93,6 +111,12 @@ Object.defineProperty(exports, "getActiveStore", {
     return _autoInstrument.getActiveStore;
   }
 });
+Object.defineProperty(exports, "getInstrumentationStatus", {
+  enumerable: true,
+  get: function () {
+    return _autoInstrument.getInstrumentationStatus;
+  }
+});
 Object.defineProperty(exports, "instrumentStore", {
   enumerable: true,
   get: function () {
@@ -105,6 +129,12 @@ Object.defineProperty(exports, "isAutoInstrumentActive", {
     return _autoInstrument.isAutoInstrumentActive;
   }
 });
+Object.defineProperty(exports, "isDevtoolsHookClaimed", {
+  enumerable: true,
+  get: function () {
+    return _devtoolsHook.isDevtoolsHookClaimed;
+  }
+});
 Object.defineProperty(exports, "isStoreInstrumented", {
   enumerable: true,
   get: function () {
@@ -141,6 +171,12 @@ Object.defineProperty(exports, "reduxToolPreset", {
     return _preset.reduxToolPreset;
   }
 });
+Object.defineProperty(exports, "registerReduxStore", {
+  enumerable: true,
+  get: function () {
+    return _autoInstrument.registerReduxStore;
+  }
+});
 Object.defineProperty(exports, "replayAction", {
   enumerable: true,
   get: function () {
@@ -177,6 +213,7 @@ Object.defineProperty(exports, "withBuoyDevTools", {
     return _buoyReduxMiddleware.withBuoyDevTools;
   }
 });
+var _devtoolsHook = require("./redux/utils/devtoolsHook");
 var _preset = require("./preset");
 var _buoyReduxMiddleware = require("./redux/utils/buoyReduxMiddleware");
 var _autoInstrument = require("./redux/utils/autoInstrument");
@@ -189,4 +226,5 @@ var _ReduxActionItem = require("./redux/components/ReduxActionItem");
 var _ReduxActionDetailView = require("./redux/components/ReduxActionDetailView");
 var _ReduxActionDetailContent = require("./redux/components/ReduxActionDetailContent");
 var _ReduxIcon = require("./redux/components/ReduxIcon");
+var _ReduxAutoInstrument = require("./redux/components/ReduxAutoInstrument");
 var _reduxActionStore = require("./redux/utils/reduxActionStore");

package/lib/commonjs/redux/components/ReduxAutoInstrument.js

@@ -0,0 +1,20 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.ReduxAutoInstrument = ReduxAutoInstrument;
+var _useAutoInstrumentRedux = require("../hooks/useAutoInstrumentRedux");
+/**
+ * Headless startup instrumentation. Auto-rendered by FloatingDevTools (same
+ * pattern as RouteTracker & the overlay tools) so the Redux store is bound
+ * from app mount — action log, MCP getState/dispatch, and desktop sync all
+ * work WITHOUT the user ever opening the Redux tool. Renders nothing.
+ *
+ * Safe anywhere: if react-redux is missing or there's no Provider above, the
+ * hook records the diagnostic and fails gracefully.
+ */
+function ReduxAutoInstrument() {
+  (0, _useAutoInstrumentRedux.useAutoInstrumentRedux)();
+  return null;
+}

package/lib/commonjs/redux/components/ReduxModal.js

@@ -58,7 +58,8 @@ function ReduxModal({
     isInstrumented,
     isLoading: isInstrumentLoading,
     error: instrumentError,
-    isReactReduxAvailable
+    isReactReduxAvailable,
+    captureMechanism
   } = (0, _useAutoInstrumentRedux.useAutoInstrumentRedux)();
   const {
     filteredActions,
@@ -314,6 +315,15 @@ function ReduxModal({
           style: styles.disabledText,
           children: "Action capture is disabled"
         })]
+      }), captureMechanism === "patch" && !_reduxActionStore.reduxActionStore.isCaptureSuppressed() && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+        style: styles.disabledBanner,
+        children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.AlertTriangle, {
+          size: 14,
+          color: _sharedUi.macOSColors.semantic.warning
+        }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+          style: styles.disabledText,
+          children: "Top-level capture only \u2014 thunk/RTK Query internals aren't visible. Put import '@buoy-gg/redux' first in your app entry (or add buoyReduxMiddleware) for full capture."
+        })]
       }), hasLockedActions && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.TouchableOpacity, {
         style: styles.lockedBanner,
         onPress: handleUpgradePress,

package/lib/commonjs/redux/components/index.js

@@ -33,6 +33,12 @@ Object.defineProperty(exports, "ReduxActionItem", {
     return _ReduxActionItem.ReduxActionItem;
   }
 });
+Object.defineProperty(exports, "ReduxAutoInstrument", {
+  enumerable: true,
+  get: function () {
+    return _ReduxAutoInstrument.ReduxAutoInstrument;
+  }
+});
 Object.defineProperty(exports, "ReduxIcon", {
   enumerable: true,
   get: function () {
@@ -49,4 +55,5 @@ var _ReduxModal = require("./ReduxModal");
 var _ReduxActionItem = require("./ReduxActionItem");
 var _ReduxActionDetailView = require("./ReduxActionDetailView");
 var _ReduxActionDetailContent = require("./ReduxActionDetailContent");
-var _ReduxIcon = require("./ReduxIcon");
+var _ReduxIcon = require("./ReduxIcon");
+var _ReduxAutoInstrument = require("./ReduxAutoInstrument");

package/lib/commonjs/redux/hooks/useAutoInstrumentRedux.js

@@ -7,29 +7,21 @@ exports.useAutoInstrumentRedux = useAutoInstrumentRedux;
 exports.useReduxAvailability = useReduxAvailability;
 var _react = require("react");
 var _autoInstrument = require("../utils/autoInstrument");
+var _activeStoreRegistry = require("../utils/activeStoreRegistry");
 /**
  * React hook for auto-instrumenting Redux stores
  *
- * This hook automatically patches the Redux store when the component mounts,
- * providing zero-config action capture for the Redux DevTools.
+ * Mounted for the app's lifetime by FloatingDevTools (via ReduxAutoInstrument)
+ * and also called by the Redux modal. Binds Buoy to the store from react-redux
+ * context:
+ * - If the store was created through the devtools-hook enhancer, capture is
+ *   already live — this just keeps the registry pointed at it.
+ * - Otherwise it applies the dispatch-patch fallback (top-level-only capture).
+ * - If react-redux is missing or there's no Provider above, it fails
+ *   gracefully and records WHY (surfaced by the sync adapter / MCP).
  *
- * Usage:
- * - The hook attempts to use react-redux's useStore() to get the store
- * - If successful, it instruments the store automatically
- * - If react-redux is not available or not in a Provider, it fails gracefully
- *
- * @example
- * ```tsx
- * function ReduxDevTools() {
- *   const { isInstrumented, error } = useAutoInstrumentRedux();
- *
- *   if (error) {
- *     return <Text>Redux not available: {error}</Text>;
- *   }
- *
- *   return <ReduxActionList />;
- * }
- * ```
+ * Re-instruments when the store INSTANCE changes (hosts that rebuild their
+ * store at runtime), so the registry never pins a dead store.
  */
 
 // ============================================
@@ -59,19 +51,16 @@ function getReactReduxUseStore() {
 // Main Hook
 // ============================================
 
-/**
- * Hook to automatically instrument Redux store for DevTools
- *
- * This provides zero-config Redux action capture by:
- * 1. Using react-redux's useStore() to get the Redux store
- * 2. Automatically patching store.dispatch to capture actions
- * 3. Cleaning up when the component unmounts
- */
 function useAutoInstrumentRedux(options = {}) {
   const {
-    autoStart = true,
-    ...instrumentOptions
+    autoStart = true
   } = options;
+
+  // Options live in a ref: this hook is app-lifetime-mounted, and a fresh
+  // `{...rest}` object every render would churn startInstrumentation's
+  // identity and re-run the effect on every render.
+  const optionsRef = (0, _react.useRef)(options);
+  optionsRef.current = options;
   const [isInstrumented, setIsInstrumented] = (0, _react.useState)(false);
   const [isLoading, setIsLoading] = (0, _react.useState)(true);
   const [error, setError] = (0, _react.useState)(null);
@@ -86,37 +75,35 @@ function useAutoInstrumentRedux(options = {}) {
   // This must be called unconditionally due to hooks rules
   let reduxStore = null;
   let storeError = null;
+  let storeDiagnostic = null;
   if (useStoreHook) {
     try {
       // eslint-disable-next-line react-hooks/rules-of-hooks
       reduxStore = useStoreHook();
     } catch (e) {
       // Not inside a Provider or other error
+      storeDiagnostic = "no-provider";
       storeError = e instanceof Error ? e.message : "Failed to access Redux store. Make sure your app is wrapped in a Redux Provider.";
     }
   } else {
+    storeDiagnostic = "no-react-redux";
     storeError = "react-redux is not installed or not available";
   }
 
   // Function to start instrumentation
   const startInstrumentation = (0, _react.useCallback)(() => {
     if (!reduxStore) {
+      // Record the failure reason for non-React surfaces (sync adapter/MCP).
+      (0, _activeStoreRegistry.setReduxDiagnostic)(storeDiagnostic);
       setError(storeError || "No Redux store available");
       setIsLoading(false);
       return;
     }
-
-    // Check if already instrumented
-    if ((0, _autoInstrument.isStoreInstrumented)(reduxStore)) {
-      setIsInstrumented(true);
-      setStore(reduxStore);
-      setIsLoading(false);
-      setError(null);
-      return;
-    }
     try {
-      // Instrument the store
-      const cleanup = (0, _autoInstrument.instrumentStore)(reduxStore, instrumentOptions);
+      // Instrument the store. Idempotent per store: enhancer-created and
+      // already-patched stores just get (re)registered, so a store SWAP at
+      // runtime re-binds the registry to the new instance.
+      const cleanup = (0, _autoInstrument.instrumentStore)(reduxStore, optionsRef.current);
       cleanupRef.current = cleanup;
       setIsInstrumented(true);
       setStore(reduxStore);
@@ -127,7 +114,8 @@ function useAutoInstrumentRedux(options = {}) {
     } finally {
       setIsLoading(false);
     }
-  }, [reduxStore, storeError, instrumentOptions]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- storeError/storeDiagnostic derive from reduxStore
+  }, [reduxStore]);
 
   // Function to stop instrumentation
   const stopInstrumentation = (0, _react.useCallback)(() => {
@@ -142,7 +130,8 @@ function useAutoInstrumentRedux(options = {}) {
     setStore(null);
   }, [store]);
 
-  // Auto-start instrumentation on mount
+  // Auto-start instrumentation on mount, and again whenever the store
+  // INSTANCE changes (hosts that rebuild their store re-point the registry).
   (0, _react.useEffect)(() => {
     if (autoStart) {
       startInstrumentation();
@@ -163,6 +152,7 @@ function useAutoInstrumentRedux(options = {}) {
     isLoading,
     error,
     isReactReduxAvailable,
+    captureMechanism: (0, _autoInstrument.getInstrumentationStatus)().mechanism,
     startInstrumentation,
     stopInstrumentation,
     store

package/lib/commonjs/redux/sync/reduxSyncAdapter.js

@@ -11,14 +11,31 @@ function topLevelKeys(state) {
   return state && typeof state === "object" && !Array.isArray(state) ? Object.keys(state) : [];
 }
 
+/**
+ * Why there's no bound store, in a shape remote drivers (MCP/desktop) can turn
+ * into a SPECIFIC remedy instead of a generic "check your setup".
+ */
+function unavailable() {
+  const status = (0, _autoInstrument.getInstrumentationStatus)();
+  const reason = status.diagnostic ?? "not-instrumented";
+  return {
+    available: false,
+    slices: [],
+    /** 'no-react-redux' | 'no-provider' | 'not-instrumented' */
+    reason
+  };
+}
+
 /**
  * Sync adapter for the redux tool, consumed by @buoy-gg/external-sync's
  * `useExternalSync` (structurally matches its ToolSyncAdapter interface so
  * this package doesn't need a dependency on it).
  *
- * Actions are captured by the auto-instrumentation middleware (installed when
- * FloatingDevTools mounts), independent of whether a dashboard is watching —
- * subscribing here only streams what the store already records.
+ * Actions are captured from app startup — by the store-creation enhancer or
+ * the explicit middleware (full capture), or by the dispatch-patch fallback
+ * mounted with FloatingDevTools (top-level-only) — independent of whether a
+ * dashboard is watching. Subscribing here only streams what's already
+ * recorded.
  *
  * `getState`/`dispatch` read & drive the live instrumented store (via
  * getActiveStore()) so a remote driver (MCP/LLM) can inspect current state and
@@ -43,15 +60,16 @@ const reduxSyncAdapter = exports.reduxSyncAdapter = {
       } = params ?? {};
       const store = (0, _autoInstrument.getActiveStore)();
       if (!store) {
-        return {
-          available: false,
-          slices: []
-        };
+        return unavailable();
       }
       const state = store.getState();
+      const status = (0, _autoInstrument.getInstrumentationStatus)();
       return {
         available: true,
         slices: topLevelKeys(state),
+        /** 'full' | 'top-level-only' — what the live capture mechanism sees. */
+        capture: status.capture,
+        mechanism: status.mechanism,
         ...(includeValues ? {
           state
         } : {})
@@ -65,7 +83,8 @@ const reduxSyncAdapter = exports.reduxSyncAdapter = {
       const store = (0, _autoInstrument.getActiveStore)();
       if (!store) {
         return {
-          dispatched: false
+          dispatched: false,
+          ...unavailable()
         };
       }
       store.dispatch(action);

package/lib/commonjs/redux/utils/activeStoreRegistry.js

@@ -0,0 +1,73 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.ENHANCER_SYMBOL = void 0;
+exports.getActiveStore = getActiveStore;
+exports.getCaptureMechanism = getCaptureMechanism;
+exports.getInstrumentationStatus = getInstrumentationStatus;
+exports.registerActiveStore = registerActiveStore;
+exports.setReduxDiagnostic = setReduxDiagnostic;
+exports.unregisterActiveStore = unregisterActiveStore;
+/**
+ * Shared registry for the one live Redux store Buoy is bound to, plus how it
+ * got bound (the capture mechanism) and why binding failed when it did.
+ *
+ * Lives in its own module so the three capture paths (devtools-hook enhancer,
+ * explicit middleware, dispatch-patch fallback) and the sync adapter can all
+ * import it without cycles.
+ */
+
+/** The minimum store surface Buoy needs (middleware storeApi satisfies this). */
+
+/**
+ * How the store got instrumented:
+ * - `enhancer`   — store-creation-time enhancer via the Redux DevTools global.
+ *                  FULL capture (thunk-internal & RTK Query actions included).
+ * - `middleware` — user-added buoyReduxMiddleware. FULL capture.
+ * - `patch`      — store.dispatch patched after creation (auto-instrumentation
+ *                  fallback). TOP-LEVEL-ONLY capture: actions dispatched from
+ *                  inside middleware/thunks bypass the patch.
+ */
+
+/** Why there is no bound store, when there isn't one. */
+
+/** Marks stores created through the Buoy devtools-hook enhancer. */
+const ENHANCER_SYMBOL = exports.ENHANCER_SYMBOL = Symbol.for("@@buoy/enhancerInstrumented");
+let activeStore = null;
+let mechanism = null;
+let diagnostic = null;
+function registerActiveStore(store, mech) {
+  activeStore = store;
+  mechanism = mech;
+  diagnostic = null;
+}
+function unregisterActiveStore(store) {
+  if (activeStore === store) {
+    activeStore = null;
+    mechanism = null;
+  }
+}
+function getActiveStore() {
+  return activeStore;
+}
+function getCaptureMechanism() {
+  return mechanism;
+}
+
+/**
+ * Recorded by the auto-instrument hook so non-React surfaces (sync adapter,
+ * MCP) can report WHY there's no store instead of a generic failure.
+ */
+function setReduxDiagnostic(d) {
+  diagnostic = d;
+}
+function getInstrumentationStatus() {
+  return {
+    mechanism,
+    capture: mechanism === "enhancer" || mechanism === "middleware" ? "full" : mechanism === "patch" ? "top-level-only" : "none",
+    hasStore: activeStore !== null,
+    diagnostic
+  };
+}