@fundamental-engine/core 0.4.0 → 0.5.1

package/dist/core/field.js

@@ -24,7 +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 { clamp, hexToRgb, particleRGB, rgbToHex, sampleStops } from "./math.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";
@@ -44,10 +44,16 @@ import { canvas2dBackend } from "./render-backend.js";
 import { forceAt, netField } from "./streamlines.js";
 import { traceFieldLines } from "./fieldlines.js";
 import { fieldLineSeeds } from "./fieldline-seeds.js";
-import { flowBias, makeFlowFocus } from "./flow.js";
+import { flowBiasInto, makeFlowFocus } from "./flow.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
+// scratch before the next write (no overlapping lifetimes, no cross-instance interleaving).
+const _flowB = { x: 0, y: 0 };
+const _rgb = [0, 0, 0];
 export function createField(canvas, opts = {}) {
     // Signals-only mode (`render: 'none'`, §13.7 / #297): the full simulation + feedback pipeline
     // runs, but the engine never acquires a 2d context, never sizes a canvas backing store (it stays
@@ -59,7 +65,7 @@ export function createField(canvas, opts = {}) {
     if ((opts.render ?? 'dots') !== 'none') {
         ctx = canvas.getContext('2d');
         if (!ctx)
-            throw new Error('field-ui: 2D canvas context unavailable');
+            throw new Error('Fundamental: 2D canvas context unavailable');
     }
     // Field Surfaces: the optional OVERLAY surface, drawn in front of page content. Core only draws to
     // it (the caller owns the element + its fixed/pointer-events placement); its backing store is sized
@@ -72,8 +78,23 @@ export function createField(canvas, opts = {}) {
     // overlay's own 2d context.
     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 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
+    // host reacts to (a sink caught/released matter, the swarm settled) — no DOM, no polling. Cheap
+    // 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) {
+        const set = busListeners.get(type);
+        if (set)
+            for (const cb of set)
+                cb(payload);
+    }
+    const sinkPeak = new WeakMap(); // matter held at the rising edge, for the release count
+    const programmaticBodies = []; // bodies added via addBody(); merged into `bodies` each scan
+    const fieldChannels = new Map(); // addField() input channels
     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
@@ -81,7 +102,7 @@ export function createField(canvas, opts = {}) {
     // In the browser, pass `browserHost()` from @fundamental-engine/platform (or use createBrowserField); the
     // @fundamental-engine/{elements,react,vanilla} entry points wire it for you.
     if (!opts.host) {
-        throw new Error('field-ui: createField requires opts.host. Use @fundamental-engine/vanilla (createField/mountField) or ' +
+        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.');
     }
     const host = opts.host;
@@ -98,6 +119,8 @@ 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
+        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
         // to the 2D engine; > 0 opens a shallow depth the matter drifts through, opt-in.
         depth: opts.depth && opts.depth > 0 ? opts.depth : 0,
@@ -132,6 +155,7 @@ export function createField(canvas, opts = {}) {
     const rng = opts.rng ?? Math.random;
     const wallNow = opts.now ?? (() => performance.now());
     let boot = reduceMotion ? 1 : 0;
+    let lastNow = NaN; // previous frame timestamp — drives the frame-rate-independent dt (#434)
     let mball = null; // scratch density grid for the metaballs render mode
     let vor = null; // scratch owner grid for the voronoi render mode
     // EMA (exponential moving average) of the per-frame peak magnitude for each arrow renderer.
@@ -251,6 +275,9 @@ export function createField(canvas, opts = {}) {
             if (b.el.dataset.fxCap === '1') {
                 b.el.dataset.fxCap = '0';
                 fireCaptureEvent(b.el, 'released', { accreted: 0, load: 0 });
+                if (busHas('release'))
+                    busEmit('release', { body: b, count: released.length });
+                sinkPeak.delete(b);
             }
         },
         // class-[S] sources emit through here, capped by a hard pool ceiling (the
@@ -290,6 +317,7 @@ export function createField(canvas, opts = {}) {
     function newParticle(seed = {}) {
         const size = seed.size ?? 0.7 + rng() * 1.8;
         return {
+            id: seed.id ?? nextParticleId++,
             x: seed.x ?? rng() * W,
             y: seed.y ?? rng() * H,
             vx: seed.vx ?? (rng() - 0.5) * 0.25,
@@ -307,6 +335,7 @@ export function createField(canvas, opts = {}) {
             cap: null,
             ...(seed.age != null ? { age: seed.age } : {}), // mortal matter (a [S] source)
             ...(seed.color != null ? { color: seed.color } : {}),
+            ...(seed.species != null ? { species: seed.species } : {}), // matter tagging (#444)
         };
     }
     // optional per-particle data records (FieldHandle.seed) — round-robined onto the base pool, with
@@ -347,6 +376,9 @@ export function createField(canvas, opts = {}) {
         else {
             bodies = scanned;
         }
+        // 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);
         bindEngagement();
         // Reconcile movers: carry forward offset + dock state for elements that persist across
@@ -519,10 +551,16 @@ export function createField(canvas, opts = {}) {
             if (edge.fire === 'captured') {
                 b.el.dataset.fxCap = '1';
                 fireCaptureEvent(b.el, 'captured', { accreted: b.accreted, load: sinkLoad(b) });
+                if (busHas('absorb'))
+                    busEmit('absorb', { body: b, count: b.accreted });
+                sinkPeak.set(b, b.accreted);
             }
             else if (edge.fire === 'released') {
                 b.el.dataset.fxCap = '0';
                 fireCaptureEvent(b.el, 'released', { accreted: 0, load: 0 });
+                if (busHas('release'))
+                    busEmit('release', { body: b, count: sinkPeak.get(b) ?? 0 });
+                sinkPeak.delete(b);
             }
         }
     }
@@ -647,6 +685,23 @@ export function createField(canvas, opts = {}) {
     // engagement: hover/focus a [data-hot] element → it activates (b.on, lighting
     // the spine + on-state forces) and overrides the accent with its data-color (§9).
     function bindEngagement() {
+        // Reconcile across rescans (mirrors the emitter prune above): a persistent field outlives the
+        // [data-hot] elements swapped under it (Astro nav, dynamic content), so drop engagements whose
+        // element has left the DOM — release their listeners + the strong ref the `engaged` array holds,
+        // so a long-lived field can't accumulate detached nodes. New elements are bound below; the
+        // `fxEngaged` guard keeps live ones from double-binding.
+        if (engaged.length) {
+            engaged = engaged.filter((e) => {
+                if (e.el.isConnected)
+                    return true;
+                e.el.removeEventListener('pointerenter', e.enter);
+                e.el.removeEventListener('pointerleave', e.leave);
+                e.el.removeEventListener('focus', e.enter);
+                e.el.removeEventListener('blur', e.leave);
+                delete e.el.dataset.fxEngaged;
+                return false;
+            });
+        }
         host.root.querySelectorAll('[data-hot]').forEach((node) => {
             const el = node;
             if (el.dataset.fxEngaged === '1')
@@ -719,7 +774,7 @@ export function createField(canvas, opts = {}) {
     function sizeSurfaces(dprRaw) {
         if (!ctx)
             return;
-        const dpr = Math.min(dprRaw || 1, 2);
+        const dpr = Math.min(dprRaw || 1, cfg.dprCap);
         canvas.width = Math.floor(W * dpr);
         canvas.height = Math.floor(H * dpr);
         canvas.style.width = W + 'px';
@@ -894,14 +949,17 @@ export function createField(canvas, opts = {}) {
             // (feedback-sink.ts), which performs the same direct writes the engine always made:
             // `--d`/`--field-density`, `--field-heatmap-density`, `--load`/`--mass`,
             // plus the measured `--entropy`/`--coherence`/`--temperature`.
-            cfg.feedbackSink(writeEl, {
+            const channels = {
                 density: b.d,
                 heatmapDensity,
                 load,
                 entropy: m.entropy,
                 coherence: m.coherence,
                 temperature: m.temperature,
-            });
+            };
+            cfg.feedbackSink(writeEl, channels);
+            // per-body feedback (addBody): demux this body's channels to its own callback.
+            b.onFeedback?.(channels);
         }
     }
     function drawSparks() {
@@ -1008,11 +1066,11 @@ export function createField(canvas, opts = {}) {
             ctx.fillRect(0, 0, W, H);
         }
         drawWaves();
-        // The heatmap is a full-viewport bilinear-upscale glow — the heaviest per-frame layer. It's
-        // ambient density you read at rest, not detail you track mid-scroll, so suppress it while the
-        // page is scrolling fast (eased env.scrollV). Scrolling never pays the heatmap's fill cost; the
-        // glow returns the moment the page settles. (Body charge/glow is CSS --load, unaffected.)
-        if (heatmap && (env.scrollV ?? 0) < 6)
+        // The heatmap is a continuous ambient layer — NOT coupled to scroll. It draws every frame
+        // 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();
         drawBound();
         // free particles — cool centre → warm edge, blended toward accent (§20.8).
@@ -1040,7 +1098,10 @@ 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;
-                let [r, g, b] = particleRGB(rs, h, acc);
+                particleRGBInto(_rgb, rs, h, acc);
+                let r = _rgb[0];
+                let g = _rgb[1];
+                let b = _rgb[2];
                 if (p.color) {
                     // carried pigment (§20.8): a stained particle reads mostly as its own tint.
                     const [pr, pg, pb] = hexToRgb(p.color);
@@ -1056,23 +1117,19 @@ export function createField(canvas, opts = {}) {
                 const cr = r | 0;
                 const cg = g | 0;
                 const cb = b | 0;
-                // Soft additive glow, not a solid disc. Three concentric discs — a wide faint aura, a mid
-                // body, a small bright core — sum under the 'lighter' composite into a smooth radial falloff,
-                // so the particle reads as LIGHT rather than a hard filled circle. Cheap (a few small arcs,
-                // no per-particle gradient or shadowBlur — the costs §20.8 deliberately avoids), and it keeps
-                // the per-particle tint. Hotter matter glows wider.
-                const col = `${cr},${cg},${cb}`;
-                ctx.fillStyle = `rgba(${col},${(0.05 + 0.08 * h) * boot * zk})`;
-                ctx.beginPath();
-                ctx.arc(p.x, p.y, (size + 1) * (2 + h * 1.6), 0, 6.28318);
-                ctx.fill();
-                ctx.fillStyle = `rgba(${col},${0.16 * alpha})`;
+                // A single tight, faint bloom under the crisp core (additive, 'lighter' composite) — just
+                // enough to soften the point into a star. NOT the old wide, heat-scaled halo (`size+3+6*h`):
+                // near an accretion sink every particle heats to h≈1, so that halo bloomed the whole cluster
+                // into big overlapping rings (the repeatedly-flagged "glow" — #434 follow-up). Heat now reads
+                // only through the brighter, slightly larger core (the `+ h*2` size and `+ h*0.5` alpha above),
+                // never a growing aura. Radius is fixed (size + ~1px), so points stay crisp at any heat.
+                ctx.fillStyle = `rgba(${cr},${cg},${cb},${0.12 * alpha})`;
                 ctx.beginPath();
-                ctx.arc(p.x, p.y, size * 1.25 + 0.6, 0, 6.28318);
+                ctx.arc(p.x, p.y, size + 1.2, 0, 6.28318);
                 ctx.fill();
-                ctx.fillStyle = `rgba(${col},${0.55 * alpha})`;
+                ctx.fillStyle = `rgba(${cr},${cg},${cb},${alpha})`;
                 ctx.beginPath();
-                ctx.arc(p.x, p.y, Math.max(0.4, size * 0.55), 0, 6.28318);
+                ctx.arc(p.x, p.y, size, 0, 6.28318);
                 ctx.fill();
             }
         drawSparks();
@@ -1212,7 +1269,7 @@ export function createField(canvas, opts = {}) {
                         let { fx, fy } = forceAt(bodies, reg.forces, env, gx, gy);
                         // a live flow focus bends the rendered field lines toward the target (field.flowTo).
                         if (flow) {
-                            const b = flowBias(gx, gy, flow, 0.04);
+                            const b = flowBiasInto(_flowB, gx, gy, flow, 0.04);
                             fx += b.x;
                             fy += b.y;
                         }
@@ -1291,7 +1348,7 @@ export function createField(canvas, opts = {}) {
             for (let gy = GRID / 2; gy < H; gy += GRID) {
                 let { fx, fy } = forceAt(bodies, reg.forces, env, gx, gy);
                 if (flow) {
-                    const b = flowBias(gx, gy, flow, 0.04);
+                    const b = flowBiasInto(_flowB, gx, gy, flow, 0.04);
                     fx += b.x;
                     fy += b.y;
                 }
@@ -1495,7 +1552,7 @@ export function createField(canvas, opts = {}) {
                 for (let i = 0; i < STEPS; i++) {
                     let { fx, fy } = forceAt(bodies, reg.forces, env, x, y);
                     if (flow) {
-                        const b = flowBias(x, y, flow, 0.04);
+                        const b = flowBiasInto(_flowB, x, y, flow, 0.04);
                         fx += b.x;
                         fy += b.y;
                     }
@@ -1561,7 +1618,17 @@ export function createField(canvas, opts = {}) {
         frameN++;
         env.t = (now - t0) / 1000;
         env.frameN = frameN;
-        env.dt = reduceMotion ? 0 : 1;
+        // Frame-rate-independent timestep (#434): dt is the real frame interval normalized to a
+        // 60fps baseline (≈1 at 60fps, ≈0.5 at 120fps, ≈2 at 30fps), clamped so a long stall
+        // (tab switch, GC pause) can't teleport matter. Previously dt was a flat 1 regardless of
+        // FPS, so when the perf work lifted the homepage to 60–120fps the same per-frame physics
+        // ran 2–4× faster on screen. Position alone is dt-scaled (forces/friction are per-frame by
+        // design, §applyForce) — that's enough to make displacement-per-second FPS-independent.
+        // Still 0 under reduce-motion: the integrator and the `if (env.dt)` gates read it as the
+        // "is the field animating" flag, so it must stay falsy when still and >0 when moving.
+        const dtRaw = Number.isFinite(lastNow) ? (now - lastNow) / 16.6667 : 1;
+        lastNow = now;
+        env.dt = reduceMotion ? 0 : clamp(dtRaw, 0.2, 2);
         if (boot < 1)
             boot = Math.min(1, boot + 0.012);
         easeFormation(env.form, formTarget, 0.03); // glide between formations (§7)
@@ -1617,7 +1684,7 @@ export function createField(canvas, opts = {}) {
             for (const p of store.particles) {
                 if (p.cap)
                     continue;
-                const b = flowBias(p.x, p.y, flow, 0.6);
+                const b = flowBiasInto(_flowB, p.x, p.y, flow, 0.6);
                 p.vx += b.x;
                 p.vy += b.y;
             }
@@ -1695,6 +1762,11 @@ export function createField(canvas, opts = {}) {
             setFormation('ambient');
         }
     }, 1200);
+    // Never let this ambient idle-detection timer pin the host alive on its own: Node keeps the
+    // process running while an un-unref'd interval is pending (browsers ignore unref). destroy()
+    // still clears it for prompt teardown — this just guarantees a field that outlives its destroy()
+    // (e.g. a headless test that forgets to tear down) can't hang process exit.
+    idleTimer.unref?.();
     const onResize = () => resize();
     resize();
     // pause all work while the tab is backgrounded — stop the loop and the idle timer,
@@ -1720,7 +1792,7 @@ export function createField(canvas, opts = {}) {
     teardowns.push(host.onBodyEvent(UPDATE_BODY, onUpdateBody));
     onScroll();
     raf = host.raf(frame);
-    return {
+    const handle = {
         scan,
         rescan: scan,
         setAccent: (hex) => {
@@ -1764,7 +1836,7 @@ export function createField(canvas, opts = {}) {
                 if (!ctx) {
                     // context acquisition can genuinely fail (lost GPU process, too many contexts) —
                     // warn and stay signals-only rather than crash the live simulation.
-                    console.warn(`field-ui: setRender('${mode}') could not acquire a 2d context; staying in render 'none'`);
+                    console.warn(`Fundamental: setRender('${mode}') could not acquire a 2d context; staying in render 'none'`);
                     return;
                 }
                 if (overlayCanvas && !overlayCtx) {
@@ -1801,6 +1873,11 @@ export function createField(canvas, opts = {}) {
                 }
             }
         },
+        setDprCap: (cap) => {
+            cfg.dprCap = cap > 0 ? cap : 2;
+            if (ctx)
+                sizeSurfaces(host.viewport().dpr); // re-size the backing store to the new ceiling now
+        },
         threads: setThreads,
         burst: (x, y, hex) => {
             // discrete one-shot: shove + heat nearby matter, optionally tint it (§11).
@@ -1877,23 +1954,153 @@ export function createField(canvas, opts = {}) {
         particleCount: () => store.size,
         readParticles: (out) => {
             const ps = store.particles;
-            const n = Math.min(store.size, Math.floor(out.length / 5)); // stride 5
-            for (let i = 0; i < n; i++) {
+            const capN = Math.floor(out.length / 5); // stride 5
+            let w = 0;
+            for (let i = 0; i < ps.length && w < capN; i++) {
                 const p = ps[i];
-                const o = i * 5;
+                if (p.report !== undefined)
+                    continue; // agents draw as their own object, not a swarm dot
+                const o = w * 5;
                 out[o] = p.x;
                 out[o + 1] = p.y;
                 out[o + 2] = p.z ?? 0; // optional z lane (z-axis.md); 0 in a flat field
                 out[o + 3] = p.heat;
                 out[o + 4] = p.size;
+                w++;
             }
-            return n;
+            return w;
+        },
+        readParticleIds: (out) => {
+            // parallel to readParticles (same pool order, same agent skip), so out[i] is the stable id of
+            // the particle written at stride offset i*5 there — the host maps id → its own opaque payload.
+            const ps = store.particles;
+            let w = 0;
+            for (let i = 0; i < ps.length && w < out.length; i++) {
+                const p = ps[i];
+                if (p.report !== undefined)
+                    continue; // agents excluded, exactly like readParticles
+                out[w++] = p.id ?? 0;
+            }
+            return w;
+        },
+        addAgent: (spec) => {
+            const p = newParticle({ x: spec.x, y: spec.y, z: spec.z, species: spec.species });
+            p.vx = 0;
+            p.vy = 0;
+            if (spec.z === undefined && cfg.depth <= 0)
+                p.z = 0;
+            if (spec.mass !== undefined)
+                p.m = spec.mass;
+            p.maxSpeed = spec.maxSpeed;
+            p.report = spec.report;
+            store.add(p);
+            return { particle: p, remove: () => store.remove(p) };
+        },
+        addBody: (spec) => {
+            // A programmatic body has no DOM. A minimal rect-backed element answers the body contract the
+            // measurer + reactive-param refresh read (getAttribute / dataset / getBoundingClientRect), so we
+            // reuse the exact bodyFromElement path the scan uses — no fake document, no querySelectorAll root.
+            const attrs = {
+                'data-body': Array.isArray(spec.tokens) ? spec.tokens.join(' ') : String(spec.tokens),
+            };
+            if (spec.strength != null)
+                attrs['data-strength'] = String(spec.strength);
+            if (spec.range != null)
+                attrs['data-range'] = String(spec.range);
+            if (spec.spin != null)
+                attrs['data-spin'] = String(spec.spin);
+            if (spec.angle != null)
+                attrs['data-angle'] = String(spec.angle);
+            if (spec.color != null)
+                attrs['data-color'] = spec.color;
+            const toRect = () => {
+                const r = spec.rect();
+                return {
+                    left: r.left, top: r.top, right: r.left + r.width, bottom: r.top + r.height,
+                    width: r.width, height: r.height, x: r.left, y: r.top, toJSON: () => ({}),
+                };
+            };
+            const el = {
+                tagName: 'DIV', id: '', className: '',
+                dataset: spec.color != null ? { color: spec.color } : {},
+                getAttribute: (n) => attrs[n] ?? null,
+                hasAttribute: (n) => n in attrs,
+                getBoundingClientRect: toRect,
+                dispatchEvent: () => true,
+                setAttribute: () => { },
+                removeAttribute: () => { },
+                // the feedback sink writes CSS vars here; a no-op style absorbs them (the value is delivered
+                // to onFeedback / the handle's channels, not the DOM).
+                style: { setProperty: () => { }, removeProperty: () => { }, getPropertyValue: () => '' },
+            };
+            const body = bodyFromElement(el);
+            body.rect = toRect;
+            body.data = spec.data;
+            body.feedback = true; // programmatic bodies always compute channels (the CSS write hits the
+            // harmless stub element; the value flows to onFeedback + the handle's live channels).
+            const channels = {};
+            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 {
+                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)
+                        programmaticBodies.splice(i, 1);
+                    bodies = bodies.filter((x) => x !== body);
+                },
+            };
+        },
+        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 }),
+        grid: (name) => env.grid(name),
+        on: (type, cb) => {
+            let set = busListeners.get(type);
+            if (!set) {
+                set = new Set();
+                busListeners.set(type, set);
+            }
+            set.add(cb);
+            return () => void set.delete(cb);
+        },
         scrollV: () => env.scrollV ?? 0,
         setVisible: (on) => {
             canvasVisible = on;
@@ -1939,5 +2146,6 @@ export function createField(canvas, opts = {}) {
             store.clear();
         },
     };
+    return handle;
 }
 //# sourceMappingURL=field.js.map