@fundamental-engine/core 0.4.0

package/dist/core/geometry.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Shaped-source geometry (field-systems plan, Stage A).
+ *
+ * A body is not a point. These pure helpers derive the geometry a shaped source needs
+ * from the rect we already measure each frame: the nearest point on the element's box
+ * (so matter shells the shape instead of collapsing to its centre), the signed distance
+ * to the box (negative inside), and the two poles of a dipole laid along the body's
+ * heading (so `magnetism`/`charge` can draw and act as real N→S / +→− fields).
+ *
+ * Nothing here touches particles or velocity. Stage B (the field-line render) and Stage C
+ * (shaped force sampling) consume these; this stage is groundwork with golden tests.
+ */
+import type { Vec2 } from './types.ts';
+/** Guard against divide-by-zero when sampling a field at a pole (1px, sub-pixel). */
+export declare const EPS = 1;
+/** An axis-aligned box: centre + half-extents. The force-facing subset of `Body`. */
+export interface Rect {
+    cx: number;
+    cy: number;
+    hw: number;
+    hh: number;
+}
+/** A box plus its heading and polarity — what `polePair` reads off a `Body`. */
+export interface AxisRect extends Rect {
+    /** unit heading (cos θ, sin θ) from `data-angle`. */
+    ux: number;
+    uy: number;
+    /** polarity sign; which end carries the + / N pole. */
+    spin: number;
+}
+/** One pole of a dipole: a position and a signed charge (±1). */
+export interface Pole {
+    x: number;
+    y: number;
+    q: number;
+}
+/**
+ * The nearest point of the filled box to `(px, py)`. Outside the box this is the closest
+ * boundary point; inside, it is the point itself (the box is solid, so distance is zero).
+ * Shaped attract/gravity pull toward this instead of the centre, so matter gathers in a
+ * shell around the element rather than a blob at its middle.
+ */
+export declare function nearestOnRect(px: number, py: number, r: Rect): Vec2;
+/**
+ * Signed distance from `(px, py)` to the box: negative inside, zero on the edge, positive
+ * outside (the standard 2D box SDF). Falloffs key off this so the field references the
+ * element's surface, not an arbitrary centre distance.
+ */
+export declare function sdfRect(px: number, py: number, r: Rect): number;
+/**
+ * The two poles of the body's dipole, laid on its heading axis at the box edge. The `+`
+ * (N) pole sits at the `+(ux, uy)` end, the `−` (S) pole at the other; `spin < 0` swaps
+ * them. `reach` is the centre-to-edge distance along the heading (the ray/box exit), so a
+ * wide element makes a long magnet and a tall one a short, fat magnet. Strength is applied
+ * by the consumer (`field()`), not here — this returns geometry and polarity only.
+ */
+export declare function polePair(b: AxisRect): [Pole, Pole];
+/**
+ * The in-plane field of a set of poles at `(x, y)`: the superposition of each pole's
+ * radial `q/d²` monopole field (away from `+`, toward `−`). For the two poles of a body
+ * this is the classic dipole, whose streamlines are the bar-magnet (N→S) and
+ * electric-dipole (+→−) field-line diagrams. `EPS` floors the distance at a pole so the
+ * sample never divides by zero. Direction carries the geometry; magnitude (scaled by the
+ * body's strength downstream) sets line density and the tracer's min-strength cutoff.
+ */
+export declare function dipoleField(poles: readonly Pole[], x: number, y: number): Vec2;
+//# sourceMappingURL=geometry.d.ts.map

package/dist/core/geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geometry.d.ts","sourceRoot":"","sources":["../../src/core/geometry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAGvC,qFAAqF;AACrF,eAAO,MAAM,GAAG,IAAI,CAAC;AAErB,qFAAqF;AACrF,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,gFAAgF;AAChF,MAAM,WAAW,QAAS,SAAQ,IAAI;IACpC,qDAAqD;IACrD,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,iEAAiE;AACjE,MAAM,WAAW,IAAI;IACnB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,GAAG,IAAI,CAKnE;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,GAAG,MAAM,CAM/D;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,QAAQ,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAWlD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAY9E"}

