@fundamental-engine/core 0.4.0

package/dist/config/palettes.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Color templates for the field's travelling accent (§9) and particle tint. The
+ * accent journeys through these stops as you scroll; `setPalette` / the `palette`
+ * option swap the whole set live.
+ *
+ * `ours` is the canonical forces journey; the others are recognizable scientific
+ * ramps. Stops are ordered cool → hot (or by spectrum), chosen to read as accents
+ * on the dark substrate.
+ */
+export declare const PALETTES: Record<string, readonly string[]>;
+/** Names of the built-in palettes, in display order. */
+export declare const PALETTE_NAMES: readonly ["ours", "heatmap", "infrared", "spectrum"];
+/**
+ * Resolve a palette option to its color stops: a name looks up `PALETTES`, an array
+ * is used as-is, anything unknown or empty falls back to the canonical journey.
+ */
+export declare function resolvePalette(p?: string | readonly string[]): readonly string[];
+//# sourceMappingURL=palettes.d.ts.map

package/dist/config/palettes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"palettes.d.ts","sourceRoot":"","sources":["../../src/config/palettes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAStD,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,aAAa,sDAAuD,CAAC;AAElF;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE,CAIhF"}

package/dist/config/palettes.js

@@ -0,0 +1,34 @@
+/**
+ * Color templates for the field's travelling accent (§9) and particle tint. The
+ * accent journeys through these stops as you scroll; `setPalette` / the `palette`
+ * option swap the whole set live.
+ *
+ * `ours` is the canonical forces journey; the others are recognizable scientific
+ * ramps. Stops are ordered cool → hot (or by spectrum), chosen to read as accents
+ * on the dark substrate.
+ */
+import { ACCENT_JOURNEY } from "./forces.config.js";
+export const PALETTES = {
+    /** the canonical forces accent journey. */
+    ours: ACCENT_JOURNEY,
+    /** classic heatmap: cool blue → cyan → green → yellow → orange → red. */
+    heatmap: ['#2b3a8c', '#2d8fd4', '#3fd07a', '#ffe14d', '#ff8a3d', '#e23b3b'],
+    /** thermal "ironbow": deep purple → magenta → red → amber → pale yellow. */
+    infrared: ['#2a0a4a', '#8e24aa', '#e53935', '#ff8f00', '#ffd54f', '#fffde7'],
+    /** the visible spectrum: red → orange → yellow → green → teal → blue → violet. */
+    spectrum: ['#ff3b30', '#ff9500', '#ffcc00', '#34c759', '#00c7be', '#007aff', '#af52de'],
+};
+/** Names of the built-in palettes, in display order. */
+export const PALETTE_NAMES = ['ours', 'heatmap', 'infrared', 'spectrum'];
+/**
+ * Resolve a palette option to its color stops: a name looks up `PALETTES`, an array
+ * is used as-is, anything unknown or empty falls back to the canonical journey.
+ */
+export function resolvePalette(p) {
+    if (Array.isArray(p))
+        return p.length > 0 ? p : ACCENT_JOURNEY;
+    if (typeof p === 'string')
+        return PALETTES[p] ?? ACCENT_JOURNEY;
+    return ACCENT_JOURNEY;
+}
+//# sourceMappingURL=palettes.js.map

package/dist/config/palettes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"palettes.js","sourceRoot":"","sources":["../../src/config/palettes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,MAAM,CAAC,MAAM,QAAQ,GAAsC;IACzD,2CAA2C;IAC3C,IAAI,EAAE,cAAc;IACpB,yEAAyE;IACzE,OAAO,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC;IAC3E,4EAA4E;IAC5E,QAAQ,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC;IAC5E,kFAAkF;IAClF,QAAQ,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC;CACxF,CAAC;AAEF,wDAAwD;AACxD,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,CAAU,CAAC;AAElF;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,CAA8B;IAC3D,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC;IAC/D,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC,CAAC,CAAC,IAAI,cAAc,CAAC;IAChE,OAAO,cAAc,CAAC;AACxB,CAAC"}

