three-vat 0.3.0 → 1.0.0

package/README.md

@@ -1,5 +1,6 @@
 # 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)
 
@@ -7,7 +8,16 @@ Bake a glTF `AnimationClip` into GPU textures and animate **hundreds or thousand
 
 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.
 
-> **Status: early release — `0.3.0`, published on npm.** The baker core (skinning, morph targets **and** rigid node-animated subtrees) and WebGL decode are covered by tests. The TSL/WebGPU path ships but is verified visually, not yet by automated tests. See [`docs/DESIGN.md`](./docs/DESIGN.md) and [`docs/adr/`](./docs/adr) for the full rationale, and [`CHANGELOG.md`](./CHANGELOG.md) for release notes.
+## Live demos
+
+- **[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.
 
 ## Install
 
@@ -46,17 +56,53 @@ const vat = bakeVAT(gltf.scene, clips, {
 })
 ```
 
-## Render a crowd — WebGL (`WebGLRenderer`)
+## Render a crowd
+
+One call on either renderer. The import line is the only difference:
+
+```ts
+import { createVATMesh } from 'three-vat/webgl' // WebGLRenderer
+// import { createVATMesh } from 'three-vat/tsl'  ← WebGPURenderer: the only line that changes
+```
+
+```ts
+// instances: { clip, timeOffset, speed }[] — one per character.
+const { mesh, time } = createVATMesh(vat, instances)
+mesh.castShadow = mesh.receiveShadow = true
+scene.add(mesh)
+
+// 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
+```
+
+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)).
+
+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.
+
+Instance matrices and `castShadow`/`receiveShadow` stay yours: only you know where the crowd stands and whether the scene has shadows at all.
+
+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>
+<summary>By hand on WebGL, when you are not rendering onto a plain <code>InstancedMesh</code></summary>
 
 ```ts
-import { addInstancedVATAttributes, createVATUniforms, createVATDepthMaterial, patchVATMaterial } from 'three-vat/webgl'
+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()
-addInstancedVATAttributes(geometry, instances) // instances: { clip, timeOffset, speed }[]
+// 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) => {
@@ -66,62 +112,260 @@ const materials = vat.materials.map((source) => {
 })
 
 const mesh = new THREE.InstancedMesh(geometry, materials, instances.length)
-mesh.customDepthMaterial = createVATDepthMaterial(vat, uniforms) // correct instanced shadows
-mesh.castShadow = mesh.receiveShadow = true
+// 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)
 
 // per frame:
 uniforms.uVatTime.value = clock.elapsedTime
 ```
 
-## Render a crowd — TSL (`WebGPURenderer`)
+</details>
+
+<details>
+<summary>By hand on TSL, and the zero-config default</summary>
 
 ```ts
 import { MeshStandardNodeMaterial } from 'three/webgpu'
+import { addVATInstanceAttributes } from 'three-vat'
 import { vatNodes } from 'three-vat/tsl'
 
-const { positionNode, normalNode, time } = vatNodes(vat, { clipIndex: 0, desync: 10 })
+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
-material.normalNode = normalNode
 
 // per frame:
 time.value = clock.elapsedTime
 ```
 
-Shadows just work on the TSL path (`positionNode` feeds the depth pass). v1 plays one clip per material with per-instance phase desync; use the WebGL path for mixed-clip crowds.
+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.
+
+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.
+
+</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.
 
-## Offline format — deprecated, removed in 1.0
+```ts
+// bake.worker.ts
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
+import { bakeVAT } from 'three-vat'
+
+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],
+  )
+}
+```
 
-> **Do not use `serializeVAT` / `loadVAT`.** They still ship in `0.3.0` for
-> compatibility and are removed in `1.0`
-> ([ADR-0010](./docs/adr/0010-drop-the-offline-format-runtime-bake-is-the-library.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)
+```
 
-The format stores the texel buffers and a manifest, but *not* the geometry. Since
-`0.3.0` a bake merges the whole subtree into a new vertex set and the textures are
-indexed by that ordering, so a serialized VAT can only be rendered by reloading the
-source glTF and re-running the merge — the work the file existed to save. A VAT
-restored by `loadVAT` has no `geometry` or `materials`, so it is **not**
-interchangeable with a freshly-baked one, whatever earlier releases claimed.
+Two things do not cross the wire, both by nature rather than by omission:
 
-Bake at runtime instead. The baker is pure CPU and touches no renderer, so if bake
-time hurts on load, run `bakeVAT` in a Web Worker and transfer the texel buffers back.
+- **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 in v1.
+- **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
 
 ```bash
 pnpm install
-pnpm test        # baker core — pure CPU, no GPU needed
+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     # runs the robot-crowd demo in examples/ (model bundled)
+pnpm example             # serves the demo pages in examples/ (model bundled)
+pnpm parity              # cross-path pixel-diff gate — needs a GPU and a WebGPU browser
 ```
 
