@woosh/meep-engine 3.60.3 → 3.60.5

package/src/shade/renderer/camera/orbital/OrbitalCameraController.js

@@ -1,109 +1,125 @@
 import { assert } from "../../../../core/assert.js";
-import { clamp } from "../../../../core/math/clamp.js";
 import Vector3 from "../../../../core/geom/Vector3.js";
+import { NumericInterval } from "../../../../core/math/interval/NumericInterval.js";
+import { clamp } from "../../../../core/math/clamp.js";
+import { clamp01 } from "../../../../core/math/clamp01.js";
+import { lerp } from "../../../../core/math/lerp.js";
+import { current_time_in_seconds } from "../../../../core/time/current_time_in_seconds.js";
 import { t64_equals_components } from "../../../../engine/ecs/transform/t64_equals_components.js";
 import { Transform64 } from "../../../../engine/ecs/transform/Transform64.js";
-import { current_time_in_seconds } from "../../../../core/time/current_time_in_seconds.js";
+import { OrbitalCameraRig } from "../../../../engine/graphics/camera/orbital/OrbitalCameraRig.js";
+import TopDownCameraController, {
+    computeTopDownTransform,
+    top_down_truck_in_view
+} from "../../../../engine/graphics/ecs/camera/topdown/TopDownCameraController.js";
 import KeyboardDevice from "../../../../engine/input/devices/KeyboardDevice.js";
+import { MouseEventButtons } from "../../../../engine/input/devices/mouse/MouseEventButtons.js";
 import { PointerDevice } from "../../../../engine/input/devices/PointerDevice.js";
-import { OrbitalCameraRig } from "./OrbitalCameraRig.js";
-import { OrbitalCameraInput } from "./OrbitalCameraInput.js";
-import { createOrbitalCameraConfig } from "./OrbitalCameraConfig.js";
+
+const RAD_TO_DEG = 180 / Math.PI;
 
 /**
- * Smoothed orbital camera controller — a drop-in replacement for the legacy
- * {@link ../OrbitalCameraController.js} that adds frame-rate-independent inertia
- * via meep's critically-damped springs.
- *
- * It is a thin FACADE over two decoupled, independently-testable layers:
- *   - {@link OrbitalCameraRig}   — pure control core (springs + goals, no DOM/clock)
- *   - {@link OrbitalCameraInput} — input adapter (events → rig intents, no kinematics)
+ * Seconds; a frame time beyond this is a tab coming back or a hitch, not motion to integrate.
+ * @type {number}
+ */
+const MAX_DT = 0.1;
+
+/**
+ * Orbital camera for a Shade {@link PerspectiveCamera} outside the ECS: drag to orbit, right-drag to
+ * pan, wheel to zoom, W/A/S/D to fly the target along the view.
  *
- * The facade owns only the things that genuinely need the outside world: device
- * lifecycle, the frame `dt`, writing the result onto the camera's transform, and
- * the "camera moved outside our control" detection contract. The public surface
- * ({@link look}, {@link from_transform}, {@link pan}, {@link update},
- * `distanceLimits`, `movement_speed_scale`, `camera`) matches the legacy
- * controller so switching is a single import change.
+ * The pose is a {@link TopDownCameraController} of its own, the same one an ECS camera carries, and
+ * an {@link OrbitalCameraRig} moves it with the feel every orbital camera in the engine shares. Each
+ * {@link update} writes the pose onto the camera's transform, and a transform moved by anyone else
+ * since is adopted as the new pose instead.
  *
- * @author Alex Goldring (orbital rework)
+ * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
 export class OrbitalCameraController {
+    /**
+     * Zoom range, world units. Mutate `.min`/`.max` or `set()`; it applies from the next
+     * {@link look} or {@link update}.
+     * @type {NumericInterval}
+     */
+    distanceLimits = new NumericInterval(0.1, 1000);
+
+    /**
+     * W/A/S/D speed, world units a second with the camera at the near end of {@link distanceLimits},
+     * rising to twice that at the far end.
+     * @type {number}
+     */
+    movement_speed_scale = 1;
+
+    /**
+     * @type {TopDownCameraController}
+     */
+    pose = new TopDownCameraController();
+
+    /**
+     * the camera transform as this last left it, to tell when someone else moved it
+     * @type {Transform64}
+     */
+    #last_recorded = new Transform64();
+
+    /**
+     * the pose as last written, so a pose that did not change is not written again
+     * @type {TopDownCameraController}
+     */
+    #last_pose = new TopDownCameraController();
+
+    /**
+     * @type {number}
+     */
+    #last_update_time = current_time_in_seconds();
+
+    #scratch_eye = new Vector3();
+    #scratch_target = new Vector3();
+
     /**
      * @param {import("../PerspectiveCamera.js").PerspectiveCamera} camera
      * @param {HTMLElement} domElement
-     * @param {Partial<import("./OrbitalCameraConfig.js").ORBITAL_CAMERA_FEEL_DEFAULTS>} [configOverrides]
      */