package/dist/config/presets.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The preset layer (§20.9) — cosmology as *named arrangements of primitives*, not
+ * new force modules.
+ *
+ * An element with `data-preset="blackhole"` expands into several **co-located virtual
+ * bodies**, each a single primitive with its *own* attrs, all bound to the same rect.
+ * This solves the one blocker the spec calls out: a plain `data-body="attract swirl
+ * sink"` shares one strength/range across every token, so the horizon (`sink`)
+ * can't be tuned independently of the well (`attract`). A preset gives each primitive
+ * its own parameters.
+ *
+ * The force loop is unchanged — it already iterates `bodies × tokens` (§4); the
+ * scanner just emits more bodies (`scanner.ts` → `expandPreset`). Presets are opt-in:
+ * a page using `data-body` is entirely unaffected.
+ *
+ * This file is pure data (no imports), so it can't create an import cycle with the
+ * scanner that consumes it. Entries use only *implemented* tokens — the canonical nine
+ * (§6), the natural primitives (§20.10), and the designed-extended forces (§20.3, e.g.
+ * `lens`, `buoyancy`, `spawn`). A composite that needs a still-unbuilt atom (e.g. `warp`,
+ * §20.6) waits until it lands.
+ */
+/** One virtual body in a preset — a single primitive with its own parameters (§20.9). */
+export interface PresetEntry {
+    /** the primitive token this virtual body runs (a single force). */
+    body: string;
+    /** force magnitude S (and, for gravity/charge, the source scalar GM). */
+    strength?: number;
+    /** influence radius, px. */
+    range?: number;
+    /** swirl/charge/magnetism sign or spin (±). */
+    spin?: number;
+    /** heading in degrees, for stream/jet. */
+    angle?: number;
+    /** capture radius, for sink. */
+    absorb?: number;
+    /** load at which a sink supernovas. */
+    max?: number;
+    /** lifespan (frames) of matter a class-[S] source emits — the `data-life` budget. */
+    life?: number;
+    /** max live particles a class-[S] source sustains — the `data-cap` budget. */
+    cap?: number;
+}
+/**
+ * The preset table (§20.9 composite map). Tunable starting points — refine when each
+ * is actually demoed, since these never touch the live site until opted into.
+ */
+export declare const PRESETS: Record<string, readonly PresetEntry[]>;
+//# sourceMappingURL=presets.d.ts.map

package/dist/config/presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../../src/config/presets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,yFAAyF;AACzF,MAAM,WAAW,WAAW;IAC1B,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qFAAqF;IACrF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CA4D1D,CAAC"}

package/dist/config/presets.js