+`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).
+
 ## License
 
 MIT

package/dist/chunk-SXTVASKG.js

@@ -0,0 +1,40 @@
+import { InstancedBufferAttribute } from 'three';
+
+// src/instance-playback.ts
+var PLAYBACK_ATTRIBUTES = {
+  clipStart: "aClipStart",
+  clipFrames: "aClipFrames",
+  clipFps: "aClipFps",
+  timeOffset: "aTimeOffset",
+  speed: "aSpeed"
+};
+function addVATInstanceAttributes(geometry, instances) {
+  geometry.morphAttributes = {};
+  geometry.morphTargetsRelative = false;
+  const n = instances.length;
+  const clipStart = new Float32Array(n);
+  const clipFrames = new Float32Array(n);
+  const clipFps = new Float32Array(n);
+  const timeOffset = new Float32Array(n);
+  const speed = new Float32Array(n);
+  for (let i = 0; i < n; i++) {
+    const inst = instances[i];
+    clipStart[i] = inst.clip.startFrame;
+    clipFrames[i] = inst.clip.frames;
+    clipFps[i] = inst.clip.fps;
+    timeOffset[i] = inst.timeOffset;
+    speed[i] = inst.speed;
+  }
+  geometry.setAttribute(PLAYBACK_ATTRIBUTES.clipStart, new InstancedBufferAttribute(clipStart, 1));
+  geometry.setAttribute(PLAYBACK_ATTRIBUTES.clipFrames, new InstancedBufferAttribute(clipFrames, 1));
+  geometry.setAttribute(PLAYBACK_ATTRIBUTES.clipFps, new InstancedBufferAttribute(clipFps, 1));
+  geometry.setAttribute(PLAYBACK_ATTRIBUTES.timeOffset, new InstancedBufferAttribute(timeOffset, 1));
+  geometry.setAttribute(PLAYBACK_ATTRIBUTES.speed, new InstancedBufferAttribute(speed, 1));
+}
+function createCrowdGeometry(vat, instances) {
+  const geometry = vat.geometry.clone();
+  addVATInstanceAttributes(geometry, instances);
+  return geometry;
+}
+
+export { PLAYBACK_ATTRIBUTES, addVATInstanceAttributes, createCrowdGeometry };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { Object3D, AnimationClip, TypedArray, TextureDataType, DataTexture } from 'three';
-import { B as BakedVAT, V as VATClip, a as VAT } from './types-wVmIj2tC.js';
+import { V as VAT } from './instance-playback-BrGBIKLe.js';
+export { a as VATClip, b as VATClock, c as VATCrowd, d as VATInstance, e as addVATInstanceAttributes } from './instance-playback-BrGBIKLe.js';
 
 /**
  * Conservative fallback texture-dimension cap, used when the caller does not
@@ -33,10 +34,18 @@ interface BakeOptions {
  * how it got there.
  *
  * Positions are stored as deltas from the merged rest pose; normals absolute.
+ * Positions are exact for skinning, morph targets, node animation and any mix
+ * of them. A normal follows the same stages its vertex does — morph targets
+ * (`morphAttributes.normal`, where the asset carries them), then the skin
+ * matrix, then the part matrix. Normals reproduce what three's own skinning
+ * shader renders: linear blend skinning transforms a normal by the skin matrix
+ * rather than its inverse-transpose, which is exact for rigid and
+ * uniformly-scaled bones and an approximation for anything else. Non-uniform bone scale is where that
+ * approximation becomes visible, so the bake warns once, naming the bone.
  * Renderer-agnostic — touches no WebGL/WebGPU context — so it runs identically
  * at runtime, in a Web Worker, and in Node.
  */
-declare function bakeVAT(root: Object3D, clips: AnimationClip[], { fps, maxTextureSize }?: BakeOptions): BakedVAT;
+declare function bakeVAT(root: Object3D, clips: AnimationClip[], { fps, maxTextureSize }?: BakeOptions): VAT;
 /**
  * Build a VAT `DataTexture` with the fixed sampling flags every path relies on:
  * RGBA, nearest filtering, no mipmaps. Frame interpolation is done manually in
@@ -44,48 +53,4 @@ declare function bakeVAT(root: Object3D, clips: AnimationClip[], { fps, maxTextu
  */
 declare function makeVATTexture(data: TypedArray, width: number, height: number, type?: TextureDataType): DataTexture;
 
-type VATPrecision = 'float16' | 'float32';
-/**
- * The versioned descriptor of an offline-baked VAT. The manifest *is* the
- * format — bump `version` on any breaking layout change.
- */
-interface VATManifest {
-    version: 1;
-    vertexCount: number;
-    totalFrames: number;
-    encoding: 'delta';
-    precision: VATPrecision;
-    clips: VATClip[];
-    bounds: {
-        min: [number, number, number];
-        max: [number, number, number];
-    };
-}
-/** A serialized VAT: manifest plus the two raw texel buffers. */
-interface SerializedVAT {
-    manifest: VATManifest;
-    /** Interleaved RGBA position deltas, `float16` or `float32` per `manifest.precision`. */
-    position: ArrayBuffer;
-    /** Interleaved RGBA absolute normals, same precision. */
-    normal: ArrayBuffer;
-}
-interface SerializeOptions {
-    /** On-disk texel precision. Default `'float16'` (half the bytes, uploads directly). */
-    precision?: VATPrecision;
-}
-/**
- * Serialize a baked VAT to raw texel buffers + a versioned manifest. This is
- * the on-disk format; the runtime object is always reconstructed with
- * {@link loadVAT}.
- */
-/** @deprecated Removed in 1.0 — see ADR-0010. Bake at runtime instead. */
-declare function serializeVAT(vat: VAT, { precision }?: SerializeOptions): SerializedVAT;
-/**
- * Reconstruct a runtime VAT from serialized buffers. `float16` uploads as
- * `HalfFloatType`; `float32` as `FloatType`. The result is interchangeable with
- * a {@link bakeVAT} result.
- */
-/** @deprecated Removed in 1.0 — see ADR-0010. Bake at runtime instead. */
-declare function loadVAT(serialized: SerializedVAT): VAT;
-
-export { type BakeOptions, BakedVAT, MAX_TEXTURE_SIZE, type SerializeOptions, type SerializedVAT, VAT, VATClip, type VATManifest, type VATPrecision, bakeVAT, loadVAT, makeVATTexture, serializeVAT };
+export { type BakeOptions, MAX_TEXTURE_SIZE, VAT, bakeVAT, makeVATTexture };

package/dist/index.js

@@ -1,6 +1,6 @@
-import { FloatType, Matrix4, AnimationMixer, Box3, Vector4, Vector3, Sphere, DataTexture, RGBAFormat, NearestFilter, DataUtils, HalfFloatType, BufferGeometry, BufferAttribute } from 'three';
+export { addVATInstanceAttributes } from './chunk-SXTVASKG.js';
+import { FloatType, Matrix4, AnimationMixer, Box3, Vector4, Vector3, Sphere, DataTexture, RGBAFormat, NearestFilter, BufferGeometry, BufferAttribute } from 'three';
 
-// src/bake.ts
 var MAX_TEXTURE_SIZE = 16384;
 function asAttribute(value, mesh, name) {
   if (!(value instanceof BufferAttribute)) {
@@ -47,6 +47,7 @@ function collectParts(root) {
       skinIndex: geometry.attributes.skinIndex,
       skinWeight: geometry.attributes.skinWeight,
       morphPos: geometry.morphAttributes.position,
+      morphNrm: geometry.morphAttributes.normal,
       morphRelative: geometry.morphTargetsRelative
     });
   }
@@ -160,6 +161,9 @@ function bakeVAT(root, clips, { fps = 30, maxTextureSize = MAX_TEXTURE_SIZE } =
   const _n = new Vector3();
   const _mt = new Vector3();
   const _mb = new Vector3();
+  const _mbn = new Vector3();
+  const influencers = parts.filter((p) => p.isSkinned && p.skeleton).map(influencedBones);
+  let warnedNonUniformScale = false;
   let rowOffset = 0;
   clips.forEach((clip, ci) => {
     const frames = frameCounts[ci];
@@ -170,22 +174,38 @@ function bakeVAT(root, clips, { fps = 30, maxTextureSize = MAX_TEXTURE_SIZE } =
       mixer.setTime(f / frames * clip.duration);
       root.updateMatrixWorld(true);
       const row = rowOffset + f;
+      if (!warnedNonUniformScale) {
+        warnedNonUniformScale = warnOnNonUniformBoneScale(influencers, _bone);
+      }
       for (const part of parts) {
         _partMatrix.multiplyMatrices(rootInverse, part.mesh.matrixWorld);
         const influences = part.mesh.morphTargetInfluences;
-        const { morphPos, morphRelative, isSkinned, skeleton, skinIndex, skinWeight } = part;
+        const { morphPos, morphNrm, morphRelative, isSkinned, skeleton, skinIndex, skinWeight } = part;
+        const morphCount = influences ? Math.min(influences.length, Math.max(morphPos?.length ?? 0, morphNrm?.length ?? 0)) : 0;
         for (let v = 0; v < part.vertexCount; v++) {
           const vi = part.vertexStart + v;
           _p.fromBufferAttribute(part.basePos, v);
           _n.fromBufferAttribute(part.baseNrm, v);
-          if (morphPos && influences) {
-            if (!morphRelative) _mb.fromBufferAttribute(part.basePos, v);
-            for (let t = 0; t < morphPos.length; t++) {
+          if (influences && morphCount > 0) {
+            if (!morphRelative) {
+              _mb.fromBufferAttribute(part.basePos, v);
+              _mbn.fromBufferAttribute(part.baseNrm, v);
+            }
+            for (let t = 0; t < morphCount; t++) {
               const w = influences[t];
               if (w === 0) continue;
-              _mt.fromBufferAttribute(morphPos[t], v);
-              if (!morphRelative) _mt.sub(_mb);
-              _p.addScaledVector(_mt, w);
+              const targetPos = morphPos?.[t];
+              if (targetPos) {
+                _mt.fromBufferAttribute(targetPos, v);
+                if (!morphRelative) _mt.sub(_mb);
+                _p.addScaledVector(_mt, w);
+              }
+              const targetNrm = morphNrm?.[t];
+              if (targetNrm) {
+                _mt.fromBufferAttribute(targetNrm, v);
+                if (!morphRelative) _mt.sub(_mbn);
+                _n.addScaledVector(_mt, w);
+              }
             }
           }
           if (isSkinned && skeleton) {
@@ -256,6 +276,39 @@ function bakeVAT(root, clips, { fps = 30, maxTextureSize = MAX_TEXTURE_SIZE } =
     materials
   };
 }
+function influencedBones(part) {
+  const used = /* @__PURE__ */ new Set();
+  const index = part.skinIndex;
+  const weight = part.skinWeight;
+  for (let v = 0; v < part.vertexCount; v++) {
+    for (let i = 0; i < 4; i++) {
+      if (weight.getComponent(v, i) !== 0) used.add(index.getComponent(v, i));
+    }
+  }
+  return { skeleton: part.skeleton, bones: [...used] };
+}
+var SCALE_UNIFORMITY_EPSILON = 1e-4;
+function hasNonUniformScale(m) {
+  const e = m.elements;
+  const x = e[0] * e[0] + e[1] * e[1] + e[2] * e[2];
+  const y = e[4] * e[4] + e[5] * e[5] + e[6] * e[6];
+  const z = e[8] * e[8] + e[9] * e[9] + e[10] * e[10];
+  const max = Math.max(x, y, z);
+  return max - Math.min(x, y, z) > SCALE_UNIFORMITY_EPSILON * max;
+}
+function warnOnNonUniformBoneScale(influencers, scratch) {
+  for (const { skeleton, bones } of influencers) {
+    for (const b of bones) {
+      scratch.multiplyMatrices(skeleton.bones[b].matrixWorld, skeleton.boneInverses[b]);
+      if (!hasNonUniformScale(scratch)) continue;
+      console.warn(
+        `three-vat: bone "${skeleton.bones[b].name || "(unnamed)"}" animates with non-uniform scale; baked normals under it are approximate, because linear-blend skinning transforms a normal by the skin matrix rather than its inverse-transpose \u2014 the same shortcut three's own skinning shader takes. Positions are exact.`
+      );
+      return true;
+    }
+  }
+  return false;
+}
 function makeVATTexture(data, width, height, type = FloatType) {
   const tex = new DataTexture(data, width, height, RGBAFormat, type);
   tex.minFilter = NearestFilter;
@@ -264,50 +317,5 @@ function makeVATTexture(data, width, height, type = FloatType) {
   tex.needsUpdate = true;
   return tex;
 }
-function serializeVAT(vat, { precision = "float16" } = {}) {
-  const pos = vat.positionTexture.image.data;
-  const nrm = vat.normalTexture.image.data;
-  const manifest = {
-    version: 1,
-    vertexCount: vat.vertexCount,
-    totalFrames: vat.totalFrames,
-    encoding: vat.encoding,
-    precision,
-    clips: vat.clips,
-    bounds: {
-      min: [vat.bounds.min.x, vat.bounds.min.y, vat.bounds.min.z],
-      max: [vat.bounds.max.x, vat.bounds.max.y, vat.bounds.max.z]
-    }
-  };
-  return { manifest, position: encode(pos, precision), normal: encode(nrm, precision) };
-}
-function encode(src, precision) {
-  if (precision === "float32") {
-    return src.slice().buffer;
-  }
-  const half = new Uint16Array(src.length);
-  for (let i = 0; i < src.length; i++) half[i] = DataUtils.toHalfFloat(src[i]);
-  return half.buffer;
-}
-function loadVAT(serialized) {
-  const { manifest, position, normal } = serialized;
-  const { vertexCount, totalFrames, precision } = manifest;
-  const type = precision === "float32" ? FloatType : HalfFloatType;
-  const posData = precision === "float32" ? new Float32Array(position) : new Uint16Array(position);
-  const nrmData = precision === "float32" ? new Float32Array(normal) : new Uint16Array(normal);
-  const bounds = new Box3(
-    new Vector3().fromArray(manifest.bounds.min),
-    new Vector3().fromArray(manifest.bounds.max)
-  );
-  return {
-    positionTexture: makeVATTexture(posData, vertexCount, totalFrames, type),
-    normalTexture: makeVATTexture(nrmData, vertexCount, totalFrames, type),
-    clips: manifest.clips,
-    bounds,
-    vertexCount,
-    totalFrames,
-    encoding: manifest.encoding
-  };
-}
 
-export { MAX_TEXTURE_SIZE, bakeVAT, loadVAT, makeVATTexture, serializeVAT };
+export { MAX_TEXTURE_SIZE, bakeVAT, makeVATTexture };

package/dist/instance-playback-BrGBIKLe.d.ts

@@ -0,0 +1,109 @@
+import { DataTexture, BufferGeometry, Material, Box3, InstancedMesh } from 'three';
+
+/** One baked animation range within a VAT's stacked frame rows. */
+interface VATClip {
+    /** Clip name, taken from the source `AnimationClip`. */
+    name: string;
+    /** First frame row (y) of this clip in the texture. */
+    startFrame: number;
+    /** Number of frame rows baked for this clip. */
+    frames: number;
+    /** Effective frames-per-second of the bake (`frames / duration`). */
+    fps: number;
+    /** Source clip duration in seconds. */
+    duration: number;
+    /**
+     * Largest per-vertex position-delta magnitude (metres) across the clip.
+     * Near-zero means the clip baked as a frozen pose — the diagnostic for a
+     * mis-targeted or genuinely static clip.
+     */
+    maxDelta: number;
+}
+/**
+ * A baked Vertex Animation Texture: the position/normal `DataTexture`s, the
+ * geometry they are indexed by, and the clip table and bounds needed to decode
+ * and render them. Produced exactly one way — {@link bakeVAT}, at runtime, from
+ * a loaded glTF (ADR-0010).
+ *
+ * The merged vertex ordering is the baker's own invention and the textures are
+ * indexed by it (`x = gl_VertexID`), so the caller cannot bring its own
+ * geometry — it must render the one baked here. `materials` is ordered to match
+ * `geometry.groups[].materialIndex`, giving one draw call per material.
+ */
+interface VAT {
+    /** RGBA float texture of per-vertex position deltas (`x = vertex`, `y = frame`). */
+    positionTexture: DataTexture;
+    /** RGBA float texture of per-vertex absolute normals (`x = vertex`, `y = frame`). */
+    normalTexture: DataTexture;
+    /** Merged, root-space rest-pose geometry. Its `position` is the delta reference. */
+    geometry: BufferGeometry;
+    /** Source materials, indexed by `geometry.groups[].materialIndex`. */
+    materials: Material[];
+    /** Clip table: name → `{ startFrame, frames, fps, ... }`. */
+    clips: VATClip[];
+    /** Union of every baked frame's bounds; use as the geometry bounding box. */
+    bounds: Box3;
+    /** Vertex count (texture width). */
+    vertexCount: number;
+    /** Total frame rows across all clips (texture height). */
+    totalFrames: number;
+    /** Position encoding. Only `'delta'` in v1. */
+    encoding: 'delta';
+}
+/**
+ * The shared playback clock: one `{ value }` in seconds, read by every material
+ * of every VAT mesh driven by it. Set it once per frame. Deliberately the
+ * narrowest shape both decode paths satisfy — a WebGL `IUniform<number>` and a
+ * TSL uniform node are both one of these — so `createVATMesh` returns the same
+ * thing on either renderer.
+ */
+interface VATClock {
+    value: number;
+}
+/**
+ * A **crowd** ready to render: the mesh to add to the scene, and the clock to
+ * advance. What `createVATMesh` returns on either decode path, so moving a
+ * crowd between renderers is an import change and nothing else. Named for what
+ * it is rather than for its `mesh` field — the clock is half of it.
+ */
+interface VATCrowd {
+    /** Add to the scene. Its instance matrices are yours to write. */
+    mesh: InstancedMesh;
+    /** The shared playback clock — set `.value` once per frame. */
+    time: VATClock;
+}
+
+/** Per-instance playback state consumed by both decode paths. */
+interface VATInstance {
+    clip: Pick<VAT['clips'][number], 'startFrame' | 'frames' | 'fps'>;
+    /** Phase offset in seconds — desyncs the crowd. */
+    timeOffset: number;
+    /** Playback rate multiplier. */
+    speed: number;
+}
+/**
+ * Attach the instance-playback attributes to an instanced geometry. Call once
+ * before rendering, on the geometry you hand to the `InstancedMesh`.
+ *
+ * The attribute names and layout below are the shared contract, spelled once in
+ * {@link PLAYBACK_ATTRIBUTES}. Both decode paths read exactly these five —
+ * `DECODE_PRELUDE` in `src/webgl.ts` as GLSL attributes, `vatNodes` in
+ * `src/tsl.ts` as TSL attribute nodes, when it is handed this geometry.
+ *
+ * | Attribute     | Type          | Source                |
+ * | ------------- | ------------- | --------------------- |
+ * | `aClipStart`  | `float` (x 1) | `instance.clip.startFrame` — first texture row of the clip's frame band |
+ * | `aClipFrames` | `float` (x 1) | `instance.clip.frames` — rows in the band |
+ * | `aClipFps`    | `float` (x 1) | `instance.clip.fps` — with `frames`, the clip's duration |
+ * | `aTimeOffset` | `float` (x 1) | `instance.timeOffset` — phase, in seconds |
+ * | `aSpeed`      | `float` (x 1) | `instance.speed` — rate multiplier |
+ *
+ * Every entry is a one-component `InstancedBufferAttribute` of `Float32Array`,
+ * one element per instance, in instance order. Adding a field — crossfade's
+ * reserved second clip index being the known case (ADR-0007) — means adding it
+ * here, in the table above, and in each decode path's own attribute
+ * declarations.
+ */
+declare function addVATInstanceAttributes(geometry: BufferGeometry, instances: VATInstance[]): void;
+
+export { type VAT as V, type VATClip as a, type VATClock as b, type VATCrowd as c, type VATInstance as d, addVATInstanceAttributes as e };

package/dist/tsl.d.ts

@@ -1,6 +1,6 @@
+import { BufferGeometry, InstancedMesh } from 'three';
 import { Node } from 'three/webgpu';
-import { a as VAT } from './types-wVmIj2tC.js';
-import 'three';
+import { b as VATClock, V as VAT, d as VATInstance, c as VATCrowd } from './instance-playback-BrGBIKLe.js';
 
 /**
  * The real maximum texture dimension this renderer accepts, for
@@ -16,39 +16,149 @@ declare function getMaxTextureSize(renderer: object): number;
 type FloatNode = Node<'float'>;
 /** A fluent TSL vec3 node. */
 type Vec3Node = Node<'vec3'>;
+/**
+ * A TSL float uniform: a node the graph reads, and a `{ value }` clock the
+ * caller sets per frame. Both halves matter — the node is what the decode
+ * samples against, the clock is what the render loop writes — which is why
+ * `createVATMesh` can hand the same object back as a {@link VATClock} and have
+ * it mean the same thing as the WebGL path's uniform.
+ */
+type VATTimeUniform = FloatNode & VATClock;
 interface VATNodeOptions {
     /**
-     * Elapsed-time uniform node (seconds). Create once with `uniform(0)` and set
+     * Elapsed-time uniform (seconds). Create once with `uniform(0)` and set
      * `.value` per frame. Defaults to a fresh `uniform(0)` you can read back.
      */
-    time?: FloatNode;
-    /** Which clip to play (index into `vat.clips`). Default `0`. */
+    time?: VATTimeUniform;
+    /**
+     * The geometry these nodes will render. When it carries the instance-playback
+     * attributes — write them with `addVATInstanceAttributes` from `three-vat`
+     * *before* calling this — each instance plays its own clip, at its own phase
+     * and rate. Without them, every instance plays `clipIndex`, phase-desynced by
+     * `desync`.
+     *
+     * Which decode the graph compiles is decided here, at build time: a TSL
+     * attribute that is missing from the geometry reads as a constant, so the
+     * fallback cannot be a shader-side branch.
+     */
+    geometry?: BufferGeometry;
+    /**
+     * The `InstancedMesh` these nodes will render, when there is one.
+     *
+     * Required for a crowd, and for one reason: three applies the instance matrix
+     * to `positionLocal` *before* it reads `positionNode`, so the decode has to
+     * displace in the geometry's own space and then re-apply the instancing
+     * itself. Without this the delta is added in instance space — unrotated and
+     * unscaled — and every instance deforms according to its own matrix.
+     *
+     * Omit it for a single, non-instanced mesh, where `positionLocal` is the
+     * geometry position and there is nothing to re-apply.
+     */
+    instancedMesh?: InstancedMesh;
+    /**
+     * Which clip to play (index into `vat.clips`). Ignored — along with
+     * `desync` — when `geometry` carries instance playback, which says all of this
+     * per instance. Default `0`.
+     */
     clipIndex?: number;
     /**
      * Max random per-instance time offset in seconds, hashed from `instanceIndex`.
-     * `0` (default) plays every instance in lockstep.
+     * `0` (default) plays every instance in lockstep. Ignored when `geometry`
+     * carries instance playback.
      */
     desync?: number;
 }
 /** Position/normal nodes to assign onto a `MeshStandardNodeMaterial` (or similar). */
 interface VATNodes {
+    /**
+     * Assign to `material.positionNode`. It carries the whole decode — the normal
+     * with it.
+     *
+     * There is deliberately no `normalNode`. A material's `normalNode` is built in
+     * the *fragment* stage (three reaches it from `normalView` through
+     * `builder.context.setupNormal()`) and is expected in **view** space, whereas a
+     * VAT's baked normals are per-vertex and in the geometry's own space. Handing
+     * an object-space normal to a fragment-stage node skipped both the instance
+     * matrix and the normal matrix, and took `vertexIndex` into the fragment stage
+     * with it — where `IndexNode` does not give you the vertex index at all, but
+     * quietly turns itself into a varying, so every fragment read a linearly
+     * *interpolated* index that addresses neither of the vertices it lies between.
+     *
+     * Writing `normalLocal` inside the vertex-stage decode instead is what the
+     * GLSL path does when it sets `objectNormal` in `beginnormal_vertex`: three
+     * then transforms it by the instance and normal matrices and interpolates the
+     * result, on both paths, for free.
+     */
     positionNode: Vec3Node;
-    normalNode: Vec3Node;
     /** The time uniform in use — set `.value` each frame. */
-    time: FloatNode;
+    time: VATTimeUniform;
 }
 /**
  * Build TSL decode nodes for a baked VAT, for the WebGPU/TSL renderer path.
- * Per-instance desync comes from `hash(instanceIndex)` — no instanced
- * attributes needed. Shadows work automatically because `positionNode` also
- * feeds the depth pass.
+ * Shadows work automatically because `positionNode` also feeds the depth pass.
  *
- * v1 limitation: a single clip per material (all instances share `clipIndex`,
- * only their phase is desynced). Per-instance clip variety is future work; use
- * the `three-vat/webgl` path for mixed-clip crowds today.
+ * Pass the `geometry` you are about to render and each instance plays the clip,
+ * phase and rate written into it by `addVATInstanceAttributes` — the same
+ * instance-playback contract the WebGL path reads (ADR-0009), so a mixed-clip
+ * crowd renders identically on either renderer. Without those attributes every
+ * instance plays `clipIndex`, desynced by a phase hashed from `instanceIndex`.
  *
- * NOTE: the TSL path is verified visually/manually in v1 (no automated GPU test).
+ * Coverage note: the node graph is tested structurally in CI (no GPU); that the
+ * two paths decode *identically* is a pixel-diff release gate.
  */
 declare function vatNodes(vat: VAT, options?: VATNodeOptions): VATNodes;
+/**
+ * The decode's arithmetic: the position delta and the normal this instance reads
+ * at this moment, as nodes — before the vertex-stage writes that place them.
+ *
+ * @internal Split out and exported for the structural tests. A `Fn` body is
+ * opaque to graph traversal (its statements are not built until the shader is),
+ * and structural assertions are the only TSL coverage CI can run without a GPU —
+ * so the arithmetic that matters stays reachable as a graph. Not re-exported
+ * from `three-vat`; nothing outside this package should build against it.
+ */
+declare function vatDecode(vat: VAT, options?: VATNodeOptions): {
+    position: Vec3Node;
+    normal: Vec3Node;
+};
+/** Options for {@link createVATMesh}. */
+interface CreateVATMeshOptions {
+    /**
+     * The playback clock to drive this crowd from, in seconds. Pass one — from
+     * `uniform(0)` — to run several VAT meshes off a single time value, or to
+     * keep the node for wiring elsewhere in a graph, which the returned `time`
+     * gives back as a plain clock. Defaults to a fresh `uniform(0)`.
+     *
+     * The one place the two paths' signatures differ: `three-vat/webgl` takes a
+     * `THREE.IUniform` here. Both are `{ value }` clocks, and code that lets the
+     * call make its own is identical on either path.
+     */
+    time?: VATTimeUniform;
+}
+/**
+ * Turn a baked VAT and a list of instances into a crowd ready to render: an
+ * `InstancedMesh` whose geometry carries the instance-playback contract and
+ * whose materials decode the VAT on the vertex stage.
+ *
+ * ```ts
+ * const { mesh, time } = createVATMesh(vat, instances)
+ * mesh.castShadow = mesh.receiveShadow = true
+ * scene.add(mesh)
+ * // per frame:
+ * time.value = clock.elapsedTime
+ * ```
+ *
+ * The same call, the same signature and the same return as `three-vat/webgl`:
+ * a crowd moves between `WebGLRenderer` and `WebGPURenderer` by changing the
+ * import line and nothing else. The one asymmetry is absorbed here rather than
+ * passed on — this path attaches **no depth material**, because `positionNode`
+ * already feeds the depth pass, whereas the WebGL path must patch one by hand
+ * or cast bind-pose shadows.
+ *
+ * Instance matrices and `castShadow`/`receiveShadow` stay yours, as on the
+ * WebGL path: `mesh.setMatrixAt` then `mesh.computeBoundingSphere()`, or
+ * `frustumCulled = false` when the matrices change every frame.
+ */
+declare function createVATMesh(vat: VAT, instances: VATInstance[], options?: CreateVATMeshOptions): VATCrowd;
 
-export { type VATNodeOptions, type VATNodes, getMaxTextureSize, vatNodes };
+export { type CreateVATMeshOptions, type VATNodeOptions, type VATNodes, type VATTimeUniform, createVATMesh, getMaxTextureSize, vatDecode, vatNodes };

package/dist/tsl.js

@@ -1,6 +1,7 @@
-import { uniform, float, int, hash, instanceIndex, vertexIndex, positionLocal, textureLoad, ivec2, mix } from 'three/tsl';
+import { createCrowdGeometry, PLAYBACK_ATTRIBUTES } from './chunk-SXTVASKG.js';
+import { InstancedMesh } from 'three';
+import { uniform, Fn, positionLocal, positionGeometry, normalLocal, instancedMesh, int, vertexIndex, textureLoad, ivec2, mix, float, hash, instanceIndex, attribute } from 'three/tsl';
 
-// src/tsl.ts
 function getMaxTextureSize(renderer) {
   const backend = renderer.backend;
   const device = backend?.["device"];
@@ -9,30 +10,78 @@ function getMaxTextureSize(renderer) {
   if (gl) return gl.getParameter(gl.MAX_TEXTURE_SIZE);
   throw new Error("three-vat: renderer has no initialized backend \u2014 call `await renderer.init()` first");
 }
-function vatNodes(vat, options = {}) {
-  const { time = uniform(0), clipIndex = 0, desync = 0 } = options;
+var floatAttribute = (name) => attribute(name, "float");
+function attributePlayback() {
+  const frames = floatAttribute(PLAYBACK_ATTRIBUTES.clipFrames);
+  return {
+    startFrame: int(floatAttribute(PLAYBACK_ATTRIBUTES.clipStart)),
+    frames,
+    duration: frames.div(floatAttribute(PLAYBACK_ATTRIBUTES.clipFps)),
+    timeOffset: floatAttribute(PLAYBACK_ATTRIBUTES.timeOffset),
+    speed: floatAttribute(PLAYBACK_ATTRIBUTES.speed)
+  };
+}
+function clipAt(vat, clipIndex) {
   const clip = vat.clips[clipIndex];
   if (!clip) {
     throw new Error(`three-vat: clipIndex ${clipIndex} out of range (${vat.clips.length} clips)`);
   }
-  const frames = float(clip.frames);
-  const startFrame = int(clip.startFrame);
-  const duration = float(clip.frames / clip.fps);
-  const offset = hash(instanceIndex).mul(desync);
+  return clip;
+}
+function hashedPlayback(clip, desync) {
+  return {
+    startFrame: int(clip.startFrame),
+    frames: float(clip.frames),
+    duration: float(clip.frames / clip.fps),
+    timeOffset: hash(instanceIndex).mul(desync),
+    speed: float(1)
+  };
+}
+function checkPlaybackAttributes(geometry) {
+  const names = Object.values(PLAYBACK_ATTRIBUTES);
+  const missing = names.filter((name) => geometry.getAttribute(name) === void 0);
+  if (missing.length === 0) return true;
+  if (missing.length === names.length) return false;
+  throw new Error(
+    `three-vat: geometry carries only part of the instance-playback contract (missing ${missing.join(", ")}) \u2014 write all of it with \`addVATInstanceAttributes\` from \`three-vat\`, or pass no geometry for the hashed default`
+  );
+}
+function vatNodes(vat, options = {}) {
+  const { time = uniform(0), instancedMesh: instanced } = options;
+  const { position, normal } = vatDecode(vat, options);
+  const decode = Fn(() => {
+    positionLocal.assign((instanced ? positionGeometry : positionLocal).add(position));
+    normalLocal.assign(normal);
+    if (instanced) instancedMesh(instanced);
+    return positionLocal;
+  }, "vec3");
+  return { positionNode: decode(), time };
+}
+function vatDecode(vat, options = {}) {
+  const { time = uniform(0), geometry, clipIndex = 0, desync = 0 } = options;
+  const playback = geometry && checkPlaybackAttributes(geometry) ? attributePlayback() : hashedPlayback(clipAt(vat, clipIndex), desync);
   const vertexRow = int(vertexIndex);
   const sample = (tex) => {
-    const t = time.add(offset).div(duration).fract().mul(frames);
+    const t = time.mul(playback.speed).add(playback.timeOffset).div(playback.duration).fract().mul(playback.frames);
     const f0 = int(t);
-    const f1 = int(f0.add(1).toFloat().mod(frames));
-    const s0 = textureLoad(tex, ivec2(vertexRow, f0.add(startFrame))).xyz;
-    const s1 = textureLoad(tex, ivec2(vertexRow, f1.add(startFrame))).xyz;
+    const f1 = int(f0.add(1).toFloat().mod(playback.frames));
+    const s0 = textureLoad(tex, ivec2(vertexRow, f0.add(playback.startFrame))).xyz;
+    const s1 = textureLoad(tex, ivec2(vertexRow, f1.add(playback.startFrame))).xyz;
     return mix(s0, s1, t.fract());
   };
   return {
-    positionNode: positionLocal.add(sample(vat.positionTexture)),
-    normalNode: sample(vat.normalTexture).normalize(),
-    time
+    position: sample(vat.positionTexture),
+    normal: sample(vat.normalTexture).normalize()
   };
 }
+function createVATMesh(vat, instances, options = {}) {
+  const time = options.time ?? uniform(0);
+  const geometry = createCrowdGeometry(vat, instances);
+  const materials = vat.materials.map((source) => source.clone());
+  const mesh = new InstancedMesh(geometry, materials, instances.length);
+  const { positionNode } = vatNodes(vat, { time, geometry, instancedMesh: mesh });
+  for (const material of materials) material.positionNode = positionNode;
+  return { mesh, time };
+}
 
-export { getMaxTextureSize, vatNodes };
+export { createVATMesh, getMaxTextureSize, vatDecode, vatNodes };

package/dist/webgl.d.ts

@@ -1,5 +1,5 @@
-import { IUniform, BufferGeometry, MeshDepthMaterial, WebGLRenderer, Material } from 'three';
-import { a as VAT } from './types-wVmIj2tC.js';
+import { IUniform, MeshDepthMaterial, WebGLRenderer, Material } from 'three';
+import { d as VATInstance$1, e as addVATInstanceAttributes, V as VAT, c as VATCrowd } from './instance-playback-BrGBIKLe.js';
 
 /**
  * The real maximum texture dimension this GPU accepts, for
@@ -16,19 +16,20 @@ interface VATUniforms {
 }
 /** Create the shared time uniform. Update `uVatTime.value` once per frame. */
 declare function createVATUniforms(time?: number): VATUniforms;
-/** Per-instance playback state consumed by the patched shader. */
-interface VATInstance {
-    clip: Pick<VAT['clips'][number], 'startFrame' | 'frames' | 'fps'>;
-    /** Phase offset in seconds — desyncs the crowd. */
-    timeOffset: number;
-    /** Playback rate multiplier. */
-    speed: number;
-}
 /**
- * Attach the per-instance attributes the WebGL decode reads: clip band, fps,
- * time offset, and speed. Call on the instanced geometry before rendering.
+ * The instance-playback contract now lives in the core entry point, so both
+ * decode paths can read it (ADR-0009).
+ *
+ * @deprecated Renamed to `addVATInstanceAttributes` and moved to `three-vat`.
+ * Removed from `three-vat/webgl` in the next minor version — import it from
+ * `three-vat` instead.
+ */
+declare const addInstancedVATAttributes: typeof addVATInstanceAttributes;
+/**
+ * @deprecated Moved to `three-vat`. Removed from `three-vat/webgl` in the next
+ * minor version — import `VATInstance` from `three-vat` instead.
  */
-declare function addInstancedVATAttributes(geometry: BufferGeometry, instances: VATInstance[]): void;
+type VATInstance = VATInstance$1;
 /**
  * Patch any built-in material so its vertex stage samples the VAT instead of
  * skinning. Works on the render material and on `MeshDepthMaterial` (needed for
@@ -43,5 +44,45 @@ declare function patchVATMaterial<T extends Material>(material: T, vat: VAT, uni
  * `MeshDistanceMaterial`).
  */
 declare function createVATDepthMaterial(vat: VAT, uniforms: VATUniforms): MeshDepthMaterial;
+/** Options for {@link createVATMesh}. */
+interface CreateVATMeshOptions {
+    /**
+     * The playback clock to drive this crowd from, in seconds. Pass one — from
+     * {@link createVATUniforms} or any `{ value }` — to run several VAT meshes off
+     * a single time value. Defaults to a fresh clock at `0`, returned to you as
+     * `time`. The TSL path's `vatNodes` takes its clock the same way.
+     */
+    time?: IUniform<number>;
+}
+/**
+ * Turn a baked VAT and a list of instances into a crowd ready to render: an
+ * `InstancedMesh` whose geometry carries the instance-playback contract, whose
+ * materials decode the VAT, and whose shadows are deformed rather than frozen
+ * in the bind pose.
+ *
+ * ```ts
+ * const { mesh, time } = createVATMesh(vat, instances)
+ * mesh.castShadow = mesh.receiveShadow = true
+ * scene.add(mesh)
+ * // per frame:
+ * time.value = clock.elapsedTime
+ * ```
+ *
+ * Two things stay yours, because only you can know them:
+ *
+ * - **Instance matrices.** Write them with `mesh.setMatrixAt`, then
+ *   `mesh.instanceMatrix.needsUpdate = true`. An `InstancedMesh` caches the
+ *   bounding sphere it culls against, so call `mesh.computeBoundingSphere()`
+ *   after placing the crowd, or set `mesh.frustumCulled = false` when the
+ *   matrices change every frame.
+ * - **`castShadow` / `receiveShadow`**, which are scene decisions. The depth and
+ *   distance materials the shadow passes need are already attached either way.
+ *
+ * Everything here is the exported primitives — {@link addVATInstanceAttributes},
+ * {@link patchVATMaterial}, {@link createVATDepthMaterial} — composed in the one
+ * order that is correct. Reach for them directly only when rendering onto
+ * something other than a plain `InstancedMesh`.
+ */
+declare function createVATMesh(vat: VAT, instances: VATInstance$1[], options?: CreateVATMeshOptions): VATCrowd;
 
-export { type VATInstance, type VATUniforms, addInstancedVATAttributes, createVATDepthMaterial, createVATUniforms, getMaxTextureSize, patchVATMaterial };
+export { type CreateVATMeshOptions, type VATInstance, type VATUniforms, addInstancedVATAttributes, createVATDepthMaterial, createVATMesh, createVATUniforms, getMaxTextureSize, patchVATMaterial };

package/dist/webgl.js

@@ -1,35 +1,13 @@
-import { InstancedBufferAttribute, MeshDepthMaterial, RGBADepthPacking } from 'three';
+import { addVATInstanceAttributes, createCrowdGeometry } from './chunk-SXTVASKG.js';
+import { MeshDepthMaterial, RGBADepthPacking, InstancedMesh, MeshDistanceMaterial } from 'three';
 
-// src/webgl.ts
 function getMaxTextureSize(renderer) {
   return renderer.capabilities.maxTextureSize;
 }
 function createVATUniforms(time = 0) {
   return { uVatTime: { value: time } };
 }
-function addInstancedVATAttributes(geometry, instances) {
-  geometry.morphAttributes = {};
-  geometry.morphTargetsRelative = false;
-  const n = instances.length;
-  const clipStart = new Float32Array(n);
-  const clipFrames = new Float32Array(n);
-  const clipFps = new Float32Array(n);
-  const timeOffset = new Float32Array(n);
-  const speed = new Float32Array(n);
-  for (let i = 0; i < n; i++) {
-    const inst = instances[i];
-    clipStart[i] = inst.clip.startFrame;
-    clipFrames[i] = inst.clip.frames;
-    clipFps[i] = inst.clip.fps;
-    timeOffset[i] = inst.timeOffset;
-    speed[i] = inst.speed;
-  }
-  geometry.setAttribute("aClipStart", new InstancedBufferAttribute(clipStart, 1));
-  geometry.setAttribute("aClipFrames", new InstancedBufferAttribute(clipFrames, 1));
-  geometry.setAttribute("aClipFps", new InstancedBufferAttribute(clipFps, 1));
-  geometry.setAttribute("aTimeOffset", new InstancedBufferAttribute(timeOffset, 1));
-  geometry.setAttribute("aSpeed", new InstancedBufferAttribute(speed, 1));
-}
+var addInstancedVATAttributes = addVATInstanceAttributes;
 var DECODE_PRELUDE = (
   /* glsl */
   `
@@ -82,5 +60,14 @@ function createVATDepthMaterial(vat, uniforms) {
   patchVATMaterial(depth, vat, uniforms);
   return depth;
 }
+function createVATMesh(vat, instances, options = {}) {
+  const uniforms = options.time ? { uVatTime: options.time } : createVATUniforms();
+  const geometry = createCrowdGeometry(vat, instances);
+  const materials = vat.materials.map((source) => patchVATMaterial(source.clone(), vat, uniforms));
+  const mesh = new InstancedMesh(geometry, materials, instances.length);
+  mesh.customDepthMaterial = createVATDepthMaterial(vat, uniforms);
+  mesh.customDistanceMaterial = patchVATMaterial(new MeshDistanceMaterial(), vat, uniforms);
+  return { mesh, time: uniforms.uVatTime };
+}
 
-export { addInstancedVATAttributes, createVATDepthMaterial, createVATUniforms, getMaxTextureSize, patchVATMaterial };
+export { addInstancedVATAttributes, createVATDepthMaterial, createVATMesh, createVATUniforms, getMaxTextureSize, patchVATMaterial };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-vat",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "description": "Bake glTF animation clips into vertex animation textures for zero-CPU instanced crowds in three.js.",
   "type": "module",
   "license": "MIT",
@@ -65,9 +65,14 @@
     "dev": "tsup --watch",
     "test": "vitest run",
     "test:watch": "vitest",
+    "fetch:test-assets": "node scripts/fetch-test-assets.mjs",
     "typecheck": "tsc --noEmit",
-    "release": "pnpm publish --otp=\"${NPM_OTP:?set NPM_OTP=<code from your authenticator>}\" && pnpm verify:published",
+    "release": "pnpm publish ${NPM_OTP:+--otp=\"$NPM_OTP\"} && pnpm verify:published",
     "verify:published": "node scripts/verify-published.mjs",
-    "example": "pnpm --dir examples dev"
+    "example": "pnpm --filter three-vat-example dev",
+    "build:examples": "pnpm --filter three-vat-example build",
+    "test:examples": "pnpm --filter three-vat-example test",
+    "parity": "pnpm --filter three-vat-example parity",
+    "typecheck:examples": "pnpm --filter three-vat-example typecheck"
   }
 }

package/dist/types-wVmIj2tC.d.ts

@@ -1,63 +0,0 @@
-import { DataTexture, Box3, BufferGeometry, Material } from 'three';
-
-/** One baked animation range within a VAT's stacked frame rows. */
-interface VATClip {
-    /** Clip name, taken from the source `AnimationClip`. */
-    name: string;
-    /** First frame row (y) of this clip in the texture. */
-    startFrame: number;
-    /** Number of frame rows baked for this clip. */
-    frames: number;
-    /** Effective frames-per-second of the bake (`frames / duration`). */
-    fps: number;
-    /** Source clip duration in seconds. */
-    duration: number;
-    /**
-     * Largest per-vertex position-delta magnitude (metres) across the clip.
-     * Near-zero means the clip baked as a frozen pose — the diagnostic for a
-     * mis-targeted or genuinely static clip.
-     */
-    maxDelta: number;
-}
-/**
- * A baked Vertex Animation Texture: the position/normal `DataTexture`s plus the
- * clip table and bounds needed to decode and render them. Produced by
- * {@link bakeVAT} (runtime) or `loadVAT` (offline); the two paths yield
- * identical objects.
- */
-interface VAT {
-    /** RGBA float texture of per-vertex position deltas (`x = vertex`, `y = frame`). */
-    positionTexture: DataTexture;
-    /** RGBA float texture of per-vertex absolute normals (`x = vertex`, `y = frame`). */
-    normalTexture: DataTexture;
-    /** Clip table: name → `{ startFrame, frames, fps, ... }`. */
-    clips: VATClip[];
-    /** Union of every baked frame's bounds; use as the geometry bounding box. */
-    bounds: Box3;
-    /** Vertex count (texture width). */
-    vertexCount: number;
-    /** Total frame rows across all clips (texture height). */
-    totalFrames: number;
-    /** Position encoding. Only `'delta'` in v1. */
-    encoding: 'delta';
-}
-/**
- * What {@link bakeVAT} returns: a VAT plus the geometry it was baked against.
- *
- * The merged vertex ordering is the baker's own invention and the textures are
- * indexed by it (`x = gl_VertexID`), so the caller can no longer bring its own
- * geometry — it must render the one baked here. `materials` is ordered to match
- * `geometry.groups[].materialIndex`, giving one draw call per material.
- *
- * `loadVAT` returns a plain {@link VAT} without these, which is precisely why the
- * offline format is deprecated and removed in 1.0 (ADR-0010): a serialized VAT
- * cannot be rendered without re-running the merge that produced its ordering.
- */
-interface BakedVAT extends VAT {
-    /** Merged, root-space rest-pose geometry. Its `position` is the delta reference. */
-    geometry: BufferGeometry;
-    /** Source materials, indexed by `geometry.groups[].materialIndex`. */
-    materials: Material[];
-}
-
-export type { BakedVAT as B, VATClip as V, VAT as a };