@woosh/meep-engine 3.23.0 → 3.25.0

package/src/shade/renderer/scene/rows/place_primitive.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @typedef {import("../GPUSceneContext.js").GPUSceneContext} GPUSceneContext
+ * @typedef {import("../../geometry/MeshletGeometry.js").MeshletGeometry} MeshletGeometry
+ * @typedef {import("../../material/ShadeMaterial.js").ShadeMaterial} ShadeMaterial
+ */
+/**
+ * Put one primitive into a scene that has no systems: a playground's floor, a backdrop, a probe
+ * marker, a scattered box.
+ *
+ * A game does this in `ShadedGeometrySystem`, which takes a mesh row for every entity carrying a
+ * `ShadedGeometry` as the component appears. A scene bound to a bare dataset has no such system,
+ * so this does the same by hand: an entity of the scene's dataset carrying the transform, a
+ * `ShadedGeometry` naming what it draws — so a tool can read it back — and a `Name` when given;
+ * then its `meshes` row, which takes the `transforms` row with it. The rows write on the scene
+ * context's next build.
+ *
+ * @param {GPUSceneContext} scene_context the scene's context — its rows are where the primitive goes
+ * @param {MeshletGeometry} geometry
+ * @param {ShadeMaterial} material
+ * @param {Transform64} transform where it stands; copied
+ * @param {object} [options]
+ * @param {string} [options.name]
+ * @returns {number} the entity
+ */
+export function place_primitive(scene_context: GPUSceneContext, geometry: MeshletGeometry, material: ShadeMaterial, transform: Transform64, { name }?: {
+    name?: string;
+}): number;
+/**
+ * Move a placed primitive: its transform takes `transform`, and its row is marked so the next
+ * build writes it.
+ *
+ * @param {GPUSceneContext} scene_context
+ * @param {number} entity what {@link place_primitive} answered
+ * @param {Transform64} transform copied
+ */
+export function move_primitive(scene_context: GPUSceneContext, entity: number, transform: Transform64): void;
+/**
+ * Take a placed primitive out: its rows given back, its entity removed.
+ *
+ * @param {GPUSceneContext} scene_context
+ * @param {number} entity what {@link place_primitive} answered
+ */
+export function remove_primitive(scene_context: GPUSceneContext, entity: number): void;
+export type GPUSceneContext = import("../GPUSceneContext.js").GPUSceneContext;
+export type MeshletGeometry = import("../../geometry/MeshletGeometry.js").MeshletGeometry;
+export type ShadeMaterial = import("../../material/ShadeMaterial.js").ShadeMaterial;
+import { Transform64 } from "../../../../engine/ecs/transform/Transform64.js";
+//# sourceMappingURL=place_primitive.d.ts.map

package/src/shade/renderer/scene/rows/place_primitive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"place_primitive.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/scene/rows/place_primitive.js"],"names":[],"mappings":"AAKA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,+CARW,eAAe,YACf,eAAe,YACf,aAAa,aACb,WAAW;IAEM,IAAI,GAArB,MAAM;IACJ,MAAM,CAgClB;AAED;;;;;;;GAOG;AACH,8CAJW,eAAe,UACf,MAAM,aACN,WAAW,QAerB;AAED;;;;;GAKG;AACH,gDAHW,eAAe,UACf,MAAM,QAQhB;8BA3FY,OAAO,uBAAuB,EAAE,eAAe;8BAC/C,OAAO,mCAAmC,EAAE,eAAe;4BAC3D,OAAO,iCAAiC,EAAE,aAAa;4BANxC,iDAAiD"}

package/src/shade/renderer/scene/rows/place_primitive.js