@@ -0,0 +1,87 @@
+/**
+ * The preset layer (§20.9) — cosmology as *named arrangements of primitives*, not
+ * new force modules.
+ *
+ * An element with `data-preset="blackhole"` expands into several **co-located virtual
+ * bodies**, each a single primitive with its *own* attrs, all bound to the same rect.
+ * This solves the one blocker the spec calls out: a plain `data-body="attract swirl
+ * sink"` shares one strength/range across every token, so the horizon (`sink`)
+ * can't be tuned independently of the well (`attract`). A preset gives each primitive
+ * its own parameters.
+ *
+ * The force loop is unchanged — it already iterates `bodies × tokens` (§4); the
+ * scanner just emits more bodies (`scanner.ts` → `expandPreset`). Presets are opt-in:
+ * a page using `data-body` is entirely unaffected.
+ *
+ * This file is pure data (no imports), so it can't create an import cycle with the
+ * scanner that consumes it. Entries use only *implemented* tokens — the canonical nine
+ * (§6), the natural primitives (§20.10), and the designed-extended forces (§20.3, e.g.
+ * `lens`, `buoyancy`, `spawn`). A composite that needs a still-unbuilt atom (e.g. `warp`,
+ * §20.6) waits until it lands.
+ */
+/**
+ * The preset table (§20.9 composite map). Tunable starting points — refine when each
+ * is actually demoed, since these never touch the live site until opted into.
+ */
+export const PRESETS = {
+    // §20.9 designed composite — well + frame-drag + horizon + grazing-path bending.
+    blackhole: [
+        { body: 'attract', strength: 1.4, range: 340 }, // the well
+        { body: 'swirl', strength: 1.0, range: 300, spin: 1 }, // frame-drag → accretion disk
+        { body: 'sink', absorb: 42, max: 60 }, // event horizon: capture → supernova
+        { body: 'lens', strength: 0.5, range: 380 }, // gravitational lensing of passing matter
+    ],
+    // §20.9 — the time-reverse: an emission horizon that throws matter out.
+    whitehole: [
+        { body: 'repel', strength: 1.4, range: 340 },
+        { body: 'stream', strength: 0.6, range: 300, angle: 0 }, // optional directed eject
+    ],
+    // §20.10 — hydrostatic equilibrium: gravity's collapse balanced by thermal pressure.
+    // The same `gravity ⇄ thermal` fluctuation–dissipation balance that keeps the
+    // resting field calm, scaled up. GM is large because true 1/d² is weak at UI scale.
+    star: [
+        { body: 'gravity', strength: 300, range: 320 }, // inward GM well
+        { body: 'thermal', strength: 1.0, range: 220 }, // outward Brownian pressure
+    ],
+    // §20.9 — an accreting black hole that also jets along its poles.
+    // attract is softened (0.7) so the jet nozzle speed (2.4 + 2.6·S) at S=2.5 → 8.9 px/frame
+    // exceeds the escape velocity from the weakened well (~7 px/frame at d=50) — jets escape.
+    quasar: [
+        { body: 'attract', strength: 0.7, range: 340 }, // softened well — jets must escape it
+        { body: 'swirl', strength: 1.2, range: 300, spin: 1 }, // accretion disk
+        { body: 'sink', absorb: 40, max: 60 }, // horizon
+        { body: 'lens', strength: 0.5, range: 380 }, // lensing
+        { body: 'jet', strength: 2.5, range: 280, angle: -90 }, // north pole jet (fast enough to escape)
+        { body: 'jet', strength: 2.5, range: 280, angle: 90 }, // south pole jet
+    ],
+    // A spiral disk: a soft well, a swirl for the arms, viscosity to settle into a plane,
+    // and lensing at the rim. Attract is gentle (0.6) so swirl (1.3) dominates — spiral, not cluster.
+    galaxy: [
+        { body: 'attract', strength: 0.6, range: 400 }, // soft bulge — swirl must dominate
+        { body: 'swirl', strength: 1.3, range: 380, spin: 1 }, // spiral arms
+        { body: 'viscosity', strength: 0.4, range: 400 }, // settle into the disk
+        { body: 'lens', strength: 0.3, range: 420 }, // halo lensing
+    ],
+    // A warm, slow cloud: thermal agitation churning in a viscous medium, light matter
+    // drifting up.
+    nebula: [
+        { body: 'thermal', strength: 0.8, range: 320 }, // warm churn
+        { body: 'viscosity', strength: 0.5, range: 320 }, // viscous medium
+        { body: 'buoyancy', strength: 0.3, range: 0 }, // light wisps rise
+    ],
+    // A swirl with an updraft along its axis, calmed at the edges by viscosity.
+    tornado: [
+        { body: 'swirl', strength: 1.6, range: 300, spin: 1 }, // the funnel
+        { body: 'stream', strength: 0.8, range: 280, angle: -90 }, // updraft
+        { body: 'viscosity', strength: 0.3, range: 300 }, // ragged edge
+    ],
+    // §20.2 — a continuous class-[S] source jetting matter upward, the spray pulled back
+    // down by a gentle global gravity well: a literal water fountain.
+    fountain: [
+        // the explicit budget (life 90 = the source's historical lifespan, kept so the look is
+        // unchanged) satisfies the [S] source-budget guard — presets always declare theirs.
+        { body: 'spawn', strength: 1.2, angle: -90, life: 90 }, // jet up (−y); emits while on-screen
+        { body: 'gravity', strength: 60, range: 0 }, // the arc home — global, weak
+    ],
+};
+//# sourceMappingURL=presets.js.map

package/dist/config/presets.js.map

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

package/dist/config/tokens.d.ts

@@ -0,0 +1,3 @@
+/** A `selector { --f-*: …; --coherence: …; --ease: …; }` block (§25.2). */
+export declare function cssTokens(selector?: string): string;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/config/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/config/tokens.ts"],"names":[],"mappings":"AAQA,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,QAAQ,SAAU,GAAG,MAAM,CAMpD"}

package/dist/config/tokens.js

