@buoy-gg/redux 7.0.38 → 7.0.39

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

@@ -1 +1,183 @@
-"use strict";import{useEffect,useState,useRef,useCallback}from"react";import{instrumentStore,uninstrumentStore,getInstrumentationStatus}from"../utils/autoInstrument";import{setReduxDiagnostic}from"../utils/activeStoreRegistry";function getReactReduxUseStore(){try{return require("react-redux").useStore}catch{return null}}export function useAutoInstrumentRedux(e={}){const{autoStart:t=!0}=e,r=useRef(e);r.current=e;const[n,u]=useState(!1),[s,a]=useState(!0),[o,i]=useState(null),[l,c]=useState(null),d=useRef(null),m=getReactReduxUseStore(),R=null!==m;let f=null,x=null,S=null;if(m)try{f=m()}catch(e){S="no-provider",x=e instanceof Error?e.message:"Failed to access Redux store. Make sure your app is wrapped in a Redux Provider."}else S="no-react-redux",x="react-redux is not installed or not available";const g=useCallback(()=>{if(!f)return setReduxDiagnostic(S),i(x||"No Redux store available"),void a(!1);try{const e=instrumentStore(f,r.current);d.current=e,u(!0),c(f),i(null)}catch(e){i(e instanceof Error?e.message:"Failed to instrument Redux store"),u(!1)}finally{a(!1)}},[f]),p=useCallback(()=>{d.current&&(d.current(),d.current=null),l&&uninstrumentStore(l),u(!1),c(null)},[l]);return useEffect(()=>(t?g():a(!1),()=>{}),[t,g]),{isInstrumented:n,isLoading:s,error:o,isReactReduxAvailable:R,captureMechanism:getInstrumentationStatus().mechanism,startInstrumentation:g,stopInstrumentation:p,store:l}}export function useReduxAvailability(){const e=getReactReduxUseStore();if(!e)return{isAvailable:!1,error:"react-redux is not installed"};try{return{isAvailable:null!=e(),error:null}}catch(e){return{isAvailable:!1,error:e instanceof Error?e.message:"Not inside a Redux Provider"}}}
+"use strict";
+
+/**
+ * React hook for auto-instrumenting Redux stores
+ *
+ * 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).
+ *
+ * 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, getInstrumentationStatus } from "../utils/autoInstrument";
+import { setReduxDiagnostic } from "../utils/activeStoreRegistry";
+
+// ============================================
+// Safe Module Loading
+// ============================================
+
+/**
+ * Safely attempt to load react-redux and get useStore hook
+ */
+function getReactReduxUseStore() {
+  try {
+    // Dynamic require to handle cases where react-redux isn't installed
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const reactRedux = require("react-redux");
+    return reactRedux.useStore;
+  } catch {
+    // react-redux not available
+    return null;
+  }
+}
+
+// ============================================
+// Hook Types
+// ============================================
+
+// ============================================
+// Main Hook
+// ============================================
+
+export function useAutoInstrumentRedux(options = {}) {
+  const {
+    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);
+  const [store, setStore] = useState(null);
+  const cleanupRef = useRef(null);
+
+  // Check if react-redux is available
+  const useStoreHook = getReactReduxUseStore();
+  const isReactReduxAvailable = useStoreHook !== null;
+
+  // Try to get the store using react-redux's useStore
+  // 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;
+    }
+    try {
+      // 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);
+      setError(null);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : "Failed to instrument Redux store");
+      setIsInstrumented(false);
+    } finally {
+      setIsLoading(false);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- storeError/storeDiagnostic derive from reduxStore
+  }, [reduxStore]);
+
+  // Function to stop instrumentation
+  const stopInstrumentation = useCallback(() => {
+    if (cleanupRef.current) {
+      cleanupRef.current();
+      cleanupRef.current = null;
+    }
+    if (store) {
+      uninstrumentStore(store);
+    }
+    setIsInstrumented(false);
+    setStore(null);
+  }, [store]);
+
+  // 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();
+    } else {
+      setIsLoading(false);
+    }
+
+    // Cleanup on unmount
+    return () => {
+      // Note: We intentionally DON'T uninstrument on unmount
+      // This allows actions to continue being captured even when
+      // the DevTools modal is closed. The instrumentation persists
+      // for the lifetime of the app, similar to network/storage tools.
+    };
+  }, [autoStart, startInstrumentation]);
+  return {
+    isInstrumented,
+    isLoading,
+    error,
+    isReactReduxAvailable,
+    captureMechanism: getInstrumentationStatus().mechanism,
+    startInstrumentation,
+    stopInstrumentation,
+    store
+  };
+}
+
+/**
+ * Lightweight hook to just check if Redux is available
+ * without auto-instrumenting
+ */
+export function useReduxAvailability() {
+  const useStoreHook = getReactReduxUseStore();
+  if (!useStoreHook) {
+    return {
+      isAvailable: false,
+      error: "react-redux is not installed"
+    };
+  }
+  try {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const store = useStoreHook();
+    return {
+      isAvailable: store !== null && store !== undefined,
+      error: null
+    };
+  } catch (e) {
+    return {
+      isAvailable: false,
+      error: e instanceof Error ? e.message : "Not inside a Redux Provider"
+    };
+  }
+}

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

