three-vat 2.1.0 → 3.0.0

package/README.md

@@ -148,7 +148,7 @@ 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
+`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:
 `addInstancedVATAttributes` is removed, `createVATPlaybackTexture(instances)`
@@ -184,9 +184,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-BxRuW47G.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.
      *
-     * 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.
+     * 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 blend away from — and at creation there is
+     * nothing to blend away from, so this is `setVATInstance`'s field in practice.
      */
     fadeDuration?: number;
 }
@@ -159,26 +149,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 +194,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 +210,56 @@ 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 `MAX_TEXTURE_SIZE`; 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;
+}
 /**
  * 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` — the first three always, the last two only
+ * while a transition is running.
  *
- * | 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 |
+ * | 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 |
+ *
+ * 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 +268,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 +319,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 —
@@ -512,4 +563,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 };

package/dist/{chunk-3PWAY6MD.js → chunk-J5IEUGSB.js}

@@ -15,9 +15,11 @@ function makeVATTexture(data, width, height, type = FloatType) {
 var PACK_TEXELS = {
   clip: 0,
   playback: 1,
-  fade: 2
+  crossfade: 2,
+  outgoingClip: 3,
+  outgoingPlayback: 4
 };
-var PACK_WIDTH = 3;
+var PACK_WIDTH = 5;
 var PACK_STRIDE = PACK_WIDTH * 4;
 var LoopMode = {
   /** Play the clip end to end, forever (or `repetitions` times). */
@@ -34,7 +36,6 @@ var EndMode = {
   Rewind: 1
 };
 var INFINITE_REPETITIONS = -1;
-var MAX_FADE_DURATION = 0.25;
 function defaultRepetitions(loopMode) {
   return loopMode === LoopMode.Repeat ? INFINITE_REPETITIONS : 1;
 }
@@ -56,15 +57,12 @@ function resolvedPlaybackOf(instance) {
     speed: instance.speed ?? clip.speed ?? LIBRARY_PLAYBACK_DEFAULTS.speed
   };
 }
-function fadeOf(instance) {
-  const duration = Math.min(instance.fadeDuration ?? 0, MAX_FADE_DURATION);
+function crossfadeOf(instance) {
   const from = instance.from;
-  if (!from || duration <= 0 || from.frames <= 0) return null;
-  return { from, duration };
-}
-function fadeRowOf(from) {
-  return from.startFrame + Math.max(Math.min(Math.floor(from.phase * from.frames), from.frames - 1), 0);
+  if (!from || !asksToBlend(instance)) return null;
+  return { from, duration: instance.fadeDuration };
 }
+var asksToBlend = (instance) => (instance.fadeDuration ?? 0) > 0;
 function resolveVATFrame(instance, time) {
   const { clip } = instance;
   const frames = clip.frames;
@@ -95,8 +93,8 @@ function resolveVATFrame(instance, time) {
   const f0 = Math.min(Math.floor(f), last);
   const f1 = wraps ? (f0 + 1) % frames : Math.min(f0 + 1, last);
   const row = clip.startFrame + f0;
-  const fading = fadeOf(instance);
-  const elapsed = fading ? (time - instance.startTime) / fading.duration : 0;
+  const crossfade = crossfadeOf(instance);
+  const elapsed = crossfade ? (time - instance.startTime) / crossfade.duration : 0;
   return {
     row,
     rowNext: clip.startFrame + f1,
@@ -104,50 +102,85 @@ function resolveVATFrame(instance, time) {
     wraps,
     finished,
     phase,
-    fadeRow: fading ? fadeRowOf(fading.from) : row,
-    fadeWeight: fading ? 1 - Math.min(Math.max(elapsed, 0), 1) : 0
+    outgoing: crossfade ? { ...resolveVATFrame(crossfade.from, time), weight: 1 - Math.min(Math.max(elapsed, 0), 1) } : null
   };
 }
-function createVATPlaybackTexture(instances) {
-  const count = instances.length;
+var RESERVED_ROW = {
+  clip: { startFrame: 0, frames: 1, fps: 1 },
+  startTime: 0,
+  speed: 0
+};
+function createVATPlaybackTexture(instances, options = {}) {
+  const live = instances.length;
+  const count = options.capacity ?? live;
+  if (count < live) {
+    throw new Error(
+      `three-vat: a capacity of ${count} cannot hold the ${live} instances it was given \u2014 capacity is the crowd ceiling, so it is at least the crowd you start with.`
+    );
+  }
   if (count < 1) {
     throw new Error(
-      "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"
+      "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) {
     throw new Error(
-      `three-vat: a crowd of ${count} instances needs ${count} rows of playback texture, 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 ${MAX_TEXTURE_SIZE}-row ceiling \u2014 the playback texture holds one row per instance, so MAX_TEXTURE_SIZE is the instance ceiling.`
     );
   }
   const data = new Float32Array(count * PACK_STRIDE);
-  for (let i = 0; i < count; i++) writePack(data, i, instances[i]);
+  for (let i = 0; i < count; i++) writePack(data, i, instances[i] ?? RESERVED_ROW);
   return { texture: makeVATTexture(data, PACK_WIDTH, count), count };
 }
 var FORWARD_ONLY_REASON = "a baked band plays forward from its own first row, so a negative speed would freeze it on that row rather than run it backwards \u2014 bake a reversed clip instead. A speed of 0 is a held first row, and is fine";
 var rowStart = (index) => index * PACK_STRIDE;
 var texelStart = (index, field) => rowStart(index) + field * 4;
-function writePack(data, index, instance) {
-  const clip = texelStart(index, PACK_TEXELS.clip);
-  const playback = texelStart(index, PACK_TEXELS.playback);
-  const fade = texelStart(index, PACK_TEXELS.fade);
-  const policy = resolvedPlaybackOf(instance);
+function checkedPolicyOf(state, index, what) {
+  const policy = resolvedPlaybackOf(state);
   if (policy.speed < 0) {
-    throw new Error(`three-vat: instance ${index} has speed ${policy.speed}; ${FORWARD_ONLY_REASON}.`);
+    throw new Error(`three-vat: ${what} ${index} has speed ${policy.speed}; ${FORWARD_ONLY_REASON}.`);
   }
-  data[clip] = instance.clip.startFrame;
-  data[clip + 1] = instance.clip.frames;
-  data[clip + 2] = instance.clip.fps;
+  return policy;
+}
+function putBand(data, index, at, state, policy) {
+  const clip = texelStart(index, at.clip);
+  const playback = texelStart(index, at.playback);
+  data[clip] = state.clip.startFrame;
+  data[clip + 1] = state.clip.frames;
+  data[clip + 2] = state.clip.fps;
   data[clip + 3] = policy.speed;
-  data[playback] = instance.startTime;
+  data[playback] = state.startTime;
   data[playback + 1] = policy.loopMode;
   data[playback + 2] = policy.repetitions;
   data[playback + 3] = policy.endMode;
-  const fading = fadeOf(instance);
-  data[fade] = fading ? fading.from.startFrame : 0;
-  data[fade + 1] = fading ? fading.from.frames : 0;
-  data[fade + 2] = fading ? fading.from.phase : 0;
-  data[fade + 3] = fading ? fading.duration : 0;
+}
+var LIVE_PAIR = { clip: PACK_TEXELS.clip, playback: PACK_TEXELS.playback };
+var OUTGOING_PAIR = { clip: PACK_TEXELS.outgoingClip, playback: PACK_TEXELS.outgoingPlayback };
+function checkedCrossfadeOf(instance, index) {
+  const duration = instance.fadeDuration;
+  if (duration !== void 0 && !(Number.isFinite(duration) && duration >= 0)) {
+    throw new Error(
+      `three-vat: instance ${index} has fadeDuration ${duration}; a transition lasts a finite number of seconds, and 0 (or no fadeDuration at all) is the cut.`
+    );
+  }
+  return crossfadeOf(instance);
+}
+function writePack(data, index, instance) {
+  const crossfade = checkedCrossfadeOf(instance, index);
+  const live = checkedPolicyOf(instance, index, "instance");
+  const outgoing = crossfade ? { state: crossfade.from, policy: checkedPolicyOf(crossfade.from, index, "the outgoing band of instance") } : null;
+  const crossfadeTexel = texelStart(index, PACK_TEXELS.crossfade);
+  putBand(data, index, LIVE_PAIR, instance, live);
+  if (outgoing) putBand(data, index, OUTGOING_PAIR, outgoing.state, outgoing.policy);
+  else clearTexels(data, index, OUTGOING_PAIR);
+  data[crossfadeTexel] = crossfade ? crossfade.duration : 0;
+  data[crossfadeTexel + 1] = 0;
+  data[crossfadeTexel + 2] = 0;
+  data[crossfadeTexel + 3] = 0;
+}
+function clearTexels(data, index, at) {
+  data.fill(0, texelStart(index, at.clip), texelStart(index, at.clip) + 4);
+  data.fill(0, texelStart(index, at.playback), texelStart(index, at.playback) + 4);
 }
 function readPack(data, index) {
   const clip = texelStart(index, PACK_TEXELS.clip);
@@ -163,35 +196,17 @@ function readPack(data, index) {
 }
 function assertInstance(playback, index) {
   if (!Number.isInteger(index) || index < 0 || index >= playback.count) {
-    throw new Error(`three-vat: instance ${index} is outside this crowd of ${playback.count}`);
+    throw new Error(`three-vat: instance ${index} is outside this crowd's ${playback.count} rows`);
   }
 }
 function setVATInstance(playback, index, instance) {
   assertInstance(playback, index);
   const data = playback.texture.image.data;
-  const fading = instance.from === void 0 && (instance.fadeDuration ?? 0) > 0 ? { ...instance, from: freezeOf(data, index, instance.startTime) } : instance;
-  writePack(data, index, fading);
+  const transitioning = instance.from === void 0 && asksToBlend(instance) ? { ...instance, from: readPack(data, index) } : instance;
+  writePack(data, index, transitioning);
   playback.texture.addUpdateRange(rowStart(index), PACK_STRIDE);
   playback.texture.needsUpdate = true;
 }
-function freezeOf(data, index, time) {
-  const outgoing = readPack(data, index);
-  const { row } = resolveVATFrame(outgoing, time);
-  return {
-    startFrame: outgoing.clip.startFrame,
-    frames: outgoing.clip.frames,
-    // The row the instance is actually displaying at that moment — so a fade
-    // out of a finished one-shot freezes the end pose it was holding, not the
-    // first row of a clip it stopped playing seconds ago.
-    //
-    // Named as the phase at the *centre* of that row rather than the playback
-    // phase itself, because {@link fadeRowOf} is what reads it back and the two
-    // do not spread a phase the same way: a bouncing ping-pong is up to a row
-    // apart between them, and rounding in a shader could cost another. Half a
-    // row of slack costs nothing and lands all three decodes on this row.
-    phase: (row - outgoing.clip.startFrame + 0.5) / outgoing.clip.frames
-  };
-}
 function endsAt(instance) {
   const { repetitions, speed } = resolvedPlaybackOf(instance);
   if (repetitions === INFINITE_REPETITIONS || speed <= 0) return null;
@@ -208,4 +223,4 @@ var RIG_TEXELS = {
 };
 var RIG_TEXELS_PER_SLOT = 2;
 
-export { EndMode, FORWARD_ONLY_REASON, INFINITE_REPETITIONS, LIBRARY_PLAYBACK_DEFAULTS, LoopMode, MAX_FADE_DURATION, MAX_TEXTURE_SIZE, PACK_TEXELS, RIG_TEXELS, RIG_TEXELS_PER_SLOT, createVATPlaybackTexture, endsAt, makeVATTexture, resolveVATFrame, setVATInstance };
+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 };

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-BXaLAPRO.js';
-export { E as EndMode, I as INFINITE_REPETITIONS, L as LoopMode, M as MAX_FADE_DURATION, a as VATBase, b as VATCarrier, c as VATClip, d as VATClipDefaults, e as VATClock, f as VATCrowd, g as VATFadeFrom, h as VATFrame, i as VATInstance, j as VATPlaybackTexture, k as createVATPlaybackTexture, l as endsAt, r as resolveVATFrame, s as setVATInstance } from './carrier-BXaLAPRO.js';
+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';
 
 /**
  * What {@link bakeVAT} takes for each animation: the clip itself, or an

package/dist/index.js

@@ -1,5 +1,5 @@
-import { LoopMode, MAX_TEXTURE_SIZE, makeVATTexture, RIG_TEXELS_PER_SLOT, RIG_TEXELS, LIBRARY_PLAYBACK_DEFAULTS, FORWARD_ONLY_REASON, INFINITE_REPETITIONS } from './chunk-3PWAY6MD.js';
-export { EndMode, INFINITE_REPETITIONS, LoopMode, MAX_FADE_DURATION, MAX_TEXTURE_SIZE, createVATPlaybackTexture, endsAt, makeVATTexture, resolveVATFrame, setVATInstance } from './chunk-3PWAY6MD.js';
+import { LoopMode, MAX_TEXTURE_SIZE, makeVATTexture, RIG_TEXELS_PER_SLOT, RIG_TEXELS, LIBRARY_PLAYBACK_DEFAULTS, FORWARD_ONLY_REASON, INFINITE_REPETITIONS } from './chunk-J5IEUGSB.js';
+export { EndMode, INFINITE_REPETITIONS, LoopMode, MAX_TEXTURE_SIZE, createVATPlaybackTexture, endsAt, makeVATTexture, resolveVATFrame, setVATInstance } from './chunk-J5IEUGSB.js';
 import { LoopRepeat, LoopOnce, LoopPingPong, Matrix4, AnimationMixer, Box3, Vector4, Vector3, Sphere, Quaternion, BufferGeometry, BufferAttribute, AdditiveAnimationBlendMode, PropertyBinding } from 'three';
 
 var LOOP_MODES = /* @__PURE__ */ new Map([