@woosh/meep-engine 3.60.4 → 3.60.6

package/src/shade/device/timing/profile/SGPT_FORMAT.md

@@ -1,345 +0,0 @@
-# The `.sgpt` container — format specification
-
-**S**hade **G**PU **P**rofile **T**race, format version 2.
-
-This document is the normative description of the file. It is written for somebody outside Company
-Named who wants to read or write one without reading the engine's source. Every integer is
-little-endian and unsigned unless stated otherwise.
-
----
-
-## 1. What the format is for, and what it is not
-
-A capture holds **what a renderer asked a GPU to do over a run of frames, and how long each piece
-took**: pass timings, the frame graph's structure and dependencies, declared resource sizes, and
-dispatch and draw counts.
-
-It deliberately does **not** hold buffer or texture contents, shader source, or anything else that
-scales with the size of the resources it describes. That exclusion is what keeps a frame record in
-the kilobytes and makes an uncapped recording practical.
-
-### 1.1 Two properties the layout exists to provide
-
-**A truncated capture is a capture.** A recording that ended when the tab did — which is the state
-of every capture of a crash, a device loss, or a hang — must be readable up to the last intact
-record. So every record is self-framed and checksummed, symbols travel inside the record that
-introduces them, and the directory is an index over the stream rather than a prerequisite for
-reading it.
-
-**A reader may not understand everything, and must say so rather than fail.** Records carry a type
-and a length; an unrecognised type is skipped by length. This is what lets a newer writer add record
-types without a version bump, and what lets an older reader open the result and report honestly
-which parts it could not show.
-
----
-
-## 2. File header
-
-Thirty-two bytes at offset 0.
-
-| Offset | Size | Field | Notes |
-|---|---|---|---|
-| 0 | 4 | `magic` | `0x54504753` — the ASCII bytes `S`, `G`, `P`, `T` in that order |
-| 4 | 2 | `format_version` | 2 for this document |
-| 6 | 2 | `min_reader_version` | the oldest reader that can read this file correctly |
-| 8 | 4 | `flags` | see below |
-| 12 | 4 | `header_checksum` | CRC-32 over bytes `[0, 8)` **only** |
-| 16 | 8 | `directory_offset` | absolute; **0 when there is no directory** |
-| 24 | 8 | `directory_byte_length` | 0 when absent |
-
-Records begin at offset 32.
-
-### 2.1 Flags
-
-| Bit | Name | Meaning |
-|---|---|---|
-| 0 | `CLOSED` | the writer reached `stop()` and the file is complete as intended |
-
-### 2.2 Why the checksum stops at byte 8
-
-Everything from `flags` onward is written twice: zeroed when the header is laid down, and patched
-when the session stops. A checksum covering those fields would have to be recomputed at stop — fine
-for a capture that stops, and exactly wrong for one that does not, which would then carry a checksum
-over bytes that were never written and read as corrupt.
-
-What remains under the checksum is what a reader must trust before it can do anything at all: *is
-this an `.sgpt`, and can this build read it.* Those never change after the header is written.
-
-**A reader must not treat a missing `CLOSED` flag or a zero `directory_offset` as damage.** Both are
-the normal state of an interrupted session, and such a file is fully readable by §3.
-
-### 2.3 Version handling
-
-A reader **must** refuse a file whose `min_reader_version` exceeds the highest format version it
-implements, and **must** accept anything else. `min_reader_version` is raised only when a change
-would make an older reader produce *wrong* answers rather than incomplete ones — a new record type
-it would skip is incomplete; a reordered field is wrong.
-
-Format version 2 keeps `min_reader_version` at 1: it added the `TOPO` record, which a version-1
-reader skips by length, and appended a topology reference to the end of a frame's payload, which a
-version-1 reader stops before.
-
----
-
-## 3. Records
-
-Every record, whatever its type, is framed identically.
-
-| Offset | Size | Field |
-|---|---|---|
-| 0 | 4 | `sync` — `0x43455253`, the ASCII bytes `S`, `R`, `E`, `C` |
-| 4 | 4 | `record_type` — a four-character tag as a u32 |
-| 8 | 4 | `payload_byte_length` |
-| 12 | 4 | `payload_checksum` — CRC-32 over the payload bytes only |
-| 16 | … | payload |
-
-`payload_byte_length` is a u32 rather than a u64 because no record describes anything that scales
-with resource size (§1); four gigabytes is not a ceiling anything can approach.
-
-### 3.1 Reading, and resynchronising
-
-The canonical read is a **forward scan from offset 32**, not a walk of the directory:
-
-1. At the current offset, a record is present if — and only if — all four hold: the sync marker
-   matches, at least 16 bytes remain, the payload fits within the file, and the payload's CRC-32
-   matches `payload_checksum`.
-2. If it does, decode or skip it by type and advance past its payload.
-3. If it does not, scan forward one byte at a time for the next offset where all four hold. Report
-   the skipped bytes as damage; do not stop.
-4. If the scan reaches the end without finding another record, the stream was truncated inside a
-   record. Report it. Everything already decoded stands.
-
-**The sync marker alone is not sufficient and a reader must not treat it as such.** Four bytes of
-payload can spell `SREC` — a pass label could — and resynchronising onto a false positive
-desynchronises everything after it. The length and the checksum are what confirm a candidate.
-
-### 3.2 Record types
-
-| Tag | u32 | Payload | Cardinality |
-|---|---|---|---|
-| `META` | `0x4154454D` | §4 | 1, immediately after the header |
-| `SYMS` | `0x534D5953` | §5 | 0..n, always before the records referencing them |
-| `TOPO` | `0x4F504F54` | §6 | 0..n |
-| `FRAM` | `0x4D415246` | §7 | 0..n |
-| `CNTR` | `0x52544E43` | reserved | 0..1 |
-| `DIRE` | `0x45524944` | §8 | 0..1, last |
-
-An unrecognised tag **must** be skipped using `payload_byte_length`.
-
-### 3.3 Primitive encodings
-
-- `uintVar` — 7 bits per byte, low group first, high bit set on every byte but the last. Values are
-  limited to 2³¹−1.
-- `utf8` — a `uintVar` byte length followed by that many UTF-8 bytes.
-- `f64` — IEEE 754 binary64, little-endian.
-- **Optional index** — a value of −1 meaning "none", written as `uintVar(value + 1)`. Zero means
-  none.
-
----
-
-## 4. `META`
-
-| Field | Type | Notes |
-|---|---|---|
-| `level` | u8 | 0 `TIMING`, 1 `STRUCTURE`, 2 `WORKLOAD`, 3 `VERBOSE` |
-| `wall_clock_start_ms` | f64 | `Date.now()` at session start; for ordering captures, not for timing |
-| `note` | utf8 | free text from whoever captured |
-| `engine_version` | utf8 | |
-| `adapter_vendor` | utf8 | from `GPUAdapterInfo`; empty where the browser withheld it |
-| `adapter_architecture` | utf8 | |
-| `adapter_device` | utf8 | |
-| `adapter_description` | utf8 | |
-| `feature_count` | uintVar | |
-| `features` | utf8 × count | `GPUFeatureName`s the device was created with |
-
-### 4.1 On timestamp resolution — a deliberate absence
-
-**There is no field here describing the device's timestamp quantum, and adding one is out of
-scope.**
-
-Browsers quantize WebGPU timestamps as a timing-attack mitigation; Chrome to 100 µs unless
-`chrome://flags/#enable-webgpu-developer-features` is set. Most passes in a real renderer run below
-that and are reported as exactly zero.
-
-Recovering the quantum from the data — a GCD over observed timestamps, or any equivalent — *is* the
-timing attack the mitigation exists to prevent, and doing it imperfectly applies a wrong correction
-to every number in the file. So a capture records what the device reported, zeros included, and says
-nothing further. A reader that wants to present this honestly should aggregate across many frames
-rather than trust any single one, and should say so where the reader will see it.
-
----
-
-## 5. `SYMS`
-
-| Field | Type |
-|---|---|
-| `first_index` | uintVar |
-| `count` | uintVar |
-| `strings` | utf8 × count |
-
-Strings occupy one index space across the whole file; a block declares where its run begins. Every
-later reference is a `uintVar` index into that space.
-
-A `SYMS` block **always precedes** the record that references its strings. A writer must not gather
-symbols into one block at the end of the file: a capture truncated before that block would resolve
-no names at all, which is precisely the capture of the crash somebody was trying to record.
-
----
-
-## 6. `TOPO` — frame graph structure
-
-Present at capture level `STRUCTURE` and above.
-
-| Field | Type |
-|---|---|
-| `id` | uintVar — what a frame refers to |
-| `name` | symbol index |
-| `scope_count` | uintVar |
-| **per scope** | `name` (symbol index), `parent` (optional index) |
-| `pass_count` | uintVar |
-| **per pass** | see §6.1 |
-| `resource_count` | uintVar |
-| **per resource** | see §6.2 |
-
-A scope's parent always appears at a lower index than the scope itself, so a reader resolves the
-chain in one forward pass.
-
-### 6.1 Pass
-
-| Field | Type |
-|---|---|
-| `id` | uintVar |
-| `name` | symbol index |
-| `scope` | optional index |
-| `flags` | u8 — bit 0 `CULLED`, bit 1 `HAS_SIDE_EFFECTS` |
-| `ref_count` | uintVar |
-| `reads` | uintVar count, then that many resource **node** ids |
-| `writes` | same |
-| `creates` | same |
-
-### 6.2 Resource
-
-One entry per resource **node** — that is, per version. A pass records the node it touched rather
-than the underlying resource, so a registry-keyed model would leave every reference past version 0
-dangling.
-
-| Field | Type |
-|---|---|
-| `id` | uintVar |
-| `name` | symbol index |
-| `version` | uintVar |
-| `flags` | u8 — bit 2 `TRANSIENT`, bit 3 `IMPORTED` |
-| `producer` | optional index — the pass that produced this version |
-| `kind` | u8 — 0 none, 1 buffer, 2 texture |
-| `usage` | uintVar — `GPUBufferUsage` / `GPUTextureUsage` bitmask |
-| `byte_size` | uintVar — declared bytes, §6.3 |
-| **if buffer** | `size` (uintVar) |
-| **if texture** | `width`, `height`, `depth`, `mip_level_count`, `sample_count` (uintVar each), `format`, `dimension` (symbol indices) |
-
-### 6.3 `byte_size` is declared, and is computed by the writer
-
-Declared, not allocated: a pooled allocator may serve a larger block, and an aliasing one may serve
-the same block to two resources whose lifetimes do not overlap.
-
-For a texture it covers the whole mip chain at the given sample count. **The writer computes it**
-rather than leaving a reader to, because working it out needs the format's block dimensions — so a
-reader never has to carry a copy of that table, and a format the reader has never heard of still
-reports a size. A writer that cannot determine a size **must** write 0.
-
----
-
-## 7. `FRAM` — one frame
-
-| Field | Type |
-|---|---|
-| `frame_index` | uintVar — the renderer's own counter, not a position in the file |
-| `cpu_begin_ms` | f64 — `performance.now()` when encoding began |
-| `cpu_submit_ms` | f64 — `performance.now()` at submit |
-| `gpu_epoch_ns` | u64 — the earliest GPU timestamp in this frame |
-| `dropped_pass_count` | uintVar — passes that went untimed, §7.2 |
-| `span_count` | uintVar |
-| **per span** | §7.1 |
-| `topology_id` | optional index — **appended last**, absent in a format-1 file |
-
-### 7.1 Span
-
-| Field | Type |
-|---|---|
-| `label` | symbol index |
-| `kind` | u8 — 0 compute, 1 render |
-| `query_set_id` | u8 — §7.3 |
-| `t_begin_ns` | u32 — nanoseconds from `gpu_epoch_ns` |
-| `duration_ns` | uintVar |
-| `graph_pass_id` | optional index — the frame graph pass that was executing when this pass opened |
-| `has_work` | u8 — 1 if a workload block follows |
-| **if `has_work`** | `dispatch_count`, `indirect_dispatch_count`, `workgroups_x/y/z`, `draw_count`, `indirect_draw_count`, `vertex_count`, `index_count`, `instance_count` (uintVar each), `pipeline` (symbol index), `workgroup_size_x/y/z` (uintVar each) |
-
-`t_begin_ns` is a u32 of nanoseconds, holding 4.29 s — three orders of magnitude past any frame, and
-enough to survive a stall rather than wrap. A writer **must** clamp rather than wrap, and **must**
-write a duration of 0 where a device reports an end before its begin.
-
-`has_work` is per span rather than per frame because a frame genuinely mixes the two: a pass opened
-before the recorder was attached has no workload record, and a per-frame flag would have to lie
-about one of them.
-
-A `workgroup_size` of `[0, 0, 0]` means **unknown** — typically an override-expression size — and is
-not the same as zero work. A reader must not compute an invocation count from it.
-
-### 7.2 `dropped_pass_count`
-
-Passes the recorder could not time because the frame had more of them than its query set had slots.
-Carried because an untimed pass reads downstream as a free one. A reader should surface a non-zero
-value rather than presenting the frame as complete.
-
-### 7.3 `query_set_id`
-
-Which of the frame's command contexts produced this span. Timestamps from two different
-`GPUQuerySet`s are not specified to share a clock domain, and a frame ordinarily spans several.
-Carried so that an anomaly following a query-set boundary is visible rather than unfalsifiable.
-
-### 7.4 The two clocks are not one clock
-
-`cpu_*` come from `performance.now()`; `gpu_epoch_ns` and the spans come from the device. WebGPU
-exposes no calibration between them, and this format carries none. Anything that places the two on
-one axis is anchoring, not synchronising, and should say so.
-
----
-
-## 8. `DIRE` — directory
-
-| Field | Type |
-|---|---|
-| `record_count` | uintVar |
-| **per record** | `type` (u32), `offset` (u64), `byte_length` (u32) |
-
-Written last, and does not index itself.
-
-**A reader must not require it, and must not prefer it to the records.** It exists so that a future
-reader can seek instead of scan. A capture that never reached `stop()` has none, and is not thereby
-a lesser capture.
-
----
-
-## 9. Conformance summary
-
-A conforming **reader**:
-
-- refuses a file whose magic does not match or whose `min_reader_version` exceeds its own;
-- reads by scanning records, and does not require a directory or the `CLOSED` flag;
-- validates sync, length and checksum together before accepting a record;
-- resynchronises past damage and reports it, rather than stopping;
-- skips unrecognised record types by length and reports that it did;
-- treats `[0, 0, 0]` workgroup sizes and absent workload blocks as *unknown*, never as zero.
-
-A conforming **writer**:
-
-- emits `META` first and `DIRE` last, and patches only `flags` and the directory fields;
-- emits a `SYMS` block before any record referencing its strings;
-- never gathers symbols into a single trailing block;
-- clamps rather than wraps out-of-range span times, and writes 0 for an unknown size;
-- records what the device reported, without correcting for timestamp quantization.
-
----
-
-*Company Named Limited (c) 2026. The format is documented for interoperability; the engine that
-writes it is proprietary and source-available under its own licence.*

