@woosh/meep-engine 3.14.4 → 3.14.6

package/src/shade/renderer/animation/skin_normalize_mesh_frame.js

@@ -0,0 +1,216 @@
+import { assert } from "../../../core/assert.js";
+import { m4_invert } from "../../../core/geom/3d/mat4/m4_invert.js";
+import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
+import { m4_rigidity_defect } from "../../../core/geom/3d/mat4/m4_rigidity_defect.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { skin_bind_transform } from "./skin_bind_transform.js";
+import { skin_frame_defect } from "./skin_frame_defect.js";
+
+/**
+ * How far from the bind transform a mesh node may sit and still be left alone, and how large a
+ * residual counts as landed.
+ *
+ * A `Transform64` recomposes its local matrix from f32-ish components, and the correction is applied
+ * through that round trip, so the frame arrives with rounding on it. `1e-4` is far below anything
+ * that shows — the smallest real violation seen is `99` — and far above the noise.
+ *
+ * @type {number}
+ */
+const TOLERANCE = 1e-4;
+
+/**
+ * Put a skin's meshes into the frame the skin actually deforms in.
+ *
+ * ## What it does and why
+ *
+ * The skinning pass writes each clone's vertices in `inverse(mesh.global)` space and the rasterizer
+ * re-applies `mesh.global`, so `mesh.global` is the *frame* a skinned mesh's vertices live in. The
+ * pass gets there by converting `inverse(mesh.global) × joint.global × inverse_bind` to a dual
+ * quaternion, which carries a rotation and a translation and **nothing else** — so that product has
+ * to be rigid, and whether it is depends entirely on `mesh.global`.
+ *
+ * glTF says a skinned mesh's node transform is ignored, so it is not the asset's to choose. This
+ * makes it the engine's, and sets it to the one frame that is guaranteed to work: the skin's own
+ * bind transform, `joint.global × inverse_bind` at rest — see {@link skin_bind_transform}. After
+ * this, `inverse(mesh.global) × joint.global × inverse_bind` is the joint's **displacement from
+ * bind**, which is rigid whenever the clip rotates and translates and does not scale. That is the
+ * honest precondition of dual-quaternion skinning, and it is a property of the animation rather than
+ * of the exporter's unit conventions.
+ *
+ * `SKINNING_FRAME_PLAN.md` is the whole argument, including what a violation looks like on screen.
+ *
+ * ## Properties worth knowing
+ *
+ * - **Idempotent.** Afterwards `mesh.global` *is* the bind transform, so a second call computes the
+ *   identity and changes nothing. Re-registering a skin is free.
+ * - **Placement-invariant.** The correction is `mesh.global⁻¹ × bind`, and anything applied above
+ *   both the mesh node and the joints — a placement, a walk cycle moving the character — multiplies
+ *   both on the left and cancels. Computed once, correct forever.
+ * - **A no-op for an asset that already agrees.** A file whose inverse-bind matrices are authored
+ *   before its root's unit conversion has `bind == mesh.global` already and is not touched. That is
+ *   the shape this engine's creature models are said to have, and it is what keeps this from being
+ *   a change to them.
+ *
+ * ## What it cannot fix
+ *
+ * A skin whose *own* bind frame does not work — a rest pose carrying a non-uniform scale or a shear,
+ * or joints that disagree about more than a rigid motion. No choice of frame fixes those; a dual
+ * quaternion cannot represent them at all. `frame_defect` in the report is that case, and when it
+ * fires nothing is written: the mesh is left as the asset had it rather than moved somewhere equally
+ * wrong. See `SKINNING_FRAME_PLAN.md` §4 for the ladder out.
+ *
+ * @param {Skin} skin its joints and meshes must have been walked — this reads `transform_global`,
+ *        which is derived. A skin that has never been walked at all is refused rather than
+ *        measured; one walked and then moved is the caller's to walk again, and the residual
+ *        below is what notices if the mesh half of that was missed
+ * @returns {{
+ *     frame_defect: number,
+ *     absorbed: number,
+ *     corrected: number,
+ *     unchanged: number,
+ *     residual: number,
+ *     obstructed: Node3D[],
+ *     unwalked: Node3D[],
+ * }} `frame_defect` — how far the skin is from being deformable in *any* frame, zero when it is
+ *    fine and `NaN` when `unwalked` stopped it being asked; `absorbed` — how far from rigid the largest correction was, which for a violation is the
+ *    number the soup was made of; `corrected` and `unchanged` — meshes moved and meshes already
+ *    right; `residual` — the worst `|mesh.global − bind|` left afterwards; `obstructed` — corrected
+ *    mesh nodes that had children, which have been scaled along with them; `unwalked` — joints or
+ *    meshes whose `transform_global` has never been derived, which stops everything else
+ */
+export function skin_normalize_mesh_frame(skin) {
+    assert.defined(skin, 'skin');
+    assert.equal(skin.isSkin, true, 'skin.isSkin !== true');
+
+    const unwalked = skin.joints.filter(joint => joint.version === 0)
+        .concat(skin.meshes.filter(mesh => mesh.version === 0));
+
+    const report = {
+        // not measured until there is something worth measuring — see the refusal below
+        frame_defect: Number.NaN,
+        absorbed: 0,
+        corrected: 0,
+        unchanged: 0,
+        residual: 0,
+        obstructed: [],
+        unwalked,
+    };
+
+    if (unwalked.length > 0) {
+        /*
+         Everything below reads `transform_global`, which is derived and starts at the **identity** —
+         not at zero. A skeleton nobody has walked therefore answers "every joint is at the origin"
+         rather than answering with a singular matrix, and that answer is well-formed enough to pass
+         every check here: the folds come out `inverse_bind_0⁻¹ × inverse_bind_j`, which for a real
+         character differ by rigid motions and so read as perfectly rigid. A correction would then be
+         computed from nothing and applied, and the residual below would agree with itself, because
+         both halves of it come from the same unwalked state.
+
+         `version` is the one thing that tells the two apart: `updateMatrices` bumps it, and nothing
+         else does. Refusing here rather than asserting because a caller who has not walked has a
+         scene that is not ready, not a bug in this.
+        */
+        return report;
+    }
+
+    const bind = new Float64Array(16);
+
+    skin_bind_transform(bind, skin);
+
+    report.frame_defect = skin_frame_defect(skin, bind);
+
+    if (!(report.frame_defect <= TOLERANCE)) {
+        // `!(x <= t)` rather than `x > t` so that a NaN — a singular joint matrix — lands here too
+        return report;
+    }
+
+    const inverse_global = new Float64Array(16);
+    const correction_matrix = new Float64Array(16);
+
+    const correction = new Transform64();
+
+    const meshes = skin.meshes;
+
+    for (let i = 0; i < meshes.length; i++) {
+        const mesh = meshes[i];
+
+        if (!m4_invert(inverse_global, mesh.transform_global)) {
+            // a mesh node with no inverse is not a frame either; the skinning pass inverts this
+            report.residual = Infinity;
+            continue;
+        }
+
+        m4_multiply(correction_matrix, inverse_global, bind);
+
+        const absorbed = m4_rigidity_defect(correction_matrix);
+
+        report.absorbed = Math.max(report.absorbed, absorbed);
+
+        if (matrix_distance(correction_matrix, IDENTITY) <= TOLERANCE) {
+            report.unchanged++;
+            continue;
+        }
+
+        /*
+         The correction goes on the **local** transform, on the right. `transform_global` is derived —
+         `updateMatrices` recomputes it from the local and the parent chain — so a frame written
+         there is discarded by the next walk; and the mesh node is the last node on the mesh-only
+         path, so this is the one place a correction reaches the mesh without reaching the joints.
+        */
+        correction.fromMatrix(correction_matrix);
+
+        mesh.transform_local.multiply(correction);
+
+        mesh.updateMatrices();
+
+        report.corrected++;
+        report.residual = Math.max(report.residual, matrix_distance(mesh.transform_global, bind));
+
+        if (mesh.children.length > 0) {
+            /*
+             Children of a skinned mesh node inherit the correction, and it is not a transform they
+             asked for. In this engine sockets, effect anchors and projectile spawns are authored as
+             bones, so a skinned mesh node should have none — but that is a convention, and this is
+             where it would be broken silently.
+            */
+            report.obstructed.push(mesh);
+        }
+    }
+
+    return report;
+}
+
+/**
+ * @type {Float64Array}
+ */
+const IDENTITY = new Float64Array([
+    1, 0, 0, 0,
+    0, 1, 0, 0,
+    0, 0, 1, 0,
+    0, 0, 0, 1,
+]);
+
+/**
+ * The largest element-wise difference between two matrices.
+ *
+ * Element-wise rather than a norm because it is read against a tolerance, and because the two things
+ * it has to catch — a linear part that did not land and a translation that did not — are both
+ * element-wise. Mixing units is the point: any of them being wrong is the same answer.
+ *
+ * @param {ArrayLike<number>} a
+ * @param {ArrayLike<number>} b
+ * @returns {number}
+ */
+function matrix_distance(a, b) {
+    let worst = 0;
+
+    for (let i = 0; i < 16; i++) {
+        const difference = Math.abs(a[i] - b[i]);
+
+        if (difference > worst) {
+            worst = difference;
+        }
+    }
+
+    return worst;
+}

