@aiready/components 0.14.2 → 0.14.4

package/src/hooks/useForceSimulation.ts

@@ -1,5 +1,20 @@
-// Import helpers from separate module
-import { stabilizeNodes, seedRandomPositions } from './simulation-helpers';
+/**
+ * Hook for managing d3-force simulations
+ * Automatically handles simulation lifecycle, tick updates, and cleanup
+ */
+
+import { useEffect, useRef, useState, useCallback } from 'react';
+import * as d3 from 'd3';
+import {
+  seedRandomPositions,
+  seedCircularPositions,
+  safelyStopSimulation,
+} from './simulation-helpers';
+import {
+  SIMULATION_DEFAULTS,
+  FORCE_NAMES,
+  EVENT_NAMES,
+} from './simulation-constants';
 import type {
   SimulationNode,
   SimulationLink,
@@ -7,99 +22,43 @@ import type {
   UseForceSimulationReturn,
 } from './simulation-types';
 
-import { useEffect, useRef, useState } from 'react';
-import * as d3 from 'd3';
+/**
+ * Enhanced return type for the force simulation hook
+ */
+export interface UseForceSimulationReturnExt extends UseForceSimulationReturn {
+  /**
+   * Enable or disable simulation forces (charge and link forces)
+   */
+  setForcesEnabled: (enabled: boolean) => void;
+}
 
 /**
- * Hook for managing d3-force simulations
- * Automatically handles simulation lifecycle, tick updates, and cleanup
- *
- * @param initialNodes - Initial nodes for the simulation
- * @param initialLinks - Initial links for the simulation
- * @param options - Configuration options for the force simulation
- * @returns Simulation state and control functions
- *
- * @example
- * ```tsx
- * function NetworkGraph() {
- *   const nodes = [
- *     { id: 'node1', name: 'Node 1' },
- *     { id: 'node2', name: 'Node 2' },
- *     { id: 'node3', name: 'Node 3' },
- *   ];
- *
- *   const links = [
- *     { source: 'node1', target: 'node2' },
- *     { source: 'node2', target: 'node3' },
- *   ];
- *
- *   const { nodes: simulatedNodes, links: simulatedLinks, restart } = useForceSimulation(
- *     nodes,
- *     links,
- *     {
- *       width: 800,
- *       height: 600,
- *       chargeStrength: -500,
- *       linkDistance: 150,
- *     }
- *   );
- *
- *   return (
- *     <svg width={800} height={600}>
- *       {simulatedLinks.map((link, i) => (
- *         <line
- *           key={i}
- *           x1={(link.source as SimulationNode).x}
- *           y1={(link.source as SimulationNode).y}
- *           x2={(link.target as SimulationNode).x}
- *           y2={(link.target as SimulationNode).y}
- *           stroke="#999"
- *         />
- *       ))}
- *       {simulatedNodes.map((node) => (
- *         <circle
- *           key={node.id}
- *           cx={node.x}
- *           cy={node.y}
- *           r={10}
- *           fill="#69b3a2"
- *         />
- *       ))}
- *     </svg>
- *   );
- * }
- * ```
+ * useForceSimulation: robust d3-force management with React
+ * @lastUpdated 2026-03-27
  */
 export function useForceSimulation(
   initialNodes: SimulationNode[],
   initialLinks: SimulationLink[],
   options: ForceSimulationOptions
-): UseForceSimulationReturn & { setForcesEnabled: (enabled: boolean) => void } {
-  /**
-   * Enable or disable the simulation forces (charge and link forces).
-   * When disabled, nodes can still be dragged but won't be affected by forces.
-   * @param enabled - When true, simulation forces are active; when false, forces are disabled
-   */
+): UseForceSimulationReturnExt {
   const {
-    chargeStrength = -300,
-    linkDistance = 100,
-    linkStrength = 1,
-    collisionStrength = 1,
-    collisionRadius = 10,
-    centerStrength = 0.1,
+    chargeStrength = SIMULATION_DEFAULTS.CHARGE_STRENGTH,
+    linkDistance = SIMULATION_DEFAULTS.LINK_DISTANCE,
+    linkStrength = SIMULATION_DEFAULTS.LINK_STRENGTH,
+    collisionStrength = SIMULATION_DEFAULTS.COLLISION_STRENGTH,
+    collisionRadius = SIMULATION_DEFAULTS.COLLISION_RADIUS,
+    centerStrength = SIMULATION_DEFAULTS.CENTER_STRENGTH,
     width,
     height,
-    alphaDecay = 0.0228,
-    velocityDecay = 0.4,
-    alphaTarget = 0,
-    warmAlpha = 0.3,
-    alphaMin = 0.01,
+    alphaDecay = SIMULATION_DEFAULTS.ALPHA_DECAY,
+    velocityDecay = SIMULATION_DEFAULTS.VELOCITY_DECAY,
+    alphaTarget = SIMULATION_DEFAULTS.ALPHA_TARGET,
+    warmAlpha = SIMULATION_DEFAULTS.WARM_ALPHA,
+    alphaMin = SIMULATION_DEFAULTS.ALPHA_MIN,
     onTick,
-    // Optional throttle in milliseconds for tick updates (reduce React re-renders)
-    // Lower values = smoother but more CPU; default ~30ms (~33fps)
-    stabilizeOnStop = true,
-    tickThrottleMs = 33,
-    maxSimulationTimeMs = 3000,
+    stabilizeOnStop = SIMULATION_DEFAULTS.STABILIZE_ON_STOP,
+    tickThrottleMs = SIMULATION_DEFAULTS.TICK_THROTTLE_MS,
+    maxSimulationTimeMs = SIMULATION_DEFAULTS.MAX_SIMULATION_TIME_MS,
   } = options;
 
   const [nodes, setNodes] = useState<SimulationNode[]>(initialNodes);
@@ -112,12 +71,15 @@ export function useForceSimulation(
     SimulationLink
   > | null>(null);
   const stopTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const forcesEnabledRef = useRef(true);
+  const originalForcesRef = useRef({
+    charge: chargeStrength,
+    link: linkStrength,
+  });
 
-  // Create lightweight keys for nodes/links so we only recreate the simulation
-  // when the actual identity/content of inputs change (not when parent passes
-  // new array references on each render).
+  // Unique keys to detect when to rebuild the simulation
   const nodesKey = initialNodes.map((n) => n.id).join('|');
-  const linksKey = (initialLinks || [])
+  const linksKey = initialLinks
     .map((l) => {
       const sourceId =
         typeof l.source === 'string'
@@ -127,254 +89,42 @@ export function useForceSimulation(
         typeof l.target === 'string'
           ? l.target
           : (l.target as SimulationNode)?.id;
-      const linkType = (l as SimulationLink & { type?: string }).type || '';
+      const linkType = (l as any).type || '';
       return `${sourceId}->${targetId}:${linkType}`;
     })
     .join('|');
 
+  /**
+   * Internal effect to manage simulation lifecycle
+   */
   useEffect(() => {
-    // Create a copy of nodes and links to avoid mutating the original data
     const nodesCopy = initialNodes.map((node) => ({ ...node }));
     const linksCopy = initialLinks.map((link) => ({ ...link }));
 
-    // ALWAYS seed initial positions to ensure nodes don't stack at origin
-    // This is critical for force-directed graphs to work properly
     try {
-      // Always seed positions for all nodes when simulation is created
-      // This ensures nodes start spread out even if they have coordinates
-      nodesCopy.forEach((n, i) => {
-        // Use deterministic but more widely spread positions based on index
-        const angle = (i * 2 * Math.PI) / nodesCopy.length;
-        // Larger seed radius to encourage an initial spread
-        const radius = Math.min(width, height) * 0.45;
-        n.x = width / 2 + radius * Math.cos(angle);
-        n.y = height / 2 + radius * Math.sin(angle);
-        // Add very small random velocity to avoid large initial motion
-        n.vx = (Math.random() - 0.5) * 2;
-        n.vy = (Math.random() - 0.5) * 2;
-      });
-    } catch (e) {
-      console.warn('Failed to seed node positions, falling back to random:', e);
-      // If error, fall back to random positions
+      seedCircularPositions(nodesCopy, width, height);
+    } catch (error) {
+      console.warn(
+        'AIReady: Position seeding failed, using random fallback:',
+        error
+      );
       seedRandomPositions(nodesCopy, width, height);
     }
 
-    // Create the simulation
-    const simulation = d3.forceSimulation(
-      nodesCopy as SimulationNode[]
-    ) as d3.Simulation<SimulationNode, SimulationLink>;
-
-    // Configure link force separately to avoid using generic type args on d3 helpers
-    try {
-      const linkForce = d3.forceLink(
-        linksCopy as d3.SimulationLinkDatum<SimulationNode>[]
-      ) as d3.ForceLink<SimulationNode, d3.SimulationLinkDatum<SimulationNode>>;
-      linkForce
-        .id((d: SimulationNode) => d.id)
-        .distance((d: d3.SimulationLinkDatum<SimulationNode>) => {
-          const link = d as SimulationLink & { distance?: number };
-          return link && link.distance != null ? link.distance : linkDistance;
-        })
-        .strength(linkStrength);
-      simulation.force(
-        'link',
-        linkForce as d3.Force<
-          SimulationNode,
-          d3.SimulationLinkDatum<SimulationNode>
-        >
-      );
-    } catch (e) {
-      console.warn('Failed to configure link force, using fallback:', e);
-      // fallback: attach a plain link force
-      try {
-        simulation.force(
-          'link',
-          d3.forceLink(
-            linksCopy as d3.SimulationLinkDatum<SimulationNode>[]
-          ) as d3.Force<SimulationNode, d3.SimulationLinkDatum<SimulationNode>>
-        );
-      } catch (fallbackError) {
-        console.warn('Fallback link force also failed:', fallbackError);
-      }
-    }
-    try {
-      simulation.force(
-        'charge',
-        d3.forceManyBody().strength(chargeStrength) as d3.Force<
-          SimulationNode,
-          d3.SimulationLinkDatum<SimulationNode>
-        >
-      );
-      simulation.force(
-        'center',
-        d3
-          .forceCenter(width / 2, height / 2)
-          .strength(centerStrength) as d3.Force<
-          SimulationNode,
-          d3.SimulationLinkDatum<SimulationNode>
-        >
-      );
-      const collide = d3
-        .forceCollide()
-        .radius((d: d3.SimulationNodeDatum) => {
-          const node = d as SimulationNode;
-          const nodeSize = node && node.size ? (node.size as number) : 10;
-          return nodeSize + collisionRadius;
-        })
-        .strength(collisionStrength) as d3.Force<
-        SimulationNode,
-        d3.SimulationLinkDatum<SimulationNode>
-      >;
-      simulation.force('collision', collide);
-      simulation.force(
-        'x',
-        d3
-          .forceX(width / 2)
-          .strength(Math.max(0.02, centerStrength * 0.5)) as d3.Force<
-          SimulationNode,
-          d3.SimulationLinkDatum<SimulationNode>
-        >
-      );
-      simulation.force(
-        'y',
-        d3
-          .forceY(height / 2)
-          .strength(Math.max(0.02, centerStrength * 0.5)) as d3.Force<
-          SimulationNode,
-          d3.SimulationLinkDatum<SimulationNode>
-        >
-      );
-      simulation.alphaDecay(alphaDecay);
-      simulation.velocityDecay(velocityDecay);
-      simulation.alphaMin(alphaMin);
-      try {
-        simulation.alphaTarget(alphaTarget);
-      } catch (e) {
-        console.warn('Failed to set alpha target:', e);
-      }
-      try {
-        simulation.alpha(warmAlpha);
-      } catch (e) {
-        console.warn('Failed to set initial alpha:', e);
-      }
-    } catch (e) {
-      console.warn('Failed to configure simulation forces:', e);
-      // ignore force configuration errors
-    }
+    const simulation = d3.forceSimulation<SimulationNode, SimulationLink>(
+      nodesCopy
+    );
+    applySimulationForces(simulation, linksCopy);
+    configureSimulationParameters(simulation);
 
     simulationRef.current = simulation;
 
-    // Force-stop timeout to ensure simulation doesn't run forever.
-    if (stopTimeoutRef.current != null) {
-      try {
-        globalThis.clearTimeout(stopTimeoutRef.current);
-      } catch (e) {
-        console.warn('Failed to clear simulation timeout:', e);
-      }
-      stopTimeoutRef.current = null;
-    }
-    if (maxSimulationTimeMs && maxSimulationTimeMs > 0) {
-      stopTimeoutRef.current = globalThis.setTimeout(() => {
-        try {
-          if (stabilizeOnStop) {
-            stabilizeNodes(nodesCopy);
-          }
-          simulation.alpha(0);
-          simulation.stop();
-        } catch (e) {
-          console.warn('Failed to stop simulation:', e);
-        }
-        setIsRunning(false);
-        setNodes([...nodesCopy]);
-        setLinks([...linksCopy]);
-      }, maxSimulationTimeMs);
-    }
+    const rafState = { rafId: null as number | null, lastUpdate: 0 };
+    setupTickHandler(simulation, nodesCopy, linksCopy, rafState);
 
-    // Update state on each tick. Batch updates via requestAnimationFrame to avoid
-    // excessive React re-renders which can cause visual flicker.
-    let rafId: number | null = null;
-    let lastUpdate = 0;
-    const tickHandler = () => {
-      try {
-        if (typeof onTick === 'function')
-          onTick(nodesCopy, linksCopy, simulation);
-      } catch (e) {
-        console.warn('Tick callback error:', e);
-      }
+    setupStopTimer(simulation, nodesCopy, linksCopy);
 
-      // If simulation alpha has cooled below the configured minimum, stop it to
-      // ensure nodes don't drift indefinitely (acts as a hard-stop safeguard).
-      try {
-        if (simulation.alpha() <= alphaMin) {
-          try {
-            if (stabilizeOnStop) {
-              stabilizeNodes(nodesCopy);
-            }
-            simulation.stop();
-          } catch (e) {
-            console.warn('Failed to stop simulation:', e);
-          }
-          setAlpha(simulation.alpha());
-          setIsRunning(false);
-          setNodes([...nodesCopy]);
-          setLinks([...linksCopy]);
-          return;
-        }
-      } catch (e) {
-        console.warn('Error checking simulation alpha:', e);
-      }
-
-      const now = Date.now();
-      const shouldUpdate = now - lastUpdate >= tickThrottleMs;
-      if (rafId == null && shouldUpdate) {
-        rafId = (
-          globalThis.requestAnimationFrame ||
-          ((cb: FrameRequestCallback) => setTimeout(cb, 16))
-        )(() => {
-          rafId = null;
-          lastUpdate = Date.now();
-          setNodes([...nodesCopy]);
-          setLinks([...linksCopy]);
-          setAlpha(simulation.alpha());
-          setIsRunning(simulation.alpha() > simulation.alphaMin());
-        });
-      }
-    };
-
-    simulation.on('tick', tickHandler);
-
-    simulation.on('end', () => {
-      setIsRunning(false);
-    });
-
-    // Cleanup on unmount
-    return () => {
-      try {
-        simulation.on('tick', null);
-      } catch (e) {
-        console.warn('Failed to clear simulation tick handler:', e);
-      }
-      if (stopTimeoutRef.current != null) {
-        try {
-          globalThis.clearTimeout(stopTimeoutRef.current);
-        } catch (e) {
-          console.warn('Failed to clear timeout on cleanup:', e);
-        }
-        stopTimeoutRef.current = null;
-      }
-      if (rafId != null) {
-        try {
-          (
-            globalThis.cancelAnimationFrame ||
-            ((id: number) => clearTimeout(id))
-          )(rafId);
-        } catch (e) {
-          console.warn('Failed to cancel animation frame:', e);
-        }
-        rafId = null;
-      }
-      simulation.stop();
-    };
+    return () => cleanupSimulation(simulation, rafState);
   }, [
     nodesKey,
     linksKey,
@@ -395,86 +145,241 @@ export function useForceSimulation(
     maxSimulationTimeMs,
   ]);
 
-  const restart = () => {
-    if (simulationRef.current) {
-      // Reheat the simulation to a modest alpha target rather than forcing
-      // full heat; this matches the Observable pattern and helps stability.
-      try {
-        simulationRef.current.alphaTarget(warmAlpha).restart();
-      } catch {
-        simulationRef.current.restart();
-      }
-      setIsRunning(true);
-      // Reset safety timeout when simulation is manually restarted
-      if (stopTimeoutRef.current != null) {
+  /**
+   * Applies d3 forces to the simulation instance
+   */
+  const applySimulationForces = (
+    simulation: d3.Simulation<SimulationNode, SimulationLink>,
+    linksCopy: SimulationLink[]
+  ) => {
+    try {
+      const linkForce = d3
+        .forceLink<SimulationNode, SimulationLink>(linksCopy)
+        .id((d) => d.id)
+        .distance((d) => (d as any).distance ?? linkDistance)
+        .strength(linkStrength);
+
+      simulation
+        .force(FORCE_NAMES.LINK, linkForce)
+        .force(FORCE_NAMES.CHARGE, d3.forceManyBody().strength(chargeStrength))
+        .force(
+          FORCE_NAMES.CENTER,
+          d3.forceCenter(width / 2, height / 2).strength(centerStrength)
+        )
+        .force(
+          FORCE_NAMES.COLLISION,
+          d3
+            .forceCollide<SimulationNode>()
+            .radius((d) => (d.size ?? 10) + collisionRadius)
+            .strength(collisionStrength)
+        )
+        .force(
+          FORCE_NAMES.X,
+          d3.forceX(width / 2).strength(Math.max(0.02, centerStrength * 0.5))
+        )
+        .force(
+          FORCE_NAMES.Y,
+          d3.forceY(height / 2).strength(Math.max(0.02, centerStrength * 0.5))
+        );
+    } catch (error) {
+      console.warn('AIReady: Failed to configure simulation forces:', error);
+    }
+  };
+
+  /**
+   * Configures simulation decay and heat parameters
+   */
+  const configureSimulationParameters = (
+    simulation: d3.Simulation<SimulationNode, SimulationLink>
+  ) => {
+    simulation
+      .alphaDecay(alphaDecay)
+      .velocityDecay(velocityDecay)
+      .alphaMin(alphaMin)
+      .alphaTarget(alphaTarget)
+      .alpha(warmAlpha);
+  };
+
+  /**
+   * Sets up a timer to force-stop the simulation after maxSimulationTimeMs
+   */
+  const setupStopTimer = (
+    simulation: d3.Simulation<SimulationNode, SimulationLink>,
+    nodesCopy: SimulationNode[],
+    linksCopy: SimulationLink[]
+  ) => {
+    if (stopTimeoutRef.current) {
+      clearTimeout(stopTimeoutRef.current);
+    }
+
+    if (maxSimulationTimeMs > 0) {
+      stopTimeoutRef.current = setTimeout(() => {
+        safelyStopSimulation(simulation, nodesCopy, {
+          stabilize: stabilizeOnStop,
+        });
+        updateStateAfterStop(nodesCopy, linksCopy, 0);
+      }, maxSimulationTimeMs);
+    }
+  };
+
+  /**
+   * Updates state variables after simulation stops
+   */
+  const updateStateAfterStop = (
+    nodesCopy: SimulationNode[],
+    linksCopy: SimulationLink[],
+    currentAlpha: number
+  ) => {
+    setIsRunning(false);
+    setAlpha(currentAlpha);
+    setNodes([...nodesCopy]);
+    setLinks([...linksCopy]);
+  };
+
+  /**
+   * Manages simulation ticks and React state sync
+   */
+  const setupTickHandler = (
+    simulation: d3.Simulation<SimulationNode, SimulationLink>,
+    nodesCopy: SimulationNode[],
+    linksCopy: SimulationLink[],
+    rafState: { rafId: number | null; lastUpdate: number }
+  ) => {
+    const handleTick = () => {
+      if (onTick) {
         try {
-          globalThis.clearTimeout(stopTimeoutRef.current);
-        } catch (e) {
-          console.warn('Failed to clear simulation timeout:', e);
+          onTick(nodesCopy, linksCopy, simulation);
+        } catch (error) {
+          console.warn('AIReady: Simulation onTick callback failed:', error);
         }
-        stopTimeoutRef.current = null;
       }
-      if (maxSimulationTimeMs && maxSimulationTimeMs > 0) {
-        stopTimeoutRef.current = globalThis.setTimeout(() => {
-          try {
-            simulationRef.current?.alpha(0);
-            simulationRef.current?.stop();
-          } catch (e) {
-            console.warn('Failed to stop simulation:', e);
-          }
-          setIsRunning(false);
-        }, maxSimulationTimeMs);
+
+      const currentAlpha = simulation.alpha();
+      if (currentAlpha <= alphaMin) {
+        safelyStopSimulation(simulation, nodesCopy, {
+          stabilize: stabilizeOnStop,
+        });
+        updateStateAfterStop(nodesCopy, linksCopy, currentAlpha);
+        return;
       }
-    }
+
+      syncStateOnTick(nodesCopy, linksCopy, currentAlpha, rafState);
+    };
+
+    simulation.on(EVENT_NAMES.TICK, handleTick);
+    simulation.on(EVENT_NAMES.END, () => setIsRunning(false));
   };
 
-  const stop = () => {
-    if (simulationRef.current) {
-      simulationRef.current.stop();
-      setIsRunning(false);
+  /**
+   * Syncs simulation results to React state using requestAnimationFrame
+   */
+  const syncStateOnTick = (
+    nodesCopy: SimulationNode[],
+    linksCopy: SimulationLink[],
+    currentAlpha: number,
+    rafState: { rafId: number | null; lastUpdate: number }
+  ) => {
+    const now = Date.now();
+    if (
+      rafState.rafId === null &&
+      now - rafState.lastUpdate >= tickThrottleMs
+    ) {
+      rafState.rafId = requestAnimationFrame(() => {
+        rafState.rafId = null;
+        rafState.lastUpdate = Date.now();
+        setNodes([...nodesCopy]);
+        setLinks([...linksCopy]);
+        setAlpha(currentAlpha);
+        setIsRunning(currentAlpha > alphaMin);
+      });
     }
   };
 
-  const originalForcesRef = useRef({
-    charge: chargeStrength,
-    link: linkStrength,
-    collision: collisionStrength,
-  });
-  const forcesEnabledRef = useRef(true);
+  /**
+   * Cleanup routine for simulation unmount or rebuild
+   */
+  const cleanupSimulation = (
+    simulation: d3.Simulation<SimulationNode, SimulationLink>,
+    rafState: { rafId: number | null }
+  ) => {
+    simulation.on(EVENT_NAMES.TICK, null);
+    if (stopTimeoutRef.current) clearTimeout(stopTimeoutRef.current);
+    if (rafState.rafId !== null) cancelAnimationFrame(rafState.rafId);
+    simulation.stop();
+  };
 
-  const setForcesEnabled = (enabled: boolean) => {
+  /**
+   * Restart the simulation manually
+   */
+  const restartSimulation = useCallback(() => {
     const sim = simulationRef.current;
     if (!sim) return;
-    // avoid repeated updates
-    if (forcesEnabledRef.current === enabled) return;
-    forcesEnabledRef.current = enabled;
 
     try {
-      // Only toggle charge and link forces to avoid collapse; keep collision/centering
-      const charge = sim.force(
-        'charge'
-      ) as d3.ForceManyBody<SimulationNode> | null;
-      if (charge && typeof charge.strength === 'function') {
-        charge.strength(enabled ? originalForcesRef.current.charge : 0);
+      sim.alphaTarget(warmAlpha).restart();
+      setIsRunning(true);
+      if (stopTimeoutRef.current) clearTimeout(stopTimeoutRef.current);
+      if (maxSimulationTimeMs > 0) {
+        stopTimeoutRef.current = setTimeout(() => {
+          sim.alpha(0);
+          sim.stop();
+          setIsRunning(false);
+        }, maxSimulationTimeMs);
       }
+    } catch (error) {
+      console.warn('AIReady: Failed to restart simulation:', error);
+    }
+  }, [warmAlpha, maxSimulationTimeMs]);
 
-      const link = sim.force('link') as d3.ForceLink<
-        SimulationNode,
-        d3.SimulationLinkDatum<SimulationNode>
-      > | null;
-      if (link && typeof link.strength === 'function') {
-        link.strength(enabled ? originalForcesRef.current.link : 0);
-      }
-    } catch (e) {
-      console.warn('Failed to toggle simulation forces:', e);
+  /**
+   * Stop the simulation manually
+   */
+  const stopSimulation = useCallback(() => {
+    if (simulationRef.current) {
+      simulationRef.current.stop();
+      setIsRunning(false);
     }
-  };
+  }, []);
+
+  /**
+   * Enable or disable simulation forces
+   */
+  const setForcesEnabled = useCallback(
+    (enabled: boolean) => {
+      const sim = simulationRef.current;
+      if (!sim || forcesEnabledRef.current === enabled) return;
+
+      forcesEnabledRef.current = enabled;
+
+      try {
+        const charge = sim.force(
+          FORCE_NAMES.CHARGE
+        ) as d3.ForceManyBody<SimulationNode> | null;
+        if (charge) {
+          charge.strength(enabled ? originalForcesRef.current.charge : 0);
+        }
+
+        const link = sim.force(FORCE_NAMES.LINK) as d3.ForceLink<
+          SimulationNode,
+          SimulationLink
+        > | null;
+        if (link) {
+          link.strength(enabled ? originalForcesRef.current.link : 0);
+        }
+
+        sim.alpha(warmAlpha).restart();
+      } catch (error) {
+        console.warn('AIReady: Failed to toggle simulation forces:', error);
+      }
+    },
+    [warmAlpha]
+  );
 
   return {
     nodes,
     links,
-    restart,
-    stop,
+    restart: restartSimulation,
+    stop: stopSimulation,
     isRunning,
     alpha,
     setForcesEnabled,
@@ -483,58 +388,38 @@ export function useForceSimulation(
 
 /**
  * Hook for creating a draggable force simulation
- * Provides drag handlers that can be attached to node elements
- *
- * @param simulation - The d3 force simulation instance
- * @returns Drag behavior that can be applied to nodes
- *
- * @example
- * ```tsx
- * function DraggableNetworkGraph() {
- *   const simulation = useRef<d3.Simulation<SimulationNode, SimulationLink>>();
- *   const drag = useDrag(simulation.current);
- *
- *   return (
- *     <svg>
- *       {nodes.map((node) => (
- *         <circle
- *           key={node.id}
- *           {...drag}
- *           cx={node.x}
- *           cy={node.y}
- *           r={10}
- *         />
- *       ))}
- *     </svg>
- *   );
- * }
- * ```
  */
 export function useDrag(
   simulation: d3.Simulation<SimulationNode, any> | null | undefined
 ) {
-  const dragStarted = (event: any, node: SimulationNode) => {
-    if (!simulation) return;
-    if (!event.active) simulation.alphaTarget(0.3).restart();
-    node.fx = node.x;
-    node.fy = node.y;
-  };
+  const handleDragStart = useCallback(
+    (event: any, node: SimulationNode) => {
+      if (!simulation) return;
+      if (!event.active) simulation.alphaTarget(0.3).restart();
+      node.fx = node.x;
+      node.fy = node.y;
+    },
+    [simulation]
+  );
 
-  const dragged = (event: any, node: SimulationNode) => {
+  const handleDragged = useCallback((event: any, node: SimulationNode) => {
     node.fx = event.x;
     node.fy = event.y;
-  };
+  }, []);
 
-  const dragEnded = (event: any, node: SimulationNode) => {
-    if (!simulation) return;
-    if (!event.active) simulation.alphaTarget(0);
-    node.fx = null;
-    node.fy = null;
-  };
+  const handleDragEnd = useCallback(
+    (event: any, node: SimulationNode) => {
+      if (!simulation) return;
+      if (!event.active) simulation.alphaTarget(0);
+      node.fx = null;
+      node.fy = null;
+    },
+    [simulation]
+  );
 
   return {
-    onDragStart: dragStarted,
-    onDrag: dragged,
-    onDragEnd: dragEnded,
+    onDragStart: handleDragStart,
+    onDrag: handleDragged,
+    onDragEnd: handleDragEnd,
   };
 }