@fundamental-engine/core 0.4.0

package/dist/diagnostics/modes.js

@@ -0,0 +1,181 @@
+import { FRICTION } from "../core/integrator.js";
+import { forceVectorAt } from "./probes.js";
+function arrow(ctx, x, y, dx, dy, head = 4) {
+    const len = Math.hypot(dx, dy);
+    if (len < 0.001)
+        return;
+    ctx.beginPath();
+    ctx.moveTo(x, y);
+    ctx.lineTo(x + dx, y + dy);
+    const a = Math.atan2(dy, dx);
+    ctx.lineTo(x + dx - head * Math.cos(a - 0.4), y + dy - head * Math.sin(a - 0.4));
+    ctx.moveTo(x + dx, y + dy);
+    ctx.lineTo(x + dx - head * Math.cos(a + 0.4), y + dy - head * Math.sin(a + 0.4));
+    ctx.stroke();
+}
+/**
+ * Resolve relationship agents to drawable edges via a position lookup. Agents whose endpoints have
+ * no position are dropped (you can only draw what you can place). Pure.
+ */
+export function topologyEdges(agents, posOf) {
+    const out = [];
+    for (const a of agents) {
+        const from = posOf(a.from);
+        const to = posOf(a.to);
+        if (!from || !to)
+            continue;
+        out.push({ from, to, type: a.type, strength: a.strength, memory: a.memory, active: a.active });
+    }
+    return out;
+}
+/** Draw the coupling graph: thicker = stronger, brighter = more memory, accent = active this tick. */
+export function drawTopology(ctx, agents, posOf, opts = {}) {
+    const color = opts.color ?? '77,163,255';
+    const activeColor = opts.activeColor ?? '45,212,191';
+    const maxWidth = opts.maxWidth ?? 4;
+    ctx.save();
+    for (const e of topologyEdges(agents, posOf)) {
+        const alpha = 0.18 + 0.62 * e.memory;
+        ctx.strokeStyle = `rgba(${e.active ? activeColor : color},${alpha.toFixed(3)})`;
+        ctx.lineWidth = 0.5 + maxWidth * e.strength;
+        ctx.beginPath();
+        ctx.moveTo(e.from.x, e.from.y);
+        ctx.lineTo(e.to.x, e.to.y);
+        ctx.stroke();
+    }
+    ctx.restore();
+}
+const fmt = (v) => (typeof v === 'number' ? (Number.isInteger(v) ? String(v) : v.toFixed(3)) : v);
+/** Flatten a snapshot to ordered label/value rows (counts first, then metrics). Pure. */
+export function inspectorRows(snap) {
+    const rows = [];
+    const add = (label, v) => {
+        if (v !== undefined)
+            rows.push({ label, value: fmt(v) });
+    };
+    add('bodies', snap.bodies);
+    add('particles', snap.particles);
+    add('agents', snap.agents);
+    add('relationships', snap.relationships);
+    add('contracts', snap.contracts);
+    if (snap.metrics)
+        for (const k of Object.keys(snap.metrics))
+            rows.push({ label: k, value: fmt(snap.metrics[k]) });
+    return rows;
+}
+/** Draw the inspector as a compact monospace panel (top-left by default). */
+export function drawInspector(ctx, snap, opts = {}) {
+    const rows = inspectorRows(snap);
+    const x = opts.x ?? 12;
+    const y = opts.y ?? 12;
+    const w = opts.width ?? 180;
+    const lh = 16;
+    const h = rows.length * lh + 10;
+    ctx.save();
+    ctx.font = '11px ui-monospace, monospace';
+    ctx.fillStyle = 'rgba(11,11,16,0.78)';
+    ctx.fillRect(x, y, w, h);
+    rows.forEach((r, i) => {
+        const yy = y + 8 + i * lh + 8;
+        ctx.fillStyle = 'rgba(255,255,255,0.45)';
+        ctx.fillText(r.label, x + 8, yy);
+        ctx.fillStyle = '#4da3ff';
+        ctx.textAlign = 'right';
+        ctx.fillText(r.value, x + w - 8, yy);
+        ctx.textAlign = 'left';
+    });
+    ctx.restore();
+}
+/** Rank causal contributions by magnitude (desc) with each one's fraction of the total. Pure. */
+export function causalityBars(contribs) {
+    const mags = contribs.map((c) => ({ token: c.token, magnitude: Math.hypot(c.dvx, c.dvy) }));
+    const total = mags.reduce((s, m) => s + m.magnitude, 0) || 1;
+    return mags
+        .map((m) => ({ token: m.token, magnitude: m.magnitude, fraction: m.magnitude / total }))
+        .sort((a, b) => b.magnitude - a.magnitude);
+}
+/** Draw causality at a point: a vector per contributing force from the origin, plus a ranked bar list. */
+export function drawCausality(ctx, contribs, origin, opts = {}) {
+    const scale = opts.scale ?? 8;
+    ctx.save();
+    // vectors from the probe origin
+    ctx.strokeStyle = 'rgba(240,136,62,0.85)';
+    ctx.lineWidth = 1.5;
+    for (const c of contribs)
+        arrow(ctx, origin.x, origin.y, c.dvx * scale, c.dvy * scale, 5);
+    // ranked bars
+    const bars = causalityBars(contribs);
+    const bx = opts.x ?? origin.x + 14;
+    const by = opts.y ?? origin.y + 14;
+    const bw = opts.width ?? 120;
+    ctx.font = '10px ui-monospace, monospace';
+    bars.forEach((b, i) => {
+        const yy = by + i * 14;
+        ctx.fillStyle = 'rgba(255,255,255,0.1)';
+        ctx.fillRect(bx, yy, bw, 8);
+        ctx.fillStyle = '#f0883e';
+        ctx.fillRect(bx, yy, bw * b.fraction, 8);
+        ctx.fillStyle = 'rgba(255,255,255,0.7)';
+        ctx.fillText(b.token, bx + bw + 6, yy + 8);
+    });
+    ctx.restore();
+}
+/**
+ * A deterministic forward "ghost" trajectory: integrate one probe under the class-A body forces,
+ * summing each (force, body) Δv per step and damping by friction — the same shape the real
+ * integrator uses, kept dependency-light. Pure and repeatable: same inputs → same path. This is the
+ * *prediction* overlay's data (an expected future path), not the live sim.
+ */
+export function ghostTrajectory(forces, tokens, bodies, start, opts = {}) {
+    const steps = opts.steps ?? 60;
+    const friction = opts.friction ?? FRICTION;
+    const scale = opts.forceScale ?? 1;
+    const charge = opts.charge ?? 0;
+    let x = start.x;
+    let y = start.y;
+    let vx = start.vx;
+    let vy = start.vy;
+    const path = [{ x, y }];
+    for (let i = 0; i < steps; i++) {
+        let ax = 0;
+        let ay = 0;
+        const probe = { vx, vy, charge, m: 1, heat: 0 };
+        for (const t of tokens) {
+            const f = forces[t];
+            if (!f)
+                continue;
+            for (const b of bodies) {
+                const v = forceVectorAt(f, b, x, y, probe);
+                ax += v.x;
+                ay += v.y;
+            }
+        }
+        vx = (vx + ax * scale) * friction;
+        vy = (vy + ay * scale) * friction;
+        x += vx;
+        y += vy;
+        path.push({ x, y });
+    }
+    return path;
+}
+/** Draw a ghost trajectory as a dashed path that fades toward the predicted future. */
+export function drawPrediction(ctx, points, opts = {}) {
+    if (points.length < 2)
+        return;
+    const color = opts.color ?? '255,255,255';
+    ctx.save();
+    ctx.setLineDash([3, 4]);
+    ctx.lineWidth = 1.5;
+    for (let i = 1; i < points.length; i++) {
+        const a = points[i - 1];
+        const b = points[i];
+        const alpha = 0.6 * (1 - i / points.length);
+        ctx.strokeStyle = `rgba(${color},${alpha.toFixed(3)})`;
+        ctx.beginPath();
+        ctx.moveTo(a.x, a.y);
+        ctx.lineTo(b.x, b.y);
+        ctx.stroke();
+    }
+    ctx.restore();
+}
+//# sourceMappingURL=modes.js.map