package/src/shade/renderer/animation/skin_test_fixtures.d.ts

@@ -0,0 +1,86 @@
+/**
+ * A rigged character in one of the two shapes.
+ *
+ * The rest pose **is** the bind pose, which is what a well-formed file has. The bind matrices are
+ * taken off the skeleton itself rather than composed by hand: the fixture walks the hierarchy once
+ * with the root's conversion in place and once without, and the two snapshots *are* the two bind
+ * spaces. Nothing here can drift from the hierarchy it describes, because it is read from it.
+ *
+ * The placement node goes on last, after the bind matrices are settled — which is what happens for
+ * real, and is what makes "the correction does not depend on where the character stands" a fact this
+ * fixture can be asked about rather than an assumption.
+ *
+ * @param {object} options
+ * @param {BindSpace} options.bind_space
+ * @param {number} [options.scale] the root's uniform conversion
+ * @param {boolean} [options.up_axis_rotation] whether the root also carries the −90° about x that an
+ *        FBX-derived file pairs with its conversion. On by default: a correction that handles only
+ *        the scale passes without it.
+ * @param {number[]} [options.placement] a translation applied above the whole character
+ * @returns {{
+ *     placement: Node3D,
+ *     root: Node3D,
+ *     mesh: SkinnedMesh,
+ *     skin: Skin,
+ *     joints: Node3D[],
+ * }}
+ */
+export function make_character({ bind_space, scale, up_axis_rotation, placement, }: {
+    bind_space: BindSpace;
+    scale?: number;
+    up_axis_rotation?: boolean;
+    placement?: number[];
+}): {
+    placement: Node3D;
+    root: Node3D;
+    mesh: SkinnedMesh;
+    skin: Skin;
+    joints: Node3D[];
+};
+/**
+ * The two shapes a glTF character actually arrives in, built as scene graphs.
+ *
+ * Both are legal glTF and both are in the wild; the difference is only the space the file's author
+ * wrote the inverse-bind matrices in, and it decides whether `inverse(mesh.global) × joint.global ×
+ * inverse_bind` — the matrix the skinning pass converts to a dual quaternion — comes out rigid. See
+ * `SKINNING_FRAME_PLAN.md`.
+ *
+ * One hierarchy serves both, because the difference is not in the hierarchy:
+ *
+ * ```
+ * "placement"      added at runtime, above the file's own roots
+ * └── "Character"  the file's unit conversion and up-axis rotation
+ *     ├── "Mesh"   the skinned mesh, no local transform of its own
+ *     └── "Joint0" the joint root — the mesh node's *sibling*, as every rigged glTF has it
+ *         └── "Joint1"
+ *             └── "Joint2"
+ * ```
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * What every one of this game's creature models puts on its glTF root node — an FBX unit
+ * conversion, uniform, and inherited by the joints and the mesh node alike.
+ *
+ * @type {number}
+ */
+export const EXPORT_SCALE: number;
+/**
+ * The centimetre→metre conversion `Michelle.glb` carries on hers.
+ *
+ * @type {number}
+ */
+export const MICHELLE_SCALE: number;
+/**
+ * Where the file's author wrote the inverse-bind matrices.
+ */
+export type BindSpace = string;
+export namespace BindSpace {
+    let PreScale: string;
+    let World: string;
+}
+import { Node3D } from "../scene/Node3D.js";
+import { SkinnedMesh } from "../scene/SkinnedMesh.js";
+import { Skin } from "./Skin.js";
+//# sourceMappingURL=skin_test_fixtures.d.ts.map

