@woosh/meep-engine 3.14.6 → 3.16.0

package/src/shade/renderer/buffer/table/GPUTypedTableDescriptor.js

@@ -175,6 +175,13 @@ export class GPUTypedTableDescriptor {
      */
     #chunks_iterate = new Map();
 
+    /**
+     * Cache of {@link wgsl_gen_read_field_code} results, keyed by field name.
+     *
+     * @type {Map<string, CodeChunk>}
+     */
+    #chunks_read_field = new Map();
+
     /**
      *
      * @returns {CodeChunk}
@@ -238,6 +245,22 @@ export class GPUTypedTableDescriptor {
         return chunk;
     }
 
+    /**
+     * Cached {@link wgsl_gen_read_field_code} chunk for one field of this
+     * table's record type.
+     *
+     * @param {string} field_name
+     * @returns {CodeChunk}
+     */
+    chunk_read_field(field_name) {
+        let chunk = this.#chunks_read_field.get(field_name);
+        if (chunk === undefined) {
+            chunk = this.wgsl_gen_read_field_code(field_name);
+            this.#chunks_read_field.set(field_name, chunk);
+        }
+        return chunk;
+    }
+
     /**
      *
      * @returns {string}
@@ -292,6 +315,16 @@ export class GPUTypedTableDescriptor {
         return `database_write_${this.marshalling_tag}_element_${field_name}`;
     }
 
+    /**
+     * Name of the function that reads only one field of a record.
+     * Pair with {@link wgsl_gen_read_field_code} to emit the body.
+     * @param {string} field_name
+     * @returns {string}
+     */
+    marshalling_method_read_field(field_name) {
+        return `database_read_${this.marshalling_tag}_element_${field_name}`;
+    }
+
     /**
      * Name prefix for all WGSL symbols generated by {@link wgsl_gen_iterate_code}
      * for the given workgroup size. Helpers append `_setup`, `_is_occupied`,
@@ -670,6 +703,57 @@ fn ${prefix}_read(
         );
     }
 
+    /**
+     * Generate a reader that touches only a single struct field of a record.
+     *
+     * The whole-record reader deserializes every field — for a wide record that
+     * is a lot of loads to reach one word. A pass that runs per particle rather
+     * than per record (the simulation-order histogram reads nothing but the
+     * emitter's program id) pays that on every invocation.
+     *
+     * Only struct-typed records support this — other shapes have no field
+     * concept. The field's WGSL type is mirrored in the return type.
+     *
+     * @param {string} field_name
+     * @returns {CodeChunk}
+     */
+    wgsl_gen_read_field_code(field_name) {
+        assert.isString(field_name, 'field_name');
+
+        /**
+         *
+         * @type {WebGPUStruct}
+         */
+        const type = this.type;
+
+        assert.equal(type.isStruct, true, 'wgsl_gen_read_field_code requires a struct-typed record');
+
+        const field = type.get(field_name);
+        const field_type = field.type;
+        const field_offset_words = field.offset / GPU_DATABASE_BUFFER_ELEMENT_TYPE.size;
+        assert.isNonNegativeInteger(field_offset_words, 'field_offset_words');
+
+        const lines = new LineBuilder();
+
+        const fn_name = this.marshalling_method_read_field(field_name);
+
+        lines.add(`fn ${fn_name}(database: ptr<storage, array<${GPU_DATABASE_BUFFER_ELEMENT_TYPE.wgsl_ref}>>, index: u32) -> ${field_type.wgsl_ref} {`);
+        lines.indent();
+
+        this.#wgsl_gen_element_offset(lines);
+
+        lines.add(`return `);
+        table_wgsl_gen_read_code(lines, field_offset_words, "database", field_type);
+        lines.extend(';');
+
+        lines.dedent();
+        lines.add(`}`);
+
+        const dependencies = field_type.requires_declaration ? [field_type.declaration_chunk] : [];
+
+        return CodeChunk.from(lines.build(), dependencies);
+    }
+
     /**
      * Generate a writer that touches only a single struct field of a record.
      *

package/src/shade/renderer/buffer/table/gpu_database_emulator_image.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Build the `array<u32>` image of a {@link GPUDatabase} — the exact bytes the generated marshalling
+ * functions ({@link GPUTypedTableDescriptor#chunk_read} and friends) index: the page address table,
+ * then pages at the addresses it names, each page's records past its
+ * `[u32 live_count][u32 occupancy_bitmap...]` header.
+ *
+ * This exists for the WGSL emulator. The production route to those bytes is a compute dispatch
+ * ({@link ./gpu_table_element_upload_shader.js}) against a live device, and the software device
+ * records dispatches without running them — so a spec that wants to run a database-reading shader
+ * on the CPU has no way to obtain a filled buffer. Everything here is derived from the descriptor's
+ * own published geometry (`page_lookup_address`, `elements_per_page`, `page_header_words`,
+ * `packed_element_size_bytes`), which is the same geometry the upload shader receives as its
+ * settings, so the two cannot drift apart silently.
+ *
+ * Pages are allocated in ascending (table index, page index) order — the addresses therefore differ
+ * from what a live database's slot allocator would hand out for the same writes. Nothing reads a
+ * page address except through the table, so the layout is equivalent, not identical.
+ *
+ * @param {GPUDatabaseDefinition} definition
+ * @param {Object<string, Iterable<[number, *]>>} contents records per table name, as
+ *        `[element_index, value]` pairs (a `Map`, or an array of pairs)
+ * @returns {Uint32Array}
+ */
+export function gpu_database_emulator_image(definition: GPUDatabaseDefinition, contents: {
+    [x: string]: Iterable<[number, any]>;
+}): Uint32Array;
+//# sourceMappingURL=gpu_database_emulator_image.d.ts.map

package/src/shade/renderer/buffer/table/gpu_database_emulator_image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu_database_emulator_image.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/gpu_database_emulator_image.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;QAJkB,MAAM,GAAE,SAAS,CAAC,MAAM,MAAI,CAAC;IAElC,WAAW,CAwFvB"}

package/src/shade/renderer/buffer/table/gpu_database_words.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A `GPUDatabase` as the flat `array<u32>` its shaders bind — laid out from the CPU side, for
+ * running those shaders under the WGSL emulator.
+ *
+ * On a device the rows reach the buffer through the database's upload dispatch, and the software
+ * device records dispatches without running them, so a spec that wants a shader to read real rows
+ * has to produce the bytes itself. This is the one place that knows how: the page address table at
+ * the front, then each resident page at the address the database's own allocator gave it, holding
+ * its `[live_count][occupancy bitmap]` header and its records — every number taken from the
+ * descriptors and the page metadata the database keeps, which is where the generated WGSL readers
+ * and the page iterator get theirs too.
+ *
+ * Flushes the database first, on a command context of the caller's graphics, because a page gets
+ * its address from the flush: before it, every page is CPU-only and has no address to lay out at.
+ * Nothing is read back — the words are assembled from the CPU page shadows the flush leaves in
+ * place.
+ *
+ * @param {import("./GPUDatabase.js").GPUDatabase} database
+ * @param {import("../../GraphicsContext.js").GraphicsContext} graphics the context the database was
+ *        created against; the flush records onto a command context of it
+ * @returns {Uint32Array} the buffer contents, `database.buffer.size` bytes
+ */
+export function gpu_database_words(database: import("./GPUDatabase.js").GPUDatabase, graphics: import("../../GraphicsContext.js").GraphicsContext): Uint32Array;
+//# sourceMappingURL=gpu_database_words.d.ts.map

package/src/shade/renderer/buffer/table/gpu_database_words.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu_database_words.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/gpu_database_words.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,6CALW,OAAO,kBAAkB,EAAE,WAAW,YACtC,OAAO,0BAA0B,EAAE,eAAe,GAEhD,WAAW,CAmEvB"}

package/src/shade/renderer/buffer/table/gpu_database_words.js

@@ -0,0 +1,92 @@
+import { assert } from "../../../../core/assert.js";
+import { ShadeGPUCommandContext } from "../../../device/ShadeGPUCommandContext.js";
+import { GPU_DATABASE_BUFFER_ELEMENT_TYPE } from "./GPU_DATABASE_BUFFER_ELEMENT_TYPE.js";
+
+/**
+ * A `GPUDatabase` as the flat `array<u32>` its shaders bind — laid out from the CPU side, for
+ * running those shaders under the WGSL emulator.
+ *
+ * On a device the rows reach the buffer through the database's upload dispatch, and the software
+ * device records dispatches without running them, so a spec that wants a shader to read real rows
+ * has to produce the bytes itself. This is the one place that knows how: the page address table at
+ * the front, then each resident page at the address the database's own allocator gave it, holding
+ * its `[live_count][occupancy bitmap]` header and its records — every number taken from the
+ * descriptors and the page metadata the database keeps, which is where the generated WGSL readers
+ * and the page iterator get theirs too.
+ *
+ * Flushes the database first, on a command context of the caller's graphics, because a page gets
+ * its address from the flush: before it, every page is CPU-only and has no address to lay out at.
+ * Nothing is read back — the words are assembled from the CPU page shadows the flush leaves in
+ * place.
+ *
+ * @param {import("./GPUDatabase.js").GPUDatabase} database
+ * @param {import("../../GraphicsContext.js").GraphicsContext} graphics the context the database was
+ *        created against; the flush records onto a command context of it
+ * @returns {Uint32Array} the buffer contents, `database.buffer.size` bytes
+ */
+export function gpu_database_words(database, graphics) {
+    assert.defined(database, 'database');
+    assert.defined(graphics, 'graphics');
+
+    const cmd = ShadeGPUCommandContext.create(graphics, 'gpu_database_words/flush');
+    database.update(cmd);
+    cmd.finish();
+
+    const word_size = GPU_DATABASE_BUFFER_ELEMENT_TYPE.size;
+    const words = new Uint32Array(database.buffer.size / word_size);
+
+    // Unallocated page slots read as ~0 on the GPU (the allocation table is seeded with it), and
+    // the readers and iterators test for exactly that value.
+    const page_limit_words = database.data_start_offset;
+
+    for (let i = 0; i < page_limit_words; i++) {
+        words[i] = 0xffffffff;
+    }
+
+    const data_start = database.data_start_offset;
+
+    for (const table of database.tables) {
+        const descriptor = table.descriptor;
+        const record_words = descriptor.packed_element_size_bytes / word_size;
+        const elements_per_page = descriptor.elements_per_page;
+        const header_words = descriptor.page_header_words;
+
+        for (const [page_index, page] of table.pages) {
+            if (!page.is_gpu_resident) {
+                continue;
+            }
+
+            const address = page.slot_offset + data_start;
+
+            words[descriptor.page_lookup_address + page_index] = address;
+
+            // Header: live count, then the occupancy bitmap — the CPU `occupancy` BitSet is the
+            // truth for both, exactly as the database's own header upload treats it.
+            const first_element = page_index * elements_per_page;
+            let live = 0;
+
+            for (let e = 0; e < elements_per_page; e++) {
+                if (!table.occupancy.get(first_element + e)) {
+                    continue;
+                }
+
+                live++;
+                words[address + 1 + (e >> 5)] |= (1 << (e & 31)) >>> 0;
+            }
+
+            words[address] = live;
+
+            assert.defined(page.cpu_data_buffer, `page ${page_index} of '${descriptor.name}' has no CPU shadow — was the database unmapped?`);
+
+            const page_words = new Uint32Array(
+                page.cpu_data_buffer,
+                page.cpu_data_address,
+                elements_per_page * record_words,
+            );
+
+            words.set(page_words, address + header_words);
+        }
+    }
+
+    return words;
+}

package/src/shade/renderer/camera/Camera.d.ts

@@ -1,5 +1,5 @@
 export class Camera {
-    transform: Transform;
+    transform: Transform64;
     view_matrix: Float32Array;
     projection_matrix: Float32Array;
     view_projection_matrix: Float32Array;
@@ -36,5 +36,5 @@ export class Camera {
     update(): void;
     #private;
 }
-import { Transform } from "../../../engine/ecs/transform/Transform.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
 //# sourceMappingURL=Camera.d.ts.map

package/src/shade/renderer/camera/Camera.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Camera.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/camera/Camera.js"],"names":[],"mappings":"AAgFA;IAMI,qBAA4B;IAE5B,0BAA4B;IAC5B,gCAAkC;IAClC,qCAAuC;IAEvC;;;OAGG;IACH,SAFU,YAAY,CAES;IAoB/B,sBAEC;IAED,mBAEC;IAED,qBAEC;IAED,kBAEC;IAED,wBAKC;IAED,qBAEC;IAED,0BAEC;IAED,6BAEC;IAED;;;OAGG;IACH,YAFW,MAAM,QAchB;IAED,aAQC;IAED,iBAEC;IAED,eAMC;IAED;;;OAGG;IACH,cAFW,MAAM,WAQhB;IAED,wBAKC;IAED,0BAEC;IAED,2BAkDC;IAED,uBAIC;IAED,eAQC;;CACJ;0BAlRyB,4CAA4C"}
+{"version":3,"file":"Camera.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/camera/Camera.js"],"names":[],"mappings":"AAiFA;IAMI,uBAA8B;IAE9B,0BAA4B;IAC5B,gCAAkC;IAClC,qCAAuC;IAEvC;;;OAGG;IACH,SAFU,YAAY,CAES;IAoB/B,sBAEC;IAED,mBAEC;IAED,qBAEC;IAED,kBAEC;IAED,wBAKC;IAED,qBAEC;IAED,0BAEC;IAED,6BAEC;IAED;;;OAGG;IACH,YAFW,MAAM,QAchB;IAED,aAQC;IAED,iBAEC;IAED,eAMC;IAED;;;OAGG;IACH,cAFW,MAAM,WAQhB;IAED,wBAKC;IAED,0BAEC;IAED,2BAuDC;IAED,uBAIC;IAED,eAQC;;CACJ;4BAvR2B,8CAA8C"}

package/src/shade/renderer/camera/Camera.js

@@ -5,7 +5,8 @@ import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
 import { plane3_normalize } from "../../../core/geom/3d/plane/plane3_normalize.js";
 import { v3_dot } from "../../../core/geom/vec3/v3_dot.js";
 import { computeHashFloat } from "../../../core/primitives/numbers/computeHashFloat.js";
-import { Transform } from "../../../engine/ecs/transform/Transform.js";
+import { t64_equals_components } from "../../../engine/ecs/transform/t64_equals_components.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
 
 let id_counter = 0;
 
@@ -84,7 +85,7 @@ export class Camera {
      */
     #id = id_counter++;
 
-    transform = new Transform();
+    transform = new Transform64();
 
     view_matrix = m4_allocate();
     projection_matrix = m4_allocate();
@@ -197,7 +198,7 @@ export class Camera {
         return this.near === other.near
             && this.far === other.far
             && this.aspect === other.aspect
-            && this.transform.equals(other.transform)
+            && t64_equals_components(this.transform, other.transform)
             ;
     }
 
@@ -213,8 +214,13 @@ export class Camera {
     }
 
     update_view_matrix() {
-        // Direct access to the Float32Array buffer
-        const m = this.transform.matrix;
+        // A Transform64 recomposes nothing on its own, so the world matrix is refreshed here rather
+        // than at each of the several places that write the camera's rotation. One recompose per
+        // camera per frame, and no writer can forget it.
+        this.transform.updateMatrix();
+
+        // the matrix sits at offset 0, so the transform indexes as its own matrix - no view needed
+        const m = this.transform;
         const out = this.view_matrix;
 
         // 1. Extract Camera Position

package/src/shade/renderer/camera/GPUCameraContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUCameraContext.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/camera/GPUCameraContext.js"],"names":[],"mappings":"AAWA;IAyEI;;;;OAIG;IACH,+CAIC;IA9ED,iBAEC;IAED;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,QAFU,cAAc,CAEjB;IAyBP,2CAEC;IAED;;;;OAIG;IACH,qBAHW,MAAM,KACN,MAAM,QAKhB;IAED;;;OAGG;IACH,wBAEC;IAED;;;OAGG;IACH,qBAEC;IAaD,0BAMC;IAED;;;;OAIG;IACH,YAHW,gBAAgB,8CAkC1B;IAED,mBAQC;IAED,gBAEC;IAED,eAEC;;CA4EJ;+BApO8B,6BAA6B"}
+{"version":3,"file":"GPUCameraContext.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/camera/GPUCameraContext.js"],"names":[],"mappings":"AAWA;IAyEI;;;;OAIG;IACH,+CAIC;IA9ED,iBAEC;IAED;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,QAFU,cAAc,CAEjB;IAyBP,2CAEC;IAED;;;;OAIG;IACH,qBAHW,MAAM,KACN,MAAM,QAKhB;IAED;;;OAGG;IACH,wBAEC;IAED;;;OAGG;IACH,qBAEC;IAaD,0BAMC;IAED;;;;OAIG;IACH,YAHW,gBAAgB,8CAkC1B;IAED,mBAQC;IAED,gBAEC;IAED,eAEC;;CA6EJ;+BArO8B,6BAA6B"}

package/src/shade/renderer/camera/GPUCameraContext.js

@@ -184,7 +184,8 @@ export class GPUCameraContext {
         const device = this.#device;
         const queue = device.queue;
 
-        const transform_matrix = camera.transform.matrix;
+        // matrix at offset 0 - the transform is its own matrix to every m4_* primitive
+        const transform_matrix = camera.transform;
 
 
         const transform_inverse = m4_allocate();

package/src/shade/renderer/camera/OrbitalCameraController.d.ts

@@ -43,9 +43,9 @@ export class OrbitalCameraController {
     look(from: Vector3, to: Vector3): void;
     /**
      *
-     * @param {Transform} transform
+     * @param {Transform64} transform
      */
-    from_transform(transform: Transform): void;
+    from_transform(transform: Transform64): void;
     /**
      *
      * @param {number} delta_x
@@ -59,5 +59,5 @@ import { PointerDevice } from "../../../engine/input/devices/PointerDevice.js";
 import KeyboardDevice from "../../../engine/input/devices/KeyboardDevice.js";
 import Vector3 from "../../../core/geom/Vector3.js";
 import { NumericInterval } from "../../../core/math/interval/NumericInterval.js";
-import { Transform } from "../../../engine/ecs/transform/Transform.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
 //# sourceMappingURL=OrbitalCameraController.d.ts.map

package/src/shade/renderer/camera/OrbitalCameraController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OrbitalCameraController.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/camera/OrbitalCameraController.js"],"names":[],"mappings":"AAuBA;IAsJI;;;;OAIG;IACH,mDAFW,WAAW,EA4DrB;IApND,uBAAkC;IAClC,yBAA6C;IAE7C;;OAEG;IACH,0BAAM;IAEN;;;OAGG;IACH,oBAAqC;IAErC;;;OAGG;IACH,YAFU,OAAO,CAEU;IAE3B;;;OAGG;IACH,eAAwC;IAExC;;;OAGG;IACH,sBAFU,MAAM,CAES;IAEzB,gCAAgD;IAEhD,iBAAY;IAEZ,uBAAmB;IAEnB,gBAAuB;IAMvB;;;;OAIG;IACH,WAHW,OAAO,MACP,OAAO,QA+BjB;IAED;;;OAGG;IACH,0BAFW,SAAS,QAWnB;IAwBD;;;;OAIG;IACH,aAHW,MAAM,WACN,MAAM,QA2BhB;IAyHD,eAiEC;;CACJ;8BA1V6B,gDAAgD;2BADnD,iDAAiD;oBATxD,+BAA+B;gCAGnB,gDAAgD;0BAKtD,4CAA4C"}
+{"version":3,"file":"OrbitalCameraController.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/camera/OrbitalCameraController.js"],"names":[],"mappings":"AAwBA;IAiKI;;;;OAIG;IACH,mDAFW,WAAW,EA4DrB;IA/ND,uBAAkC;IAClC,yBAA6C;IAE7C;;OAEG;IACH,0BAAM;IAEN;;;OAGG;IACH,oBAAqC;IAErC;;;OAGG;IACH,YAFU,OAAO,CAEU;IAE3B;;;OAGG;IACH,eAAwC;IAExC;;;OAGG;IACH,sBAFU,MAAM,CAES;IAEzB,gCAAgD;IAEhD,iBAAY;IAEZ,uBAAmB;IAEnB,gBAAuB;IAMvB;;;;OAIG;IACH,WAHW,OAAO,MACP,OAAO,QA+BjB;IAED;;;OAGG;IACH,0BAFW,WAAW,QAsBrB;IAwBD;;;;OAIG;IACH,aAHW,MAAM,WACN,MAAM,QA2BhB;IAyHD,eAoEC;;CACJ;8BAxW6B,gDAAgD;2BADnD,iDAAiD;oBAVxD,+BAA+B;gCAGnB,gDAAgD;4BAMpD,8CAA8C"}

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

@@ -8,11 +8,12 @@ import { lerp } from "../../../core/math/lerp.js";
 import { current_time_in_seconds } from "../../../core/time/current_time_in_seconds.js";
 import { AnimationCurve } from "../../../engine/animation/curve/AnimationCurve.js";
 import { Keyframe } from "../../../engine/animation/curve/Keyframe.js";
-import { Transform } from "../../../engine/ecs/transform/Transform.js";
+import { t64_equals_components } from "../../../engine/ecs/transform/t64_equals_components.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
 import KeyboardDevice from "../../../engine/input/devices/KeyboardDevice.js";
 import { PointerDevice } from "../../../engine/input/devices/PointerDevice.js";
 
-const scratch_transform = new Transform();
+const scratch_transform = new Transform64();
 
 const ZOOM_CURVE = AnimationCurve.from([
     Keyframe.from(0, 0.01),
@@ -62,7 +63,7 @@ export class OrbitalCameraController {
 
     target = new Vector3();
 
-    #last_recorded_transform = new Transform();
+    #last_recorded_transform = new Transform64();
 
     #last_update_time = 0;
 
@@ -104,16 +105,27 @@ export class OrbitalCameraController {
 
     /**
      *
-     * @param {Transform} transform
+     * @param {Transform64} transform
      */
     from_transform(transform) {
 
-        const t = new Vector3();
-        t.copy(transform.forward);
-        t.multiplyScalar(this.distance);
-        t.add(transform.position);
+        // forward is a fresh view over the transform buffer; look() wants Vector3s, so the
+        // two endpoints are built as such rather than passed through as arrays
+        const forward = transform.forward;
 
-        this.look(transform.position, t);
+        const t = new Vector3(
+            forward[0] * this.distance + transform.translation_x,
+            forward[1] * this.distance + transform.translation_y,
+            forward[2] * this.distance + transform.translation_z
+        );
+
+        const from = new Vector3(
+            transform.translation_x,
+            transform.translation_y,
+            transform.translation_z
+        );
+
+        this.look(from, t);
 
     }
 
@@ -146,11 +158,11 @@ export class OrbitalCameraController {
      */
     pan(delta_x, delta_y) {
 
-        const position = this.camera.transform.position;
+        const transform = this.camera.transform;
 
         const offest = new Vector3()
 
-        offest.copy(position);
+        offest.set(transform.translation_x, transform.translation_y, transform.translation_z);
         offest.sub(this.target);
 
         const target_distance = offest.length();
@@ -159,7 +171,7 @@ export class OrbitalCameraController {
 
         const element = this.pointer.domElement;
 
-        const t_matrix = this.camera.transform.matrix;
+        const t_matrix = this.camera.transform;
 
         this.#pan_left(
             2 * delta_x * movement_scale / element.clientHeight,
@@ -281,7 +293,7 @@ export class OrbitalCameraController {
         v3_matrix4_rotate(
             global_offset_vector, 0,
             local_offset_vector.x, local_offset_vector.y, local_offset_vector.z,
-            this.camera.transform.matrix
+            this.camera.transform
         );
 
         global_offset_vector.multiplyScalar(target_vector_length);
@@ -302,7 +314,7 @@ export class OrbitalCameraController {
 
         const camera_transform = this.camera.transform;
 
-        if (!this.#last_recorded_transform.equals(camera_transform)) {
+        if (!t64_equals_components(this.#last_recorded_transform, camera_transform)) {
 
             // camera changed outside our control, update target
             this.from_transform(camera_transform);
@@ -335,8 +347,11 @@ export class OrbitalCameraController {
 
             scratch_transform.copy(camera_transform);
 
-            scratch_transform.position.copy(this.target);
-            scratch_transform.position.add(offset);
+            scratch_transform.setTranslation(
+                this.target.x + offset.x,
+                this.target.y + offset.y,
+                this.target.z + offset.z
+            );
 
 
             scratch_transform.lookAt(this.target);

package/src/shade/renderer/camera/orbital/OrbitalCameraController.d.ts

@@ -44,7 +44,7 @@ export class OrbitalCameraController {
     keyboard: KeyboardDevice;
     rig: OrbitalCameraRig;
     input: OrbitalCameraInput;
-    _lastRecorded: Transform;
+    _lastRecorded: Transform64;
     _lastUpdateTime: number;
     _scratchEye: Vector3;
     /** Zoom range, in world units (NumericInterval). Mutate `.min/.max` or `.set()`. */
@@ -104,6 +104,6 @@ import { PointerDevice } from "../../../../engine/input/devices/PointerDevice.js
 import KeyboardDevice from "../../../../engine/input/devices/KeyboardDevice.js";
 import { OrbitalCameraRig } from "./OrbitalCameraRig.js";
 import { OrbitalCameraInput } from "./OrbitalCameraInput.js";
-import { Transform } from "../../../../engine/ecs/transform/Transform.js";
+import { Transform64 } from "../../../../engine/ecs/transform/Transform64.js";
 import Vector3 from "../../../../core/geom/Vector3.js";
 //# sourceMappingURL=OrbitalCameraController.d.ts.map

package/src/shade/renderer/camera/orbital/OrbitalCameraController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OrbitalCameraController.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/camera/orbital/OrbitalCameraController.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IACI;;;;OAIG;IACH,oBAJW,OAAO,yBAAyB,EAAE,iBAAiB,cACnD,WAAW,yBAuCrB;IAnCG,4DAAoB;IACpB,wBAA4B;IAE5B;;;;;;;;;;;;;OAAwD;IAGxD,uBAA4C;IAI5C,yBAA8C;IAK9C,sBAAwD;IAExD,0BAOE;IAIF,yBAAoC;IAEpC,wBAAgD;IAChD,qBAAgC;IAUpC,oFAAoF;IACpF,kGAEC;IAOD,sCAEC;IAPD,+CAA+C;IAC/C,mCAEC;IAMD,gDAAgD;IAChD,uBAEC;IAED,gFAAgF;IAChF,sBAEC;IAED;;;;OAIG;IACH,WAHW,OAAO,MACP,OAAO,QAUjB;IAED;;;;;OAKG;IACH,YAHW,OAAO,MACP,OAAO,QAUjB;IAED;;;;OAIG;IACH,0BAFW,SAAS,QAQnB;IAED;;;;OAIG;IACH,aAHW,MAAM,WACN,MAAM,QAIhB;IAED;;;;;;OAMG;IACH,YAJW,MAAM,QAuBhB;IAED,uDAAuD;IACvD,gBAIC;IAMD;;;;;;OAMG;IACH,gBAHW,MAAM,GACJ,MAAM,CAelB;CACJ;8BAjN6B,mDAAmD;2BADtD,oDAAoD;iCAE9C,uBAAuB;mCACrB,yBAAyB;0BALlC,+CAA+C;oBADrD,kCAAkC"}
+{"version":3,"file":"OrbitalCameraController.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/camera/orbital/OrbitalCameraController.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IACI;;;;OAIG;IACH,oBAJW,OAAO,yBAAyB,EAAE,iBAAiB,cACnD,WAAW,yBAuCrB;IAnCG,4DAAoB;IACpB,wBAA4B;IAE5B;;;;;;;;;;;;;OAAwD;IAGxD,uBAA4C;IAI5C,yBAA8C;IAK9C,sBAAwD;IAExD,0BAOE;IAIF,2BAAsC;IAEtC,wBAAgD;IAChD,qBAAgC;IAUpC,oFAAoF;IACpF,kGAEC;IAOD,sCAEC;IAPD,+CAA+C;IAC/C,mCAEC;IAMD,gDAAgD;IAChD,uBAEC;IAED,gFAAgF;IAChF,sBAEC;IAED;;;;OAIG;IACH,WAHW,OAAO,MACP,OAAO,QAUjB;IAED;;;;;OAKG;IACH,YAHW,OAAO,MACP,OAAO,QAUjB;IAED;;;;OAIG;IACH,2CAMC;IAED;;;;OAIG;IACH,aAHW,MAAM,WACN,MAAM,QAIhB;IAED;;;;;;OAMG;IACH,YAJW,MAAM,QAuBhB;IAED,uDAAuD;IACvD,gBAIC;IAMD;;;;;;OAMG;IACH,gBAHW,MAAM,GACJ,MAAM,CAelB;CACJ;8BAjN6B,mDAAmD;2BADtD,oDAAoD;iCAE9C,uBAAuB;mCACrB,yBAAyB;4BALhC,iDAAiD;oBAFzD,kCAAkC"}

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

@@ -1,7 +1,8 @@
 import { assert } from "../../../../core/assert.js";
 import { clamp } from "../../../../core/math/clamp.js";
 import Vector3 from "../../../../core/geom/Vector3.js";
-import { Transform } from "../../../../engine/ecs/transform/Transform.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 KeyboardDevice from "../../../../engine/input/devices/KeyboardDevice.js";
 import { PointerDevice } from "../../../../engine/input/devices/PointerDevice.js";
@@ -63,7 +64,7 @@ export class OrbitalCameraController {
         this.input.connect();
 
         // ── frame bookkeeping ───────────────────────────────────────────────
-        this._lastRecorded = new Transform();
+        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();
@@ -168,7 +169,7 @@ export class OrbitalCameraController {
 
         const camTransform = this.camera.transform;
 
-        if (!this._lastRecorded.equals(camTransform)) {
+        if (!t64_equals_components(this._lastRecorded, camTransform)) {
             // camera was moved outside our control — adopt it, skip integration
             this.from_transform(camTransform);
         } else {

package/src/shade/renderer/camera/orbital/OrbitalCameraRig.d.ts

@@ -33,7 +33,12 @@ export class OrbitalCameraRig {
         momentumEnabled: true;
         momentumDecayHalfLife: 0.1;
         velocityWindow: 0.1;
-        momentumStopSpeed: 0.012;
+        momentumStopSpeed: 0.012; /**
+         * @param {object} [options]
+         * @param {ReturnType<typeof createOrbitalCameraConfig>} [options.config]
+         * @param {NumericInterval} [options.distanceLimits]
+         * @param {number} [options.movementSpeedScale]
+         */
         rotateSpeed: 1;
         panSpeed: 1;
         zoomStep: 0.9;
@@ -67,8 +72,8 @@ export class OrbitalCameraRig {
         tz1: number;
         t: number;
     };
-    _basisTransform: Transform;
-    _scratchTransform: Transform;
+    _basisTransform: Transform64;
+    _scratchTransform: Transform64;
     _scratchTarget: Vector3;
     /** Begin an orbit drag (pointer down). Cancels any coast/fly and takes direct control. */
     engageRotate(): void;
@@ -155,14 +160,14 @@ export class OrbitalCameraRig {
     };
     _currentTarget(): Vector3;
     /** Matrix of the current pose, for deriving the pan/truck view basis. */
-    _currentBasisMatrix(): Float32Array;
+    _currentBasisMatrix(): Float64Array;
     _poseToTransform(out: any, phi: any, theta: any, radius: any, target: any): void;
     /** Representative of `target` angle nearest `current` (shortest arc). */
     _shortestAzimuth(target: any, current: any): any;
 }
 import { NumericInterval } from "../../../../core/math/interval/NumericInterval.js";
 import { MomentumAxis } from "./MomentumAxis.js";
-import { Transform } from "../../../../engine/ecs/transform/Transform.js";
+import { Transform64 } from "../../../../engine/ecs/transform/Transform64.js";
 import Vector3 from "../../../../core/geom/Vector3.js";
 import { createOrbitalCameraConfig } from "./OrbitalCameraConfig.js";
 //# sourceMappingURL=OrbitalCameraRig.d.ts.map

package/src/shade/renderer/camera/orbital/OrbitalCameraRig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OrbitalCameraRig.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/camera/orbital/OrbitalCameraRig.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IACI;;;;;OAKG;IACH;QAJkE,MAAM,GAA7D,WAAW,gCAAgC,CAAC;QAClB,cAAc,GAAxC,eAAe;QACE,kBAAkB,GAAnC,MAAM;OA4BhB;IAzBG;;;;;;;;;;;;;OAAoB;IACpB,gCAAsE;IACtE,2BAA4C;IAG5C,mBAAyC;IACzC,qBAAiC;IACjC,kBAA8B;IAC9B,kBAA8B;IAC9B,kBAA8B;IAG9B,iBAAiB;IAIjB,sBAAyB;IAGzB;;;;;;;;;;;;;;MAAgB;IAGhB,2BAAsC;IACtC,6BAAwC;IACxC,wBAAmC;IAOvC,0FAA0F;IAC1F,qBAIC;IAED;;;;;OAKG;IACH,aAHW,MAAM,UACN,MAAM,QAKhB;IAED,4FAA4F;IAC5F,wBAGC;IAMD,mDAAmD;IACnD,kBAKC;IAED;;;;;;;OAOG;IACH,cALW,MAAM,MACN,MAAM,kBACN,MAAM,OACN,MAAM,QAsBhB;IAED,kFAAkF;IAClF,qBAMC;IAMD;;;;OAIG;IACH,cAFW,MAAM,QAQhB;IAED,6DAA6D;IAC7D,iCAGC;IAED;;;;;;;OAOG;IACH,cAJW,MAAM,KACN,MAAM,MACN,MAAM,QAuBhB;IAMD;;;;;;;OAOG;IACH,cALW,OAAO,MACP,OAAO;QAEQ,OAAO,GAAtB,OAAO;aAyBjB;IAMD;;;;;OAKG;IACH,WAHW,MAAM,GACJ,OAAO,CAoCnB;IAED;;;;;OAKG;IACH,sBAHW,SAAS,GACP,SAAS,CAWrB;IAID,kBAAqC;IACrC,oBAAyC;IACzC,yDAAyD;IACzD,wBAQC;IAED;;;;;OAKG;IACH,gBAHW,OAAO,GACL,OAAO,CAMnB;IAMD,8BAiBC;IAED;;;;MAaC;IAED,0BAGC;IAED,yEAAyE;IACzE,oCAOC;IAED,iFAQC;IAED,yEAAyE;IACzE,iDAIC;CACJ;gCAvY+B,mDAAmD;6BAGtD,mBAAmB;0BADtB,+CAA+C;oBADrD,kCAAkC;0CAGZ,0BAA0B"}
+{"version":3,"file":"OrbitalCameraRig.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/camera/orbital/OrbitalCameraRig.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IACI;;;;;OAKG;IACH;QAJkE,MAAM,GAA7D,WAAW,gCAAgC,CAAC;QAClB,cAAc,GAAxC,eAAe;QACE,kBAAkB,GAAnC,MAAM;OA4BhB;IAzBG;;;;kCAPJ;;;;;WAKG;;;;;;;;;OAEqB;IACpB,gCAAsE;IACtE,2BAA4C;IAG5C,mBAAyC;IACzC,qBAAiC;IACjC,kBAA8B;IAC9B,kBAA8B;IAC9B,kBAA8B;IAG9B,iBAAiB;IAIjB,sBAAyB;IAGzB;;;;;;;;;;;;;;MAAgB;IAGhB,6BAAwC;IACxC,+BAA0C;IAC1C,wBAAmC;IAOvC,0FAA0F;IAC1F,qBAIC;IAED;;;;;OAKG;IACH,aAHW,MAAM,UACN,MAAM,QAKhB;IAED,4FAA4F;IAC5F,wBAGC;IAMD,mDAAmD;IACnD,kBAKC;IAED;;;;;;;OAOG;IACH,cALW,MAAM,MACN,MAAM,kBACN,MAAM,OACN,MAAM,QAsBhB;IAED,kFAAkF;IAClF,qBAMC;IAMD;;;;OAIG;IACH,cAFW,MAAM,QAQhB;IAED,6DAA6D;IAC7D,iCAGC;IAED;;;;;;;OAOG;IACH,cAJW,MAAM,KACN,MAAM,MACN,MAAM,QAuBhB;IAMD;;;;;;;OAOG;IACH,cALW,OAAO,MACP,OAAO;QAEQ,OAAO,GAAtB,OAAO;aAyBjB;IAMD;;;;;OAKG;IACH,WAHW,MAAM,GACJ,OAAO,CAoCnB;IAED;;;;;OAKG;IACH,4CASC;IAID,kBAAqC;IACrC,oBAAyC;IACzC,yDAAyD;IACzD,wBAQC;IAED;;;;;OAKG;IACH,gBAHW,OAAO,GACL,OAAO,CAMnB;IAMD,8BAiBC;IAED;;;;MAaC;IAED,0BAGC;IAED,yEAAyE;IACzE,oCAOC;IAED,iFAYC;IAED,yEAAyE;IACzE,iDAIC;CACJ;gCA3Y+B,mDAAmD;6BAGtD,mBAAmB;4BADpB,iDAAiD;oBADzD,kCAAkC;0CAGZ,0BAA0B"}

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

@@ -4,7 +4,7 @@ import { lerp } from "../../../../core/math/lerp.js";
 import { smoothStep } from "../../../../core/math/smoothStep.js";
 import { NumericInterval } from "../../../../core/math/interval/NumericInterval.js";
 import Vector3 from "../../../../core/geom/Vector3.js";
-import { Transform } from "../../../../engine/ecs/transform/Transform.js";
+import { Transform64 } from "../../../../engine/ecs/transform/Transform64.js";
 import { MomentumAxis } from "./MomentumAxis.js";
 import { createOrbitalCameraConfig } from "./OrbitalCameraConfig.js";
 
@@ -59,8 +59,8 @@ export class OrbitalCameraRig {
         this._fly = null;
 
         // scratch — reused, never allocated per frame
-        this._basisTransform = new Transform();
-        this._scratchTransform = new Transform();
+        this._basisTransform = new Transform64();
+        this._scratchTransform = new Transform64();
         this._scratchTarget = new Vector3();
     }
 
@@ -379,12 +379,16 @@ export class OrbitalCameraRig {
 
     _poseToTransform(out, phi, theta, radius, target) {
         const sinPhiR = Math.sin(phi) * radius;
-        out.position.set(
+        out.setTranslation(
             target.x + sinPhiR * Math.sin(theta),
             target.y + Math.cos(phi) * radius,
             target.z + sinPhiR * Math.cos(theta)
         );
         out.lookAt(target);
+
+        // lookAt set the rotation and nothing recomposes on its own, so callers reading the
+        // matrix - _currentBasisMatrix does, immediately - would otherwise get the previous pose
+        out.updateMatrix();
     }
 
     /** Representative of `target` angle nearest `current` (shortest arc). */

package/src/shade/renderer/extension/FrameContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FrameContext.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/extension/FrameContext.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AACH;IA6BI;;;OAGG;IACH,qDAMC;IAED;;;;;OAKG;IACH,wBAEC;IAED;;;;OAIG;IACH,2BAEC;IASD;;;;OAIG;IACH,uBAKC;IAjBD;;OAEG;IACH,oBAEC;IAcD;;;;;OAKG;IACH,uBAEC;IAED;;OAEG;IACH,cAEC;IAED;;;;OAIG;IACH,+CAFa,OAAO,CAMnB;IAED;;;;;;OAMG;IACH,uDAaC;IAED;;;;;;;;;;;;OAYG;IACH,0DAYC;IAED;;;;;;;;;OASG;IACH,iBAHW,MAAM,sBAOhB;IAED;;;;;;;;;;OAUG;IACH,2BAeC;;CAoBJ"}
+{"version":3,"file":"FrameContext.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/extension/FrameContext.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AACH;IA6BI;;;OAGG;IACH,qDAMC;IAED;;;;;OAKG;IACH,wBAEC;IAED;;;;OAIG;IACH,2BAEC;IASD;;;;OAIG;IACH,uBAKC;IAjBD;;OAEG;IACH,oBAEC;IAcD;;;;;OAKG;IACH,uBAEC;IAED;;OAEG;IACH,cAEC;IAED;;;;OAIG;IACH,+CAFa,OAAO,CAMnB;IAED;;;;;;OAMG;IACH,uDAaC;IAED;;;;;;;;;;;;OAYG;IACH,0DAYC;IAED;;;;;;;;;OASG;IACH,iBAHW,MAAM,sBAYhB;IAED;;;;;;;;;;OAUG;IACH,2BAeC;;CAoBJ"}

package/src/shade/renderer/extension/FrameContext.js

@@ -186,6 +186,11 @@ export class FrameContext {
     describe(handle) {
         assert.isNonNegativeInteger(handle, 'handle');
 
+        // `FrameRecord.read` and `publish` both say this; taking a raw handle rather than going
+        // through a record was the one way around it, and it answers from a graph that may already
+        // have executed and released its transients — plausibly, wrongly, and silently.
+        assert.equal(this.#open, true, `FrameContext.describe was called on a frame that has finished, so the handle names a resource of a graph that is gone`);
+
         return this.#graph.getDescriptor(handle);
     }