@@ -1 +1,54 @@
-"use strict";import{useState,useMemo,useCallback}from"react";import{useChangeLog}from"@buoy-gg/shared-ui";import{reduxActionStore}from"../utils/reduxActionStore";const filterActions=(e,t)=>reduxActionStore.filterActions(t);export function useReduxActions(){const e=useChangeLog(reduxActionStore,{filterItems:filterActions}),[t,o]=useState(null),i=useMemo(()=>reduxActionStore.getStats(),[e.items]),r=useMemo(()=>reduxActionStore.getUniqueActionTypes(),[e.items]),s=useCallback(()=>{reduxActionStore.clearActions(),o(null)},[]),c=useCallback(e=>reduxActionStore.getActionById(e),[]);return{actions:e.items,filteredActions:e.filteredItems,filter:e.filter,setFilter:e.setFilter,stats:i,clearActions:s,isEnabled:e.isEnabled,toggleCapture:e.toggleCapture,actionTypes:r,getActionById:c,selectedAction:t,setSelectedAction:o}}
+"use strict";
+
+/**
+ * Hook for consuming Redux actions from the store
+ *
+ * The subscribe / filter / pause / clear plumbing is shared `useChangeLog`;
+ * this file owns the redux-specific stats, action types and selection.
+ */
+
+import { useState, useMemo, useCallback } from "react";
+import { useChangeLog } from "@buoy-gg/shared-ui";
+import { reduxActionStore } from "../utils/reduxActionStore";
+const filterActions = (_actions, filter) => reduxActionStore.filterActions(filter);
+export function useReduxActions() {
+  const log = useChangeLog(reduxActionStore, {
+    filterItems: filterActions
+  });
+  const [selectedAction, setSelectedAction] = useState(null);
+
+  // Get stats
+  const stats = useMemo(() => {
+    return reduxActionStore.getStats();
+  }, [log.items]);
+
+  // Get unique action types
+  const actionTypes = useMemo(() => {
+    return reduxActionStore.getUniqueActionTypes();
+  }, [log.items]);
+
+  // Clear actions
+  const clearActions = useCallback(() => {
+    reduxActionStore.clearActions();
+    setSelectedAction(null);
+  }, []);
+
+  // Get action by ID
+  const getActionById = useCallback(id => {
+    return reduxActionStore.getActionById(id);
+  }, []);
+  return {
+    actions: log.items,
+    filteredActions: log.filteredItems,
+    filter: log.filter,
+    setFilter: log.setFilter,
+    stats,
+    clearActions,
+    isEnabled: log.isEnabled,
+    toggleCapture: log.toggleCapture,
+    actionTypes,
+    getActionById,
+    selectedAction,
+    setSelectedAction
+  };
+}

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