package/src/shade/renderer/animation/skin_test_fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skin_test_fixtures.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/skin_test_fixtures.js"],"names":[],"mappings":"AAsFA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IAd8B,UAAU,EAA7B,SAAS;IACQ,KAAK,GAAtB,MAAM;IACY,gBAAgB,GAAlC,OAAO;IAGY,SAAS,GAA5B,MAAM,EAAE;;eAED,MAAM;UACX,MAAM;UACN,WAAW;UACX,IAAI;YACF,MAAM,EAAE;EAgFtB;AAjLD;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;GAKG;AACH,2BAFU,MAAM,CAEiB;AAEjC;;;;GAIG;AACH,6BAFU,MAAM,CAEmB;;;;wBAKzB,MAAM;;;;;uBA7CO,oBAAoB;4BACf,yBAAyB;qBAChC,WAAW"}

package/src/shade/renderer/animation/skin_test_fixtures.js

@@ -0,0 +1,250 @@
+import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
+import { platform_compute_endianness } from "../../../core/binary/platform_compute_endianness.js";
+import { m4_invert } from "../../../core/geom/3d/mat4/m4_invert.js";
+import { MeshletGeometry } from "../geometry/MeshletGeometry.js";
+import {
+    MESHLET_METADATA_STRUCT
+} from "../geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+import { StandardShadeMaterial } from "../material/StandardShadeMaterial.js";
+import { write_wgsl_type_value } from "../shader/type/serde/write_gpu_typed_buffer.js";
+import { Node3D } from "../scene/Node3D.js";
+import { SkinnedMesh } from "../scene/SkinnedMesh.js";
+import { Skin } from "./Skin.js";
+
+/**
+ * The two shapes a glTF character actually arrives in, built as scene graphs.
+ *
+ * Both are legal glTF and both are in the wild; the difference is only the space the file's author
+ * wrote the inverse-bind matrices in, and it decides whether `inverse(mesh.global) × joint.global ×
+ * inverse_bind` — the matrix the skinning pass converts to a dual quaternion — comes out rigid. See
+ * `SKINNING_FRAME_PLAN.md`.
+ *
+ * One hierarchy serves both, because the difference is not in the hierarchy:
+ *
+ * ```
+ * "placement"      added at runtime, above the file's own roots
+ * └── "Character"  the file's unit conversion and up-axis rotation
+ *     ├── "Mesh"   the skinned mesh, no local transform of its own
+ *     └── "Joint0" the joint root — the mesh node's *sibling*, as every rigged glTF has it
+ *         └── "Joint1"
+ *             └── "Joint2"
+ * ```
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * What every one of this game's creature models puts on its glTF root node — an FBX unit
+ * conversion, uniform, and inherited by the joints and the mesh node alike.
+ *
+ * @type {number}
+ */
+export const EXPORT_SCALE = 0.35;
+
+/**
+ * The centimetre→metre conversion `Michelle.glb` carries on hers.
+ *
+ * @type {number}
+ */
+export const MICHELLE_SCALE = 0.01;
+
+/**
+ * Where the file's author wrote the inverse-bind matrices.
+ *
+ * @enum {string}
+ */
+export const BindSpace = {
+    /**
+     * Before the root's conversion — the matrices invert the joints' transforms in the mesh's own
+     * pre-conversion space, so `joint.global × inverse_bind` carries the conversion and equals the
+     * mesh node's world transform. This is the arrangement `chunk_skin_blend_mesh_local` was written
+     * for, and the one where the fold cancels.
+     */
+    PreScale: 'pre-scale',
+
+    /**
+     * After it — the matrices invert the joints' world transforms as the file leaves them, so
+     * `joint.global × inverse_bind` is the **identity** and the geometry's positions are already in
+     * converted units. `Michelle.glb` is this shape, and the fold leaves a bare `1 / scale` behind.
+     */
+    World: 'world',
+};
+
+/**
+ * Rest offsets down the joint chain, in the space the geometry's positions live in — a hip, a knee
+ * and an ankle rather than three copies of the origin, so that a defect which only shows on a joint
+ * away from the origin cannot pass.
+ *
+ * @type {number[][]}
+ */
+const REST_OFFSETS = [
+    [0, 1, 0],
+    [0.25, -0.5, 0.1],
+    [-0.1, -0.45, 0],
+];
+
+/**
+ * A rigged character in one of the two shapes.
+ *
+ * The rest pose **is** the bind pose, which is what a well-formed file has. The bind matrices are
+ * taken off the skeleton itself rather than composed by hand: the fixture walks the hierarchy once
+ * with the root's conversion in place and once without, and the two snapshots *are* the two bind
+ * spaces. Nothing here can drift from the hierarchy it describes, because it is read from it.
+ *
+ * The placement node goes on last, after the bind matrices are settled — which is what happens for
+ * real, and is what makes "the correction does not depend on where the character stands" a fact this
+ * fixture can be asked about rather than an assumption.
+ *
+ * @param {object} options
+ * @param {BindSpace} options.bind_space
+ * @param {number} [options.scale] the root's uniform conversion
+ * @param {boolean} [options.up_axis_rotation] whether the root also carries the −90° about x that an
+ *        FBX-derived file pairs with its conversion. On by default: a correction that handles only
+ *        the scale passes without it.
+ * @param {number[]} [options.placement] a translation applied above the whole character
+ * @returns {{
+ *     placement: Node3D,
+ *     root: Node3D,
+ *     mesh: SkinnedMesh,
+ *     skin: Skin,
+ *     joints: Node3D[],
+ * }}
+ */
+export function make_character({
+                                   bind_space,
+                                   scale = EXPORT_SCALE,
+                                   up_axis_rotation = true,
+                                   placement = [0, 0, 0],
+                               }) {
+
+    const root = new Node3D();
+
+    root.name = 'Character';
+
+    const mesh = new SkinnedMesh();
+
+    mesh.name = 'Mesh';
+    mesh.geometry = make_geometry();
+    mesh.material = new StandardShadeMaterial();
+
+    const joints = REST_OFFSETS.map((offset, i) => {
+        const joint = new Node3D();
+
+        joint.name = `Joint${i}`;
+        joint.transform_local.setTranslation(offset[0], offset[1], offset[2]);
+
+        return joint;
+    });
+
+    for (let i = 1; i < joints.length; i++) {
+        joints[i - 1].addChild(joints[i]);
+    }
+
+    root.addChildren([mesh, joints[0]]);
+
+    /*
+     Pass one: the root at the identity, so the joints stand in the pre-conversion space an exporter
+     writing `PreScale` bind matrices was working in. Pass two adds the conversion, and the joints
+     stand where the file leaves them — the space a `World` exporter inverts.
+    */
+    root.updateMatrices();
+
+    const bind = bind_space === BindSpace.PreScale ? snapshot_joint_globals(joints) : null;
+
+    root.transform_local.setScale(scale, scale, scale);
+
+    if (up_axis_rotation) {
+        // −90° about x, as a quaternion: the Z-up of the file into the renderer's Y-up
+        root.transform_local.setRotation(-Math.SQRT1_2, 0, 0, Math.SQRT1_2);
+    }
+
+    root.updateMatrices();
+
+    const inverse_bind_matrices = new Float32Array(joints.length * 16);
+
+    const source = bind ?? snapshot_joint_globals(joints);
+
+    const inverse = new Float64Array(16);
+
+    for (let i = 0; i < joints.length; i++) {
+        m4_invert(inverse, source[i]);
+
+        inverse_bind_matrices.set(inverse, i * 16);
+    }
+
+    const skin = Skin.from({
+        name: 'fixture',
+        joints,
+        inverse_bind_matrices,
+        meshes: [mesh],
+    });
+
+    const placement_node = new Node3D();
+
+    placement_node.name = 'placement';
+    placement_node.transform_local.setTranslation(placement[0], placement[1], placement[2]);
+    placement_node.addChild(root);
+    placement_node.updateMatrices();
+
+    return { placement: placement_node, root, mesh, skin, joints };
+}
+
+/**
+ * Every joint's world matrix as it stands, copied out — a `Transform64` is live, and these are read
+ * after the hierarchy has been walked again.
+ *
+ * @param {Node3D[]} joints
+ * @returns {Float64Array[]}
+ */
+function snapshot_joint_globals(joints) {
+    return joints.map(joint => {
+        const copy = new Float64Array(16);
+
+        // a Transform64's matrix starts at element 0
+        for (let i = 0; i < 16; i++) {
+            copy[i] = joint.transform_global[i];
+        }
+
+        return copy;
+    });
+}
+
+/**
+ * One triangle in one meshlet, with enough metadata behind it to be cloned.
+ *
+ * A bare {@link MeshletGeometry} is enough for the frame arithmetic, which only ever reads bounds —
+ * but `register_skin` reaches `GPUMeshSkinningContext#bind`, which allocates a per-instance vertex
+ * clone and refuses a batch of no meshlets. A fixture that stops short of that cannot be handed to
+ * the manager at all, and the manager is where half of what this fixture is for gets tested.
+ *
+ * @returns {MeshletGeometry}
+ */
+function make_geometry() {
+    const box = [-1, 0, -1, 1, 2, 1];
+
+    const geometry = new MeshletGeometry();
+
+    geometry.name = 'fixture';
+    geometry.primitive_count = 1;
+    geometry.bounding_box.set(box);
+    geometry.bounding_sphere.set([0, 1, 0, 1.8]);
+
+    const writer = BinaryBuffer.fromEndianness(platform_compute_endianness());
+
+    writer.setCapacity(MESHLET_METADATA_STRUCT.size);
+
+    write_wgsl_type_value({
+        bounds_box: box,
+        address: 0,
+        primitive_count: 1,
+        vertex_count: 3,
+        flags: 0,
+    }, writer, MESHLET_METADATA_STRUCT);
+
+    geometry.meshlets.count = 1;
+    geometry.meshlets.data_buffer = new ArrayBuffer(3 * 3 * 4);
+    geometry.meshlets.metadata_buffer = writer.data.slice(0, MESHLET_METADATA_STRUCT.size);
+
+    return geometry;
+}

