three-vat 4.1.0 → 4.2.0

package/dist/tsl.d.ts

@@ -1,5 +1,6 @@
 import { Node } from 'three/webgpu';
-import { e as VATClock, k as VATPlaybackTexture, b as VATCarrier, V as VAT, h as VATInstance, f as VATCrowd } from './carrier-VLSJLgjX.js';
+import { V as VATCarrier } from './carrier-DmKhB4QL.js';
+import { V as VATClock, a as VATPlaybackTexture, b as VAT, c as VATInstance, d as VATCrowd } from './types-CDPXKe0_.js';
 import 'three';
 
 /**

package/dist/tsl.js

@@ -1,5 +1,5 @@
 import { isBatchedCarrier, assertVATCarrier, assertBakedNormal } from './chunk-I4STYOD5.js';
-import { INFINITE_REPETITIONS, LoopMode, EndMode, createVATPlaybackTexture, PACK_TEXELS, RIG_TEXELS, vertexWidthOf, RIG_TEXELS_PER_SLOT } from './chunk-OEKKEHRQ.js';
+import { INFINITE_REPETITIONS, LoopMode, EndMode, createVATPlaybackTexture, PACK_TEXELS, RIG_TEXELS, vertexWidthOf, RIG_TEXELS_PER_SLOT } from './chunk-4IKOXUSX.js';
 import { InstancedMesh } from 'three';
 import { uniform, Fn, positionLocal, normalLocal, tangentLocal, positionGeometry, batch, instancedMesh, float, bool, int, vertexIndex, attribute, mat3, tangentGeometry, normalGeometry, vec4, batchIndirectIndex, instanceIndex, hash, mix, textureLoad, ivec2, dot, mat4, vec3 } from 'three/tsl';
 
@@ -20,6 +20,7 @@ function texturePlayback(texture, instance) {
       packTexel(texture, PACK_TEXELS.playback, instance)
     ),
     crossfadeDuration: crossfade.x,
+    crossfadeStart: crossfade.y,
     outgoing: outgoingBand(
       packTexel(texture, PACK_TEXELS.outgoingClip, instance),
       packTexel(texture, PACK_TEXELS.outgoingPlayback, instance)
@@ -73,7 +74,7 @@ function hashedPlayback(clip, desync, instance) {
       endMode: float(clip.endMode)
     }
   };
-  return { live, crossfadeDuration: float(0), outgoing: live };
+  return { live, crossfadeDuration: float(0), crossfadeStart: live.playback.startTime, outgoing: live };
 }
 function vatNodes(vat, options = {}) {
   const { time = uniform(0), carrier } = options;
@@ -98,25 +99,27 @@ function vatNodes(vat, options = {}) {
 function resolveBand(clip, playback, time) {
   const frames = clip.frames;
   const last = frames.sub(1);
-  const local = time.sub(playback.startTime).mul(clip.speed);
-  const loops = local.div(clip.duration);
+  const reversed = clip.speed.lessThan(0);
+  const local = time.sub(playback.startTime).mul(clip.speed.abs());
+  const loops = local.max(0).div(clip.duration);
   const started = local.greaterThanEqual(0);
   const finished = started.and(playback.repetitions.notEqual(INFINITE_REPETITIONS)).and(loops.greaterThanEqual(playback.repetitions));
   const isPingPong = playback.loopMode.equal(LoopMode.PingPong);
   const bounce = loops.sub(loops.mul(0.5).floor().mul(2));
   const pingPongPhase = bounce.lessThan(1).select(bounce, float(2).sub(bounce));
   const endPhase = playback.endMode.equal(EndMode.Clamp).select(float(1), float(0));
-  const phase = started.select(
-    finished.select(endPhase, isPingPong.select(pingPongPhase, loops.fract())),
-    float(0)
-  );
-  const looping = started.select(
-    finished.select(bool(false), isPingPong.select(bool(false), bool(true))),
-    bool(false)
-  );
-  const holds = looping.and(playback.endMode.equal(EndMode.Clamp)).and(playback.repetitions.notEqual(INFINITE_REPETITIONS)).and(loops.floor().add(1).greaterThanEqual(playback.repetitions));
+  const cascade = finished.select(endPhase, isPingPong.select(pingPongPhase, loops.fract()));
+  const looping = finished.select(bool(false), isPingPong.select(bool(false), bool(true)));
+  const forwardHolds = playback.endMode.equal(EndMode.Clamp).and(loops.floor().add(1).greaterThanEqual(playback.repetitions));
+  const holds = looping.and(playback.repetitions.notEqual(INFINITE_REPETITIONS)).and(reversed.select(loops.lessThan(1), forwardHolds));
   const wraps = looping.and(holds.not());
-  const f = phase.mul(looping.select(frames, last));
+  const mirrored = float(1).sub(cascade);
+  const phase = reversed.select(
+    wraps.and(mirrored.greaterThanEqual(1)).select(float(0), mirrored),
+    cascade
+  );
+  const spread = phase.mul(looping.select(frames, last));
+  const f = holds.select(spread.min(last), spread);
   const f0 = f.floor().min(last);
   const next = f0.add(1);
   const f1 = wraps.select(next.greaterThanEqual(frames).select(float(0), next), next.min(last));
@@ -135,7 +138,7 @@ function vatDecode(vat, options = {}) {
   const instance = instanceIdOf(carrier);
   const playback = playbackTexture ? texturePlayback(playbackTexture.texture, instance) : hashedPlayback(clipAt(vat, clipIndex), desync, instance);
   const live = resolveBand(playback.live.clip, playback.live.playback, time);
-  const elapsed = time.sub(playback.live.playback.startTime);
+  const elapsed = time.sub(playback.crossfadeStart);
   const duration = playback.crossfadeDuration;
   const weight = duration.greaterThan(0).select(
     float(1).sub(elapsed.div(duration).clamp(0, 1)),

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

@@ -1,4 +1,4 @@
-import { DataTexture, BufferGeometry, Material, Box3, InstancedMesh, BatchedMesh } from 'three';
+import { DataTexture, BufferGeometry, Material, Box3, InstancedMesh } from 'three';
 
 /**
  * How an instance repeats its clip — the numbers `THREE.LoopRepeat`,
@@ -70,10 +70,14 @@ interface VATPlaybackState {
      */
     startTime: number;
     /**
-     * Playback rate multiplier, `>= 0`. Defaults to the clip's speed, then to
-     * `1`. A negative rate is refused when the instance is written: a VAT plays
-     * forward, and a clip that must run backwards is baked as a reversed clip.
-     * `0` is legal — the instance holds its clip's first row.
+     * Playback rate multiplier. Defaults to the clip's speed, then to `1`.
+     *
+     * A negative rate plays the band backwards at its magnitude, with nothing
+     * baked for it (ADR-0033): the pose at every moment is the one forward
+     * playback shows at the mirrored point of the clip, so a reversed one-shot
+     * starts on its last frame, and the end modes read in the direction of play
+     * — `Clamp` holds the pose it stopped on, `Rewind` returns to the one it
+     * started from. `0` holds the clip's first row, and is not reversed.
      */
     speed?: number;
     /** How the clip repeats. Defaults to the clip's, then {@link LoopMode.Repeat}. */
