@buoy-gg/redux 7.0.35 → 7.0.38

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

@@ -1,183 +1 @@
-"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"
-    };
-  }
-}
+"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"}}}

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

@@ -1,54 +1 @@
-"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
-  };
-}
+"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}}

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

@@ -1,188 +1 @@
-"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
-      };
-    }
-  }
-});
+"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}}}});

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

@@ -1,92 +1 @@
-"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
-  };
-}
+"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}}