package/dist/core/geometry.js

@@ -0,0 +1,68 @@
+import { clamp } from "./math.js";
+/** Guard against divide-by-zero when sampling a field at a pole (1px, sub-pixel). */
+export const EPS = 1;
+/**
+ * The nearest point of the filled box to `(px, py)`. Outside the box this is the closest
+ * boundary point; inside, it is the point itself (the box is solid, so distance is zero).
+ * Shaped attract/gravity pull toward this instead of the centre, so matter gathers in a
+ * shell around the element rather than a blob at its middle.
+ */
+export function nearestOnRect(px, py, r) {
+    return {
+        x: clamp(px, r.cx - r.hw, r.cx + r.hw),
+        y: clamp(py, r.cy - r.hh, r.cy + r.hh),
+    };
+}
+/**
+ * Signed distance from `(px, py)` to the box: negative inside, zero on the edge, positive
+ * outside (the standard 2D box SDF). Falloffs key off this so the field references the
+ * element's surface, not an arbitrary centre distance.
+ */
+export function sdfRect(px, py, r) {
+    const dx = Math.abs(px - r.cx) - r.hw;
+    const dy = Math.abs(py - r.cy) - r.hh;
+    const outside = Math.hypot(Math.max(dx, 0), Math.max(dy, 0));
+    const inside = Math.min(Math.max(dx, dy), 0);
+    return outside + inside;
+}
+/**
+ * The two poles of the body's dipole, laid on its heading axis at the box edge. The `+`
+ * (N) pole sits at the `+(ux, uy)` end, the `−` (S) pole at the other; `spin < 0` swaps
+ * them. `reach` is the centre-to-edge distance along the heading (the ray/box exit), so a
+ * wide element makes a long magnet and a tall one a short, fat magnet. Strength is applied
+ * by the consumer (`field()`), not here — this returns geometry and polarity only.
+ */
+export function polePair(b) {
+    const tx = b.ux !== 0 ? b.hw / Math.abs(b.ux) : Infinity;
+    const ty = b.uy !== 0 ? b.hh / Math.abs(b.uy) : Infinity;
+    const reach = Math.min(tx, ty); // centre → box edge along the heading
+    const ax = b.ux * reach;
+    const ay = b.uy * reach;
+    const s = b.spin < 0 ? -1 : 1;
+    return [
+        { x: b.cx + ax, y: b.cy + ay, q: s },
+        { x: b.cx - ax, y: b.cy - ay, q: -s },
+    ];
+}
+/**
+ * The in-plane field of a set of poles at `(x, y)`: the superposition of each pole's
+ * radial `q/d²` monopole field (away from `+`, toward `−`). For the two poles of a body
+ * this is the classic dipole, whose streamlines are the bar-magnet (N→S) and
+ * electric-dipole (+→−) field-line diagrams. `EPS` floors the distance at a pole so the
+ * sample never divides by zero. Direction carries the geometry; magnitude (scaled by the
+ * body's strength downstream) sets line density and the tracer's min-strength cutoff.
+ */
+export function dipoleField(poles, x, y) {
+    let fx = 0;
+    let fy = 0;
+    for (const p of poles) {
+        const dx = x - p.x;
+        const dy = y - p.y;
+        const d = Math.max(EPS, Math.hypot(dx, dy));
+        const k = p.q / (d * d); // radial monopole, 1/d² falloff
+        fx += (dx / d) * k;
+        fy += (dy / d) * k;
+    }
+    return { x: fx, y: fy };
+}
+//# sourceMappingURL=geometry.js.map

package/dist/core/geometry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"geometry.js","sourceRoot":"","sources":["../../src/core/geometry.ts"],"names":[],"mappings":"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"}

package/dist/core/heatmap.d.ts

