@fundamental-engine/core 0.7.0 → 0.9.0

package/dist/core/field.js

@@ -20,20 +20,23 @@ 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";
+import { THEMES, DEFAULT_THEME } from "../config/themes.js";
 import { clamp, hexToRgb, particleRGBInto, rgbToHex, sampleStops } from "./math.js";
 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";
@@ -45,9 +48,9 @@ import { forceAt, netField } from "./streamlines.js";
 import { traceFieldLines } from "./fieldlines.js";
 import { fieldLineSeeds } from "./fieldline-seeds.js";
 import { flowBiasInto, makeFlowFocus } from "./flow.js";
+import { devWarnNoOp } from "../contracts/guards.js";
+import { FIELD_VERSION } from "../version.js";
 import { energyReport } from "../diagnostics/energy.js";
-// the Currents' cool baseline palette — a subset of the force palette (§24.4).
-const WAVE_RGB = ['#4da3ff', '#2dd4bf', '#a78bfa'].map(hexToRgb);
 // Shared draw/integrate scratch — reused across the per-particle and per-cell hot loops so an
 // active flow focus and the particle draw don't allocate a `{x,y}` / `[r,g,b]` each iteration.
 // Safe to share module-wide: each field's frame runs synchronously, and every read consumes the
@@ -62,7 +65,7 @@ export function createField(canvas, opts = {}) {
     // acquires it lazily (and sizes the store then) — so a field created with 'none' allocates no
     // render surface at all unless asked to draw.
     let ctx = null;
-    if ((opts.render ?? 'dots') !== 'none') {
+    if ((opts.render ?? 'none') !== 'none') {
         ctx = canvas.getContext('2d');
         if (!ctx)
             throw new Error('Fundamental: 2D canvas context unavailable');
@@ -86,15 +89,103 @@ 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
+    const metWith = new Map(); // met: bodies currently in box-contact (symmetric, deduped a<b)
+    function detectProximityEvents(bs) {
+        const wantEE = busHas('enter') || busHas('exit');
+        const wantMet = busHas('met');
+        if (!wantEE && !wantMet)
+            return; // lazy: zero listeners → zero cost
+        for (let i = 0; i < bs.length; i++) {
+            const a = bs[i];
+            if (wantEE) {
+                let inside = insideOf.get(a);
+                if (!inside)
+                    insideOf.set(a, (inside = new Set()));
+                const r2 = a.range * a.range;
+                for (let j = 0; j < bs.length; j++) {
+                    if (i === j)
+                        continue;
+                    const o = bs[j];
+                    const dx = o.cx - a.cx, dy = o.cy - a.cy;
+                    const isIn = dx * dx + dy * dy < r2;
+                    if (isIn && !inside.has(o)) {
+                        inside.add(o);
+                        if (busHas('enter'))
+                            busEmit('enter', { body: a, other: o });
+                    }
+                    else if (!isIn && inside.has(o)) {
+                        inside.delete(o);
+                        if (busHas('exit'))
+                            busEmit('exit', { body: a, other: o });
+                    }
+                }
+            }
+            if (wantMet) {
+                let met = metWith.get(a);
+                if (!met)
+                    metWith.set(a, (met = new Set()));
+                for (let j = i + 1; j < bs.length; j++) {
+                    const b = bs[j];
+                    const touch = Math.abs(b.cx - a.cx) < a.hw + b.hw && Math.abs(b.cy - a.cy) < a.hh + b.hh;
+                    if (touch && !met.has(b)) {
+                        met.add(b);
+                        busEmit('met', { a, b });
+                    }
+                    else if (!touch && met.has(b))
+                        met.delete(b);
+                }
+            }
+        }
+        // prune tracking for bodies no longer present (rescan removed them) so they neither leak nor re-fire
+        const present = new Set(bs);
+        for (const m of [insideOf, metWith])
+            for (const k of m.keys())
+                if (!present.has(k))
+                    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)
@@ -110,17 +201,32 @@ export function createField(canvas, opts = {}) {
     const host = opts.host;
     const teardowns = []; // host event unsubscribers, called on destroy
     const reduceMotion = host.reducedMotion();
+    // ambient theme (#529): a named preset for the heat ramp + wave baseline; `warm` (default) reproduces
+    // the shipped palette. Individual lanes (gradientCool/gradientWarm/waveBaseline) override the preset.
+    const theme = THEMES[opts.theme ?? DEFAULT_THEME] ?? THEMES[DEFAULT_THEME];
     const cfg = {
         accent: opts.accent ?? resolvePalette(opts.palette)[0] ?? PALETTE[0] ?? '#4da3ff',
         density: opts.density && opts.density > 0 ? opts.density : 1,
-        render: opts.render ?? 'dots',
+        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
         overlay: opts.overlay ?? 'off', // Field Surfaces: overlay-surface visualization mode, opt-in
+        // distortion multiplier for the `grid` overlay's lattice deflection (1 = calibrated default; 0 flat).
+        gridWarp: opts.gridWarp != null && opts.gridWarp >= 0 ? opts.gridWarp : 1,
+        // stroke opacity for the `grid` overlay lines. 0.16 = the calibrated faint diagnostic (default,
+        // never overpowers content); raise it (≈0.5) to make the warped lattice a deliberate centerpiece.
+        gridIntensity: opts.gridIntensity != null && opts.gridIntensity >= 0 ? Math.min(opts.gridIntensity, 1) : 0.16,
+        // theme palette (#529): the heat-ramp ends + wave baseline, resolved from the preset + overrides.
+        gradientCool: opts.gradientCool ? hexToRgb(opts.gradientCool) : theme.cool,
+        gradientWarm: opts.gradientWarm ? hexToRgb(opts.gradientWarm) : theme.warm,
+        waveBaseline: (opts.waveBaseline ?? theme.wave).map(hexToRgb),
         dprCap: opts.dprCap && opts.dprCap > 0 ? opts.dprCap : 2, // backing-store DPR ceiling (#410); the
         // dominant fill-rate lever — the ambient field is soft, so ~1.5 buys ~1.8× headroom on retina.
         // optional z volume (z-axis.md): 0 — the default — is the flat field, byte-identical
@@ -135,6 +241,14 @@ export function createField(canvas, opts = {}) {
     let bodies = [];
     let W = 0;
     let H = 0;
+    // field-space origin from the host viewport (#540) — 0,0 for a window host, the container's
+    // left/top for a contained host. measureBodies + the move/thread readouts subtract it.
+    let originX = 0;
+    let originY = 0;
+    // a contained field (host viewport returns an origin): its bodies live in container-local space,
+    // which is INVARIANT under page scroll (the container + its contents move together). So it refreshes
+    // the origin each frame and skips the window-only per-frame scroll shift below.
+    let contained = false;
     // cached page scroll extent — reading scrollHeight forces a synchronous reflow, so
     // we cache it (refreshed on resize + sampled occasionally) rather than per frame.
     let maxScroll = 1;
@@ -152,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;
@@ -175,6 +290,15 @@ export function createField(canvas, opts = {}) {
     // on a cadence and DRAW from this cache every frame (so the arrows never flicker or step).
     let slSamples = null;
     let slQuiescent = [];
+    // Same cadence cache for the OVERLAY arrows (drawOverlayArrows) — the in-front Field-Surfaces
+    // reading. Its grid is the same body-induced force field, so it had the same per-frame regrid
+    // waste the underlay shed in #406; resample on the cadence, draw from this cache every frame.
+    let olSamples = null;
+    // Tag-tint cache (#515): the parsed RGB + reach² of each coloured body, rebuilt only on the
+    // measure cadence (colour/range change there, not per frame). The body ref is kept so the
+    // per-particle loop reads cx/cy FRESH each frame — those are scroll-compensated every frame
+    // (#508), so caching positions would re-introduce the swarm-pause-on-scroll lag for the tint.
+    let tintCache = null;
     // hard pool ceiling for class-[S] sources (§20.1) — generous above the ~130·density
     // base field so emission is never starved, but bounded so the sim can't grow forever.
     const spawnCeiling = Math.round(130 * cfg.density) * 4;
@@ -192,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
@@ -273,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';
@@ -362,7 +496,7 @@ export function createField(canvas, opts = {}) {
             store.add(newParticle());
         applySeed();
         // the Currents (§24) are opt-out: with waves off, the field is just the free particles.
-        waves = cfg.waves ? buildWaves(WAVE_RGB) : [];
+        waves = cfg.waves ? buildWaves(cfg.waveBaseline) : [];
         bound = cfg.waves ? buildBound(waves.length, cfg.density, rng) : [];
         boundTarget = bound.length;
     }
@@ -381,7 +515,7 @@ export function createField(canvas, opts = {}) {
         // programmatic bodies (addBody) aren't discoverable by the scan — carry them across the rebuild.
         if (programmaticBodies.length > 0)
             bodies = bodies.concat(programmaticBodies);
-        measureBodies(bodies, W, H);
+        measureBodies(bodies, W, H, originX, originY);
         bindEngagement();
         // Reconcile movers: carry forward offset + dock state for elements that persist across
         // rescans (shadow-DOM re-register, Astro nav re-mounts, explicit rescan()). An element that
@@ -418,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) {
@@ -536,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 }));
@@ -566,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) {
@@ -588,7 +823,7 @@ export function createField(canvas, opts = {}) {
         // self-laying-out repulsion (Concept 3) sees where everything actually sits this frame.
         const centers = movers.map((mv) => {
             const r = mv.el.getBoundingClientRect();
-            return { x: r.left + r.width / 2, y: r.top + r.height / 2 };
+            return { x: r.left - originX + r.width / 2, y: r.top - originY + r.height / 2 }; // container-local (#540)
         });
         for (let i = 0; i < movers.length; i++) {
             const mv = movers[i];
@@ -644,8 +879,9 @@ export function createField(canvas, opts = {}) {
             // Concept 3 — self-laying-out: this element pushes off the others and drifts off
             // dense field regions, so a cluster spreads and re-settles (e.g. on resize).
             if (mv.layout) {
-                const others = centers.filter((_, j) => j !== i);
-                const rep = repelForce({ x: cx, y: cy }, others);
+                // #530: pass the shared centers + this index instead of allocating `centers.filter(j !== i)`
+                // every frame per mover (was O(movers²) arrays/frame on a self-laying-out cluster).
+                const rep = repelForce({ x: cx, y: cy }, centers, i);
                 const press = densityPush((sx, sy) => store.near(sx, sy, 40).length, cx, cy, 16, 6);
                 fx += rep.x + press.x;
                 fy += rep.y + press.y;
@@ -746,10 +982,10 @@ export function createField(canvas, opts = {}) {
         for (const th of threadLinks) {
             const ra = th.a.getBoundingClientRect();
             const rb = th.b.getBoundingClientRect();
-            const ax = ra.left + ra.width / 2;
-            const ay = ra.top + ra.height / 2;
-            const bx = rb.left + rb.width / 2;
-            const by = rb.top + rb.height / 2;
+            const ax = ra.left - originX + ra.width / 2; // container-local (#540)
+            const ay = ra.top - originY + ra.height / 2;
+            const bx = rb.left - originX + rb.width / 2;
+            const by = rb.top - originY + rb.height / 2;
             const [cr, cg, cb] = th.c;
             ctx.strokeStyle = `rgba(${cr},${cg},${cb},0.22)`;
             ctx.lineWidth = 1;
@@ -772,11 +1008,17 @@ export function createField(canvas, opts = {}) {
     // Size the drawing surfaces' backing stores to the current W×H (dpr-scaled). Split out of
     // resize() so the lazy `setRender('none' → drawing)` path can run exactly this once. With no
     // context (a field created with `render: 'none'`, §13.7 / #297) it is a no-op: the canvas
+    // adaptive quality tier (#413): the QualityGovernor's 0–3 signal, applied to the engine's own
+    // levers. A tier caps the backing-store DPR (the dominant fill lever) and, at 2+, skips the heaviest
+    // ambient layer (the heatmap glow). Reversible — tier 0 restores the configured quality. Driven by
+    // `setQualityTier`; the platform runtime forwards the governor's tier.
+    let qualityTier = 0;
+    const TIER_DPR = [Infinity, 1.5, 1.25, 1]; // effective DPR ceiling per tier, capping cfg.dprCap further
     // backing store stays 0×0 while W/H — the simulation space — keep tracking the viewport.
     function sizeSurfaces(dprRaw) {
         if (!ctx)
             return;
-        const dpr = Math.min(dprRaw || 1, cfg.dprCap);
+        const dpr = Math.min(dprRaw || 1, cfg.dprCap, TIER_DPR[qualityTier] ?? Infinity);
         canvas.width = Math.floor(W * dpr);
         canvas.height = Math.floor(H * dpr);
         canvas.style.width = W + 'px';
@@ -789,6 +1031,9 @@ export function createField(canvas, opts = {}) {
         const vp = host.viewport();
         W = vp.width;
         H = vp.height;
+        originX = vp.originX ?? 0;
+        originY = vp.originY ?? 0;
+        contained = vp.originX != null || vp.originY != null;
         sizeSurfaces(vp.dpr);
         env.W = W;
         env.H = H;
@@ -807,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';
     }
@@ -1003,6 +1340,14 @@ export function createField(canvas, opts = {}) {
     function drawHeatmap() {
         if (!heatmap)
             return;
+        // Fade the ambient glow out as the page scrolls past the hero (≈ the first viewport). Unlike the
+        // earlier velocity-based suppression (which popped in/out and read as choppy), this is a smooth,
+        // MONOTONIC function of scroll POSITION — full through the top of the page, gone by ~1.15 viewports
+        // — so it never flickers; and below the hero the whole layer is skipped (the #409 at-rest upscale
+        // cost the heatmap is otherwise paying every frame for a glow you can't focus on mid-page).
+        const hmFade = H > 0 ? clamp((1.15 - lastScrollY / H) / 0.85, 0, 1) : 1;
+        if (hmFade <= 0.01)
+            return;
         const cell = heatmap.cell;
         const cols = Math.max(1, Math.ceil(W / cell));
         const rows = Math.max(1, Math.ceil(H / cell));
@@ -1023,7 +1368,7 @@ export function createField(canvas, opts = {}) {
         if (hmImg === null || frameN % 3 === 0) {
             if (hmImg === null)
                 hmImg = hmCtx.createImageData(cols, rows);
-            const acc = hexToRgb(cfg.accent);
+            const acc = curAccent; // #530: the cached live accent RGB (was hexToRgb(cfg.accent) — a per-frame parse)
             const data = hmImg.data;
             for (let r = 0; r < rows; r++) {
                 for (let c = 0; c < cols; c++) {
@@ -1039,7 +1384,9 @@ export function createField(canvas, opts = {}) {
         }
         ctx.globalCompositeOperation = 'lighter';
         ctx.imageSmoothingEnabled = true;
+        ctx.globalAlpha = hmFade; // fade with scroll position (computed above)
         ctx.drawImage(hmCanvas, 0, 0, W, H); // bilinear upscale → smooth glow
+        ctx.globalAlpha = 1;
         ctx.globalCompositeOperation = 'source-over';
     }
     function render() {
@@ -1072,8 +1419,8 @@ export function createField(canvas, opts = {}) {
         // whenever enabled. (An earlier scroll-suppression made it pop/fade out while scrolling, which
         // read as choppy; the perf intent is served instead by the compute throttle — the texel grid is
         // recomputed only every 3rd frame — so the per-frame cost is just the cached bilinear upscale.)
-        if (heatmap)
-            drawHeatmap();
+        if (heatmap && qualityTier < 2)
+            drawHeatmap(); // #413: drop the heaviest ambient layer at tier 2+
         drawBound();
         // free particles — cool centre → warm edge, blended toward accent (§20.8).
         // metaballs (a molten iso-surface skin) and streamlines (the bare force field) REPLACE
@@ -1081,10 +1428,27 @@ export function createField(canvas, opts = {}) {
         // keep it (their overlays read against the particles).
         const showMatter = cfg.render !== 'metaballs' && cfg.render !== 'streamlines';
         ctx.globalCompositeOperation = 'lighter';
-        const acc = hexToRgb(cfg.accent);
+        const acc = curAccent; // #530: the cached live accent RGB (was hexToRgb(cfg.accent) — a per-frame parse)
         const cx = W / 2;
         const cy = H * 0.4;
         const maxD = Math.hypot(Math.max(cx, W - cx), Math.max(cy, H - cy)) || 1;
+        // Tag-tint: every body carrying a colour stains the swarm toward its tint by proximity — a
+        // pervasive, render-time companion to the overlap-only `pigment` force, so a particle near a
+        // tagged body wears its tag's hue even on a sparse field. Few coloured bodies, precomputed once
+        // here; nearest-strongest wins per particle so the hues don't muddy. Reach is a touch past the
+        // force range so the colour reads before matter actually arrives.
+        // Rebuild the RGB cache only on the measure cadence (every 6th frame) or first frame — hexToRgb is
+        // the churn (#515). Positions are NOT cached: the loop below reads each body's live cx/cy.
+        if (tintCache === null || frameN % 6 === 0) {
+            tintCache = [];
+            for (const tb of bodies) {
+                if (!tb.tint)
+                    continue;
+                const reach = (tb.range || 200) * 1.4;
+                tintCache.push({ b: tb, r2: reach * reach, rgb: hexToRgb(tb.tint) });
+            }
+        }
+        const tintBodies = tintCache;
         if (showMatter)
             for (const p of store.particles) {
                 // captured matter is held in orbit by the sink — drawn dim and small (the accretion's orbital
@@ -1100,10 +1464,32 @@ export function createField(canvas, opts = {}) {
                 const d = Math.min(1, Math.hypot(p.x - cx, p.y - cy) / maxD);
                 const rs = d * d;
                 const h = p.heat;
-                particleRGBInto(_rgb, rs, h, acc);
+                particleRGBInto(_rgb, rs, h, acc, cfg.gradientCool, cfg.gradientWarm);
                 let r = _rgb[0];
                 let g = _rgb[1];
                 let b = _rgb[2];
+                if (tintBodies.length) {
+                    let bw = 0;
+                    let brgb = null;
+                    for (const tb of tintBodies) {
+                        const dx = p.x - tb.b.cx; // live position — scroll-compensated every frame (#508)
+                        const dy = p.y - tb.b.cy;
+                        const dd2 = dx * dx + dy * dy;
+                        if (dd2 >= tb.r2)
+                            continue;
+                        const w = 1 - Math.sqrt(dd2 / tb.r2); // linear falloff, 1 at centre → 0 at reach
+                        if (w > bw) {
+                            bw = w;
+                            brgb = tb.rgb;
+                        }
+                    }
+                    if (brgb) {
+                        const k = bw * 0.7; // tint strength at the body centre
+                        r += (brgb[0] - r) * k;
+                        g += (brgb[1] - g) * k;
+                        b += (brgb[2] - b) * k;
+                    }
+                }
                 if (p.color) {
                     // carried pigment (§20.8): a stained particle reads mostly as its own tint.
                     const [pr, pg, pb] = hexToRgb(p.color);
@@ -1139,7 +1525,7 @@ export function createField(canvas, opts = {}) {
         ctx.globalCompositeOperation = 'source-over';
         if (cfg.render === 'links') {
             ctx.globalCompositeOperation = 'lighter';
-            const acc = hexToRgb(cfg.accent);
+            const acc = curAccent; // #530: the cached live accent RGB (was hexToRgb(cfg.accent) — a per-frame parse)
             const R = 90;
             ctx.lineWidth = 0.6;
             for (const p of store.particles) {
@@ -1179,7 +1565,7 @@ export function createField(canvas, opts = {}) {
                     continue;
                 splatDensity(mball, cols, rows, STEP, p.x, p.y, RAD, 1);
             }
-            const acc = hexToRgb(cfg.accent);
+            const acc = curAccent; // #530: the cached live accent RGB (was hexToRgb(cfg.accent) — a per-frame parse)
             ctx.globalCompositeOperation = 'lighter';
             ctx.strokeStyle = `rgba(${acc[0]},${acc[1]},${acc[2]},${0.5 * boot})`;
             ctx.lineWidth = 1.4;
@@ -1233,7 +1619,7 @@ export function createField(canvas, opts = {}) {
                     vor[gy * cols + gx] = owner;
                 }
             }
-            const acc = hexToRgb(cfg.accent);
+            const acc = curAccent; // #530: the cached live accent RGB (was hexToRgb(cfg.accent) — a per-frame parse)
             ctx.globalCompositeOperation = 'lighter';
             ctx.strokeStyle = `rgba(${acc[0]},${acc[1]},${acc[2]},${0.32 * boot})`;
             ctx.lineWidth = 1;
@@ -1251,7 +1637,7 @@ export function createField(canvas, opts = {}) {
         // particles plus the flow they ride, in this one underlay canvas (no second surface, no blend).
         if (cfg.render === 'streamlines' || cfg.render === 'flow') {
             const GRID = 46;
-            const acc = hexToRgb(cfg.accent);
+            const acc = curAccent; // #530: the cached live accent RGB (was hexToRgb(cfg.accent) — a per-frame parse)
             ctx.lineWidth = 1;
             ctx.lineCap = 'round';
             // RESAMPLE the field on a cadence, not every frame. The arrows trace the body-induced force
@@ -1343,41 +1729,51 @@ export function createField(canvas, opts = {}) {
     // unused by the current dispatch (both arrow modes read the felt field).
     function drawOverlayArrows(out, structure, absolute) {
         const GRID = 44;
-        const acc = hexToRgb(cfg.accent);
-        const samples = [];
-        let frameMax = 0;
-        for (let gx = GRID / 2; gx < W; gx += GRID) {
-            for (let gy = GRID / 2; gy < H; gy += GRID) {
-                let { fx, fy } = forceAt(bodies, reg.forces, env, gx, gy);
-                if (flow) {
-                    const b = flowBiasInto(_flowB, gx, gy, flow, 0.04);
-                    fx += b.x;
-                    fy += b.y;
+        const acc = curAccent; // #530: the cached live accent RGB (was hexToRgb(cfg.accent) — a per-frame parse)
+        // RESAMPLE the field on a cadence, not every frame (mirrors the underlay slSamples cache, #406).
+        // The overlay grid is the same body-induced force field — it only shifts on the measure cadence
+        // (every 6th frame) or while a flow focus animates — so a per-frame regrid (≈grid×bodies force
+        // evals) was the same wasted work the underlay shed, surfacing as scroll jank when a Field-
+        // Surfaces reading is live. Resample every 3rd frame (or empty cache / live flow); the EMA scale
+        // updates with it. DRAW from the cache every frame below, so the arrows never flicker or step.
+        if (olSamples === null || flow || frameN % 3 === 0) {
+            const samples = [];
+            let frameMax = 0;
+            for (let gx = GRID / 2; gx < W; gx += GRID) {
+                for (let gy = GRID / 2; gy < H; gy += GRID) {
+                    let { fx, fy } = forceAt(bodies, reg.forces, env, gx, gy);
+                    if (flow) {
+                        const b = flowBiasInto(_flowB, gx, gy, flow, 0.04);
+                        fx += b.x;
+                        fy += b.y;
+                    }
+                    const mag = Math.hypot(fx, fy);
+                    if (!(mag > 1e-9))
+                        continue; // skip dead zones / NaN
+                    samples.push({ gx, gy, ux: fx / mag, uy: fy / mag, mag });
+                    if (mag > frameMax)
+                        frameMax = mag;
                 }
-                const mag = Math.hypot(fx, fy);
-                if (!(mag > 1e-9))
-                    continue; // skip dead zones / NaN
-                samples.push({ gx, gy, ux: fx / mag, uy: fy / mag, mag });
-                if (mag > frameMax)
-                    frameMax = mag;
             }
+            // Same EMA approach as the underlay streamlines (see slMaxSmoothed) — independent state so
+            // the overlay scale never couples to the underlay's field strength. Updated with the resample.
+            if (olMaxSmoothed === 0)
+                olMaxSmoothed = frameMax;
+            else
+                olMaxSmoothed = frameMax > olMaxSmoothed
+                    ? olMaxSmoothed * 0.7 + frameMax * 0.3 // track rises promptly
+                    : olMaxSmoothed * 0.9 + frameMax * 0.1; // decay slowly so quiet frames don't flash
+            olSamples = samples;
         }
-        // Same EMA approach as the underlay streamlines (see slMaxSmoothed) — independent state so
-        // the overlay scale never couples to the underlay's field strength.
-        if (olMaxSmoothed === 0)
-            olMaxSmoothed = frameMax;
-        else
-            olMaxSmoothed = frameMax > olMaxSmoothed
-                ? olMaxSmoothed * 0.7 + frameMax * 0.3 // track rises promptly
-                : olMaxSmoothed * 0.9 + frameMax * 0.1; // decay slowly so quiet frames don't flash
         if (olMaxSmoothed <= 0)
             return;
         // one backend call per arrow: shaft + two head strokes packed as three segments. Alpha varies
         // per arrow (it encodes magnitude), so arrows can't share one batch without quantizing — the
-        // call count matches the previous per-arrow beginPath/stroke exactly.
+        // call count matches the previous per-arrow beginPath/stroke exactly. `acc` is read every frame
+        // (outside the resample) so a live setAccent recolors the cached arrows immediately.
         const stroke = { r: acc[0], g: acc[1], b: acc[2], alpha: 0, width: 1.2 };
         const seg = new Float64Array(12);
-        for (const s of samples) {
+        for (const s of olSamples) {
             const rel = absolute ? clamp(s.mag / olMaxSmoothed, 0, 1) : Math.sqrt(s.mag / olMaxSmoothed);
             const len = GRID * 0.5 * (0.25 + 0.75 * rel);
             const ex = s.gx + s.ux * len;
@@ -1415,7 +1811,7 @@ export function createField(canvas, opts = {}) {
             bounds: { w: W, h: H },
             loopDist: 8,
         });
-        const acc = hexToRgb(cfg.accent);
+        const acc = curAccent; // #530: the cached live accent RGB (was hexToRgb(cfg.accent) — a per-frame parse)
         // one polyline per traced curve through the backend seam (#373) — same shared stroke style.
         const stroke = { r: acc[0], g: acc[1], b: acc[2], alpha: 0.42, width: 1.1 };
         for (const line of lines) {
@@ -1432,8 +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; // px displacement at the strongest sample — legible, never chaotic
+        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);
@@ -1454,25 +1854,124 @@ export function createField(canvas, opts = {}) {
                 }
             }
         }
-        const acc = hexToRgb(cfg.accent);
-        const stroke = { r: acc[0], g: acc[1], b: acc[2], alpha: 0.16, width: 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];
+        };
+        // 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;
         };
-        const row = [];
+        // 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
@@ -1506,7 +2005,7 @@ export function createField(canvas, opts = {}) {
                 max = oscalar[i];
         if (max <= 0)
             return;
-        const acc = hexToRgb(cfg.accent);
+        const acc = curAccent; // #530: the cached live accent RGB (was hexToRgb(cfg.accent) — a per-frame parse)
         const LEVELS = [0.25, 0.5, 0.78]; // nested iso-rings: faint outer shell → bright core
         const packed = [];
         for (let li = 0; li < LEVELS.length; li++) {
@@ -1544,7 +2043,7 @@ export function createField(canvas, opts = {}) {
         const SEED = 104; // seed lattice spacing (px)
         const STEPPX = 9; // integration step (px)
         const STEPS = 24; // max steps per path
-        const acc = hexToRgb(cfg.accent);
+        const acc = curAccent; // #530: the cached live accent RGB (was hexToRgb(cfg.accent) — a per-frame parse)
         const stroke = { r: acc[0], g: acc[1], b: acc[2], alpha: 0, width: 1.1 };
         const seg = new Float64Array(4);
         for (let sx = SEED / 2; sx < W; sx += SEED) {
@@ -1582,7 +2081,7 @@ export function createField(canvas, opts = {}) {
     // (§8, the same number the platform mirrors to `--d`) printed beside the body. Feedback bodies
     // lead (they asked to be measured); non-feedback bodies are skipped — no reading, no chip.
     function drawOverlayData(out) {
-        const acc = hexToRgb(cfg.accent);
+        const acc = curAccent; // #530: the cached live accent RGB (was hexToRgb(cfg.accent) — a per-frame parse)
         for (const b of bodies) {
             if (!b.vis || !b.feedback)
                 continue;
@@ -1614,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) {
@@ -1634,20 +2137,48 @@ export function createField(canvas, opts = {}) {
         if (boot < 1)
             boot = Math.min(1, boot + 0.012);
         easeFormation(env.form, formTarget, 0.03); // glide between formations (§7)
+        // a contained field re-reads its origin each frame (the container's viewport position shifts as the
+        // page scrolls); cheap — one getBoundingClientRect for the container, only when contained.
+        if (contained) {
+            const vp = host.viewport();
+            originX = vp.originX ?? 0;
+            originY = vp.originY ?? 0;
+        }
         const scrollY = host.scrollY();
+        const dScroll = scrollY - lastScrollY;
         // eased page-scroll speed for the `scrolling` data-when gate (§5).
-        env.scrollV = (env.scrollV ?? 0) * 0.7 + Math.abs(scrollY - lastScrollY) * 0.3;
+        env.scrollV = (env.scrollV ?? 0) * 0.7 + Math.abs(dScroll) * 0.3;
         lastScrollY = scrollY;
+        // Scroll-compensate the cached body centres between the every-6th-frame re-measures. The page
+        // scrolls continuously under the fixed field, so each body's viewport position shifts every frame
+        // even though getBoundingClientRect only runs on the measure cadence — without this the attractors
+        // snap in 6-frame steps during scroll and the swarm reads as "pausing". Cheap and drift-free: the
+        // elements don't move in the document between measures, so the only delta is scroll, and
+        // measureBodies refreshes from the real rects on its own cadence. cy carries the shaped box too
+        // (it is centred on cy ± hh). Window fields only: a contained field's local positions are
+        // scroll-invariant (container + contents move together), so this shift would corrupt them (#540).
+        if (dScroll !== 0 && !contained)
+            for (const b of bodies)
+                b.cy -= dScroll;
         for (const w of waves) {
             const target = scrollY * (0.025 + w.depth * 0.08); // wave parallax (§24)
             w.offsetY += (target - w.offsetY) * 0.04;
         }
         if (bodies.length && frameN % 6 === 0) {
-            measureBodies(bodies, W, H);
+            measureBodies(bodies, W, H, originX, originY);
+            detectProximityEvents(bodies); // #441 enter/exit/met — on the measure cadence, lazy
             // attention-gated discharge (#365): an engagement-gated sink releases on the falling
             // 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;
@@ -1691,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) {
@@ -1715,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
@@ -1812,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)
@@ -1880,6 +2440,14 @@ export function createField(canvas, opts = {}) {
             if (ctx)
                 sizeSurfaces(host.viewport().dpr); // re-size the backing store to the new ceiling now
         },
+        setQualityTier: (tier) => {
+            const next = Math.max(0, Math.min(3, Math.floor(tier || 0)));
+            if (next === qualityTier)
+                return;
+            qualityTier = next;
+            if (ctx)
+                sizeSurfaces(host.viewport().dpr); // re-apply the tier's effective DPR ceiling now
+        },
         threads: setThreads,
         burst: (x, y, hex) => {
             // discrete one-shot: shove + heat nearby matter, optionally tint it (§11).
@@ -1985,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;
@@ -2044,8 +2640,8 @@ export function createField(canvas, opts = {}) {
             body.onFeedback = (ch) => { Object.assign(channels, ch); spec.onFeedback?.(ch); };
             programmaticBodies.push(body);
             bodies = bodies.concat(body); // live this frame, before the next scan re-merges it
-            measureBodies([body], W, H); // init cx/cy so the first sample/force is correct
-            return {
+            measureBodies([body], W, H, originX, originY); // init cx/cy so the first sample/force is correct
+            const handle = {
                 data: spec.data,
                 get channels() { return channels; },
                 set: (params) => {
@@ -2071,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 {
@@ -2091,8 +2736,18 @@ export function createField(canvas, opts = {}) {
             const { fx, fy } = forceAt(bodies, reg.forces, env, x, y);
             return { x: fx, y: fy };
         },
-        sampleScalar: (x, y) => (heatmap ? heatmap.norm(x, y) : 0),
-        sampleGradient: (x, y) => (heatmap ? heatmap.gradient(x, y) : { x: 0, y: 0 }),
+        sampleScalar: (x, y) => {
+            if (heatmap)
+                return heatmap.norm(x, y);
+            devWarnNoOp('NOOP_NO_HEATMAP', 'sampleScalar() returned 0 because the heatmap layer is off — construct with { heatmap: true } or call setHeatmap(true).');
+            return 0;
+        },
+        sampleGradient: (x, y) => {
+            if (heatmap)
+                return heatmap.gradient(x, y);
+            devWarnNoOp('NOOP_NO_HEATMAP', 'sampleGradient() returned { x: 0, y: 0 } because the heatmap layer is off — construct with { heatmap: true } or call setHeatmap(true).');
+            return { x: 0, y: 0 };
+        },
         grid: (name) => env.grid(name),
         on: (type, cb) => {
             let set = busListeners.get(type);
@@ -2103,6 +2758,7 @@ export function createField(canvas, opts = {}) {
             set.add(cb);
             return () => void set.delete(cb);
         },
+        version: FIELD_VERSION,
         scrollV: () => env.scrollV ?? 0,
         setVisible: (on) => {
             canvasVisible = on;