three-vat 0.3.0 → 1.0.1

package/README.md

@@ -1,13 +1,14 @@
 # three-vat
 
-[![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)
+![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)
 
-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.
+**[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.
 
-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.
+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.
 
-> **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.
+[![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
 
@@ -17,111 +18,147 @@ npm install three-vat three
 
 `three` (>= 0.185) 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
+})
 
-// 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, ... }
-```
-
-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 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.
-- **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.
+// One entry per character: which clip it plays, its phase, its rate.
+const instances = Array.from({ length: 500 }, (_, i) => ({
+  clip: vat.clips[i % vat.clips.length],
+  timeOffset: Math.random() * 2, // desync, so the crowd is not in lockstep
+  speed: 0.9 + Math.random() * 0.2,
+}))
 
-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):
+// 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)
 
-```ts
-import { getMaxTextureSize } from 'three-vat/webgl' // or 'three-vat/tsl'
+// 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
 
-const vat = bakeVAT(gltf.scene, clips, {
-  fps: 30,
-  maxTextureSize: getMaxTextureSize(renderer),
+renderer.setAnimationLoop(() => {
+  time.value = clock.getElapsedTime() // the whole per-frame cost of the animation
+  renderer.render(scene, camera)
 })
 ```
 
-## Render a crowd — WebGL (`WebGLRenderer`)
+Two things worth knowing the first time:
 
-```ts
-import { addInstancedVATAttributes, createVATUniforms, createVATDepthMaterial, patchVATMaterial } from 'three-vat/webgl'
+- **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.
 
-const uniforms = createVATUniforms()
+<details>
+<summary><b>Does it work with my model?</b></summary>
 
-// 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 }[]
+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.
 
-// 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
-})
+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 mesh = new THREE.InstancedMesh(geometry, materials, instances.length)
-mesh.customDepthMaterial = createVATDepthMaterial(vat, uniforms) // correct instanced shadows
-mesh.castShadow = mesh.receiveShadow = true
+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.
 
-// per frame:
-uniforms.uVatTime.value = clock.elapsedTime
-```
+</details>
 
-## Render a crowd — TSL (`WebGPURenderer`)
+<details>
+<summary><b>Going bigger: texture limits, bake cost, Web Workers</b></summary>
 
-```ts
-import { MeshStandardNodeMaterial } from 'three/webgpu'
-import { vatNodes } from 'three-vat/tsl'
+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.
 
-const { positionNode, normalNode, time } = vatNodes(vat, { clipIndex: 0, desync: 10 })
-const material = new MeshStandardNodeMaterial()
-material.positionNode = positionNode
-material.normalNode = normalNode
+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.
 
-// per frame:
-time.value = clock.elapsedTime
-```
+**[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`.
 
-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.
+</details>
 
-## Offline format — deprecated, removed in 1.0
+<details>
+<summary><b>What it does not do</b></summary>
 
-> **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)).
+No clip crossfade (instances cut between clips), 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.
 
-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.
+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)).
 
-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.
+</details>
 
-## Trade-offs
+<details>
+<summary><b>Development</b></summary>
 
-- **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.
+```bash
+pnpm i
+pnpm run dev    # opens the demo — this and the line above are the whole setup
+```
 
-## Development
+Three more verbs, and that is the table:
 
 ```bash
-pnpm install
-pnpm test        # baker core — pure CPU, no GPU needed
-pnpm typecheck
-pnpm build
-pnpm example     # runs the robot-crowd demo in examples/ (model bundled)
+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 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
 
 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.1",
   "description": "Bake glTF animation clips into vertex animation textures for zero-CPU instanced crowds in three.js.",
   "type": "module",
   "license": "MIT",
@@ -52,22 +52,24 @@
   },
   "devDependencies": {
     "@types/three": "^0.185.0",
+    "gifenc": "1.0.3",
+    "playwright-core": "1.63.0",
+    "pngjs": "7.0.0",
     "three": "^0.185.0",
     "tsup": "^8.3.0",
     "typescript": "^5.6.0",
+    "vite": "^7.1.0",
     "vitest": "^2.1.0"
   },
   "engines": {
     "node": ">=18"
   },
   "scripts": {
+    "dev": "pnpm --filter three-vat-example dev",
+    "test": "vitest run && pnpm --filter three-vat-example test",
     "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "release": "pnpm publish --otp=\"${NPM_OTP:?set NPM_OTP=<code from your authenticator>}\" && pnpm verify:published",
-    "verify:published": "node scripts/verify-published.mjs",
-    "example": "pnpm --dir examples dev"
+    "typecheck": "tsc --noEmit && tsc --noEmit -p release/tsconfig.json && pnpm --filter three-vat-example typecheck",
+    "build:watch": "tsup --watch",
+    "test:watch": "vitest"
   }
 }

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 };