@fundamental-engine/core 0.9.2 → 0.9.3

package/dist/core/field.js

@@ -41,8 +41,8 @@ import { registerCoreForces } from "../forces/index.js";
 import { registerNaturalForces } from "../forces/natural.js";
 import { registerExtendedForces } from "../forces/extended.js";
 import { ScalarGridImpl } from "./scalar-grid.js";
-import { sparkCount, burstImpulse } from "./reactions.js";
-import { linkAlpha, marchingCell, splatDensity, nearestSite, voronoiWalls } from "./render-modes.js";
+import { sparkCount, burstImpulse, BURST_RADIUS } from "./reactions.js";
+import { linkAlpha, marchingCell, splatDensity, nearestSite, voronoiWalls, knockoutHoleRadius, radialVelocity, dopplerShift, wellWeight, redshiftShift, redshiftRGBInto, blackbodyT, blackbodyRGBInto, depthScale, depthProject, depthAlpha, depthBlurRadius, } from "./render-modes.js";
 import { canvas2dBackend } from "./render-backend.js";
 import { forceAt, netField } from "./streamlines.js";
 import { traceFieldLines } from "./fieldlines.js";
@@ -61,6 +61,94 @@ import { applyLens } from "./query-lens.js";
 // scratch before the next write (no overlapping lifetimes, no cross-instance interleaving).
 const _flowB = { x: 0, y: 0 };
 const _rgb = [0, 0, 0];
+/** Deep-copy a {@link FieldPolicy} (shallow is unsafe — `budgets` is nested). `undefined` → `{}` (the
+ *  unbounded default). Used on set + read so callers can neither mutate the field's live policy nor
+ *  observe later mutations of the object they passed in. */
+function clonePolicy(p) {
+    if (!p)
+        return {};
+    const out = {};
+    if (p.allowBodyDataInSnapshots != null)
+        out.allowBodyDataInSnapshots = p.allowBodyDataInSnapshots;
+    if (p.allowMotionProjection != null)
+        out.allowMotionProjection = p.allowMotionProjection;
+    if (p.maxMotionBudget != null)
+        out.maxMotionBudget = p.maxMotionBudget;
+    if (p.budgets)
+        out.budgets = { ...p.budgets };
+    return out;
+}
+/**
+ * Resolve {@link FieldSnapshotOptions} — an optional {@link SnapshotProfile} composed with the explicit
+ * `include*` flags — to concrete inclusion, TIGHTEST-wins. A profile establishes a baseline; an explicit
+ * flag may tighten it further but never widen it (an explicit `true` cannot re-enable what the profile
+ * turned off). `includeData` additionally passes through the policy gate at the call site (this only
+ * governs whether the CALLER asked for it). Relationships default true when nothing narrows them.
+ */
+function resolveSnapshotInclusion(opts) {
+    // Per-profile baselines. `debug` = everything; `agent` = structure + attribution, no opaque data;
+    // `bug-report` = structural + versions, no data; `public` = ids + shape only.
+    const base = {
+        debug: { includeParticles: true, includeRelationships: true, includeData: true, includeInfluences: true },
+        agent: { includeParticles: false, includeRelationships: true, includeData: false, includeInfluences: true },
+        'bug-report': { includeParticles: false, includeRelationships: true, includeData: false, includeInfluences: true },
+        public: { includeParticles: false, includeRelationships: false, includeData: false, includeInfluences: false },
+    };
+    const p = opts.profile;
+    if (!p) {
+        // No profile: today's defaults — relationships default true, the rest default false.
+        return {
+            includeParticles: opts.includeParticles === true,
+            includeRelationships: opts.includeRelationships !== false,
+            includeData: opts.includeData === true,
+            includeInfluences: opts.includeInfluences === true,
+        };
+    }
+    const b = base[p];
+    // TIGHTEST wins: a flag is on only if the profile allows it AND the caller didn't explicitly turn it
+    // off. An explicit `true` can never widen past the profile's baseline.
+    return {
+        includeParticles: b.includeParticles && opts.includeParticles !== false,
+        includeRelationships: b.includeRelationships && opts.includeRelationships !== false,
+        includeData: b.includeData && opts.includeData !== false,
+        includeInfluences: b.includeInfluences && opts.includeInfluences !== false,
+    };
+}
+/**
+ * Strip a set of dotted `redactions` paths from a plain reading (query result or snapshot). A top-level
+ * key (`'metrics'`, `'relationships'`) deletes that key from the object. A `<prefix>.<key>` path where
+ * prefix ∈ {body, relationship, influence, projection} strips `<key>` from each entry of the matching
+ * list; `body.data` strips per-body `data`. Mutates the passed object (it's always a fresh result/copy).
+ */
+function applyRedactions(reading, redactions) {
+    const listKeyFor = { body: 'bodies', relationship: 'relationships', influence: 'influences', projection: 'projections' };
+    for (const path of redactions) {
+        const dot = path.indexOf('.');
+        if (dot < 0) {
+            delete reading[path];
+            continue;
+        }
+        const prefix = path.slice(0, dot);
+        const key = path.slice(dot + 1);
+        const listKey = listKeyFor[prefix];
+        if (listKey && Array.isArray(reading[listKey])) {
+            for (const entry of reading[listKey]) {
+                if (entry && typeof entry === 'object')
+                    delete entry[key];
+            }
+        }
+        else if (prefix === 'metrics' && reading['metrics'] && typeof reading['metrics'] === 'object') {
+            delete reading['metrics'][key];
+        }
+        else {
+            // an unrecognized prefix addresses a nested top-level object key.
+            const target = reading[prefix];
+            if (target && typeof target === 'object')
+                delete target[key];
+        }
+    }
+    return reading;
+}
 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