@@ -0,0 +1,22 @@
+import type { Particle } from './types.ts';
+export declare class Heatmap {
+    private grid;
+    /** eased running peak, for flicker-free normalization. */
+    private peak;
+    /** grid resolution in px (the render samples on this lattice). */
+    readonly cell = 24;
+    constructor(width: number, height: number);
+    resize(width: number, height: number): void;
+    /**
+     * Zero every cell in the accumulation buffer and reset the peak tracker. Called by
+     * `setHeatmap(false)` so that re-enabling starts with a clean slate rather than
+     * carrying over stale density from a previous active period. Also the right call after
+     * a hard field reset where continuity of the heat history would be misleading.
+     */
+    clear(): void;
+    /** Deposit the current particle field, decay + blur, and track the peak. Call once a frame. */
+    update(particles: readonly Particle[]): void;
+    /** Normalized density ∈ [0, 1] at a point — for the glow render and DOM write-back. */
+    norm(x: number, y: number): number;
+}
+//# sourceMappingURL=heatmap.d.ts.map

package/dist/core/heatmap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heatmap.d.ts","sourceRoot":"","sources":["../../src/core/heatmap.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAM3C,qBAAa,OAAO;IAClB,OAAO,CAAC,IAAI,CAAiB;IAC7B,0DAA0D;IAC1D,OAAO,CAAC,IAAI,CAAQ;IACpB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,MAAQ;gBAET,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAIzC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAI3C;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IAKb,+FAA+F;IAC/F,MAAM,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,GAAG,IAAI;IAU5C,uFAAuF;IACvF,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM;CAGnC"}

package/dist/core/heatmap.js

@@ -0,0 +1,55 @@
+/**
+ * Heatmaps (field-systems plan, H1) — a scalar field buffer that reveals where field state
+ * accumulates, rendered as a diagnostic/ambient layer and sampled back into DOM. NOT a force:
+ * it measures, it does not push (docs/engine-reference/forces-fields-plan.md, D5).
+ *
+ * H1 ships the **density** layer: each frame every particle deposits into a coarse grid that
+ * decays and lightly blurs, so the buffer tracks where matter currently gathers. Values are
+ * normalized to [0, 1] by an eased running peak, so the glow render and the
+ * `--field-heatmap-density` write-back are stable and resolution-independent. Built on the
+ * existing class-[C] `ScalarGridImpl`, the same buffer the diffuse/wave/memory forces use.
+ */
+import { ScalarGridImpl } from "./scalar-grid.js";
+import { clamp } from "./math.js";
+const CELL = 24; // grid resolution in px — coarse, so the per-frame deposit + render is cheap
+const DECAY = 0.12; // per-frame fade: high enough that the map tracks the CURRENT density
+const BLUR = 0.22; // light diffusion, for a smooth glow rather than blocky cells
+export class Heatmap {
+    grid;
+    /** eased running peak, for flicker-free normalization. */
+    peak = 1e-3;
+    /** grid resolution in px (the render samples on this lattice). */
+    cell = CELL;
+    constructor(width, height) {
+        this.grid = new ScalarGridImpl(Math.max(1, width), Math.max(1, height), 'diffuse', CELL);
+    }
+    resize(width, height) {
+        this.grid.resize(width, height);
+    }
+    /**
+     * Zero every cell in the accumulation buffer and reset the peak tracker. Called by
+     * `setHeatmap(false)` so that re-enabling starts with a clean slate rather than
+     * carrying over stale density from a previous active period. Also the right call after
+     * a hard field reset where continuity of the heat history would be misleading.
+     */
+    clear() {
+        this.grid.clear();
+        this.peak = 1e-3;
+    }
+    /** Deposit the current particle field, decay + blur, and track the peak. Call once a frame. */
+    update(particles) {
+        for (const p of particles)
+            this.grid.deposit(p.x, p.y, 1);
+        this.grid.stepDiffuse(BLUR, DECAY);
+        const m = this.grid.max();
+        // ease the peak up fast (so a sudden spike normalizes promptly) and down slowly (so the
+        // map doesn't flare as the field empties); floored so we never divide by zero.
+        const k = m > this.peak ? 0.25 : 0.03;
+        this.peak += (Math.max(m, 1e-3) - this.peak) * k;
+    }
+    /** Normalized density ∈ [0, 1] at a point — for the glow render and DOM write-back. */
+    norm(x, y) {
+        return clamp(this.grid.sample(x, y) / this.peak, 0, 1);
+    }
+}
+//# sourceMappingURL=heatmap.js.map

