three-vat 1.0.1 → 2.1.0

package/dist/webgl.js

@@ -1,4 +1,5 @@
-import { addVATInstanceAttributes, createCrowdGeometry } from './chunk-SXTVASKG.js';
+import { assertBakedNormal, assertVATCarrier, isBatchedCarrier } from './chunk-I4STYOD5.js';
+import { PACK_TEXELS, EndMode, LoopMode, RIG_TEXELS_PER_SLOT, RIG_TEXELS, INFINITE_REPETITIONS, createVATPlaybackTexture } from './chunk-3PWAY6MD.js';
 import { MeshDepthMaterial, RGBADepthPacking, InstancedMesh, MeshDistanceMaterial } from 'three';
 
 function getMaxTextureSize(renderer) {
@@ -7,67 +8,326 @@ function getMaxTextureSize(renderer) {
 function createVATUniforms(time = 0) {
   return { uVatTime: { value: time } };
 }
-var addInstancedVATAttributes = addVATInstanceAttributes;
-var DECODE_PRELUDE = (
+var glslFloat = (n) => n.toFixed(1);
+var ROW_PRELUDE = (
+  /* glsl */
+  `
+  uniform highp sampler2D uVatPlaybackTex;
+  uniform float uVatTime;
+
+  // Where an instance is reading: the two rows of its band it sits between and
+  // the blend toward the second; and the pose-freeze fade's frozen row and
+  // weight, a weight of zero being "not fading".
+  struct VatRows {
+    int row0;
+    int row1;
+    float blend;
+    int fadeRow;
+    float fadeWeight;
+  };
+
+  VatRows vatRows( const in int vatInstance ) {
+    // The pack, fetched by this instance's *logical* index rather than read
+    // off an attribute indexed by the drawn slot (ADR-0016). Three texels of
+    // one row, in the order src/instance-playback.ts lays them out; the
+    // arithmetic below is untouched by where they came from, because the pack
+    // was already three vec4s.
+    //
+    // The index arrives as a parameter rather than being read here, because
+    // where it comes from is the carrier's business and not the decode's:
+    // gl_InstanceID on an InstancedMesh, getIndirectIndex( gl_DrawID ) on a
+    // BatchedMesh \u2014 see INSTANCE_ID in src/webgl.ts. It also has to be a
+    // parameter: getIndirectIndex is declared by batching_pars_vertex, which
+    // three expands *after* this prelude, so naming it up here would not
+    // compile.
+    //
+    // Fetched inside the function, so each injection point stays
+    // self-contained (ADR-0006) \u2014 which costs a second set of fetches in the
+    // normal decode. Every vertex of an instance reads the same three texels,
+    // so the texture cache absorbs them; the 5% demo bench is what says so.
+    vec4 vatClip     = texelFetch( uVatPlaybackTex, ivec2( ${PACK_TEXELS.clip}, vatInstance ), 0 );
+    vec4 vatPlayback = texelFetch( uVatPlaybackTex, ivec2( ${PACK_TEXELS.playback}, vatInstance ), 0 );
+    vec4 vatFade     = texelFetch( uVatPlaybackTex, ivec2( ${PACK_TEXELS.fade}, vatInstance ), 0 );
+
+    float frames = vatClip.y;
+    float last = frames - 1.0;
+    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;
+    float repetitions = vatPlayback.z;
+
+    bool started = local >= 0.0;
+    bool finished = started && repetitions != ${glslFloat(INFINITE_REPETITIONS)} && loops >= repetitions;
+
+    float phase;
+    bool wraps;
+    if ( !started ) {
+      phase = 0.0;
+      wraps = false;
+    } else if ( finished ) {
+      // Held at an end pose, and in neither case sampling past it.
+      phase = vatPlayback.w == ${glslFloat(EndMode.Clamp)} ? 1.0 : 0.0;
+      wraps = false;
+    } else if ( vatPlayback.y == ${glslFloat(LoopMode.PingPong)} ) {
+      float m = mod( loops, 2.0 );
+      phase = m < 1.0 ? m : 2.0 - m;
+      wraps = false; // a ping-pong bounces; it does not wrap
+    } else {
+      phase = fract( loops );
+      wraps = true;  // and here the interpolation crossing back is correct
+    }
+
+    float f = phase * ( wraps ? frames : last );
+    float f0 = min( floor( f ), last );
+    float f1 = wraps ? mod( f0 + 1.0, frames ) : min( f0 + 1.0, last );
+
+    VatRows rows;
+    rows.row0 = int( vatClip.x + f0 );
+    rows.row1 = int( vatClip.x + f1 );
+    rows.blend = f - f0;
+
+    // The pose-freeze fade, transcribed from the same resolver: one frozen row
+    // of the clip this instance was playing when it changed, blended away over
+    // vatFade.w. Wall clock, not clip time \u2014 the incoming clip's speed does
+    // not stretch a fade. A duration of zero is what "not fading" is, and the
+    // pack never writes one without a band to go with it.
+    rows.fadeRow = 0;
+    rows.fadeWeight = 0.0;
+    if ( vatFade.w > 0.0 ) {
+      float weight = 1.0 - clamp( ( uVatTime - vatPlayback.x ) / vatFade.w, 0.0, 1.0 );
+      float fromRow = max( min( floor( vatFade.z * vatFade.y ), vatFade.y - 1.0 ), 0.0 );
+      rows.fadeRow = int( vatFade.x + fromRow );
+      rows.fadeWeight = weight;
+    }
+    return rows;
+  }
+`
+);
+var VERTEX_PRELUDE = (
   /* glsl */
   `
   uniform highp sampler2D uVatPosTex;
+  vec3 vatSample( const in sampler2D tex, const in int vatInstance ) {
+    VatRows rows = vatRows( vatInstance );
+    vec3 s0 = texelFetch( tex, ivec2( gl_VertexID, rows.row0 ), 0 ).xyz;
+    vec3 s1 = texelFetch( tex, ivec2( gl_VertexID, rows.row1 ), 0 ).xyz;
+    vec3 sampled = mix( s0, s1, rows.blend );
+    // The frozen row, blended in by the weight the rows resolved.
+    float weight = rows.fadeWeight;
+    if ( weight > 0.0 ) {
+      vec3 frozen = texelFetch( tex, ivec2( gl_VertexID, rows.fadeRow ), 0 ).xyz;
+      sampled = mix( sampled, frozen, weight );
+    }
+    return sampled;
+  }
+`
+);
+var NORMAL_PRELUDE = (
+  /* glsl */
+  `
   uniform highp sampler2D uVatNrmTex;
-  uniform float uVatTime;
-  attribute float aClipStart;
-  attribute float aClipFrames;
-  attribute float aClipFps;
-  attribute float aTimeOffset;
-  attribute float aSpeed;
-  vec3 vatSample( const in sampler2D tex ) {
-    float duration = aClipFrames / aClipFps;
-    float t = fract( ( uVatTime * aSpeed + aTimeOffset ) / duration ) * aClipFrames;
-    int f0 = int( t );
-    int f1 = int( mod( float( f0 + 1 ), aClipFrames ) );
-    vec3 s0 = texelFetch( tex, ivec2( gl_VertexID, f0 + int( aClipStart ) ), 0 ).xyz;
-    vec3 s1 = texelFetch( tex, ivec2( gl_VertexID, f1 + int( aClipStart ) ), 0 ).xyz;
-    return mix( s0, s1, fract( t ) );
+`
+);
+var RIG_PRELUDE = (
+  /* glsl */
+  `
+  uniform highp sampler2D uVatRigTex;
+  attribute vec4 skinIndex;
+  attribute vec4 skinWeight;
+
+  // Matrix4.compose, component for component: a rotation, a translation and
+  // one scale back to the matrix the skinning wants \u2014 so both encodings feed
+  // the same linear blend, and a rig crowd deforms as its vertex bake does.
+  mat4 vatCompose( const in vec4 q, const in vec4 ts ) {
+    float x2 = q.x + q.x, y2 = q.y + q.y, z2 = q.z + q.z;
+    float xx = q.x * x2, xy = q.x * y2, xz = q.x * z2;
+    float yy = q.y * y2, yz = q.y * z2, zz = q.z * z2;
+    float wx = q.w * x2, wy = q.w * y2, wz = q.w * z2;
+    float s = ts.w;
+    return mat4(
+      vec4( ( 1.0 - ( yy + zz ) ) * s, ( xy + wz ) * s, ( xz - wy ) * s, 0.0 ),
+      vec4( ( xy - wz ) * s, ( 1.0 - ( xx + zz ) ) * s, ( yz + wx ) * s, 0.0 ),
+      vec4( ( xz + wy ) * s, ( yz - wx ) * s, ( 1.0 - ( xx + yy ) ) * s, 0.0 ),
+      vec4( ts.xyz, 1.0 )
+    );
+  }
+
+  // One slot's matrix between the two rows the instance sits between \u2014 and
+  // through the fade, blended before it is composed.
+  mat4 vatSlot( const in int slot, const in VatRows rows ) {
+    int rotation = slot * ${RIG_TEXELS_PER_SLOT} + ${RIG_TEXELS.rotation};
+    int placement = slot * ${RIG_TEXELS_PER_SLOT} + ${RIG_TEXELS.placement};
+    vec4 q0 = texelFetch( uVatRigTex, ivec2( rotation, rows.row0 ), 0 );
+    vec4 ts0 = texelFetch( uVatRigTex, ivec2( placement, rows.row0 ), 0 );
+    vec4 q1 = texelFetch( uVatRigTex, ivec2( rotation, rows.row1 ), 0 );
+    vec4 ts1 = texelFetch( uVatRigTex, ivec2( placement, rows.row1 ), 0 );
+    // The bake keeps consecutive rows on one hemisphere, but a looping clip
+    // blends its band's last row into its first, and a bone that turned a full
+    // circle over the clip arrives there on the far side: one dot product per
+    // slot, or the blend passes through zero on the wrap frame.
+    if ( dot( q0, q1 ) < 0.0 ) q1 = -q1;
+    // A normalised lerp, not a slerp: at a bake's frame step the angular error
+    // against a true slerp is far below anything visible. It is still a
+    // *rotation* at every blend, which is what a componentwise matrix lerp is
+    // not \u2014 that one shortens a limb as it turns (ADR-0018).
+    vec4 q = normalize( mix( q0, q1, rows.blend ) );
+    vec4 ts = mix( ts0, ts1, rows.blend );
+    if ( rows.fadeWeight > 0.0 ) {
+      vec4 qf = texelFetch( uVatRigTex, ivec2( rotation, rows.fadeRow ), 0 );
+      vec4 tsf = texelFetch( uVatRigTex, ivec2( placement, rows.fadeRow ), 0 );
+      // The frozen row is any row of the bake, not this row's neighbour, so
+      // the same check.
+      if ( dot( q, qf ) < 0.0 ) qf = -qf;
+      q = normalize( mix( q, qf, rows.fadeWeight ) );
+      ts = mix( ts, tsf, rows.fadeWeight );
+    }
+    return vatCompose( q, ts );
+  }
+
+  // Linear blend skinning: the weighted sum of slot matrices, which is the
+  // blend the bake did on the CPU for the bounds and three's own
+  // skinning_vertex does on the GPU. A zero weight skips its four fetches.
+  mat4 vatSkinMatrix( const in int vatInstance ) {
+    VatRows rows = vatRows( vatInstance );
+    mat4 skin = mat4( 0.0 );
+    for ( int i = 0; i < 4; i ++ ) {
+      float w = skinWeight[ i ];
+      if ( w == 0.0 ) continue;
+      skin += w * vatSlot( int( skinIndex[ i ] ), rows );
+    }
+    return skin;
   }
 `
 );
-var DECODE_POSITION = (
+var INSTANCE_ID = {
+  instance: "gl_InstanceID",
+  batch: "int( getIndirectIndex( gl_DrawID ) )"
+};
+var vertexPosition = (id) => (
   /* glsl */
   `
-  vec3 transformed = position + vatSample( uVatPosTex );
+  vec3 transformed = position + vatSample( uVatPosTex, ${INSTANCE_ID[id]} );
 `
 );
-var DECODE_NORMAL = (
+var vertexNormal = (id) => (
   /* glsl */
   `
-  vec3 objectNormal = normalize( vatSample( uVatNrmTex ) );
+  vec3 objectNormal = normalize( vatSample( uVatNrmTex, ${INSTANCE_ID[id]} ) );
   #ifdef USE_TANGENT
     vec3 objectTangent = vec3( tangent.xyz );
   #endif
 `
 );
-function patchVATMaterial(material, vat, uniforms) {
+var rigPosition = (id) => (
+  /* glsl */
+  `
+  mat4 vatSkin = vatSkinMatrix( ${INSTANCE_ID[id]} );
+  vec3 transformed = ( vatSkin * vec4( position, 1.0 ) ).xyz;
+`
+);
+var rigNormal = (id) => (
+  /* glsl */
+  `
+  mat4 vatSkinN = vatSkinMatrix( ${INSTANCE_ID[id]} );
+  vec3 objectNormal = normalize( mat3( vatSkinN ) * normal );
+  #ifdef USE_TANGENT
+    vec3 objectTangent = normalize( mat3( vatSkinN ) * tangent.xyz );
+  #endif
+`
+);
+function vertexDecode({ positionTexture, normalTexture }, id) {
+  return {
+    prelude: (normalTexture ? NORMAL_PRELUDE : "") + VERTEX_PRELUDE,
+    bind(uniforms) {
+      uniforms.uVatPosTex = { value: positionTexture };
+      if (normalTexture) uniforms.uVatNrmTex = { value: normalTexture };
+    },
+    inject(vertexShader) {
+      const positioned = vertexShader.replace("#include <begin_vertex>", vertexPosition(id));
+      return normalTexture ? positioned.replace("#include <beginnormal_vertex>", vertexNormal(id)) : positioned;
+    },
+    // A normal-less VAT injects a different vertex shader off the same material
+    // parameters, so the variant is in the key (see `patchVATMaterial`).
+    key: `three-vat:${id}${normalTexture ? "" : ":no-normal"}`
+  };
+}
+function rigDecode({ rigTexture }, id) {
+  return {
+    prelude: RIG_PRELUDE,
+    bind(uniforms) {
+      uniforms.uVatRigTex = { value: rigTexture };
+    },
+    inject(vertexShader) {
+      return vertexShader.replace("#include <begin_vertex>", rigPosition(id)).replace("#include <beginnormal_vertex>", rigNormal(id));
+    },
+    key: `three-vat:rig:${id}`
+  };
+}
+function decodeFor(vat, id) {
+  switch (vat.encoding) {
+    case "delta":
+      return vertexDecode(vat, id);
+    case "rig":
+      return rigDecode(vat, id);
+    default: {
+      const unhandled = vat;
+      throw new Error(
+        `three-vat: patchVATMaterial has no decode for encoding "${String(unhandled.encoding)}"`
+      );
+    }
+  }
+}
+function patchVATMaterial(material, vat, uniforms, playback, carrier) {
+  assertBakedNormal(vat, material);
+  if (carrier) assertVATCarrier(carrier, vat);
+  const id = isBatchedCarrier(carrier) ? "batch" : "instance";
+  const decode = decodeFor(vat, id);
   material.onBeforeCompile = (shader) => {
-    shader.uniforms.uVatPosTex = { value: vat.positionTexture };
-    shader.uniforms.uVatNrmTex = { value: vat.normalTexture };
+    shader.uniforms.uVatPlaybackTex = { value: playback.texture };
     shader.uniforms.uVatTime = uniforms.uVatTime;
-    shader.vertexShader = DECODE_PRELUDE + shader.vertexShader.replace("#include <begin_vertex>", DECODE_POSITION).replace("#include <beginnormal_vertex>", DECODE_NORMAL);
+    decode.bind(shader.uniforms);
+    shader.vertexShader = ROW_PRELUDE + decode.prelude + decode.inject(shader.vertexShader);
   };
-  material.customProgramCacheKey = () => "three-vat";
+  material.customProgramCacheKey = () => decode.key;
+  guardCarrierMismatch(material, id);
   return material;
 }
-function createVATDepthMaterial(vat, uniforms) {
+function guardCarrierMismatch(material, id) {
+  const previous = material.onBeforeRender.bind(material);
+  let checked = false;
+  material.onBeforeRender = function(renderer, scene, camera, geometry, object, group) {
+    if (!checked) {
+      checked = true;
+      const drawnOn = isBatchedCarrier(object) ? "batch" : "instance";
+      if (drawnOn !== id) {
+        throw new Error(
+          `three-vat: this material was patched for ${CARRIER_NAME[id]} and is being drawn on ${CARRIER_NAME[drawnOn]}. Pass the carrier as \`patchVATMaterial\`'s fifth argument \u2014 the two spell the instance index differently, and a batch drawn with the instanced spelling plays instance 0\u2019s clip on every instance.`
+        );
+      }
+    }
+    previous(renderer, scene, camera, geometry, object, group);
+  };
+}
+var CARRIER_NAME = {
+  instance: "an InstancedMesh",
+  batch: "a BatchedMesh"
+};
+function createVATDepthMaterial(vat, uniforms, playback, carrier) {
   const depth = new MeshDepthMaterial({ depthPacking: RGBADepthPacking });
-  patchVATMaterial(depth, vat, uniforms);
+  patchVATMaterial(depth, vat, uniforms, playback, carrier);
   return depth;
 }
 function createVATMesh(vat, instances, options = {}) {
   const uniforms = options.time ? { uVatTime: options.time } : createVATUniforms();
-  const geometry = createCrowdGeometry(vat, instances);
-  const materials = vat.materials.map((source) => patchVATMaterial(source.clone(), vat, uniforms));
-  const mesh = new InstancedMesh(geometry, materials, instances.length);
-  mesh.customDepthMaterial = createVATDepthMaterial(vat, uniforms);
-  mesh.customDistanceMaterial = patchVATMaterial(new MeshDistanceMaterial(), vat, uniforms);
-  return { mesh, time: uniforms.uVatTime };
+  const playback = createVATPlaybackTexture(instances);
+  const materials = vat.materials.map((source) => patchVATMaterial(source.clone(), vat, uniforms, playback));
+  const mesh = new InstancedMesh(vat.geometry, materials, instances.length);
+  mesh.customDepthMaterial = createVATDepthMaterial(vat, uniforms, playback);
+  mesh.customDistanceMaterial = patchVATMaterial(new MeshDistanceMaterial(), vat, uniforms, playback);
+  return { mesh, time: uniforms.uVatTime, playback };
 }
 
-export { addInstancedVATAttributes, createVATDepthMaterial, createVATMesh, createVATUniforms, getMaxTextureSize, patchVATMaterial };
+export { createVATDepthMaterial, createVATMesh, createVATUniforms, getMaxTextureSize, patchVATMaterial };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-vat",
-  "version": "1.0.1",
+  "version": "2.1.0",
   "description": "Bake glTF animation clips into vertex animation textures for zero-CPU instanced crowds in three.js.",
   "type": "module",
   "license": "MIT",
@@ -16,6 +16,7 @@
   "publishConfig": {
     "access": "public"
   },
+  "packageManager": "pnpm@10.19.0",
   "sideEffects": false,
   "files": [
     "dist"
@@ -34,6 +35,15 @@
       "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",
@@ -48,28 +58,24 @@
     "tsl"
   ],
   "peerDependencies": {
-    "three": ">=0.185.0"
+    "three": ">=0.186.0"
   },
   "devDependencies": {
-    "@types/three": "^0.185.0",
+    "@types/three": "^0.186.0",
     "gifenc": "1.0.3",
     "playwright-core": "1.63.0",
     "pngjs": "7.0.0",
-    "three": "^0.185.0",
+    "three": "^0.186.0",
     "tsup": "^8.3.0",
     "typescript": "^5.6.0",
     "vite": "^7.1.0",
     "vitest": "^2.1.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
-  "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"
-  }
-}
+  "workspaces": [
+    ".",
+    "examples"
+  ]
+}

package/dist/chunk-SXTVASKG.js

@@ -1,40 +0,0 @@
-import { InstancedBufferAttribute } from 'three';
-
-// src/instance-playback.ts
-var PLAYBACK_ATTRIBUTES = {
-  clipStart: "aClipStart",
-  clipFrames: "aClipFrames",
-  clipFps: "aClipFps",
-  timeOffset: "aTimeOffset",
-  speed: "aSpeed"
-};
-function addVATInstanceAttributes(geometry, instances) {
-  geometry.morphAttributes = {};
-  geometry.morphTargetsRelative = false;
-  const n = instances.length;
-  const clipStart = new Float32Array(n);
-  const clipFrames = new Float32Array(n);
-  const clipFps = new Float32Array(n);
-  const timeOffset = new Float32Array(n);
-  const speed = new Float32Array(n);
-  for (let i = 0; i < n; i++) {
-    const inst = instances[i];
-    clipStart[i] = inst.clip.startFrame;
-    clipFrames[i] = inst.clip.frames;
-    clipFps[i] = inst.clip.fps;
-    timeOffset[i] = inst.timeOffset;
-    speed[i] = inst.speed;
-  }
-  geometry.setAttribute(PLAYBACK_ATTRIBUTES.clipStart, new InstancedBufferAttribute(clipStart, 1));
-  geometry.setAttribute(PLAYBACK_ATTRIBUTES.clipFrames, new InstancedBufferAttribute(clipFrames, 1));
-  geometry.setAttribute(PLAYBACK_ATTRIBUTES.clipFps, new InstancedBufferAttribute(clipFps, 1));
-  geometry.setAttribute(PLAYBACK_ATTRIBUTES.timeOffset, new InstancedBufferAttribute(timeOffset, 1));
-  geometry.setAttribute(PLAYBACK_ATTRIBUTES.speed, new InstancedBufferAttribute(speed, 1));
-}
-function createCrowdGeometry(vat, instances) {
-  const geometry = vat.geometry.clone();
-  addVATInstanceAttributes(geometry, instances);
-  return geometry;
-}
-
-export { PLAYBACK_ATTRIBUTES, addVATInstanceAttributes, createCrowdGeometry };

package/dist/instance-playback-BrGBIKLe.d.ts

@@ -1,109 +0,0 @@
-import { DataTexture, BufferGeometry, Material, Box3, InstancedMesh } from 'three';
-
-/** One baked animation range within a VAT's stacked frame rows. */
-interface VATClip {
-    /** Clip name, taken from the source `AnimationClip`. */
-    name: string;
-    /** First frame row (y) of this clip in the texture. */
-    startFrame: number;
-    /** Number of frame rows baked for this clip. */
-    frames: number;
-    /** Effective frames-per-second of the bake (`frames / duration`). */
-    fps: number;
-    /** Source clip duration in seconds. */
-    duration: number;
-    /**
-     * Largest per-vertex position-delta magnitude (metres) across the clip.
-     * Near-zero means the clip baked as a frozen pose — the diagnostic for a
-     * mis-targeted or genuinely static clip.
-     */
-    maxDelta: number;
-}
-/**
- * A baked Vertex Animation Texture: the position/normal `DataTexture`s, the
- * geometry they are indexed by, and the clip table and bounds needed to decode
- * and render them. Produced exactly one way — {@link bakeVAT}, at runtime, from
- * a loaded glTF (ADR-0010).
- *
- * The merged vertex ordering is the baker's own invention and the textures are
- * indexed by it (`x = gl_VertexID`), so the caller cannot bring its own
- * geometry — it must render the one baked here. `materials` is ordered to match
- * `geometry.groups[].materialIndex`, giving one draw call per material.
- */
-interface VAT {
-    /** RGBA float texture of per-vertex position deltas (`x = vertex`, `y = frame`). */
-    positionTexture: DataTexture;
-    /** RGBA float texture of per-vertex absolute normals (`x = vertex`, `y = frame`). */
-    normalTexture: DataTexture;
-    /** Merged, root-space rest-pose geometry. Its `position` is the delta reference. */
-    geometry: BufferGeometry;
-    /** Source materials, indexed by `geometry.groups[].materialIndex`. */
-    materials: Material[];
-    /** Clip table: name → `{ startFrame, frames, fps, ... }`. */
-    clips: VATClip[];
-    /** Union of every baked frame's bounds; use as the geometry bounding box. */
-    bounds: Box3;
-    /** Vertex count (texture width). */
-    vertexCount: number;
-    /** Total frame rows across all clips (texture height). */
-    totalFrames: number;
-    /** Position encoding. Only `'delta'` in v1. */
-    encoding: 'delta';
-}
-/**
- * The shared playback clock: one `{ value }` in seconds, read by every material
- * of every VAT mesh driven by it. Set it once per frame. Deliberately the
- * narrowest shape both decode paths satisfy — a WebGL `IUniform<number>` and a
- * TSL uniform node are both one of these — so `createVATMesh` returns the same
- * thing on either renderer.
- */
-interface VATClock {
-    value: number;
-}
-/**
- * A **crowd** ready to render: the mesh to add to the scene, and the clock to
- * advance. What `createVATMesh` returns on either decode path, so moving a
- * crowd between renderers is an import change and nothing else. Named for what
- * it is rather than for its `mesh` field — the clock is half of it.
- */
-interface VATCrowd {
-    /** Add to the scene. Its instance matrices are yours to write. */
-    mesh: InstancedMesh;
-    /** The shared playback clock — set `.value` once per frame. */
-    time: VATClock;
-}
-
-/** Per-instance playback state consumed by both decode paths. */
-interface VATInstance {
-    clip: Pick<VAT['clips'][number], 'startFrame' | 'frames' | 'fps'>;
-    /** Phase offset in seconds — desyncs the crowd. */
-    timeOffset: number;
-    /** Playback rate multiplier. */
-    speed: number;
-}
-/**
- * Attach the instance-playback attributes to an instanced geometry. Call once
- * before rendering, on the geometry you hand to the `InstancedMesh`.
- *
- * The attribute names and layout below are the shared contract, spelled once in
- * {@link PLAYBACK_ATTRIBUTES}. Both decode paths read exactly these five —
- * `DECODE_PRELUDE` in `src/webgl.ts` as GLSL attributes, `vatNodes` in
- * `src/tsl.ts` as TSL attribute nodes, when it is handed this geometry.
- *
- * | Attribute     | Type          | Source                |
- * | ------------- | ------------- | --------------------- |
- * | `aClipStart`  | `float` (x 1) | `instance.clip.startFrame` — first texture row of the clip's frame band |
- * | `aClipFrames` | `float` (x 1) | `instance.clip.frames` — rows in the band |
- * | `aClipFps`    | `float` (x 1) | `instance.clip.fps` — with `frames`, the clip's duration |
- * | `aTimeOffset` | `float` (x 1) | `instance.timeOffset` — phase, in seconds |
- * | `aSpeed`      | `float` (x 1) | `instance.speed` — rate multiplier |
- *
- * Every entry is a one-component `InstancedBufferAttribute` of `Float32Array`,
- * one element per instance, in instance order. Adding a field — crossfade's
- * reserved second clip index being the known case (ADR-0007) — means adding it
- * here, in the table above, and in each decode path's own attribute
- * declarations.
- */
-declare function addVATInstanceAttributes(geometry: BufferGeometry, instances: VATInstance[]): void;
-
-export { type VAT as V, type VATClip as a, type VATClock as b, type VATCrowd as c, type VATInstance as d, addVATInstanceAttributes as e };