three-vat 1.0.0 → 2.0.0

package/README.md

@@ -1,23 +1,14 @@
 # three-vat
 
-[![CI](https://github.com/MikeFernandez-Pro/three-vat/actions/workflows/ci.yml/badge.svg)](https://github.com/MikeFernandez-Pro/three-vat/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/three-vat.svg)](https://www.npmjs.com/package/three-vat)
-[![license: MIT](https://img.shields.io/npm/l/three-vat.svg)](./LICENSE)
-
-Bake a glTF `AnimationClip` into GPU textures and animate **hundreds or thousands of instanced characters with zero per-frame CPU** — one draw call, no `SkinnedMesh` per character.
+![The demo's count dragged from a single robot up to 340, the crowd filling the screen while the draw-call counter holds still at three — one per material](https://raw.githubusercontent.com/MikeFernandez-Pro/three-vat/main/docs/media/hero.gif)
 
-VAT (Vertex Animation Texture) is battle-tested in Unity/Unreal but has been a gap on the three.js side: only scattered demos, no maintained package, nothing in drei. `three-vat` bakes the VAT **at runtime, directly from the glTF** — so any Mixamo/Sketchfab asset works with zero pipeline, and there is exactly one way to produce a VAT.
+**[Open the live demo →](https://mikefernandez-pro.github.io/three-vat/)** and drag the count from 1 robot to 340. The draw calls do not move.
 
-## Live demos
+Bake a glTF `AnimationClip` into GPU textures and animate **hundreds or thousands of instanced characters with zero per-frame CPU** — one draw call per material, no `SkinnedMesh` per character. Works on `WebGLRenderer` and `WebGPURenderer`, from the same baked VAT.
 
-- **[WebGL crowd](https://mikefernandez-pro.github.io/three-vat/webgl_crowd.html)** — 340 robots, mixed clips, one mesh, through the GLSL decode path.
-- **[WebGPU crowd](https://mikefernandez-pro.github.io/three-vat/webgpu_crowd.html)** — the same crowd through the TSL decode path, on `WebGPURenderer`.
-
-Both pages carry a live draw-call counter and a view of the baked textures, with
-cursors on the frame rows each instance is sampling. Source in
-[`examples/`](./examples); they deploy from `main` on every push.
-
-> **Status: `1.0.0`** — the npm badge above reads the registry, so it is the one to trust for what is actually published. The library is **three surfaces**, and all three work: the core baker (`three-vat`), the WebGL/GLSL decode (`three-vat/webgl`), and the WebGPU/TSL decode (`three-vat/tsl`). The two decode paths read one shared instance-playback contract and export the same `createVATMesh`, so nothing documented here is true on one renderer and false on the other. Where the renderers genuinely differ — shadow materials, the `time` clock's type, and what the TSL node builder needs to re-apply instancing — it is called out where it arises. The baker and the WebGL decode are covered by tests; the TSL path is tested structurally, because CI has no GPU, and that the two paths decode *pixel-identically* is a manual release gate ([`pnpm parity`](./docs/releasing.md)). See [`docs/DESIGN.md`](./docs/DESIGN.md) and [`docs/adr/`](./docs/adr) for the full rationale, [What 1.0 does not do](#what-10-does-not-do) for the deferred work, and [`CHANGELOG.md`](./CHANGELOG.md) for release notes.
+[![CI](https://github.com/MikeFernandez-Pro/three-vat/actions/workflows/ci.yml/badge.svg)](https://github.com/MikeFernandez-Pro/three-vat/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/three-vat.svg)](https://www.npmjs.com/package/three-vat)
+[![license: MIT](https://img.shields.io/npm/l/three-vat.svg)](./LICENSE)
 
 ## Install
 
@@ -25,346 +16,211 @@ cursors on the frame rows each instance is sampling. Source in
 npm install three-vat three
 ```
 
-`three` (>= 0.185) is a peer dependency.
+`three` (>= 0.186) is a peer dependency.
 
-## Bake
+## One crowd, start to finish
 
 ```ts
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
 import { bakeVAT } from 'three-vat'
+import { createVATMesh, getMaxTextureSize } from 'three-vat/webgl'
+// WebGPURenderer? `from 'three-vat/tsl'` — that import is the only line that changes.
+
+// The parts you already know — renderer, scene, camera, lights, clock — made
+// however you usually make them. Nothing on this line is VAT-specific.
+const { renderer, scene, camera, clock } = setUpYourScene()
+
+const gltf = await new GLTFLoader().loadAsync('/robot.glb')
+
+// Bake once, at load. Pass the subtree root — `gltf.scene` — and not a mesh
+// inside it: the bake unit is the whole subtree, merged and recorded in root
+// space. This same call takes
+//   - a skinned character (Mixamo, Sketchfab, `Soldier.glb`)
+//   - a morph-target mesh
+//   - a hierarchy of rigid, node-animated parts (three's `RobotExpressive`)
+//   - any mix of those in one subtree
+// because a VAT records where a vertex ended up and never how it got there.
+// Nothing to classify, and no variant of this call to go looking for.
+const vat = bakeVAT(gltf.scene, gltf.animations, {
+  fps: 30,
+  maxTextureSize: getMaxTextureSize(renderer), // this GPU's real ceiling
+})
+
+// One entry per character: which clip it plays, when it started, its rate.
+// Everything but `startTime` is optional — a clip baked from a configured
+// `AnimationAction` carries its own loop, repetition count, end behaviour and
+// speed, and an instance overrides only what it wants to differ.
+const instances = Array.from({ length: 500 }, (_, i) => ({
+  clip: vat.clips[i % vat.clips.length],
+  startTime: -Math.random() * 2, // began a moment ago, so the crowd is not in lockstep
+  speed: 0.9 + Math.random() * 0.2,
+}))
+
+// The crowd: one InstancedMesh, its geometry and materials already decoding the
+// VAT, plus the clock that drives every instance.
+const { mesh, time } = createVATMesh(vat, instances)
+mesh.castShadow = mesh.receiveShadow = true
+scene.add(mesh)
+
+// Where each character stands is yours — the library never guesses a layout.
+for (let i = 0; i < instances.length; i++) mesh.setMatrixAt(i, matrixFor(i))
+mesh.instanceMatrix.needsUpdate = true
+mesh.computeBoundingSphere() // or frustumCulled = false, if matrices move every frame
 
-// gltf loaded via GLTFLoader — pass the subtree root, not a mesh.
-const clips = gltf.animations.filter((c) => c.name !== 'TPose')
-const vat = bakeVAT(gltf.scene, clips, { fps: 30 })
-// vat: { positionTexture, normalTexture, geometry, materials, clips, bounds, ... }
+renderer.setAnimationLoop(() => {
+  time.value = clock.getElapsedTime() // the whole per-frame cost of the animation
+  renderer.render(scene, camera)
+})
 ```
 
-The bake unit is the **whole subtree**, merged into one vertex set and recorded in root space ([ADR-0008](./docs/adr/0008-a-vat-bakes-a-posed-subtree-not-a-skinnedmesh.md)). A VAT only records *where a vertex ended up*, never how it got there, so one call handles a single `SkinnedMesh`, a morph-target mesh, a hierarchy of rigid node-animated parts (three.js `RobotExpressive`), or any mix — with no classification by the caller.
+Two things worth knowing the first time:
 
-Two consequences worth knowing up front:
+- **Render `vat.geometry`, not your source mesh.** The merged vertex ordering is
+  the baker's, and the textures are indexed by it. `createVATMesh` does this for
+  you; by hand, clone that geometry and no other.
+- **Materials are never merged.** A 500-robot crowd with 3 materials is 3 draw
+  calls — not 1, and not 500. VAT collapses instance count, not material count.
 
-- **Render `vat.geometry`, not your source mesh.** The merged vertex ordering is the baker's, and the textures are indexed by it.
-- **Materials are never merged.** `vat.materials` lines up with `vat.geometry.groups`, giving one draw call per material. VAT collapses *instance* count, not *material* count — a 500-robot crowd with 3 materials is 3 draw calls, not 1 and not 500.
+<details>
+<summary><b>Does it work with my model?</b></summary>
 
-The VAT is a flat `vertexCount` × `totalFrames` texture pair, so **both** axes are bounded by the GPU's max texture dimension. The baker is renderer-agnostic and defaults to a conservative `16384`; pass the real limit whenever you have a renderer, or a bake that allocates on desktop can fail on mobile (commonly 4096–8192):
+If `GLTFLoader` loads it and it has an `AnimationClip`, yes — the four shapes
+listed in the snippet above, and any mix of them, through that one call.
 
-```ts
-import { getMaxTextureSize } from 'three-vat/webgl' // or 'three-vat/tsl'
+The bake unit is the **subtree**, not the mesh
+([ADR-0008](./docs/adr/0008-a-vat-bakes-a-posed-subtree-not-a-skinnedmesh.md)),
+which is where the one real mistake lives: pass `gltf.scene`, or the node you
+want animated, never a `SkinnedMesh` you fished out of it.
 
-const vat = bakeVAT(gltf.scene, clips, {
-  fps: 30,
-  maxTextureSize: getMaxTextureSize(renderer),
-})
-```
+Positions bake exactly under any rig; normals match what three's own skinning
+shader draws, which is approximate under non-uniform bone scale — `bakeVAT`
+warns once and names the bone. A rest-pose track such as Mixamo's `TPose` bakes
+to a frozen band and reports it as a near-zero `clip.maxDelta`: filter those out
+of `gltf.animations` rather than spending texture rows on them.
 
-## Render a crowd
+</details>
 
-One call on either renderer. The import line is the only difference:
+<details>
+<summary><b>Per-clip playback defaults</b></summary>
 
-```ts
-import { createVATMesh } from 'three-vat/webgl' // WebGLRenderer
-// import { createVATMesh } from 'three-vat/tsl'  ← WebGPURenderer: the only line that changes
-```
+`bakeVAT` takes an `AnimationClip` **or** an `AnimationAction`, in the same
+array. Configure the action the way three already taught you, and every instance
+of that clip inherits it — and overrides any field it names.
 
 ```ts
-// instances: { clip, timeOffset, speed }[] — one per character.
-const { mesh, time } = createVATMesh(vat, instances)
-mesh.castShadow = mesh.receiveShadow = true
-scene.add(mesh)
+const death = mixer.clipAction(deathClip)
+death.loop = THREE.LoopOnce
 
-// place the crowd
-for (let i = 0; i < instances.length; i++) mesh.setMatrixAt(i, matrix)
-mesh.instanceMatrix.needsUpdate = true
-mesh.computeBoundingSphere() // or frustumCulled = false, if matrices change every frame
-
-// per frame:
-time.value = clock.elapsedTime
+const vat = bakeVAT(gltf.scene, [walkClip, death, idleClip])
 ```
 
-The call clones the baked geometry, writes the per-instance playback attributes, and prepares one material per material group — so a crowd mixes clips, phases and playback rates on either renderer, from the same `instances` array ([ADR-0009](./docs/adr/0009-both-decode-paths-read-one-instance-playback-contract.md)).
+`loop`, `repetitions` and `timeScale` are read; `time` and `paused` are ignored,
+because a VAT has no playhead of its own to seed; a non-unit `weight` or an
+additive `blendMode` throws, because one baked band cannot be several actions
+blended at once.
 
-Shadows are the one place the renderers genuinely differ, and the call absorbs it: on WebGL it attaches the patched depth and distance materials the shadow passes need (miss them by hand and the crowd's body animates while its shadow stays in the bind pose); on TSL it attaches nothing, because `positionNode` already feeds the depth pass. Either way you write `castShadow` and nothing else.
+**Both inputs clamp, where three rewinds.** `clampWhenFinished` defaults to
+`false` in three, which means an untouched action says nothing about the end
+either — and a crowd's answer to nothing is to hold the last frame, because a
+corpse standing back up is the worse default. So the end mode is not read off
+the action; an instance asks for three's rewind with `endMode: EndMode.Rewind`,
+which is the finer grain anyway.
 
-Instance matrices and `castShadow`/`receiveShadow` stay yours: only you know where the crowd stands and whether the scene has shadows at all.
+[Declaring the defaults at the bake](./docs/usage.md#declaring-the-defaults-at-the-bake).
 
-The returned `time` is the same `{ value }` clock on both paths. The one other place the signatures differ is supplying your own: `options.time` is a `THREE.IUniform` on the WebGL path and a TSL `uniform(0)` on the TSL path, because that is what each renderer's material can read. Let the call make its own — as above — and even that line is identical.
+</details>
 
 <details>
-<summary>By hand on WebGL, when you are not rendering onto a plain <code>InstancedMesh</code></summary>
-
-```ts
-import { addVATInstanceAttributes } from 'three-vat'
-import { createVATUniforms, createVATDepthMaterial, patchVATMaterial } from 'three-vat/webgl'
-
-const uniforms = createVATUniforms()
-
-// vat.geometry already carries the all-frames bounding box/sphere, so instances
-// never cull mid-animation.
-const geometry = vat.geometry.clone()
-// Instance playback — `{ clip, timeOffset, speed }` per instance — is a core
-// contract both decode paths read, not a WebGL-only concept.
-addVATInstanceAttributes(geometry, instances)
-
-// One patched material per source material, sharing one clock.
-const materials = vat.materials.map((source) => {
-  const material = source.clone()
-  patchVATMaterial(material, vat, uniforms)
-  return material
-})
+<summary><b>Upgrading from 1.x</b></summary>
 
-const mesh = new THREE.InstancedMesh(geometry, materials, instances.length)
-// Correct instanced shadows: depth for directional/spot lights, distance for point lights.
-mesh.customDepthMaterial = createVATDepthMaterial(vat, uniforms)
-mesh.customDistanceMaterial = patchVATMaterial(new THREE.MeshDistanceMaterial(), vat, uniforms)
+The breaks that reach a 1.x caller, no shims — the package had no users on the
+1.x playback contract, so 2.0 spells it one way rather than two. The full list
+is [the CHANGELOG's 2.0.0 entry](./CHANGELOG.md).
 
-// per frame:
-uniforms.uVatTime.value = clock.elapsedTime
+```ts
+{ clip, timeOffset: 1.4, speed: 1 }  // 1.x — every field required
+{ clip, startTime: -1.4 }            // 2.0 — desync is a start time in the past
 ```
 
+`timeOffset` is gone (`startTime: -timeOffset / speed`), and with it
+`aTimeOffset`. The pack is three `vec4`s — clip, playback, fade — in a
+**playback texture** keyed by the instance's logical index, not instanced
+attributes, which are indexed by the *drawn* slot:
+`addInstancedVATAttributes` is removed, `createVATPlaybackTexture(instances)`
+replaces `addVATInstanceAttributes`, and `setVATInstance(playback, id, instance)`
+takes that texture — `createVATMesh` returns it as `playback` — rather than a
+geometry. A VAT texture's `image.data` is now opaque. Node 20, where
+1.x said 18, and `three >= 0.186`, where `batchIndirectIndex` is exported;
+browsers are unaffected.
+
+New, and none of it breaking: per-instance loop modes, one-shots,
+`setVATInstance` after the crowd is built, and a crowd on a `BatchedMesh`.
+[By hand, on either path](./docs/usage.md#by-hand-on-either-path).
+
 </details>
 
 <details>
-<summary>By hand on TSL, and the zero-config default</summary>
+<summary><b>Going bigger: texture limits, bake cost, Web Workers</b></summary>
 
-```ts
-import { MeshStandardNodeMaterial } from 'three/webgpu'
-import { addVATInstanceAttributes } from 'three-vat'
-import { vatNodes } from 'three-vat/tsl'
-
-const geometry = vat.geometry.clone()
-addVATInstanceAttributes(geometry, instances)
-
-// The mesh is built first, because the decode is built from it.
-const material = new MeshStandardNodeMaterial()
-const mesh = new THREE.InstancedMesh(geometry, material, instances.length)
-
-// `geometry`: each instance plays its own clip, phase and rate.
-// `instancedMesh`: the decode re-applies this mesh's instancing itself, because
-// three applies the instance matrix to `positionLocal` *before* it reads
-// `positionNode` — so the delta has to be added in the geometry's own space and
-// instanced afterwards. Omit it only for a single, non-instanced mesh.
-const { positionNode, time } = vatNodes(vat, { geometry, instancedMesh: mesh })
-material.positionNode = positionNode
-
-// per frame:
-time.value = clock.elapsedTime
-```
+The VAT is one `vertexCount` × `totalFrames` texture pair, so both axes hit the
+GPU's texture ceiling. Always pass `maxTextureSize: getMaxTextureSize(renderer)`
+as above: the default is a desktop-shaped guess, and mobile is often 4096.
 
-There is deliberately no `normalNode`: the decode writes `normalLocal` from
-inside the vertex stage, exactly as the GLSL path writes `objectNormal`, and
-three transforms and interpolates it from there. A material's `normalNode` is
-built in the *fragment* stage and expected in view space, which is neither where
-nor what a per-vertex, object-space VAT normal is.
+The bake is CPU work done once at load — about 100 ms for the demo's robot, and
+seconds for a 20k-vertex skinned character with many clips. It never touches the
+renderer, so it moves into a Web Worker as-is.
 
-Omit `geometry` and you get the zero-config default instead: every instance plays `clipIndex`, phase-desynced by `desync` seconds hashed from `instanceIndex`, with no attributes to write.
+**[docs/usage.md](./docs/usage.md)** has the measured bake-cost table, the
+worker recipe, the draw-call arithmetic, and the primitives underneath
+`createVATMesh` for when you are not rendering onto a plain `InstancedMesh`.
 
 </details>
 
-## Bake cost, and baking in a Web Worker
-
-A VAT is produced exactly one way — `bakeVAT` at runtime
-([ADR-0010](./docs/adr/0010-drop-the-offline-format-runtime-bake-is-the-library.md)).
-There is no file format to write or load, so the one cost to budget is the bake
-itself, once at load. Measured on `three@0.185.1` (Node, Apple Silicon, mean of
-3 runs after warm-up):
-
-| Asset | Clips | fps | Rows | Bake |
-|---|---|---|---|---|
-| `RobotExpressive` (rigid, 7 214 v) | 3 (the demo) | 30 | 158 | 97 ms |
-| `RobotExpressive` | 5 | 30 | 313 | 178 ms |
-| `RobotExpressive` | 14 (all) | 30 | 585 | 330 ms |
-| `RobotExpressive` | 14 (all) | 60 | 1 168 | 659 ms |
-| `Soldier` (skinned, 7 434 v) | 4 (all) | 30 | 113 | 250 ms |
-| `Soldier` (skinned) | 4 (all) | 60 | 224 | 492 ms |
-
-Cost is linear in `vertices × frames`, and **a skinned vertex costs ~4× per
-frame row what a rigid one does** (2.2 ms/row here vs 0.56) — the four-weight
-bone blend is the hot loop. So budget by rows, and halve `fps` before you cut
-clips. A 20k-vertex skinned character with 6 clips at 30 fps extrapolates to
-~1.8 s on this machine and several seconds on a mid-range phone — enough to
-matter, and the point at which the bake belongs off the main thread.
-
-It can go there as-is: **the baker is pure CPU and never touches the renderer**,
-so it runs in a Web Worker, with the texel buffers transferred back at no copy
-cost. The worker loads the glTF and bakes; the main thread rebuilds the
-textures and the geometry from plain buffers.
+<details>
+<summary><b>What it does not do</b></summary>
 
-```ts
-// bake.worker.ts
-import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
-import { bakeVAT } from 'three-vat'
+No clip crossfade (an instance blends out of a frozen pose, not between two
+clips that are both playing), no LOD, no baking CLI or file
+format, no React/drei binding, glTF input only. Each is a decision rather than a
+gap, and each is written up with its reasoning in
+**[docs/usage.md](./docs/usage.md#what-10-does-not-do)**, alongside the
+trade-offs against `SkinnedMesh` and bone-texture instancing.
 
-self.onmessage = async ({ data: { url, fps, maxTextureSize } }) => {
-  const gltf = await new GLTFLoader().loadAsync(url)
-  const vat = bakeVAT(gltf.scene, gltf.animations, { fps, maxTextureSize })
-
-  const position = vat.positionTexture.image.data as Float32Array
-  const normal = vat.normalTexture.image.data as Float32Array
-  const index = vat.geometry.getIndex()
-
-  self.postMessage(
-    {
-      position,
-      normal,
-      // Every attribute the merge produced — position, normal, and uv/color
-      // when the source had them. Carry each itemSize rather than guessing it.
-      attributes: Object.fromEntries(
-        Object.entries(vat.geometry.attributes).map(([name, a]) => [
-          name,
-          { array: a.array, itemSize: a.itemSize },
-        ]),
-      ),
-      index: index?.array,
-      groups: vat.geometry.groups,
-      clips: vat.clips,
-      bounds: { min: vat.bounds.min.toArray(), max: vat.bounds.max.toArray() },
-      vertexCount: vat.vertexCount,
-      totalFrames: vat.totalFrames,
-    },
-    // Transferred, not copied — the texel buffers are the large part.
-    [position.buffer, normal.buffer],
-  )
-}
-```
+Both decode paths — GLSL on `WebGLRenderer`, TSL on `WebGPURenderer` — read one
+shared instance-playback contract and export the same `createVATMesh`, so
+nothing documented here is true on one renderer and false on the other. That the
+two decode *pixel-identically* is a manual gate before every release
+([docs/releasing.md](./docs/releasing.md)).
 
-```ts
-// main thread
-import * as THREE from 'three'
-import { makeVATTexture } from 'three-vat'
-import { createVATMesh, getMaxTextureSize } from 'three-vat/webgl' // or 'three-vat/tsl'
-import type { VAT } from 'three-vat'
-
-// `renderer` is your WebGLRenderer (or WebGPURenderer), already created — only
-// the main thread can ask the GPU for its limits.
-const worker = new Worker(new URL('./bake.worker.ts', import.meta.url), { type: 'module' })
-
-function bakeInWorker(url: string, fps = 30): Promise<VAT> {
-  return new Promise((resolve) => {
-    worker.onmessage = ({ data: d }) => {
-      const geometry = new THREE.BufferGeometry()
-      for (const [name, { array, itemSize }] of Object.entries(d.attributes)) {
-        geometry.setAttribute(name, new THREE.BufferAttribute(array, itemSize))
-      }
-      if (d.index) geometry.setIndex(new THREE.BufferAttribute(d.index, 1))
-      for (const g of d.groups) geometry.addGroup(g.start, g.count, g.materialIndex)
-
-      const bounds = new THREE.Box3(
-        new THREE.Vector3(...d.bounds.min),
-        new THREE.Vector3(...d.bounds.max),
-      )
-      // The union-of-all-frames volume, or a deformed crowd culls mid-animation.
-      geometry.boundingBox = bounds.clone()
-      geometry.boundingSphere = bounds.getBoundingSphere(new THREE.Sphere())
-
-      resolve({
-        positionTexture: makeVATTexture(d.position, d.vertexCount, d.totalFrames),
-        normalTexture: makeVATTexture(d.normal, d.vertexCount, d.totalFrames),
-        geometry,
-        // One per group, in `materialIndex` order — see the note below.
-        materials: d.groups.map(() => new THREE.MeshStandardMaterial()),
-        clips: d.clips,
-        bounds,
-        vertexCount: d.vertexCount,
-        totalFrames: d.totalFrames,
-        encoding: 'delta',
-      })
-    }
-    worker.postMessage({ url, fps, maxTextureSize: getMaxTextureSize(renderer) })
-  })
-}
-
-const { mesh, time } = createVATMesh(await bakeInWorker('/robot.glb'), instances)
+</details>
+
+<details>
+<summary><b>Development</b></summary>
+
+```bash
+pnpm i
+pnpm run dev    # opens the demo — this and the line above are the whole setup
 ```
 
-Two things do not cross the wire, both by nature rather than by omission:
-
-- **Materials.** A `Material` holds textures and GPU state, so it has to be
-  built on the main thread. The placeholder above is a stand-in: `materials`
-  must have one entry per `geometry.groups[].materialIndex`, or every group past
-  the first renders undefined. For a glTF's real materials, load it a second
-  time on the main thread (the browser serves it from cache) and take
-  `gltf.scene`'s materials in the same order the merge recorded them.
-- **The renderer's `maxTextureSize`**, which only the main thread can ask for —
-  read it there and pass it in, as the snippet does.
-
-A `bakeVATInWorker` helper is deferred, for the reason in
-[What 1.0 does not do](#what-10-does-not-do).
-
-## Trade-offs
-
-- **vs N × `SkinnedMesh`:** N draw calls + per-frame CPU skeletons → VAT is 1 draw call, zero per-frame CPU, 2 texel fetches per vertex. The headline.
-- **vs bone-texture instancing:** smaller textures and supports blending, but more fetches per vertex. VAT also captures morph/non-skeletal deformation for free.
-- **VAT limits:** no runtime IK/blending, discrete frames, memory cost (`verts × frames × 16 B × 2` textures). No clip crossfade — see [What 1.0 does not do](#what-10-does-not-do).
-- **Skinned normals:** positions bake exactly under any rig. Normals reproduce what three's own skinning shader renders — linear-blend skinning transforms a normal by the skin matrix rather than its inverse-transpose, exact for rigid and uniformly-scaled bones, an approximation otherwise. Non-uniform bone scale is where that shows, so `bakeVAT` warns once, naming the bone.
-
-## What 1.0 does not do
-
-Named rather than left to be discovered. None of these is a known defect; each
-is a decision, with the reasoning recorded where it was made.
-
-- **No clip crossfade.** An instance cuts between clips, it does not blend.
-  Crossfade doubles the per-vertex texel fetches (2 → 4) and adds per-instance
-  transition state, which is not worth spending before the single-clip decode is
-  proven on both paths ([ADR-0007](./docs/adr/0007-v1-scope-library-only.md)).
-  The instance-attribute layout reserves room for a second clip index, so it
-  stays a non-breaking addition.
-- **No LOD.** Every instance samples the VAT at full vertex count, whatever its
-  distance.
-- **No `npx vat-bake` CLI, and no file format for it to write.** The offline
-  format was removed in 1.0 and the runtime bake is the only way to produce a
-  VAT ([ADR-0010](./docs/adr/0010-drop-the-offline-format-runtime-bake-is-the-library.md));
-  the design a CLI would build on is kept on record in the superseded
-  [ADR-0003](./docs/adr/0003-offline-format-float16-bin-plus-manifest.md), so
-  reviving it is a decision rather than a fresh design problem.
-- **No React/drei hook or component.** A downstream contribution rather than a
-  library surface, and `createVATMesh` is what makes it thin enough to be one.
-- **No `bakeVATInWorker` helper.** 1.0 ships the [recipe](#bake-cost-and-baking-in-a-web-worker)
-  instead: adding a second, async way to bake while the API stabilizes is the
-  two-entry-point split [ADR-0008](./docs/adr/0008-a-vat-bakes-a-posed-subtree-not-a-skinnedmesh.md)
-  refused, and demand should decide it.
-- **glTF/GLB input only**, and multi-material meshes are rejected rather than
-  split by geometry group — `GLTFLoader` emits one mesh per primitive, so the
-  case is unreachable through the only input surface there is.
-
-## Development
+Three more verbs, and that is the table:
 
 ```bash
-pnpm install
-pnpm fetch:test-assets   # Soldier.glb — too big for git, so the skinned real-asset tests skip without it
-pnpm test                # baker core — pure CPU, no GPU needed
-pnpm test:examples       # the demo's own suite (crowd layout, page/bundle shape)
-pnpm typecheck
-pnpm typecheck:examples
-pnpm build
-pnpm example             # serves the demo pages in examples/ (model bundled)
-pnpm parity              # cross-path pixel-diff gate — needs a GPU and a WebGPU browser
+pnpm test       # every suite: the baker core, the release suite, the demo's own
+pnpm typecheck  # all three tsconfigs: library, release suite, demo
+pnpm build      # the published library (`pnpm run build:watch` to watch)
 ```
 
-`examples/` is a workspace package, so one `pnpm install` at the root covers
-both it and the library. It is a multi-page app: a landing `index.html` plus one
-page per renderer (`webgl_crowd.html`, `webgpu_crowd.html`), each self-contained
-by design
-([ADR-0011](./docs/adr/0011-one-example-per-renderer-duplicated-on-purpose.md)).
-Both the build entries and the landing page's list are globbed from those HTML
-files, so adding a demo is adding a file. `pnpm build:examples` produces the
-static site that `.github/workflows/pages.yml` publishes from `main`; it builds
-with a relative base, so it also runs from any subpath or a `file://` open.
-
-The WebGPU page checks for an adapter before it loads anything else and points
-at the WebGL demo when there is none — `WebGPURenderer` would otherwise fall
-back to its WebGL backend and quietly draw the WebGPU demo through GLSL.
-
-`pnpm parity` is the one check that is not in CI and not optional. It renders
-one bake through both decode paths at the same camera, lights and time and
-compares the frames pixel by pixel — the only thing that can catch a decode
-subtly wrong on one path only, and the only thing that needs a real GPU on both
-backends. It is a **required gate before publishing**, not a test; see
-[docs/releasing.md](./docs/releasing.md) for what it checks and how to read a
-failure.
-
-The suite is green on a fresh clone with no network: the real-asset tests skip
-when their asset is missing. Run `pnpm fetch:test-assets` before touching the
-baker, so a real skinned character is actually being baked — see
-[docs/test-assets.md](./docs/test-assets.md).
+`examples/` is the demo — one page per renderer, self-contained on purpose
+([ADR-0011](./docs/adr/0011-one-example-per-renderer-duplicated-on-purpose.md)),
+deployed from `main` on every push. Release steps are `node` invocations rather
+than table entries, the parity gate among them and required
+([docs/releasing.md](./docs/releasing.md)). The suite is green on a fresh clone
+with no network: real-asset tests skip when their asset is missing, so fetch it
+before touching the baker ([docs/test-assets.md](./docs/test-assets.md)).
+
+</details>
+
+Deeper: [docs/](./docs) · [CHANGELOG.md](./CHANGELOG.md) · [live WebGPU demo](https://mikefernandez-pro.github.io/three-vat/webgpu_crowd.html)
 
 ## License