package/dist/core/heatmap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heatmap.js","sourceRoot":"","sources":["../../src/core/heatmap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAGlC,MAAM,IAAI,GAAG,EAAE,CAAC,CAAC,6EAA6E;AAC9F,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,sEAAsE;AAC1F,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,8DAA8D;AAEjF,MAAM,OAAO,OAAO;IACV,IAAI,CAAiB;IAC7B,0DAA0D;IAClD,IAAI,GAAG,IAAI,CAAC;IACpB,kEAAkE;IACzD,IAAI,GAAG,IAAI,CAAC;IAErB,YAAY,KAAa,EAAE,MAAc;QACvC,IAAI,CAAC,IAAI,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;IAC3F,CAAC;IAED,MAAM,CAAC,KAAa,EAAE,MAAc;QAClC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAClC,CAAC;IAED;;;;;OAKG;IACH,KAAK;QACH,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QAClB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,+FAA+F;IAC/F,MAAM,CAAC,SAA8B;QACnC,KAAK,MAAM,CAAC,IAAI,SAAS;YAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC1D,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACnC,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QAC1B,wFAAwF;QACxF,+EAA+E;QAC/E,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;QACtC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnD,CAAC;IAED,uFAAuF;IACvF,IAAI,CAAC,CAAS,EAAE,CAAS;QACvB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACzD,CAAC;CACF"}

package/dist/core/host.d.ts

@@ -0,0 +1,46 @@
+/**
+ * FieldHost — the renderer/environment seam (Phase: frontier). `createField`'s engine is
+ * renderer-agnostic: every DOM-global touchpoint (viewport size, scroll, rAF, reduced-motion,
+ * visibility, the scan root, and event wiring) goes through this injected host instead of `window` /
+ * `document` / `requestAnimationFrame` directly. `browserHost()` (in `@fundamental-engine/platform`)
+ * binds it to the browser; an alternative host could drive the same engine from a headless renderer,
+ * a different document, or a test harness. This interface is pure types — no globals — so `field.ts`
+ * imports zero DOM (enforced by `dom-boundary.test.ts`).
+ */
+/** The host's current viewport, in CSS px plus device-pixel ratio. */
+export interface HostViewport {
+    width: number;
+    height: number;
+    dpr: number;
+}
+export interface FieldHost {
+    /** the subtree scanned for `[data-body]` / `[data-move]` / `[data-on]` / `[data-hot]` / `[data-formation]`. */
+    root: ParentNode;
+    /** the current viewport size + DPR (read each resize). */
+    viewport(): HostViewport;
+    /** current vertical scroll offset in px. */
+    scrollY(): number;
+    /** the scrollable height of the page (cached by the caller — reading it forces reflow). */
+    scrollHeight(): number;
+    /** whether the user prefers reduced motion (freezes the sim). */
+    reducedMotion(): boolean;
+    /** whether the surface is hidden (backgrounded tab) — pauses the loop. */
+    hidden(): boolean;
+    /** schedule the next frame; returns a handle. */
+    raf(cb: (t: number) => void): number;
+    /** cancel a scheduled frame. */
+    cancelRaf(id: number): void;
+    /** an offscreen canvas for the heatmap buffer. */
+    createCanvas(): HTMLCanvasElement;
+    /** subscribe to viewport-resize; returns an unsubscribe. */
+    onResize(cb: () => void): () => void;
+    /** subscribe to scroll; returns an unsubscribe. */
+    onScroll(cb: () => void): () => void;
+    /** subscribe to surface visibility changes; returns an unsubscribe. */
+    onVisibility(cb: () => void): () => void;
+    /** subscribe to user input activity (pointer/wheel/key/touch); returns an unsubscribe. */
+    onInput(cb: () => void): () => void;
+    /** subscribe to a composed shadow-DOM body event by name; returns an unsubscribe. */
+    onBodyEvent(type: string, cb: (e: Event) => void): () => void;
+}
+//# sourceMappingURL=host.d.ts.map