package/dist/diagnostics/modes.js.map

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

package/dist/diagnostics/potential.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Potential & scalar-field diagnostics (visualization-methods-taxonomy §6). The scalar potential a
+ * body radiates (`Φ = -s / sqrt(d² + ε²)`), and a generic grid sampler that turns any scalar field
+ * into a value grid for contour / potential / heatmap rendering. Pure; reads no live state.
+ */
+import type { Body } from '../core/types.ts';
+/**
+ * The scalar potential of a body at a world point. `gravity` is an attractive well (Φ < 0, deeper
+ * toward the mass); `charge` is signed by polarity. `s` defaults to the body's `M`.
+ */
+export declare function potentialAt(b: Body, x: number, y: number, kind?: 'gravity' | 'charge'): number;
+/** The summed potential of many bodies at a point. */
+export declare function netPotentialAt(bodies: readonly Body[], x: number, y: number, kind?: 'gravity' | 'charge'): number;
+export interface ScalarGridData {
+    width: number;
+    height: number;
+    /** cell size in px. */
+    resolution: number;
+    cols: number;
+    rows: number;
+    values: Float32Array;
+    min: number;
+    max: number;
+}
+/**
+ * Sample any scalar field `f(x, y)` onto a grid — the data a contour/potential layer renders from
+ * (e.g. marching squares over `values`). Pure.
+ */
+export declare function sampleScalarGrid(f: (x: number, y: number) => number, width: number, height: number, resolution?: number): ScalarGridData;
+//# sourceMappingURL=potential.d.ts.map

