@fundamental-engine/core 0.8.0 → 0.9.1

package/dist/core/field.js

@@ -20,7 +20,7 @@ import { scanBodies, measureBodies, bodyFromElement } from "./scanner.js";
 import { ShadowRegistry, REGISTER_BODY, UNREGISTER_BODY, UPDATE_BODY, } from "./shadow.js";
 import { easeFormation } from "./formations.js";
 import { Heatmap } from "./heatmap.js";
-import { buildWaves, buildBound, waveYat, } from "./currents.js";
+import { buildWaves, buildBound, waveYat, waveRAt, } from "./currents.js";
 import { healWaves, tearBoundNear, tearBoundByForces, induceCharges } from "./reservoir.js";
 import { FORMATION_BY, PALETTE } from "../config/forces.config.js";
 import { resolvePalette } from "../config/palettes.js";
@@ -30,11 +30,13 @@ import { feedbackTarget, feedbackWeight } from "./feedback.js";
 import { defaultFeedbackSink } from "./feedback-sink.js";
 import { thermoMetrics } from "./thermo.js";
 import { attentionMuls } from "./attention.js";
+import { updateRelationship } from "../agents/relationship.js";
+import { Thresholder } from "../agents/event-agent.js";
 import { spillover } from "./causality.js";
 import { integrateOffset, anchorForce, elementMass, repelForce, densityPush } from "./agents.js";
 import { releaseCaptured, sinkLoad, captureEdge, dischargeDisengaged } from "./accretion.js";
 import { withinCapture, stepDock, dockTransform } from "./dock.js";
-import { parseEventBindings, triggerActive } from "./events.js";
+import { FieldEventCoalescer, parseEventBindings, triggerActive } from "./events.js";
 import { registerCoreForces } from "../forces/index.js";
 import { registerNaturalForces } from "../forces/natural.js";
 import { registerExtendedForces } from "../forces/extended.js";