package/dist/core/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/core/host.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,SAAS;IACxB,+GAA+G;IAC/G,IAAI,EAAE,UAAU,CAAC;IACjB,0DAA0D;IAC1D,QAAQ,IAAI,YAAY,CAAC;IACzB,4CAA4C;IAC5C,OAAO,IAAI,MAAM,CAAC;IAClB,2FAA2F;IAC3F,YAAY,IAAI,MAAM,CAAC;IACvB,iEAAiE;IACjE,aAAa,IAAI,OAAO,CAAC;IACzB,0EAA0E;IAC1E,MAAM,IAAI,OAAO,CAAC;IAClB,iDAAiD;IACjD,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,CAAC;IACrC,gCAAgC;IAChC,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,kDAAkD;IAClD,YAAY,IAAI,iBAAiB,CAAC;IAClC,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IACrC,mDAAmD;IACnD,QAAQ,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IACrC,uEAAuE;IACvE,YAAY,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IACzC,0FAA0F;IAC1F,OAAO,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IACpC,qFAAqF;IACrF,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC/D"}

package/dist/core/host.js

@@ -0,0 +1,11 @@
+/**
+ * FieldHost — the renderer/environment seam (Phase: frontier). `createField`'s engine is
+ * renderer-agnostic: every DOM-global touchpoint (viewport size, scroll, rAF, reduced-motion,
+ * visibility, the scan root, and event wiring) goes through this injected host instead of `window` /
+ * `document` / `requestAnimationFrame` directly. `browserHost()` (in `@fundamental-engine/platform`)
+ * binds it to the browser; an alternative host could drive the same engine from a headless renderer,
+ * a different document, or a test harness. This interface is pure types — no globals — so `field.ts`
+ * imports zero DOM (enforced by `dom-boundary.test.ts`).
+ */
+export {};
+//# sourceMappingURL=host.js.map

package/dist/core/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../../src/core/host.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/core/integrator.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The integrator — advances the field one tick (§2.2, §7).
+ *
+ * For each free particle: apply DOM-body forces (§4), the formation bias (§7),
+ * then integrate and damp. Under first-class mass (§21.3) each additive body force is
+ * scaled by `1/m` as it applies, while velocity-replacing (`kinematic`) forces are left
+ * untouched. Reduced motion (`dt = 0`) freezes the sim (§18).
+ */
+import type { Body, ConditionRegistry, Env, ForceRegistry } from './types.ts';
+import type { FieldStore } from './field-store.ts';
+import { type Wave } from './currents.ts';
+export declare const FRICTION = 0.95;
+export declare const HEAT_DECAY = 0.972;
+export interface StepInput {
+    store: FieldStore;
+    bodies: readonly Body[];
+    env: Env;
+    forces: ForceRegistry;
+    conditions: ConditionRegistry;
+    /** the carrier waves — free particles drift along their slope (§2.3). */
+    waves?: readonly Wave[];
+}
+export declare function step(input: StepInput): void;
+//# sourceMappingURL=integrator.d.ts.map

package/dist/core/integrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrator.d.ts","sourceRoot":"","sources":["../../src/core/integrator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAE,GAAG,EAAS,aAAa,EAAY,MAAM,YAAY,CAAC;AAC/F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAsB,KAAK,IAAI,EAAE,MAAM,eAAe,CAAC;AAK9D,eAAO,MAAM,QAAQ,OAAO,CAAC;AAC7B,eAAO,MAAM,UAAU,QAAQ,CAAC;AAGhC,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,SAAS,IAAI,EAAE,CAAC;IACxB,GAAG,EAAE,GAAG,CAAC;IACT,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,yEAAyE;IACzE,KAAK,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;CACzB;AA2CD,wBAAgB,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CA6S3C"}