three-vat 2.1.0 → 4.0.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 no vertex ceiling for a phone's 4096 to
+refuse. 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 is three `vec4`s — clip, playback, fade — in a
-**playback texture** keyed by the instance's logical index, not instanced
-attributes, which are indexed by the *drawn* slot:
+`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>
@@ -184,9 +188,8 @@ worker recipe, the draw-call arithmetic, and the primitives underneath
 <details>
 <summary><b>What it does not do</b></summary>
 
-No clip crossfade (an instance blends out of a frozen pose, not between two
-clips that are both playing), no LOD, no baking CLI or file
-format, no React/drei binding, glTF input only. Each is a decision rather than a
+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.

package/dist/{carrier-BXaLAPRO.d.ts → carrier-D4pkftSk.d.ts}

@@ -40,44 +40,20 @@ type EndMode = (typeof EndMode)[keyof typeof EndMode];
  */
 declare const INFINITE_REPETITIONS = -1;
 /**
- * The longest fade {@link setVATInstance} will honour, in seconds.
+ * One clip playing: which band, from when, how fast and under what policy.
  *
- * The cap exists because of what this fade *is*: one frozen pose of the
- * outgoing clip, blended away — not a second playback running alongside the
- * first. Over a tenth of a second that is invisible; over half a second the
- * instance visibly skates, because whatever it was doing stopped dead the
- * moment the transition began. A longer fade would not be a better fade, it
- * would be a more visible bug, so the number is clamped rather than trusted.
- *
- * Provisional, like the fade itself: a real two-clip crossfade (#30) replaces
- * both, and nothing else should be built on top of them.
- */
-declare const MAX_FADE_DURATION = 0.25;
-/**
- * The frozen pose a fade blends away from: one phase of the clip an instance
- * was playing when its animation changed, and the band that phase indexes.
- *
- * Not a second playback state — there is no start time and no speed here,
- * because nothing about it moves. That is the whole of the freeze, and the
- * whole of its limit; see {@link MAX_FADE_DURATION}.
- */
-interface VATFadeFrom {
-    /** First texture row of the outgoing clip's band. */
-    startFrame: number;
-    /** Rows in that band. */
-    frames: number;
-    /** The phase of that band the instance was at, in `[0, 1]`. */
-    phase: number;
-}
-/**
- * Per-instance playback state consumed by both decode paths.
+ * The unit the pack carries twice — as the animation an instance is playing,
+ * and as the one it is blending out of ({@link VATInstance.from}). Both are
+ * resolved by {@link resolveVATFrame} through the very same arithmetic, which
+ * is the whole difference between a crossfade and the pose freeze it replaced
+ * (ADR-0025): the outgoing half is a clip still *playing*, not a photograph.
  *
  * Every policy field is optional because the clip already answers it: a bake
  * handed a configured `AnimationAction` records the answer in the clip table
- * ({@link VATClipDefaults}), and an instance that says nothing inherits it. A
+ * ({@link VATClipDefaults}), and a state that says nothing inherits it. A
  * crowd of a thousand deaths says "once, clamped" once, at the bake.
  */
-interface VATInstance {
+interface VATPlaybackState {
     /**
      * The clip band to play, straight out of `vat.clips`. Its playback defaults
      * come along with it; a clip table assembled by hand may carry none, and then
@@ -119,19 +95,33 @@ interface VATInstance {
      * `false`; see {@link EndMode}.
      */
     endMode?: EndMode;
+}
+/**
+ * Per-instance playback state consumed by both decode paths: the clip this
+ * instance is playing, and — while it is transitioning — the one it is
+ * crossfading out of.
+ */
+interface VATInstance extends VATPlaybackState {
     /**
-     * The frozen outgoing pose to fade away from. Normally you do not write this
-     * yourself: {@link setVATInstance} freezes whatever the instance was playing
-     * and fills it in when you ask for a {@link fadeDuration}.
+     * The outgoing playback state to blend away from: a clip *still playing*, in
+     * every respect an instance except that it carries no transition of its own.
+     *
+     * Normally you do not write this yourself — {@link setVATInstance} reads the
+     * instance's current pack back, whole, and fills it in when you ask for a
+     * {@link fadeDuration}. Write it by hand when you are assembling a crowd the
+     * library does not build for you; what you pass is what is written.
      */
-    from?: VATFadeFrom;
+    from?: VATPlaybackState;
     /**
-     * Seconds to blend {@link from} away over, capped at {@link MAX_FADE_DURATION}.
-     * Wall-clock seconds from {@link startTime}: the clip's `speed` does not
-     * stretch a fade.
+     * Seconds to blend {@link from} away over. Uncapped, and wall-clock seconds
+     * from {@link startTime}: the incoming clip's `speed` does not stretch a
+     * transition.
+     *
+     * Zero, or absent, is a cut: no outgoing band is written. A negative or
+     * non-finite duration is refused when the instance is written.
      *
-     * Ignored without a `from` to fade away from — and at creation there is
-     * nothing to fade away from, so this is `setVATInstance`'s field in practice.
+     * Ignored without a `from` to blend away from — and at creation there is
+     * nothing to blend away from, so this is `setVATInstance`'s field in practice.
      */
     fadeDuration?: number;
 }
@@ -151,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. */
@@ -159,26 +150,39 @@ interface VATFrame {
     /** How far through the clip this is, in `[0, 1]` — what {@link row} is derived from. */
     phase: number;
     /**
-     * The frozen outgoing row a fade blends away from. Equal to {@link row} when
-     * the instance is not fading, so a reader that ignores {@link fade} — the
-     * demo's texture-panel cursors among them — never points at a row this
-     * instance is not sampling.
+     * The band this instance is blending out of, resolved at the same moment —
+     * or `null` when it is not transitioning, which is almost always. Not a
+     * weight of zero, so a reader with no interest in transitions ignores one
+     * field rather than testing one.
      */
-    fadeRow: number;
+    outgoing: VATOutgoingFrame | null;
+}
+/**
+ * The outgoing half of a crossfade: the very frame the outgoing clip would be
+ * showing if nothing had interrupted it, and how much of it is still showing.
+ *
+ * It is a {@link VATFrame} because it is one — resolved by
+ * {@link resolveVATFrame} from the outgoing playback state, through the same
+ * arithmetic, so an outgoing one-shot that runs out mid-transition clamps
+ * exactly as it would have. Its own `outgoing` is always `null`: the pack holds
+ * two bands, and the recursion is one level deep.
+ */
+interface VATOutgoingFrame extends VATFrame {
     /**
-     * How much of {@link fadeRow} is still showing: `1` at the moment of the
-     * write, falling to `0` across `fadeDuration`, and `0` for an instance that
-     * is not fading. The decode mixes the sampled clip toward the frozen pose by
-     * exactly this weight — the weight of the fade, not the fade itself, which is
-     * the pose-freeze fade `CONTEXT.md` names.
+     * How much of this band is still showing: `1` at the moment of the write,
+     * falling to `0` across `fadeDuration`, and `0` once the transition is over.
+     * Wall clock — `1 - clamp((time - startTime) / fadeDuration, 0, 1)` — so a
+     * half-speed incoming clip does not stretch the transition.
      */
-    fadeWeight: number;
+    weight: number;
 }
 /**
  * What the vertex shader computes, as a pure function of `(instance, time)` —
  * the **one definition** of the playback semantics. Both decode paths
- * transcribe it (`DECODE_PRELUDE` in src/webgl.ts, `vatDecode` in src/tsl.ts);
- * neither invents it.
+ * transcribe it — its band half in `vatBand` (src/webgl.ts) and `resolveBand`
+ * (src/tsl.ts), one function of a clip and playback texel pair, *called twice*
+ * where an instance is transitioning; its crossfade weight beside the call, in
+ * `vatRows` and `vatDecode` — and neither invents it.
  *
  * It exists in TypeScript because the arithmetic is otherwise reachable only
  * inside a GLSL string and a TSL node graph, neither of which CI can evaluate
@@ -191,7 +195,7 @@ interface VATFrame {
  */
 declare function resolveVATFrame(instance: VATInstance, time: number): VATFrame;
 /**
- * What carries the pack to the shader: one `DataTexture`, three texels wide,
+ * What carries the pack to the shader: one `DataTexture`, five texels wide,
  * one row per instance, read by the instance's *logical* index (ADR-0016).
  *
  * Held by the caller rather than hidden behind the geometry, because a
@@ -207,24 +211,64 @@ interface VATPlaybackTexture {
      * float, {@link PACK_WIDTH} texels wide.
      */
     texture: DataTexture;
-    /** Instances it carries — the rows of {@link texture}. */
+    /**
+     * Rows of {@link texture} — the crowd's **capacity**, which is what the
+     * decode indexes and what {@link setVATInstance} bounds-checks against.
+     *
+     * Not a live population: for a crowd that spawns and dies, most of these
+     * rows may be reserved and empty at any moment, and the library has no
+     * notion of which (ADR-0022). The caller owns the indices, because the
+     * carrier already hands that numbering out.
+     */
     count: number;
 }
+/**
+ * How a playback texture is sized when the instances it is handed are not the
+ * whole story.
+ */
+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 {@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,
  * before rendering, and bind the result into the decode — `createVATMesh` does
  * both for you.
  *
  * The layout below is the shared contract, spelled once in {@link PACK_TEXELS}.
- * Both decode paths read exactly these three texels of row `instanceIndex` —
- * `DECODE_PRELUDE` in `src/webgl.ts` with `texelFetch`, `texturePlayback` in
- * `src/tsl.ts` with `textureLoad`.
+ * 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` — all five every frame, whether or not the
+ * instance is transitioning (see {@link PACK_TEXELS}).
+ *
+ * | Texel                     | r              | g           | b           | a        |
+ * | ------------------------- | -------------- | ----------- | ----------- | -------- |
+ * | `x = 0` clip              | clip start row | clip frames | clip fps    | speed    |
+ * | `x = 1` playback          | start time     | loop mode   | repetitions | end mode |
+ * | `x = 2` crossfade         | fade duration  | 0           | 0           | 0        |
+ * | `x = 3` outgoing clip     | clip start row | clip frames | clip fps    | speed    |
+ * | `x = 4` outgoing playback | start time     | loop mode   | repetitions | end mode |
  *