@@ -87,12 +89,29 @@ export function createField(canvas, opts = {}) {
     // when unused: detection passes guard on `busHas(type)` so zero listeners cost nothing.
     const busListeners = new Map();
     const busHas = (type) => (busListeners.get(type)?.size ?? 0) > 0;
-    function busEmit(type, payload) {
+    function busDeliver(type, payload) {
         const set = busListeners.get(type);
         if (set)
             for (const cb of set)
                 cb(payload);
     }
+    // Per-frame coalescing (#684, shadow-dom §31): a force/condition can cross the same edge more than
+    // once within a single frame (multiple detection passes, a same-frame fill+release), which would
+    // otherwise fire the bus repeatedly per tick. busEmit buffers occurrences during the frame; the
+    // single flushBusEvents() at frame end delivers at most ONE event per (source, type) — last write
+    // wins. Behaviour-preserving for listeners that just react to "it happened"; it removes intra-frame
+    // duplicates only. detectProximityEvents/updateCaptureEvents already dedupe per *state transition*;
+    // this layer additionally guarantees one delivery per frame regardless of how many passes ran.
+    const busCoalescer = new FieldEventCoalescer();
+    function busEmit(type, payload) {
+        if (!busHas(type))
+            return; // no listeners → don't even buffer
+        busCoalescer.record(type, payload);
+    }
+    // Flush the frame's coalesced bus events to listeners — called once at the end of each frame.
+    function flushBusEvents() {
+        busCoalescer.flush(busDeliver);
+    }
     const sinkPeak = new WeakMap(); // matter held at the rising edge, for the release count
     // #441 body-proximity events. Object-identity membership (survives rescan; removed bodies pruned).
     const insideOf = new Map(); // enter/exit: bodies currently within a body's range
@@ -151,7 +170,22 @@ export function createField(canvas, opts = {}) {
                     m.delete(k);
     }
     const programmaticBodies = []; // bodies added via addBody(); merged into `bodies` each scan
+    // programmatic edges (addEdge): relationships between two addBody bodies, with no DOM. Each carries a
+    // pure RelationshipAgent stepped every frame (strengthen-with-use / decay / memory). handleToBody lets
+    // addEdge resolve the two bodies from the handles addBody returned.
+    const handleToBody = new WeakMap();
+    const programmaticEdges = [];
+    let edgeSeq = 0;
+    // Reserved agent-threshold events (§22.5, FIELD_EVENTS): per-body hysteretic edge detectors that
+    // turn a continuous metric (sink load, density, attention, entropy) into one debounced `field:*`
+    // CustomEvent on its rising edge — never per-frame. Lazy: a body gets a Thresholder for a metric
+    // only the first frame it has a value to test, and the maps are pruned on rescan with the body.
+    // Keyed body → metric-name → Thresholder; edges track relationship `memory` the same way.
+    const bodyThresholds = new WeakMap();
+    const edgeThresholds = new WeakMap();
     const fieldChannels = new Map(); // addField() input channels
+    // custom overlay functions registered via registerOverlay(); keyed by name, dispatched from renderOverlay()
+    const customOverlays = new Map();
     // All 36 forces are registered on every field — there is no opt-in. Any of them activates per-body
     // through its `data-body` token (e.g. `data-body="lens crystallize"`); an unused force costs nothing.
     registerCoreForces(reg); // the canonical nine (§6)
@@ -175,8 +209,11 @@ export function createField(canvas, opts = {}) {
         density: opts.density && opts.density > 0 ? opts.density : 1,
         render: opts.render ?? 'none', // signals-first default (#538): a bare field runs the sim + feedback but draws nothing until asked. Pass render:'dots' for the particle surface.
         waves: opts.waves ?? true, // draw the background Currents (§24); opt-out for the bare field
+        waveStyle: opts.waveStyle ?? 'linear',
+        waveCenter: opts.waveCenter ?? null,
         background: opts.background ?? 'opaque', // 'transparent' → clear to transparent, underlay over light content
         mass: opts.mass ?? false, // first-class mass (§21.3): m ∝ size when on
+        separation: opts.separation != null && opts.separation >= 0 ? opts.separation : 0,
         attention: opts.attention ?? false, // conserved attention (§2.4), opt-in
         causality: opts.causality ?? false, // cross-boundary causality (Concept 4), opt-in
         heatmap: opts.heatmap ?? false, // density heatmap layer (field-systems H1), opt-in
@@ -229,6 +266,7 @@ export function createField(canvas, opts = {}) {
     let waves = [];
     let bound = [];
     let boundTarget = 0;
+    let resolvedWaveCenter = null;
     // the injected sources (#371): every random draw and wall-clock read in the engine flows
     // through these two, so a seeded rng + fixed clock make a run reproducible end to end.
     const rng = opts.rng ?? Math.random;
@@ -278,6 +316,10 @@ export function createField(canvas, opts = {}) {
     let emitters = [];
     let sparks = [];
     let eventEls = [];
+    // element trigger class-toggle (§22.3, FACM #687): `data-class="dense:lit, captured:full"` adds a
+    // class while a trigger holds and removes it when the trigger releases — the declarative, no-JS
+    // counterpart of the `data-on` CustomEvent binding (same trigger vocabulary, parsed identically).
+    let classEls = [];
     let engaged = []; // [data-hot] listeners, for teardown
     // shadow-DOM participation (docs/engine-reference/shadow-dom.md): encapsulated components dispatch composed
     // register/unregister/update events; the field registers the HOST and never inspects the
@@ -359,6 +401,12 @@ export function createField(canvas, opts = {}) {
             tearBoundNear(bound, waves, b.cx, b.cy, 320, W, H, env.t, (p) => void store.add(newParticle(p)));
             // release docks any DOM elements this sink had captured (§22.3, element capture).
             undockFrom(b);
+            // saturation is the threshold transition for field:saturated (§22.5, FACM #686): the sink
+            // reached its capacity this frame (that is what triggered the supernova). The force pass resets
+            // accreted to 0 immediately, so the load metric is never observable at ≈1 after the fact — the
+            // honest place to announce saturation is here, the moment it happens. field:released (below) is
+            // the paired down-edge, so a consumer gets both ends of the cycle.
+            fireThreshold(b.el, 'field:saturated', { peak: released.length });
             // and fires field:released on the falling edge of accreting (capture/release events, §22.5).
             if (b.el.dataset.fxCap === '1') {
                 b.el.dataset.fxCap = '0';
@@ -504,6 +552,16 @@ export function createField(canvas, opts = {}) {
                 bindings: parseEventBindings(el.dataset.on ?? ''),
             };
         });
+        // element trigger class-toggle (§22.3, FACM #687): same trigger:value grammar as data-on, but the
+        // value is a class name toggled on the element instead of an event name dispatched.
+        classEls = [...host.root.querySelectorAll('[data-class]')].map((node) => {
+            const el = node;
+            return {
+                el,
+                body: bodies.find((b) => b.el === el) ?? null,
+                bindings: parseEventBindings(el.dataset.class ?? ''),
+            };
+        });
         // resolve `warp` pairings (§22.3 relocate): a body's data-pair selector → the paired body, whose
         // live centre becomes the relocate target each frame (updateWarpTargets).
         for (const b of bodies) {
@@ -622,6 +680,31 @@ export function createField(canvas, opts = {}) {
             }
         }
     }
+    // element trigger class-toggle (§22.3, FACM #687): the declarative element-trigger consumer. While a
+    // trigger holds (the same dense/sparse/engaged/captured vocabulary data-on uses), add its class to
+    // the element; remove it when the trigger releases. Idempotent via classList + the per-binding armed
+    // flag, so a held trigger toggles exactly once. Opt-in by `data-class`, so it never touches existing
+    // content — the no-JS counterpart of doing `el.classList.toggle()` inside a data-on handler.
+    function updateClassToggles() {
+        if (classEls.length === 0)
+            return;
+        for (const ce of classEls) {
+            const s = ce.body
+                ? { d: ce.body.d, on: ce.body.on, accreted: ce.body.accreted }
+                : { d: 0, on: ce.el.dataset.active === '1', accreted: 0 };
+            for (const bind of ce.bindings) {
+                const active = triggerActive(bind.trigger, s);
+                if (active && !bind.armed) {
+                    bind.armed = true;
+                    ce.el.classList.add(bind.event); // `event` carries the class name for a data-class binding
+                }
+                else if (!active && bind.armed) {
+                    bind.armed = false;
+                    ce.el.classList.remove(bind.event);
+                }
+            }
+        }
+    }
     // dispatch a discrete field event on an element, with the forces:* alias (migration window).
     function fireCaptureEvent(el, name, detail) {
         el.dispatchEvent(new CustomEvent('field:' + name, { bubbles: true, composed: true, detail }));
@@ -652,6 +735,72 @@ export function createField(canvas, opts = {}) {
             }
         }
     }
+    // Reserved agent-threshold events (§22.5): turn each body's continuous metrics into debounced,
+    // hysteretic `field:*` CustomEvents on the element as it crosses a level. Mirrors the lit/dim
+    // contract (rising edge fires once, falls re-arm), but routed through the shared Thresholder so the
+    // enter/exit levels + debounce are uniform. Every event is paired (a "warning"/"shifted" rising
+    // edge and an `*-cleared` falling edge) so a consumer can react both ways. Lazy & cheap: a body
+    // only allocates a Thresholder for a metric the first frame that metric has a value to test, and
+    // the per-frame loop is a few comparisons. `field:entered`/`field:exited` here are the body's own
+    // density crossing (distinct from `field:lit`/`field:dim`, which carry the neighbour-spillover lit
+    // channel). See FIELD_EVENTS in agents/event-agent.ts and docs/canonical/agent-consumption-model.md.
+    // density / attention / entropy are continuous channels sampled per frame → hysteretic Thresholder.
+    // saturation is a discrete transition (the sink hitting capacity), so field:saturated is fired from
+    // the supernova callback above, not here (the load metric is reset to 0 before this loop runs).
+    const THRESHOLD_EVENTS = [
+        { metric: 'density', enter: 0.6, exit: 0.2, rise: 'field:entered', fall: 'field:exited' },
+        { metric: 'attention', enter: 1.5, exit: 1.1, rise: 'field:attention-shifted', fall: 'field:attention-settled' },
+        { metric: 'entropy', enter: 0.7, exit: 0.4, rise: 'field:entropy-warning', fall: 'field:entropy-cleared' },
+    ];
+    const THRESHOLD_DEBOUNCE_MS = 120;
+    function fireThreshold(el, name, detail) {
+        el.dispatchEvent(new CustomEvent(name, { bubbles: true, composed: true, detail }));
+    }
+    function dispatchBodyThreshold(store, key, el, spec, value, now) {
+        let metrics = store.get(key);
+        if (!metrics)
+            store.set(key, (metrics = new Map()));
+        let th = metrics.get(spec.metric);
+        if (!th)
+            metrics.set(spec.metric, (th = new Thresholder({ enter: spec.enter, exit: spec.exit, debounceMs: THRESHOLD_DEBOUNCE_MS })));
+        const edge = th.update(value, now);
+        if (edge === 'entered')
+            fireThreshold(el, spec.rise, { metric: spec.metric, value });
+        else if (edge === 'exited')
+            fireThreshold(el, spec.fall, { metric: spec.metric, value });
+    }
+    function updateThresholdEvents(now) {
+        for (const b of bodies) {
+            if (!b.vis || b.tokens.length === 0)
+                continue;
+            for (const spec of THRESHOLD_EVENTS) {
+                let value;
+                switch (spec.metric) {
+                    case 'density':
+                        value = b.d;
+                        break;
+                    case 'attention':
+                        // conserved-attention multiplier (1 = neutral); only meaningful while attention is on.
+                        if (cfg.attention)
+                            value = b.attn ?? 1;
+                        break;
+                    case 'entropy':
+                        value = b.metrics?.entropy;
+                        break;
+                }
+                if (value === undefined)
+                    continue;
+                dispatchBodyThreshold(bodyThresholds, b, b.el, spec, value, now);
+            }
+        }
+        // relationship memory (addEdge agents, §2.7): a remembered edge crosses its memory threshold.
+        // The event dispatches on the source body's element so an app can react to "this relationship is
+        // now durably remembered" / "…has faded". (For programmatic addBody bodies the element is the
+        // internal synthetic stub; a DOM-backed edge surfaces it on a real node.)
+        for (const e of programmaticEdges) {
+            dispatchBodyThreshold(edgeThresholds, e.agent, e.from.el, { metric: 'memory', enter: 0.6, exit: 0.3, rise: 'field:memory-threshold', fall: 'field:memory-faded' }, e.agent.memory, now);
+        }
+    }
     // release any DOM elements a sink had docked (§22.3) — restore their transform + a11y, fire
     // field:released. Called from supernova so element capture is conserved like particle capture.
     function undockFrom(b) {
@@ -903,73 +1052,165 @@ export function createField(canvas, opts = {}) {
     function drawWaves() {
         const time = env.t;
         const STEP = 16;
-        for (const w of waves) {
-            const [cr, cg, cb] = w.color;
-            ctx.beginPath();
-            ctx.moveTo(0, waveYat(w, 0, time, H, 1, 1, pull));
-            for (let x = 0; x <= W; x += STEP)
-                ctx.lineTo(x, waveYat(w, x, time, H, 1, 1, pull));
-            ctx.lineTo(W, H);
-            ctx.lineTo(0, H);
-            ctx.closePath();
-            const ty = w.baseFrac * H + w.offsetY - w.amp;
-            const grad = ctx.createLinearGradient(0, ty, 0, ty + 320);
-            grad.addColorStop(0, `rgba(${cr},${cg},${cb},${(0.11 + w.depth * 0.05) * boot})`);
-            grad.addColorStop(1, `rgba(${cr},${cg},${cb},0)`);
-            ctx.fillStyle = grad;
-            ctx.fill();
+        if (cfg.waveStyle === 'circular') {
+            const c = resolvedWaveCenter || { x: W / 2, y: H / 2 };
+            const maxRadius = Math.min(W, H) * 0.48;
+            for (const w of waves) {
+                const [cr, cg, cb] = w.color;
+                ctx.beginPath();
+                const dTheta = 0.08;
+                let first = true;
+                for (let theta = 0; theta <= 2 * Math.PI + 0.01; theta += dTheta) {
+                    const r = waveRAt(w, theta, time, maxRadius);
+                    const x = c.x + Math.cos(theta) * r;
+                    const y = c.y + Math.sin(theta) * r;
+                    if (first) {
+                        ctx.moveTo(x, y);
+                        first = false;
+                    }
+                    else {
+                        ctx.lineTo(x, y);
+                    }
+                }
+                ctx.closePath();
+                const baseR = w.baseFrac * maxRadius + w.offsetY;
+                const grad = ctx.createRadialGradient(c.x, c.y, Math.max(0, baseR - w.amp), c.x, c.y, baseR + w.amp + 80);
+                grad.addColorStop(0, `rgba(${cr},${cg},${cb},${(0.08 + w.depth * 0.04) * boot})`);
+                grad.addColorStop(1, `rgba(${cr},${cg},${cb},0)`);
+                ctx.fillStyle = grad;
+                ctx.fill();
+            }
+            ctx.globalCompositeOperation = 'lighter';
+            for (const w of waves) {
+                const [cr, cg, cb] = w.color;
+                ctx.beginPath();
+                const dTheta = 0.08;
+                let first = true;
+                for (let theta = 0; theta <= 2 * Math.PI + 0.01; theta += dTheta) {
+                    const r = waveRAt(w, theta, time, maxRadius);
+                    const x = c.x + Math.cos(theta) * r;
+                    const y = c.y + Math.sin(theta) * r;
+                    if (first) {
+                        ctx.moveTo(x, y);
+                        first = false;
+                    }
+                    else {
+                        ctx.lineTo(x, y);
+                    }
+                }
+                ctx.closePath();
+                ctx.lineWidth = 5;
+                ctx.strokeStyle = `rgba(${cr},${cg},${cb},${(0.05 + w.depth * 0.04) * boot})`;
+                ctx.stroke();
+                ctx.lineWidth = 1.2;
+                ctx.strokeStyle = `rgba(${cr},${cg},${cb},${(0.3 + w.depth * 0.22) * boot})`;
+                ctx.stroke();
+            }
+            ctx.globalCompositeOperation = 'source-over';
         }
-        ctx.globalCompositeOperation = 'lighter';
-        for (const w of waves) {
-            const [cr, cg, cb] = w.color;
-            ctx.beginPath();
-            ctx.moveTo(0, waveYat(w, 0, time, H, 1, 1, pull));
-            for (let x = 0; x <= W; x += STEP)
-                ctx.lineTo(x, waveYat(w, x, time, H, 1, 1, pull));
-            // glow via a wide faint underlay then a crisp line (both additive) — not
-            // shadowBlur, which made each of the five long strokes cost several ×.
-            ctx.lineWidth = 5;
-            ctx.strokeStyle = `rgba(${cr},${cg},${cb},${(0.05 + w.depth * 0.04) * boot})`;
-            ctx.stroke();
-            ctx.lineWidth = 1.2;
-            ctx.strokeStyle = `rgba(${cr},${cg},${cb},${(0.3 + w.depth * 0.22) * boot})`;
-            ctx.stroke();
+        else {
+            for (const w of waves) {
+                const [cr, cg, cb] = w.color;
+                ctx.beginPath();
+                ctx.moveTo(0, waveYat(w, 0, time, H, 1, 1, pull));
+                for (let x = 0; x <= W; x += STEP)
+                    ctx.lineTo(x, waveYat(w, x, time, H, 1, 1, pull));
+                ctx.lineTo(W, H);
+                ctx.lineTo(0, H);
+                ctx.closePath();
+                const ty = w.baseFrac * H + w.offsetY - w.amp;
+                const grad = ctx.createLinearGradient(0, ty, 0, ty + 320);
+                grad.addColorStop(0, `rgba(${cr},${cg},${cb},${(0.11 + w.depth * 0.05) * boot})`);
+                grad.addColorStop(1, `rgba(${cr},${cg},${cb},0)`);
+                ctx.fillStyle = grad;
+                ctx.fill();
+            }
+            ctx.globalCompositeOperation = 'lighter';
+            for (const w of waves) {
+                const [cr, cg, cb] = w.color;
+                ctx.beginPath();
+                ctx.moveTo(0, waveYat(w, 0, time, H, 1, 1, pull));
+                for (let x = 0; x <= W; x += STEP)
+                    ctx.lineTo(x, waveYat(w, x, time, H, 1, 1, pull));
+                ctx.lineWidth = 5;
+                ctx.strokeStyle = `rgba(${cr},${cg},${cb},${(0.05 + w.depth * 0.04) * boot})`;
+                ctx.stroke();
+                ctx.lineWidth = 1.2;
+                ctx.strokeStyle = `rgba(${cr},${cg},${cb},${(0.3 + w.depth * 0.22) * boot})`;
+                ctx.stroke();
+            }
+            ctx.globalCompositeOperation = 'source-over';
         }
-        ctx.globalCompositeOperation = 'source-over';
     }
     function drawBound() {
         ctx.globalCompositeOperation = 'lighter';
         const time = env.t;
         let i = 0;
-        for (const p of bound) {
-            const w = waves[p.wi];
-            if (!w) {
+        if (cfg.waveStyle === 'circular') {
+            const c = resolvedWaveCenter || { x: W / 2, y: H / 2 };
+            const maxRadius = Math.min(W, H) * 0.48;
+            for (const p of bound) {
+                const w = waves[p.wi];
+                if (!w) {
+                    i++;
+                    continue;
+                }
+                if (env.dt) {
+                    p.progress += p.speed;
+                    if (p.progress > 1)
+                        p.progress -= 1;
+                    else if (p.progress < 0)
+                        p.progress += 1;
+                }
+                const theta = p.progress * 2 * Math.PI;
+                const r = waveRAt(w, theta, time, maxRadius) + p.phase * 32;
+                const x = c.x + Math.cos(theta) * r;
+                const y = c.y + Math.sin(theta) * r;
+                const [cr, cg, cb] = w.color;
+                const tw = p.glow ? 0.6 + 0.4 * Math.sin(time * 2.2 + i) : 0.85;
+                if (p.glow) {
+                    ctx.fillStyle = `rgba(${cr},${cg},${cb},${0.16 * tw * boot})`;
+                    ctx.beginPath();
+                    ctx.arc(x, y, p.size + 2.5, 0, 6.28318);
+                    ctx.fill();
+                }
+                ctx.fillStyle = `rgba(${cr},${cg},${cb},${tw * boot})`;
+                ctx.beginPath();
+                ctx.arc(x, y, p.size, 0, 6.28318);
+                ctx.fill();
                 i++;
-                continue;
             }
-            if (env.dt) {
-                p.progress += p.speed;
-                if (p.progress > 1)
-                    p.progress -= 1;
-                else if (p.progress < 0)
-                    p.progress += 1;
-            }
-            const x = p.progress * W;
-            const y = waveYat(w, x, time, H, 1, 1, pull) + p.phase * 32;
-            const [cr, cg, cb] = w.color;
-            const tw = p.glow ? 0.6 + 0.4 * Math.sin(time * 2.2 + i) : 0.85;
-            if (p.glow) {
-                // additive halo instead of shadowBlur (the canvas is composited 'lighter')
-                ctx.fillStyle = `rgba(${cr},${cg},${cb},${0.16 * tw * boot})`;
+        }
+        else {
+            for (const p of bound) {
+                const w = waves[p.wi];
+                if (!w) {
+                    i++;
+                    continue;
+                }
+                if (env.dt) {
+                    p.progress += p.speed;
+                    if (p.progress > 1)
+                        p.progress -= 1;
+                    else if (p.progress < 0)
+                        p.progress += 1;
+                }
+                const x = p.progress * W;
+                const y = waveYat(w, x, time, H, 1, 1, pull) + p.phase * 32;
+                const [cr, cg, cb] = w.color;
+                const tw = p.glow ? 0.6 + 0.4 * Math.sin(time * 2.2 + i) : 0.85;
+                if (p.glow) {
+                    ctx.fillStyle = `rgba(${cr},${cg},${cb},${0.16 * tw * boot})`;
+                    ctx.beginPath();
+                    ctx.arc(x, y, p.size + 2.5, 0, 6.28318);
+                    ctx.fill();
+                }
+                ctx.fillStyle = `rgba(${cr},${cg},${cb},${tw * boot})`;
                 ctx.beginPath();
-                ctx.arc(x, y, p.size + 2.5, 0, 6.28318);
+                ctx.arc(x, y, p.size, 0, 6.28318);
                 ctx.fill();
+                i++;
             }
-            ctx.fillStyle = `rgba(${cr},${cg},${cb},${tw * boot})`;
-            ctx.beginPath();
-            ctx.arc(x, y, p.size, 0, 6.28318);
-            ctx.fill();
-            i++;
         }
         ctx.globalCompositeOperation = 'source-over';
     }
@@ -1587,9 +1828,12 @@ export function createField(canvas, opts = {}) {
     // `grid` — a reference lattice whose vertices are displaced along the felt field; the page's
     // space itself made visible, bending where the field is strong. Reads deformation.
     function drawOverlayGrid(out) {
-        const STEP = 56;
-        const MAXD = 11 * cfg.gridWarp; // px displacement at the strongest sample — legible, never
-        // chaotic at the default gridWarp=1; the multiplier exaggerates the deformation for demos.
+        const STEP = 48; // roomy cells so each mass can dimple the lattice into a deep, legible bowl; the
+        // CLAMP below keeps even a deep bowl foldless (denser than the field-line default still reads fine).
+        const MAXD = 22 * cfg.gridWarp; // px displacement the field asks for at the strongest sample; the
+        // CLAMP below is what actually keeps it legible, so gridWarp drives how fast that ceiling is reached.
+        const CLAMP = STEP * 0.46; // a vertex can move at most ~half a cell, so adjacent lines bend hard but
+        // can NEVER cross — the displaced grid always reads as deep curved space, never a tangle.
         const cols = Math.floor(W / STEP) + 2;
         const rows = Math.floor(H / STEP) + 2;
         const dx = new Float32Array(cols * rows);
@@ -1610,27 +1854,124 @@ export function createField(canvas, opts = {}) {
                 }
             }
         }
-        const acc = curAccent; // #530: the cached live accent RGB (was hexToRgb(cfg.accent) — a per-frame parse)
-        // a bolder lattice also wants a slightly heavier line so it reads as structure, not threads;
-        // at the faint diagnostic default (0.16) this stays width 1 — byte-identical to before.
-        const stroke = { r: acc[0], g: acc[1], b: acc[2], alpha: cfg.gridIntensity, width: cfg.gridIntensity > 0.3 ? 1.2 : 1 };
+        // Heatmap-coloured lattice: each segment is tinted by how hard the field warps it there — cool
+        // accent where space is flat, through warm orange, to white-hot at the strongest deflection (the
+        // mass wells). Opacity rises with the deflection too, so flat space is a faint base lattice and the
+        // warped regions blaze — the spacetime-curvature image made literal. Consecutive same-band segments
+        // are merged into one polyline, so the colouring costs a handful of extra strokes, not one per cell.
+        // neon ramp: accent blue (flat space) → electric violet → neon magenta → hot neon pink (the wells).
+        // curAccent (#530) is the cached accent RGB — the cool stop the warped regions heat away from.
+        const HEAT = [curAccent, [120, 110, 255], [240, 70, 255], [255, 50, 130]];
+        const BANDS = 8;
+        const relAt = (i) => (maxMag > 0 ? Math.sqrt(mags[i] / maxMag) : 0);
+        const bandAt = (i) => Math.round(relAt(i) * BANDS);
+        const strokeFor = (b) => {
+            const rel = b / BANDS;
+            const c = sampleStops(HEAT, rel);
+            // cool flat space sits at ~30% of the configured intensity; the hottest cells reach it in full.
+            return { r: c[0], g: c[1], b: c[2], alpha: Math.min(1, cfg.gridIntensity * (0.3 + 0.85 * rel)), width: rel > 0.55 ? 1.4 : 1 };
+        };
+        // Build the raw displacement vector per vertex (direction × normalized strength × throw), then box-
+        // blur it once so neighbouring vertices move together — a rubber sheet dimpling, not per-vertex
+        // jitter. Blurring the displacement (not the field) is what turns the knot at each mass into a smooth
+        // bowl: the inward pull is averaged with its calmer neighbours, so nothing collapses to a point.
+        const wx = new Float32Array(cols * rows);
+        const wy = new Float32Array(cols * rows);
+        for (let i = 0; i < cols * rows; i++) {
+            const rel = relAt(i);
+            wx[i] = dx[i] * rel * MAXD;
+            wy[i] = dy[i] * rel * MAXD;
+        }
+        const bx = new Float32Array(cols * rows);
+        const by = new Float32Array(cols * rows);
+        for (let gy = 0; gy < rows; gy++) {
+            for (let gx = 0; gx < cols; gx++) {
+                let sx = 0, sy = 0, n = 0;
+                for (let oy = -1; oy <= 1; oy++) {
+                    for (let ox = -1; ox <= 1; ox++) {
+                        const x = gx + ox, y = gy + oy;
+                        if (x < 0 || y < 0 || x >= cols || y >= rows)
+                            continue;
+                        const j = y * cols + x;
+                        sx += wx[j];
+                        sy += wy[j];
+                        n++;
+                    }
+                }
+                const i = gy * cols + gx;
+                bx[i] = sx / n;
+                by[i] = sy / n;
+            }
+        }
+        const FADE = STEP * 1.5; // taper the warp to zero within ~1.5 cells of each viewport edge, so the
+        // lattice always frames the screen instead of pulling away from the edges under a strong inward warp.
         const px = (gx, gy) => {
             const i = gy * cols + gx;
-            const rel = maxMag > 0 ? Math.sqrt(mags[i] / maxMag) : 0;
-            return [gx * STEP + dx[i] * rel * MAXD, gy * STEP + dy[i] * rel * MAXD];
+            let ux = bx[i], uy = by[i];
+            const m = Math.hypot(ux, uy);
+            if (m > CLAMP) {
+                ux = (ux / m) * CLAMP;
+                uy = (uy / m) * CLAMP;
+            } // half-cell ceiling: never fold.
+            const px0 = gx * STEP, py0 = gy * STEP;
+            const e = Math.min(px0, W - px0, py0, H - py0); // distance to the nearest viewport edge
+            const k = e <= 0 ? 0 : e < FADE ? e / FADE : 1; // pin the boundary (k=0), ease to full warp inward
+            return [px0 + ux * k, py0 + uy * k];
         };
-        const row = [];
+        // Smooth the warped lines into curves: Catmull-Rom through the displaced vertices (the curve passes
+        // through every original point, so the warp magnitude is preserved) — the lattice reads as bent
+        // space, not faceted segments. Single-segment runs (n < 3) are already straight, returned as-is.
+        const SUB = 4;
+        const smooth = (p) => {
+            const n = p.length >> 1;
+            if (n < 3)
+                return p;
+            const o = [p[0], p[1]];
+            for (let i = 0; i < n - 1; i++) {
+                const a = (i > 0 ? i - 1 : 0) << 1;
+                const b = i << 1;
+                const c = (i + 1) << 1;
+                const e = (i + 2 < n ? i + 2 : n - 1) << 1;
+                const x0 = p[a], y0 = p[a + 1], x1 = p[b], y1 = p[b + 1], x2 = p[c], y2 = p[c + 1], x3 = p[e], y3 = p[e + 1];
+                for (let s = 1; s <= SUB; s++) {
+                    const t = s / SUB, t2 = t * t, t3 = t2 * t;
+                    o.push(0.5 * (2 * x1 + (-x0 + x2) * t + (2 * x0 - 5 * x1 + 4 * x2 - x3) * t2 + (-x0 + 3 * x1 - 3 * x2 + x3) * t3), 0.5 * (2 * y1 + (-y0 + y2) * t + (2 * y0 - 5 * y1 + 4 * y2 - y3) * t2 + (-y0 + 3 * y1 - 3 * y2 + y3) * t3));
+                }
+            }
+            return o;
+        };
+        // a segment is as hot as its hottest endpoint, so a line passing a well lights up across the well.
+        const hSeg = (gy, gx) => Math.max(bandAt(gy * cols + gx), bandAt(gy * cols + gx + 1));
+        const vSeg = (gx, gy) => Math.max(bandAt(gy * cols + gx), bandAt((gy + 1) * cols + gx));
         for (let gy = 0; gy < rows; gy++) {
-            row.length = 0;
-            for (let gx = 0; gx < cols; gx++)
-                row.push(...px(gx, gy));
-            out.polyline(row, stroke);
+            let band = hSeg(gy, 0);
+            let pts = [...px(0, gy), ...px(1, gy)];
+            for (let gx = 1; gx < cols - 1; gx++) {
+                const sb = hSeg(gy, gx);
+                if (sb === band)
+                    pts.push(...px(gx + 1, gy));
+                else {
+                    out.polyline(smooth(pts), strokeFor(band));
+                    pts = [...px(gx, gy), ...px(gx + 1, gy)];
+                    band = sb;
+                }
+            }
+            out.polyline(smooth(pts), strokeFor(band));
         }
         for (let gx = 0; gx < cols; gx++) {
-            row.length = 0;
-            for (let gy = 0; gy < rows; gy++)
-                row.push(...px(gx, gy));
-            out.polyline(row, stroke);
+            let band = vSeg(gx, 0);
+            let pts = [...px(gx, 0), ...px(gx, 1)];
+            for (let gy = 1; gy < rows - 1; gy++) {
+                const sb = vSeg(gx, gy);
+                if (sb === band)
+                    pts.push(...px(gx, gy + 1));
+                else {
+                    out.polyline(smooth(pts), strokeFor(band));
+                    pts = [...px(gx, gy), ...px(gx, gy + 1)];
+                    band = sb;
+                }
+            }
+            out.polyline(smooth(pts), strokeFor(band));
         }
     }
     // shared scalar-contour pass for `temperature` and `energy` — splat a per-particle scalar onto a
@@ -1772,6 +2113,10 @@ export function createField(canvas, opts = {}) {
                 drawOverlayPaths(out);
             else if (mode === 'data')
                 drawOverlayData(out);
+            // custom overlays registered via registerOverlay()
+            const customFn = customOverlays.get(mode);
+            if (customFn)
+                customFn(out, env, W, H);
         }
     }
     function frame(now) {
@@ -1826,6 +2171,14 @@ export function createField(canvas, opts = {}) {
             // edge of engagement — the same conserved supernova ritual as saturation.
             dischargeDisengaged(bodies, env.supernova);
         }
+        // Step programmatic edges (addEdge): a relationship is "active" while its source body is salient
+        // (gathering matter, d > 0.08) — it then strengthens + accumulates memory, and decays while idle.
+        // env.dt is frame-normalized (≈1 at 60fps); the dynamics rates are per-second, so convert (÷60).
+        if (programmaticEdges.length && env.dt) {
+            const dtS = env.dt / 60;
+            for (const e of programmaticEdges)
+                updateRelationship(e.agent, e.from.d > 0.08, 0, dtS);
+        }
         // spine: ease the wave-bend toward the flow focus (if set) or the engaged element (§24). A live
         // flow focus (field.flowTo) takes priority, so the streamline spine curves to the moving target.
         let engaged = null;
@@ -1869,8 +2222,25 @@ export function createField(canvas, opts = {}) {
                 p.vy += b.y;
             }
         }
+        if (cfg.waveStyle === 'circular') {
+            if (cfg.waveCenter) {
+                resolvedWaveCenter = typeof cfg.waveCenter === 'function' ? cfg.waveCenter() : cfg.waveCenter;
+            }
+            else {
+                const star = bodies.find((b) => b.tokens.includes('star') || b.tokens.includes('vortex'));
+                if (star) {
+                    resolvedWaveCenter = { x: star.cx, y: star.cy };
+                }
+                else {
+                    resolvedWaveCenter = { x: W / 2, y: H / 2 };
+                }
+            }
+        }
+        else {
+            resolvedWaveCenter = null;
+        }
         updateWarpTargets(); // refresh warp relocate targets from paired bodies (§22.3) before the step
-        step({ store, bodies, env, forces: reg.forces, conditions: reg.conditions, waves });
+        step({ store, bodies, env, forces: reg.forces, conditions: reg.conditions, waves, waveStyle: cfg.waveStyle, waveCenter: resolvedWaveCenter, separation: cfg.separation });
         // hover-focus (field.focusAt): hold the focused particle still and light it up — the dwell
         // affordance ("it stops and does something") before a click opens its record.
         if (focusP) {
@@ -1893,7 +2263,10 @@ export function createField(canvas, opts = {}) {
         writeFeedback();
         applyCausality();
         updateEvents();
+        updateClassToggles(); // element trigger class-toggle (§22.3, FACM #687): toggle data-class on crossings
         updateCaptureEvents();
+        updateThresholdEvents(now); // reserved agent-threshold events (§22.5): debounced field:* on crossings
+        flushBusEvents(); // #684: deliver the frame's coalesced discrete events — one per (source, type)
         // Draw only when there is a surface to draw to AND the canvas can be seen. Under the
         // signals-only mode (`render: 'none'`, §13.7 / #297) the engine never draws — neither the
         // underlay nor the overlay — and `ctx` may not even exist. Under reduced motion the scene is
@@ -1990,6 +2363,15 @@ export function createField(canvas, opts = {}) {
             }
         },
         setFormation,
+        setWaveStyle: (style) => {
+            cfg.waveStyle = style;
+        },
+        setWaveCenter: (center) => {
+            cfg.waveCenter = center;
+        },
+        setSeparation: (strength) => {
+            cfg.separation = strength >= 0 ? strength : 0;
+        },
         setAttention: (on) => {
             cfg.attention = on;
             if (!on)
@@ -2171,6 +2553,34 @@ export function createField(canvas, opts = {}) {
             }
             return w;
         },
+        readParticleChannels: (channels, out) => {
+            const ps = store.particles;
+            let written = 0;
+            for (let i = 0; i < ps.length; i++) {
+                const p = ps[i];
+                if ('report' in p && p.report !== undefined)
+                    continue;
+                if (written >= Math.min(...out.map(b => b.length)))
+                    break;
+                for (let ci = 0; ci < channels.length; ci++) {
+                    if (ci >= out.length)
+                        break;
+                    const ch = channels[ci];
+                    out[ci][written] =
+                        ch === 'x' ? p.x : ch === 'y' ? p.y : ch === 'z' ? (p.z ?? 0) :
+                            ch === 'vx' ? p.vx : ch === 'vy' ? p.vy :
+                                ch === 'heat' ? p.heat : ch === 'size' ? p.size :
+                                    ch === 'm' ? p.m : ch === 'id' ? (p.id ?? 0) :
+                                        ch === 'age' ? (p.age ?? 0) : ch === 'charge' ? (p.charge ?? 0) : 0;
+                }
+                written++;
+            }
+            return written;
+        },
+        registerOverlay: (name, drawFn) => {
+            customOverlays.set(name, drawFn);
+            return () => { customOverlays.delete(name); };
+        },
         addAgent: (spec) => {
             const p = newParticle({ x: spec.x, y: spec.y, z: spec.z, species: spec.species });
             p.vx = 0;
@@ -2231,7 +2641,7 @@ export function createField(canvas, opts = {}) {
             programmaticBodies.push(body);
             bodies = bodies.concat(body); // live this frame, before the next scan re-merges it
             measureBodies([body], W, H, originX, originY); // init cx/cy so the first sample/force is correct
-            return {
+            const handle = {
                 data: spec.data,
                 get channels() { return channels; },
                 set: (params) => {
@@ -2257,9 +2667,58 @@ export function createField(canvas, opts = {}) {
                     if (i >= 0)
                         programmaticBodies.splice(i, 1);
                     bodies = bodies.filter((x) => x !== body);
+                    // drop any programmatic edges that touched this body (#601).
+                    for (let k = programmaticEdges.length - 1; k >= 0; k--) {
+                        const pe = programmaticEdges[k];
+                        if (pe.from === body || pe.to === body)
+                            programmaticEdges.splice(k, 1);
+                    }
+                },
+            };
+            handleToBody.set(handle, body);
+            return handle;
+        },
+        addEdge: (a, b, opts) => {
+            // a relationship between two programmatic bodies (the addBody handles). No DOM — the edge keys on
+            // the body identities; it feeds the same pure RelationshipAgent dynamics the DOM graph uses.
+            const from = handleToBody.get(a);
+            const to = handleToBody.get(b);
+            if (!from || !to)
+                throw new Error('addEdge: both arguments must be handles returned by addBody on this field.');
+            const agent = {
+                id: `e${edgeSeq++}`,
+                from: '', // body ids are internal; readEdges exposes the carried data instead
+                to: '',
+                type: opts?.type ?? 'related',
+                strength: opts?.strength ?? 0.5,
+                tension: 0,
+                memory: 0,
+                active: false,
+            };
+            const edge = { agent, from, to, fromData: a.data, toData: b.data };
+            programmaticEdges.push(edge);
+            return {
+                set: (params) => {
+                    if (params.strength != null)
+                        agent.strength = params.strength < 0 ? 0 : params.strength > 1 ? 1 : params.strength;
+                    if (params.type != null)
+                        agent.type = params.type;
+                },
+                remove: () => {
+                    const i = programmaticEdges.indexOf(edge);
+                    if (i >= 0)
+                        programmaticEdges.splice(i, 1);
                 },
             };
         },
+        readEdges: () => programmaticEdges.map((e) => ({
+            from: e.fromData,
+            to: e.toData,
+            type: e.agent.type,
+            strength: e.agent.strength,
+            memory: e.agent.memory,
+            active: e.agent.active,
+        })),
         addField: (name, sampler) => {
             fieldChannels.set(name, sampler);
             return {