@@ -0,0 +1,98 @@
+import { assert } from "../../../../core/assert.js";
+import { Name } from "../../../../engine/ecs/name/Name.js";
+import { Transform64 } from "../../../../engine/ecs/transform/Transform64.js";
+import { ShadedGeometry } from "../../../../engine/graphics/ecs/mesh-v2/ShadedGeometry.js";
+
+/**
+ * @typedef {import("../GPUSceneContext.js").GPUSceneContext} GPUSceneContext
+ * @typedef {import("../../geometry/MeshletGeometry.js").MeshletGeometry} MeshletGeometry
+ * @typedef {import("../../material/ShadeMaterial.js").ShadeMaterial} ShadeMaterial
+ */
+
+/**
+ * Put one primitive into a scene that has no systems: a playground's floor, a backdrop, a probe
+ * marker, a scattered box.
+ *
+ * A game does this in `ShadedGeometrySystem`, which takes a mesh row for every entity carrying a
+ * `ShadedGeometry` as the component appears. A scene bound to a bare dataset has no such system,
+ * so this does the same by hand: an entity of the scene's dataset carrying the transform, a
+ * `ShadedGeometry` naming what it draws — so a tool can read it back — and a `Name` when given;
+ * then its `meshes` row, which takes the `transforms` row with it. The rows write on the scene
+ * context's next build.
+ *
+ * @param {GPUSceneContext} scene_context the scene's context — its rows are where the primitive goes
+ * @param {MeshletGeometry} geometry
+ * @param {ShadeMaterial} material
+ * @param {Transform64} transform where it stands; copied
+ * @param {object} [options]
+ * @param {string} [options.name]
+ * @returns {number} the entity
+ */
+export function place_primitive(scene_context, geometry, material, transform, { name = "" } = {}) {
+    assert.defined(scene_context, 'scene_context');
+    assert.defined(geometry, 'geometry');
+    assert.equal(geometry.isMeshletGeometry, true, 'geometry.isMeshletGeometry !== true');
+    assert.defined(material, 'material');
+    assert.defined(transform, 'transform');
+    assert.isString(name, 'name');
+
+    const dataset = scene_context.scene.dataset;
+
+    assert.ok(dataset !== null && dataset !== undefined, 'the scene names no dataset, and a primitive is an entity of one');
+
+    dataset.registerManyComponentTypes([Transform64, ShadedGeometry, Name]);
+
+    const entity = dataset.createEntity();
+    const world = new Transform64();
+
+    world.copy(transform);
+    world.updateMatrix();
+
+    dataset.addComponentToEntity(entity, world);
+    dataset.addComponentToEntity(entity, ShadedGeometry.from(geometry, material));
+
+    if (name !== "") {
+        dataset.addComponentToEntity(entity, new Name(name));
+    }
+
+    scene_context.rows.attach_mesh(entity, geometry, material);
+
+    return entity;
+}
+
+/**
+ * Move a placed primitive: its transform takes `transform`, and its row is marked so the next
+ * build writes it.
+ *
+ * @param {GPUSceneContext} scene_context
+ * @param {number} entity what {@link place_primitive} answered
+ * @param {Transform64} transform copied
+ */
+export function move_primitive(scene_context, entity, transform) {
+    assert.defined(scene_context, 'scene_context');
+    assert.isNonNegativeInteger(entity, 'entity');
+    assert.defined(transform, 'transform');
+
+    const world = scene_context.scene.dataset.getComponent(entity, Transform64);
+
+    assert.defined(world, `entity ${entity} carries no Transform64 — was it placed with place_primitive?`);
+
+    world.copy(transform);
+    world.updateMatrix();
+
+    scene_context.rows.mark_world(entity);
+}
+
+/**
+ * Take a placed primitive out: its rows given back, its entity removed.
+ *
+ * @param {GPUSceneContext} scene_context
+ * @param {number} entity what {@link place_primitive} answered
+ */
+export function remove_primitive(scene_context, entity) {
+    assert.defined(scene_context, 'scene_context');
+    assert.isNonNegativeInteger(entity, 'entity');
+
+    scene_context.rows.detach_mesh(entity);
+    scene_context.scene.dataset.removeEntity(entity);
+}

package/src/shade/renderer/scene/serialization/deserialize_scene.d.ts

@@ -2,18 +2,20 @@
  * Deserialize a scene from a BinaryBuffer that was produced by {@link serialize_scene}.
  *
  * @param {BinaryBuffer} buffer  positioned at the start of the serialized data
- * @param {Scene} scene  an empty Scene instance to populate
- * @returns {Promise<Scene>}
+ * @param {Scene} scene  takes the file's lights, at entities of its dataset, and its environment
+ * @returns {Promise<SceneBundle>} the file's meshes, as a model to compile and place — each a root
+ *          at its world transform, the format being flat
  */