package/src/shade/renderer/animation/skinning/chunk_skin_blend_mesh_local.d.ts

@@ -17,10 +17,24 @@
  * and authors the inverse bind matrices in the pre-scale mesh space, so the skin matrix carries the
  * scale by construction.
  *
- * Preconditions: `m0`–`m3` are `joint.global × joint.inverse_bind` as
- * {@link shader_skin_matrix_prep} writes them, `inv_mesh_world` is the inverse of the skinned
- * mesh's own world matrix, and `weights` sums to 1. The four products must be rigid, which holds
- * whenever the joints and the mesh node share the scaling ancestors — the shape a glTF skin has.
+ * ## Preconditions
+ *
+ * `m0`–`m3` are `joint.global × joint.inverse_bind` as {@link shader_skin_matrix_prep} writes them,
+ * `inv_mesh_world` is the inverse of the frame the rasterizer will re-apply, and `weights` sums to
+ * 1. **The four products must be rigid.**
+ *
+ * That is a condition on the *frame*, and the frame is chosen — it is not a property of the asset to
+ * be hoped for. It used to be stated here as "the joints and the mesh node share the scaling
+ * ancestors", which is neither necessary nor sufficient: `Michelle.glb`'s joints and mesh node share
+ * theirs and her products came out at a hundredfold scale, because her inverse-bind matrices are
+ * authored *after* the conversion rather than before it and the fold therefore had nothing to
+ * cancel against. Both shapes are legal glTF and both are in the wild.
+ *
+ * The condition that does hold is `mesh.global == the skin's bind transform`, and
+ * {@link skin_normalize_mesh_frame} makes it true at `register_skin` for every asset rather than
+ * leaving it to the exporter. The product is then the joint's displacement from bind, which is rigid
+ * whenever the clip rotates and translates and does not scale. `SKINNING_FRAME_PLAN.md` is the
+ * argument, and what a violation looks like on screen.
  */
 export const chunk_skin_blend_mesh_local: CodeChunk;
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";

