@buoy-gg/redux 7.0.5 → 7.0.6

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

@@ -52,7 +52,8 @@ export function ReduxModal({
     isInstrumented,
     isLoading: isInstrumentLoading,
     error: instrumentError,
-    isReactReduxAvailable
+    isReactReduxAvailable,
+    captureMechanism
   } = useAutoInstrumentRedux();
   const {
     filteredActions,
@@ -308,6 +309,15 @@ export function ReduxModal({
           style: styles.disabledText,
           children: "Action capture is disabled"
         })]
+      }), captureMechanism === "patch" && !reduxActionStore.isCaptureSuppressed() && /*#__PURE__*/_jsxs(View, {
+        style: styles.disabledBanner,
+        children: [/*#__PURE__*/_jsx(AlertTriangle, {
+          size: 14,
+          color: macOSColors.semantic.warning
+        }), /*#__PURE__*/_jsx(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__*/_jsxs(TouchableOpacity, {
         style: styles.lockedBanner,
         onPress: handleUpgradePress,

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

@@ -4,4 +4,5 @@ export { ReduxModal, FREE_TIER_ACTION_LIMIT } from "./ReduxModal";
 export { ReduxActionItem } from "./ReduxActionItem";
 export { ReduxActionDetailView } from "./ReduxActionDetailView";
 export { ReduxActionDetailContent, ReduxActionDetailFooter } from "./ReduxActionDetailContent";
-export { ReduxIcon } from "./ReduxIcon";
+export { ReduxIcon } from "./ReduxIcon";
+export { ReduxAutoInstrument } from "./ReduxAutoInstrument";

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

@@ -3,30 +3,22 @@
 /**
  * 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.
  */
 
 import { useEffect, useState, useRef, useCallback } from "react";
-import { instrumentStore, uninstrumentStore, isStoreInstrumented } from "../utils/autoInstrument";
+import { instrumentStore, uninstrumentStore, getInstrumentationStatus } from "../utils/autoInstrument";
+import { setReduxDiagnostic } from "../utils/activeStoreRegistry";
 
 // ============================================
 // Safe Module Loading
@@ -55,19 +47,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
- */
 export 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 = useRef(options);
+  optionsRef.current = options;
   const [isInstrumented, setIsInstrumented] = useState(false);
   const [isLoading, setIsLoading] = useState(true);
   const [error, setError] = useState(null);
@@ -82,37 +71,35 @@ export 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 = useCallback(() => {
     if (!reduxStore) {
+      // Record the failure reason for non-React surfaces (sync adapter/MCP).
+      setReduxDiagnostic(storeDiagnostic);
       setError(storeError || "No Redux store available");
       setIsLoading(false);
       return;
     }
-
-    // Check if already instrumented
-    if (isStoreInstrumented(reduxStore)) {
-      setIsInstrumented(true);
-      setStore(reduxStore);
-      setIsLoading(false);
-      setError(null);
-      return;
-    }
     try {
-      // Instrument the store
-      const cleanup = 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 = instrumentStore(reduxStore, optionsRef.current);
       cleanupRef.current = cleanup;
       setIsInstrumented(true);
       setStore(reduxStore);
@@ -123,7 +110,8 @@ export 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 = useCallback(() => {
@@ -138,7 +126,8 @@ export 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).
   useEffect(() => {
     if (autoStart) {
       startInstrumentation();
@@ -159,6 +148,7 @@ export function useAutoInstrumentRedux(options = {}) {
     isLoading,
     error,
     isReactReduxAvailable,
+    captureMechanism: getInstrumentationStatus().mechanism,
     startInstrumentation,
     stopInstrumentation,
     store

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

@@ -1,20 +1,37 @@
 "use strict";
 
 import { reduxActionStore } from "../utils/reduxActionStore";
-import { getActiveStore } from "../utils/autoInstrument";
+import { getActiveStore, getInstrumentationStatus } from "../utils/autoInstrument";
 /** Top-level slice names of the state tree, for the compact (no-values) view. */
 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 = 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
@@ -39,15 +56,16 @@ export const reduxSyncAdapter = {
       } = params ?? {};
       const store = getActiveStore();
       if (!store) {
-        return {
-          available: false,
-          slices: []
-        };
+        return unavailable();
       }
       const state = store.getState();
+      const status = 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
         } : {})
@@ -61,7 +79,8 @@ export const reduxSyncAdapter = {
       const store = getActiveStore();
       if (!store) {
         return {
-          dispatched: false
+          dispatched: false,
+          ...unavailable()
         };
       }
       store.dispatch(action);

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

@@ -0,0 +1,63 @@
+"use strict";
+
+/**
+ * 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. */
+export const ENHANCER_SYMBOL = Symbol.for("@@buoy/enhancerInstrumented");
+let activeStore = null;
+let mechanism = null;
+let diagnostic = null;
+export function registerActiveStore(store, mech) {
+  activeStore = store;
+  mechanism = mech;
+  diagnostic = null;
+}
+export function unregisterActiveStore(store) {
+  if (activeStore === store) {
+    activeStore = null;
+    mechanism = null;
+  }
+}
+export function getActiveStore() {
+  return activeStore;
+}
+export 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.
+ */
+export function setReduxDiagnostic(d) {
+  diagnostic = d;
+}
+export function getInstrumentationStatus() {
+  return {
+    mechanism,
+    capture: mechanism === "enhancer" || mechanism === "middleware" ? "full" : mechanism === "patch" ? "top-level-only" : "none",
+    hasStore: activeStore !== null,
+    diagnostic
+  };
+}

package/lib/module/redux/utils/autoInstrument.js

@@ -1,18 +1,26 @@
 "use strict";
 
 /**
- * Auto-instrumentation for Redux stores
+ * Fallback auto-instrumentation for Redux stores.
  *
- * This module provides zero-config Redux DevTools integration by automatically
- * patching the store's dispatch method when the DevTools component mounts.
+ * The PRIMARY capture path is the store-creation-time enhancer in
+ * devtoolsHook.ts (full capture, real time travel). This module is the
+ * fallback for stores created before our module loaded: it patches
+ * store.dispatch after the fact.
  *
- * Similar to how @buoy-gg/network patches globalThis.fetch, this patches
- * store.dispatch to capture all Redux actions without requiring manual
- * middleware configuration.
+ * Fallback limitation (inherent to patching, verified against redux 5.x):
+ * `middlewareAPI.dispatch` is a separate closure from `store.dispatch`, so
+ * actions dispatched from INSIDE middleware/thunks (RTK pending/fulfilled/
+ * rejected, RTK Query) bypass the patch. That's why this mechanism reports
+ * capture as "top-level-only" — see activeStoreRegistry.getInstrumentationStatus.
  */
 
 import { reduxActionStore } from "./reduxActionStore";
 import { BUOY_JUMP_TO_STATE, isMiddlewareActive } from "./buoyReduxMiddleware";
+import { registerActiveStore, unregisterActiveStore, getActiveStore as getRegisteredStore, ENHANCER_SYMBOL } from "./activeStoreRegistry";
+
+// Re-exported for non-React callers (sync adapter, app code).
+export { getInstrumentationStatus } from "./activeStoreRegistry";
 
 // ============================================
 // Store Tracking
@@ -24,15 +32,6 @@ const INSTRUMENTED_SYMBOL = Symbol.for("@@buoy/instrumented");
 /** Symbol to store original dispatch reference */
 const ORIGINAL_DISPATCH_SYMBOL = Symbol.for("@@buoy/originalDispatch");
 
-/** Symbol to store original reducer reference */
-const ORIGINAL_REDUCER_SYMBOL = Symbol.for("@@buoy/originalReducer");
-
-/** Reference to the active store for time-travel operations */
-let activeStore = null;
-
-/** Track if store has been enhanced for time-travel */
-let timeTravelEnabled = false;
-
 // ============================================
 // Type Definitions
 // ============================================
@@ -42,40 +41,44 @@ let timeTravelEnabled = false;
 // ============================================
 
 /**
- * Check if a store has already been instrumented
+ * Check if a store has already been instrumented (either mechanism)
  */
 export function isStoreInstrumented(store) {
-  return store[INSTRUMENTED_SYMBOL] === true;
+  const s = store;
+  return s[INSTRUMENTED_SYMBOL] === true || s[ENHANCER_SYMBOL] === true;
 }
 
 /**
- * Instrument a Redux store for action capture
+ * Instrument a Redux store for action capture (fallback path).
  *
- * This function patches store.dispatch to capture all actions without
- * requiring the user to configure middleware manually.
+ * Patches store.dispatch to capture top-level dispatches. No-ops (but still
+ * registers the store for getState/dispatch) when the enhancer or the
+ * explicit middleware is already capturing.
  *
- * @param store - The Redux store to instrument
- * @param options - Configuration options
  * @returns Cleanup function to restore original dispatch
  */
 export function instrumentStore(store, options = {}) {
   const instrumentedStore = store;
 
+  // Store was created through the devtools-hook enhancer — full capture is
+  // already live; just (re)point the registry at it.
+  if (instrumentedStore[ENHANCER_SYMBOL]) {
+    registerActiveStore(store, "enhancer");
+    return () => {};
+  }
+
   // Skip if middleware is already handling action capture
-  // This prevents duplicate recording when both mechanisms are active
   if (isMiddlewareActive()) {
-    activeStore = store;
+    registerActiveStore(store, "middleware");
     return () => {};
   }
 
-  // Skip if already instrumented
+  // Skip if already patched — update the registry even so (store swap case)
   if (instrumentedStore[INSTRUMENTED_SYMBOL]) {
-    // Update active store reference even if already instrumented
-    activeStore = store;
+    registerActiveStore(store, "patch");
     return () => {};
   }
   const {
-    enableTimeTravel = false,
     maxActions = 200,
     ignoreActions = []
   } = options;
@@ -126,12 +129,7 @@ export function instrumentStore(store, options = {}) {
   // Replace dispatch
   store.dispatch = instrumentedDispatch;
   instrumentedStore[INSTRUMENTED_SYMBOL] = true;
-  activeStore = store;
-
-  // Enable time-travel if requested and store supports replaceReducer
-  if (enableTimeTravel && typeof store.replaceReducer === "function") {
-    enableTimeTravelSupport(store);
-  }
+  registerActiveStore(store, "patch");
 
   // Return cleanup function
   return () => {
@@ -140,90 +138,63 @@ export function instrumentStore(store, options = {}) {
 }
 
 /**
- * Remove instrumentation from a store
+ * Remove dispatch-patch instrumentation from a store.
+ *
+ * Only restores the patched dispatch. (This used to also replaceReducer with a
+ * synthetic reducer that froze the host store permanently — that path is gone.)
+ * Enhancer-created stores are left untouched apart from the registry.
  */
 export function uninstrumentStore(store) {
   const instrumentedStore = store;
-  if (!instrumentedStore[INSTRUMENTED_SYMBOL]) {
-    return;
-  }
-
-  // Restore original dispatch
-  const originalDispatch = instrumentedStore[ORIGINAL_DISPATCH_SYMBOL];
-  if (originalDispatch) {
-    store.dispatch = originalDispatch;
-  }
-
-  // Restore original reducer if time-travel was enabled
-  const originalReducer = instrumentedStore[ORIGINAL_REDUCER_SYMBOL];
-  if (originalReducer && typeof store.replaceReducer === "function") {
-    store.replaceReducer(originalReducer);
-    timeTravelEnabled = false;
-  }
-
-  // Clean up symbols
-  delete instrumentedStore[INSTRUMENTED_SYMBOL];
-  delete instrumentedStore[ORIGINAL_DISPATCH_SYMBOL];
-  delete instrumentedStore[ORIGINAL_REDUCER_SYMBOL];
-
-  // Clear active store reference
-  if (activeStore === store) {
-    activeStore = null;
+  if (instrumentedStore[INSTRUMENTED_SYMBOL]) {
+    const originalDispatch = instrumentedStore[ORIGINAL_DISPATCH_SYMBOL];
+    if (originalDispatch) {
+      store.dispatch = originalDispatch;
+    }
+    delete instrumentedStore[INSTRUMENTED_SYMBOL];
+    delete instrumentedStore[ORIGINAL_DISPATCH_SYMBOL];
   }
+  unregisterActiveStore(store);
 }
 
-// ============================================
-// Time-Travel Support
-// ============================================
-
 /**
- * Enable time-travel support by wrapping the store's reducer
+ * Manually register a store with Buoy — the escape hatch for apps that can't
+ * render FloatingDevTools inside a react-redux Provider (or don't use
+ * react-redux at all). Instruments via the fallback dispatch patch.
  *
- * This uses store.replaceReducer to inject our time-travel wrapper
- * dynamically, without requiring users to manually wrap their reducer.
+ * Prefer the zero-config paths; this exists so no app is ever stuck.
  */
-function enableTimeTravelSupport(store) {
-  const instrumentedStore = store;
-
-  // Get current reducer by dispatching a probe action
-  // Note: This is a workaround since there's no store.getReducer()
-  // We'll wrap whatever reducer is currently active
-  const currentState = store.getState();
-
-  // Create a time-travel enabled reducer wrapper
-  const timeTravelReducer = (state = currentState, action) => {
-    // Handle jump to state action
-    if (action.type === BUOY_JUMP_TO_STATE) {
-      return action.payload;
-    }
+export function registerReduxStore(store, options = {}) {
+  return instrumentStore(store, options);
+}
 
-    // Get the result from the original dispatch flow
-    // Since we've already wrapped dispatch, we need to be careful here
-    // The state will be updated by the store's internal reducer
-    return state;
-  };
+// ============================================
+// Time-Travel / Introspection
+// ============================================
 
-  // Store reference (we can't actually get the original reducer directly)
-  // This approach has limitations - full time-travel works better with
-  // the explicit withBuoyDevTools wrapper
-  instrumentedStore[ORIGINAL_REDUCER_SYMBOL] = timeTravelReducer;
-  timeTravelEnabled = true;
-}
+let warnedJumpUnsupported = false;
 
 /**
- * Jump to a specific state (time-travel)
+ * Jump to a specific state (time-travel).
  *
- * For full time-travel support, users should use withBuoyDevTools.
- * This limited version attempts to work with auto-instrumentation.
+ * Real on the enhancer path (reducer is wrapped from creation) and on the
+ * middleware path when the app used `withBuoyDevTools`. On the bare patch
+ * path there's no reducer wrapper, so the jump action is ignored — we detect
+ * that and warn once instead of pretending it worked.
  */
 export function jumpToState(state) {
-  if (activeStore) {
-    activeStore.dispatch({
-      type: BUOY_JUMP_TO_STATE,
-      payload: state
-    });
-  } else {
+  const store = getRegisteredStore();
+  if (!store) {
     console.warn("[BuoyRedux] Cannot jump to state - no store instrumented");
+    return;
+  }
+  store.dispatch({
+    type: BUOY_JUMP_TO_STATE,
+    payload: state
+  });
+  if (typeof __DEV__ !== "undefined" && __DEV__ && !warnedJumpUnsupported && store.getState() !== state) {
+    warnedJumpUnsupported = true;
+    console.warn("[BuoyRedux] Time-travel jump was ignored by the store. Wrap your root " + "reducer with withBuoyDevTools(), or ensure @buoy-gg/redux is imported " + "before your store is created (enhancer path) for real time travel.");
   }
 }
 
@@ -231,30 +202,28 @@ export function jumpToState(state) {
  * Replay an action (dispatch it again)
  */
 export function replayAction(action) {
-  if (activeStore) {
-    activeStore.dispatch(action);
+  const store = getRegisteredStore();
+  if (store) {
+    store.dispatch(action);
   } else {
     console.warn("[BuoyRedux] Cannot replay action - no store instrumented");
   }
 }
 
 /**
- * Get the currently active (instrumented) store
+ * Get the currently active (instrumented) store.
+ *
+ * NOTE: on the middleware path this is the middleware `storeApi`
+ * ({getState, dispatch}) rather than the full Store object — every consumer
+ * in this package only needs those two.
  */
 export function getActiveStore() {
-  return activeStore;
+  return getRegisteredStore();
 }
 
 /**
  * Check if auto-instrumentation is active
  */
 export function isAutoInstrumentActive() {
-  return activeStore !== null && isStoreInstrumented(activeStore);
-}
-
-/**
- * Check if time-travel support is enabled
- */
-export function isTimeTravelEnabled() {
-  return timeTravelEnabled;
+  return getRegisteredStore() !== null;
 }