@buoy-gg/redux 7.0.5 → 7.0.7

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

@@ -4,26 +4,39 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.getActiveStore = getActiveStore;
+Object.defineProperty(exports, "getInstrumentationStatus", {
+  enumerable: true,
+  get: function () {
+    return _activeStoreRegistry.getInstrumentationStatus;
+  }
+});
 exports.instrumentStore = instrumentStore;
 exports.isAutoInstrumentActive = isAutoInstrumentActive;
 exports.isStoreInstrumented = isStoreInstrumented;
-exports.isTimeTravelEnabled = isTimeTravelEnabled;
 exports.jumpToState = jumpToState;
+exports.registerReduxStore = registerReduxStore;
 exports.replayAction = replayAction;
 exports.uninstrumentStore = uninstrumentStore;
 var _reduxActionStore = require("./reduxActionStore");
 var _buoyReduxMiddleware = require("./buoyReduxMiddleware");
+var _activeStoreRegistry = require("./activeStoreRegistry");
 /**
- * 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.
  */
 
+// Re-exported for non-React callers (sync adapter, app code).
+
 // ============================================
 // Store Tracking
 // ============================================
@@ -34,15 +47,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
 // ============================================
@@ -52,40 +56,44 @@ let timeTravelEnabled = false;
 // ============================================
 
 /**
- * Check if a store has already been instrumented
+ * Check if a store has already been instrumented (either mechanism)
  */
 function isStoreInstrumented(store) {
-  return store[INSTRUMENTED_SYMBOL] === true;
+  const s = store;
+  return s[INSTRUMENTED_SYMBOL] === true || s[_activeStoreRegistry.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
  */
 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[_activeStoreRegistry.ENHANCER_SYMBOL]) {
+    (0, _activeStoreRegistry.registerActiveStore)(store, "enhancer");
+    return () => {};
+  }
+
   // Skip if middleware is already handling action capture
-  // This prevents duplicate recording when both mechanisms are active
   if ((0, _buoyReduxMiddleware.isMiddlewareActive)()) {
-    activeStore = store;
+    (0, _activeStoreRegistry.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;
+    (0, _activeStoreRegistry.registerActiveStore)(store, "patch");
     return () => {};
   }
   const {
-    enableTimeTravel = false,
     maxActions = 200,
     ignoreActions = []
   } = options;
@@ -136,12 +144,7 @@ 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);
-  }
+  (0, _activeStoreRegistry.registerActiveStore)(store, "patch");
 
   // Return cleanup function
   return () => {
@@ -150,90 +153,63 @@ 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.
  */
 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];
   }
