@buoy-gg/redux 7.0.4 → 7.0.6

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 () {
@@ -57,12 +63,30 @@ Object.defineProperty(exports, "ReduxModal", {
     return _ReduxModal.ReduxModal;
   }
 });
+Object.defineProperty(exports, "ReduxToolView", {
+  enumerable: true,
+  get: function () {
+    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 () {
@@ -87,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 () {
@@ -99,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 () {
@@ -135,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 () {
@@ -171,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");
@@ -183,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

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.FREE_TIER_ACTION_LIMIT = void 0;
 exports.ReduxModal = ReduxModal;
+exports.ReduxToolView = ReduxToolView;
 var _react = require("react");
 var _reactNative = require("react-native");
 var _sharedUi = require("@buoy-gg/shared-ui");
@@ -46,7 +47,8 @@ function ReduxModal({
   onClose,
   onBack,
   onMinimize,
-  enableSharedModalDimensions = false
+  enableSharedModalDimensions = false,
+  inline = false
 }) {
   const isPro = (0, _license.useIsPro)();
   const [showProModal, setShowProModal] = (0, _react.useState)(false);
@@ -56,7 +58,8 @@ function ReduxModal({
     isInstrumented,
     isLoading: isInstrumentLoading,
     error: instrumentError,
-    isReactReduxAvailable
+    isReactReduxAvailable,
+    captureMechanism
   } = (0, _useAutoInstrumentRedux.useAutoInstrumentRedux)();
   const {
     filteredActions,
@@ -285,6 +288,95 @@ function ReduxModal({
   // The action list owns its scrolling so FlatList virtualization works
   // (see ZustandModal — same pattern, same tool-bench evidence).
   const listOwnsScroll = selectedAction == null;
+  const body = /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+    style: styles.container,
+    children: selectedAction && selectedActionIndex !== null ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_ReduxActionDetailContent.ReduxActionDetailContent, {
+      action: selectedAction,
+      actions: visibleActions,
+      selectedIndex: selectedActionIndex,
+      onIndexChange: handleIndexChange,
+      disableInternalFooter: true
+    }) : /*#__PURE__*/(0, _jsxRuntime.jsxs)(_jsxRuntime.Fragment, {
+      children: [instrumentError && !isInstrumented && !_reduxActionStore.reduxActionStore.isCaptureSuppressed() && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+        style: styles.errorBanner,
+        children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.AlertTriangle, {
+          size: 14,
+          color: _sharedUi.macOSColors.semantic.error
+        }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+          style: styles.errorText,
+          children: isReactReduxAvailable ? "Not inside a Redux Provider. Wrap your app with <Provider store={store}>." : "react-redux not installed. Run: npm install react-redux"
+        })]
+      }), !isEnabled && isInstrumented && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+        style: styles.disabledBanner,
+        children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.Power, {
+          size: 14,
+          color: _sharedUi.macOSColors.semantic.warning
+        }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+          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,
+        activeOpacity: 0.8,
+        children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.Lock, {
+          size: 14,
+          color: _sharedUi.buoyColors.primary
+        }), /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.Text, {
+          style: styles.lockedText,
+          children: [lockedActionCount, " older ", lockedActionCount === 1 ? "action" : "actions", " locked"]
+        }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+          style: styles.upgradeBadge,
+          children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+            style: styles.upgradeBadgeText,
+            children: "UPGRADE"
+          })
+        })]
+      }), visibleActions.length > 0 ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.FlatList, {
+        ref: flatListRef,
+        data: visibleActions,
+        renderItem: renderItem,
+        keyExtractor: keyExtractor,
+        contentContainerStyle: styles.listContent,
+        showsVerticalScrollIndicator: true,
+        removeClippedSubviews: true,
+        initialNumToRender: 12,
+        maxToRenderPerBatch: 8,
+        windowSize: 5,
+        updateCellsBatchingPeriod: 50
+      }) : /*#__PURE__*/(0, _jsxRuntime.jsx)(EmptyState, {
+        isEnabled: isEnabled
+      })]
+    })
+  });
+  const upgradeModal = /*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.ProUpgradeModal, {
+    visible: showProModal,
+    onClose: () => setShowProModal(false),
+    featureName: "Full Action History"
+  });
+
+  // The ONLY difference between the phone and the desktop dashboard is which
+  // shell the header, body and footer go in. Everything above this is shared.
+  if (inline) {
+    return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_sharedUi.TickProvider, {
+      children: [/*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+        style: styles.inlineRoot,
+        children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+          style: styles.inlineHeader,
+          children: renderHeaderContent()
+        }), body, footerNode]
+      }), upgradeModal]
+    });
+  }
   return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_sharedUi.TickProvider, {
     children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.JsModal, {
       visible: visible,
@@ -303,75 +395,38 @@ function ReduxModal({
       styles: {},
       footer: footerNode,
       footerHeight: footerHeight,
-      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
-        style: styles.container,
-        children: selectedAction && selectedActionIndex !== null ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_ReduxActionDetailContent.ReduxActionDetailContent, {
-          action: selectedAction,
-          actions: visibleActions,
-          selectedIndex: selectedActionIndex,
-          onIndexChange: handleIndexChange,
-          disableInternalFooter: true
-        }) : /*#__PURE__*/(0, _jsxRuntime.jsxs)(_jsxRuntime.Fragment, {
-          children: [instrumentError && !isInstrumented && !_reduxActionStore.reduxActionStore.isCaptureSuppressed() && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
-            style: styles.errorBanner,
-            children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.AlertTriangle, {
-              size: 14,
-              color: _sharedUi.macOSColors.semantic.error
-            }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
-              style: styles.errorText,
-              children: isReactReduxAvailable ? "Not inside a Redux Provider. Wrap your app with <Provider store={store}>." : "react-redux not installed. Run: npm install react-redux"
-            })]
-          }), !isEnabled && isInstrumented && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
-            style: styles.disabledBanner,
-            children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.Power, {
-              size: 14,
-              color: _sharedUi.macOSColors.semantic.warning
-            }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
-              style: styles.disabledText,
-              children: "Action capture is disabled"
-            })]
-          }), hasLockedActions && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.TouchableOpacity, {
-            style: styles.lockedBanner,
-            onPress: handleUpgradePress,
-            activeOpacity: 0.8,
-            children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.Lock, {
-              size: 14,
-              color: _sharedUi.buoyColors.primary
-            }), /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.Text, {
-              style: styles.lockedText,
-              children: [lockedActionCount, " older ", lockedActionCount === 1 ? "action" : "actions", " locked"]
-            }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
-              style: styles.upgradeBadge,
-              children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
-                style: styles.upgradeBadgeText,
-                children: "UPGRADE"
-              })
-            })]
-          }), visibleActions.length > 0 ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.FlatList, {
-            ref: flatListRef,
-            data: visibleActions,
-            renderItem: renderItem,
-            keyExtractor: keyExtractor,
-            contentContainerStyle: styles.listContent,
-            showsVerticalScrollIndicator: true,
-            removeClippedSubviews: true,
-            initialNumToRender: 12,
-            maxToRenderPerBatch: 8,
-            windowSize: 5,
-            updateCellsBatchingPeriod: 50
-          }) : /*#__PURE__*/(0, _jsxRuntime.jsx)(EmptyState, {
-            isEnabled: isEnabled
-          })]
-        })
-      })
-    }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.ProUpgradeModal, {
-      visible: showProModal,
-      onClose: () => setShowProModal(false),
-      featureName: "Full Action History"
-    })]
+      children: body
+    }), upgradeModal]
+  });
+}
+
+/**
+ * The same Redux tool as `ReduxModal`, rendered INLINE for hosts that place
+ * tools in a panel rather than a modal. Exists so there is exactly one
+ * implementation — the desktop dashboard used to ship its own copy of this
+ * component's header, action list and detail router.
+ */
+function ReduxToolView(props = {}) {
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(ReduxModal, {
+    ...props,
+    inline: true,
+    visible: true,
+    onClose: () => {}
   });
 }
 const styles = _reactNative.StyleSheet.create({
+  inlineRoot: {
+    flex: 1,
+    minHeight: 0,
+    backgroundColor: _sharedUi.macOSColors.background.base
+  },
+  inlineHeader: {
+    paddingHorizontal: 12,
+    paddingVertical: 8,
+    borderBottomWidth: 1,
+    borderBottomColor: _sharedUi.macOSColors.border.default,
+    backgroundColor: _sharedUi.macOSColors.background.card
+  },
   container: {
     flex: 1,
     backgroundColor: _sharedUi.macOSColors.background.base

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);