@weasel-js/simulation 0.0.0-stage → 1.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 orochi235
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# @weasel-js/simulation
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Continuous N-body simulation — force-directed layout, physics-ish motion.
+
+Part of [weasel](https://github.com/orochi235/weasel), a domain-agnostic 2D
+scene-graph canvas kit for React. See the
+[API reference](https://orochi235.github.io/weasel/api/).
+
+```sh
+npm install @weasel-js/simulation
+```
+
+`createSimulation` is the root entry and needs no React or DOM. `useSimulation`
+is in `@weasel-js/simulation/react`.
+
+`createSimulation` is the velocity-Verlet integrator and nothing else: `tick()`
+is the only thing that moves a node, so a caller wanting the whole relaxation at
+once — a layout pass, a pre-warm — runs it to settle and reads the answer.
+`useSimulation` is that integrator on a frame loop.
+
+Forces are pluggable functions matching **d3-force's protocol**, so d3-force's
+bundled forces (`forceManyBody`, `forceLink`, `forceCenter`, …) work here
+without translation. Don't invent a parallel force signature.
+
+## The kit doesn't write to your scene
+
+`onTick(nodes)` fires after each integration step and **the consumer decides**
+how, and whether, to write through to scene ops. The simulation holds its own
+node array; it never touches the adapter.
+
+That matters for undo: a simulation running at 60fps would otherwise produce 60
+history entries per second. Typical wiring is to let the sim run free and commit
+a single op when it settles (or on user action), not per tick.
+
+## Alpha and settling
+
+The usual d3 convention: `alpha` decays each tick by `DEFAULT_ALPHA_DECAY`
+until it drops below `DEFAULT_ALPHA_MIN`, at which point the layout is
+considered settled and the loop can stop. `DEFAULT_VELOCITY_DECAY` is the
+per-tick friction.
+
+Reheating (bumping alpha back up) is how you restart motion after a user drags
+a node — otherwise a settled simulation stays settled.
+
+## Related
+
+`@weasel-js/d3` is the packaged integration if you want the d3 ecosystem wired
+up for you rather than assembling forces by hand.

package/dist/chunk-RA6U67OH.js

@@ -0,0 +1,106 @@
+// src/types.ts
+var DEFAULT_ALPHA_DECAY = 1 - Math.pow(1e-3, 1 / 300);
+var DEFAULT_ALPHA_MIN = 1e-3;
+var DEFAULT_VELOCITY_DECAY = 0.4;
+
+// src/createSimulation.ts
+function createSimulation(opts) {
+  let nodes = opts.nodes;
+  let forces = opts.forces ?? [];
+  let alpha = opts.alpha ?? 1;
+  let alphaMin = opts.alphaMin ?? DEFAULT_ALPHA_MIN;
+  let alphaDecay = opts.alphaDecay ?? DEFAULT_ALPHA_DECAY;
+  let alphaTarget = opts.alphaTarget ?? 0;
+  let velocityDecay = opts.velocityDecay ?? DEFAULT_VELOCITY_DECAY;
+  const random = opts.random ?? Math.random;
+  function prime(list) {
+    list.forEach((n, i) => {
+      n.index = i;
+      if (n.vx == null) n.vx = 0;
+      if (n.vy == null) n.vy = 0;
+    });
+  }
+  prime(nodes);
+  for (const f of forces) f.initialize?.(nodes, random);
+  function step() {
+    alpha += (alphaTarget - alpha) * alphaDecay;
+    for (const f of forces) f(alpha);
+    const friction = 1 - velocityDecay;
+    for (const n of nodes) {
+      if (n.fx == null) {
+        n.vx = (n.vx ?? 0) * friction;
+        if (!Number.isFinite(n.vx)) n.vx = 0;
+        n.x += n.vx;
+        if (!Number.isFinite(n.x)) n.x = 0;
+      } else {
+        n.x = n.fx;
+        n.vx = 0;
+      }
+      if (n.fy == null) {
+        n.vy = (n.vy ?? 0) * friction;
+        if (!Number.isFinite(n.vy)) n.vy = 0;
+        n.y += n.vy;
+        if (!Number.isFinite(n.y)) n.y = 0;
+      } else {
+        n.y = n.fy;
+        n.vy = 0;
+      }
+    }
+  }
+  const core = {
+    get nodes() {
+      return nodes;
+    },
+    setNodes(next) {
+      nodes = next;
+      prime(nodes);
+      for (const f of forces) f.initialize?.(nodes, random);
+      return core;
+    },
+    setForces(next) {
+      const old = forces;
+      forces = next;
+      for (const f of next) {
+        if (!old.includes(f)) f.initialize?.(nodes, random);
+      }
+      return core;
+    },
+    alpha(value) {
+      if (value === void 0) return alpha;
+      alpha = value;
+      return core;
+    },
+    alphaTarget(value) {
+      if (value === void 0) return alphaTarget;
+      alphaTarget = value;
+      return core;
+    },
+    alphaDecay(value) {
+      if (value === void 0) return alphaDecay;
+      alphaDecay = value;
+      return core;
+    },
+    alphaMin(value) {
+      if (value === void 0) return alphaMin;
+      alphaMin = value;
+      return core;
+    },
+    velocityDecay(value) {
+      if (value === void 0) return velocityDecay;
+      velocityDecay = value;
+      return core;
+    },
+    tick(iterations = 1) {
+      for (let i = 0; i < iterations; i++) step();
+      return core;
+    },
+    isSettled() {
+      return alpha < alphaMin && alphaTarget === 0;
+    }
+  };
+  return core;
+}
+
+export { DEFAULT_ALPHA_DECAY, DEFAULT_ALPHA_MIN, DEFAULT_VELOCITY_DECAY, createSimulation };
+//# sourceMappingURL=chunk-RA6U67OH.js.map
+//# sourceMappingURL=chunk-RA6U67OH.js.map

package/dist/chunk-RA6U67OH.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/createSimulation.ts"],"names":[],"mappings":"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","file":"chunk-RA6U67OH.js","sourcesContent":["/**\n * Matches d3-force's node shape exactly so d3-force's bundled forces work\n * without translation. Consumers extend this with additional fields.\n */\nexport interface SimulationNode {\n  x: number;\n  y: number;\n  vx?: number;\n  vy?: number;\n  /** Pin x to this value when non-null. The integrator skips x/vx for the node. */\n  fx?: number | null;\n  fy?: number | null;\n  /** Array index, written by `initialize`. Some forces (e.g. forceLink) rely on it. */\n  index?: number;\n}\n\n/**\n * Force protocol — contract-compatible with d3-force. A force is a function\n * called once per tick with the current alpha; it mutates `vx`/`vy` on nodes.\n * Optional `initialize` lets the force compute setup (link indices, etc.).\n */\nexport interface SimulationForce<TNode extends SimulationNode = SimulationNode> {\n  (alpha: number): void;\n  initialize?(nodes: TNode[], random?: () => number): void;\n}\n\n/** Options for `useSimulation`: everything {@link SimulationOptions} carries,\n *  plus the loop's own callbacks and clock. */\nexport interface UseSimulationOptions<TNode extends SimulationNode>\n  extends SimulationOptions<TNode> {\n  /** Fired after each integration step. */\n  onTick?: (nodes: TNode[]) => void;\n  /** Fired once when the sim settles (alpha < alphaMin && alphaTarget === 0). */\n  onEnd?: () => void;\n\n  // Test injection (mirrors useAnimator):\n  /** Optional rAF injection. Defaults to window.requestAnimationFrame. */\n  requestFrame?: (cb: (t: number) => void) => number;\n  cancelFrame?: (handle: number) => void;\n}\n\n/**\n * A force simulation over a set of nodes, with no clock of its own.\n *\n * Each tick applies every force and then integrates velocities, scaled by\n * `alpha` — a temperature that decays toward `alphaTarget` so the layout\n * settles. Raise `alphaTarget` to reheat it.\n *\n * Nodes are mutated in place; the simulation holds the array, not a copy.\n * {@link Simulation} adds the frame loop.\n */\nexport interface SimulationCore<TNode extends SimulationNode> {\n  readonly nodes: TNode[];\n\n  setNodes(nodes: TNode[]): this;\n  setForces(forces: SimulationForce<TNode>[]): this;\n\n  alpha(): number;\n  alpha(value: number): this;\n  alphaTarget(): number;\n  alphaTarget(value: number): this;\n  alphaDecay(): number;\n  alphaDecay(value: number): this;\n  alphaMin(): number;\n  alphaMin(value: number): this;\n  velocityDecay(): number;\n  velocityDecay(value: number): this;\n\n  /** Run the tick body synchronously `iterations` times. Does NOT fire\n   *  onTick or onEnd (matches d3-force). */\n  tick(iterations?: number): this;\n\n  isSettled(): boolean;\n}\n\n/** A {@link SimulationCore} running on a frame loop. */\nexport interface Simulation<TNode extends SimulationNode> extends SimulationCore<TNode> {\n  /** Resume the RAF loop. If alpha < alphaMin, reset alpha to 1. */\n  restart(): this;\n  /** Cancel the RAF loop. Does not change alpha. */\n  stop(): this;\n}\n\n/** What {@link SimulationCore} needs: the nodes, the forces acting on them,\n *  and the cooling schedule. {@link UseSimulationOptions} adds the loop's. */\nexport interface SimulationOptions<TNode extends SimulationNode> {\n  /** Mutable array of nodes. Kit + forces mutate vx/vy/x/y in place. */\n  nodes: TNode[];\n  /** Forces applied per tick. Each may implement `initialize` for setup. */\n  forces?: SimulationForce<TNode>[];\n\n  /** Initial alpha. Default 1. */\n  alpha?: number;\n  /** Settle threshold. When alpha drops below and alphaTarget is 0, onEnd fires. Default 0.001. */\n  alphaMin?: number;\n  /** Per-tick decay rate toward alphaTarget. Default 1 - 0.001^(1/300) ≈ 0.0228. */\n  alphaDecay?: number;\n  /** Target alpha. Set above alphaMin to keep sim warm (e.g. during drag). Default 0. */\n  alphaTarget?: number;\n  /** Friction multiplier on velocity per tick: vx *= (1 - velocityDecay). Default 0.4. */\n  velocityDecay?: number;\n  /** Handed to each force's `initialize`. Default `Math.random`; pass a seeded\n   *  source to make a run reproducible. */\n  random?: () => number;\n}\n\n/** Default alpha decay: such that alpha drops from 1 to alphaMin (0.001) in 300 ticks. */\nexport const DEFAULT_ALPHA_DECAY = 1 - Math.pow(0.001, 1 / 300);\n/** Alpha below which a cooling simulation is considered settled. */\nexport const DEFAULT_ALPHA_MIN = 0.001;\n/** Fraction of velocity shed each tick — friction. Higher settles sooner and\n *  overshoots less. */\nexport const DEFAULT_VELOCITY_DECAY = 0.4;\n","/**\n * The integrator, with no clock attached.\n *\n * Velocity-Verlet over a pluggable force list, contract-compatible with\n * d3-force so d3's own bundled forces drop in untranslated. Nothing here\n * advances time: `tick()` is the only thing that moves a node, and the caller\n * decides how often to call it.\n */\nimport {\n  DEFAULT_ALPHA_DECAY,\n  DEFAULT_ALPHA_MIN,\n  DEFAULT_VELOCITY_DECAY,\n  type SimulationCore,\n  type SimulationForce,\n  type SimulationNode,\n  type SimulationOptions,\n} from './types';\n\n/**\n * A d3-force-compatible simulation with no clock: nothing moves until `tick()`.\n * Nodes are mutated in place, and primed with `index`, `vx` and `vy` on creation.\n */\nexport function createSimulation<TNode extends SimulationNode>(\n  opts: SimulationOptions<TNode>,\n): SimulationCore<TNode> {\n  let nodes = opts.nodes;\n  let forces = opts.forces ?? [];\n  let alpha = opts.alpha ?? 1;\n  let alphaMin = opts.alphaMin ?? DEFAULT_ALPHA_MIN;\n  let alphaDecay = opts.alphaDecay ?? DEFAULT_ALPHA_DECAY;\n  let alphaTarget = opts.alphaTarget ?? 0;\n  let velocityDecay = opts.velocityDecay ?? DEFAULT_VELOCITY_DECAY;\n  const random = opts.random ?? Math.random;\n\n  /** `index` is what `forceLink` and friends address nodes by, and a d3 force\n   *  does `n.vx += …` without checking, so both must exist before the first\n   *  tick or the first tick produces NaN. */\n  function prime(list: TNode[]): void {\n    list.forEach((n, i) => {\n      n.index = i;\n      if (n.vx == null) n.vx = 0;\n      if (n.vy == null) n.vy = 0;\n    });\n  }\n\n  prime(nodes);\n  for (const f of forces) f.initialize?.(nodes, random);\n\n  function step(): void {\n    alpha += (alphaTarget - alpha) * alphaDecay;\n    for (const f of forces) f(alpha);\n\n    const friction = 1 - velocityDecay;\n    for (const n of nodes) {\n      if (n.fx == null) {\n        n.vx = (n.vx ?? 0) * friction;\n        // A non-finite velocity — force overflow, or two nodes exactly\n        // coincident — would reach the renderer as geometry and cost\n        // pathological tessellation work without throwing anywhere.\n        if (!Number.isFinite(n.vx)) n.vx = 0;\n        n.x += n.vx;\n        if (!Number.isFinite(n.x)) n.x = 0;\n      } else {\n        n.x = n.fx;\n        n.vx = 0;\n      }\n      if (n.fy == null) {\n        n.vy = (n.vy ?? 0) * friction;\n        if (!Number.isFinite(n.vy)) n.vy = 0;\n        n.y += n.vy;\n        if (!Number.isFinite(n.y)) n.y = 0;\n      } else {\n        n.y = n.fy;\n        n.vy = 0;\n      }\n    }\n  }\n\n  /* eslint-disable @typescript-eslint/no-explicit-any */\n  const core: any = {\n    get nodes() {\n      return nodes;\n    },\n    setNodes(next: TNode[]) {\n      nodes = next;\n      prime(nodes);\n      for (const f of forces) f.initialize?.(nodes, random);\n      return core;\n    },\n    setForces(next: SimulationForce<TNode>[]) {\n      const old = forces;\n      forces = next;\n      for (const f of next) {\n        if (!old.includes(f)) f.initialize?.(nodes, random);\n      }\n      return core;\n    },\n    alpha(value?: number) {\n      if (value === undefined) return alpha;\n      alpha = value;\n      return core;\n    },\n    alphaTarget(value?: number) {\n      if (value === undefined) return alphaTarget;\n      alphaTarget = value;\n      return core;\n    },\n    alphaDecay(value?: number) {\n      if (value === undefined) return alphaDecay;\n      alphaDecay = value;\n      return core;\n    },\n    alphaMin(value?: number) {\n      if (value === undefined) return alphaMin;\n      alphaMin = value;\n      return core;\n    },\n    velocityDecay(value?: number) {\n      if (value === undefined) return velocityDecay;\n      velocityDecay = value;\n      return core;\n    },\n    tick(iterations: number = 1) {\n      for (let i = 0; i < iterations; i++) step();\n      return core;\n    },\n    isSettled() {\n      return alpha < alphaMin && alphaTarget === 0;\n    },\n  };\n  /* eslint-enable @typescript-eslint/no-explicit-any */\n  return core as SimulationCore<TNode>;\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import { S as SimulationNode, a as SimulationOptions, b as SimulationCore } from './types-CmLrFukG.js';
+export { D as DEFAULT_ALPHA_DECAY, c as DEFAULT_ALPHA_MIN, d as DEFAULT_VELOCITY_DECAY, e as Simulation, f as SimulationForce, U as UseSimulationOptions } from './types-CmLrFukG.js';
+
+/**
+ * The integrator, with no clock attached.
+ *
+ * Velocity-Verlet over a pluggable force list, contract-compatible with
+ * d3-force so d3's own bundled forces drop in untranslated. Nothing here
+ * advances time: `tick()` is the only thing that moves a node, and the caller
+ * decides how often to call it.
+ */
+
+/**
+ * A d3-force-compatible simulation with no clock: nothing moves until `tick()`.
+ * Nodes are mutated in place, and primed with `index`, `vx` and `vy` on creation.
+ */
+declare function createSimulation<TNode extends SimulationNode>(opts: SimulationOptions<TNode>): SimulationCore<TNode>;
+
+export { SimulationCore, SimulationNode, SimulationOptions, createSimulation };

package/dist/index.js

@@ -0,0 +1,3 @@
+export { DEFAULT_ALPHA_DECAY, DEFAULT_ALPHA_MIN, DEFAULT_VELOCITY_DECAY, createSimulation } from './chunk-RA6U67OH.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/react.d.ts

@@ -0,0 +1,14 @@
+import { S as SimulationNode, U as UseSimulationOptions, e as Simulation } from './types-CmLrFukG.js';
+
+/**
+ * Continuous N-body simulation primitive: `createSimulation`'s integrator on a
+ * frame loop.
+ *
+ * The kit is adapter-agnostic — `onTick(nodes)` fires after each integration
+ * step and the consumer decides how (and whether) to write through to scene
+ * state. Per-tick history bypass and settle-commit semantics are consumer
+ * concerns; the kit doesn't have an opinion.
+ */
+declare function useSimulation<TNode extends SimulationNode>(opts: UseSimulationOptions<TNode>): Simulation<TNode>;
+
+export { UseSimulationOptions, useSimulation };

package/dist/react.js

@@ -0,0 +1,115 @@
+import { createSimulation } from './chunk-RA6U67OH.js';
+import { useRef, useLayoutEffect, useMemo } from 'react';
+import { useLatest, useVisibleRaf } from '@weasel-js/react';
+
+function useSimulation(opts) {
+  const optsRef = useLatest(opts);
+  const coreRef = useRef(null);
+  coreRef.current ??= createSimulation(opts);
+  const core = coreRef.current;
+  const endedRef = useRef(false);
+  const mountedRef = useRef(true);
+  const frameLoop = useVisibleRaf(
+    () => {
+      rafTick();
+    },
+    {
+      requestFrame: opts.requestFrame,
+      cancelFrame: opts.cancelFrame
+    }
+  );
+  const stopRaf = () => {
+    frameLoop.cancel();
+  };
+  const rafTick = () => {
+    if (!mountedRef.current) return;
+    core.tick();
+    optsRef.current.onTick?.(core.nodes);
+    if (core.alpha() < core.alphaMin()) {
+      stopRaf();
+      if (!endedRef.current) {
+        endedRef.current = true;
+        optsRef.current.onEnd?.();
+      }
+      return;
+    }
+    frameLoop.request();
+  };
+  const startRaf = () => {
+    if (!mountedRef.current) return;
+    frameLoop.request();
+  };
+  useLayoutEffect(() => {
+    mountedRef.current = true;
+    frameLoop.request();
+    return () => {
+      mountedRef.current = false;
+      frameLoop.cancel();
+    };
+  }, [frameLoop]);
+  const handle = useMemo(() => {
+    const h = {
+      get nodes() {
+        return core.nodes;
+      },
+      setNodes(newNodes) {
+        core.setNodes(newNodes);
+        return h;
+      },
+      setForces(newForces) {
+        core.setForces(newForces);
+        return h;
+      },
+      alpha(value) {
+        if (value === void 0) return core.alpha();
+        core.alpha(value);
+        if (value >= core.alphaMin()) endedRef.current = false;
+        return h;
+      },
+      alphaTarget(value) {
+        if (value === void 0) return core.alphaTarget();
+        core.alphaTarget(value);
+        if (value > 0) endedRef.current = false;
+        return h;
+      },
+      alphaDecay(value) {
+        if (value === void 0) return core.alphaDecay();
+        core.alphaDecay(value);
+        return h;
+      },
+      alphaMin(value) {
+        if (value === void 0) return core.alphaMin();
+        core.alphaMin(value);
+        return h;
+      },
+      velocityDecay(value) {
+        if (value === void 0) return core.velocityDecay();
+        core.velocityDecay(value);
+        return h;
+      },
+      restart() {
+        if (core.alpha() < core.alphaMin()) core.alpha(1);
+        endedRef.current = false;
+        startRaf();
+        return h;
+      },
+      stop() {
+        stopRaf();
+        return h;
+      },
+      tick(iterations = 1) {
+        core.tick(iterations);
+        return h;
+      },
+      isSettled() {
+        return core.isSettled();
+      }
+    };
+    return h;
+  }, []);
+  return handle;
+}
+
+export { useSimulation };
+//# sourceMappingURL=react.js.map
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useSimulation.ts"],"names":[],"mappings":"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","file":"react.js","sourcesContent":["import { useLayoutEffect, useMemo, useRef } from 'react';\nimport { useLatest, useVisibleRaf } from '@weasel-js/react';\nimport { createSimulation } from './createSimulation';\nimport {\n  type Simulation,\n  type SimulationCore,\n  type SimulationForce,\n  type SimulationNode,\n  type UseSimulationOptions,\n} from './types';\n\n/**\n * Continuous N-body simulation primitive: `createSimulation`'s integrator on a\n * frame loop.\n *\n * The kit is adapter-agnostic — `onTick(nodes)` fires after each integration\n * step and the consumer decides how (and whether) to write through to scene\n * state. Per-tick history bypass and settle-commit semantics are consumer\n * concerns; the kit doesn't have an opinion.\n */\nexport function useSimulation<TNode extends SimulationNode>(\n  opts: UseSimulationOptions<TNode>,\n): Simulation<TNode> {\n  const optsRef = useLatest(opts);\n\n  const coreRef = useRef<SimulationCore<TNode> | null>(null);\n  coreRef.current ??= createSimulation(opts);\n  const core = coreRef.current;\n\n  /** Whether onEnd has fired since the last energization (restart / alpha set / target raise). */\n  const endedRef = useRef(false);\n  const mountedRef = useRef(true);\n\n  // The loop runs behind the visibility gate: a settling simulation stops\n  // integrating on a page nobody is looking at, and picks up where it left off.\n  // Its step is fixed rather than time-based, so there is no clock to rebase.\n  // The gate defaults an absent clock to `requestAnimationFrame`, so an\n  // injected one passes straight through rather than being defaulted twice.\n  const frameLoop = useVisibleRaf(\n    () => { rafTick(); },\n    {\n      requestFrame: opts.requestFrame,\n      cancelFrame: opts.cancelFrame,\n    },\n  );\n\n  const stopRaf = (): void => { frameLoop.cancel(); };\n\n  const rafTick = (): void => {\n    if (!mountedRef.current) return;\n\n    core.tick();\n    optsRef.current.onTick?.(core.nodes);\n\n    if (core.alpha() < core.alphaMin()) {\n      stopRaf();\n      if (!endedRef.current) {\n        endedRef.current = true;\n        optsRef.current.onEnd?.();\n      }\n      return;\n    }\n\n    frameLoop.request();\n  };\n\n  const startRaf = (): void => {\n    if (!mountedRef.current) return;\n    frameLoop.request();\n  };\n\n  // Starts on every mount, StrictMode's simulated remount included, and in a\n  // layout effect so a host's own layout effects can already `stop()` it.\n  // `createSimulation` has already primed the nodes.\n  useLayoutEffect(() => {\n    mountedRef.current = true;\n    frameLoop.request();\n    return () => {\n      mountedRef.current = false;\n      frameLoop.cancel();\n    };\n  }, [frameLoop]);\n\n  // Stable handle. All methods read through the core, so a fixed identity is safe.\n  const handle = useMemo<Simulation<TNode>>(() => {\n    /* eslint-disable @typescript-eslint/no-explicit-any */\n    const h: any = {\n      get nodes() {\n        return core.nodes;\n      },\n      setNodes(newNodes: TNode[]) {\n        core.setNodes(newNodes);\n        return h;\n      },\n      setForces(newForces: SimulationForce<TNode>[]) {\n        core.setForces(newForces);\n        return h;\n      },\n      alpha(value?: number) {\n        if (value === undefined) return core.alpha();\n        core.alpha(value);\n        if (value >= core.alphaMin()) endedRef.current = false;\n        return h;\n      },\n      alphaTarget(value?: number) {\n        if (value === undefined) return core.alphaTarget();\n        core.alphaTarget(value);\n        if (value > 0) endedRef.current = false;\n        return h;\n      },\n      alphaDecay(value?: number) {\n        if (value === undefined) return core.alphaDecay();\n        core.alphaDecay(value);\n        return h;\n      },\n      alphaMin(value?: number) {\n        if (value === undefined) return core.alphaMin();\n        core.alphaMin(value);\n        return h;\n      },\n      velocityDecay(value?: number) {\n        if (value === undefined) return core.velocityDecay();\n        core.velocityDecay(value);\n        return h;\n      },\n      restart() {\n        if (core.alpha() < core.alphaMin()) core.alpha(1);\n        endedRef.current = false;\n        startRaf();\n        return h;\n      },\n      stop() {\n        stopRaf();\n        return h;\n      },\n      tick(iterations: number = 1) {\n        core.tick(iterations);\n        return h;\n      },\n      isSettled() {\n        return core.isSettled();\n      },\n    };\n    return h as Simulation<TNode>;\n    /* eslint-enable @typescript-eslint/no-explicit-any */\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n\n  return handle;\n}\n"]}

package/dist/types-CmLrFukG.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Matches d3-force's node shape exactly so d3-force's bundled forces work
+ * without translation. Consumers extend this with additional fields.
+ */
+interface SimulationNode {
+    x: number;
+    y: number;
+    vx?: number;
+    vy?: number;
+    /** Pin x to this value when non-null. The integrator skips x/vx for the node. */
+    fx?: number | null;
+    fy?: number | null;
+    /** Array index, written by `initialize`. Some forces (e.g. forceLink) rely on it. */
+    index?: number;
+}
+/**
+ * Force protocol — contract-compatible with d3-force. A force is a function
+ * called once per tick with the current alpha; it mutates `vx`/`vy` on nodes.
+ * Optional `initialize` lets the force compute setup (link indices, etc.).
+ */
+interface SimulationForce<TNode extends SimulationNode = SimulationNode> {
+    (alpha: number): void;
+    initialize?(nodes: TNode[], random?: () => number): void;
+}
+/** Options for `useSimulation`: everything {@link SimulationOptions} carries,
+ *  plus the loop's own callbacks and clock. */
+interface UseSimulationOptions<TNode extends SimulationNode> extends SimulationOptions<TNode> {
+    /** Fired after each integration step. */
+    onTick?: (nodes: TNode[]) => void;
+    /** Fired once when the sim settles (alpha < alphaMin && alphaTarget === 0). */
+    onEnd?: () => void;
+    /** Optional rAF injection. Defaults to window.requestAnimationFrame. */
+    requestFrame?: (cb: (t: number) => void) => number;
+    cancelFrame?: (handle: number) => void;
+}
+/**
+ * A force simulation over a set of nodes, with no clock of its own.
+ *
+ * Each tick applies every force and then integrates velocities, scaled by
+ * `alpha` — a temperature that decays toward `alphaTarget` so the layout
+ * settles. Raise `alphaTarget` to reheat it.
+ *
+ * Nodes are mutated in place; the simulation holds the array, not a copy.
+ * {@link Simulation} adds the frame loop.
+ */
+interface SimulationCore<TNode extends SimulationNode> {
+    readonly nodes: TNode[];
+    setNodes(nodes: TNode[]): this;
+    setForces(forces: SimulationForce<TNode>[]): this;
+    alpha(): number;
+    alpha(value: number): this;
+    alphaTarget(): number;
+    alphaTarget(value: number): this;
+    alphaDecay(): number;
+    alphaDecay(value: number): this;
+    alphaMin(): number;
+    alphaMin(value: number): this;
+    velocityDecay(): number;
+    velocityDecay(value: number): this;
+    /** Run the tick body synchronously `iterations` times. Does NOT fire
+     *  onTick or onEnd (matches d3-force). */
+    tick(iterations?: number): this;
+    isSettled(): boolean;
+}
+/** A {@link SimulationCore} running on a frame loop. */
+interface Simulation<TNode extends SimulationNode> extends SimulationCore<TNode> {
+    /** Resume the RAF loop. If alpha < alphaMin, reset alpha to 1. */
+    restart(): this;
+    /** Cancel the RAF loop. Does not change alpha. */
+    stop(): this;
+}
+/** What {@link SimulationCore} needs: the nodes, the forces acting on them,
+ *  and the cooling schedule. {@link UseSimulationOptions} adds the loop's. */
+interface SimulationOptions<TNode extends SimulationNode> {
+    /** Mutable array of nodes. Kit + forces mutate vx/vy/x/y in place. */
+    nodes: TNode[];
+    /** Forces applied per tick. Each may implement `initialize` for setup. */
+    forces?: SimulationForce<TNode>[];
+    /** Initial alpha. Default 1. */
+    alpha?: number;
+    /** Settle threshold. When alpha drops below and alphaTarget is 0, onEnd fires. Default 0.001. */
+    alphaMin?: number;
+    /** Per-tick decay rate toward alphaTarget. Default 1 - 0.001^(1/300) ≈ 0.0228. */
+    alphaDecay?: number;
+    /** Target alpha. Set above alphaMin to keep sim warm (e.g. during drag). Default 0. */
+    alphaTarget?: number;
+    /** Friction multiplier on velocity per tick: vx *= (1 - velocityDecay). Default 0.4. */
+    velocityDecay?: number;
+    /** Handed to each force's `initialize`. Default `Math.random`; pass a seeded
+     *  source to make a run reproducible. */
+    random?: () => number;
+}
+/** Default alpha decay: such that alpha drops from 1 to alphaMin (0.001) in 300 ticks. */
+declare const DEFAULT_ALPHA_DECAY: number;
+/** Alpha below which a cooling simulation is considered settled. */
+declare const DEFAULT_ALPHA_MIN = 0.001;
+/** Fraction of velocity shed each tick — friction. Higher settles sooner and
+ *  overshoots less. */
+declare const DEFAULT_VELOCITY_DECAY = 0.4;
+
+export { DEFAULT_ALPHA_DECAY as D, type SimulationNode as S, type UseSimulationOptions as U, type SimulationOptions as a, type SimulationCore as b, DEFAULT_ALPHA_MIN as c, DEFAULT_VELOCITY_DECAY as d, type Simulation as e, type SimulationForce as f };

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@weasel-js/simulation",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.10.0",
+  "description": "A velocity-Verlet N-body integrator that takes d3-force's forces, and a hook that runs it on a frame loop. The root entry has no React and no DOM.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./react": {
+      "import": "./dist/react.js",
+      "types": "./dist/react.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true }
+  },
+  "dependencies": {
+    "@weasel-js/react": "1.10.0"
+  },
+  "author": "orochi235",
+  "homepage": "https://orochi235.github.io/weasel/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/orochi235/weasel.git",
+    "directory": "packages/simulation"
+  },
+  "bugs": {
+    "url": "https://github.com/orochi235/weasel/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}