-    constructor(camera, domElement, configOverrides) {
+    constructor(camera, domElement) {
         this.camera = camera;
         this.domElement = domElement;
 
-        this.config = createOrbitalCameraConfig(configOverrides);
+        this.pose.distance = 1;
+        this.#apply_distance_limits();
+
+        this.rig = new OrbitalCameraRig(this.pose, {
+            orbit_buttons: MouseEventButtons.primary,
+            pan_buttons: MouseEventButtons.secondary,
+            pitch_min: -Math.PI / 2,
+            pitch_max: Math.PI / 2,
+            pan_axes: Vector3.one
+        });
 
-        // ── devices (the facade owns their lifecycle) ───────────────────────
         this.pointer = new PointerDevice(domElement);
-        this.pointer.domElement = domElement;
+        this.pointer.on.dragStart.add(this.#handle_drag_start, this);
+        this.pointer.on.drag.add(this.#handle_drag, this);
+        this.pointer.on.dragEnd.add(this.#handle_drag_end, this);
+        this.pointer.on.wheel.add(this.#handle_wheel, this);
         this.pointer.start();
 
         this.keyboard = new KeyboardDevice(domElement);
-        this.keyboard.domElement = domElement;
         this.keyboard.start();
 
-        // ── layers ──────────────────────────────────────────────────────────
-        this.rig = new OrbitalCameraRig({ config: this.config });
-
-        this.input = new OrbitalCameraInput({
-            rig: this.rig,
-            pointer: this.pointer,
-            keyboard: this.keyboard,
-            viewport: domElement,
-            lens: camera,
-            config: this.config,
-        });
-        this.input.connect();
-
-        // ── frame bookkeeping ───────────────────────────────────────────────
-        this._lastRecorded = new Transform64();
-        // seed so the first no-arg update() sees ~0 dt instead of the page lifetime
-        this._lastUpdateTime = current_time_in_seconds();
-        this._scratchEye = new Vector3();
-        this._scratchTarget = new Vector3();
-
-        // adopt the camera's current pose
         this.from_transform(camera.transform);
     }
 
-    // ─────────────────────────────────────────────────────────────────────────
-    //  Public API (legacy-compatible)
-    // ─────────────────────────────────────────────────────────────────────────
-
-    /** Zoom range, in world units (NumericInterval). Mutate `.min/.max` or `.set()`. */
-    get distanceLimits() {
-        return this.rig.distanceLimits;
-    }
-
-    /** Scene-relative WASD/keyboard move speed. */
-    get movement_speed_scale() {
-        return this.rig.movementSpeedScale;
-    }
-
-    set movement_speed_scale(value) {
-        this.rig.movementSpeedScale = value;
-    }
-
-    /** Current smoothed orbit distance (radius). */
+    /** Orbit distance, world units. */
     get distance() {
-        return this.rig.distance;
+        return this.pose.distance;
     }
 
-    /** Current smoothed target (shared scratch — copy if you need to retain it). */
+    /** Orbit target, live: copy it to keep it. */
     get target() {
-        return this.rig.getTarget();
+        return this.pose.target;
     }
 
     /**
-     * Point the camera at `to` from `from`, immediately (no animation).
+     * Point the camera at `to` from `from`, at once, stopping any throw.
      * @param {Vector3} from
      * @param {Vector3} to
      */
@@ -111,127 +127,161 @@ export class OrbitalCameraController {
         assert.defined(from, "from");
         assert.defined(to, "to");
 
-        this.rig.frameTo(from, to, { animate: false });
-        // apply immediately so a subsequent at-rest update() doesn't skip the write
-        this.rig.composeTransform(this.camera.transform);
-        this._lastRecorded.copy(this.camera.transform);
-    }
+        const pose = this.pose;
 
-    /**
-     * Eased "fly to" framing: glide to the new pose over {@link config}.flyToHalfLife
-     * instead of snapping. The normal update() loop animates it.
-     * @param {Vector3} from
-     * @param {Vector3} to
-     */
-    flyTo(from, to) {
-        assert.defined(from, "from");
-        assert.defined(to, "to");
+        this.rig.stop();
+
+        pose.setFromEyeAndTarget(from, to);
+
+        // the eye is kept within the zoom range rather than widening the range to fit it
+        this.#apply_distance_limits();
+        pose.distance = clamp(pose.distance, pose.distanceMin, pose.distanceMax);
 
-        this.rig.frameTo(from, to, { animate: true });
-        // camera transform is unchanged this frame; keep the snapshot in sync so
-        // the animation isn't mistaken for an external mutation next update().
-        this._lastRecorded.copy(this.camera.transform);
+        this.#write();
     }
 
     /**
-     * Adopt an external camera transform as the new orbit pose (target is placed
-     * `distance` ahead along its forward).
+     * Adopt a camera transform as the pose, the target the current orbit distance ahead of it.
      *
-     * Read component-wise rather than through `Vector3.copy`, because a
-     * {@link Transform64} answers `forward` and `translation` with raw
-     * `Float64Array`s — no `.x`, and a `copy` of one silently sets three
-     * undefineds. Those two arrays are also freshly allocated per access, so
-     * each is read once into a scratch that outlives the call.
+     * Read by component, because a {@link Transform64} answers `forward` with a raw `Float64Array`,
+     * allocated on each access.
      *
      * @param {Transform64} transform
      */
     from_transform(transform) {
         const forward = transform.forward;
 
-        const distance = this.rig.distance;
+        const distance = this.pose.distance;
 
-        this._scratchEye.set(
+        this.#scratch_eye.set(
             transform.translation_x,
             transform.translation_y,
             transform.translation_z
         );
 
-        this._scratchTarget.set(
-            this._scratchEye.x + forward[0] * distance,
-            this._scratchEye.y + forward[1] * distance,
-            this._scratchEye.z + forward[2] * distance
+        this.#scratch_target.set(
+            this.#scratch_eye.x + forward[0] * distance,
+            this.#scratch_eye.y + forward[1] * distance,
+            this.#scratch_eye.z + forward[2] * distance
         );
 
-        this.look(this._scratchEye, this._scratchTarget);
+        this.look(this.#scratch_eye, this.#scratch_target);
     }
 
     /**
-     * Screen-space pan of the orbit target, in pointer pixels (legacy signature).
-     * @param {number} delta_x
-     * @param {number} delta_y
-     */
-    pan(delta_x, delta_y) {
-        this.rig.panScreen(delta_x, delta_y, this.domElement.clientHeight, this.camera.fov);
-    }
-
-    /**
-     * Advance one frame and write the result onto the camera transform.
+     * Advance one frame and write the pose onto the camera transform.
      *
-     * @param {number} [dt] frame time in seconds. STRONGLY preferred — pass the
-     *   value `create_frame_loop` already hands the callback. Omit to fall back
-     *   to an internal clock (clamped, so no first-frame teleport).
+     * @param {number} [dt] frame time in seconds; `create_frame_loop` hands it to its callback. Omit
+     * it to measure the time since the last call instead.
      */
     update(dt) {
-        const frameDt = this._resolveDt(dt);
+        const frame_dt = this.#resolve_dt(dt);
 
-        // continuous (held-key) input → rig intents
-        this.input.update(frameDt);
+        this.#apply_distance_limits();
 
-        const camTransform = this.camera.transform;
+        if (!t64_equals_components(this.#last_recorded, this.camera.transform)) {
+            // moved outside our control: that is the pose now
+            this.from_transform(this.camera.transform);
 
-        if (!t64_equals_components(this._lastRecorded, camTransform)) {
-            // camera was moved outside our control — adopt it, skip integration
-            this.from_transform(camTransform);
-        } else {
-            const moved = this.rig.update(frameDt);
-            if (moved) {
-                this.rig.composeTransform(camTransform);
-            }
+            return;
         }
 
-        this._lastRecorded.copy(camTransform);
+        this.#truck(frame_dt);
+
+        this.rig.update(frame_dt);
+
+        if (!this.pose.equals(this.#last_pose)) {
+            this.#write();
+        }
     }
 
-    /** Detach input subscriptions and stop the devices. */
+    /** Detach input and stop the devices. */
     dispose() {
-        this.input.disconnect();
-        this.pointer.stop?.();
-        this.keyboard.stop?.();
+        this.pointer.on.dragStart.remove(this.#handle_drag_start, this);
+        this.pointer.on.drag.remove(this.#handle_drag, this);
+        this.pointer.on.dragEnd.remove(this.#handle_drag_end, this);
+        this.pointer.on.wheel.remove(this.#handle_wheel, this);
+        this.pointer.stop();
+
+        this.keyboard.stop();
+    }
+
+    #write() {
+        computeTopDownTransform(this.pose, this.camera.transform);
+
+        this.#last_pose.copy(this.pose);
+        this.#last_recorded.copy(this.camera.transform);
+    }
+
+    #apply_distance_limits() {
+        this.pose.distanceMin = this.distanceLimits.min;
+        this.pose.distanceMax = this.distanceLimits.max;
+    }
+
+    /**
+     * @param {number} dt seconds
+     */
+    #truck(dt) {
+        const keys = this.keyboard.keys;
+
+        const right = (keys.d?.is_down ? 1 : 0) - (keys.a?.is_down ? 1 : 0);
+        const forward = (keys.w?.is_down ? 1 : 0) - (keys.s?.is_down ? 1 : 0);
+
+        if (right === 0 && forward === 0) {
+            return;
+        }
+
+        const zoom_scale = lerp(1, 2, clamp01(this.distanceLimits.normalizeValue(this.pose.distance)));
+
+        top_down_truck_in_view(this.pose, right, forward, this.movement_speed_scale * zoom_scale * dt);
+    }
+
+    /**
+     * @param {Vector2} origin
+     * @param {PointerEvent} event
+     */
+    #handle_drag_start(origin, event) {
+        this.rig.begin(event.buttons);
+    }
+
+    /**
+     * @param {Vector2} position
+     * @param {Vector2} origin
+     * @param {Vector2} last_position
+     */
+    #handle_drag(position, origin, last_position) {
+        this.rig.move(
+            position.x - last_position.x,
+            position.y - last_position.y,
+            this.domElement.clientHeight,
+            this.camera.fov * RAD_TO_DEG
+        );
     }
 
-    // ─────────────────────────────────────────────────────────────────────────
-    //  Internals
-    // ─────────────────────────────────────────────────────────────────────────
+    #handle_drag_end() {
+        this.rig.end();
+    }
+
+    /**
+     * @param {Vector3} delta signs of the wheel's motion
+     */
+    #handle_wheel(delta) {
+        this.#apply_distance_limits();
+
+        this.rig.dolly(delta.y);
+    }
 
     /**
-     * Resolve and sanitize the frame dt. Prefers the supplied value; otherwise
-     * derives it from an internal clock. Always clamped to [0, maxDt] so a tab
-     * refocus / GC hitch can't make the springs jump.
      * @param {number} [dt]
-     * @returns {number}
+     * @returns {number} seconds, within [0, {@link MAX_DT}]
      */
-    _resolveDt(dt) {
+    #resolve_dt(dt) {
         const now = current_time_in_seconds();
 
-        let d;
-        if (typeof dt === "number" && Number.isFinite(dt)) {
-            d = dt;
-        } else {
-            d = now - this._lastUpdateTime;
-        }
+        const elapsed = (typeof dt === "number" && Number.isFinite(dt)) ? dt : now - this.#last_update_time;
 
-        this._lastUpdateTime = now;
+        this.#last_update_time = now;
 
-        return clamp(d, 0, this.config.maxDt);
+        return clamp(elapsed, 0, MAX_DT);
     }
 }

package/src/shade/renderer/fluid/GPUFluidCascade.d.ts

@@ -143,7 +143,7 @@ export class GPUFluidCascade {
      * @param {*} _resources
      * @param {{encoder: ShadeGPUCommandContext}} context
      */
-    static "__#277@#execute_restrict"(record: object, _resources: any, context: {
+    static "__#279@#execute_restrict"(record: object, _resources: any, context: {
         encoder: ShadeGPUCommandContext;
     }): void;
     /**
@@ -151,7 +151,7 @@ export class GPUFluidCascade {
      * @param {*} _resources
      * @param {{encoder: ShadeGPUCommandContext}} context
      */
-    static "__#277@#execute_fill"(record: object, _resources: any, context: {
+    static "__#279@#execute_fill"(record: object, _resources: any, context: {
         encoder: ShadeGPUCommandContext;
     }): void;
     /**
@@ -159,7 +159,7 @@ export class GPUFluidCascade {
      * @param {import("../../../engine/graphics/render/frame_graph/FramePassResources.js").FramePassResources} resources
      * @param {{encoder: ShadeGPUCommandContext}} context
      */
-    static "__#277@#execute"(record: object, resources: import("../../../engine/graphics/render/frame_graph/FramePassResources.js").FramePassResources, context: {
+    static "__#279@#execute"(record: object, resources: import("../../../engine/graphics/render/frame_graph/FramePassResources.js").FramePassResources, context: {
         encoder: ShadeGPUCommandContext;
     }): void;
     /**

package/src/shade/renderer/fluid/GPUFluidCascadeStack.d.ts

@@ -63,7 +63,7 @@ export class GPUFluidCascadeStack {
      * @param {*} _resources
      * @param {{encoder: import("../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext}} context
      */
-    static "__#279@#execute_publish"(pass: object, _resources: any, context: {
+    static "__#281@#execute_publish"(pass: object, _resources: any, context: {
         encoder: import("../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext;
     }): void;
     /**

package/src/shade/renderer/fluid/forcing/GPUFluidForcing.d.ts

@@ -90,19 +90,19 @@ export class GPUFluidForcing {
      * @param {number} clear_size bytes cleared from 0 when the pool reuses the buffer
      * @returns {BufferResourceDescriptor}
      */
-    static "__#280@#descriptor"(kept: BufferResourceDescriptor[], role: number, size: number, usage: number, clear_size: number): BufferResourceDescriptor;
+    static "__#282@#descriptor"(kept: BufferResourceDescriptor[], role: number, size: number, usage: number, clear_size: number): BufferResourceDescriptor;
     /**
      * @param {object} record
      * @param {FramePassResources} resources
      * @param {{encoder: ShadeGPUCommandContext}} context
      */
-    static "__#280@#execute_extract"(record: object, resources: FramePassResources, context: {
+    static "__#282@#execute_extract"(record: object, resources: FramePassResources, context: {
         encoder: ShadeGPUCommandContext;
     }): void;
-    static "__#280@#execute_clear"(record: any, _resources: any, context: any): void;
-    static "__#280@#execute_query"(record: any, resources: any, context: any): void;
-    static "__#280@#execute_command"(record: any, resources: any, context: any): void;
-    static "__#280@#execute_apply"(record: any, resources: any, context: any): void;
+    static "__#282@#execute_clear"(record: any, _resources: any, context: any): void;
+    static "__#282@#execute_query"(record: any, resources: any, context: any): void;
+    static "__#282@#execute_command"(record: any, resources: any, context: any): void;
+    static "__#282@#execute_apply"(record: any, resources: any, context: any): void;
     /**
      * @param {object} options
      * @param {GPUDevice} options.device

package/src/shade/renderer/fluid/pressure/GPUFluidPressureSolve.d.ts

@@ -41,7 +41,7 @@ export class GPUFluidPressureSolve {
      * @param {*} _resources
      * @param {{encoder: ShadeGPUCommandContext}} context
      */
-    static "__#276@#execute"(data: {
+    static "__#278@#execute"(data: {
         solve: GPUFluidPressureSolve;
         arm: number;
         count: number;

package/src/shade/renderer/fluid/query/GPUFluidQueries.d.ts

@@ -49,7 +49,7 @@ export class GPUFluidQueries {
      * @param {import("../../../../engine/graphics/render/frame_graph/FramePassResources.js").FramePassResources} resources
      * @param {{encoder: import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext}} context
      */
-    static "__#281@#execute"(pass: object, resources: import("../../../../engine/graphics/render/frame_graph/FramePassResources.js").FramePassResources, context: {
+    static "__#283@#execute"(pass: object, resources: import("../../../../engine/graphics/render/frame_graph/FramePassResources.js").FramePassResources, context: {
         encoder: import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext;
     }): void;
     /**

package/src/shade/renderer/geometry/sdf/GPUGeometrySDFManager.d.ts

@@ -17,8 +17,8 @@ export const MESH_SDF_BAKE_BUDGET_MAX: number;
  * {@link alias} points a skinned clone's id at its source's cache, which readers follow.
  *
  * **Side.** A holder says whether it draws both sides of the geometry. A field is baked two-sided
- * while any of its holders does: its vote then counts no back face, so nothing is inside it (UE 5.4's
- * rule, which takes the side from the material). A field whose holders' side has changed since its
+ * while any of its holders does: its vote then counts no back face, so nothing is inside it.
+ * A field whose holders' side has changed since its
  * bake is baked again at the next bake, so holds moved within a frame bake nothing; a field no one
  * holds keeps the side it has.
  *
@@ -245,8 +245,8 @@ export class GPUGeometrySDFManager {
      * @param {number} options.budget bricks evaluated at most, `mesh_sdf_bake_budget`
      * @param {number} [options.capture_budget] card pages captured at most, `card_capture_budget`; 0
      *        captures nothing
-     * @param {GPUResidentMaterialContext|null} [options.materials] what the capture shades with, as it
-     *        stands this frame; needed with a `capture_budget`
+     * @param {GPUResidentMaterialContext|null} [options.materials] what a traced capture shades with,
+     *        which makes what it traces resident; needed with a `capture_budget`
      * @param {GPUMaterialManager|null} [options.material_contexts] what a raster capture draws with
      *        ({@link GPUMeshCardSets#capture_mode}); needed with a `capture_budget` in that mode
      */

package/src/shade/renderer/geometry/sdf/GPUGeometrySDFManager.js

@@ -207,8 +207,8 @@ function grow_typed(array, length) {
  * {@link alias} points a skinned clone's id at its source's cache, which readers follow.
  *
  * **Side.** A holder says whether it draws both sides of the geometry. A field is baked two-sided
- * while any of its holders does: its vote then counts no back face, so nothing is inside it (UE 5.4's
- * rule, which takes the side from the material). A field whose holders' side has changed since its
+ * while any of its holders does: its vote then counts no back face, so nothing is inside it.
+ * A field whose holders' side has changed since its
  * bake is baked again at the next bake, so holds moved within a frame bake nothing; a field no one
  * holds keeps the side it has.
  *
@@ -980,8 +980,8 @@ export class GPUGeometrySDFManager {
      * @param {number} options.budget bricks evaluated at most, `mesh_sdf_bake_budget`
      * @param {number} [options.capture_budget] card pages captured at most, `card_capture_budget`; 0
      *        captures nothing
-     * @param {GPUResidentMaterialContext|null} [options.materials] what the capture shades with, as it
-     *        stands this frame; needed with a `capture_budget`
+     * @param {GPUResidentMaterialContext|null} [options.materials] what a traced capture shades with,
+     *        which makes what it traces resident; needed with a `capture_budget`
      * @param {GPUMaterialManager|null} [options.material_contexts] what a raster capture draws with
      *        ({@link GPUMeshCardSets#capture_mode}); needed with a `capture_budget` in that mode
      */

package/src/shade/renderer/geometry/sdf/cards/GPUMeshCardSets.d.ts

@@ -162,7 +162,8 @@ export class GPUMeshCardSets {
      * @param {number} options.budget pages captured at most, `card_capture_budget`
      * @param {number} options.arena graph handle of the arena, as the frame's bake left it
      * @param {GPUBuffer} options.headers
-     * @param {GPUResidentMaterialContext} options.materials what the trace shades with
+     * @param {GPUResidentMaterialContext} options.materials what the trace shades with: each traced
+     *        material is made resident, and the rows committed, before the trace is recorded
      * @param {GPUMaterialManager} options.material_contexts what the raster draws with: each
      *        material's template and bind group
      * @param {Object} options.blas the geometry bindings `ray_query_blas_nearest` reads, whose

package/src/shade/renderer/geometry/sdf/cards/GPUMeshCardSets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUMeshCardSets.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/sdf/cards/GPUMeshCardSets.js"],"names":[],"mappings":"AAyEA;;;;;;GAMG;AACH,sDAHW,aAAa,GACX,MAAM,CAUlB;AApCD;;;GAGG;AACH,2CAFU,MAAM,CAEmF;AA0DnG;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IAmLI;;OAEG;IACH,+BAIC;IAnLD;;;OAGG;IACH,gBAA0B;IAE1B;;;OAGG;IACH,iBAA2B;IA2K3B;;;OAGG;IACH,oBAUC;IAED;;OAEG;IACH,6BAEC;IAED;;;OAGG;IACH,mCAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;;OAIG;IACH,mCAIC;IAED;;;OAGG;IACH,2BAcC;IASD;;;;;OAKG;IACH,+BAgBC;IA7BD;;OAEG;IACH,2BAEC;IA0BD;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,yBAIC;IAED;;;OAGG;IACH,4BAIC;IAED;;;;;;OAMG;IACH,kBAJW,MAAM,YACN,aAAa,GACX,MAAM,CA+BlB;IAED;;OAEG;IACH,YAFW,MAAM,QA2BhB;IAED;;;;;OAKG;IACH,cAFW,MAAM,QAqBhB;IAED;;;;;;;OAOG;IACH,qBALW,MAAM,SACN,MAAM,QACN,MAAM,QAqBhB;IAED;;;;OAIG;IACH,sBAFW,MAAM,QA+BhB;IAuSD;;;;;;;;;;;;;;;OAeG;IACH;QAV+B,KAAK,EAAzB,UAAU;QACM,MAAM,EAAtB,MAAM;QACU,KAAK,EAArB,MAAM;QACa,OAAO;QACU,SAAS,EAA7C,0BAA0B;QACE,iBAAiB,EAA7C,kBAAkB;QAEF,IAAI;aAiG9B;IAiTD;;OAEG;IACH,+BAuBC;IAED,gBAoBC;;CACJ;yBA70CY,OAAO,iEAAiE,EAAE,UAAU;4BACpF,OAAO,oCAAoC,EAAE,aAAa;yCAC1D,OAAO,0DAA0D,EAAE,0BAA0B;iCAC7F,OAAO,yCAAyC,EAAE,kBAAkB;iCACpE,OAAO,yCAAyC,EAAE,kBAAkB;yBACpE,OAAO,yDAAyD,EAAE,UAAU;+BAxB1D,0CAA0C"}
+{"version":3,"file":"GPUMeshCardSets.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/sdf/cards/GPUMeshCardSets.js"],"names":[],"mappings":"AAyEA;;;;;;GAMG;AACH,sDAHW,aAAa,GACX,MAAM,CAUlB;AApCD;;;GAGG;AACH,2CAFU,MAAM,CAEmF;AA0DnG;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IA2LI;;OAEG;IACH,+BAIC;IA3LD;;;OAGG;IACH,gBAA0B;IAE1B;;;OAGG;IACH,iBAA2B;IAmL3B;;;OAGG;IACH,oBAUC;IAED;;OAEG;IACH,6BAEC;IAED;;;OAGG;IACH,mCAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;;OAIG;IACH,mCAIC;IAED;;;OAGG;IACH,2BAcC;IASD;;;;;OAKG;IACH,+BAgBC;IA7BD;;OAEG;IACH,2BAEC;IA0BD;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,yBAIC;IAED;;;OAGG;IACH,4BAIC;IAED;;;;;;OAMG;IACH,kBAJW,MAAM,YACN,aAAa,GACX,MAAM,CA+BlB;IAED;;OAEG;IACH,YAFW,MAAM,QA2BhB;IAED;;;;;OAKG;IACH,cAFW,MAAM,QAqBhB;IAED;;;;;;;OAOG;IACH,qBALW,MAAM,SACN,MAAM,QACN,MAAM,QAqBhB;IAED;;;;OAIG;IACH,sBAFW,MAAM,QA+BhB;IA0SD;;;;;;;;;;;;;;;;OAgBG;IACH;QAX+B,KAAK,EAAzB,UAAU;QACM,MAAM,EAAtB,MAAM;QACU,KAAK,EAArB,MAAM;QACa,OAAO;QACU,SAAS,EAA7C,0BAA0B;QAEE,iBAAiB,EAA7C,kBAAkB;QAEF,IAAI;aAsG9B;IAiTD;;OAEG;IACH,+BAuBC;IAED,gBAoBC;;CACJ;yBA91CY,OAAO,iEAAiE,EAAE,UAAU;4BACpF,OAAO,oCAAoC,EAAE,aAAa;yCAC1D,OAAO,0DAA0D,EAAE,0BAA0B;iCAC7F,OAAO,yCAAyC,EAAE,kBAAkB;iCACpE,OAAO,yCAAyC,EAAE,kBAAkB;yBACpE,OAAO,yDAAyD,EAAE,UAAU;+BAxB1D,0CAA0C"}

package/src/shade/renderer/geometry/sdf/cards/GPUMeshCardSets.js

@@ -265,6 +265,14 @@ export class GPUMeshCardSets {
      */
     #frame_material_contexts = null;
 
+    /**
+     * What a frame's capture traces with: set by {@link graph_capture}. Only what is traced is made
+     * resident, each run's material as its run is taken, so a frame that traces nothing leaves the
+     * resident materials as they were.
+     * @type {GPUResidentMaterialContext|null}
+     */
+    #frame_materials = null;
+
     // the frame's shelves in the scratch
     #shelf_x = 0;
     #shelf_y = 0;
@@ -787,6 +795,9 @@ export class GPUMeshCardSets {
                 // a template that cannot be drawn this way is traced
             }
 
+            // its row as the material stands now, repacked if it has moved since
+            this.#frame_materials.obtain_material(this.#material[id]);
+
             const first = this.#next_page[id];
             const count = Math.min(pages - first, this.#frame_left);
 
@@ -930,7 +941,8 @@ export class GPUMeshCardSets {
      * @param {number} options.budget pages captured at most, `card_capture_budget`
      * @param {number} options.arena graph handle of the arena, as the frame's bake left it
      * @param {GPUBuffer} options.headers
-     * @param {GPUResidentMaterialContext} options.materials what the trace shades with
+     * @param {GPUResidentMaterialContext} options.materials what the trace shades with: each traced
+     *        material is made resident, and the rows committed, before the trace is recorded
      * @param {GPUMaterialManager} options.material_contexts what the raster draws with: each
      *        material's template and bind group
      * @param {Object} options.blas the geometry bindings `ray_query_blas_nearest` reads, whose
@@ -947,10 +959,12 @@ export class GPUMeshCardSets {
         }
 
         this.#frame_material_contexts = material_contexts;
+        this.#frame_materials = materials;
 
         this.#take(budget);
 
         this.#frame_material_contexts = null;
+        this.#frame_materials = null;
 
         const completed = this.#completed;
 
@@ -961,6 +975,9 @@ export class GPUMeshCardSets {
             let emissive = graph_import_texture(graph, this.#atlas.texture_at(1), "mesh_card_emissive");
 
             if (this.#frame_runs > 0) {
+                // what the runs' materials made resident, written before the trace reads it
+                materials.commit();
+
                 this.#ensure_runs(this.#frame_runs);
 
                 this.#device.queue.writeBuffer(this.#runs, 0, this.#run_scratch, 0, 4 * this.#frame_runs);