package/dist/diagnostics/potential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"potential.d.ts","sourceRoot":"","sources":["../../src/diagnostics/potential.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAI7C;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,GAAE,SAAS,GAAG,QAAoB,GAAG,MAAM,CAOzG;AAED,sDAAsD;AACtD,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,IAAI,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,GAAE,SAAS,GAAG,QAAoB,GAAG,MAAM,CAI5H;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,uBAAuB;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,EACnC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,UAAU,SAAK,GACd,cAAc,CAehB"}

package/dist/diagnostics/potential.js

@@ -0,0 +1,43 @@
+const EPS = 6; // softening, matches the engine's Plummer-style core
+/**
+ * The scalar potential of a body at a world point. `gravity` is an attractive well (Φ < 0, deeper
+ * toward the mass); `charge` is signed by polarity. `s` defaults to the body's `M`.
+ */
+export function potentialAt(b, x, y, kind = 'gravity') {
+    const dx = x - b.cx;
+    const dy = y - b.cy;
+    const d = Math.sqrt(dx * dx + dy * dy + EPS * EPS);
+    const s = b.M || b.strength || 1;
+    const sign = kind === 'charge' ? (b.spin < 0 ? -1 : 1) : -1; // gravity always attractive
+    return (sign * s) / d;
+}
+/** The summed potential of many bodies at a point. */
+export function netPotentialAt(bodies, x, y, kind = 'gravity') {
+    let phi = 0;
+    for (const b of bodies)
+        phi += potentialAt(b, x, y, kind);
+    return phi;
+}
+/**
+ * Sample any scalar field `f(x, y)` onto a grid — the data a contour/potential layer renders from
+ * (e.g. marching squares over `values`). Pure.
+ */
+export function sampleScalarGrid(f, width, height, resolution = 16) {
+    const cols = Math.max(1, Math.ceil(width / resolution));
+    const rows = Math.max(1, Math.ceil(height / resolution));
+    const values = new Float32Array(cols * rows);
+    let min = Infinity;
+    let max = -Infinity;
+    for (let r = 0; r < rows; r++) {
+        for (let c = 0; c < cols; c++) {
+            const v = f(c * resolution, r * resolution);
+            values[r * cols + c] = v;
+            if (v < min)
+                min = v;
+            if (v > max)
+                max = v;
+        }
+    }
+    return { width, height, resolution, cols, rows, values, min: min === Infinity ? 0 : min, max: max === -Infinity ? 0 : max };
+}
+//# sourceMappingURL=potential.js.map