@@ -0,0 +1,16 @@
+/**
+ * Design tokens (§25.2) — the force palette + coherence + ease as CSS custom
+ * properties, derived from the canonical catalog (the single source of truth).
+ * Consumers can inject `cssTokens()` into a <style> so CSS can reference
+ * `var(--f-attract)`, `var(--coherence)`, `var(--ease)`.
+ */
+import { FORCES } from "./forces.config.js";
+/** A `selector { --f-*: …; --coherence: …; --ease: …; }` block (§25.2). */
+export function cssTokens(selector = ':root') {
+    const lines = FORCES.map((f) => `  --f-${f.id}: ${f.color};`);
+    lines.push('  --f-condition: var(--f-jet);');
+    lines.push('  --coherence: #ffce6b;');
+    lines.push('  --ease: cubic-bezier(0.16, 1, 0.3, 1);');
+    return `${selector} {\n${lines.join('\n')}\n}`;
+}
+//# sourceMappingURL=tokens.js.map

package/dist/config/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/config/tokens.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C,2EAA2E;AAC3E,MAAM,UAAU,SAAS,CAAC,QAAQ,GAAG,OAAO;IAC1C,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;IAC9D,KAAK,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;IAC7C,KAAK,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;IACtC,KAAK,CAAC,IAAI,CAAC,0CAA0C,CAAC,CAAC;IACvD,OAAO,GAAG,QAAQ,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;AACjD,CAAC"}

package/dist/conformance/expectations.d.ts

@@ -0,0 +1,40 @@
+import type { Expectation } from './types.ts';
+/** Δv on the test particle points toward the body. */
+export declare function movesToward(): Expectation;
+/** Δv on the test particle points away from the body. */
+export declare function movesAway(): Expectation;
+/** Over the whole run, the test particle ends farther from the body than it began — it rode
+ *  an outgoing wavefront out. Trajectory-based (a wave needs frames to form), for class-[C]
+ *  forces whose effect can't be read from a single frame-0 apply on an empty grid. */
+export declare function endsFartherOut(minGain?: number): Expectation;
+/** The exact frame-0 Δv matches the spec formula. */
+export declare function exactDelta(dvx: number, dvy: number, tol?: number): Expectation;
+/** Speed is preserved by the force (rotation only): |v+Δv| ≈ |v|. */
+export declare function speedPreserved(tol?: number): Expectation;
+/** The force bleeds speed without redirecting (drag): final speed < initial, same heading. */
+export declare function speedReduced(): Expectation;
+/** The force is perpendicular to velocity (does no work): Δv·v ≈ 0, Δv ≠ 0. */
+export declare function perpendicularToVelocity(tol?: number): Expectation;
+/** Total frame-0 momentum change across the particle set is ≈ 0 (e.g. an elastic collision). */
+export declare function momentumConserved(tol?: number): Expectation;
+/** Over the run, two particles end farther apart than they began (they repel/separate). */
+export declare function separates(i?: number, j?: number): Expectation;
+/** Over the run, the test particle ends closer to the body than it began. */
+export declare function approachesBody(): Expectation;
+/** Over the run, the test particle ends farther from the body than it began. */
+export declare function recedesFromBody(): Expectation;
+/** The test particle gains heat over the run. */
+export declare function heats(): Expectation;
+/** Beyond ~1.6× range the force does nothing (the integrator's cull / each force's cutoff). */
+export declare function noEffectBeyondRange(): Expectation;
+/** A field-buffer force deposits a mark and steers along the grid gradient (§20.1 [C]). */
+export declare function followsGradient(gx: number, gy: number): Expectation;
+/** A modifier gates its siblings outside a heading cone and lets them act inside it. */
+export declare function gatesOutsideCone(insideAngle: number, outsideAngle: number): Expectation;
+/** The force does nothing to neutral (charge-free) matter. */
+export declare function unaffectedWhenNeutral(): Expectation;
+/** The particle adopts and carries the body's tint on overlap (conserved color). */
+export declare function adoptsTint(): Expectation;
+/** A modifier scales sibling strength as 1 + sin(ω·t) over time. */
+export declare function modulatesStrength(): Expectation;
+//# sourceMappingURL=expectations.d.ts.map