@@ -1 +1,188 @@
-"use strict";import{reduxActionStore,STATE_ON_DEVICE,PAYLOAD_ON_DEVICE,isEvictedState}from"../utils/reduxActionStore";import{WIRE_DETAIL_LIMIT_BYTES,capDetail,createSyncAdapter,memoByIdentity,readParams,toWire}from"@buoy-gg/shared-ui";import{getActiveStore,getInstrumentationStatus}from"../utils/autoInstrument";const toWireValue=t=>toWire(t,PAYLOAD_ON_DEVICE),toWireAction=memoByIdentity(t=>{const e=isEvictedState(t.prevState)?{...t}:{...t,prevState:STATE_ON_DEVICE,nextState:STATE_ON_DEVICE};if(e.payload=toWireValue(e.payload),e.action=toWireValue(e.action),e.error=toWireValue(e.error),e.meta){const t=toWireValue(e.meta.arg);t!==e.meta.arg&&(e.meta={...e.meta,arg:t})}return e});function topLevelKeys(t){return t&&"object"==typeof t&&!Array.isArray(t)?Object.keys(t):[]}function unavailable(){return{available:!1,slices:[],reason:getInstrumentationStatus().diagnostic??"not-instrumented"}}export const reduxSyncAdapter=createSyncAdapter({version:2,getSnapshot:()=>reduxActionStore.getActions().map(toWireAction),subscribe:t=>reduxActionStore.subscribe(t),actions:{clearEvents:()=>{reduxActionStore.clearActions()},getActionDetail:t=>{const{id:e}=readParams(t);if(!e)return{found:!1,reason:"missing id"};const r=reduxActionStore.getActionById(e);if(!r)return{found:!1,reason:"unknown id"};if(isEvictedState(r.prevState))return{found:!0,id:e,evicted:!0,reason:"Raw state was evicted (retained for recent actions only)."};const a=t=>capDetail(t,WIRE_DETAIL_LIMIT_BYTES);return{found:!0,id:e,prevState:a(r.prevState),nextState:a(r.nextState),payload:a(r.payload),action:a(r.action),meta:(t=>{if(!t)return t;const e=a(t.arg);return e===t.arg?t:{...t,arg:e}})(r.meta),error:a(r.error)}},getState:t=>{const{includeValues:e=!1}=readParams(t),r=getActiveStore();if(!r)return unavailable();const a=r.getState(),n=getInstrumentationStatus();return{available:!0,slices:topLevelKeys(a),capture:n.capture,mechanism:n.mechanism,...e?{state:a}:{}}},dispatch:t=>{const{action:e}=readParams(t),r=getActiveStore();if(!r)return{dispatched:!1,...unavailable()};if(!e)throw new Error("dispatch requires an `action`");return r.dispatch(e),{dispatched:!0,type:e.type}}}});
+"use strict";
+
+import { reduxActionStore, STATE_ON_DEVICE, PAYLOAD_ON_DEVICE, isEvictedState } from "../utils/reduxActionStore";
+import { WIRE_DETAIL_LIMIT_BYTES, capDetail, createSyncAdapter, memoByIdentity, readParams, toWire } from "@buoy-gg/shared-ui";
+import { getActiveStore, getInstrumentationStatus } from "../utils/autoInstrument";
+
+/** Per-action budget for `payload`/`action`/`meta.arg`/`error` on the snapshot wire. */
+const toWireValue = value => toWire(value, PAYLOAD_ON_DEVICE);
+
+/**
+ * Per-action wire cache. `reduxActionStore` never mutates an action in place —
+ * it prepends, and `replaceActions` maps to fresh objects — so keying on
+ * identity is correct and self-invalidating. Without it, every payload,
+ * `action`, `meta.arg` and `error` in the list is re-measured on all ~5
+ * snapshots per second for as long as it stays in the list.
+ */
+const toWireAction = memoByIdentity(a => {
+  const wire = isEvictedState(a.prevState) ? {
+    ...a
+  } : {
+    ...a,
+    prevState: STATE_ON_DEVICE,
+    nextState: STATE_ON_DEVICE
+  };
+  // A dispatched payload can itself be huge (rehydration actions carry whole
+  // state trees). The list view renders payloadPreview anyway — oversized /
+  // unserializable values stay on-device behind markers. `meta.arg` is a
+  // leftover: RTK copies the thunk argument there, and capping `action` still
+  // left the extracted copy on the wire.
+  wire.payload = toWireValue(wire.payload);
+  wire.action = toWireValue(wire.action);
+  wire.error = toWireValue(wire.error);
+  if (wire.meta) {
+    const arg = toWireValue(wire.meta.arg);
+    if (arg !== wire.meta.arg) wire.meta = {
+      ...wire.meta,
+      arg
+    };
+  }
+  return wire;
+});
+/** 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 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
+ * dispatch actions — redux is action-based, so the *current state* isn't in the
+ * action-log snapshot.
+ */
+export const reduxSyncAdapter = createSyncAdapter({
+  version: 2,
+  /**
+   * WIRE-FORM snapshot: actions WITHOUT raw prevState/nextState trees.
+   * Shipping the trees serialized up to 25×2 full state trees through
+   * socket.emit per action — no guard on that path — which froze and
+   * native-OOM-crashed enterprise-scale apps whenever a dashboard was
+   * connected (root cause confirmed by patch-and-retest). Dashboards fetch
+   * trees on demand via `getActionDetail`; already-evicted entries keep the
+   * eviction sentinel so consumers can distinguish "fetchable" from "gone".
+   */
+  getSnapshot: () => reduxActionStore.getActions().map(toWireAction),
+  subscribe: onChange => reduxActionStore.subscribe(onChange),
+  actions: {
+    clearEvents: () => {
+      reduxActionStore.clearActions();
+    },
+    /**
+     * On-demand detail: one action's real prevState/nextState trees.
+     * The per-snapshot stream stays tree-free; this is the explicit,
+     * size-guarded channel for the detail pane.
+     */
+    getActionDetail: params => {
+      const {
+        id
+      } = readParams(params);
+      if (!id) return {
+        found: false,
+        reason: "missing id"
+      };
+      const action = reduxActionStore.getActionById(id);
+      if (!action) return {
+        found: false,
+        reason: "unknown id"
+      };
+      if (isEvictedState(action.prevState)) {
+        return {
+          found: true,
+          id,
+          evicted: true,
+          reason: `Raw state was evicted (retained for recent actions only).`
+        };
+      }
+      // Per-field cap: oversized fields degrade individually instead of
+      // failing the whole detail (a giant payload shouldn't hide the trees).
+      const cap = value => capDetail(value, WIRE_DETAIL_LIMIT_BYTES);
+      const capMeta = meta => {
+        if (!meta) return meta;
+        const arg = cap(meta.arg);
+        return arg === meta.arg ? meta : {
+          ...meta,
+          arg
+        };
+      };
+      return {
+        found: true,
+        id,
+        prevState: cap(action.prevState),
+        nextState: cap(action.nextState),
+        payload: cap(action.payload),
+        action: cap(action.action),
+        meta: capMeta(action.meta),
+        error: cap(action.error)
+      };
+    },
+    /**
+     * Compact current-state reader: the instrumented store's slice names, and
+     * the full state tree only when `includeValues` is set (heavy).
+     */
+    getState: params => {
+      const {
+        includeValues = false
+      } = readParams(params);
+      const store = getActiveStore();
+      if (!store) {
+        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
+        } : {})
+      };
+    },
+    /** Dispatch a plain action object to the instrumented store. */
+    dispatch: params => {
+      const {
+        action
+      } = readParams(params);
+      const store = getActiveStore();
+      if (!store) {
+        return {
+          dispatched: false,
+          ...unavailable()
+        };
+      }
+      if (!action) throw new Error("dispatch requires an `action`");
+      store.dispatch(action);
+      return {
+        dispatched: true,
+        type: action.type
+      };
+    }
+  }
+});

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