@@ -78,12 +166,37 @@ export function createField(canvas, opts = {}) {
     // it (the caller owns the element + its fixed/pointer-events placement); its backing store is sized
     // in resize() to match the main canvas dpr. Keeps core DOM-free — the canvas is handed in.
     // Under `render: 'none'` it is never acquired either (the overlay never draws in that mode).
-    const overlayCanvas = opts.overlayCanvas ?? null;
+    // The overlay canvas may be handed in eagerly (`overlayCanvas`) OR resolved lazily the first time an
+    // overlay actually becomes active (`overlayCanvasProvider`, #676) — the host defers creating a
+    // full-viewport light-DOM canvas until a reading is switched on, so the common `overlay: off` case
+    // never adds a mix-blend canvas to the compositing tree at boot. Core stays DOM-free either way: the
+    // host owns the element; core only draws to it.
+    let overlayCanvas = opts.overlayCanvas ?? null;
     let overlayCtx = ctx ? (overlayCanvas?.getContext('2d') ?? null) : null;
     // The overlay draws exclusively through the RenderBackend contract (#373) — the structural
     // seam a WebGL/WebGPU surface implements later. Callers may inject one; the default wraps the
     // overlay's own 2d context.
     let overlayBackend = opts.overlayBackend ?? (overlayCanvas && overlayCtx ? canvas2dBackend(overlayCanvas, overlayCtx) : null);
+    /**
+     * Resolve the overlay surface on demand (#676). If no canvas is bound yet but a provider was supplied,
+     * call it once, acquire its 2d context + default backend, and size the backing store to the live dpr.
+     * Idempotent — an already-resolved backend (eager canvas, injected backend, or a prior call) short-
+     * circuits. Called the first time an overlay reading becomes active (`setOverlay`) and on the
+     * `setRender('none' → …)` lazy path. No-op while the underlay `ctx` is absent (signals-only boot).
+     */
+    function ensureOverlaySurface() {
+        if (overlayBackend)
+            return;
+        if (!overlayCanvas && opts.overlayCanvasProvider)
+            overlayCanvas = opts.overlayCanvasProvider() ?? null;
+        if (!overlayCanvas || !ctx)
+            return;
+        overlayCtx ??= overlayCanvas.getContext('2d');
+        if (!overlayCtx)
+            return;
+        overlayBackend = opts.overlayBackend ?? canvas2dBackend(overlayCanvas, overlayCtx);
+        overlayBackend.size(W, H, host.viewport().dpr); // size to the live viewport — resize() only fires on change
+    }
     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
@@ -183,7 +296,9 @@ export function createField(canvas, opts = {}) {
     // 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.
+    // only the first frame it has a value to test. On rescan, a persisting body's Thresholders are
+    // re-keyed onto its replacement Body (scan()'s reconciliation, #966 — the carried d/attn would
+    // otherwise re-fire a rising edge already announced); a removed body's entries drop with it.
     // Keyed body → metric-name → Thresholder; edges track relationship `memory` the same way.
     const bodyThresholds = new WeakMap();
     const edgeThresholds = new WeakMap();
@@ -204,7 +319,42 @@ export function createField(canvas, opts = {}) {
     }
     const host = opts.host;
     const teardowns = []; // host event unsubscribers, called on destroy
-    const reduceMotion = host.reducedMotion();
+    // Reduced-motion is an ACCESSIBILITY clamp: when the host/user asks for it, motion can only be
+    // *removed*, never restored by policy. It's read live (not captured once) so it always reflects the
+    // current OS/user state.
+    const hostReducedMotion = () => host.reducedMotion?.() ?? false;
+    // Runtime FIELD POLICY (#field-policy): what THIS host/session/user/app PERMITS (runtime), distinct
+    // from governance (what doctrine allows — static lint). Replaced live via `setPolicy`. Default: no
+    // policy → unbounded, byte-identical to the pre-policy engine.
+    let policy = clonePolicy(opts.policy);
+    // The effective MOTION budget (0..1) — the single value the render/easing/integrator path reads.
+    // Unifies reduced-motion + host policy (+ perf pressure, folded via the same `min`). Reduced-motion
+    // ALWAYS wins (accessibility can only lower motion, never raise it): when it's on, this is 0.
+    const effectiveMotion = () => {
+        if (hostReducedMotion())
+            return 0; // accessibility clamp — beats any policy
+        let m = 1;
+        if (policy.allowMotionProjection === false)
+            return 0; // policy pins motion off
+        if (policy.maxMotionBudget != null)
+            m = Math.min(m, policy.maxMotionBudget);
+        if (policy.budgets?.motion != null)
+            m = Math.min(m, policy.budgets.motion);
+        return Math.max(0, Math.min(1, m)); // perf pressure folds here via the same min (currently 1)
+    };
+    // the initial static snapshot used for boot/seed state (frame 0 has no perf history):
+    const reduceMotion = effectiveMotion() <= 0;
+    // Privacy budget → snapshot data gate. A privacy budget below this withholds body `data` even when a
+    // caller passes `includeData` (policy tightens; it can't be overridden upward at the call site).
+    const PRIVACY_DATA_THRESHOLD = 0.5;
+    const policyPermitsBodyData = () => {
+        if (policy.allowBodyDataInSnapshots === false)
+            return false; // explicit deny wins
+        const pv = policy.budgets?.privacy;
+        if (pv != null && pv < PRIVACY_DATA_THRESHOLD)
+            return false; // low privacy budget → withhold
+        return true; // default: fall through to the call-site `includeData`
+    };
     // 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];
@@ -212,12 +362,19 @@ export function createField(canvas, opts = {}) {
         accent: opts.accent ?? resolvePalette(opts.palette)[0] ?? PALETTE[0] ?? '#4da3ff',
         density: opts.density && opts.density > 0 ? opts.density : 1,
         render: opts.render ?? 'none', // signals-first default (#538): a bare field runs the sim + feedback but draws nothing until asked. Pass render:'dots' for the particle surface.
-        waves: opts.waves ?? true, // draw the background Currents (§24); opt-out for the bare field
+        waves: opts.waves ?? false, // the background Currents (§24) are OPT-IN (#979, doc-06 Step 0): a bare field has no carrier waves; pass waves:true for the ambient resting structure.
         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
+        reaction: opts.reaction ?? false, // Newtonian own-emission recoil for dynamic bodies (#873)
         separation: opts.separation != null && opts.separation >= 0 ? opts.separation : 0,
+        // DECLARED ambient bias (Wallpaper Rule, #978): the resting `ambient` formation's swirl (`orbit`)
+        // and drift (`wander`), formerly hardcoded (0.1 / 1.0) in FORMATION_BY.ambient.preset — a gray debt.
+        // Defaulting to the historical preset values keeps the resting field byte-identical; these dials let
+        // a host zero the spiral (ambientOrbit:0 → purely radial attract) or calm the drift.
+        ambientOrbit: opts.ambientOrbit != null && opts.ambientOrbit >= 0 ? opts.ambientOrbit : FORMATION_BY.ambient.preset.orbit,
+        ambientWander: opts.ambientWander != null && opts.ambientWander >= 0 ? opts.ambientWander : FORMATION_BY.ambient.preset.wander,
         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
@@ -236,8 +393,25 @@ export function createField(canvas, opts = {}) {
         // 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,
-        // the integration scheme (substrate doc 04 §Step 3); 'legacy' (default) is the shipped engine.
-        integrator: (opts.integrator === 'fixed' ? 'fixed' : 'legacy'),
+        // DECLARED render reference points (Wallpaper Rule, #975): four content-independent constants
+        // formerly painted into the draw path, now dials whose defaults reproduce the historical values
+        // (so every render mode stays byte-identical by default).
+        // heat vignette center — viewport fractions, formerly (W/2, H·0.4). Resolved to px per frame.
+        heatCenterX: opts.heatCenter && Number.isFinite(opts.heatCenter.x) ? opts.heatCenter.x : 0.5,
+        heatCenterY: opts.heatCenter && Number.isFinite(opts.heatCenter.y) ? opts.heatCenter.y : 0.4,
+        // redshift observer — viewport fractions, formerly (W/2, H/2). Resolved to px per frame.
+        redshiftObserverX: opts.redshiftObserver && Number.isFinite(opts.redshiftObserver.x) ? opts.redshiftObserver.x : 0.5,
+        redshiftObserverY: opts.redshiftObserver && Number.isFinite(opts.redshiftObserver.y) ? opts.redshiftObserver.y : 0.5,
+        // depth-camera focal length in CSS px, formerly the hardcoded FOCAL = 480.
+        depthFocal: opts.depthFocal != null && opts.depthFocal > 0 ? opts.depthFocal : 480,
+        // heatmap scroll-fade curve (in viewports), formerly the hardcoded (1.15 - scrollY/H)/0.85 —
+        // full above start·H, gone by (start+span)·H. Defaults reproduce start=0.3, span=0.85.
+        heatmapFadeStart: opts.heatmapFade && Number.isFinite(opts.heatmapFade.start) ? opts.heatmapFade.start : 0.3,
+        heatmapFadeSpan: opts.heatmapFade && Number.isFinite(opts.heatmapFade.span) && opts.heatmapFade.span > 0 ? opts.heatmapFade.span : 0.85,
+        // the integration scheme (substrate doc 04 §Step 3, #659); 'legacy' (default) is the shipped engine.
+        integrator: (opts.integrator === 'fixed' || opts.integrator === 'velocity-verlet'
+            ? opts.integrator
+            : 'legacy'),
         // ONE write path (#228, Phase 5): every feedback write goes through a sink. The platform
         // supplies one (D3, FeedbackRegistry via <field-root>); without it the engine installs the
         // internal default sink, whose writes are byte-identical to the historical direct writes.
@@ -268,23 +442,37 @@ export function createField(canvas, opts = {}) {
     // the simulation + feedback signals stay live. Tab-level visibility is handled separately
     // (onVisibility stops the loop entirely).
     let canvasVisible = true;
-    let formTarget = { ...FORMATION_BY.ambient.preset };
+    // the resting `ambient` formation, with its two DECLARED dials applied (#978). Everything that
+    // targets `ambient` — the initial form, env.form, and the conductor's idle drift-back — resolves
+    // through this so the override is consistent. Defaults reproduce FORMATION_BY.ambient.preset.
+    const ambientForm = {
+        ...FORMATION_BY.ambient.preset,
+        orbit: cfg.ambientOrbit,
+        wander: cfg.ambientWander,
+    };
+    let formTarget = { ...ambientForm };
     let formationName = 'ambient'; // the active formation's id, for FieldHandle.query()
-    // Stable per-body ids for FieldHandle.query(): the element's id when present, else a synthetic
-    // `body-N` kept stable across queries (same Body object → same id), so relationship endpoints and
-    // body readings agree.
-    const bodyIdMap = new WeakMap();
+    // First-class body identity (substrate critical path). Every body resolves to a stable, structured
+    // FieldBodyIdentity, cached on `b.identity` the first time it is keyed. Precedence: a supplied identity
+    // (addBody({ identity })) → the `identify` field-option resolver → the element's DOM id → a monotonic
+    // `body-N` synthetic. Deterministic (never Math.random); stable for the body's life, so relationship
+    // endpoints, body readings, snapshots, and diff/replay all agree on `identity.id`.
     let bodyIdSeq = 0;
-    const bodyId = (b) => {
-        if (b.el && b.el.id)
-            return b.el.id;
-        let id = bodyIdMap.get(b);
-        if (id === undefined) {
-            id = `body-${bodyIdSeq++}`;
-            bodyIdMap.set(b, id);
-        }
-        return id;
+    const identify = opts.identify;
+    const bodyIdentity = (b) => {
+        if (b.identity)
+            return b.identity;
+        let ident;
+        if (identify && b.el)
+            ident = identify(b.el);
+        if (!ident) {
+            const domId = b.el && b.el.id ? b.el.id : undefined;
+            ident = { id: domId ?? `body-${bodyIdSeq++}` };
+        }
+        b.identity = ident;
+        return ident;
     };
+    const bodyId = (b) => bodyIdentity(b).id;
     // Shared metric/dimension reading for query() and snapshot(), so both compute identically (diff
     // compares snapshot metrics — they must agree with what query() reports).
     const readBodyMetrics = (b) => {
@@ -357,6 +545,8 @@ export function createField(canvas, opts = {}) {
     // kinematic bodies are never touched, so with no dynamic bodies this loop is a no-op.
     const BODY_FRICTION = 0.9; // heavier than particle FRICTION so dynamic bodies settle, not drift forever
     const MAX_BODY_SPEED = 8; // px/frame cap — keeps a dynamic body from flinging off under a strong well
+    const MASS_REF_AREA = 4800; // px² reference (~120×40 body) → inertia 1; sqrt+clamp keeps the range sane (#872)
+    const REACTION_COEFF = 0.02; // scales own-emission recoil (summed over matter in range); capped by MAX_BODY_SPEED (#873)
     function moveDynamicBodies() {
         for (const b of bodies) {
             if (b.authority !== 'dynamic' || !b.vis)
@@ -374,9 +564,34 @@ export function createField(canvas, opts = {}) {
             // doesn't recoil from its own singular centre).
             const others = bodies.filter((o) => o !== b && o.vis && o.tokens.length > 0);
             const { fx, fy } = forceAt(others, reg.forces, env, bx, by);
-            const invM = 1 / Math.max(b.M, 1e-4);
-            let vx = (b.bvx ?? 0) + fx * invM * env.dt;
-            let vy = (b.bvy ?? 0) + fy * invM * env.dt;
+            // INERTIAL mass (#872): under first-class `mass`, a body's resistance to motion ∝ rendered area
+            // (sqrt, clamped) — a big heading settles slowly, a small tag snaps. Otherwise inertia stays
+            // undefined and recoil falls back to the source mass M (today's behavior, byte-identical). a = F/inertia.
+            if (cfg.mass) {
+                const area = b.hw * 2 * (b.hh * 2);
+                b.inertia = Math.min(4, Math.max(0.4, Math.sqrt(area / MASS_REF_AREA)));
+            }
+            const invM = 1 / Math.max(b.inertia ?? b.M, 1e-4);
+            // Newtonian own-emission reaction (#873): B feels the equal-and-opposite of the net impulse it
+            // imparts to nearby matter — a directional emitter recoils like a rocket, closing reciprocity
+            // through *motion*, not just feedback. Off by default (byte-identical). Best paired with `mass`.
+            let reFx = 0, reFy = 0;
+            if (cfg.reaction && b.tokens.length > 0) {
+                const r2 = b.range * b.range;
+                const self = [b];
+                for (const p of store.particles) {
+                    if (p.cap)
+                        continue;
+                    const ddx = p.x - bx, ddy = p.y - by;
+                    if (ddx * ddx + ddy * ddy > r2)
+                        continue; // only matter B can actually push
+                    const bf = forceAt(self, reg.forces, env, p.x, p.y);
+                    reFx -= bf.fx; // third law: the body gets the opposite of what it pushes
+                    reFy -= bf.fy;
+                }
+            }
+            let vx = (b.bvx ?? 0) + (fx + reFx * REACTION_COEFF) * invM * env.dt;
+            let vy = (b.bvy ?? 0) + (fy + reFy * REACTION_COEFF) * invM * env.dt;
             vx *= BODY_FRICTION;
             vy *= BODY_FRICTION;
             const sp = Math.hypot(vx, vy);
@@ -423,6 +638,7 @@ export function createField(canvas, opts = {}) {
     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
+    let depthIdx = null; // scratch draw-order index for the depth render mode (far → near)
     // EMA (exponential moving average) of the per-frame peak magnitude for each arrow renderer.
     // Normalizing to the raw frame max caused the entire arrow field to rescale in one step when
     // maxMag shifted (body drag, animated strength, density ramp) — visible as a pulsing flash.
@@ -488,7 +704,7 @@ export function createField(canvas, opts = {}) {
     // clear the field's CSS write-back when a still-connected host leaves the field, so it
     // doesn't keep a frozen `--d` glow (a removed light-DOM element is gone, so it needs no clear).
     const clearWriteback = (el) => {
-        for (const v of ['--d', '--field-density', '--load', '--mass', '--entropy', '--coherence', '--temperature'])
+        for (const v of ['--d', '--field-density', '--load', '--entropy', '--coherence', '--temperature'])
             el.style.removeProperty(v);
     };
     const onRegister = (e) => {
@@ -514,11 +730,11 @@ export function createField(canvas, opts = {}) {
         dy: 0,
         dz: 0,
         dist: 1,
-        form: { ...FORMATION_BY.ambient.preset },
+        form: { ...ambientForm },
         W: 0,
         H: 0,
         D: cfg.depth, // the optional z volume (z-axis.md); 0 = the flat field
-        integrator: cfg.integrator, // 'legacy' (default) | 'fixed' (doc 04 §Step 3)
+        integrator: cfg.integrator, // 'legacy' (default) | 'fixed' (doc 04 §Step 3) | 'velocity-verlet' (#659)
         t: 0,
         frameN: 0,
         dt: reduceMotion ? 0 : 1,
@@ -560,8 +776,8 @@ 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 });
+                if (busHas('released'))
+                    busEmit('released', { body: b, count: released.length });
                 sinkPeak.delete(b);
             }
         },
@@ -592,7 +808,7 @@ export function createField(canvas, opts = {}) {
         if (reduceMotion || sparks.length > 260)
             return;
         const c = color ? hexToRgb(color) : [255, 122, 69]; // WARM default (§20.8)
-        const n = sparkCount(power);
+        const n = sparkCount(power, rng); // count through the injected rng too (#371) — directions already are
         for (let k = 0; k < n; k++) {
             const a = rng() * 6.28318;
             const s = 0.8 + rng() * (power > 0 ? power : 1) * 1.7;
@@ -644,12 +860,15 @@ export function createField(canvas, opts = {}) {
         for (let i = 0; i < n; i++)
             store.add(newParticle());
         applySeed();
-        // the Currents (§24) are opt-out: with waves off, the field is just the free particles.
+        // the Currents (§24) are OPT-IN (#979): by default the field is just the free particles.
         waves = cfg.waves ? buildWaves(cfg.waveBaseline) : [];
         bound = cfg.waves ? buildBound(waves.length, cfg.density, rng) : [];
         boundTarget = bound.length;
     }
     function scan() {
+        // capture the outgoing generation FIRST — the rebuild below replaces every DOM-scanned Body
+        // object wholesale, and the reconciliation pass after the rebuild carries runtime state across.
+        const prevGen = bodies;
         const scanned = scanBodies(host.root);
         // merge event-registered shadow-DOM hosts (deduped — a light-DOM host that also fires
         // a registration event is counted once). Registration is the canonical discovery path;
@@ -664,6 +883,104 @@ 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);
+        // ——— Rescan reconciliation (#966): carry body feedback state + remap captures. ———
+        // makeBody zeroes runtime state (`d: 0`, `accreted: 0`, …), which made ANY rescan a visible
+        // discontinuity: every data-feedback body's --d hard-dropped (measured 1.000 → 0.080) and eased
+        // back over ~1s, while matter a sink had captured stayed pinned to the OLD (ghost) Body — frozen,
+        // never released — as the rebuilt sink re-captured a second full capacity. Mirror the
+        // prevMovers/prevEmitters reconciliation: key the outgoing generation by (element, per-element
+        // body index) — a data-preset element expands to several virtual bodies in a stable order, so
+        // the index tells them apart — and carry each persisting body's runtime feedback state
+        // (`d`, `attn`, `accreted`, `count`, `wasOn`) onto its replacement. Programmatic (addBody)
+        // bodies persist by object identity (ob === nb) and skip naturally. Removed elements are simply
+        // absent from the new generation, so their state drops with the old Body (no leak).
+        //
+        // Body-keyed side tables — per-map carry/reset decisions:
+        //   sinkPeak         CARRY — the armed flag lives on el.dataset.fxCap (which survives the
+        //                    rescan) and `accreted` is carried, so a filling sink is still mid-cycle;
+        //                    dropping the peak would make the eventual `release` bus event report 0.
+        //   bodyThresholds   CARRY — `d`/`attn` are carried, so keeping the hysteresis + debounce state
+        //                    avoids a duplicate rising-edge `field:*` event on the first post-rescan
+        //                    frame. (Entries for removed bodies drop with the Body — WeakMap keys.)
+        //   insideOf/metWith RESET (by design) — proximity membership re-derives from live geometry on
+        //                    the next detection pass; carrying it would need old→new remaps of both
+        //                    keys and set members for marginal benefit.
+        //   emitAcc/thermo/metrics RESET (by design) — the fractional-emission remainder and the
+        //                    windowed thermodynamic measurements re-accumulate within a frame or two.
+        let bodyRemap = null; // old → new, for the capture remaps below
+        let remapCaptures = false; // some persisting body held matter → run the O(P) cap-remap pass
+        if (prevGen.length > 0) {
+            const prevByEl = new Map();
+            for (const ob of prevGen) {
+                const list = prevByEl.get(ob.el);
+                if (list)
+                    list.push(ob);
+                else
+                    prevByEl.set(ob.el, [ob]);
+            }
+            const nextIdx = new Map();
+            for (const nb of bodies) {
+                const list = prevByEl.get(nb.el);
+                if (!list)
+                    continue;
+                const i = nextIdx.get(nb.el) ?? 0;
+                nextIdx.set(nb.el, i + 1);
+                const ob = list[i];
+                if (!ob || ob === nb)
+                    continue; // index outgrew the old expansion, or same object (addBody)
+                // IDENTITY (#970): carry the resolved identity so an anonymous body keeps its synthetic
+                // `body-N` across rescans. Without this the rebuilt Body has `identity: undefined` and
+                // bodyIdentity() mints a FRESH `body-${bodyIdSeq++}` — the same element's id churned on
+                // every rescan, breaking snapshot/diff/replay continuity for anonymous bodies (state carry,
+                // captures, and relationship edges all key on identity.id). Keyed by the same (element,
+                // per-element index) as the state carry, so a preset's virtual bodies keep their ids too.
+                if (ob.identity !== undefined)
+                    nb.identity = ob.identity;
+                // DYNAMIC MOTION (#970): a `data-authority="dynamic"` body's position + velocity are
+                // engine-owned (bx/by/bvx/bvy), not DOM-derived. makeBody leaves them undefined, so on
+                // rescan moveDynamicBodies() re-adopts the freshly-measured DOM centre and zeroes velocity
+                // — a drifting body teleported back to its authored slot when ANY body was added/removed.
+                // Carry the kinematic state so the body keeps moving through a rescan (the motion analog of
+                // the feedback-state carry above). Only meaningful for dynamic bodies; undefined otherwise.
+                if (ob.bx !== undefined) {
+                    nb.bx = ob.bx;
+                    nb.by = ob.by;
+                    nb.bvx = ob.bvx;
+                    nb.bvy = ob.bvy;
+                    // measureBodies (below) overwrites cx/cy from the rect, but the next moveDynamicBodies()
+                    // re-asserts the carried bx/by as authoritative — so the body resumes from where it was.
+                }
+                nb.d = ob.d;
+                if (ob.attn !== undefined)
+                    nb.attn = ob.attn;
+                nb.accreted = ob.accreted;
+                nb.count = ob.count;
+                if (ob.wasOn !== undefined)
+                    nb.wasOn = ob.wasOn;
+                const th = bodyThresholds.get(ob);
+                if (th)
+                    bodyThresholds.set(nb, th);
+                const peak = sinkPeak.get(ob);
+                if (peak !== undefined)
+                    sinkPeak.set(nb, peak);
+                (bodyRemap ??= new Map()).set(ob, nb);
+                if (ob.accreted > 0)
+                    remapCaptures = true;
+            }
+            // Remap captured matter onto the replacement Body (the ghost-body strand: `p.cap` kept
+            // lerping to the old object's frozen centre — integrator.ts holds captured matter via
+            // `p.cap.cx/cy` — and `releaseCaptured` on the new body never matched it). One O(P) pass,
+            // and only when some persisting body actually held matter.
+            if (remapCaptures) {
+                for (const p of store.particles) {
+                    if (!p.cap)
+                        continue;
+                    const nb = bodyRemap.get(p.cap);
+                    if (nb)
+                        p.cap = nb;
+                }
+            }
+        }
         measureBodies(bodies, W, H, originX, originY);
         bindEngagement();
         // Reconcile movers: carry forward offset + dock state for elements that persist across
@@ -689,7 +1006,11 @@ export function createField(canvas, opts = {}) {
             if (prev) {
                 // Persist the in-flight state: the element was already known, keep its offset + dock
                 // progress. Re-check dockable/warpable/layout in case attributes changed. mEl re-measured.
-                return { el, o: prev.o, mEl, layout, dockable, dock: prev.dock, docked: prev.docked, warpable, warpCool: prev.warpCool };
+                // A docked element's sink reference is remapped to the sink's replacement Body (#966) —
+                // otherwise it would hold the OLD generation's object and `undockFrom` (supernova release)
+                // on the new body would never release it.
+                const docked = prev.docked ? (bodyRemap?.get(prev.docked) ?? prev.docked) : null;
+                return { el, o: prev.o, mEl, layout, dockable, dock: prev.dock, docked, warpable, warpCool: prev.warpCool };
             }
             return { el, o: { x: 0, y: 0, vx: 0, vy: 0 }, mEl, layout, dockable, dock: { dock: 0 }, docked: null, warpable, warpCool: 0 };
         });
@@ -854,10 +1175,9 @@ export function createField(canvas, opts = {}) {
             }
         }
     }
-    // dispatch a discrete field event on an element, with the forces:* alias (migration window).
+    // dispatch a discrete field event on an element.
     function fireCaptureEvent(el, name, detail) {
         el.dispatchEvent(new CustomEvent('field:' + name, { bubbles: true, composed: true, detail }));
-        el.dispatchEvent(new CustomEvent('forces:' + name, { bubbles: true, composed: true, detail }));
     }
     // capture/release events for sink BODIES (particle accretion): fire field:captured on the rising
     // edge of accreting and field:released on the falling edge (§22.5). Release is also fired directly
@@ -871,15 +1191,15 @@ 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 });
+                if (busHas('captured'))
+                    busEmit('captured', { 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 });
+                if (busHas('released'))
+                    busEmit('released', { body: b, count: sinkPeak.get(b) ?? 0 });
                 sinkPeak.delete(b);
             }
         }
@@ -1071,6 +1391,14 @@ 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).
+    // Keyboard parity (a11y, #665): a [data-hot] body is often a container (card, row, <li>,
+    // <aside>) whose focusable content is a CHILD (<a>/<button>). Pointer engagement uses
+    // `pointerenter`, which fires when the cursor enters the container's box — so a mouse user
+    // engages it. But focus does NOT bubble, so `focus`/`blur` on the container would never fire
+    // when a keyboard user tabbed to a descendant, and the body stayed dark for keyboard-only
+    // users. We bind the bubbling `focusin`/`focusout` instead, so tabbing into (or out of) any
+    // focusable descendant engages the body exactly the way hover does — the RC-8 principle that
+    // keyboard users get the same field reactions as the mouse.
     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
@@ -1083,8 +1411,8 @@ export function createField(canvas, opts = {}) {
                     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);
+                e.el.removeEventListener('focusin', e.enter);
+                e.el.removeEventListener('focusout', e.leave);
                 delete e.el.dataset.fxEngaged;
                 return false;
             });
@@ -1110,8 +1438,11 @@ export function createField(canvas, opts = {}) {
             };
             el.addEventListener('pointerenter', enter);
             el.addEventListener('pointerleave', leave);
-            el.addEventListener('focus', enter);
-            el.addEventListener('blur', leave);
+            // focusin/focusout (not focus/blur) so focus on a focusable DESCENDANT of a [data-hot]
+            // container engages the body — keyboard parity with pointerenter (#665). These bubble;
+            // focus/blur do not.
+            el.addEventListener('focusin', enter);
+            el.addEventListener('focusout', leave);
             engaged.push({ el, enter, leave });
         });
     }