package/dist/conformance/expectations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expectations.d.ts","sourceRoot":"","sources":["../../src/conformance/expectations.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAqC,MAAM,YAAY,CAAC;AAkBjF,sDAAsD;AACtD,wBAAgB,WAAW,IAAI,WAAW,CAWzC;AAED,yDAAyD;AACzD,wBAAgB,SAAS,IAAI,WAAW,CAWvC;AAED;;sFAEsF;AACtF,wBAAgB,cAAc,CAAC,OAAO,SAAO,GAAG,WAAW,CAa1D;AAED,qDAAqD;AACrD,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,SAAO,GAAG,WAAW,CAU5E;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,GAAG,SAAO,GAAG,WAAW,CAetD;AAED,8FAA8F;AAC9F,wBAAgB,YAAY,IAAI,WAAW,CAY1C;AAED,+EAA+E;AAC/E,wBAAgB,uBAAuB,CAAC,GAAG,SAAO,GAAG,WAAW,CAY/D;AAED,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,GAAG,SAAO,GAAG,WAAW,CAczD;AAQD,2FAA2F;AAC3F,wBAAgB,SAAS,CAAC,CAAC,SAAI,EAAE,CAAC,SAAI,GAAG,WAAW,CAUnD;AAOD,6EAA6E;AAC7E,wBAAgB,cAAc,IAAI,WAAW,CAU5C;AAED,gFAAgF;AAChF,wBAAgB,eAAe,IAAI,WAAW,CAU7C;AAED,iDAAiD;AACjD,wBAAgB,KAAK,IAAI,WAAW,CASnC;AAyCD,+FAA+F;AAC/F,wBAAgB,mBAAmB,IAAI,WAAW,CAgBjD;AAED,2FAA2F;AAC3F,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,WAAW,CA+BnE;AAED,wFAAwF;AACxF,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,WAAW,CAiBvF;AAED,8DAA8D;AAC9D,wBAAgB,qBAAqB,IAAI,WAAW,CAiBnD;AAED,oFAAoF;AACpF,wBAAgB,UAAU,IAAI,WAAW,CAaxC;AAED,oEAAoE;AACpE,wBAAgB,iBAAiB,IAAI,WAAW,CAoB/C"}

package/dist/conformance/expectations.js