package/dist/diagnostics/potential.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"potential.js","sourceRoot":"","sources":["../../src/diagnostics/potential.ts"],"names":[],"mappings":"AAOA,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,qDAAqD;AAEpE;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,CAAO,EAAE,CAAS,EAAE,CAAS,EAAE,OAA6B,SAAS;IAC/F,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;IACpB,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;IACpB,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC;IACnD,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC;IACjC,MAAM,IAAI,GAAG,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,4BAA4B;IACzF,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;AACxB,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,cAAc,CAAC,MAAuB,EAAE,CAAS,EAAE,CAAS,EAAE,OAA6B,SAAS;IAClH,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,MAAM,CAAC,IAAI,MAAM;QAAE,GAAG,IAAI,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;IAC1D,OAAO,GAAG,CAAC;AACb,CAAC;AAcD;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,CAAmC,EACnC,KAAa,EACb,MAAc,EACd,UAAU,GAAG,EAAE;IAEf,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC;IACzD,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IAC7C,IAAI,GAAG,GAAG,QAAQ,CAAC;IACnB,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC;IACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;YAC9B,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,UAAU,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC;YAC5C,MAAM,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;YACzB,IAAI,CAAC,GAAG,GAAG;gBAAE,GAAG,GAAG,CAAC,CAAC;YACrB,IAAI,CAAC,GAAG,GAAG;gBAAE,GAAG,GAAG,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;AAC9H,CAAC"}