@@ -114,7 +118,7 @@ interface VATInstance extends VATPlaybackState {
     from?: VATPlaybackState;
     /**
      * Seconds to blend {@link from} away over. Uncapped, and wall-clock seconds
-     * from {@link startTime}: the incoming clip's `speed` does not stretch a
+     * from {@link fadeStart}: the incoming clip's `speed` does not stretch a
      * transition.
      *
      * Zero, or absent, is a cut: no outgoing band is written. A negative or
@@ -124,6 +128,18 @@ interface VATInstance extends VATPlaybackState {
      * nothing to blend away from, so this is `setVATInstance`'s field in practice.
      */
     fadeDuration?: number;
+    /**
+     * The clock time, in seconds, at which the blend out of {@link from} began.
+     * Defaults to {@link startTime}, which is when every transition you write
+     * yourself begins, so you normally leave it out: it is normally written by a
+     * turn, whose live band's start time is fixed by pose continuity and cannot
+     * also place the blend (ADR-0036).
+     *
+     * Moves the weight and nothing else: both bands resolve exactly as they
+     * would without it. A non-finite start is refused when the instance is
+     * written.
+     */
+    fadeStart?: number;
 }
 /**
  * Where in its VAT an instance is at a given moment: the two frame rows to
@@ -139,10 +155,11 @@ interface VATFrame {
     mix: number;
     /**
      * 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
+     * True only while a clip is genuinely looping, or scheduled to start doing so: 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 — nor, across its final repetition, may any
-     * clip that ends by clamping (#88).
+     * clip that ends by clamping (#88), nor a reversed finite play across its
+     * first interval (ADR-0033).
      */
     wraps: boolean;
     /** Whether the repetitions have run out and the instance is holding an end pose. */