@@ -0,0 +1,347 @@
+import { allForces } from "./run.js";
+const f3 = (n) => (Math.abs(n) < 1e-9 ? '0' : n.toFixed(3));
+const ok = (pass, measured, expected) => ({
+    pass,
+    measured,
+    expected,
+});
+function toBodyUnit(r) {
+    const p = r.scenario.particles[0];
+    const dx = r.body.cx - p.x;
+    const dy = r.body.cy - p.y;
+    const d = Math.hypot(dx, dy) || 1;
+    return { ux: dx / d, uy: dy / d };
+}
+/** Δv on the test particle points toward the body. */
+export function movesToward() {
+    return {
+        label: 'pulled toward the body',
+        kind: 'invariant',
+        check(r) {
+            const { ux, uy } = toBodyUnit(r);
+            const { dvx, dvy } = r.applyDelta[0];
+            const along = dvx * ux + dvy * uy;
+            return ok(along > 1e-6, `Δv·û = ${f3(along)}`, '> 0 (inward)');
+        },
+    };
+}
+/** Δv on the test particle points away from the body. */
+export function movesAway() {
+    return {
+        label: 'pushed away from the body',
+        kind: 'invariant',
+        check(r) {
+            const { ux, uy } = toBodyUnit(r);
+            const { dvx, dvy } = r.applyDelta[0];
+            const along = dvx * ux + dvy * uy;
+            return ok(along < -1e-6, `Δv·û = ${f3(along)}`, '< 0 (outward)');
+        },
+    };
+}
+/** Over the whole run, the test particle ends farther from the body than it began — it rode
+ *  an outgoing wavefront out. Trajectory-based (a wave needs frames to form), for class-[C]
+ *  forces whose effect can't be read from a single frame-0 apply on an empty grid. */
+export function endsFartherOut(minGain = 1.05) {
+    return {
+        label: 'rides the wavefront outward',
+        kind: 'invariant',
+        check(r) {
+            const b = r.body;
+            const first = r.trajectory[0][0];
+            const last = r.trajectory[r.trajectory.length - 1][0];
+            const r0 = Math.hypot(first.x - b.cx, first.y - b.cy) || 1;
+            const rN = Math.hypot(last.x - b.cx, last.y - b.cy);
+            return ok(rN > r0 * minGain, `r ${f3(r0)}→${f3(rN)}`, `> ${minGain}× (outward)`);
+        },
+    };
+}
+/** The exact frame-0 Δv matches the spec formula. */
+export function exactDelta(dvx, dvy, tol = 2e-3) {
+    return {
+        label: `Δv = (${f3(dvx)}, ${f3(dvy)})`,
+        kind: 'exact',
+        check(r) {
+            const a = r.applyDelta[0];
+            const pass = Math.abs(a.dvx - dvx) < tol && Math.abs(a.dvy - dvy) < tol;
+            return ok(pass, `(${f3(a.dvx)}, ${f3(a.dvy)})`, `(${f3(dvx)}, ${f3(dvy)}) ±${tol}`);
+        },
+    };
+}
+/** Speed is preserved by the force (rotation only): |v+Δv| ≈ |v|. */
+export function speedPreserved(tol = 0.02) {
+    return {
+        label: 'speed preserved (no work done)',
+        kind: 'invariant',
+        check(r) {
+            const p = r.scenario.particles[0];
+            const vx = p.vx ?? 0;
+            const vy = p.vy ?? 0;
+            const before = Math.hypot(vx, vy) || 1;
+            const a = r.applyDelta[0];
+            const after = Math.hypot(vx + a.dvx, vy + a.dvy);
+            const rel = Math.abs(after - before) / before;
+            return ok(rel < tol, `|v| ${f3(before)} → ${f3(after)}`, `±${(tol * 100).toFixed(0)}%`);
+        },
+    };
+}
+/** The force bleeds speed without redirecting (drag): final speed < initial, same heading. */
+export function speedReduced() {
+    return {
+        label: 'speed bled off',
+        kind: 'invariant',
+        check(r) {
+            const p = r.scenario.particles[0];
+            const before = Math.hypot(p.vx ?? 0, p.vy ?? 0) || 1;
+            const a = r.applyDelta[0];
+            const after = Math.hypot((p.vx ?? 0) + a.dvx, (p.vy ?? 0) + a.dvy);
+            return ok(after < before - 1e-6, `|v| ${f3(before)} → ${f3(after)}`, '< initial');
+        },
+    };
+}
+/** The force is perpendicular to velocity (does no work): Δv·v ≈ 0, Δv ≠ 0. */
+export function perpendicularToVelocity(tol = 1e-3) {
+    return {
+        label: 'force ⟂ velocity (no work)',
+        kind: 'invariant',
+        check(r) {
+            const p = r.scenario.particles[0];
+            const a = r.applyDelta[0];
+            const dot = (p.vx ?? 0) * a.dvx + (p.vy ?? 0) * a.dvy;
+            const mag = Math.hypot(a.dvx, a.dvy);
+            return ok(mag > 1e-6 && Math.abs(dot) < tol, `Δv·v = ${f3(dot)}, |Δv| = ${f3(mag)}`, '≈ 0, |Δv| > 0');
+        },
+    };
+}
+/** Total frame-0 momentum change across the particle set is ≈ 0 (e.g. an elastic collision). */
+export function momentumConserved(tol = 1e-6) {
+    return {
+        label: 'momentum conserved across the pair',
+        kind: 'invariant',
+        check(r) {
+            let sx = 0;
+            let sy = 0;
+            for (const a of r.applyDelta) {
+                sx += a.dvx;
+                sy += a.dvy;
+            }
+            return ok(Math.hypot(sx, sy) < tol, `Σ Δp = ${f3(Math.hypot(sx, sy))}`, '≈ 0');
+        },
+    };
+}
+const distAt = (r, frame, i, j) => {
+    const a = r.trajectory[frame][i];
+    const b = r.trajectory[frame][j];
+    return Math.hypot(a.x - b.x, a.y - b.y);
+};
+/** Over the run, two particles end farther apart than they began (they repel/separate). */
+export function separates(i = 0, j = 1) {
+    return {
+        label: 'the two particles separate',
+        kind: 'invariant',
+        check(r) {
+            const start = distAt(r, 0, i, j);
+            const end = distAt(r, r.trajectory.length - 1, i, j);
+            return ok(end > start + 1e-6, `gap ${f3(start)} → ${f3(end)}`, 'end > start');
+        },
+    };
+}
+const distToBody = (r, frame, i = 0) => {
+    const p = r.trajectory[frame][i];
+    return Math.hypot(p.x - r.body.cx, p.y - r.body.cy);
+};
+/** Over the run, the test particle ends closer to the body than it began. */
+export function approachesBody() {
+    return {
+        label: 'ends closer to the body',
+        kind: 'invariant',
+        check(r) {
+            const start = distToBody(r, 0);
+            const end = distToBody(r, r.trajectory.length - 1);
+            return ok(end < start - 1e-6, `dist ${f3(start)} → ${f3(end)}`, 'end < start');
+        },
+    };
+}
+/** Over the run, the test particle ends farther from the body than it began. */
+export function recedesFromBody() {
+    return {
+        label: 'ends farther from the body',
+        kind: 'invariant',
+        check(r) {
+            const start = distToBody(r, 0);
+            const end = distToBody(r, r.trajectory.length - 1);
+            return ok(end > start + 1e-6, `dist ${f3(start)} → ${f3(end)}`, 'end > start');
+        },
+    };
+}
+/** The test particle gains heat over the run. */
+export function heats() {
+    return {
+        label: 'particle gains heat',
+        kind: 'invariant',
+        check(r) {
+            const end = r.trajectory[r.trajectory.length - 1][0];
+            return ok(end.heat > 1e-4, `heat = ${f3(end.heat)}`, '> 0');
+        },
+    };
+}
+// ── checks that do a controlled direct apply via the registry ────────────────────
+function probeEnv(over = {}) {
+    return {
+        dx: 0,
+        dy: 0,
+        dist: 1,
+        form: { driftX: 0, wander: 0, orbit: 0, spread: 0, conv: 0 },
+        W: 1200,
+        H: 800,
+        t: 0,
+        frameN: 0,
+        dt: 1,
+        c: 12,
+        G: 1,
+        spark: () => { },
+        supernova: () => { },
+        spawn: () => { },
+        neighbors: () => [],
+        grid: () => ({ sample: () => 0, deposit: () => { }, gradient: () => ({ x: 0, y: 0 }) }),
+        ...over,
+    };
+}
+function cloneParticle(p) {
+    return {
+        x: p.x,
+        y: p.y,
+        vx: p.vx ?? 0,
+        vy: p.vy ?? 0,
+        m: 1,
+        heat: p.heat ?? 0,
+        size: p.size ?? 1,
+        cap: null,
+        ...(p.charge != null ? { charge: p.charge } : {}),
+        ...(p.color != null ? { color: p.color } : {}),
+    };
+}
+/** Beyond ~1.6× range the force does nothing (the integrator's cull / each force's cutoff). */
+export function noEffectBeyondRange() {
+    return {
+        label: 'no effect beyond range',
+        kind: 'invariant',
+        check(r) {
+            const force = allForces()[r.scenario.force];
+            const range = r.body.range || 300;
+            const p = cloneParticle({ x: r.body.cx + range * 2, y: r.body.cy });
+            const env = probeEnv({ dx: r.body.cx - p.x, dy: r.body.cy - p.y, dist: range * 2 });
+            const vx0 = p.vx;
+            const vy0 = p.vy;
+            force.apply(r.body, p, env);
+            const mag = Math.hypot(p.vx - vx0, p.vy - vy0);
+            return ok(mag < 1e-9, `|Δv| = ${f3(mag)} at 2× range`, '≈ 0');
+        },
+    };
+}
+/** A field-buffer force deposits a mark and steers along the grid gradient (§20.1 [C]). */
+export function followsGradient(gx, gy) {
+    return {
+        label: 'deposits + follows the grid gradient',
+        kind: 'invariant',
+        check(r) {
+            const force = allForces()[r.scenario.force];
+            const deposits = [];
+            const grid = {
+                sample: () => 0.5,
+                deposit: (x, y, a) => deposits.push([x, y, a]),
+                gradient: () => ({ x: gx, y: gy }),
+            };
+            const sp = r.scenario.particles[0];
+            const p = cloneParticle(sp);
+            const env = probeEnv({
+                dx: r.body.cx - p.x,
+                dy: r.body.cy - p.y,
+                dist: Math.hypot(r.body.cx - p.x, r.body.cy - p.y) || 1,
+                grid: () => grid,
+            });
+            const vx0 = p.vx;
+            force.apply(r.body, p, env);
+            const along = (p.vx - vx0) * gx + (p.vy - (sp.vy ?? 0)) * gy;
+            void vx0;
+            return ok(deposits.length > 0 && along > 0, `deposits ${deposits.length}, Δv·∇ = ${f3(along)}`, 'deposits > 0, follows up-gradient');
+        },
+    };
+}
+/** A modifier gates its siblings outside a heading cone and lets them act inside it. */
+export function gatesOutsideCone(insideAngle, outsideAngle) {
+    return {
+        label: 'gates outside the cone, acts inside',
+        kind: 'invariant',
+        check(r) {
+            const force = allForces()[r.scenario.force];
+            if (!force.modify)
+                return ok(false, 'no modify()', 'a modifier force');
+            const at = (ang) => {
+                const p = cloneParticle({ x: r.body.cx + Math.cos(ang) * 100, y: r.body.cy + Math.sin(ang) * 100 });
+                const env = probeEnv({ dx: r.body.cx - p.x, dy: r.body.cy - p.y, dist: 100 });
+                return force.modify(r.body, p, env).gate === true;
+            };
+            const outGated = at(outsideAngle);
+            const inGated = at(insideAngle);
+            return ok(outGated && !inGated, `out=${outGated} in=${inGated}`, 'out=true, in=false');
+        },
+    };
+}
+/** The force does nothing to neutral (charge-free) matter. */
+export function unaffectedWhenNeutral() {
+    return {
+        label: 'neutral matter is unaffected',
+        kind: 'invariant',
+        check(r) {
+            const force = allForces()[r.scenario.force];
+            const p = cloneParticle(r.scenario.particles[0]);
+            delete p.charge; // truly neutral
+            const d = Math.hypot(r.body.cx - p.x, r.body.cy - p.y) || 1;
+            const env = probeEnv({ dx: r.body.cx - p.x, dy: r.body.cy - p.y, dist: d });
+            const vx0 = p.vx;
+            const vy0 = p.vy;
+            force.apply(r.body, p, env);
+            const mag = Math.hypot(p.vx - vx0, p.vy - vy0);
+            return ok(mag < 1e-9, `|Δv| = ${f3(mag)} (q = 0)`, '≈ 0');
+        },
+    };
+}
+/** The particle adopts and carries the body's tint on overlap (conserved color). */
+export function adoptsTint() {
+    return {
+        label: 'adopts and carries the tint',
+        kind: 'invariant',
+        check(r) {
+            const force = allForces()[r.scenario.force];
+            const p = cloneParticle(r.scenario.particles[0]);
+            const d = Math.hypot(r.body.cx - p.x, r.body.cy - p.y) || 1;
+            const env = probeEnv({ dx: r.body.cx - p.x, dy: r.body.cy - p.y, dist: d });
+            force.apply(r.body, p, env);
+            return ok(!!p.color, `color = ${p.color ?? 'none'}`, 'set to the body tint');
+        },
+    };
+}
+/** A modifier scales sibling strength as 1 + sin(ω·t) over time. */
+export function modulatesStrength() {
+    return {
+        label: 'strength oscillates as 1 + sin(ωt)',
+        kind: 'invariant',
+        check(r) {
+            const force = allForces()[r.scenario.force];
+            if (!force.modify)
+                return ok(false, 'no modify()', 'a modifier force');
+            const p = cloneParticle(r.scenario.particles[0]);
+            let min = Infinity;
+            let max = -Infinity;
+            for (let i = 0; i < 64; i++) {
+                const env = probeEnv({ t: i / 8, dx: 1, dy: 0, dist: 1 });
+                const s = force.modify(r.body, p, env).strength ?? 1;
+                min = Math.min(min, s);
+                max = Math.max(max, s);
+            }
+            // a clean sinusoid swings roughly [0, 2] (around 1)
+            return ok(min < 0.2 && max > 1.8, `range [${f3(min)}, ${f3(max)}]`, '≈ [0, 2]');
+        },
+    };
+}
+//# sourceMappingURL=expectations.js.map