-export function deserialize_scene(buffer: BinaryBuffer, scene: Scene): Promise<Scene>;
+export function deserialize_scene(buffer: BinaryBuffer, scene: Scene): Promise<SceneBundle>;
 /**
- * Fetch a serialized scene binary from a URL and deserialize it into the given Scene.
- * Convenience wrapper for testing.
+ * Fetch a serialized scene binary from a URL and deserialize it: the lights and the environment
+ * into the given scene, the meshes as a bundle to compile and place.
  *
  * @param {string} url   URL pointing to the binary blob produced by serialize_scene
- * @param {Scene} scene  an empty Scene instance to populate
- * @returns {Promise<Scene>}
+ * @param {Scene} scene  takes the file's lights and environment
+ * @returns {Promise<SceneBundle>}
  */
-export function load_scene_from_url(url: string, scene: Scene): Promise<Scene>;
+export function load_scene_from_url(url: string, scene: Scene): Promise<SceneBundle>;
 import { BinaryBuffer } from "../../../../core/binary/BinaryBuffer.js";
+import { SceneBundle } from "../../loader/SceneBundle.js";
 //# sourceMappingURL=deserialize_scene.d.ts.map

package/src/shade/renderer/scene/serialization/deserialize_scene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deserialize_scene.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/scene/serialization/deserialize_scene.js"],"names":[],"mappings":"AAgNA;;;;;;GAMG;AACH,0CAJW,YAAY,iBAEV,cAAc,CA8R1B;AAED;;;;;;;GAOG;AACH,yCAJW,MAAM,iBAEJ,cAAc,CAuB1B;6BAjhB4B,yCAAyC"}
+{"version":3,"file":"deserialize_scene.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/scene/serialization/deserialize_scene.js"],"names":[],"mappings":"AAkNA;;;;;;;GAOG;AACH,0CALW,YAAY,iBAEV,QAAQ,WAAW,CAAC,CAyRhC;AAED;;;;;;;GAOG;AACH,yCAJW,MAAM,iBAEJ,QAAQ,WAAW,CAAC,CAuBhC;6BA9gB4B,yCAAyC;4BAW1C,6BAA6B"}

package/src/shade/renderer/scene/serialization/deserialize_scene.js

@@ -6,10 +6,12 @@ import { Sampler2D } from "../../../../engine/graphics/texture/sampler/Sampler2D
 import { MeshletGeometry } from "../../geometry/MeshletGeometry.js";
 import { MeshletGeometrySerializationAdapter } from "../../geometry/MeshletGeometrySerializationAdapter.js";
 import { DirectionalLight } from "../../light/model/DirectionalLight.js";
+import { place_light } from "../../light/place_light.js";
 import { PointLight } from "../../light/model/PointLight.js";
 import { SpotLight } from "../../light/model/SpotLight.js";
 import { StandardShadeMaterial } from "../../material/StandardShadeMaterial.js";
-import { Mesh } from "../Mesh.js";
+import { SceneBundle } from "../../loader/SceneBundle.js";
+import { SceneNode } from "../../loader/SceneNode.js";
 import { ShadeTexture } from "../../texture/ShadeTexture.js";
 import { ShadeImage } from "../../texture/source/ShadeImage.js";
 import { avif_to_sampler2d } from "../../../../engine/graphics/texture/sampler/avif_to_sampler2d.js";