package/src/shade/renderer/NOTES.md

@@ -1,78 +0,0 @@
-the renderer is optimized for large number of instances, and for using PBR shader (`StandardMaterial`)
-
-## Normalized Vertex Layout
-
-* Geometries that are used with StandardShader are expected to conform to a specific Vertex layout.
-* Tools are to be provided to deal with relevant conversion.
-    * Conversion may be done automatically with logged messaged about such, to make the user aware of performance
-      penalty
-* Where possible without sacrificing rendering performance - support non-normalized layouts.
-
-## GPU-resident renderer architecture
-
-* All geometry data (vertex+index) is written into a huge buffer and sits in GPU memory
-* All meshes are represented by a small descriptor that resides on GPU
-* ⚠️*[IMPOSSIBLE]* All draw is indirect draw, indirect draw batches are prepared in a compute shader
-  * __Impossible__ on WebGPU, `drawIndirect` as well as `drawIndexedIndirect` only execute 1 draw command from the buffer and not the whole buffer. As a result you're still stuck issuing commands on CPU
-* Culling is done on GPU
-
-### references:
-* https://vkguide.dev/docs/gpudriven/draw_indirect/
-* SIGGRAPH-2015 2016 GPU-Driven Rendering Pipelines
-* Anti-Aliasing for specular highlights - really good paper https://blog.selfshadow.com/2011/07/22/specular-showdown/
-
-### Unordered References
-Spatio-temporal variance-guided filtering:
-* https://research.nvidia.com/publication/2017-07_spatiotemporal-variance-guided-filtering-real-time-reconstruction-path-traced
-* https://diharaw.github.io/post/adventures_in_hybrid_rendering/
-* https://github.com/diharaw/hybrid-rendering
-* https://github.com/gkjohnson/three-gpu-pathtracer/issues/292
-
-### IDEA v2:
-
----
-
-### Deferred shading
-
- - make use of Visibility Buffer to remove material cost of overdraw and better support GPU-resident rendering (see "The Visibility Buffer: A Cache-Friendly Approach to Deferred Shading", 2013 JCGT)
-   - visibility buffer structure: DEPTH, CLUSTER_ID, TRIANGLE_ID (?) 
-
-#### Geometry Cluster
- - collection of indices (index buffer)
- - references vertex buffer (a geometry) by index
- - A cluster instance also references Mesh that it was produced from
- 
-**problem**: Vertex shader doesn't allow `STORAGE` type buffers, which can have runt-time defined array length, this means that vertex shader can only accept fixed-sided data. This makes decoding of clusters inside vertex shader impossible, as we don't know ahead of time how many clusters we might have. 
-
-#### Draw algorithm
-
-1. Cull instances, takes list of instances as input, culls against various constraints, produces another, smaller list
-2. Prepare instances for render by breaking them up into fixed chunks of triangles (64/128), to do this:
-   1. prepare buffer with clusters
-
-### Textures
-
- - virtual textures?
- - compressed textures, compression support in-engine
- - AI texture upscaling, enlarge texture by generating in-between data using a neural network
- - Toksvig mapping: https://blog.selfshadow.com/2011/07/22/specular-showdown/
-
-
-### Variable Rate shading
- - Poposal in WebGPU, not in actual standard yet as of 19/05/2024
- - VRS is no good for deferred :(
- - Adaptive Shading possible
-   - "Adaptive Undersampling With DACS" https://graphics.geometrian.com/research/dacs.html
-   - maybe use a similar technique to post-process by creating N number of render targets of smaller resolution and combining them in the final pass (ala checked-board pattern)
-
-### Compute swizzling for better cache usage
- - https://github.com/LouisBavoil/ThreadGroupIDSwizzling/blob/master/ThreadGroupTilingX.hlsl
- - https://developer.nvidia.com/blog/optimizing-compute-shaders-for-l2-locality-using-thread-group-id-swizzling/
-
-
-## Shadow terminator
-* "HACKING THE SHADOW TERMINATOR" by Johannes Hanika ( https://jo.dreggn.org/home/2021_terminator.pdf )
-
-## VRS links
-
-* https://github.com/GameTechDev/VRS-DoF

package/src/shade/renderer/PLAN.md

@@ -1,8 +0,0 @@
-* Roll back to env-map sampling until GI is ready
-* Implement VRS for shadows
-    * see "The Rendering of The Callisto Protocol" by Jorge Jimenez, SIGGRAPH 2023
-    * see AMD VRS
-      sample: https://github.com/GPUOpen-LibrariesAndSDKs/FidelityFX-SDK/blob/main/sdk/include/FidelityFX/gpu/vrs/ffx_variable_shading.h
-* Clustered lighting
-* Alpha-tested materials ( consider using VT for alpha(?) and as a substitute for bindless in general )
-* TAA at grazing angles messes up textures, need to UNDO jitter during texture sampling

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

@@ -1,145 +0,0 @@
-# Unified Rest-Anchored Delta Animation Blending
-
-**Status:** Approved & Implemented (Zero Runtime Switches / Enums)
-
-## 1. Core Insight: Why Bone Masks, Override Layers, and Runtime Blend Enums Are Not Needed
-
-In traditional engines where animations are dense full-skeleton arrays, combining a lower-body
-animation with an upper-body or additive animation requires runtime **bone masks**, an explicit
-**override layer mode**, and a runtime **additive vs. absolute clip switch**.
-
-`meep-engine` needs none of these:
-1. **`ShadeAnimationClip` is already sparse per-node and per-axis.** A clip's `channels` array only
-   contains entries for the specific entities (joints) and axes it keys. An upper-body clip with
-   only upper-body channels leaves every lower-body joint untouched. Any per-bone feathering (e.g.
-   `Spine_01` moving 30% as much as `Spine_03`) is naturally authored into the keyframe curves.
-2. **Every clip in the runtime is evaluated as a weighted delta from the target joint's Rest Pose
-   ($V_{\text{rest}}$).**
-   Instead of accumulating raw $w_i \cdot V_i(t)$ into a zero-based slot (which collapses
-   translation and scale toward zero whenever $\sum w_i < 1$, and ignores partial weights on single
-   rotation clips), the apply pass accumulates weighted **deltas from rest**
-   $w_i \cdot (V_i(t) - V_{\text{rest}})$ and the resolve pass adds the accumulated delta back onto
-   $V_{\text{rest}}$:
-   $$V_{\text{final}} = V_{\text{rest}} + \sum_i w_i \cdot \bigl(V_i(t) - V_{\text{rest}}\bigr)$$
-   (with $R_{\text{final}} = \text{normalize}(R_{\text{rest}} + \sum_i w_i \cdot (R_i(t) - R_{\text{rest}}))$ for rotation).
-
----
-
-## 2. Adversarial Pass on the Zero-Runtime-Switch Design
-
-### 2.1. Why Naive "Import-Only Zero-Centered Deltas" Fail on a Zero-Based Accumulator
-Suppose we kept the old zero-based accumulator ($V_{\text{final}} = \sum_i w_i V_i(t)$) and tried to
-bake additive clips at import time as raw zero-centered deltas $\Delta V(t) = V(t) - V_{\text{ref}}$:
-- **Failure 1 (Unkeyed Base Channels / `clip.optimize`):** `load_gltf` calls `clip.optimize(rest)`,
-  stripping un-animated channels. In `Michelle.glb`, `SambaDancing` only keys `Translation` on 1 of
-  65 bones (`Hips`) and `Rotation` on 52 of 65 bones. If an additive clip keys a bone or axis that
-   the base clip does *not* key, the zero-based accumulator receives only $0 + w_{\text{add}} \Delta T$,
-  **wiping out the bone's rest translation and scale to zero**.
-- **Failure 2 (Rotation Collapse on Unkeyed Base Bones):** On a bone whose rotation is not keyed by
-  the active base clip, a zero-centered quaternion difference $\Delta R = R(t) - R_{\text{ref}}$ has
-  $w \approx 0$ for small angles. Normalizing $0 + w_{\text{add}} \Delta R$ without $R_{\text{rest}}$
-  normalizes a pure-imaginary chordal vector, **snapping the bone by $90^\circ$**.
-- **Failure 3 (Single Partial-Weight Clip):** On a zero-based accumulator, a single clip fading in
-  with weight $w \in (0, 1)$ scales translation and scale toward zero ($w \cdot T$, $w \cdot S$)
-  while leaving rotation at 100% full strength ($\text{normalize}(w \cdot R) = R$), then snaps at
-  $w = 0$.
-
-### 2.2. How Unified Rest-Anchored Delta Accumulation Solves Every Case Without Switches
-Under $V_{\text{final}} = V_{\text{rest}} + \sum_i w_i \cdot (V_i(t) - V_{\text{rest}})$:
-1. **Single clip at $w = 1$:**
-   $$V_{\text{rest}} + 1 \cdot (V_1 - V_{\text{rest}}) = V_1$$
-2. **Silent clip at $w = 0$ (fixes D37/E14 at the root for T, R, and S):**
-   $$V_{\text{rest}} + 0 \cdot (V_1 - V_{\text{rest}}) = V_{\text{rest}}$$
-   A bound clip at weight zero never clobbers non-zero rest translation or scale.
-3. **Single partial-body clip fading $w: 0 \to 1$:**
-   $$V_{\text{rest}} + w \cdot (V_1 - V_{\text{rest}}) = (1 - w) V_{\text{rest}} + w V_1$$
-   Smoothly interpolates (lerp for T/S, nlerp for R) from the joint's rest pose to $V_1$.
-4. **Two full-body clips crossfading ($w_1 + w_2 = 1$):**
-   $$V_{\text{rest}} + w_1(V_1 - V_{\text{rest}}) + w_2(V_2 - V_{\text{rest}}) = w_1 V_1 + w_2 V_2$$
-   Even if `clip.optimize` stripped a constant-at-rest channel from clip 1, clip 1's omitted delta
-   is identically $0$, so clip 2 still crossfades smoothly against $V_{\text{rest}}$!
-5. **Base clip ($w_{\text{base}} = 1$, or crossfading base clips summing to $1$) + Additive /
-   Upper-Body clip ($w_{\text{add}} = w$):**
-   $$V_{\text{rest}} + 1 \cdot (V_{\text{base}} - V_{\text{rest}}) + w \cdot (V_{\text{add}} - V_{\text{rest}}) = V_{\text{base}} + w \cdot \Delta V_{\text{add}}$$
-   And on any bone/axis that $V_{\text{base}}$ does *not* key, it automatically evaluates to
-   $V_{\text{rest}} + w \cdot \Delta V_{\text{add}}$.
-
-### 2.3. Adversarial Check: Why Quaternion Hemisphere Alignment Must Happen at Import/Build Time, Not Per-Frame in the Apply Shader
-Suppose a base clip spins a joint past $180^\circ$ so $\text{dot}(R_{\text{base}}(t), R_{\text{rest}})$
-crosses $0$ mid-clip, while an additive clip contributes $w_{\text{add}} \Delta R_{\text{add}}$.
-If the apply shader flipped $R_{\text{base}}(t) \to -R_{\text{base}}(t)$ dynamically when
-$\text{dot}(R_{\text{base}}(t), R_{\text{rest}}) < 0$, then at the crossing frame the sum would flip
-from $+R_{\text{base}} + w_{\text{add}} \Delta R_{\text{add}}$ to
-$-R_{\text{base}} + w_{\text{add}} \Delta R_{\text{add}} = -(R_{\text{base}} - w_{\text{add}} \Delta R_{\text{add}})$,
-inverting the direction of the additive offset mid-animation!
-By keeping sign canonicalization strictly at clip import/creation time (`quat3_canonicalize_sign_run`
-anchored to $R_{\text{rest}}$ at keyframe 0 and continuous across consecutive keyframes), curves
-remain $C^1$-continuous everywhere and the apply shader has zero sign-flip branches.
-
----
-
-## 3. Architecture
-
-### 3.1. Accumulator Layout ([`POSE_ACCUMULATOR_LAYOUT.js`](./POSE_ACCUMULATOR_LAYOUT.js))
-
-Expand each per-row slot in `pose_accumulator` from 16 `u32`s (64 bytes) to 32 `u32`s (128 bytes,
-preserving power-of-two shift indexing) so rest translation and rest scale ride alongside rest
-rotation:
-
-```text
-Word Offset   Field                       Description
-──────────────────────────────────────────────────────────────────────────────────────────
-[0..3]        translation.xyz             Σ w_i * (T_i - rest_T)
-[3..7]        rotation.xyzw               Σ w_i * (R_i - rest_R)
-[7..10]       scale.xyz                   Σ w_i * (S_i - rest_S)
-[10]          dirty_mask                  Bitmask of touched channels (TX, TY, TZ, R, SX, SY, SZ)
-[11..15]      rest_rotation.xyzw          Target joint's rest rotation
-[15..18]      rest_translation.xyz        Target joint's rest translation
-[18..21]      rest_scale.xyz              Target joint's rest scale
-[21..32]      padding                     Power-of-two slot alignment (32 u32s = 128 bytes)
-```
-
-### 3.2. Zero-Overhead Binding Rest Value ([`ANIMATION_TRACK_BINDING_STRUCT.js`](./ANIMATION_TRACK_BINDING_STRUCT.js))
-
-Each row in `animation_bindings` targets a single `property` (`Translation`, `Rotation`, or `Scale`)
-and already carries a `vec4f` field (`rest_rotation`). By populating that `vec4f` with the target
-entity's rest value for its bound `property`—`[tx, ty, tz, 0]` for Translation, `[sx, sy, sz, 0]`
-for Scale, and `[rx, ry, rz, rw]` for Rotation, both at binding completion and in
-`GPUAnimationManager.#unmute`—the binding struct stays 32 bytes with zero extra memory overhead.
-
-### 3.3. GPU Apply & Resolve ([`chunk_pose_accumulator.js`](./chunk_pose_accumulator.js), [`shader_animation_pose_resolve.js`](./shader_animation_pose_resolve.js))
-
-- **Apply (`chunk_pose_accumulator`):**
-  - `pose_accumulator_add_translation(row, value, mask, weight, rest)`: for each masked axis $a$,
-    atomic-adds `value[a] - rest[a] * weight` into `POSE_OFFSET_TRANSLATION + a` and stores
-    `rest[a]` into `POSE_OFFSET_REST_TRANSLATION + a`.
-  - `pose_accumulator_add_rotation(row, value, mask, weight, rest)`: substitutes `weight` for a
-    missing $w$ curve (`let w = select(weight, value.w, (mask & 0x8u) != 0u)`), atomic-adds
-    `(value.xyz, w) - rest * weight` into `POSE_OFFSET_ROTATION`, and stores `rest` into
-    `POSE_OFFSET_REST_ROTATION`.
-  - `pose_accumulator_add_scale(row, value, mask, weight, rest)`: for each masked axis $a$,
-    atomic-adds `value[a] - rest[a] * weight` into `POSE_OFFSET_SCALE + a` and stores `rest[a]`
-    into `POSE_OFFSET_REST_SCALE + a`.
-- **Resolve (`shader_animation_pose_resolve`):**
-  - Translation (per dirty axis $a$): `t[a] = rest_t[a] + delta_t[a]`, then zeroes `delta_t[a]`.
-  - Rotation (when `POSE_DIRTY_R` set): `r = rest_r + delta_r`, zeroes `delta_r`, and writes
-    `normalize(r)` when `length(r) > 0.0`, else `rest_r`.
-  - Scale (per dirty axis $a$): `s[a] = rest_s[a] + delta_s[a]`, then zeroes `delta_s[a]`.
-
-### 3.4. CPU Twin Lockstep ([`pose_evaluate_local.js`](./pose/pose_evaluate_local.js))
-
-`pose_evaluate_local(result, target, rest, playbacks)` accumulates `(curve.evaluate(time) - rest_comp) * weight`
-into `SUM_TRANSLATION`, `SUM_ROTATION`, and `SUM_SCALE`, and resolves `rest + SUM` (normalizing
-rotation with fallback to `rest.rotation` on zero length), matching the GPU bit-for-bit.
-
-### 3.5. Import / Authoring Stage Additive Rebasing ([`ShadeAnimationClip.js`](./ShadeAnimationClip.js))
-
-`ShadeAnimationClip.from_additive(source_clip, { reference_clip, reference_time, rest_of, name })`
-rebases a clip authored relative to `reference_clip` at `reference_time` onto each target's rest
-pose `rest_of(target)`:
-- $T_{\text{out}}(t) = T_{\text{rest}} + (T_{\text{src}}(t) - T_{\text{ref}})$
-- $S_{\text{out}}(t) = S_{\text{rest}} + (S_{\text{src}}(t) - S_{\text{ref}})$
-- $R_{\text{out}}(t) = (R_{\text{src}}(t) \otimes R_{\text{ref}}^{-1}) \otimes R_{\text{rest}}$,
-  sign-canonicalized against $R_{\text{rest}}$
-- Automatically drops any axis curve or rotation channel whose delta from $V_{\text{ref}}$ is zero
-  across all keyframes (within `1e-5`).