@@ -171,8 +188,9 @@ interface VATOutgoingFrame extends VATFrame {
     /**
      * 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.
+     * Wall clock — `1 - clamp((time - fadeStart) / fadeDuration, 0, 1)`, where
+     * `fadeStart` defaults to the live `startTime` — so a half-speed incoming
+     * clip does not stretch the transition.
      */
     weight: number;
 }
@@ -261,14 +279,16 @@ interface VATPlaybackTextureOptions {
  * | ------------------------- | -------------- | ----------- | ----------- | -------- |
  * | `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 = 2` crossfade         | fade duration  | fade start  | 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.
+ * freeze and a crossfade (ADR-0025). The crossfade texel's `g` is the blend
+ * start, the instance's `fadeStart` or else its start time, so every write
+ * fills it (ADR-0036); its two 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
@@ -290,9 +310,10 @@ interface VATPlaybackTextureOptions {
  * 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 crossfade texel and the outgoing
+ * {@link resolveVATFrame} defines them. The crossfade duration 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
+ * being created has no animation to blend away from. The blend start beside
+ * the duration is filled anyway, as on every write. Transitions belong to
  * {@link setVATInstance}, where an instance's animation changes and there is
  * something to blend out of.
  *
@@ -332,8 +353,9 @@ declare function createVATPlaybackTexture(instances: VATInstance[], options?: VA
  * in which anything changed (docs/usage.md says what that costs).
  *
  * 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
+ * playing**, blended away over that many wall-clock seconds from `startTime`
+ * (or from a `fadeStart`, which a turn writes), so the change is a transition
+ * rather than a pop (ADR-0025, ADR-0036). 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.
  *
@@ -341,8 +363,9 @@ declare function createVATPlaybackTexture(instances: VATInstance[], options?: VA
  * 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.
+ * produce. `startTime + fadeDuration` is when the transition ends — or
+ * `fadeStart + fadeDuration`, where one is written — 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 —
@@ -355,10 +378,62 @@ declare function createVATPlaybackTexture(instances: VATInstance[], options?: VA
  * to — and the playback texture is the object such a caller holds (ADR-0016).
  */
 declare function setVATInstance(playback: VATPlaybackTexture, index: number, instance: VATInstance): void;
+/**
+ * Turn one instance round at the pose it is showing (ADR-0036): from `time`
+ * on, it retraces its path, showing at `time + x` the pose it showed at
+ * `time − x`. A walker backs up; a door halfway open closes from halfway.
+ *
+ * ```ts
+ * // the moment the player lets go — and nothing per frame afterwards
+ * const back = turnVATInstance(playback, doorId, time.value)
+ * const shut = endsAt(back) // when it is closed again, or null if endless
+ * ```
+ *
+ * The row is read back out of the playback texture, so there is no CPU copy
+ * of the instance to keep. The turned instance is written through the same
+ * pack writer as {@link setVATInstance}, only its row is flagged for upload,
+ * and it is returned so {@link endsAt} can schedule what comes next.
+ *
+ * - A play with a count runs back to where it began and holds that pose. It
+ *   is written with `Clamp` whatever its end mode, because a `Rewind` would
+ *   snap back to the pose it turned at — so a second turn gives back the path
+ *   but not a `Rewind`, which the pack does not remember.
+ * - An endless play has no beginning, only a desync start time, and retraces
+ *   endlessly.
+ * - A turn retraces motion, never waiting. A finished play turns from the
+ *   moment it finished, not from the end of its hold — and from the pose its
+ *   path finished on, which is not the one `Clamp` holds for a fractional
+ *   count or an even ping-pong, so those jump back onto their path. A play finished on the
+ *   pose it started from (`Rewind`), or still waiting for its start time, has
+ *   nothing to retrace and holds where it is, for good.
+ * - Direction is the way the pose is moving. For a ping-pong the turn chooses
+ *   the sign, the count and the start time that reproduce the retraced path,
+ *   an even count included. The speed's magnitude is kept.
+ *
+ * Distinct from reverse playback, a negative `speed` written with
+ * {@link setVATInstance}, which plays a clip backwards from its start rather
+ * than from where the instance is.
+ *
+ * A turn does not ease: the pose is continuous and the velocity reverses at
+ * once, as three's `timeScale = -timeScale` does.
+ *
+ * An instance mid-crossfade retraces the blend too (#120). The weight flows
+ * back toward the clip it was leaving: that clip, retraced, is the live band
+ * of what the turn writes, the clip it was entering, retraced, is its `from`,
+ * and a `fadeStart` places the blend to end when the retrace passes the
+ * moment the original began. From then on it plays the clip it was leaving,
+ * retraced, alone, and `endsAt` answers for that. Within the blend both bands
+ * are mirrored whole, so a band that had finished on `Clamp` holds as long
+ * again before it retraces. Not a band finished on `Rewind`, which holds its
+ * start pose for good, nor one clamped off its path, which jumps back onto
+ * it, both as they would alone. A transition already over is dropped.
+ */
+declare function turnVATInstance(playback: VATPlaybackTexture, index: number, time: number): VATInstance;
 /**
  * The exact clock time this instance stops animating — when
  * {@link resolveVATFrame} first reports `finished` — or `null` for an animation
- * that never gets there: an endless loop, or a speed of zero.
+ * that never gets there: an endless loop, or a speed of zero. The same moment
+ * for `speed: -1` as for `speed: 1`.
  *
  * This is what makes chaining one clip to the next a single scheduled write
  * rather than a per-frame poll:
@@ -412,9 +487,9 @@ interface VATClipDefaults {
      */
     endMode: EndMode;
     /**
-     * Playback rate, from the action's `timeScale`. `>= 0`: a band is sampled
-     * forward from its own first row, so a negative rate is refused at the bake
-     * rather than held on that row for ever. `0` is a held first row, on purpose.
+     * Playback rate, from the action's `timeScale`. A negative rate plays the
+     * band backwards, as it does on an instance (ADR-0033). `0` is a held first
+     * row, on purpose.
      */
     speed: number;
 }
@@ -605,14 +680,4 @@ interface VATCrowd {
     playback: VATPlaybackTexture;
 }
 
-/**
- * A mesh a VAT crowd can ride.
- *
- * `InstancedMesh` is what `createVATMesh` builds on either path.
- * `BatchedMesh` is reached through the primitives, and buys per-instance
- * frustum culling and depth sorting from three.js itself — see
- * docs/usage.md, which also says what it does *not* buy.
- */
-type VATCarrier = InstancedMesh | BatchedMesh;
-
-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 };
+export { type DeltaVAT as D, EndMode as E, INFINITE_REPETITIONS as I, LoopMode as L, type RigVAT as R, type VATClock as V, type VATPlaybackTexture as a, type VAT as b, type VATInstance as c, type VATCrowd as d, type VATBase as e, type VATClip as f, type VATClipDefaults as g, type VATFrame as h, type VATOutgoingFrame as i, type VATPlaybackState as j, type VATPlaybackTextureOptions as k, createVATPlaybackTexture as l, endsAt as m, resolveVATFrame as r, setVATInstance as s, turnVATInstance as t };

package/dist/webgl.d.ts

@@ -1,5 +1,6 @@
 import { IUniform, MeshDepthMaterial, WebGLRenderer, Material } from 'three';
-import { b as VATCarrier, V as VAT, k as VATPlaybackTexture, h as VATInstance, f as VATCrowd } from './carrier-VLSJLgjX.js';
+import { V as VATCarrier } from './carrier-DmKhB4QL.js';
+import { b as VAT, a as VATPlaybackTexture, c as VATInstance, d as VATCrowd } from './types-CDPXKe0_.js';
 
 /**
  * The real maximum texture dimension this GPU accepts, for

package/dist/webgl.js

@@ -1,5 +1,5 @@
 import { assertBakedNormal, assertVATCarrier, isBatchedCarrier } from './chunk-I4STYOD5.js';
-import { PACK_TEXELS, EndMode, LoopMode, RIG_TEXELS_PER_SLOT, RIG_TEXELS, INFINITE_REPETITIONS, createVATPlaybackTexture, vertexWidthOf } from './chunk-OEKKEHRQ.js';
+import { PACK_TEXELS, EndMode, LoopMode, RIG_TEXELS_PER_SLOT, RIG_TEXELS, INFINITE_REPETITIONS, createVATPlaybackTexture, vertexWidthOf } from './chunk-4IKOXUSX.js';
 import { MeshDepthMaterial, RGBADepthPacking, InstancedMesh, MeshDistanceMaterial, Material } from 'three';
 
 function getMaxTextureSize(renderer) {
@@ -40,7 +40,7 @@ var ROW_PRELUDE = (
   };
 
   // resolveVATFrame for one (clip texel, playback texel) pair, branch for
-  // branch: not started, finished, ping-pong, repeat \u2014 the resolver's own
+  // branch: finished, ping-pong, repeat \u2014 the resolver's own
   // order, each case falling out into the shared phase-to-row arithmetic below
   // rather than returning early, so all of them land on the same two rows.
   //
@@ -53,9 +53,12 @@ var ROW_PRELUDE = (
     float duration = frames / vatClip.z;
     // Local time: how far into its own animation this instance is. A start time
     // in the past is what desyncs a crowd; a start time in the future has not
-    // begun, which is not the same thing as having finished.
-    float local = ( uVatTime - vatPlayback.x ) * vatClip.w;
-    float loops = local / duration;
+    // begun, which is not the same thing as having finished. The speed's sign is
+    // the direction and its magnitude the rate (ADR-0033).
+    bool reversed = vatClip.w < 0.0;
+    float local = ( uVatTime - vatPlayback.x ) * abs( vatClip.w );
+    // Not yet started sits on the pose its start time will show.
+    float loops = max( local, 0.0 ) / duration;
     float repetitions = vatPlayback.z;
 
     bool started = local >= 0.0;
@@ -63,10 +66,7 @@ var ROW_PRELUDE = (
 
     float phase;
     bool looping;
-    if ( !started ) {
-      phase = 0.0;
-      looping = false;
-    } else if ( finished ) {
+    if ( finished ) {
       // Held at an end pose, and in neither case sampling past it.
       phase = vatPlayback.w == ${glslFloat(EndMode.Clamp)} ? 1.0 : 0.0;
       looping = false;
@@ -81,11 +81,20 @@ var ROW_PRELUDE = (
     }
 
     // Except across the final repetition of a clip that clamps, which holds its
-    // last row rather than blending back toward its first (#88).
-    bool holds = looping && vatPlayback.w == ${glslFloat(EndMode.Clamp)} && repetitions != ${glslFloat(INFINITE_REPETITIONS)} && floor( loops ) + 1.0 >= repetitions;
+    // last row rather than blending back toward its first (#88) \u2014 and, reversed,
+    // across the first interval of a play that runs out.
+    bool holds = looping && repetitions != ${glslFloat(INFINITE_REPETITIONS)} && ( reversed ? loops < 1.0 : vatPlayback.w == ${glslFloat(EndMode.Clamp)} && floor( loops ) + 1.0 >= repetitions );
     bool wraps = looping && !holds;
 
-    float f = phase * ( looping ? frames : last );
+    // The mirror, as a select on the phase and never a branch: every instance
+    // pays for it, reversed or not (#72). A mirrored 1 across the seam is the
+    // seam, the first row again.
+    float mirrored = 1.0 - phase;
+    phase = reversed ? ( wraps && mirrored >= 1.0 ? 0.0 : mirrored ) : phase;
+
+    // A held interval sits on the last row, with nothing to blend toward.
+    float spread = phase * ( looping ? frames : last );
+    float f = holds ? min( spread, last ) : spread;
     float f0 = min( floor( f ), last );
     // A compare, not a mod: a mod divides, and at the last row a quotient a hair
     // under 1 leaves f1 at frames, one row past the band (#79).
@@ -137,10 +146,12 @@ var ROW_PRELUDE = (
     // The crossfade's weight, transcribed from the resolver: wall clock, not
     // clip time \u2014 the incoming clip's speed does not stretch a transition \u2014 and
     // a duration of zero is what a cut is, which is what the pack writes when
-    // there is no band to blend away.
+    // there is no band to blend away. Measured from the blend start the same
+    // texel carries in g, which is the live start time unless a turn placed it
+    // (ADR-0036): one component swapped for another, so no fetch and no branch.
     rows.weight = 0.0;
     if ( vatCrossfade.x > 0.0 ) {
-      rows.weight = 1.0 - clamp( ( uVatTime - vatPlayback.x ) / vatCrossfade.x, 0.0, 1.0 );
+      rows.weight = 1.0 - clamp( ( uVatTime - vatCrossfade.y ) / vatCrossfade.x, 0.0, 1.0 );
     }
 
     return rows;

package/dist/write.d.ts

@@ -0,0 +1,53 @@
+import { b as VAT } from './types-CDPXKe0_.js';
+import { Texture } from 'three';
+import { GLTFParser } from 'three/examples/jsm/loaders/GLTFLoader.js';
+
+/** One image of the source file, as the file held it. */
+interface SourceImage {
+    bytes: Uint8Array;
+    mimeType: string;
+    name?: string;
+}
+/**
+ * How a source texture reaches its image: through its own `source`, through
+ * one of the {@link IMAGE_EXTENSIONS}, or both, one the fallback of the other. Copied through
+ * in the same shape, so a KTX2 texture stays KTX2.
+ */
+interface SourceTexture {
+    source?: SourceImage;
+    extensions: Record<string, SourceImage>;
+    /** The image-format extensions the source file required. */
+    required: string[];
+}
+/** Each source texture's images, keyed by the image a loaded texture holds, which its clones share. */
+type SourceImages = Map<Texture['source'], SourceTexture>;
+/**
+ * How a `.gltf`'s image file beside it is read: its bytes, now or later, for
+ * the URI exactly as the `.gltf` writes it.
+ */
+type ReadImageFile = (uri: string) => ArrayBuffer | Promise<ArrayBuffer>;
+/**
+ * Every texture the loaded materials hold, keyed by its image, with that
+ * image's bytes as the file holds them, for {@link writeBakedFile} to copy
+ * into the baked file as they are (ADR-0034). `parser` is the loaded glTF's
+ * own (`gltf.parser`): an image in the binary chunk is read through its
+ * `getDependency('bufferView', i)`, and a `data:` URI is decoded where it
+ * stands. An image in a file beside a `.gltf` is read through `readFile`,
+ * which by default fetches it from where the loader found the `.gltf`.
+ */
+declare function readSourceImages(parser: GLTFParser, readFile?: ReadImageFile): Promise<SourceImages>;
+
+/**
+ * Write `vat` as a baked file. Resolves to the `.glb`'s bytes. In Node, a
+ * `FileReader` has to be installed first (src/file-reader.ts): the exporter
+ * reads its own output back through one.
+ *
+ * A textured material's images are copied from `images`, the source file's
+ * own bytes (src/write-materials.ts). A rig-encoded VAT is written with a
+ * preview skin, and only as `bakeVAT` returned it ({@link previewSkin}).
+ */
+declare function writeBakedFile(vat: VAT, { images }?: {
+    images?: SourceImages;
+}): Promise<Uint8Array>;
+
+export { type ReadImageFile, type SourceImage, type SourceImages, type SourceTexture, readSourceImages, writeBakedFile };

package/dist/write.js

@@ -0,0 +1,3 @@
+export { readSourceImages, writeBakedFile } from './chunk-7TT7B5WS.js';
+import './chunk-P6AFXEBT.js';
+import './chunk-4IKOXUSX.js';

package/package.json

@@ -1,81 +1,88 @@
-{
-  "name": "three-vat",
-  "version": "4.1.0",
-  "description": "Bake glTF animation clips into vertex animation textures for zero-CPU instanced crowds in three.js.",
-  "type": "module",
-  "license": "MIT",
-  "author": "Mike Fernandez <mike.fernandez.sec@gmail.com>",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/MikeFernandez-Pro/three-vat.git"
-  },
-  "bugs": {
-    "url": "https://github.com/MikeFernandez-Pro/three-vat/issues"
-  },
-  "homepage": "https://github.com/MikeFernandez-Pro/three-vat#readme",
-  "publishConfig": {
-    "access": "public"
-  },
-  "packageManager": "pnpm@10.19.0",
-  "sideEffects": false,
-  "files": [
-    "dist"
-  ],
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./webgl": {
-      "types": "./dist/webgl.d.ts",
-      "import": "./dist/webgl.js"
-    },
-    "./tsl": {
-      "types": "./dist/tsl.d.ts",
-      "import": "./dist/tsl.js"
-    }
-  },
-  "scripts": {
-    "dev": "pnpm --filter three-vat-example dev",
-    "test": "vitest run && pnpm --filter three-vat-example test",
-    "build": "tsup",
-    "typecheck": "tsc --noEmit && tsc --noEmit -p release/tsconfig.json && pnpm --filter three-vat-example typecheck",
-    "build:watch": "tsup --watch",
-    "test:watch": "vitest",
-    "prepublishOnly": "pnpm typecheck && pnpm test && pnpm build"
-  },
-  "keywords": [
-    "three",
-    "threejs",
-    "vat",
-    "vertex-animation-texture",
-    "instancing",
-    "instancedmesh",
-    "crowd",
-    "animation",
-    "skinning",
-    "webgpu",
-    "tsl"
-  ],
-  "peerDependencies": {
-    "three": ">=0.186.0"
-  },
-  "devDependencies": {
-    "@types/three": "^0.186.0",
-    "gifenc": "1.0.3",
-    "playwright-core": "1.63.0",
-    "pngjs": "7.0.0",
-    "three": "^0.186.0",
-    "tsup": "^8.3.0",
-    "typescript": "^5.6.0",
-    "vite": "^7.1.0",
-    "vitest": "^2.1.0"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "workspaces": [
-    ".",
-    "examples"
-  ]
-}
+{
+  "name": "three-vat",
+  "version": "4.2.0",
+  "description": "Bake glTF animation clips into vertex animation textures for zero-CPU instanced crowds in three.js.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Mike Fernandez <mike.fernandez.sec@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MikeFernandez-Pro/three-vat.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MikeFernandez-Pro/three-vat/issues"
+  },
+  "homepage": "https://github.com/MikeFernandez-Pro/three-vat#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "pnpm@10.19.0",
+  "sideEffects": false,
+  "bin": {
+    "three-vat": "./dist/bin.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./webgl": {
+      "types": "./dist/webgl.d.ts",
+      "import": "./dist/webgl.js"
+    },
+    "./tsl": {
+      "types": "./dist/tsl.d.ts",
+      "import": "./dist/tsl.js"
+    },
+    "./write": {
+      "types": "./dist/write.d.ts",
+      "import": "./dist/write.js"
+    }
+  },
+  "scripts": {
+    "dev": "pnpm --filter three-vat-example dev",
+    "test": "vitest run && pnpm --filter three-vat-example test",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p release/tsconfig.json && pnpm --filter three-vat-example typecheck",
+    "build:watch": "tsup --watch",
+    "test:watch": "vitest",
+    "prepublishOnly": "pnpm typecheck && pnpm test && pnpm build"
+  },
+  "keywords": [
+    "three",
+    "threejs",
+    "vat",
+    "vertex-animation-texture",
+    "instancing",
+    "instancedmesh",
+    "crowd",
+    "animation",
+    "skinning",
+    "webgpu",
+    "tsl"
+  ],
+  "peerDependencies": {
+    "three": ">=0.186.0"
+  },
+  "devDependencies": {
+    "@types/three": "^0.186.0",
+    "gifenc": "1.0.3",
+    "playwright-core": "1.63.0",
+    "pngjs": "7.0.0",
+    "three": "^0.186.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vite": "^7.1.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "workspaces": [
+    ".",
+    "examples"
+  ]
+}