package/dist/diagnostics/probes.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Probe diagnostics (visualization-methods-taxonomy §3/§4, §11). Probes are instruments fired into
+ * the field to read it: a force's *vector* at a point (Δv on a probe — `field magnitude != force
+ * magnitude`), and the per-token *causality* breakdown of why motion happened. Works for body→
+ * particle (class-A) forces; class-B/C/D forces need neighbours/grids the conformance runner wires.
+ */
+import type { Body, Force, ForceRegistry, Vec2 } from '../core/types.ts';
+/** An instrument particle. */
+export interface Probe {
+    vx: number;
+    vy: number;
+    charge: number;
+    m: number;
+    heat: number;
+}
+/** The standard probe set (viz-taxonomy §4). */
+export declare const PROBE_PRESETS: Readonly<Record<string, Probe>>;
+/**
+ * The force vector a class-A force exerts on a probe at (x, y): the Δv from a single `apply()`. A
+ * still or neutral probe correctly reads zero for velocity- or charge-dependent forces (magnetism,
+ * charge) — that's the point of probes.
+ */
+export declare function forceVectorAt(force: Force, b: Body, x: number, y: number, probe?: Probe): Vec2;
+export interface CausalContribution {
+    token: string;
+    dvx: number;
+    dvy: number;
+}
+/** Decompose the motion at (x, y) into per-token contributions — the causality overlay's data. */
+export declare function causalityAt(registry: ForceRegistry, tokens: readonly string[], b: Body, x: number, y: number, probe?: Probe): CausalContribution[];
+//# sourceMappingURL=probes.d.ts.map

package/dist/diagnostics/probes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"probes.d.ts","sourceRoot":"","sources":["../../src/diagnostics/probes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,IAAI,EAAiB,KAAK,EAAE,aAAa,EAAa,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAEnG,8BAA8B;AAC9B,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;CACd;AAED,gDAAgD;AAChD,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAQzD,CAAC;AAgBF;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,GAAE,KAA8B,GAAG,IAAI,CAkBtH;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,kGAAkG;AAClG,wBAAgB,WAAW,CACzB,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,CAAC,EAAE,IAAI,EACP,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,KAAK,GAAE,KAA8B,GACpC,kBAAkB,EAAE,CAStB"}

package/dist/diagnostics/probes.js

@@ -0,0 +1,61 @@
+/** The standard probe set (viz-taxonomy §4). */
+export const PROBE_PRESETS = {
+    neutral: { vx: 0, vy: 0, charge: 0, m: 1, heat: 0 },
+    positive: { vx: 1, vy: 0, charge: 1, m: 1, heat: 0 },
+    negative: { vx: 1, vy: 0, charge: -1, m: 1, heat: 0 },
+    still: { vx: 0, vy: 0, charge: 1, m: 1, heat: 0 },
+    fast: { vx: 6, vy: 0, charge: 1, m: 1, heat: 0 },
+    hot: { vx: 0, vy: 0, charge: 0, m: 1, heat: 1 },
+    massive: { vx: 0, vy: 0, charge: 0, m: 6, heat: 0 },
+};
+function probeEnv(b, x, y) {
+    const dx = b.cx - x;
+    const dy = b.cy - y;
+    return {
+        dx,
+        dy,
+        dist: Math.max(Math.hypot(dx, dy), 1),
+        form: {},
+        c: 12,
+        G: 1,
+        t: 0,
+    };
+}
+/**
+ * The force vector a class-A force exerts on a probe at (x, y): the Δv from a single `apply()`. A
+ * still or neutral probe correctly reads zero for velocity- or charge-dependent forces (magnetism,
+ * charge) — that's the point of probes.
+ */
+export function forceVectorAt(force, b, x, y, probe = PROBE_PRESETS.neutral) {
+    const p = {
+        x,
+        y,
+        vx: probe.vx,
+        vy: probe.vy,
+        charge: probe.charge,
+        m: probe.m,
+        heat: probe.heat,
+        size: 1,
+        cap: null,
+    };
+    try {
+        force.apply(b, p, probeEnv(b, x, y));
+    }
+    catch {
+        return { x: 0, y: 0 };
+    }
+    return { x: p.vx - probe.vx, y: p.vy - probe.vy };
+}
+/** Decompose the motion at (x, y) into per-token contributions — the causality overlay's data. */
+export function causalityAt(registry, tokens, b, x, y, probe = PROBE_PRESETS.neutral) {
+    const out = [];
+    for (const t of tokens) {
+        const f = registry[t];
+        if (!f)
+            continue;
+        const v = forceVectorAt(f, b, x, y, probe);
+        out.push({ token: t, dvx: v.x, dvy: v.y });
+    }
+    return out;
+}
+//# sourceMappingURL=probes.js.map

package/dist/diagnostics/probes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"probes.js","sourceRoot":"","sources":["../../src/diagnostics/probes.ts"],"names":[],"mappings":"AAiBA,gDAAgD;AAChD,MAAM,CAAC,MAAM,aAAa,GAAoC;IAC5D,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE;IACnD,QAAQ,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE;IACpD,QAAQ,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE;IACrD,KAAK,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE;IACjD,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE;IAChD,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE;IAC/C,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE;CACpD,CAAC;AAEF,SAAS,QAAQ,CAAC,CAAO,EAAE,CAAS,EAAE,CAAS;IAC7C,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACpB,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACpB,OAAO;QACL,EAAE;QACF,EAAE;QACF,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;QACrC,IAAI,EAAE,EAAe;QACrB,CAAC,EAAE,EAAE;QACL,CAAC,EAAE,CAAC;QACJ,CAAC,EAAE,CAAC;KACa,CAAC;AACtB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAY,EAAE,CAAO,EAAE,CAAS,EAAE,CAAS,EAAE,QAAe,aAAa,CAAC,OAAQ;IAC9G,MAAM,CAAC,GAAG;QACR,CAAC;QACD,CAAC;QACD,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,CAAC,EAAE,KAAK,CAAC,CAAC;QACV,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,IAAI,EAAE,CAAC;QACP,GAAG,EAAE,IAAI;KACa,CAAC;IACzB,IAAI,CAAC;QACH,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;IACxB,CAAC;IACD,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,EAAE,EAAE,CAAC;AACpD,CAAC;AAQD,kGAAkG;AAClG,MAAM,UAAU,WAAW,CACzB,QAAuB,EACvB,MAAyB,EACzB,CAAO,EACP,CAAS,EACT,CAAS,EACT,QAAe,aAAa,CAAC,OAAQ;IAErC,MAAM,GAAG,GAAyB,EAAE,CAAC;IACrC,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,CAAC,CAAC;YAAE,SAAS;QACjB,MAAM,CAAC,GAAG,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;QAC3C,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/diagnostics/render.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Diagnostic overlay rendering (visualization-methods-taxonomy §3, §6, §7, §11). Draws the pure
+ * diagnostic data (force vectors, contours, potential, energy) onto a Canvas 2D context. The
+ * marching-squares contour extraction is pure and testable; the `draw*` helpers are thin context
+ * calls. These reveal state — they read, never mutate physics.
+ */
+import type { Body, Particle, Force } from '../core/types.ts';
+import type { ScalarGridData } from './potential.ts';
+import { sampleScalarGrid } from './potential.ts';
+import { type Probe } from './probes.ts';
+import type { EnergyReport } from './energy.ts';
+export interface Segment {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+/** All isoline segments for a set of levels (evenly spaced if `levels` is a count). Pure. */
+export declare function contourSegments(grid: ScalarGridData, levels?: number[] | number): Segment[];
+type Ctx = CanvasRenderingContext2D;
+/** Draw contour isolines of a scalar grid. */
+export declare function drawContours(ctx: Ctx, grid: ScalarGridData, opts?: {
+    levels?: number;
+    color?: string;
+}): void;
+/** Draw a body's potential field as soft shaded wells (normalized grid → alpha). */
+export declare function drawPotential(ctx: Ctx, grid: ScalarGridData, opts?: {
+    color?: string;
+}): void;
+/** Draw a force's vector field by probing it on a grid (viz §3 — uses a probe, §4). */
+export declare function drawForceVectors(ctx: Ctx, force: Force, body: Body, W: number, H: number, opts?: {
+    spacing?: number;
+    probe?: Probe;
+    scale?: number;
+    color?: string;
+}): void;
+/** Draw per-particle velocity vectors. */
+export declare function drawVelocityVectors(ctx: Ctx, particles: readonly Particle[], opts?: {
+    scale?: number;
+    color?: string;
+}): void;
+/** Draw a compact kinetic/thermal/total energy bar. */
+export declare function drawEnergyBar(ctx: Ctx, report: EnergyReport, opts?: {
+    x?: number;
+    y?: number;
+    w?: number;
+}): void;
+export { sampleScalarGrid };
+//# sourceMappingURL=render.d.ts.map

package/dist/diagnostics/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/diagnostics/render.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAiB,KAAK,KAAK,EAAiB,MAAM,aAAa,CAAC;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;CACZ;AAgCD,6FAA6F;AAC7F,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,EAAE,MAAM,GAAE,MAAM,EAAE,GAAG,MAAU,GAAG,OAAO,EAAE,CAM9F;AAED,KAAK,GAAG,GAAG,wBAAwB,CAAC;AAepC,8CAA8C;AAC9C,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,IAAI,CAWjH;AAED,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,IAAI,CAWjG;AAED,uFAAuF;AACvF,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,IAAI,EACV,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7E,IAAI,CAaN;AAED,0CAA0C;AAC1C,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,QAAQ,EAAE,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,IAAI,CAOjI;AAED,uDAAuD;AACvD,wBAAgB,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,GAAE;IAAE,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,IAAI,CAqBrH;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/diagnostics/render.js

@@ -0,0 +1,132 @@
+import { sampleScalarGrid } from "./potential.js";
+import { forceVectorAt, PROBE_PRESETS } from "./probes.js";
+/**
+ * Marching-squares isolines for one level over a scalar grid → line segments in pixel space. Pure.
+ * (Saddle cells are split into two segments by edge order — good enough for diagnostic contours.)
+ */
+function levelSegments(grid, level) {
+    const { cols, rows, resolution: res, values } = grid;
+    const at = (c, r) => values[r * cols + c] ?? 0;
+    const segs = [];
+    for (let r = 0; r < rows - 1; r++) {
+        for (let c = 0; c < cols - 1; c++) {
+            const tl = at(c, r);
+            const tr = at(c + 1, r);
+            const bl = at(c, r + 1);
+            const br = at(c + 1, r + 1);
+            const pts = [];
+            const cross = (a, b) => (level - a) / (b - a);
+            if (tl < level !== tr < level)
+                pts.push({ x: (c + cross(tl, tr)) * res, y: r * res }); // top
+            if (tr < level !== br < level)
+                pts.push({ x: (c + 1) * res, y: (r + cross(tr, br)) * res }); // right
+            if (bl < level !== br < level)
+                pts.push({ x: (c + cross(bl, br)) * res, y: (r + 1) * res }); // bottom
+            if (tl < level !== bl < level)
+                pts.push({ x: c * res, y: (r + cross(tl, bl)) * res }); // left
+            if (pts.length === 2)
+                segs.push({ x1: pts[0].x, y1: pts[0].y, x2: pts[1].x, y2: pts[1].y });
+            else if (pts.length === 4) {
+                segs.push({ x1: pts[0].x, y1: pts[0].y, x2: pts[1].x, y2: pts[1].y });
+                segs.push({ x1: pts[2].x, y1: pts[2].y, x2: pts[3].x, y2: pts[3].y });
+            }
+        }
+    }
+    return segs;
+}
+/** All isoline segments for a set of levels (evenly spaced if `levels` is a count). Pure. */
+export function contourSegments(grid, levels = 8) {
+    const list = typeof levels === 'number'
+        ? Array.from({ length: levels }, (_, i) => grid.min + ((i + 1) / (levels + 1)) * (grid.max - grid.min))
+        : levels;
+    return list.flatMap((l) => levelSegments(grid, l));
+}
+function arrow(ctx, x, y, dx, dy, head = 4) {
+    const len = Math.hypot(dx, dy);
+    if (len < 0.001)
+        return;
+    ctx.beginPath();
+    ctx.moveTo(x, y);
+    ctx.lineTo(x + dx, y + dy);
+    const a = Math.atan2(dy, dx);
+    ctx.lineTo(x + dx - head * Math.cos(a - 0.4), y + dy - head * Math.sin(a - 0.4));
+    ctx.moveTo(x + dx, y + dy);
+    ctx.lineTo(x + dx - head * Math.cos(a + 0.4), y + dy - head * Math.sin(a + 0.4));
+    ctx.stroke();
+}
+/** Draw contour isolines of a scalar grid. */
+export function drawContours(ctx, grid, opts = {}) {
+    ctx.save();
+    ctx.strokeStyle = opts.color ?? 'rgba(77,163,255,0.5)';
+    ctx.lineWidth = 1;
+    for (const s of contourSegments(grid, opts.levels ?? 8)) {
+        ctx.beginPath();
+        ctx.moveTo(s.x1, s.y1);
+        ctx.lineTo(s.x2, s.y2);
+        ctx.stroke();
+    }
+    ctx.restore();
+}
+/** Draw a body's potential field as soft shaded wells (normalized grid → alpha). */
+export function drawPotential(ctx, grid, opts = {}) {
+    const span = grid.max - grid.min || 1;
+    ctx.save();
+    for (let r = 0; r < grid.rows; r++) {
+        for (let c = 0; c < grid.cols; c++) {
+            const n = ((grid.values[r * grid.cols + c] ?? 0) - grid.min) / span;
+            ctx.fillStyle = (opts.color ?? 'rgba(77,163,255,A)').replace('A', (n * 0.5).toFixed(3));
+            ctx.fillRect(c * grid.resolution, r * grid.resolution, grid.resolution, grid.resolution);
+        }
+    }
+    ctx.restore();
+}
+/** Draw a force's vector field by probing it on a grid (viz §3 — uses a probe, §4). */
+export function drawForceVectors(ctx, force, body, W, H, opts = {}) {
+    const spacing = opts.spacing ?? 36;
+    const scale = opts.scale ?? 6;
+    ctx.save();
+    ctx.strokeStyle = opts.color ?? 'rgba(45,212,191,0.7)';
+    ctx.lineWidth = 1;
+    for (let y = spacing / 2; y < H; y += spacing) {
+        for (let x = spacing / 2; x < W; x += spacing) {
+            const v = forceVectorAt(force, body, x, y, opts.probe ?? PROBE_PRESETS.neutral);
+            arrow(ctx, x, y, v.x * scale, v.y * scale);
+        }
+    }
+    ctx.restore();
+}
+/** Draw per-particle velocity vectors. */
+export function drawVelocityVectors(ctx, particles, opts = {}) {
+    const scale = opts.scale ?? 3;
+    ctx.save();
+    ctx.strokeStyle = opts.color ?? 'rgba(255,255,255,0.5)';
+    ctx.lineWidth = 1;
+    for (const p of particles)
+        arrow(ctx, p.x, p.y, p.vx * scale, p.vy * scale);
+    ctx.restore();
+}
+/** Draw a compact kinetic/thermal/total energy bar. */
+export function drawEnergyBar(ctx, report, opts = {}) {
+    const x = opts.x ?? 12;
+    const y = opts.y ?? 12;
+    const w = opts.w ?? 160;
+    const total = report.total || 1;
+    const rows = [
+        ['K', report.kinetic / total, '#4da3ff'],
+        ['T', report.thermal / total, '#f0883e'],
+    ];
+    ctx.save();
+    ctx.font = '11px ui-monospace, monospace';
+    rows.forEach(([label, frac, color], i) => {
+        const yy = y + i * 16;
+        ctx.fillStyle = 'rgba(255,255,255,0.4)';
+        ctx.fillText(label, x, yy + 9);
+        ctx.fillStyle = 'rgba(255,255,255,0.1)';
+        ctx.fillRect(x + 16, yy, w, 10);
+        ctx.fillStyle = color;
+        ctx.fillRect(x + 16, yy, w * Math.min(1, frac), 10);
+    });
+    ctx.restore();
+}
+export { sampleScalarGrid };
+//# sourceMappingURL=render.js.map

package/dist/diagnostics/render.js.map

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

package/dist/export.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Field export serializers (visualization-methods-taxonomy §15). Turn a field into a portable
+ * artifact: an SVG of vector segments (field lines, contours, relationship overlays), or a PNG data
+ * URL of the canvas. Both are DOM-global-free — `segmentsToSvg` is pure, and `canvasToPng` calls the
+ * passed canvas's own `toDataURL`. The download helpers (which need `document`) live in
+ * `@fundamental-engine/platform` (`downloadUrl` / `downloadText` / `downloadCanvasPng`).
+ */
+import type { Segment } from './diagnostics/render.ts';
+export interface SvgOptions {
+    stroke?: string;
+    strokeWidth?: number;
+    background?: string;
+}
+/** Serialize line segments to a standalone SVG document. Pure — no DOM. */
+export declare function segmentsToSvg(segments: readonly Segment[], width: number, height: number, opts?: SvgOptions): string;
+/** A PNG data URL of a canvas (the rasterized field) — the canvas's own `toDataURL`, no globals. */
+export declare function canvasToPng(canvas: HTMLCanvasElement): string;
+//# sourceMappingURL=export.d.ts.map

package/dist/export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../src/export.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAIvD,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe,GAAG,MAAM,CAWxH;AAED,oGAAoG;AACpG,wBAAgB,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAE7D"}

package/dist/export.js

@@ -0,0 +1,17 @@
+const round = (n) => Math.round(n * 100) / 100;
+/** Serialize line segments to a standalone SVG document. Pure — no DOM. */
+export function segmentsToSvg(segments, width, height, opts = {}) {
+    const bg = opts.background ? `<rect width="${width}" height="${height}" fill="${opts.background}"/>` : '';
+    const lines = segments
+        .map((s) => `<line x1="${round(s.x1)}" y1="${round(s.y1)}" x2="${round(s.x2)}" y2="${round(s.y2)}"/>`)
+        .join('');
+    return (`<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">` +
+        bg +
+        `<g stroke="${opts.stroke ?? '#4da3ff'}" stroke-width="${opts.strokeWidth ?? 1}" fill="none">${lines}</g>` +
+        `</svg>`);
+}
+/** A PNG data URL of a canvas (the rasterized field) — the canvas's own `toDataURL`, no globals. */
+export function canvasToPng(canvas) {
+    return canvas.toDataURL('image/png');
+}
+//# sourceMappingURL=export.js.map

package/dist/export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.js","sourceRoot":"","sources":["../src/export.ts"],"names":[],"mappings":"AASA,MAAM,KAAK,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;AAQ/D,2EAA2E;AAC3E,MAAM,UAAU,aAAa,CAAC,QAA4B,EAAE,KAAa,EAAE,MAAc,EAAE,OAAmB,EAAE;IAC9G,MAAM,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,gBAAgB,KAAK,aAAa,MAAM,WAAW,IAAI,CAAC,UAAU,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1G,MAAM,KAAK,GAAG,QAAQ;SACnB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC;SACrG,IAAI,CAAC,EAAE,CAAC,CAAC;IACZ,OAAO,CACL,kDAAkD,KAAK,aAAa,MAAM,kBAAkB,KAAK,IAAI,MAAM,IAAI;QAC/G,EAAE;QACF,cAAc,IAAI,CAAC,MAAM,IAAI,SAAS,mBAAmB,IAAI,CAAC,WAAW,IAAI,CAAC,iBAAiB,KAAK,MAAM;QAC1G,QAAQ,CACT,CAAC;AACJ,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,WAAW,CAAC,MAAyB;IACnD,OAAO,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;AACvC,CAAC"}