@@ -183,7 +185,7 @@ function deserialize_light(buffer) {
 
     const light_matrix = new Float32Array(16);
     buffer.readFloat32Array(light_matrix, 0, 16);
-    light.transform_global.fromMatrix(light_matrix);
+    light.transform.fromMatrix(light_matrix);
 
     light.intensity = buffer.readFloat32();
 
@@ -210,8 +212,9 @@ function deserialize_light(buffer) {
  * Deserialize a scene from a BinaryBuffer that was produced by {@link serialize_scene}.
  *
  * @param {BinaryBuffer} buffer  positioned at the start of the serialized data
- * @param {Scene} scene  an empty Scene instance to populate
- * @returns {Promise<Scene>}
+ * @param {Scene} scene  takes the file's lights, at entities of its dataset, and its environment
+ * @returns {Promise<SceneBundle>} the file's meshes, as a model to compile and place — each a root
+ *          at its world transform, the format being flat
  */
 export async function deserialize_scene(buffer, scene) {
 
@@ -469,43 +472,37 @@ export async function deserialize_scene(buffer, scene) {
         scene.lights.environment = textures[environment_index];
     }
 
-    // Light elements
+    // Light elements — each at an entity of the scene's dataset, which the scene has to name
     const light_count = buffer.readUint32();
     for (let i = 0; i < light_count; i++) {
         const light = deserialize_light(buffer);
-        scene.lights.add(light);
+        place_light(scene, light);
     }
 
-    // ── Assemble Meshes ──
+    // ── Assemble the model: one root per mesh, at its world transform ──
+    const bundle = new SceneBundle();
 
     for (const record of mesh_records) {
-        const mesh = new Mesh();
-        mesh.name = record.name;
-        mesh.geometry = geometries[record.geometry_index];
-        mesh.material = materials[record.material_index];
-        // serialized transform is world-space; meshes deserialize without a parent, so
-        // local == global. Setting only transform_global would leave transform_local at
-        // identity, and the next updateMatrices() / GPU hierarchy pass (which recompose
-        // global from local TRS) would snap the mesh to the origin.
-        mesh.transform_local.fromMatrix(record.transform);
-        mesh.updateMatrices();
-
-        // Compute world-space bounds from geometry bounds + transform
-        mesh.updateBoundsBasic();
-
-        scene.instances.add(mesh);
+        bundle.add_node(SceneNode.from({
+            name: record.name,
+            // serialized transforms are world-space, and a mesh comes back as a root — so its
+            // local is its world
+            matrix: record.transform,
+            geometry: geometries[record.geometry_index],
+            material: materials[record.material_index],
+        }));
     }
 
-    return scene;
+    return bundle;
 }
 
 /**
- * Fetch a serialized scene binary from a URL and deserialize it into the given Scene.
- * Convenience wrapper for testing.
+ * Fetch a serialized scene binary from a URL and deserialize it: the lights and the environment
+ * into the given scene, the meshes as a bundle to compile and place.
  *
  * @param {string} url   URL pointing to the binary blob produced by serialize_scene
- * @param {Scene} scene  an empty Scene instance to populate
- * @returns {Promise<Scene>}
+ * @param {Scene} scene  takes the file's lights and environment
+ * @returns {Promise<SceneBundle>}
  */
 export async function load_scene_from_url(url, scene) {
     assert.defined(scene, 'scene');

package/src/shade/renderer/scene/serialization/serialize_scene.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @typedef {import("../../loader/SceneBundle.js").SceneBundle} SceneBundle
+ */
 /**
  *
  * @param {BinaryBuffer} buffer
@@ -8,12 +11,16 @@ export function material_write_standard(buffer: BinaryBuffer, material: Standard
 /**
  *
  * @param {Object} options
- * @param {Scene} options.scene
+ * @param {SceneBundle} options.bundle the meshes, as a loader or the deserializer describes them —
+ *        written flat, each primitive at its world transform
+ * @param {Scene} options.scene the lights and the environment
  * @param {boolean} [options.include_blas] BLAS BVH takes up a lot of space, but it is optimal and will save processing time
  */
-export function serialize_scene({ scene, include_blas, }: {
+export function serialize_scene({ bundle, scene, include_blas, }: {
+    bundle: SceneBundle;
     scene: Scene;
     include_blas?: boolean;
 }): Promise<BinaryBuffer>;
+export type SceneBundle = import("../../loader/SceneBundle.js").SceneBundle;
 import { BinaryBuffer } from "../../../../core/binary/BinaryBuffer.js";
 //# sourceMappingURL=serialize_scene.d.ts.map

package/src/shade/renderer/scene/serialization/serialize_scene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serialize_scene.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/scene/serialization/serialize_scene.js"],"names":[],"mappings":"AAQA;;;;;GAKG;AACH,gDAJW,YAAY,mDAEZ,kBAAkB,MAAM,CAAC,QAsDnC;AAwJD;;;;;GAKG;AACH;IAH0B,KAAK;IACF,YAAY,GAA9B,OAAO;0BAkPjB;6BA/c4B,yCAAyC"}
+{"version":3,"file":"serialize_scene.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/scene/serialization/serialize_scene.js"],"names":[],"mappings":"AAOA;;GAEG;AAGH;;;;;GAKG;AACH,gDAJW,YAAY,mDAEZ,kBAAkB,MAAM,CAAC,QAsDnC;AAwJD;;;;;;;GAOG;AACH;IALgC,MAAM,EAA3B,WAAW;IAEI,KAAK;IACF,YAAY,GAA9B,OAAO;0BAiQjB;0BA7dY,OAAO,6BAA6B,EAAE,WAAW;6BAPjC,yCAAyC"}

package/src/shade/renderer/scene/serialization/serialize_scene.js

@@ -5,6 +5,10 @@ import { MeshletGeometrySerializationAdapter } from "../../geometry/MeshletGeome
 import { LightTypeSerializationIndex } from "./LightTypeSerializationIndex.js";
 import { write_image_source } from "./write_image_source.js";
 
+/**
+ * @typedef {import("../../loader/SceneBundle.js").SceneBundle} SceneBundle
+ */
+
 
 /**
  *
@@ -197,7 +201,7 @@ function serialize_light(buffer, light) {
     const light_type = LightTypeSerializationIndex[light.type];
     buffer.writeUint8(light_type);
 
-    buffer.writeFloat32Array(light.transform_global.matrix, 0, 16);
+    buffer.writeFloat32Array(light.transform.matrix, 0, 16);
     buffer.writeFloat32(light.intensity);
     buffer.writeUint32(light.color.toUint32());
     buffer.writeFloat32(light.radius);
@@ -219,13 +223,19 @@ function serialize_light(buffer, light) {
 /**
  *
  * @param {Object} options
- * @param {Scene} options.scene
+ * @param {SceneBundle} options.bundle the meshes, as a loader or the deserializer describes them —
+ *        written flat, each primitive at its world transform
+ * @param {Scene} options.scene the lights and the environment
  * @param {boolean} [options.include_blas] BLAS BVH takes up a lot of space, but it is optimal and will save processing time
  */
 export async function serialize_scene({
+                                          bundle,
                                           scene,
                                           include_blas = true,
                                       }) {
+    assert.defined(bundle, 'bundle');
+    assert.equal(bundle.isSceneBundle, true, 'bundle.isSceneBundle !== true');
+
     /**
      *
      * @type {Set<MeshletGeometry>}
@@ -260,7 +270,18 @@ export async function serialize_scene({
      */
     const images = new Set();
 
-    const meshes = scene.instances.instances;
+    // every primitive at its world transform: the format is flat, and a node that only places
+    // others is composed away
+    const worlds = bundle.compute_world_matrices();
+    const meshes = [];
+
+    for (let i = 0; i < bundle.nodes.length; i++) {
+        const node = bundle.nodes[i];
+
+        if (node.geometry !== null) {
+            meshes.push({ name: node.name, geometry: node.geometry, material: node.material, world: worlds[i] });
+        }
+    }
     for (const mesh of meshes) {
 
         // extract geometries
@@ -353,7 +374,7 @@ export async function serialize_scene({
 
         // TODO add scene node graph
 
-        buffer.writeFloat32Array(mesh.transform_global.matrix, 0, 16);
+        buffer.writeFloat32Array(mesh.world, 0, 16);
     }
 
     // write geometries

package/src/shade/renderer/scene/verify_gpu_tlas_build.js

@@ -280,7 +280,7 @@ export async function verify_gpu_tlas_build(graphics) {
             rows.push(row);
             boxes_by_row[row] = box;
 
-            tlas.instance_add(row, { bounding_box: box });
+            tlas.instance_add(row);
         }
 
         flush(graphics, database);
@@ -300,7 +300,7 @@ export async function verify_gpu_tlas_build(graphics) {
                 boxes_by_row[row] = box;
 
                 meshes.set(row, make_mesh_record(box));
-                tlas.instance_update(row, { bounding_box: box });
+                tlas.instance_update(row);
             }
 
             flush(graphics, database);

package/src/shade/renderer/shader/chunk/geometry/mat3/chunk_mat3_singular_values.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The largest and smallest singular values of a 3×3 matrix.
+ *
+ * They are what "how much does this transform stretch a distance" actually means: a vector's length
+ * is scaled by something between σ_min and σ_max, and both bounds are attained. Column lengths are
+ * the obvious stand-in and they are **not** the same number — for
+ * `[[1,0,0],[k,1,0],[0,0,1]]`, every column has length 1 or √(1+k²) while the true ratio grows
+ * without bound in `k`. A shear has no scale in any column and stretches space anyway.
+ *
+ * Computed as the square roots of the eigenvalues of `MᵀM`, which is symmetric and positive
+ * semi-definite, through the closed form for a symmetric 3×3 (Smith 1961). No iteration, no
+ * branching past the diagonal case, and **exact for a uniform scale**: `MᵀM` is then `s²I`, the
+ * off-diagonal sum is zero, and both values come back as `s`. That matters more than the general
+ * case — a conservative bound that answered 5.2 for an unscaled instance would over-refine every
+ * ordinary object in a scene to buy correctness for a sheared one.
+ *
+ * **Not a degeneracy test.** σ_min is zero exactly when the matrix is singular *in exact
+ * arithmetic*, and this once said so without the qualifier. In f32 it holds only on the diagonal
+ * branch: the trigonometric one computes the smallest eigenvalue as a difference of nearly equal
+ * numbers, and the `sqrt` turns its absolute error of about `eps·σ_max²` into about
+ * `sqrt(eps)·σ_max ≈ 3.4e-4·σ_max` in σ_min. A rotated matrix with one column of zeros therefore
+ * comes back with a σ_min near 1e-4 rather than 0, and a caller testing `σ_min > 0` before
+ * inverting is let through with the NaN it was guarding against
+ * (`shader_vgeo_cut_collect`, REVIEW_LEDGER M3). A caller about to invert should test the
+ * **determinant**, which is the number the inverse divides by and which is exactly zero whenever a
+ * column is.
+ *
+ * @type {CodeChunk}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const chunk_mat3_singular_values: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_mat3_singular_values.d.ts.map

package/src/shade/renderer/shader/chunk/geometry/mat3/chunk_mat3_singular_values.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_mat3_singular_values.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/mat3/chunk_mat3_singular_values.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,yCALU,SAAS,CA6DZ;0BA1FmB,gCAAgC"}

package/src/shade/renderer/shader/chunk/geometry/mat3/chunk_mat3_singular_values.js

@@ -0,0 +1,91 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+
+/**
+ * The largest and smallest singular values of a 3×3 matrix.
+ *
+ * They are what "how much does this transform stretch a distance" actually means: a vector's length
+ * is scaled by something between σ_min and σ_max, and both bounds are attained. Column lengths are
+ * the obvious stand-in and they are **not** the same number — for
+ * `[[1,0,0],[k,1,0],[0,0,1]]`, every column has length 1 or √(1+k²) while the true ratio grows
+ * without bound in `k`. A shear has no scale in any column and stretches space anyway.
+ *
+ * Computed as the square roots of the eigenvalues of `MᵀM`, which is symmetric and positive
+ * semi-definite, through the closed form for a symmetric 3×3 (Smith 1961). No iteration, no
+ * branching past the diagonal case, and **exact for a uniform scale**: `MᵀM` is then `s²I`, the
+ * off-diagonal sum is zero, and both values come back as `s`. That matters more than the general
+ * case — a conservative bound that answered 5.2 for an unscaled instance would over-refine every
+ * ordinary object in a scene to buy correctness for a sheared one.
+ *
+ * **Not a degeneracy test.** σ_min is zero exactly when the matrix is singular *in exact
+ * arithmetic*, and this once said so without the qualifier. In f32 it holds only on the diagonal
+ * branch: the trigonometric one computes the smallest eigenvalue as a difference of nearly equal
+ * numbers, and the `sqrt` turns its absolute error of about `eps·σ_max²` into about
+ * `sqrt(eps)·σ_max ≈ 3.4e-4·σ_max` in σ_min. A rotated matrix with one column of zeros therefore
+ * comes back with a σ_min near 1e-4 rather than 0, and a caller testing `σ_min > 0` before
+ * inverting is let through with the NaN it was guarding against
+ * (`shader_vgeo_cut_collect`, REVIEW_LEDGER M3). A caller about to invert should test the
+ * **determinant**, which is the number the inverse divides by and which is exactly zero whenever a
+ * column is.
+ *
+ * @type {CodeChunk}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const chunk_mat3_singular_values = CodeChunk.from(
+    //language=WGSL
+    `
+/**
+ * @returns (largest, smallest) singular value
+ */
+fn mat3_singular_values(m: mat3x3<f32>) -> vec2<f32> {
+    // MtM, symmetric and positive semi-definite; its eigenvalues are the squared singular values
+    let a00 = dot(m[0], m[0]);
+    let a11 = dot(m[1], m[1]);
+    let a22 = dot(m[2], m[2]);
+    let a01 = dot(m[0], m[1]);
+    let a02 = dot(m[0], m[2]);
+    let a12 = dot(m[1], m[2]);
+
+    let p1 = a01 * a01 + a02 * a02 + a12 * a12;
+
+    if (p1 <= 0.0) {
+        // already diagonal — the uniform-scale case lands here, and lands exactly
+        let high = max(a00, max(a11, a22));
+        let low = min(a00, min(a11, a22));
+
+        return vec2<f32>(sqrt(max(high, 0.0)), sqrt(max(low, 0.0)));
+    }
+
+    let q = (a00 + a11 + a22) / 3.0;
+
+    let d0 = a00 - q;
+    let d1 = a11 - q;
+    let d2 = a22 - q;
+
+    let p2 = d0 * d0 + d1 * d1 + d2 * d2 + 2.0 * p1;
+
+    let p = sqrt(p2 / 6.0);
+
+    // det(B) / 2, with B = (A - qI) / p
+    let b00 = d0 / p;
+    let b11 = d1 / p;
+    let b22 = d2 / p;
+    let b01 = a01 / p;
+    let b02 = a02 / p;
+    let b12 = a12 / p;
+
+    let determinant = b00 * (b11 * b22 - b12 * b12)
+        - b01 * (b01 * b22 - b12 * b02)
+        + b02 * (b01 * b12 - b11 * b02);
+
+    // clamped because rounding can push it a hair outside acos's domain, where the whole
+    // computation would otherwise come back NaN for a perfectly ordinary matrix
+    let phi = acos(clamp(determinant * 0.5, -1.0, 1.0)) / 3.0;
+
+    let high = q + 2.0 * p * cos(phi);
+    let low = q + 2.0 * p * cos(phi + 2.0 * 3.14159265358979 / 3.0);
+
+    return vec2<f32>(sqrt(max(high, 0.0)), sqrt(max(low, 0.0)));
+}
+`, []);

package/src/shade/renderer/shader/chunk/light/DIRECTIONAL_LIGHT_STRUCT.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DIRECTIONAL_LIGHT_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/light/DIRECTIONAL_LIGHT_STRUCT.js"],"names":[],"mappings":"AAGA,oDAwB8B;6BA1BD,4BAA4B"}
+{"version":3,"file":"DIRECTIONAL_LIGHT_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/light/DIRECTIONAL_LIGHT_STRUCT.js"],"names":[],"mappings":"AAGA,oDA6B8B;6BA/BD,4BAA4B"}

package/src/shade/renderer/shader/chunk/light/DIRECTIONAL_LIGHT_STRUCT.js

@@ -25,4 +25,9 @@ export const DIRECTIONAL_LIGHT_STRUCT = WebGPUStruct.from({
      * Pointer into the shadow table for directional lights
      */
     shadow_id: u32,
+    /**
+     * The `transforms` row of the light's entity, one on. `shader_refresh_light_poses` writes the
+     * pose above from this row's `global` every frame, after the hierarchy pass.
+     */
+    node: u32,
 }, "DirectionalLight").pack();

package/src/shade/renderer/shader/chunk/light/POINT_LIGHT_STRUCT.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"POINT_LIGHT_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/light/POINT_LIGHT_STRUCT.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH,iCAFU,YAAY,CA2BE;6BA/BK,4BAA4B"}
+{"version":3,"file":"POINT_LIGHT_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/light/POINT_LIGHT_STRUCT.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH,iCAFU,YAAY,CAgCE;6BApCK,4BAA4B"}

package/src/shade/renderer/shader/chunk/light/POINT_LIGHT_STRUCT.js

@@ -30,4 +30,9 @@ export const POINT_LIGHT_STRUCT = WebGPUStruct.from({
      * Pointer into the shadow table for point lights
      */
     shadow_id: u32,
+    /**
+     * The `transforms` row of the light's entity, one on. `shader_refresh_light_poses` writes the
+     * pose above from this row's `global` every frame, after the hierarchy pass.
+     */
+    node: u32,
 }, "PointLight").pack();

package/src/shade/renderer/shader/chunk/light/SPOT_LIGHT_STRUCT.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SPOT_LIGHT_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/light/SPOT_LIGHT_STRUCT.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH,gCAFU,YAAY,CA2BZ;6BA/BmB,4BAA4B"}
+{"version":3,"file":"SPOT_LIGHT_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/light/SPOT_LIGHT_STRUCT.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH,gCAFU,YAAY,CAgCZ;6BApCmB,4BAA4B"}

package/src/shade/renderer/shader/chunk/light/SPOT_LIGHT_STRUCT.js

@@ -30,4 +30,9 @@ export const SPOT_LIGHT_STRUCT = WebGPUStruct.from({
      * Pointer into the shadow table for the spot lights
      */
     shadow_id: u32,
+    /**
+     * The `transforms` row of the light's entity, one on. `shader_refresh_light_poses` writes the
+     * pose above from this row's `global` every frame, after the hierarchy pass.
+     */
+    node: u32,
 }).pack();

package/src/shade/renderer/shadow/map/DirectionalLightShadowmap.d.ts

@@ -10,8 +10,47 @@ export class DirectionalLightShadowmap extends Shadowmap {
      */
     distance_max: number;
     splits: Float32Array;
+    /**
+     * The row of the light database's `shadow_csm_caster_range` table this map's caster range is
+     * published into, claimed by the shadow context with the map; -1 until then.
+     *
+     * @type {number}
+     */
+    caster_row: number;
+    /**
+     * Per cascade, the nearest caster along the light's axis that the GPU measured — from the
+     * world origin, the previous frame's cascade frusta — as the readback delivered it. NaN until
+     * the first delivery, which is what {@link caster_range_valid} reads: the readback writes these
+     * bytes only when a request lands, and a request that was dropped leaves them as they were.
+     *
+     * @type {Float32Array}
+     */
+    caster_range: Float32Array;
+    /**
+     * Whether {@link caster_range} has ever been delivered.
+     *
+     * @type {boolean}
+     */
+    caster_range_valid: boolean;
+    /**
+     * What the accumulate pass measures this frame's casters against: the light's axis and each
+     * cascade's four side planes, as {@link update} fitted them. `base` is the shadow context's.
+     *
+     * `planes` is what is marshalled — a vec4 per plane — and `planes_words` the one buffer those
+     * are views over, which {@link update} writes.
+     *
+     * @type {{z_axis: Float32Array, planes: Float32Array[], planes_words: Float32Array, base: number, cascade_count: number}}
+     */
+    caster_settings: {
+        z_axis: Float32Array;
+        planes: Float32Array[];
+        planes_words: Float32Array;
+        base: number;
+        cascade_count: number;
+    };
     update(main_camera: any, scene_ctx: any): void;
     make_record(): any[];
+    #private;
 }
 import { Shadowmap } from "./Shadowmap.js";
 //# sourceMappingURL=DirectionalLightShadowmap.d.ts.map

package/src/shade/renderer/shadow/map/DirectionalLightShadowmap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DirectionalLightShadowmap.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/DirectionalLightShadowmap.js"],"names":[],"mappings":"AAkGA;IACI;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB,qBAAuD;IAEvD,+CAqQC;IAED,qBAYC;CAEJ;0BA3WyB,gBAAgB"}
+{"version":3,"file":"DirectionalLightShadowmap.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/DirectionalLightShadowmap.js"],"names":[],"mappings":"AAiGA;IACI;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB,qBAAuD;IAEvD;;;;;OAKG;IACH,YAFU,MAAM,CAEA;IAEhB;;;;;;;OAOG;IACH,cAFU,YAAY,CAEiD;IASvE;;;;OAIG;IACH,oBAFU,OAAO,CAEU;IAE3B;;;;;;;;OAQG;IACH,iBAFU;QAAC,MAAM,EAAE,YAAY,CAAC;QAAC,MAAM,EAAE,YAAY,EAAE,CAAC;QAAC,YAAY,EAAE,YAAY,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAC,CAYpH;IAEL,+CAiQC;IAED,qBAYC;;CAEJ;0BA5ZyB,gBAAgB"}