@woosh/meep-engine 3.14.4 → 3.14.5

package/src/shade/renderer/animation/SKINNING_FRAME_PLAN.md

@@ -0,0 +1,357 @@
+# The skinning frame
+
+**Status:** phase 1 landed, §9 with it, both confirmed on a device. §4 is detected but not
+carried.
+
+A skinned mesh's vertices are written in a frame, and the renderer re-applies that frame. Today the
+frame is whatever the asset's mesh node happens to carry, and nothing checks that it is a frame the
+skinning pass can actually work in. This plan makes the frame the engine's, derived from the skin,
+and makes the condition it must satisfy a checked one.
+
+## 1. The defect
+
+The pipeline is two multiplications:
+
+```
+A_j(t) = joint.global(t) · inverse_bind        shader_skin_matrix_prep writes this
+M_j(t) = mesh.global⁻¹ · A_j(t)                chunk_skin_blend_mesh_local converts this to a DQ
+```
+
+`dual_quat_from_m4` builds a unit quaternion out of `sqrt(max(0, 1 ± m00 ± m11 ± m22))`. It can
+represent a rotation and a translation and nothing else, so **`M_j` must be rigid**. Whether it is
+depends on `mesh.global` — a value the exporter chose, that glTF declares meaningless for a skinned
+mesh, and that this engine neither derives nor validates.
+
+`compute_skin_world_bounds` already refuses to use `mesh.global` for exactly that reason, and says
+so in its doc comment. The skinning pass still does, and inverts it.
+
+### What it looks like when it is violated
+
+Measured on `test_assets/Michelle.glb`, in `playground/skinned_mesh_soup/__soup_blend_probe.spec.js`
+— the shader's own chunks ported to JS and run over the character's own matrices:
+
+| | |
+| --- | --- |
+| `joint.global · inverse_bind` at rest | the **identity**, for all 65 joints |
+| `mesh.global` | `0.01` scale × the file's up-axis rotation |
+| column length of `M_j` | **100.0000**, at rest and under the dance, where rigid is 1 |
+
+At rest every joint folds to the *same* matrix, `100·Rx(90°)`, whose `w` and `x` terms are both
+`1 + 100` and whose `y` and `z` both clamp to zero — the normalize recovers `Rx(90°)` by luck, and
+only the scale is lost. Output is `expected / 100` to the digit: the right character, 1/100 the
+size.
+
+Under the dance the joints' matrices differ, each loses a different amount, and the mesh comes
+apart. Mean error 121 in a mesh-local space where the body is 224 across; worst 165, on vertices
+bound to **a single joint at weight 1**, so the blend is not even involved. That is the soup.
+
+### What it is not
+
+Ruled out on the CPU, on the parsed asset, before a GPU is involved
+(`playground/skinned_mesh_soup/__soup_probe.spec.js`):
+
+- the geometry is a surface — 28 106 triangles, no degenerates, longest edge 0.093 against a 2.24
+  diagonal, every meshlet index in range;
+- the skinning attributes are sound — all 19 106 vertices land back on their rest position under
+  `joint.global · inverse_bind`, no zero-weight vertices, no out-of-range joint;
+- the source BLAS is exact — 56 211 nodes all reachable, 28 106 leaves each naming a distinct
+  triangle whose box matches to the bit, all 28 105 internal nodes exactly their children's union.
+
+Worth stating plainly: `skinned_blas_refit`'s `verify()` is structurally blind to this. It holds the
+tree's root box against the bounds chain's box, and **both derive from the clone's vertex region**.
+Vertices wrong in the same way agree with each other perfectly. A green `verify()` and a soup
+picture are consistent, and were.
+
+### The precondition as currently written is the wrong one
+
+`chunk_skin_blend_mesh_local` states it as *"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."* Michelle's
+joints and mesh node **do** share their scaling ancestor (`Character`, carrying the 0.01), and it
+still breaks. Sharing ancestors is neither necessary nor sufficient. §2 is the condition that is.
+
+## 2. The invariant
+
+At rest, `A_j` collapses to one matrix for every joint — `compute_skin_world_bounds` already names
+it, as "the character's placement in the world". Call it `A_bind`.
+
+> **A skinned mesh's node transform is not the file's. It is the skin's bind transform:
+> `mesh.global == A_bind`.**
+
+Three consequences, each of them testable:
+
+1. `M_j(rest) = I`. The clone at rest is bit-identical to the source geometry — which `SkinnedMesh`'s
+   class doc already claims ("until bound … its vertices stay at the source's bind-pose values") and
+   today only accidentally delivers.
+2. `M_j(t) = A_bind⁻¹ · A_j(t)` — the joint's **displacement from bind**. Rigid exactly when the clip
+   rotates and translates and does not scale. That is the honest precondition of dual-quaternion
+   skinning: a property of the *animation*, not of the exporter's unit conventions.
+3. It is *checkable* — from data the engine already holds, on the CPU, once per skin.
+
+## 3. Enforcement
+
+At `register_skin`, per skinned mesh:
+
+```
+C := mesh.global⁻¹ · A_bind
+mesh.transform_local := mesh.transform_local · C
+mesh.updateMatrices()
+```
+
+- **`C` is constant.** Anything applied above both the mesh node and the joints — placement,
+  movement, re-parenting — left-multiplies `mesh.global` and `A_bind` alike and cancels. Compute it
+  once.
+- **It is idempotent.** After the correction `mesh.global == A_bind`, so a second `C` is the
+  identity. Re-registering a skin changes nothing.
+- **It is a no-op for an asset that already satisfies the invariant.** An FBX-derived model whose
+  inverse-bind matrices are authored in pre-scale space has `A_bind == mesh.global` and gets
+  `C = I`. That is the no-regression pin, and it is a test rather than an assumption.
+- For Michelle, `C = 100·R⁻¹` on `Ch03`, whose local transform is the identity today.
+
+### Why this layer
+
+The mesh node is the last node on the mesh-only path — the one place a correction reaches the mesh
+without disturbing the joints. Correcting it fixes the frame identically for the rasterizer, the
+path tracer, the TLAS instance transform, the bounds chain and the motion vectors, because all of
+them read one transform. **No shader changes. No per-vertex cost.** One matrix per skin, once.
+
+`register_skin` rather than the loader because every skin passes through it — glTF, USD, the
+editor, `instantiate_scene_bundle`, and skins built in code, which never see a loader at all.
+
+### The sharp edge
+
+Children of a skinned mesh node would inherit the correction. In this engine sockets, effect anchors
+and projectile spawns are authored as *bones*, so a skinned mesh node should have no children — but
+"should" is what got us here. The normalisation asserts it, and says which node and which children if
+it fires.
+
+### Where it is not representable
+
+`Transform64` recomposes its local from TRS components, so a correction carrying shear does not
+survive the round trip. Rather than test `C` for shear, the normalisation applies it and then
+measures the residual directly — `max |mesh.global − A_bind|` — which is the end-to-end quantity and
+catches decomposition loss, a non-agreeing skeleton and a bad `C` in one number.
+
+## 4. What no frame can fix
+
+The correction absorbs a *constant* linear part. A clip that scales a joint makes `A_j` non-rigid
+per joint and per frame, and no choice of frame fixes that. The ladder:
+
+| `A_j` | answer |
+| --- | --- |
+| rigid | DQS, unchanged. Every asset in practice. |
+| per-joint **uniform** scale | DQS with scale: factor `M_j = S(s_j) · (Rot \| t/s_j)`, DQ the rigid part, blend `s = Σ wⱼsⱼ` alongside, multiply the transformed point by `s`. One divide and one multiply per joint. |
+| **non-uniform** or sheared | a dual quaternion cannot represent it at all. Either a per-skin linear-blend path — correct, candy-wrapper on those assets only — or a hard import error. |
+
+### The detector — landed
+
+Rows 2 and 3 are contingencies rather than requirements, so neither is carried. What *is* built is
+the thing that says whether they are ever needed, and it says it without a device:
+`skin_clip_scale_conflicts`, called from `register_skin` and `register_clip` alike.
+
+The condition is sharper than this section first stated. "A clip animating a `Scale` channel on a
+joint" understates it in one direction and overstates it in another, and both matter:
+
+- a scale on the character's **own root** reaches the mesh *and* every joint, enters `mesh.global`
+  and every `joint.global` alike, and cancels out of the fold. That is how a model is made to grow
+  and it has to stay legal — a joint-targeting test would have called it clean, which is right by
+  luck, and a "does it scale anything under the skin" test would have called it broken, which is
+  wrong;
+- a scale on a node **above only some of the joints** never targets a joint at all and breaks the
+  fold exactly as a joint-targeted one does.
+
+So the question is reachability, not targeting: **a scale is safe exactly when the node carrying it
+reaches the mesh and all of the joints, or none of them.** Anything between is a conflict.
+
+Two further refinements the curves themselves settle. A channel whose curves never leave 1 is not a
+scale, whatever it targets — clips arrive unoptimized and an identity channel on a joint is noise.
+And the range comes from `animation_curve_compute_aabb`, which follows the Hermite spline between
+keys rather than reading the keys alone: a curve that leaves 1 and returns to it scales the joints
+for most of the clip, and reading its endpoints would call it flat.
+
+The report says which rung would be needed. `uniform` is true only when all three axes are driven by
+equal curves, so an axis left unanimated — a squash — reads as non-uniform, which is the safe
+direction.
+
+**Cost.** `clip_scale_channels` is asked first and is one pass over a clip's channel list with a
+`property !== Scale` early-out. A clip that scales nothing is remembered by nothing and compared
+against nothing, which is every clip a character normally carries. Only a clip that scales something
+is held in the manager's index and paired off against the registered skins, in both registration
+orders — a clip can arrive before its skin as easily as after, and neither may pass in silence.
+
+## 5. Rejected
+
+- **Patch `dual_quat_from_m4` to swallow the scale.** Moves an asset-conditioning problem into the
+  per-vertex hot loop; correct only for a uniform scale, so it still needs the check; and it leaves
+  the invariant unstated, so the next asset shape breaks it silently. The band-aid.
+- **Drop the fold; write clones in world space.** The cleanest mathematically — glTF says skinned
+  vertices are world-space and the node transform is ignored. But f32 vertex storage at world
+  coordinates costs about a millimetre of precision per ten kilometres from the origin, and it forces
+  a skinned special case into the rasterizer's uniform "apply `node.global`" path. Correctness bought
+  with a precision bug.
+- **Bake the scale into geometry at import.** Does not defend the editor's drag-and-drop or anything
+  the importer never saw; mutates geometry that content-keyed registration now keys on; costs a full
+  vertex rewrite per asset. Worth doing *additionally*, offline, so the runtime correction is a
+  no-op — not instead of it.
+
+## 6. Tiers
+
+Kept as low as they will go, for as long as they will go. Every assertion below runs without a
+device and without an asset.
+
+| tier | what it holds | file |
+| --- | --- | --- |
+| 1 — pure arithmetic | a rigid matrix has zero defect; a scaled, sheared, degenerate or reflected one is reported as it should be | `core/geom/3d/mat4/m4_rigidity_defect.spec.js` |
+| 2 — the skin, on the CPU | what each asset shape's bind transform *is*, and that the mesh node is a frame for one and not the other; the correction lands `mesh.global` on the bind transform for both; the pre-scale shape is untouched, element for element; idempotent; survives the walk; placement-invariant; children named; a skin no frame can fix is reported and left alone | `skin_bind_transform.spec.js`, `skin_normalize_mesh_frame.spec.js` |
+| 3 — the shader's own WGSL, in the emulator | a vertex lands where its skin matrix says — every joint, both bind spaces, three conversions, at rest and posed apart — plus the negative control: the same vertex on the asset's own mesh node, most of a body away | `skinning/chunk_skin_blend_mesh_local.spec.js` |
+| 2b — the clip against the skin | a scale on a joint conflicts and a scale on the character's root does not; a curve flat at 1 is not a scale and one that leaves 1 between its keys is; uniform told from squash; and the manager reports it in both registration orders | `skin_clip_scale_conflicts.spec.js` |
+| 3b — the real asset, on the CPU | the whole chain over `Michelle.glb`'s own matrices and her `SambaDance`: the folded scale, the correction, and where every sampled vertex lands, before and after | `playground/skinned_mesh_soup/__soup_blend_probe.spec.js` |
+| 4 — the browser | `?skin=bind` is a full-size character; `?skin=animated` dances | `playground/skinned_mesh_soup/` |
+
+Tier 3 is the one that would have caught this: it already ran the real chunk over a synthetic model,
+and it only ever built the one asset shape. Adding the other shape was the whole test change.
+
+**Run, on an NVIDIA RTX 4090.** Phase 1: the console reported `absorbing 99.0000 of non-rigidity the
+skinning pass could not have carried`, `?skin=bind` drew a full-size character, `?skin=animated`
+danced, and the published box came back `1.4556 × 1.6644 × 0.3872 m` — a character, not a coin.
+Then §9, whose WGSL nothing offline type-checks: compiles and runs. Then `await diagnose()` at
+`?skin=bind`, which reads the clone's vertices back off the device and holds them against the bind
+pose — **all 19 106 of them, worst error `7.96e-7`**, no wrong meshlets and no wrong vertex slots.
+That is the f32 floor of a matrix product, a quaternion conversion and a screw motion at single
+precision, and it is four orders below the smallest violation the tool can report.
+
+Held red by hand before landing: with the correction's body removed, 11 tests fail — four of them
+tier 3, and only the world-space rows. Every pre-scale row stays green, which is the no-regression
+claim stated as an experiment rather than as a hope.
+
+Measured on `Michelle.glb`, 2 486 vertices sampled, in a mesh-local space where the body is 2.24
+across:
+
+| | folded scale | mean error | worst | worst on a single-joint vertex |
+| --- | --- | --- | --- | --- |
+| bind, mesh node as the file gave it | 100.0000 | 121.2470 | 165.4281 | 165.4281 |
+| posed at 0.5 s, the same | 100.0000 | 121.6197 | 165.5332 | — |
+| bind, on the skin frame | 1.0000 | 0.0002 | 0.0016 | 0.0014 |
+| posed at 0.5 s, on the skin frame | 1.0000 | 0.0001 | 0.0062 | 0.000014 |
+| bind, skin frame **and §9** | 1.0000 | 0.0000 | 0.0000 | **0** |
+| posed at 0.5 s, skin frame and §9 | 1.0000 | 0.0001 | 0.0062 | **0.000001** |
+
+The one residual left is the blended vertices — 0.0062 at 0.76 / 0.23 across a bent joint — which is
+dual-quaternion skinning declining to be a linear blend, and is what it is for. The 0.0014 at bind
+was §9, and is gone.
+
+## 7. What landed
+
+1. `m4_rigidity_defect` — tier 1.
+2. `skin_joint_matrix`, `skin_bind_transform`, `skin_frame_defect` — the three questions, one file
+   each; `skin_test_fixtures` builds both asset shapes as scene graphs, off the hierarchy rather
+   than by hand.
+3. `skin_normalize_mesh_frame` — the correction, with the report `register_skin` logs from.
+4. `GPUAnimationManager#register_skin` calls it ahead of the bind loop, and names an asset it cannot
+   put right.
+5. Doc corrections: `chunk_skin_blend_mesh_local`'s stated precondition, `SkinnedMesh`'s class doc
+   (`transform_global` on a skinned mesh is now the engine's, and says so), and the fixture header in
+   `SkinnedMesh.spec.js` that had drawn the wrong conclusion from the right observation.
+
+Then §9, and §4's detector — `skin_clip_scale_conflicts`, with the manager keeping an index of
+skins by id and of the clips that scale anything, so the pairing runs whichever order they arrive in.
+
+Not carried: §4's rows 2 and 3 themselves. The detector is what would say they are needed.
+
+## 8. Risks
+
+- **Something reads a skinned mesh's `transform_global` expecting the file's value.**
+  `compute_skin_world_bounds` does not, and glTF says the value is meaningless for a skinned mesh.
+  After this it *means* something: the frame the mesh's vertices are expressed in. Any consumer that
+  wanted the file's node transform wanted the wrong thing.
+- **An asset whose rest pose is not its bind pose** has no single `A_bind`. The deviation number says
+  so by name rather than the engine guessing. Not seen in practice; the check is what would find it.
+- **The eighteen creature models.** Whether they satisfy the invariant today cannot be measured from
+  this repository — they are the game's. The check answers it on their first frame, which is itself
+  the argument for landing the check before the correction.
+
+## 9. Landed: `dual_quat_from_m4` was ill-conditioned near the identity
+
+Not caused by phase 1, and exposed by it. The conversion took all four quaternion components as
+
+```wgsl
+sqrt(max(0, 1 ± m00 ± m11 ± m22)) * 0.5
+```
+
+and near the identity three of those radicands are near zero. A square root turns an error of `e`
+into one of `sqrt(e)`, and it lands on the rotation *axis* rather than its angle, so it does not
+average out.
+
+Measured on Michelle after the frame correction: every folded matrix is the identity to `1.131e-6`
+(worst joint, `mixamorig:LeftUpLeg`), predicting `sqrt(3 × 1.131e-6) / 2 = 9.21e-4` per component, an
+angular error of `1.84e-3` rad, and `1.418e-3` at the worst vertex's radius. Observed: `1.402e-3` —
+a millimetre and a half on a 1.66 m character. It showed **only at bind**, because that is the one
+pose where the fold lands every joint on the identity; posed at 0.5 s the same measurement gave
+`1.4e-5`.
+
+**The fix was already in the tree.** `chunk_quat_from_m3` is Shoemake's branch-picking form —
+compute whichever component the diagonal says is largest, derive the other three by division — and
+it was written, correct, and used by nothing but a doc reference. `dual_quat_from_m4` now delegates
+its real part to it. One `sqrt` and a reciprocal instead of four `sqrt`s and a normalize, every
+branch dividing by at least 2, and the error passes through in proportion rather than as its square
+root.
+
+On Michelle: `1.402e-3` → `0` at bind, `1.4e-5` → `1e-6` posed.
+
+Three tiers, all device-free. `chunk_quat_from_m3.spec.js` is new, because delegating put a chunk
+with no spec of its own on the path of every skinned vertex: a sweep of rotations about four axes
+against what the matrix does to three off-axis probes, all four branches reached and each exact
+where it takes over, the near-identity scaling law over three decades, and a hair either side of a
+half turn. `chunk_dual_quat_from_m4.spec.js` gained the composed form of the same question and a
+case for a translation carried by a rotation that is barely there. `__soup_blend_probe.spec.js`'s
+ported chunk follows the real one, and its single-joint tolerance went from `5e-3` to `1e-5`.
+
+Held red by hand, with the four-`sqrt` form swapped back in: four tests fail. The near-identity one
+reports `0.000863` against the `8.66e-4` predicted above — three digits — and, as a bonus nobody was
+looking for, a genuine rotation of `1e-5` came back as **exactly zero**: f32 rounds the diagonal to 1,
+every radicand to 0 or 4, and the rotation is not amplified but destroyed.
+
+One consequence worth naming: the old form recovered `Rx(90°)` exactly from `100·Rx(90°)`, because
+its `w` and `x` radicands were both `1 + 100` and its `y` and `z` both clamped — the coincidence §1
+describes, where only the scale was lost and the character came out the right shape at 1/100 size.
+The branch form has no such luck, so a frame violation now looks wrong rather than small. That is the
+better failure, and the negative controls in `chunk_skin_blend_mesh_local.spec.js` still hold.
+
+### Still open
+
+`quat_from_m3` reads a matrix's upper 3×3 as a rotation, which is the same contract
+`dual_quat_from_m4` has and the same one `m4_rigidity_defect` exists to check. Nothing calls it with
+a scale on purpose now, and nothing warns if something starts to.
+
+## 10. Adversarial review
+
+Of §§1–9's own work, after it was green. Findings in the order they matter.
+
+| | severity | finding | resolution |
+| --- | --- | --- | --- |
+| A1 | **must-fix** | `transform_global` is derived and a fresh `Transform64` is the **identity**, not zeros — so a skin whose scene has never been walked answers "every joint is at the origin", and that answer passes every check in §3. The folds come out `inverse_bind_0⁻¹ × inverse_bind_j`, which on a real character differ by rigid motions and read as perfectly rigid; a correction would be computed from nothing, applied, and then confirmed by a residual whose two halves both come from the same unwalked state. The exact class of silent wrongness this whole change exists to end, reintroduced inside its own guard. | **Fixed.** `Node3D#version` is bumped by `updateMatrices` and by nothing else, so a node at version 0 has never been derived. `skin_normalize_mesh_frame` refuses before measuring, reports the nodes, and `register_skin` names one. Pinned twice: the refusal, and the premise — that an all-identity skeleton scores under `1e-6` on the defect. |
+| A2 | **must-fix** | A reflection scores **zero** on `m4_rigidity_defect`, because it is orthonormal and that is what the defect measures. So a mirrored joint passed the frame check and `quat_from_m3` would answer with a rotation, silently. The one way a fold can be unrepresentable and still look perfect. | **Fixed.** `skin_frame_defect` checks the sign of the fold's linear determinant and answers `Infinity`. A reflection the frame and every joint share cancels and never reaches it, so what does reach it is a skeleton disagreeing with itself about handedness, which no frame reconciles. |
+| A3 | should-fix | `skin_frame_defect_by_joint` — the diagnostic that says *which* joint — did not make A2's refusal, so the gate and the explanation of the gate would have disagreed about which joints were the problem. | **Fixed** alongside A2, and the test now asserts both halves: joint 0 clean, joints 1 and 2 `Infinity`. |
+| A4 | should-fix | `__soup_probe.spec.js`'s bind-pose probe compared against `mesh.transform_global × rest` — a composition the renderer *cancels* — and printed "worst bind-pose deviation 1.672182" next to a `skinned` column that was exactly right. A trap rather than a measurement, and it asserted nothing. | **Fixed.** It compares against the skin's bind transform, prints `5.65e-7`, and now asserts: no zero-weight vertices, no out-of-range joints, worst under `1e-5`. |
+| A5 | nit | `skin_normalize_mesh_frame` measured `frame_defect` before the unwalked check could reject the data it was measured from, leaving a meaningful-looking number in a report where it meant nothing. | **Fixed**: measured after the refusal, `NaN` before it, and said so in the return doc. |
+| A6 | nit | `chunk_dual_quat_from_m4`'s doc claimed "one `sqrt` and a reciprocal, against four `sqrt`s and a normalize" while keeping the normalize. | **Fixed**, and the normalize's actual job — a degenerate 3×3, where `quat_from_m3` lands on a branch whose answer has length 0.5 — is stated instead of implied. |
+| A7 | nit | `verify_clone_vertices` dereferenced an unregistered source geometry's record. | **Fixed**: reported as a verdict rather than a `TypeError`. |
+| A8 | nit | The rotation fixture in `chunk_quat_from_m3.spec.js` recomputed one cross product three times, and — found the hard way — took its axis on trust. `[0.4243, -0.5657, 0.7071]` has norm `0.99982`, and that `1.8e-4` came back out as `1.15e-4` of "disagreement" that read as a defect in the conversion for a good ten minutes. | **Fixed**: normalized in the fixture, with the incident in its doc comment so the next person does not spend the ten minutes. |
+
+### Left, with reasons
+
+- **`skin_bind_transform` takes joint 0's matrix.** In a file whose rest pose is its bind pose every
+  joint answers the same one. In a file where they differ there is no single answer, and it does not
+  matter: the frame cancels out of the rendered position entirely — `mesh.global × (mesh.global⁻¹ ×
+  A_j) = A_j` for any invertible frame — so the frame's only job is to make `M_j` *representable*, and
+  `skin_frame_defect` is what checks that. Joints disagreeing by rigid motions cost nothing.
+- **A skeleton walked, then moved, then not walked again.** Not detectable by `version`, which counts
+  walks rather than staleness. The mesh half of it *is* caught: the correction is computed from the
+  stale global but applied to the local, and the residual is measured against the live one, so it
+  fires. The joint half is the caller's contract.
+- **The `TOLERANCE` constant gates two different quantities** — a dimensionless rigidity measure and
+  a matrix distance mixing linear and translation units. Defensible at `1e-4` against a smallest real
+  violation of `99`, and splitting it would invite two numbers nobody can justify separately.
+- **No offline tier in this engine type-checks WGSL.** The emulator builds the whole skinning shader
+  from its chunk graph, which catches an undefined function and a syntax error, and that is where the
+  coverage stops. §9's `mat3x3<f32>(m[0].xyz, …)` was settled by a page load rather than by a test,
+  and the next chunk edit will be too.

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

@@ -0,0 +1,25 @@
+/**
+ * The transform that maps this skin's mesh-space geometry into the world at rest.
+ *
+ * `compute_skin_world_bounds` already names the thing: *"with every joint at its bind pose
+ * `joint.global × inverse_bind` collapses to one and the same matrix, the character's placement in
+ * the world"*. This returns that matrix. It is the frame a skinned mesh's vertices belong in, and
+ * under {@link skin_normalize_mesh_frame} it becomes the mesh node's transform — see
+ * `SKINNING_FRAME_PLAN.md`.
+ *
+ * **Joint 0's is the one taken.** In a file whose rest pose is its bind pose every joint answers the
+ * same matrix, so which one is asked is not a choice; in a file where they differ there is no single
+ * answer and no amount of averaging makes one. What matters is not that they agree but that
+ * `frame⁻¹ · joint_matrix` comes out rigid for every joint, which is a weaker condition and a
+ * different question — {@link skin_frame_defect} is that question, and it is the one to ask.
+ *
+ * Reads the joints' `transform_global`, so the skeleton has to have been walked
+ * ({@link Node3D#updateMatrices}) since it was last moved. Joints under
+ * {@link TransformAuthority.GPU} hold the rest pose there, which is what this wants.
+ *
+ * @param {Float64Array|Float32Array|number[]} out 16 elements, column-major
+ * @param {Skin} skin
+ * @returns {Float64Array|Float32Array|number[]} `out`
+ */
+export function skin_bind_transform(out: Float64Array | Float32Array | number[], skin: Skin): Float64Array | Float32Array | number[];
+//# sourceMappingURL=skin_bind_transform.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"skin_bind_transform.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/skin_bind_transform.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,yCAJW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,eAEhC,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,CAQ9C"}

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

@@ -0,0 +1,33 @@
+import { assert } from "../../../core/assert.js";
+import { skin_joint_matrix } from "./skin_joint_matrix.js";
+
+/**
+ * The transform that maps this skin's mesh-space geometry into the world at rest.
+ *
+ * `compute_skin_world_bounds` already names the thing: *"with every joint at its bind pose
+ * `joint.global × inverse_bind` collapses to one and the same matrix, the character's placement in
+ * the world"*. This returns that matrix. It is the frame a skinned mesh's vertices belong in, and
+ * under {@link skin_normalize_mesh_frame} it becomes the mesh node's transform — see
+ * `SKINNING_FRAME_PLAN.md`.
+ *
+ * **Joint 0's is the one taken.** In a file whose rest pose is its bind pose every joint answers the
+ * same matrix, so which one is asked is not a choice; in a file where they differ there is no single
+ * answer and no amount of averaging makes one. What matters is not that they agree but that
+ * `frame⁻¹ · joint_matrix` comes out rigid for every joint, which is a weaker condition and a
+ * different question — {@link skin_frame_defect} is that question, and it is the one to ask.
+ *
+ * Reads the joints' `transform_global`, so the skeleton has to have been walked
+ * ({@link Node3D#updateMatrices}) since it was last moved. Joints under
+ * {@link TransformAuthority.GPU} hold the rest pose there, which is what this wants.
+ *
+ * @param {Float64Array|Float32Array|number[]} out 16 elements, column-major
+ * @param {Skin} skin
+ * @returns {Float64Array|Float32Array|number[]} `out`
+ */
+export function skin_bind_transform(out, skin) {
+    assert.defined(skin, 'skin');
+    assert.equal(skin.isSkin, true, 'skin.isSkin !== true');
+    assert.greaterThanOrEqual(skin.joints.length, 1, 'skin.joints.length');
+
+    return skin_joint_matrix(out, skin, 0);
+}

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

@@ -0,0 +1,67 @@
+/**
+ * The channels of a clip that would scale this skin's joints out from under the frame it is
+ * deformed in.
+ *
+ * ## Why this is worth asking
+ *
+ * {@link skin_normalize_mesh_frame} makes `inverse(mesh.global) × joint.global × inverse_bind`
+ * rigid, and rigid is what a dual quaternion can carry. It does that with a **constant** correction,
+ * which is sound because the frame and the joints share their ancestors and a placement multiplies
+ * both on the left. A clip that scales a joint breaks that: the scale enters `joint.global` and not
+ * the frame, the fold stops being rigid, and no choice of frame fixes it —
+ * `SKINNING_FRAME_PLAN.md` §4 is the ladder out and neither of its rungs is built.
+ *
+ * The failure is per-frame and on the GPU, where nothing can see it. This is the same question asked
+ * **statically**, off the clip's own curves, at registration: exact, cheap, and it needs no device.
+ *
+ * ## What counts
+ *
+ * Not "the channel targets a joint" — that understates it. What matters is whether the scale is
+ * *shared* between the frame and the joints, and a scale is shared exactly when the node carrying it
+ * is an ancestor of the mesh **and** of every joint. So:
+ *
+ * - a scale on the character's own root reaches the mesh and all the joints, cancels out of the
+ *   fold, and is fine — this is how a model is made to grow;
+ * - a scale on a joint, or on any node above only *some* of them, reaches the joints and not the
+ *   mesh, and is a conflict;
+ * - a scale on a node that reaches neither is somebody else's business.
+ *
+ * A channel whose curves are all the constant 1 is not a scale at all, whatever it targets. The
+ * range is taken with {@link animation_curve_compute_aabb}, which follows the Hermite spline between
+ * keys rather than only reading the keys — a curve that leaves 1 and returns to it is a scale.
+ *
+ * @param {Skin} skin
+ * @param {ShadeAnimationClip} clip
+ * @returns {Array<{
+ *     channel: ShadeAnimationChannel,
+ *     node: Node3D,
+ *     uniform: boolean,
+ *     joints_reached: number,
+ *     reaches_mesh: boolean,
+ * }>} one entry per conflicting channel, empty when the clip and the skin can coexist. `uniform`
+ *     says which rung of §4's ladder would be needed: a uniform scale is one a dual quaternion could
+ *     be taught to carry alongside, a non-uniform one is not. It is `true` only when all three
+ *     components are animated by equal curves, so a channel that is uniform by coincidence of the
+ *     node's own scale reads as non-uniform — the safe direction for a report
+ */
+export function skin_clip_scale_conflicts(skin: Skin, clip: ShadeAnimationClip): Array<{
+    channel: ShadeAnimationChannel;
+    node: Node3D;
+    uniform: boolean;
+    joints_reached: number;
+    reaches_mesh: boolean;
+}>;
+/**
+ * The channels of a clip that scale something, anywhere — before any question of *whose* joints.
+ *
+ * Separated out because it is the cheap half and almost always the whole answer. A character's clips
+ * rotate and translate; a clip with no scale channel at all can be dismissed in one pass over its
+ * channel list, which is what keeps the per-`(skin, clip)` pair check from costing anything at a
+ * few hundred dancers. {@link GPUAnimationManager} asks this first and only remembers a clip that
+ * says yes.
+ *
+ * @param {ShadeAnimationClip} clip
+ * @returns {ShadeAnimationChannel[]}
+ */
+export function clip_scale_channels(clip: ShadeAnimationClip): ShadeAnimationChannel[];
+//# sourceMappingURL=skin_clip_scale_conflicts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"skin_clip_scale_conflicts.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/skin_clip_scale_conflicts.js"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,iFAZa,MAAM;IAClB,OAAa,wBAAwB;IACrC,IAAU,SAAS;IACnB,OAAa,EAAE,OAAO,CAAC;IACvB,cAAoB,EAAE,MAAM,CAAC;IAC7B,YAAkB,EAAE,OAAO,CAAC;CACzB,CAAC,CAqDJ;AAED;;;;;;;;;;;GAWG;AACH,+DAFa,uBAAuB,CAuBnC"}