@@ -1186,7 +1517,7 @@ export function createField(canvas, opts = {}) {
         sizeSurfaces(vp.dpr);
         env.W = W;
         env.H = H;
-        maxScroll = host.scrollHeight() - H || 1;
+        maxScroll = (host.scrollHeight?.() ?? H) - H || 1;
         for (const g of grids.values())
             g.resize(W, H); // keep field buffers viewport-sized
         if (cfg.heatmap) {
@@ -1435,7 +1766,7 @@ export function createField(canvas, opts = {}) {
             // ONE write path (#228): the CSS-var channels always go to the sink — the platform's
             // FeedbackRegistry route (D3) when configured, otherwise the internal default sink
             // (feedback-sink.ts), which performs the same direct writes the engine always made:
-            // `--d`/`--field-density`, `--field-heatmap-density`, `--load`/`--mass`,
+            // `--d`/`--field-density`, `--field-heatmap-density`, `--load`,
             // plus the measured `--entropy`/`--coherence`/`--temperature`.
             const channels = {
                 density: b.d,
@@ -1494,13 +1825,20 @@ export function createField(canvas, opts = {}) {
         // 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;
+        // DECLARED scroll-fade curve (#975): full above start·H, gone by (start+span)·H — formerly the
+        // hardcoded (1.15 - scrollY/H)/0.85 (start=0.3, span=0.85 reproduce it, so it stays byte-identical).
+        const hmFade = H > 0 ? clamp((cfg.heatmapFadeStart + cfg.heatmapFadeSpan - lastScrollY / H) / cfg.heatmapFadeSpan, 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));
         if (!hmCanvas) {
+            if (!host.createCanvas) {
+                // a drawing mode reached the heatmap buffer but the host has no canvas capability; a
+                // signals-first (render:'none') field never gets here. Fail loud rather than draw nothing.
+                throw new Error("Fundamental: this FieldHost provides no createCanvas() — the heatmap layer needs one. Use render:'none' (signals-first) or supply a host with a createCanvas capability.");
+            }
             hmCanvas = host.createCanvas();
             hmCtx = hmCanvas.getContext('2d');
         }
@@ -1564,22 +1902,31 @@ export function createField(canvas, opts = {}) {
             ctx.fillRect(0, 0, W, H);
         }
         drawWaves();
-        // 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.)
+        // The heatmap is an ambient layer that fades out with scroll POSITION (the DECLARED `heatmapFade`
+        // curve above), not with scroll SPEED. An earlier speed-based suppression made it pop/fade in/out
+        // while scrolling, which read as choppy; the position fade is monotonic so it never flickers, and
+        // the per-frame cost is just the cached bilinear upscale (the texel grid recomputes every 3rd
+        // frame). Below the fade window the whole layer is skipped.
         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
         // the matter per §20.6, so suppress the dot swarm for those two; dots/trails/links/voronoi
-        // keep it (their overlays read against the particles).
-        const showMatter = cfg.render !== 'metaballs' && cfg.render !== 'streamlines';
+        // keep it (their overlays read against the particles). The four matter-swap modes
+        // (knockout / redshift / blackbody / depth, #667–#670) draw their own particle pass
+        // below — same suppression, different material.
+        const showMatter = cfg.render !== 'metaballs' &&
+            cfg.render !== 'streamlines' &&
+            cfg.render !== 'knockout' &&
+            cfg.render !== 'redshift' &&
+            cfg.render !== 'blackbody' &&
+            cfg.render !== 'depth';
         ctx.globalCompositeOperation = 'lighter';
         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;
+        // DECLARED heat-vignette center (#975): viewport fractions → px, formerly the hardcoded (W/2, H·0.4).
+        const cx = W * cfg.heatCenterX;
+        const cy = H * cfg.heatCenterY;
         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
@@ -1780,6 +2127,148 @@ export function createField(canvas, opts = {}) {
             ctx.stroke();
             ctx.globalCompositeOperation = 'source-over';
         }
+        // knockout (#667): figure-ground inversion — the field is a solid accent sheet and matter
+        // is NEGATIVE space: each particle erases a feathered hole through everything beneath it
+        // (waves, heatmap, sparks — a true print knockout). §11-safe by construction: matter never
+        // assembles into letterforms; for the "field visible only inside letters" treatment the
+        // host clips this canvas to real type with a CSS mask/clip-path — the type stays type and
+        // the field shows through it. One full-canvas wash (the clear's cost class) + two arcs per
+        // particle (the dots-mode cost envelope); no extra surface, no mix-blend.
+        if (cfg.render === 'knockout') {
+            const wash = curAccent;
+            ctx.fillStyle = `rgba(${wash[0]},${wash[1]},${wash[2]},${0.22 * boot})`;
+            ctx.fillRect(0, 0, W, H);
+            ctx.globalCompositeOperation = 'destination-out';
+            for (const p of store.particles) {
+                if (p.cap)
+                    continue;
+                const zk = cfg.depth > 0 ? 1 - Math.min(Math.abs(p.z ?? 0) / cfg.depth, 1) * 0.55 : 1;
+                const hole = knockoutHoleRadius(p.size, p.heat, zk);
+                // feathered punch: a soft rim then a hard core (destination-out reads only the alpha)
+                ctx.fillStyle = `rgba(0,0,0,${0.38 * boot})`;
+                ctx.beginPath();
+                ctx.arc(p.x, p.y, hole + 2.2, 0, 6.28318);
+                ctx.fill();
+                ctx.fillStyle = `rgba(0,0,0,${boot})`;
+                ctx.beginPath();
+                ctx.arc(p.x, p.y, hole, 0, 6.28318);
+                ctx.fill();
+            }
+            ctx.globalCompositeOperation = 'source-over';
+        }
+        // redshift (#668): the dots geometry tinted by SPECTRAL SHIFT instead of the heat ramp —
+        // the Doppler term reads each particle's radial velocity against an observer at the
+        // viewport centre (receding reds, approaching blues, normalized by the unit system's
+        // velocity cap env.c), and the gravitational term reads proximity to body wells (light
+        // climbing out loses energy, so a well only reddens). The §20.6 "relativistic
+        // accretion-disk" look: matter falling around a sink wears its infall.
+        if (cfg.render === 'redshift') {
+            ctx.globalCompositeOperation = 'lighter';
+            // DECLARED observer (#975): viewport fractions → px, formerly the hardcoded (W/2, H/2).
+            const ox = W * cfg.redshiftObserverX;
+            const oy = H * cfg.redshiftObserverY;
+            for (const p of store.particles) {
+                if (p.cap)
+                    continue;
+                let well = 0;
+                for (const b of bodies) {
+                    const reach = b.range || 200;
+                    const dx = p.x - b.cx;
+                    const dy = p.y - b.cy;
+                    const w = wellWeight(dx * dx + dy * dy, reach * reach);
+                    if (w > well)
+                        well = w;
+                }
+                const s = redshiftShift(dopplerShift(radialVelocity(p.x, p.y, p.vx, p.vy, ox, oy), env.c), well);
+                redshiftRGBInto(_rgb, s);
+                const zk = cfg.depth > 0 ? 1 - Math.min(Math.abs(p.z ?? 0) / cfg.depth, 1) * 0.55 : 1;
+                const mag = s < 0 ? -s : s;
+                const size = (p.size + mag * 1.6) * zk;
+                const alpha = clamp((0.4 + 0.45 * mag) * boot * zk, 0, 1);
+                ctx.fillStyle = `rgba(${_rgb[0] | 0},${_rgb[1] | 0},${_rgb[2] | 0},${alpha})`;
+                ctx.beginPath();
+                ctx.arc(p.x, p.y, size, 0, 6.28318);
+                ctx.fill();
+            }
+            ctx.globalCompositeOperation = 'source-over';
+        }
+        // blackbody (#669): thermal truth — each particle tinted by its ENERGY on a Planckian-ish
+        // ramp (near-black ember → deep red → orange → warm white → blue-white), brightness rising
+        // with temperature so cold matter barely glows and hot matter reads white (§20.6). Energy =
+        // carried heat + kinetic (|v|² against a 0.3·env.c reference). Caveat canon: a reading of
+        // the designed unit system, not radiometry.
+        if (cfg.render === 'blackbody') {
+            ctx.globalCompositeOperation = 'lighter';
+            for (const p of store.particles) {
+                if (p.cap)
+                    continue;
+                const t = blackbodyT(p.vx, p.vy, p.heat, env.c);
+                blackbodyRGBInto(_rgb, t);
+                const zk = cfg.depth > 0 ? 1 - Math.min(Math.abs(p.z ?? 0) / cfg.depth, 1) * 0.55 : 1;
+                const size = (p.size + t * 2.2) * zk;
+                const alpha = clamp((0.16 + 0.84 * t) * boot * zk, 0, 1);
+                const cr = _rgb[0] | 0;
+                const cg = _rgb[1] | 0;
+                const cb = _rgb[2] | 0;
+                // hot matter blooms: a soft halo under the crisp core, scaled by temperature
+                ctx.fillStyle = `rgba(${cr},${cg},${cb},${0.14 * alpha})`;
+                ctx.beginPath();
+                ctx.arc(p.x, p.y, size + 1.4 + t * 2, 0, 6.28318);
+                ctx.fill();
+                ctx.fillStyle = `rgba(${cr},${cg},${cb},${alpha})`;
+                ctx.beginPath();
+                ctx.arc(p.x, p.y, size, 0, 6.28318);
+                ctx.fill();
+            }
+            ctx.globalCompositeOperation = 'source-over';
+        }
+        // depth (#670): the z lane made visible — true 2.5D. Particles are sorted far-to-near
+        // (painter's algorithm, drawn source-over so near matter OCCLUDES far — additive 'lighter'
+        // would make the order meaningless), projected toward the viewport centre by a perspective
+        // scale (motion parallax emerges as z integrates), and defocused with distance: a wider
+        // soft halo + a faded core, the cheap draw-time stand-in for blur (no ctx.filter, which
+        // costs a composited surface per particle). In a flat field (depth: 0, z ≡ 0) every factor
+        // is exactly 1 and this is the dots pass in painter's order. The index array is a persistent
+        // scratch (reallocated only when the count changes) — no per-frame allocation.
+        if (cfg.render === 'depth') {
+            const parts = store.particles;
+            const n = parts.length;
+            if (!depthIdx || depthIdx.length !== n)
+                depthIdx = new Array(n);
+            for (let i = 0; i < n; i++)
+                depthIdx[i] = i;
+            depthIdx.sort((a, b) => Math.abs(parts[b].z ?? 0) - Math.abs(parts[a].z ?? 0)); // far first
+            const FOCAL = cfg.depthFocal; // DECLARED (#975): px focal length, formerly hardcoded 480.
+            const ox = W / 2; // projection center = viewport center (perspective principal point).
+            const oy = H / 2;
+            for (let i = 0; i < n; i++) {
+                const p = parts[depthIdx[i]];
+                if (p.cap)
+                    continue;
+                const z = p.z ?? 0;
+                const zn = cfg.depth > 0 ? Math.min(Math.abs(z) / cfg.depth, 1) : 0;
+                const scale = depthScale(z, FOCAL);
+                const px = depthProject(p.x, ox, scale);
+                const py = depthProject(p.y, oy, scale);
+                const d = Math.min(1, Math.hypot(px - cx, py - cy) / maxD);
+                const rs = d * d;
+                const h = p.heat;
+                particleRGBInto(_rgb, rs, h, acc, cfg.gradientCool, cfg.gradientWarm);
+                const size = (p.size * (1 - 0.4 * rs) + h * 2) * scale;
+                const alpha = clamp((0.5 - 0.3 * rs + h * 0.5) * boot * depthAlpha(zn), 0, 1);
+                const cr = _rgb[0] | 0;
+                const cg = _rgb[1] | 0;
+                const cb = _rgb[2] | 0;
+                ctx.fillStyle = `rgba(${cr},${cg},${cb},${0.12 * alpha})`;
+                ctx.beginPath();
+                ctx.arc(px, py, size + 1.2 + depthBlurRadius(zn), 0, 6.28318);
+                ctx.fill();
+                ctx.fillStyle = `rgba(${cr},${cg},${cb},${alpha})`;
+                ctx.beginPath();
+                ctx.arc(px, py, size, 0, 6.28318);
+                ctx.fill();
+            }
+        }
         // streamlines: draw the force field itself — a grid of arrows along the net push a still test
         // particle would feel (§20.6 diagnostic). 'streamlines' draws them ALONE (showMatter suppressed
         // the dots above); 'flow' draws the SAME arrows additively over the dots already painted — the
@@ -2282,7 +2771,12 @@ export function createField(canvas, opts = {}) {
         // "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);
+        // Effective motion budget (0..1) folds reduced-motion + policy (+ perf pressure). At 0 the field is
+        // frozen exactly as reduced-motion (`dt = 0` — the "is animating" flag stays falsy); a partial
+        // budget scales displacement-per-second proportionally, so a `maxMotionBudget: 0.5` field drifts at
+        // half speed. Reduced-motion always forces this to 0 (see `effectiveMotion`).
+        const motion = effectiveMotion();
+        env.dt = motion <= 0 ? 0 : clamp(dtRaw, 0.2, 2) * motion;
         if (boot < 1)
             boot = Math.min(1, boot + 0.012);
         easeFormation(env.form, formTarget, 0.03); // glide between formations (§7)
@@ -2293,7 +2787,7 @@ export function createField(canvas, opts = {}) {
             originX = vp.originX ?? 0;
             originY = vp.originY ?? 0;
         }
-        const scrollY = host.scrollY();
+        const scrollY = host.scrollY?.() ?? 0;
         const dScroll = scrollY - lastScrollY;
         // eased page-scroll speed for the `scrolling` data-when gate (§5).
         env.scrollV = (env.scrollV ?? 0) * 0.7 + Math.abs(dScroll) * 0.3;
@@ -2354,7 +2848,7 @@ export function createField(canvas, opts = {}) {
         // accent journey (§9): scroll travels the palette; a hovered element overrides.
         // maxScroll is cached (scrollHeight forces a reflow); resample it twice a second.
         if (frameN % 30 === 0)
-            maxScroll = host.scrollHeight() - H || 1;
+            maxScroll = (host.scrollHeight?.() ?? H) - H || 1;
         const targetAcc = hoverAccent ? hexToRgb(hoverAccent) : sampleStops(JOURNEY, scrollY / maxScroll);
         curAccent = [
             curAccent[0] + (targetAcc[0] - curAccent[0]) * 0.08,
@@ -2427,7 +2921,7 @@ export function createField(canvas, opts = {}) {
         // 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
         // static (dt = 0), so a quarter-rate redraw is visually identical at a quarter of the cost.
-        if (ctx && cfg.render !== 'none' && canvasVisible && (!reduceMotion || frameN % 4 === 0)) {
+        if (ctx && cfg.render !== 'none' && canvasVisible && (motion > 0 || frameN % 4 === 0)) {
             render();
             if (overlayBackend) {
                 const stack = overlayStack(cfg.overlay);
@@ -2440,7 +2934,8 @@ export function createField(canvas, opts = {}) {
     function setFormation(name) {
         const f = FORMATION_BY[name];
         if (f) {
-            formTarget = { ...f.preset };
+            // `ambient` carries the two DECLARED dials (#978); other formations keep their authored presets.
+            formTarget = name === 'ambient' ? { ...ambientForm } : { ...f.preset };
             formationName = name;
         }
     }
@@ -2480,11 +2975,16 @@ export function createField(canvas, opts = {}) {
     idleTimer.unref?.();
     const onResize = () => resize();
     resize();
+    // A field created with an overlay reading ALREADY set (`overlay: 'grid'`, or `<field-root overlay=…>`
+    // at mount) resolves its overlay surface now, so the lazily-provided canvas is created at boot rather
+    // than only on a later setOverlay (#676). `overlay: 'off'` (the default) resolves nothing.
+    if (overlayStack(cfg.overlay).length)
+        ensureOverlaySurface();
     // pause all work while the tab is backgrounded — stop the loop and the idle timer,
     // resume cleanly when it returns (browsers throttle rAF in the background, but this
     // guarantees zero work and avoids drift on return).
     const onVisibility = () => {
-        if (host.hidden()) {
+        if (host.hidden?.() ?? false) {
             host.cancelRaf(raf);
             raf = 0;
         }
@@ -2492,15 +2992,24 @@ export function createField(canvas, opts = {}) {
             raf = host.raf(frame);
         }
     };
-    teardowns.push(host.onResize(onResize));
-    teardowns.push(host.onScroll(scrollHandler));
-    teardowns.push(host.onVisibility(onVisibility));
-    teardowns.push(host.onInput(markInput));
+    // Optional subscription capabilities — a MinimalFieldHost supplies none of these; the field then
+    // never re-reads on resize, never scroll-drives, never auto-pauses, and takes no DOM body events
+    // (programmatic bodies via addBody still work). Each is wired only when the host offers it.
+    if (host.onResize)
+        teardowns.push(host.onResize(onResize));
+    if (host.onScroll)
+        teardowns.push(host.onScroll(scrollHandler));
+    if (host.onVisibility)
+        teardowns.push(host.onVisibility(onVisibility));
+    if (host.onInput)
+        teardowns.push(host.onInput(markInput));
     // shadow-DOM body events: forces:* + field:* aliases share the same idempotent handlers, so a body
     // registers under either namespace; the controller dispatches both, the engine listens to both.
-    teardowns.push(host.onBodyEvent(REGISTER_BODY, onRegister));
-    teardowns.push(host.onBodyEvent(UNREGISTER_BODY, onUnregister));
-    teardowns.push(host.onBodyEvent(UPDATE_BODY, onUpdateBody));
+    if (host.onBodyEvent) {
+        teardowns.push(host.onBodyEvent(REGISTER_BODY, onRegister));
+        teardowns.push(host.onBodyEvent(UNREGISTER_BODY, onUnregister));
+        teardowns.push(host.onBodyEvent(UPDATE_BODY, onUpdateBody));
+    }
     onScroll();
     raf = host.raf(frame);
     const handle = {
@@ -2560,18 +3069,21 @@ export function createField(canvas, opts = {}) {
                     console.warn(`Fundamental: setRender('${mode}') could not acquire a 2d context; staying in render 'none'`);
                     return;
                 }
-                if (overlayCanvas && !overlayCtx) {
-                    overlayCtx = overlayCanvas.getContext('2d');
-                    if (overlayCtx && !overlayBackend)
-                        overlayBackend = opts.overlayBackend ?? canvas2dBackend(overlayCanvas, overlayCtx);
-                }
+                // an overlay reading is already active → bring its surface up alongside the underlay (#676).
+                if (overlayStack(cfg.overlay).length)
+                    ensureOverlaySurface();
                 sizeSurfaces(host.viewport().dpr); // the one deferred resize the lazy path needs
             }
             cfg.render = mode;
         },
         setOverlay: (mode) => {
             cfg.overlay = mode;
-            if (!overlayStack(mode).length)
+            // A non-empty reading stack resolves the overlay surface on demand (#676) — the first non-off
+            // setOverlay is where a lazily-provided canvas is created + bound. 'off'/empty just clears any
+            // surface that already exists and never forces one into being.
+            if (overlayStack(mode).length)
+                ensureOverlaySurface();
+            else
                 overlayBackend?.clear(); // empty stack → clear the front surface
         },
         setHeatmap: (on) => {
@@ -2607,10 +3119,96 @@ export function createField(canvas, opts = {}) {
             if (ctx)
                 sizeSurfaces(host.viewport().dpr); // re-apply the tier's effective DPR ceiling now
         },
+        get policy() {
+            return clonePolicy(policy); // frozen copy — callers can't mutate the live policy
+        },
+        setPolicy: (next) => {
+            // REPLACE (not merge): the field runs exactly the policy handed in. Deep-cloned so a later
+            // mutation of the caller's object can't reach in. Takes effect next frame (motion) / next call
+            // (privacy). Reduced-motion still wins in `effectiveMotion`, so this can't raise motion above it.
+            policy = clonePolicy(next);
+        },
+        forAgent: (viewOpts) => {
+            const caps = new Set(viewOpts.capabilities ?? []);
+            const redactions = (viewOpts.redactions ?? []).slice();
+            const has = (c) => caps.has(c);
+            // If a future `budgets.agentRead` budget is 0, the agent surface is closed entirely: the most
+            // restricted view (empty caps → ids + shape only). SEAM: only the 0 boundary is wired today; the
+            // fractional 0<b<1 gradient (partial agent read) is DECLARED-not-yet-enforced (see FieldBudgets).
+            const agentReadOpen = () => {
+                const b = policy.budgets?.agentRead;
+                return b == null || b > 0;
+            };
+            const scopeQuery = (q = {}) => {
+                if (!agentReadOpen()) {
+                    // closed budget → most-restricted reading: shape only, no metrics/relationships/influences.
+                    const empty = handle.query({ ...q, include: ['bodies'] });
+                    empty.metrics = {};
+                    empty.relationships = [];
+                    empty.influences = [];
+                    if (!has('read:projections'))
+                        empty.projections = [];
+                    return applyRedactions(empty, redactions);
+                }
+                // Capability scoping: intersect any requested `include` with what the caps grant, so a reading
+                // can only ever narrow. Bodies (ids + shape) are always readable — identity is the base grant.
+                const grantable = new Set(['bodies']);
+                if (has('read:metrics'))
+                    grantable.add('metrics');
+                if (has('read:relationships'))
+                    grantable.add('relationships');
+                if (has('read:influences'))
+                    grantable.add('influences');
+                const requested = q.include ? new Set(q.include) : null;
+                const include = [...grantable].filter((i) => !requested || requested.has(i));
+                const res = handle.query({ ...q, include });
+                // Belt-and-braces: strip any dimension the caps don't grant even if query populated it.
+                if (!has('read:metrics'))
+                    res.metrics = {};
+                if (!has('read:relationships'))
+                    res.relationships = [];
+                if (!has('read:influences'))
+                    res.influences = [];
+                if (!has('read:projections'))
+                    res.projections = [];
+                return applyRedactions(res, redactions);
+            };
+            const scopeSnapshot = (snapOpts = {}) => {
+                if (!agentReadOpen()) {
+                    const snap = handle.snapshot({ profile: 'public' });
+                    return applyRedactions(snap, redactions);
+                }
+                // read:body-data is the gate for opaque `data`: without it, force `includeData` off (tightens,
+                // never widens — even if a profile or explicit flag asked for it). Everything else composes with
+                // resolveSnapshotInclusion's TIGHTEST-wins rule + the field's own privacy policy downstream.
+                const scoped = { ...snapOpts };
+                if (!has('read:body-data'))
+                    scoped.includeData = false;
+                if (!has('read:relationships'))
+                    scoped.includeRelationships = false;
+                if (!has('read:influences'))
+                    scoped.includeInfluences = false;
+                const snap = handle.snapshot(scoped);
+                if (!has('read:projections'))
+                    snap.projections = [];
+                return applyRedactions(snap, redactions);
+            };
+            const view = {
+                get capabilities() { return Object.freeze([...caps]); },
+                get redactions() { return Object.freeze([...redactions]); },
+                query: scopeQuery,
+                snapshot: scopeSnapshot,
+            };
+            // `replay` is present ONLY when granted — the facade's shape reflects the capability.
+            if (has('read:replay')) {
+                view.replay = (a, b, replayOpts) => handle.replay(a, b, replayOpts);
+            }
+            return Object.freeze(view);
+        },
         threads: setThreads,
         burst: (x, y, hex) => {
             // discrete one-shot: shove + heat nearby matter, optionally tint it (§11).
-            const R = 160;
+            const R = BURST_RADIUS;
             for (const q of store.particles) {
                 // the blast point sits on the page plane (z = 0): matter off-plane is shoved
                 // deeper as well as outward — the 3D leg is 0 in a flat field (z-axis.md).
@@ -2793,6 +3391,12 @@ export function createField(canvas, opts = {}) {
             const body = bodyFromElement(el);
             body.rect = toRect;
             body.data = spec.data;
+            // first-class identity: a supplied identity pins the stable id (a bare string is shorthand for
+            // { id }); omitted ⇒ the engine derives a synthetic `body-N` on first keying. A programmatic body
+            // has no DOM id, so a supplied identity is the only way to reference it stably across snapshots.
+            if (spec.identity != null) {
+                body.identity = typeof spec.identity === 'string' ? { id: spec.identity } : spec.identity;
+            }
             if (spec.authority)
                 body.authority = spec.authority; // body-authority (doc 04); default anchored
             body.feedback = true; // programmatic bodies always compute channels (the CSS write hits the
@@ -2920,8 +3524,10 @@ export function createField(canvas, opts = {}) {
             const bodyReadings = want.has('bodies')
                 ? matched.map((b) => {
                     const { metrics, dimensions } = readBodyMetrics(b);
+                    const identity = bodyIdentity(b);
                     return {
-                        id: bodyId(b),
+                        id: identity.id,
+                        identity,
                         rect: { x: b.cx - b.hw, y: b.cy - b.hh, width: b.hw * 2, height: b.hh * 2 },
                         tokens: b.tokens.slice(),
                         metrics,
@@ -2977,12 +3583,15 @@ export function createField(canvas, opts = {}) {
             return q.lens ? applyLens(result, q.lens) : result;
         },
         snapshot: (opts = {}) => {
-            const includeRelationships = opts.includeRelationships !== false;
+            const inc = resolveSnapshotInclusion(opts);
+            const includeRelationships = inc.includeRelationships;
             const visible = bodies.filter((b) => b.vis);
             const snapBodies = visible.map((b) => {
                 const { metrics, dimensions } = readBodyMetrics(b);
+                const identity = bodyIdentity(b);
                 const reading = {
-                    id: bodyId(b),
+                    id: identity.id,
+                    identity,
                     authority: b.authority ?? 'anchored',
                     rect: { x: b.cx - b.hw, y: b.cy - b.hh, width: b.hw * 2, height: b.hh * 2 },
                     position: { x: b.cx, y: b.cy, z: 0 },
@@ -2990,7 +3599,10 @@ export function createField(canvas, opts = {}) {
                     metrics,
                     dimensions,
                 };
-                if (opts.includeData)
+                // Privacy gate: the caller must ask for data AND the policy must permit it. Policy tightens —
+                // `allowBodyDataInSnapshots === false` (or a privacy budget below threshold) withholds body
+                // `data` even when the call opts in. A policy can restrict, never widen, the call-site default.
+                if (inc.includeData && policyPermitsBodyData())
                     reading.data = cloneData(b.data);
                 return reading;
             });
@@ -3023,7 +3635,7 @@ export function createField(canvas, opts = {}) {
                 metrics: fieldMetrics,
                 projections: projectionList(),
             };
-            if (opts.includeParticles) {
+            if (inc.includeParticles) {
                 const out = [];
                 for (const p of store.particles) {
                     if (p.cap)
@@ -3032,7 +3644,7 @@ export function createField(canvas, opts = {}) {
                 }
                 snap.particles = out;
             }
-            if (opts.includeInfluences) {
+            if (inc.includeInfluences) {
                 // per-body force attribution: each body's own forces at its centre, by channel (linear Δv,
                 // thermal heat, …). A later replay() derives `cause: 'force'` steps from how these shift.
                 const inf = [];
@@ -3113,8 +3725,8 @@ export function createField(canvas, opts = {}) {
             for (const e of engaged) {
                 e.el.removeEventListener('pointerenter', e.enter);
                 e.el.removeEventListener('pointerleave', e.leave);
-                e.el.removeEventListener('focus', e.enter);
-                e.el.removeEventListener('blur', e.leave);
+                e.el.removeEventListener('focusin', e.enter);
+                e.el.removeEventListener('focusout', e.leave);
                 delete e.el.dataset.fxEngaged;
             }
             engaged = [];
@@ -3135,6 +3747,9 @@ export function createField(canvas, opts = {}) {
                     clone.remove();
             emitters = [];
             store.clear();
+            // release host-side state last (e.g. a contained host's data-field-boundary marker, #980)
+            // so an outer field re-adopts this field's bodies on its next rescan.
+            host.detach?.();
         },
     };
     return handle;