+  (0, _activeStoreRegistry.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 === _buoyReduxMiddleware.BUOY_JUMP_TO_STATE) {
-      return action.payload;
-    }
+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.
  */
 function jumpToState(state) {
-  if (activeStore) {
-    activeStore.dispatch({
-      type: _buoyReduxMiddleware.BUOY_JUMP_TO_STATE,
-      payload: state
-    });
-  } else {
+  const store = (0, _activeStoreRegistry.getActiveStore)();
+  if (!store) {
     console.warn("[BuoyRedux] Cannot jump to state - no store instrumented");
+    return;
+  }
+  store.dispatch({
+    type: _buoyReduxMiddleware.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.");
   }
 }
 
@@ -241,30 +217,28 @@ function jumpToState(state) {
  * Replay an action (dispatch it again)
  */
 function replayAction(action) {
-  if (activeStore) {
-    activeStore.dispatch(action);
+  const store = (0, _activeStoreRegistry.getActiveStore)();
+  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.
  */
 function getActiveStore() {
-  return activeStore;
+  return (0, _activeStoreRegistry.getActiveStore)();
 }
 
 /**
  * Check if auto-instrumentation is active
  */
 function isAutoInstrumentActive() {
-  return activeStore !== null && isStoreInstrumented(activeStore);
-}
-
-/**
- * Check if time-travel support is enabled
- */
-function isTimeTravelEnabled() {
-  return timeTravelEnabled;
+  return (0, _activeStoreRegistry.getActiveStore)() !== null;
 }

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

@@ -10,6 +10,7 @@ exports.jumpToState = jumpToState;
 exports.replayAction = replayAction;
 exports.withBuoyDevTools = withBuoyDevTools;
 var _reduxActionStore = require("./reduxActionStore");
+var _activeStoreRegistry = require("./activeStoreRegistry");
 /**
  * Buoy Redux Middleware for Redux Toolkit
  *
@@ -47,20 +48,22 @@ function isMiddlewareActive() {
 
 const BUOY_JUMP_TO_STATE = exports.BUOY_JUMP_TO_STATE = "@@buoy/JUMP_TO_STATE";
 const BUOY_REPLAY_ACTION = exports.BUOY_REPLAY_ACTION = "@@buoy/REPLAY_ACTION";
-// Store reference to dispatch for time-travel
-let storeDispatch = null;
-
 /**
- * Jump to a specific state (time-travel)
+ * Jump to a specific state (time-travel).
+ *
+ * Registry-backed, so it works on EVERY capture path (enhancer, middleware,
+ * patch) — previously this only worked when the middleware was installed,
+ * which silently broke the modal's Jump button on the zero-config path.
  */
 function jumpToState(state) {
-  if (storeDispatch) {
-    storeDispatch({
+  const store = (0, _activeStoreRegistry.getActiveStore)();
+  if (store) {
+    store.dispatch({
       type: BUOY_JUMP_TO_STATE,
       payload: state
     });
   } else {
-    console.warn("[BuoyRedux] Cannot jump to state - middleware not initialized");
+    console.warn("[BuoyRedux] Cannot jump to state - no store instrumented");
   }
 }
 
@@ -68,11 +71,11 @@ function jumpToState(state) {
  * Replay an action (dispatch it again)
  */
 function replayAction(action) {
-  if (storeDispatch) {
-    // Dispatch the original action directly
-    storeDispatch(action);
+  const store = (0, _activeStoreRegistry.getActiveStore)();
+  if (store) {
+    store.dispatch(action);
   } else {
-    console.warn("[BuoyRedux] Cannot replay action - middleware not initialized");
+    console.warn("[BuoyRedux] Cannot replay action - no store instrumented");
   }
 }
 
@@ -107,8 +110,10 @@ const buoyReduxMiddleware = storeApi => {
   // Mark middleware as active so auto-instrument knows to skip
   middlewareActive = true;
 
-  // Store dispatch reference for time-travel
-  storeDispatch = storeApi.dispatch;
+  // Register as the active store so getState/dispatch (MCP, desktop, time
+  // travel) work on the middleware path too — storeApi has both getState and
+  // dispatch, which is all the registry needs.
+  (0, _activeStoreRegistry.registerActiveStore)(storeApi, "middleware");
   return next => action => {
     const actionObj = action;
     const actionType = actionObj.type;
@@ -141,8 +146,8 @@ function createBuoyReduxMiddleware(options = {}) {
     // Mark middleware as active so auto-instrument knows to skip
     middlewareActive = true;
 
-    // Store dispatch reference for time-travel
-    storeDispatch = storeApi.dispatch;
+    // Register as the active store (see buoyReduxMiddleware above).
+    (0, _activeStoreRegistry.registerActiveStore)(storeApi, "middleware");
     return next => action => {
       const actionObj = action;
       const actionType = actionObj.type || "";

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

@@ -0,0 +1,137 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.buoyDevtoolsEnhancer = void 0;
+exports.claimDevtoolsHook = claimDevtoolsHook;
+exports.isDevtoolsHookClaimed = isDevtoolsHookClaimed;
+var _reduxActionStore = require("./reduxActionStore");
+var _buoyReduxMiddleware = require("./buoyReduxMiddleware");
+var _activeStoreRegistry = require("./activeStoreRegistry");
+/**
+ * Store-creation-time capture via the OFFICIAL Redux DevTools hook.
+ *
+ * `configureStore` defaults `devTools: true` and, at RTK module-evaluation
+ * time, snapshots `window.__REDUX_DEVTOOLS_EXTENSION_COMPOSE__` if defined.
+ * That global doesn't exist in React Native — so Buoy claims it (dev builds
+ * only, and only when nothing else has). This makes Buoy a real store
+ * ENHANCER, present from the store's birth:
+ *
+ * - FULL capture: actions dispatched from inside middleware/thunks (RTK
+ *   `pending`/`fulfilled`/`rejected`, RTK Query) hit our dispatch because the
+ *   enhancer sits BELOW applyMiddleware in the compose chain.
+ * - Real time travel: we wrap the reducer, so BUOY_JUMP_TO_STATE actually
+ *   jumps — and replaceReducer is re-wrapped, so hosts that inject reducers
+ *   dynamically keep working.
+ * - Nothing is monkey-patched: this is the integration point Redux itself
+ *   ships for devtools (same one react-native-debugger used).
+ *
+ * Race note: RTK snapshots the global when ITS module first evaluates, so this
+ * module must load before `@reduxjs/toolkit` does. `@buoy-gg/core` requires us
+ * at module scope, which usually wins; when it doesn't, the dispatch-patch
+ * fallback in autoInstrument.ts still binds at first mount. Apps that want a
+ * guarantee put `import '@buoy-gg/redux';` as the FIRST import of their entry.
+ */
+
+/** Standard redux compose. */
+function composeFns(...funcs) {
+  if (funcs.length === 0) return arg => arg;
+  if (funcs.length === 1) return funcs[0];
+  return funcs.reduce((a, b) => (...args) => a(b(...args)));
+}
+
+/** Wrap a reducer so BUOY_JUMP_TO_STATE performs a real state jump. */
+function wrapReducer(reducer) {
+  return (state, action) => {
+    if (action && action.type === _buoyReduxMiddleware.BUOY_JUMP_TO_STATE) {
+      return action.payload;
+    }
+    return reducer(state, action);
+  };
+}
+
+/** Should this action be recorded? (Mirrors autoInstrument's filters.) */
+function isRecordable(action) {
+  if (typeof action !== "object" || action === null) return false;
+  const type = action.type;
+  if (typeof type !== "string") return false;
+  return !type.startsWith("@@buoy/") && !type.startsWith("@@redux/");
+}
+
+/**
+ * The Buoy store enhancer. Innermost in the compose chain (below
+ * applyMiddleware), so every action that reaches the reducer — including ones
+ * dispatched from inside middleware and thunks — passes through here.
+ */
+const buoyDevtoolsEnhancer = createStore => (reducer, preloadedState) => {
+  const store = createStore(wrapReducer(reducer), preloadedState);
+  const dispatch = action => {
+    // If the explicit middleware is installed it already records — the
+    // enhancer stays passive to avoid double capture.
+    if (!isRecordable(action) || (0, _buoyReduxMiddleware.isMiddlewareActive)()) {
+      return store.dispatch(action);
+    }
+    const startTime = performance.now();
+    const prevState = store.getState();
+    const result = store.dispatch(action);
+    _reduxActionStore.reduxActionStore.addAction(action, prevState, store.getState(), performance.now() - startTime);
+    return result;
+  };
+  const enhanced = {
+    ...store,
+    dispatch,
+    // Keep time travel alive across dynamic reducer injection.
+    replaceReducer: next => store.replaceReducer(wrapReducer(next)),
+    [_activeStoreRegistry.ENHANCER_SYMBOL]: true
+  };
+  (0, _activeStoreRegistry.registerActiveStore)(enhanced, "enhancer");
+  return enhanced;
+};
+
+/**
+ * Implements the `__REDUX_DEVTOOLS_EXTENSION_COMPOSE__` calling conventions:
+ * - `compose(options)(...enhancers)` — what RTK's configureStore does
+ * - `compose(...enhancers)` — classic createStore usage from the Redux docs
+ */
+exports.buoyDevtoolsEnhancer = buoyDevtoolsEnhancer;
+function buoyComposeWithDevTools(...args) {
+  if (args.length === 0) {
+    return composeFns(buoyDevtoolsEnhancer);
+  }
+  if (args.length === 1 && typeof args[0] === "object" && args[0] !== null) {
+    // Options form → return a compose function.
+    return (...enhancers) => composeFns(...enhancers, buoyDevtoolsEnhancer);
+  }
+  return composeFns(...args, buoyDevtoolsEnhancer);
+}
+let claimed = false;
+
+/**
+ * Claim the DevTools globals — dev builds only, and never over an existing
+ * claimant (e.g. the real browser extension on web).
+ *
+ * Idempotent; runs at module scope so simply importing `@buoy-gg/redux` (which
+ * `@buoy-gg/core` does at module scope) performs the claim as early as
+ * possible.
+ */
+function claimDevtoolsHook() {
+  const isDev = typeof __DEV__ !== "undefined" && __DEV__;
+  if (!isDev) return false;
+  const g = globalThis;
+  if (!g.__REDUX_DEVTOOLS_EXTENSION_COMPOSE__) {
+    g.__REDUX_DEVTOOLS_EXTENSION_COMPOSE__ = buoyComposeWithDevTools;
+    claimed = true;
+  }
+  if (!g.__REDUX_DEVTOOLS_EXTENSION__) {
+    // Legacy single-enhancer form: `createStore(reducer, __REDUX_DEVTOOLS_EXTENSION__())`
+    g.__REDUX_DEVTOOLS_EXTENSION__ = () => buoyDevtoolsEnhancer;
+  }
+  return claimed;
+}
+
+/** Whether Buoy owns the DevTools compose global (i.e. won the load race). */
+function isDevtoolsHookClaimed() {
+  return claimed;
+}
+claimDevtoolsHook();

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

@@ -27,12 +27,24 @@ Object.defineProperty(exports, "autoReplayAction", {
     return _autoInstrument.replayAction;
   }
 });
+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 () {
@@ -51,6 +63,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 () {
@@ -63,6 +81,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 () {
@@ -87,6 +111,12 @@ Object.defineProperty(exports, "reduxHistoryAdapter", {
     return _createReduxHistoryAdapter.reduxHistoryAdapter;
   }
 });
+Object.defineProperty(exports, "registerReduxStore", {
+  enumerable: true,
+  get: function () {
+    return _autoInstrument.registerReduxStore;
+  }
+});
 Object.defineProperty(exports, "replayAction", {
   enumerable: true,
   get: function () {
@@ -108,4 +138,5 @@ Object.defineProperty(exports, "withBuoyDevTools", {
 var _reduxActionStore = require("./reduxActionStore");
 var _buoyReduxMiddleware = require("./buoyReduxMiddleware");
 var _createReduxHistoryAdapter = require("./createReduxHistoryAdapter");
-var _autoInstrument = require("./autoInstrument");
+var _autoInstrument = require("./autoInstrument");
+var _devtoolsHook = require("./devtoolsHook");

package/lib/module/index.js

@@ -29,9 +29,20 @@
  *
  * That's it! The Redux tool will auto-detect your store and capture actions.
  *
- * @example Advanced: Manual middleware (only if you need more control)
+ * HOW CAPTURE WORKS (in priority order):
+ * 1. ENHANCER — importing this package claims the official Redux DevTools
+ *    global (`__REDUX_DEVTOOLS_EXTENSION_COMPOSE__`), which RTK checks by
+ *    default. If this package loads before your store module, Buoy is inside
+ *    the store from creation: FULL capture (thunk/RTK Query actions included)
+ *    and real time travel. To guarantee this ordering, make
+ *    `import '@buoy-gg/redux';` the FIRST import of your app entry.
+ * 2. MIDDLEWARE — add `buoyReduxMiddleware` for explicit full capture.
+ * 3. PATCH — otherwise, `FloatingDevTools` binds the store at first mount by
+ *    patching store.dispatch. Top-level dispatches only (thunk-internal
+ *    actions bypass a dispatch patch — that's a Redux architecture fact).
+ *
+ * @example Advanced: Manual middleware (explicit full capture)
  * ```tsx
- * // For time-travel or custom options, you can optionally use middleware:
  * import { buoyReduxMiddleware, withBuoyDevTools } from '@buoy-gg/redux';
  *
  * const store = configureStore({
@@ -42,6 +53,11 @@
  * ```
  */
 
+// SIDE EFFECT (must stay first): claim the Redux DevTools global so stores
+// created after this module loads get the full-capture enhancer. Dev-only,
+// never overrides an existing claimant. See ./redux/utils/devtoolsHook.ts.
+import "./redux/utils/devtoolsHook";
+
 // =============================================================================
 // PRESET (Primary entry point for users)
 // =============================================================================
@@ -55,7 +71,11 @@ export { buoyReduxMiddleware, createBuoyReduxMiddleware, withBuoyDevTools, jumpT
 // =============================================================================
 // AUTO-INSTRUMENTATION (For programmatic store instrumentation)
 // =============================================================================
-export { instrumentStore, uninstrumentStore, isStoreInstrumented, isAutoInstrumentActive, getActiveStore } from "./redux/utils/autoInstrument";
+export { instrumentStore, uninstrumentStore, isStoreInstrumented, isAutoInstrumentActive, getActiveStore, getInstrumentationStatus, registerReduxStore } from "./redux/utils/autoInstrument";
+// Store-creation-time capture (the primary, full-capture path). Claimed as a
+// module side effect above; exported for tests/advanced hosts.
+export { buoyDevtoolsEnhancer, claimDevtoolsHook, isDevtoolsHookClaimed } from "./redux/utils/devtoolsHook";
+
 // =============================================================================
 // HISTORY ADAPTER (For universal history devtools)
 // =============================================================================
@@ -82,6 +102,9 @@ export { ReduxActionItem } from "./redux/components/ReduxActionItem";
 export { ReduxActionDetailView } from "./redux/components/ReduxActionDetailView";
 export { ReduxActionDetailContent, ReduxActionDetailFooter } from "./redux/components/ReduxActionDetailContent";
 export { ReduxIcon } from "./redux/components/ReduxIcon";
+// Headless startup instrumentation — auto-rendered by @buoy-gg/core's
+// FloatingDevTools; exported for hosts that mount devtools their own way.
+export { ReduxAutoInstrument } from "./redux/components/ReduxAutoInstrument";
 
 // =============================================================================
 // TYPES

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

@@ -0,0 +1,17 @@
+"use strict";
+
+import { useAutoInstrumentRedux } from "../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.
+ */
+export function ReduxAutoInstrument() {
+  useAutoInstrumentRedux();
+  return null;
+}