@fundamental-engine/core 0.4.0 → 0.5.0

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,21 @@ 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
     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 +100,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;
@@ -132,6 +151,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 +271,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 +313,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 +331,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
@@ -519,10 +544,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 +678,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')
@@ -1008,11 +1056,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 +1088,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 +1107,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})`;
+                // 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) * (2 + h * 1.6), 0, 6.28318);
+                ctx.arc(p.x, p.y, size + 1.2, 0, 6.28318);
                 ctx.fill();
-                ctx.fillStyle = `rgba(${col},${0.16 * alpha})`;
+                ctx.fillStyle = `rgba(${cr},${cg},${cb},${alpha})`;
                 ctx.beginPath();
-                ctx.arc(p.x, p.y, size * 1.25 + 0.6, 0, 6.28318);
-                ctx.fill();
-                ctx.fillStyle = `rgba(${col},${0.55 * 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 +1259,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 +1338,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 +1542,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 +1608,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 +1674,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 +1752,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,
@@ -1764,7 +1826,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) {
@@ -1877,23 +1939,65 @@ 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 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 n;
+            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) };
         },
         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;