@fundamental-engine/core 0.6.0 → 0.8.0

package/dist/core/field.js

@@ -24,6 +24,7 @@ import { buildWaves, buildBound, waveYat, } 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";
@@ -45,9 +46,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 +63,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');
@@ -79,8 +80,6 @@ export function createField(canvas, opts = {}) {
     let overlayBackend = opts.overlayBackend ?? (overlayCanvas && overlayCtx ? canvas2dBackend(overlayCanvas, overlayCtx) : null);
     const store = new FieldStore();
     let nextParticleId = 1; // monotonic stable particle identity (readParticleIds); never reused
-    const colorMemo = new Map(); // hex → rgb, parsed once per distinct color (readParticleColors)
-    const WHITE_RGB = [255, 255, 255]; // the default tint for an uncolored particle
     const grids = new Map(); // §20.1 class [C] field buffers, lazy
     const reg = createRegistry();
     // host-agnostic discrete event bus (the read side): plain-data push for occurrences a non-DOM
@@ -95,24 +94,86 @@ export function createField(canvas, opts = {}) {
                 cb(payload);
     }
     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
+    const fieldChannels = new Map(); // addField() input channels
+    // 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)
-    registerNaturalForces(reg); // natural primitives: gravity + charge (§20.10), opt-in
-    registerExtendedForces(reg); // designed extended forces: lens, … (§20.3), opt-in
+    registerNaturalForces(reg); // 8 natural primitives: gravity, charge, magnetism, thermal, … (§20.10)
+    registerExtendedForces(reg); // 19 designed extended forces: lens, crystallize, link, morph, … (§20.3)
     // the environment seam: all DOM access goes through this injected host — core imports zero DOM.
-    // In the browser, pass `browserHost()` from @fundamental-engine/platform (or use createBrowserField); the
+    // In the browser, pass `browserHost()` from @fundamental-engine/dom (or use createBrowserField); the
     // @fundamental-engine/{elements,react,vanilla} entry points wire it for you.
     if (!opts.host) {
         throw new Error('Fundamental: createField requires opts.host. Use @fundamental-engine/vanilla (createField/mountField) or ' +
-            '@fundamental-engine/elements / @fundamental-engine/react, or pass browserHost() from @fundamental-engine/platform.');
+            '@fundamental-engine/elements / @fundamental-engine/react, or pass browserHost() from @fundamental-engine/dom.');
     }
     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
         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
@@ -120,6 +181,15 @@ export function createField(canvas, opts = {}) {
         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
@@ -134,6 +204,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;
@@ -174,6 +252,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;
@@ -361,7 +448,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;
     }
@@ -380,7 +467,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
@@ -587,7 +674,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];
@@ -643,8 +730,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;
@@ -745,10 +833,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;
@@ -771,11 +859,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';
@@ -788,6 +882,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;
@@ -1002,6 +1099,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));
@@ -1022,7 +1127,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++) {
@@ -1038,7 +1143,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() {
@@ -1071,8 +1178,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
@@ -1080,10 +1187,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
@@ -1099,10 +1223,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);
@@ -1138,7 +1284,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) {
@@ -1178,7 +1324,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;
@@ -1232,7 +1378,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;
@@ -1250,7 +1396,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
@@ -1342,41 +1488,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;
@@ -1414,7 +1570,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,7 +1588,8 @@ export function createField(canvas, opts = {}) {
     // 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 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 cols = Math.floor(W / STEP) + 2;
         const rows = Math.floor(H / STEP) + 2;
         const dx = new Float32Array(cols * rows);
@@ -1453,8 +1610,10 @@ 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 };
+        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 };
         const px = (gx, gy) => {
             const i = gy * cols + gx;
             const rel = maxMag > 0 ? Math.sqrt(mags[i] / maxMag) : 0;
@@ -1505,7 +1664,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++) {
@@ -1543,7 +1702,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) {
@@ -1581,7 +1740,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;
@@ -1633,16 +1792,36 @@ 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);
@@ -1874,20 +2053,19 @@ export function createField(canvas, opts = {}) {
                 }
             }
         },