- * | Texel            | r                   | g            | b             | a             |
- * | ---------------- | ------------------- | ------------ | ------------- | ------------- |
- * | `x = 0` clip     | clip start row      | clip frames  | clip fps      | speed         |
- * | `x = 1` playback | start time          | loop mode    | repetitions   | end mode      |
- * | `x = 2` fade     | from clip start row | from frames  | from phase    | fade duration |
+ * The outgoing pair is a full playback state — the same two texels, in the same
+ * order, with the same meaning — because that is the whole difference between a
+ * freeze and a crossfade (ADR-0025). The crossfade texel's three spare
+ * components are written as zero and read by nothing.
  *
  * **A texture, not three instanced attributes.** An attribute with divisor 1 is
  * indexed by the *drawn slot*, and the drawn slot stops being the instance the
@@ -233,25 +277,35 @@ interface VATPlaybackTexture {
  * (ADR-0016). A row keyed by the logical index is what three itself does for
  * the same problem, in `_matricesTexture`.
  *
- * **Three texels, not thirteen floats.** The move to a texture touched no
+ * **RGBA-shaped texels, not loose floats.** The move to a texture touched no
  * decode arithmetic, because the layout did not change with it: the pack was
- * already three RGBA-shaped `vec4`s (ADR-0009). Published 1.x is the other
- * story — five one-float attributes there, so a 1.x caller meets both changes
- * at once.
+ * already RGBA-shaped `vec4`s (ADR-0009). Published 1.x is the other story —
+ * five one-float attributes there, so a 1.x caller meets both changes at once.
  *
  * **`FloatType`, and it stays that way.** A `startTime` in seconds does not
- * survive half precision — one second of resolution at 2 048 s — so a narrower
- * encoding for the VAT textures does not reach this one.
+ * survive half precision — one second of resolution at 2 048 s — and there are
+ * now two of them per row, so a narrower encoding for the VAT textures does not
+ * reach this one.
  *
  * The policy fields, and the clip texel's speed, come from the instance where
  * it names them and from the clip's baked defaults where it does not — resolved
  * in the one place those tiers are spelled — and both decode paths read them as
- * {@link resolveVATFrame} defines them. The fade texel is written as zeroes,
- * which is what "not fading" is: a crowd being created has no pose to fade away
- * from. Fades belong to {@link setVATInstance}, where an instance's animation
- * changes and there is something to fade out of.
+ * {@link resolveVATFrame} defines them. The crossfade texel and the outgoing
+ * pair are written as zeroes, which is what "not transitioning" is: a crowd
+ * being created has no animation to blend away from. Transitions belong to
+ * {@link setVATInstance}, where an instance's animation changes and there is
+ * something to blend out of.
+ *
+ * **A crowd that spawns and dies gives a capacity** instead of a census
+ * ({@link VATPlaybackTextureOptions}, ADR-0022): the rows are reserved once,
+ * from the ceiling, and filled with {@link setVATInstance} as instances appear.
+ * The list may then be empty — a level that starts with nothing alive in it —
+ * and the reserved rows hold a first frame, held. The library allocates no
+ * indices and follows no `setInstanceCount`: the carrier already numbers the
+ * instances, and a texture does not grow in place. `docs/usage.md` carries both,
+ * with **row recycling** — the hazard of reusing a row an instance has died on.
  */
-declare function createVATPlaybackTexture(instances: VATInstance[]): VATPlaybackTexture;
+declare function createVATPlaybackTexture(instances: VATInstance[], options?: VATPlaybackTextureOptions): VATPlaybackTexture;
 /**
  * Change one instance's animation, after the crowd is built. The single write
  * the whole event-driven half of this library is made of: an enemy hit at
@@ -274,15 +328,21 @@ declare function createVATPlaybackTexture(instances: VATInstance[]): VATPlayback
  * one small write rather than a full re-upload. Everything else about the
  * instance — its matrix, its clip's defaults — is untouched. On the TSL path
  * the range is recorded and ignored: three's WebGPU backend re-uploads the
- * whole image on `needsUpdate`, which is 48 bytes per instance once per frame
+ * whole image on `needsUpdate`, which is 80 bytes per instance once per frame
  * in which anything changed (docs/usage.md says what that costs).
  *
- * Ask for a `fadeDuration` and the pose the instance is in *at `startTime`* is
- * frozen and blended away over that many wall-clock seconds, so the change does
- * not pop. It is a frozen pose and not a second playback: see
- * {@link MAX_FADE_DURATION} for what that costs and how far it can be pushed.
- * One pose, too — writing an instance that is *already* fading freezes the clip
- * it had switched to and drops the older pose, because the pack holds one.
+ * Ask for a `fadeDuration` and the animation the instance was playing **keeps
+ * playing**, blended away over that many wall-clock seconds from `startTime`,
+ * so the change is a transition rather than a pop (ADR-0025). Uncapped: a tenth
+ * of a second for a death, half a second for a walk into a run, and both clips
+ * move throughout. Zero, or none at all, is a cut.
+ *
+ * Two bands, and no more. Writing an instance that is *already* mid-transition
+ * replaces the outgoing band with the one it was switching to and drops the
+ * older band at whatever weight it still had — a pop proportional to how early
+ * the interruption came, and the one visible discontinuity a caller can
+ * produce. `startTime + fadeDuration` is when the transition ends, for a caller
+ * who would rather wait it out.
  *
  * A written instance is a pure function of the clock from here on, so what
  * happens *after* it is a matter of scheduling one more of these writes —
@@ -394,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 {
     /**
@@ -422,22 +486,43 @@ interface VATBase {
 /**
  * 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;
+    /**
+     * 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
@@ -512,4 +597,4 @@ interface VATCrowd {
  */
 type VATCarrier = InstancedMesh | BatchedMesh;
 
-export { type DeltaVAT as D, EndMode as E, INFINITE_REPETITIONS as I, LoopMode as L, MAX_FADE_DURATION as M, type RigVAT as R, type VAT as V, type VATBase as a, type VATCarrier as b, type VATClip as c, type VATClipDefaults as d, type VATClock as e, type VATCrowd as f, type VATFadeFrom as g, type VATFrame as h, type VATInstance as i, type VATPlaybackTexture as j, createVATPlaybackTexture as k, endsAt as l, resolveVATFrame as r, setVATInstance as s };
+export { type DeltaVAT as D, EndMode as E, INFINITE_REPETITIONS as I, LoopMode as L, type RigVAT as R, type VAT as V, type VATBase as a, type VATCarrier as b, type VATClip as c, type VATClipDefaults as d, type VATClock as e, type VATCrowd as f, type VATFrame as g, type VATInstance as h, type VATOutgoingFrame as i, type VATPlaybackState as j, type VATPlaybackTexture as k, type VATPlaybackTextureOptions as l, createVATPlaybackTexture as m, endsAt as n, resolveVATFrame as r, setVATInstance as s };