@@ -1 +1,92 @@
-"use strict";export const ENHANCER_SYMBOL=Symbol.for("@@buoy/enhancerInstrumented");let activeStore=null,mechanism=null,diagnostic=null,timeTravelReducer=!1;export function registerActiveStore(e,t){activeStore=e,mechanism=t,diagnostic=null}export function unregisterActiveStore(e){activeStore===e&&(activeStore=null,mechanism=null)}export function getActiveStore(){return activeStore}export function getCaptureMechanism(){return mechanism}export function markTimeTravelReducer(){timeTravelReducer=!0}export function isTimeTravelAvailable(){return timeTravelReducer&&null!==activeStore}export function setReduxDiagnostic(e){diagnostic=e}export function getInstrumentationStatus(){return{mechanism:mechanism,capture:"enhancer"===mechanism||"middleware"===mechanism?"full":"patch"===mechanism?"top-level-only":"none",hasStore:null!==activeStore,timeTravel:isTimeTravelAvailable(),diagnostic:diagnostic}}
+"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;
+let timeTravelReducer = false;
+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;
+}
+
+/**
+ * Record that a reducer able to serve `BUOY_JUMP_TO_STATE` is in the store.
+ *
+ * Called by the devtools-hook enhancer and by `withBuoyDevTools` — the only
+ * two things that wrap the root reducer. Capture and time travel are separate
+ * capabilities and they are wired separately: a store can be fully captured
+ * through `buoyReduxMiddleware` and still have no way to restore a state,
+ * because middleware sits ABOVE the reducer and cannot replace what it
+ * returns.
+ */
+export function markTimeTravelReducer() {
+  timeTravelReducer = true;
+}
+
+/**
+ * Whether pressing JUMP can actually do anything.
+ *
+ * Worth a first-class answer rather than a try-and-see, because the failure is
+ * invisible: `jumpToState` dispatches into a store that simply does not
+ * recognise the action, the reducer returns the state it already had, and the
+ * screen does not move. From the outside that is indistinguishable from a
+ * devtool that is broken.
+ */
+export function isTimeTravelAvailable() {
+  return timeTravelReducer && activeStore !== null;
+}
+
+/**
+ * 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,
+    timeTravel: isTimeTravelAvailable(),
+    diagnostic
+  };
+}