-        setSurfaces: (plan) => {
-            // One declarative verb for the whole surface state — the plan IS the truth, so an omitted key
-            // resets to its default (matter `dots`, no readings, no accumulation). Idempotent and
-            // restorable; the three single-surface verbs remain for surgical pokes. (#385)
-            handle.setRender(plan.underlay ?? 'dots');
-            handle.setOverlay(plan.overlay ?? 'off');
-            handle.setHeatmap(plan.heatmap ?? false);
-        },
-        getSurfaces: () => ({ underlay: cfg.render, overlay: cfg.overlay, heatmap: cfg.heatmap }),
         setDprCap: (cap) => {
             cfg.dprCap = cap > 0 ? cap : 2;
             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).
@@ -1993,29 +2171,6 @@ export function createField(canvas, opts = {}) {
             }
             return w;
         },
-        readParticleColors: (out) => {
-            // parallel to readParticles (same order, same agent skip): out[i*3 .. i*3+2] is the [r,g,b]
-            // tint (0-255) of the particle at stride offset i*5 there — the pigment color (Particle.color,
-            // conserved color transport) the swarm renderer blends with heat. White when uncolored. The
-            // hex is parsed once per distinct color (memoized) to keep this zero-allocation on the hot path.
-            const ps = store.particles;
-            let w = 0;
-            for (let i = 0; i < ps.length && w * 3 + 2 < out.length; i++) {
-                const p = ps[i];
-                if (p.report !== undefined)
-                    continue;
-                let c = WHITE_RGB;
-                if (p.color) {
-                    c = colorMemo.get(p.color) ?? colorMemo.set(p.color, hexToRgb(p.color)).get(p.color);
-                }
-                const o = w * 3;
-                out[o] = c[0];
-                out[o + 1] = c[1];
-                out[o + 2] = c[2];
-                w++;
-            }
-            return w;
-        },
         addAgent: (spec) => {
             const p = newParticle({ x: spec.x, y: spec.y, z: spec.z, species: spec.species });
             p.vx = 0;
@@ -2075,10 +2230,28 @@ 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
+            measureBodies([body], W, H, originX, originY); // init cx/cy so the first sample/force is correct
             return {
                 data: spec.data,
                 get channels() { return channels; },
+                set: (params) => {
+                    // mutate the attrs the synthetic element exposes; refreshBodyParams (measure cadence) picks
+                    // up strength/range/spin/angle next frame — the same reactive path DOM + three bodies use.
+                    if (params.strength != null)
+                        attrs['data-strength'] = String(params.strength);
+                    if (params.range != null)
+                        attrs['data-range'] = String(params.range);
+                    if (params.spin != null)
+                        attrs['data-spin'] = String(params.spin);
+                    if (params.angle != null)
+                        attrs['data-angle'] = String(params.angle);
+                    // color/tint isn't on the refresh path — set it directly (the scanner reads tint once).
+                    if (params.color != null) {
+                        attrs['data-color'] = params.color;
+                        el.dataset.color = params.color;
+                        body.tint = params.color;
+                    }
+                },
                 remove: () => {
                     const i = programmaticBodies.indexOf(body);
                     if (i >= 0)
@@ -2087,13 +2260,35 @@ export function createField(canvas, opts = {}) {
                 },
             };
         },
+        addField: (name, sampler) => {
+            fieldChannels.set(name, sampler);
+            return {
+                name,
+                set: (next) => { fieldChannels.set(name, next); },
+                remove: () => { fieldChannels.delete(name); },
+            };
+        },
+        sampleField: (name, x, y) => {
+            const s = fieldChannels.get(name);
+            return s ? s(x, y) : 0;
+        },
         energy: () => energyReport(store.particles),
         sample: (x, y) => {
             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);
@@ -2104,6 +2299,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;