three-vat 3.0.0 → 4.1.0

package/README.md

@@ -47,7 +47,7 @@ const vat = bakeVAT(gltf.scene, gltf.animations, {
 })
 
 // One entry per character: which clip it plays, when it started, its rate.
-// Everything but `startTime` is optional — a clip baked from a configured
+// Only `clip` and `startTime` are required — a clip baked from a configured
 // `AnimationAction` carries its own loop, repetition count, end behaviour and
 // speed, and an instance overrides only what it wants to differ.
 const instances = Array.from({ length: 500 }, (_, i) => ({
@@ -78,13 +78,15 @@ Two things worth knowing the first time:
 - **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.
+- **Materials are never merged unless you ask.** A 500-robot crowd with 3
+  materials is 3 draw calls — not 1, and not 500. `mergeFlatMaterials: true`
+  makes flat colours one material, and the crowd one draw call.
 
-**A skinned character?** There is a second encoding: `{ encoding: 'rig' }` bakes
-the posed rig instead of the posed vertices — two orders of magnitude less
-texture, a bake in milliseconds, and faster on a phone, for an asset a rig can
-express. [The rig encoding](./docs/usage.md#the-rig-encoding-encoding-rig).
+**A skinned character?** The bake picks the rig encoding for it by itself: the
+posed rig instead of the posed vertices, for two orders of magnitude less
+texture, a bake in milliseconds, and a texture whose width is the rig's, not
+the mesh's. Assets a rig cannot express fall back to vertices, and `vat.fallback`
+says why. [The rig encoding](./docs/usage.md#the-rig-encoding-encoding-rig).
 
 <details>
 <summary><b>Does it work with my model?</b></summary>
@@ -148,9 +150,9 @@ is [the CHANGELOG's 2.0.0 entry](./CHANGELOG.md).
 ```
 
 `timeOffset` is gone (`startTime: -timeOffset / speed`), and with it
-`aTimeOffset`. The pack became three `vec4`s — clip, playback, fade — in a
-**playback texture** keyed by the instance's logical index, not instanced
-attributes, which are indexed by the *drawn* slot:
+`aTimeOffset`. The pack moved into a **playback texture**, five texels a row
+since 3.0 (clip, playback, crossfade, outgoing clip, outgoing playback), keyed
+by the instance's logical index rather than the *drawn* slot. So
 `addInstancedVATAttributes` is removed, `createVATPlaybackTexture(instances)`
 replaces `addVATInstanceAttributes`, and `setVATInstance(playback, id, instance)`
 takes that texture — `createVATMesh` returns it as `playback` — rather than a
@@ -167,16 +169,18 @@ New, and none of it breaking: per-instance loop modes, one-shots,
 <details>
 <summary><b>Going bigger: texture limits, bake cost, Web Workers</b></summary>
 
-The VAT is one `vertexCount` × `totalFrames` texture pair, so both axes hit the
-GPU's texture ceiling. Always pass `maxTextureSize: getMaxTextureSize(renderer)`
+A vertex-encoded VAT is one `vertexCount` × `totalFrames` texture pair, so both
+axes hit the GPU's texture ceiling; a rig-encoded one is two texels a bone wide,
+so in practice only its frames do. Always pass `maxTextureSize: getMaxTextureSize(renderer)`
 as above: the default is a desktop-shaped guess, and mobile is often 4096.
 
-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.
+The bake is CPU work done once at load. Under the vertex encoding that is about
+100 ms for the demo's robot, and seconds for a 20k-vertex skinned character with
+many clips; the rig encoding bakes several to a few hundred times faster. It
+never touches the renderer, so `bakeVATInWorker` runs it in a Web Worker as-is.
 
 **[docs/usage.md](./docs/usage.md)** has the measured bake-cost table, the
-worker recipe, the draw-call arithmetic, and the primitives underneath
+worker bake, the draw-call arithmetic, and the primitives underneath
 `createVATMesh` for when you are not rendering onto a plain `InstancedMesh`.
 
 </details>

package/dist/{carrier-BxRuW47G.d.ts → carrier-VLSJLgjX.d.ts}

@@ -141,7 +141,8 @@ interface VATFrame {
      * Whether {@link rowNext} crossed the clip's last row back into its first.
      * True only while a clip is genuinely looping: a ping-pong bounces rather
      * than wraps, and a finished one-shot must not wrap at all or the corpse
-     * stands back up for a frame.
+     * stands back up for a frame — nor, across its final repetition, may any
+     * clip that ends by clamping (#88).
      */
     wraps: boolean;
     /** Whether the repetitions have run out and the instance is holding an end pose. */
@@ -230,12 +231,20 @@ interface VATPlaybackTextureOptions {
      * Rows to reserve — the crowd's ceiling, rather than its current population.
      * Defaults to the number of instances given, which is a crowd placed once.
      *
-     * At least that many, and at most `MAX_TEXTURE_SIZE`; both are refused by
-     * name. Fixed once the texture is made (ADR-0022): a texture does not grow
+     * At least that many, and at most {@link maxTextureSize}; both are refused
+     * by name. Fixed once the texture is made (ADR-0022): a texture does not grow
      * in place, and growing one means rebuilding it and rebinding it on every
      * patched material — `docs/usage.md` carries that recipe.
      */
     capacity?: number;
+    /**
+     * The GPU's real texture ceiling, and so the crowd's: the playback texture
+     * is one row per instance. Pass `getMaxTextureSize(renderer)` from
+     * `three-vat/webgl` or `three-vat/tsl`. Defaults to `MAX_TEXTURE_SIZE`, a
+     * desktop figure: a phone reporting 4096 refuses a crowd of 5000 at upload,
+     * with nothing naming the cause, unless the limit is given here (ADR-0022).
+     */
+    maxTextureSize?: number;
 }
 /**
  * Write a crowd's instance playback into a new playback texture. Call once,
@@ -245,8 +254,8 @@ interface VATPlaybackTextureOptions {
  * The layout below is the shared contract, spelled once in {@link PACK_TEXELS}.
  * Both decode paths read exactly these texels of row `instanceIndex` —
  * `ROW_PRELUDE` in `src/webgl.ts` with `texelFetch`, `texturePlayback` in
- * `src/tsl.ts` with `textureLoad` — the first three always, the last two only
- * while a transition is running.
+ * `src/tsl.ts` with `textureLoad` — all five every frame, whether or not the
+ * instance is transitioning (see {@link PACK_TEXELS}).
  *
  * | Texel                     | r              | g           | b           | a        |
  * | ------------------------- | -------------- | ----------- | ----------- | -------- |
@@ -445,9 +454,13 @@ interface VATClip extends VATClipDefaults {
  * `geometry.groups[].materialIndex`, giving one draw call per material.
  *
  * The typed array behind either texture's `image.data` is the bake's choice,
- * not part of this contract: `Float32Array` today, and a narrower encoding may
- * change it in a minor release. Move the buffer, hand it to {@link makeVATTexture};
- * do not read numbers out of it.
+ * not part of this contract, and it is not the same array on every layer: the
+ * position texture holds a `Uint16Array` of half-floats (#73), the rig texture
+ * a `Float32Array`, the normal texture a `Uint8Array` of octahedral pairs
+ * (#29), and a narrower encoding may change any of them again in a minor
+ * release. Move the buffer, hand it back to the builder for that layer —
+ * {@link makeVATTexture} or {@link makeVATNormalTexture} — and do not read
+ * numbers out of it.
  */
 interface VATBase {
     /**
@@ -465,30 +478,69 @@ interface VATBase {
     clips: VATClip[];
     /** Union of every baked frame's bounds; use as the geometry bounding box. */
     bounds: Box3;
-    /** Vertex count (texture width). */
+    /**
+     * Vertices in the merged geometry — the vertex encoding's texture width
+     * wherever they fit one row, which is every bake below the ceiling
+     * ({@link DeltaVAT.rowsPerFrame}).
+     */
     vertexCount: number;
-    /** Total frame rows across all clips (texture height). */
+    /**
+     * Total frames across all clips — the texture's height in rows, times
+     * {@link DeltaVAT.rowsPerFrame} under the vertex encoding. The unit every
+     * `startFrame` and `frames` in the clip table counts in.
+     */
     totalFrames: number;
 }
 /**
  * A VAT under the **vertex encoding**: a row holds where every vertex ended up,
  * as a position delta and, unless the bake was told to skip it, a normal. The
- * source-agnostic encoding (ADR-0008) and the default; the member every bake
- * produced before there was a second one (ADR-0018).
+ * source-agnostic encoding (ADR-0008), the member every bake produced before
+ * there was a second one (ADR-0018), and what the default falls back to where
+ * the rig encoding refuses an asset (ADR-0027).
  */
 interface DeltaVAT extends VATBase {
     /** Which encoding a row holds — the discriminant of {@link VAT}. */
     encoding: 'delta';
-    /** RGBA float texture of per-vertex position deltas (`x = vertex`, `y = frame`). */
+    /**
+     * `RGBA16F` texture of per-vertex position deltas (`x = vertex`, `y = frame`),
+     * eight bytes a texel — half of what RGBA float cost, for 0.061% of the delta
+     * and nothing at all at the rest pose (#73, ADR-0002's amendment). A
+     * half-float sampler hands the shader floats, so neither decode unpacks
+     * anything; a bake whose delta would pass half-float's 65 504 ceiling is
+     * refused rather than clipped.
+     */
     positionTexture: DataTexture;
     /**
-     * RGBA float texture of per-vertex absolute normals (`x = vertex`, `y = frame`),
-     * or `null` when the bake was told to skip it (`bakeNormals: false`) — halving
-     * the VAT for a crowd that never reads a normal. Neither decode path samples
-     * it when it is absent; a smooth-shaded lit material paired with such a VAT is
-     * refused rather than lit by its rest pose.
+     * `RG8` texture of per-vertex absolute normals (`x = vertex`, `y = frame`),
+     * each texel an octahedral unit vector in two unsigned bytes — a quarter of
+     * the position texel beside it, for ~0.95° of angular error (#29,
+     * `src/octahedral.ts`).
+     * Decode it with `decodeOctahedral`; both shaders do.
+     *
+     * `null` when the bake was told to skip it (`bakeNormals: false`) — dropping
+     * the layer for a crowd that never reads a normal. Neither decode path
+     * samples it when it is absent; a smooth-shaded lit material paired with such
+     * a VAT is refused rather than lit by its rest pose.
      */
     normalTexture: DataTexture | null;
+    /**
+     * Texture rows one frame takes (ADR-0030). `1` wherever the vertex count
+     * fits the bake's `maxTextureSize`, and then both layers are `vertexCount`
+     * wide and `totalFrames` tall, as every bake before this field was. Past it,
+     * a frame's vertices continue onto the next row: the fewest rows that hold
+     * them, `ceil(vertexCount / rowsPerFrame)` texels wide, and vertex `v` of
+     * frame `f` at column `v mod width`, row `f × rowsPerFrame + floor(v /
+     * width)`. Both decode paths read it; neither adds a line where it is `1`.
+     */
+    rowsPerFrame: number;
+    /**
+     * Why the default encoding fell back to this one (ADR-0029): the message of
+     * the rig encoding's refusal, naming what the rig could not store and where
+     * — an animated morph, its clip and its part, say. `null` where the vertex
+     * encoding was asked for by name (`encoding: 'delta'`). The bake prints
+     * nothing on a fallback; this is where the reason is kept.
+     */
+    fallback: string | null;
 }
 /**
  * A VAT under the **rig encoding** (ADR-0018): a row holds the posed rig — one

package/dist/{chunk-J5IEUGSB.js → chunk-OEKKEHRQ.js}

@@ -1,15 +1,44 @@
-import { FloatType, DataTexture, RGBAFormat, NearestFilter } from 'three';
+import { FloatType, DataTexture, RGBAFormat, RGFormat, UnsignedByteType, HalfFloatType, NearestFilter } from 'three';
 
 // src/vat-texture.ts
 var MAX_TEXTURE_SIZE = 16384;
-function makeVATTexture(data, width, height, type = FloatType) {
-  const tex = new DataTexture(data, width, height, RGBAFormat, type);
+var HALF_FLOAT_MAX = 65504;
+function vertexLayoutFor(vertexCount, totalFrames, maxTextureSize) {
+  const rowsPerFrame = Math.max(1, Math.ceil(vertexCount / maxTextureSize));
+  const width = vertexWidthOf({ vertexCount, rowsPerFrame });
+  const height = totalFrames * rowsPerFrame;
+  if (height > maxTextureSize) {
+    throw new Error(
+      `three-vat: totalFrames ${totalFrames} at ${rowsPerFrame} rows a frame is ${height} rows, which exceeds maxTextureSize ${maxTextureSize} \u2014 the vertex encoding spans each frame's ${vertexCount} vertices across ${rowsPerFrame} rows of ${width}; lower fps or bake fewer clips`
+    );
+  }
+  return { rowsPerFrame, width, height, frameStride: rowsPerFrame * width };
+}
+function vertexWidthOf({ vertexCount, rowsPerFrame }) {
+  return Math.ceil(vertexCount / rowsPerFrame);
+}
+function sampledExactly(tex) {
   tex.minFilter = NearestFilter;
   tex.magFilter = NearestFilter;
   tex.generateMipmaps = false;
   tex.needsUpdate = true;
   return tex;
 }
+function makeVATTexture(data, width, height, type = FloatType) {
+  const half = type === HalfFloatType;
+  const wanted = half ? Uint16Array : Float32Array;
+  if (!(data instanceof wanted)) {
+    throw new Error(
+      `three-vat: a ${half ? "HalfFloatType" : "FloatType"} texture is built from a ${wanted.name}, not a ${data.constructor.name} \u2014 the array and the type describe the same texels and have to agree`
+    );
+  }
+  return sampledExactly(new DataTexture(data, width, height, RGBAFormat, type));
+}
+function makeVATNormalTexture(data, width, height) {
+  const tex = new DataTexture(data, width, height, RGFormat, UnsignedByteType);
+  tex.unpackAlignment = 1;
+  return sampledExactly(tex);
+}
 
 // src/instance-playback.ts
 var PACK_TEXELS = {
@@ -74,24 +103,27 @@ function resolveVATFrame(instance, time) {
   const started = local >= 0;
   const finished = started && repetitions !== INFINITE_REPETITIONS && loops >= repetitions;
   let phase;
-  let wraps;
+  let looping;
   if (!started) {
     phase = 0;
-    wraps = false;
+    looping = false;
   } else if (finished) {
     phase = endMode === EndMode.Clamp ? 1 : 0;
-    wraps = false;
+    looping = false;
   } else if (loopMode === LoopMode.PingPong) {
-    const m = loops % 2;
+    const m = loops - 2 * Math.floor(loops * 0.5);
     phase = m < 1 ? m : 2 - m;
-    wraps = false;
+    looping = false;
   } else {
     phase = loops % 1;
-    wraps = true;
+    looping = true;
   }
-  const f = phase * (wraps ? frames : last);
+  const holds = looping && endMode === EndMode.Clamp && repetitions !== INFINITE_REPETITIONS && Math.floor(loops) + 1 >= repetitions;
+  const wraps = looping && !holds;
+  const f = phase * (looping ? frames : last);
   const f0 = Math.min(Math.floor(f), last);
-  const f1 = wraps ? (f0 + 1) % frames : Math.min(f0 + 1, last);
+  const next = f0 + 1;
+  const f1 = wraps ? next >= frames ? 0 : next : Math.min(next, last);
   const row = clip.startFrame + f0;
   const crossfade = crossfadeOf(instance);
   const elapsed = crossfade ? (time - instance.startTime) / crossfade.duration : 0;
@@ -123,9 +155,14 @@ function createVATPlaybackTexture(instances, options = {}) {
       "three-vat: a crowd needs at least one instance \u2014 a playback texture is one row per instance, and there is no zero-row texture to carry none. Pass a capacity to reserve rows for a crowd that has not spawned yet"
     );
   }
-  if (count > MAX_TEXTURE_SIZE) {
+  const ceiling = options.maxTextureSize ?? MAX_TEXTURE_SIZE;
+  if (count > ceiling) {
+    const [source, hint] = options.maxTextureSize === void 0 ? [
+      "MAX_TEXTURE_SIZE, the default when no maxTextureSize option is given",
+      " Pass getMaxTextureSize(renderer) as maxTextureSize to check against this GPU's own limit."
+    ] : ["the maxTextureSize option", ""];
     throw new Error(
-      `three-vat: ${count} rows of playback texture is past the ${MAX_TEXTURE_SIZE}-row ceiling \u2014 the playback texture holds one row per instance, so MAX_TEXTURE_SIZE is the instance ceiling.`
+      `three-vat: ${count} rows of playback texture is past the ${ceiling}-row ceiling of ${source} \u2014 the playback texture holds one row per instance, so the texture ceiling is the instance ceiling.` + hint
     );
   }
   const data = new Float32Array(count * PACK_STRIDE);
@@ -223,4 +260,4 @@ var RIG_TEXELS = {
 };
 var RIG_TEXELS_PER_SLOT = 2;
 
-export { EndMode, FORWARD_ONLY_REASON, INFINITE_REPETITIONS, LIBRARY_PLAYBACK_DEFAULTS, LoopMode, MAX_TEXTURE_SIZE, PACK_TEXELS, RIG_TEXELS, RIG_TEXELS_PER_SLOT, createVATPlaybackTexture, endsAt, makeVATTexture, resolveVATFrame, setVATInstance };
+export { EndMode, FORWARD_ONLY_REASON, HALF_FLOAT_MAX, INFINITE_REPETITIONS, LIBRARY_PLAYBACK_DEFAULTS, LoopMode, MAX_TEXTURE_SIZE, PACK_TEXELS, RIG_TEXELS, RIG_TEXELS_PER_SLOT, createVATPlaybackTexture, endsAt, makeVATNormalTexture, makeVATTexture, resolveVATFrame, setVATInstance, vertexLayoutFor, vertexWidthOf };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { AnimationClip, AnimationAction, Object3D, TypedArray, TextureDataType, DataTexture } from 'three';
-import { D as DeltaVAT, R as RigVAT, V as VAT } from './carrier-BxRuW47G.js';
-export { E as EndMode, I as INFINITE_REPETITIONS, L as LoopMode, a as VATBase, b as VATCarrier, c as VATClip, d as VATClipDefaults, e as VATClock, f as VATCrowd, g as VATFrame, h as VATInstance, i as VATOutgoingFrame, j as VATPlaybackState, k as VATPlaybackTexture, l as VATPlaybackTextureOptions, m as createVATPlaybackTexture, n as endsAt, r as resolveVATFrame, s as setVATInstance } from './carrier-BxRuW47G.js';
+import { AnimationClip, AnimationAction, Object3D, DataTexture, FloatType, HalfFloatType } from 'three';
+import { D as DeltaVAT, R as RigVAT, V as VAT } from './carrier-VLSJLgjX.js';
+export { E as EndMode, I as INFINITE_REPETITIONS, L as LoopMode, a as VATBase, b as VATCarrier, c as VATClip, d as VATClipDefaults, e as VATClock, f as VATCrowd, g as VATFrame, h as VATInstance, i as VATOutgoingFrame, j as VATPlaybackState, k as VATPlaybackTexture, l as VATPlaybackTextureOptions, m as createVATPlaybackTexture, n as endsAt, r as resolveVATFrame, s as setVATInstance } from './carrier-VLSJLgjX.js';
 
 /**
  * What {@link bakeVAT} takes for each animation: the clip itself, or an
@@ -15,17 +15,21 @@ interface BakeOptions {
     /** Sample rate in frames per second. Default `30`. */
     fps?: number;
     /**
-     * Largest texture dimension the target GPU accepts. Both VAT axes are checked
-     * against it: `vertexCount` (width) and `totalFrames` (height). Defaults to
+     * Largest texture dimension the target GPU accepts. Under the rig encoding
+     * both axes are checked against it: the rig's width and `totalFrames`. Under
+     * the vertex encoding a frame whose vertices outnumber it spans several rows
+     * instead of refusing (ADR-0030), so the height alone is checked: `totalFrames
+     * × rowsPerFrame`. Defaults to
      * {@link MAX_TEXTURE_SIZE}; pass the renderer's real limit to avoid baking a
-     * VAT that allocates on your desktop and fails on a phone.
+     * VAT that allocates on your desktop and fails on a phone, and so that a
+     * frame spans rows only where this GPU needs it to.
      */
     maxTextureSize?: number;
     /**
      * Bake the normal texture. Default `true`.
      *
-     * Turning it off halves the VAT — `verts x frames x 16 B x 2` becomes `x 1` —
-     * and is correct for exactly two material setups:
+     * Turning it off drops the normal layer — `verts x frames x (8 B + 2 B)`
+     * becomes `x 8 B` — and is correct for exactly two material setups:
      *
      * - **Unlit** (`MeshBasicMaterial`, and its node twin), which never reads a
      *   normal, so the texture was pure waste.
@@ -44,11 +48,16 @@ interface BakeOptions {
      */
     bakeNormals?: boolean;
     /**
-     * What a frame row holds (ADR-0018). Default `'delta'`.
+     * What a frame row holds (ADR-0018). Default `'auto'` (ADR-0027).
      *
+     * - **`'auto'`** — the rig encoding where the asset allows it, and the
+     *   vertex encoding where the rig encoding refuses it. Read `vat.encoding` to
+     *   learn which one a bake chose. The default since 4.0: the rig texture is
+     *   two orders of magnitude smaller, bakes in milliseconds, and decodes
+     *   faster where memory bandwidth is scarce, as on a phone.
      * - **`'delta'`** — the vertex encoding: where every vertex ended up, as a
      *   position delta and a normal. Source-agnostic — skinning, morph targets
-     *   and node animation alike — and the default.
+     *   and node animation alike.
      * - **`'rig'`** — the rig encoding: the posed rig, one **slot** per bone as a
      *   rotation, a translation and a uniform scale, skinned in the vertex shader
      *   from the rest-pose geometry. Two orders of magnitude smaller, no vertex
@@ -59,7 +68,24 @@ interface BakeOptions {
      *   node-animated part is one slot of weight one; parts reading the same
      *   bones through the same bind matrix share slots.
      */
-    encoding?: 'delta' | 'rig';
+    encoding?: 'auto' | 'delta' | 'rig';
+    /**
+     * Collapse materials that differ only in their flat colour into one, so the
+     * crowd draws once instead of once per material (ADR-0028). Default `false`.
+     *
+     * A material is **flat** when it has a `color`, no texture map of any kind,
+     * and `vertexColors` off. Two or more flat materials that agree on every
+     * other property — type, roughness, metalness, emissive, side, opacity and
+     * the rest — become one clone of the first, white, with `vertexColors` on,
+     * and each part's colour moves into the merged geometry's `color` attribute.
+     * A material that is not flat, or is the only one of its kind, is left
+     * exactly as it was. `vat.materials` therefore holds a material you did not
+     * create wherever a merge happened.
+     *
+     * Off by default because it is only ever right for flat-shaded assets: a
+     * textured character has nothing to collapse, and merging never guesses.
+     */
+    mergeFlatMaterials?: boolean;
 }
 /**
  * Bake animations into a VAT by sampling the posed subtree frame by frame on
@@ -111,16 +137,17 @@ interface BakeOptions {
  * Renderer-agnostic — touches no WebGL/WebGPU context — so it runs identically
  * at runtime, in a Web Worker, and in Node.
  *
- * All of that is the **vertex encoding**, the default. `encoding: 'rig'`
- * stores the posed rig instead — one slot per bone, two texels, skinned in the
- * vertex shader from the rest-pose geometry (ADR-0018) — under the same clip
- * table and the same playback contract, at a fraction of the memory; see
- * {@link BakeOptions.encoding} for what it refuses. Overloaded on the option's
- * literal, so a call that names no encoding, or the vertex encoding, still
- * holds the narrow {@link DeltaVAT} it always did.
+ * All of that is the **vertex encoding**. `encoding: 'rig'` stores the posed
+ * rig instead — one slot per bone, two texels, skinned in the vertex shader
+ * from the rest-pose geometry (ADR-0018) — under the same clip table and the
+ * same playback contract, at a fraction of the memory; see
+ * {@link BakeOptions.encoding} for what it refuses. The default is the rig
+ * where the asset allows it and the vertices where it does not (ADR-0027), so
+ * a bake that names no encoding returns the {@link VAT} union: narrow on
+ * `vat.encoding`, or name the encoding and get the narrow member back.
  */
-declare function bakeVAT(root: Object3D, animations: BakeInput[], options?: BakeOptions & {
-    encoding?: 'delta';
+declare function bakeVAT(root: Object3D, animations: BakeInput[], options: BakeOptions & {
+    encoding: 'delta';
 }): DeltaVAT;
 declare function bakeVAT(root: Object3D, animations: BakeInput[], options: BakeOptions & {
     encoding: 'rig';
@@ -135,21 +162,160 @@ declare function bakeVAT(root: Object3D, animations: BakeInput[], options?: Bake
  *   Node, and in a Web Worker) so it cannot query the real limit itself: pass
  *   `getMaxTextureSize(renderer)` from `three-vat/webgl` or `three-vat/tsl`
  *   whenever a renderer exists.
- * - **The instance ceiling**, because the playback texture is one row per
- *   instance (`createVATPlaybackTexture`, ADR-0016). That one takes no
- *   override, the crowd being built long after the bake was sized.
- *
- * Not a guarantee either way: plenty of mobile GPUs report 4096 or 8192, and
- * a crowd between that and this number is refused by the driver at upload
- * rather than here. The bake is where the real limit is worth passing, because
- * it is where the numbers get large.
+ * - **The instance ceiling's fallback**, because the playback texture is one
+ *   row per instance (`createVATPlaybackTexture`, ADR-0016), used when the
+ *   caller does not pass `maxTextureSize` to it or to `createVATMesh`. The
+ *   crowd is built beside the renderer, so the real limit is to hand there
+ *   (ADR-0022's amendment).
+ *
+ * Not a guarantee either way: plenty of mobile GPUs report 4096 or 8192. The
+ * playback texture names this number as its source when it falls back to it,
+ * so a crowd refused against it says where the real limit belongs.
  */
 declare const MAX_TEXTURE_SIZE = 16384;
 /**
- * Build a VAT `DataTexture` with the fixed sampling flags every path relies on:
- * RGBA, nearest filtering, no mipmaps. Frame interpolation is done manually in
- * the shader, so linear filtering must stay off.
+ * Build an RGBA VAT `DataTexture` — the position texture, the rig texture and
+ * the playback texture, which is every layer whose texel is four numbers that
+ * have to stay numbers.
+ *
+ * `type` says which kind of number, and the two callers that pass it disagree
+ * deliberately (ADR-0002's amendment):
+ *
+ * - **`HalfFloatType`, with a `Uint16Array`** — the position layer (#73). It
+ *   stores *deltas*, and half-float's error is proportional to what it holds:
+ *   0.061% of the delta, zero at the rest pose. Eight bytes a texel instead of
+ *   sixteen. Half-float tops out at 65 504, which is the one thing a delta can
+ *   exceed, so `bakeVAT` range-checks before it writes.
+ * - **`FloatType`, with a `Float32Array`** — the rig texture, whose texels are
+ *   a quaternion and an *absolute* translation, and the playback texture, whose
+ *   `startTime` in seconds does not survive half precision.
+ *
+ * `data` is one of those two arrays and not a `TypedArray`, deliberately: the
+ * normal texture is two unsigned bytes a texel ({@link makeVATNormalTexture}),
+ * and handing its buffer to this function would upload byte pairs as float32
+ * bits — a crowd rendering garbage rather than a call that failed. The narrow
+ * parameter turns that into a compile error, which is what a stale copy of the
+ * Web Worker recipe in `docs/usage.md` deserves. Pairing either array with the
+ * *other's* `type` is the same fault wearing a legal signature — half a texel
+ * read as a whole one — so that pairing is checked here and refused, rather
+ * than left to the driver.
+ */
+declare function makeVATTexture(data: Float32Array | Uint16Array, width: number, height: number, type?: typeof FloatType | typeof HalfFloatType): DataTexture;
+/**
+ * Build the normal texture: two unsigned bytes a texel, an octahedral unit
+ * vector (`src/octahedral.ts`, #29). `RG8` where the position layer is
+ * `RGBA16F`, because a normal is a direction and eight bits of each of two
+ * channels carry one to under a degree.
+ *
+ * `unpackAlignment` is the one thing this needs that the float builder does
+ * not: a row of `RG8` is `2 × width` bytes, so an odd vertex count makes every
+ * row an odd multiple of two, and the default alignment of 4 would have the
+ * driver start each row at the wrong offset. An RGBA half-float row is `8 ×
+ * width` bytes and an RGBA float row `16 × width` — a multiple of 4 at any
+ * width either way, which is why this never came up on those.
+ */
+declare function makeVATNormalTexture(data: Uint8Array, width: number, height: number): DataTexture;
+
+/** A vector the decode can write into — `THREE.Vector3` is one. */
+interface Vec3Out {
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * Write a normal into two bytes of a VAT normal texture's buffer, at `offset`
+ * and `offset + 1` — `(row * vertexCount + vertex) * 2` in a one-row bake,
+ * `deltaTexel` in `src/test-utils.ts` in any, for the texel of one
+ * vertex at one frame.
+ *
+ * Takes a direction, not a unit vector: the first step is a division by the L1
+ * norm, so the encoding is scale-invariant and an unnormalised normal encodes
+ * to the same texel its normalised twin does. A zero-length normal has no
+ * direction to divide out, and is written as the texel +Z lands on rather than
+ * as NaN — a degenerate vertex then shades like a flat one instead of turning
+ * the mesh black.
+ */
+declare function encodeOctahedral(x: number, y: number, z: number, out: Uint8Array | number[], offset: number): void;
+/**
+ * Decode a normal texel — the two bytes {@link encodeOctahedral} wrote — back
+ * to a unit vector. Pass `out` to decode a whole layer without allocating.
+ *
+ * `u` and `v` are the stored bytes, `0..255`; a sampler hands the shaders the
+ * same numbers already divided by 255, which is the `/ 255` below and the only
+ * difference between this and the two transcriptions of it.
+ *
+ * The fold is undone without a branch, by the identity that a negative `z`
+ * means exactly `|x| + |y| - 1` of overshoot to take back off both components,
+ * each toward its own zero. Branchless because #72 measured what a branch in
+ * the vertex decode costs: the compiler holds registers for the side it skips,
+ * and an idle crowd pays for them.
+ */
+declare function decodeOctahedral<T extends Vec3Out>(u: number, v: number, out: T): T;
+declare function decodeOctahedral(u: number, v: number): Vec3Out;
+
+/**
+ * What `bakeVATInWorker` talks to: a `Worker`, or anything else that posts and
+ * receives messages the same way (a `MessagePort`, say). The worker on the
+ * other end must call {@link serveVATBakes}.
+ */
+interface VATBakeWorker {
+    postMessage(message: unknown, transfer: Transferable[]): void;
+    addEventListener(type: 'message' | 'error', listener: (event: MessageEvent | ErrorEvent) => void): void;
+    removeEventListener(type: 'message' | 'error', listener: (event: MessageEvent | ErrorEvent) => void): void;
+}
+/**
+ * Where `serveVATBakes` listens: the worker's own global scope by default, or
+ * any other end of a message channel.
+ */
+interface VATBakeScope {
+    postMessage(message: unknown, transfer: Transferable[]): void;
+    addEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+    removeEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+}
+/**
+ * {@link bakeVAT}, in a Web Worker: the same arguments, the same VAT, and a
+ * page that keeps drawing frames while it bakes.
+ *
+ * ```ts
+ * // bake.worker.ts — the whole file
+ * import { serveVATBakes } from 'three-vat'
+ * serveVATBakes()
+ * ```
+ *
+ * ```ts
+ * // the page
+ * const worker = new Worker(new URL('./bake.worker.ts', import.meta.url), { type: 'module' })
+ * const vat = await bakeVATInWorker(worker, gltf.scene, gltf.animations, {
+ *   maxTextureSize: getMaxTextureSize(renderer),
+ * })
+ * ```
+ *
+ * The subtree is copied, not moved: the caller's scene is untouched, and a
+ * source geometry without normals is not given them as it would be by a bake
+ * on this thread. Materials never cross — the VAT comes back holding the
+ * caller's own, in `materialIndex` order. A refusal rejects the promise with
+ * the message `bakeVAT` would have thrown. One worker serves any number of
+ * bakes, one at a time. A track on what the bake does not read, such as a
+ * material's colour, stays on the page.
+ *
+ * What cannot be copied is refused before anything is sent: a bone outside
+ * the subtree, a keyframe track the bake reads that has a custom interpolant
+ * (glTF's cubic spline is carried), an attribute that is neither a
+ * `BufferAttribute` nor an interleaved one.
+ */
+declare function bakeVATInWorker(worker: VATBakeWorker, root: Object3D, animations: BakeInput[], options: BakeOptions & {
+    encoding: 'delta';
+}): Promise<DeltaVAT>;
+declare function bakeVATInWorker(worker: VATBakeWorker, root: Object3D, animations: BakeInput[], options: BakeOptions & {
+    encoding: 'rig';
+}): Promise<RigVAT>;
+declare function bakeVATInWorker(worker: VATBakeWorker, root: Object3D, animations: BakeInput[], options?: BakeOptions): Promise<VAT>;
+/**
+ * The worker's half of {@link bakeVATInWorker}: answer every bake the page
+ * sends, by calling `bakeVAT` here. Call it once, at the top of the worker
+ * module. Messages that are not bakes are left alone, so the worker may do
+ * other work besides. Returns a function that stops listening.
  */
-declare function makeVATTexture(data: TypedArray, width: number, height: number, type?: TextureDataType): DataTexture;
+declare function serveVATBakes(scope?: VATBakeScope): () => void;
 
-export { type BakeInput, type BakeOptions, DeltaVAT, MAX_TEXTURE_SIZE, RigVAT, VAT, bakeVAT, makeVATTexture };
+export { type BakeInput, type BakeOptions, DeltaVAT, MAX_TEXTURE_SIZE, RigVAT, VAT, type VATBakeScope, type VATBakeWorker, type Vec3Out, bakeVAT, bakeVATInWorker, decodeOctahedral, encodeOctahedral, makeVATNormalTexture, makeVATTexture, serveVATBakes };