package/src/shade/renderer/animation/skinning/chunk_skin_blend_mesh_local.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_skin_blend_mesh_local.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/skinning/chunk_skin_blend_mesh_local.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,oDAuBE;0BAvDwB,oCAAoC"}
+{"version":3,"file":"chunk_skin_blend_mesh_local.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/skinning/chunk_skin_blend_mesh_local.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,oDAuBE;0BArEwB,oCAAoC"}

package/src/shade/renderer/animation/skinning/chunk_skin_blend_mesh_local.js

@@ -25,10 +25,24 @@ import {
  * and authors the inverse bind matrices in the pre-scale mesh space, so the skin matrix carries the
  * scale by construction.
  *
- * Preconditions: `m0`–`m3` are `joint.global × joint.inverse_bind` as
- * {@link shader_skin_matrix_prep} writes them, `inv_mesh_world` is the inverse of the skinned
- * mesh's own world matrix, and `weights` sums to 1. The four products must be rigid, which holds
- * whenever the joints and the mesh node share the scaling ancestors — the shape a glTF skin has.
+ * ## Preconditions
+ *
+ * `m0`–`m3` are `joint.global × joint.inverse_bind` as {@link shader_skin_matrix_prep} writes them,
+ * `inv_mesh_world` is the inverse of the frame the rasterizer will re-apply, and `weights` sums to
+ * 1. **The four products must be rigid.**
+ *
+ * That is a condition on the *frame*, and the frame is chosen — it is not a property of the asset to
+ * be hoped for. It used to be stated here as "the joints and the mesh node share the scaling
+ * ancestors", which is neither necessary nor sufficient: `Michelle.glb`'s joints and mesh node share
+ * theirs and her products came out at a hundredfold scale, because her inverse-bind matrices are
+ * authored *after* the conversion rather than before it and the fold therefore had nothing to
+ * cancel against. Both shapes are legal glTF and both are in the wild.
+ *
+ * The condition that does hold is `mesh.global == the skin's bind transform`, and
+ * {@link skin_normalize_mesh_frame} makes it true at `register_skin` for every asset rather than
+ * leaving it to the exporter. The product is then the joint's displacement from bind, which is rigid
+ * whenever the clip rotates and translates and does not scale. `SKINNING_FRAME_PLAN.md` is the
+ * argument, and what a violation looks like on screen.
  */
 export const chunk_skin_blend_mesh_local = CodeChunk.from(
     //language=WGSL

package/src/shade/renderer/geometry/MeshletGeometrySerializationAdapter.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Round-trips a {@link MeshletGeometry} through a `BinaryBuffer`.
+ *
+ * **This is the offline meshlet format**, and saying so is the point of this docblock: nothing
+ * documented it as the intended pipeline, so a consumer reasonably assumed
+ * {@link meshlet_geometry_build_from_geometry} was the only route from a `Geometry` to something
+ * the renderer draws — and paid 1.25 seconds of unbroken main thread per 200k-triangle level for
+ * it, at load, synchronously (GAP-008).
+ *
+ * The pipeline this supports: build the meshlets once in the asset build, serialize here, ship the
+ * bytes, and let the runtime deserialize and upload. `serialize_bvh` decides whether the BLAS
+ * travels with them or is rebuilt on load — carrying it costs bytes and saves the rebuild.
+ */
 export class MeshletGeometrySerializationAdapter extends BinaryClassSerializationAdapter<any> {
     constructor();
     klass: typeof MeshletGeometry;

package/src/shade/renderer/geometry/MeshletGeometrySerializationAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MeshletGeometrySerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/MeshletGeometrySerializationAdapter.js"],"names":[],"mappings":"AAMA;;IAGI,8BAAwB;IAGxB,uBAAqB;IAErB;;;OAGG;IACH,8BAFW,eAAe,QA6BzB;IAED;;;OAGG;IACH,gCAFW,eAAe,QAyCzB;CACJ;gDAzFM,uEAAuE;gCAE9C,sBAAsB"}
+{"version":3,"file":"MeshletGeometrySerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/MeshletGeometrySerializationAdapter.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AACH;;IAGI,8BAAwB;IAGxB,uBAAqB;IAErB;;;OAGG;IACH,8BAFW,eAAe,QA6BzB;IAED;;;OAGG;IACH,gCAFW,eAAe,QAyCzB;CACJ;gDAtGM,uEAAuE;gCAE9C,sBAAsB"}

package/src/shade/renderer/geometry/MeshletGeometrySerializationAdapter.js

@@ -4,6 +4,19 @@ import {
 import { blas_from_meshlets } from "./blas_from_meshlets.js";
 import { MeshletGeometry } from "./MeshletGeometry.js";
 
+/**
+ * Round-trips a {@link MeshletGeometry} through a `BinaryBuffer`.
+ *
+ * **This is the offline meshlet format**, and saying so is the point of this docblock: nothing
+ * documented it as the intended pipeline, so a consumer reasonably assumed
+ * {@link meshlet_geometry_build_from_geometry} was the only route from a `Geometry` to something
+ * the renderer draws — and paid 1.25 seconds of unbroken main thread per 200k-triangle level for
+ * it, at load, synchronously (GAP-008).
+ *
+ * The pipeline this supports: build the meshlets once in the asset build, serialize here, ship the
+ * bytes, and let the runtime deserialize and upload. `serialize_bvh` decides whether the BLAS
+ * travels with them or is rebuilt on load — carrying it costs bytes and saves the rebuild.
+ */
 export class MeshletGeometrySerializationAdapter extends BinaryClassSerializationAdapter {
 
     version = 0