spoint 0.1.650 → 0.1.652

package/client/core/PlayerVAT.js

@@ -49,239 +49,11 @@
 
 import * as THREE from 'three'
 import { InstancedMesh2 } from '@three.ez/instanced-mesh'
+import { bakeVAT, bakeVATMultiClip } from './PlayerVATBake.js'
 
-// window.__tickAnimTiming / _tickAnimSamples live in app.js (the actual call site) -- this module only
-// consumes the resulting bake/renderer, it doesn't own the timing surface.
-
-// --- Bake -------------------------------------------------------------------------------------------
-// Drives a REAL AnimationMixer against a REAL cloned SkinnedMesh hierarchy at a fixed sample rate,
-// reading back post-skin world-space vertex positions each sample via CPU skinning (THREE's own
-// SkinnedMesh.boneTransform, the same math the GPU skinning path performs, just run on CPU once at
-// bake time instead of every frame at runtime) and encoding position DELTA (post-skin minus bind-pose
-// local position) into a float RGBA DataTexture: one texel row per sampled animation frame, one texel
-// column per source vertex. A GPU vertex shader then reconstructs the animated position at runtime by
-// sampling this texture at (vertexIndex, phase) and adding the delta to the bind-pose position -- no
-// bone matrices, no skinning weights needed at runtime, just one texelFetch.
-const VAT_SAMPLE_HZ = 24 // resample rate baked into the texture; independent of the source clip's authored keyframe spacing (same discipline as AnimationClipCache.js's RESAMPLE_HZ)
-
-const _vtmp = new THREE.Vector3()
-const _baseVec = new THREE.Vector3()
-const _bindPos = new THREE.Vector3()
-const _boneMtx = new THREE.Matrix4()
-/**
- * Computes the post-skin world-space (mesh-local-space, i.e. relative to the SkinnedMesh's own
- * unmoved transform) position of vertex `vi` on `skinnedMesh` at its CURRENT pose (caller must have
- * already advanced the driving AnimationMixer + called skeleton.update() before calling this).
- * Exactly mirrors THREE.SkinnedMesh.applyBoneTransform's own CPU skin math (see
- * three/src/objects/SkinnedMesh.js): baseVector = bindPos * bindMatrix, accumulate per-bone
- * (bone.matrixWorld * boneInverse) * baseVector weighted, then multiply by bindMatrixInverse -- NOT the
- * skeleton's own precomputed boneMatrices array directly (that buffer already premultiplies bindMatrix
- * differently for GPU upload; reproducing the CPU-path formula verbatim, bone-by-bone, is what keeps
- * this bake bit-identical to what the GPU skinning path would have rendered).
- */
-function boneTransformInto(skinnedMesh, vi, target) {
-  const geometry = skinnedMesh.geometry
-  const skeleton = skinnedMesh.skeleton
-  const posAttr = geometry.attributes.position
-  const skinIndex = geometry.attributes.skinIndex
-  const skinWeight = geometry.attributes.skinWeight
-  // _baseVec is a SEPARATE scratch from `target` -- target is caller-supplied and may alias a module-level
-  // scratch (bakeVAT passes _vtmp as target); reusing the same scratch for the internal base-vector AND the
-  // output accumulator caused target.set(0,0,0) below to wipe the base vector before it was consumed
-  // (found live: every baked frame read back as the raw un-skinned bind pose, a large CONSTANT delta at
-  // "frame 0" that should have been ~0 -- traced to exactly this aliasing bug).
-  _baseVec.fromBufferAttribute(posAttr, vi).applyMatrix4(skinnedMesh.bindMatrix)
-  target.set(0, 0, 0)
-  for (let j = 0; j < 4; j++) {
-    const weight = skinWeight.getComponent(vi, j)
-    if (weight === 0) continue
-    const boneIndex = skinIndex.getComponent(vi, j)
-    _boneMtx.multiplyMatrices(skeleton.bones[boneIndex].matrixWorld, skeleton.boneInverses[boneIndex])
-    const p = _baseVec.clone().applyMatrix4(_boneMtx)
-    target.x += p.x * weight; target.y += p.y * weight; target.z += p.z * weight
-  }
-  target.applyMatrix4(skinnedMesh.bindMatrixInverse)
-  return target
-}
-
-const _baseNrm = new THREE.Vector3()
-const _skinnedNrm = new THREE.Vector3()
-const _skinMtx = new THREE.Matrix4()
-const _accumMtx = new THREE.Matrix4()
-const _weightedMtx = new THREE.Matrix4()
-/**
- * Computes the post-skin (mesh-local-space) NORMAL of vertex `vi` at the CURRENT pose, writing it into
- * `target`. Mirrors three's own GPU `skinnormal_vertex` chunk (see
- * three/src/renderers/shaders/ShaderChunk/skinnormal_vertex.glsl.js) verbatim rather than a generic
- * inverse-transpose normal-matrix recompute: skinMatrix = bindMatrixInverse * (per-bone-weighted sum of
- * boneMatrices) * bindMatrix, then objectNormal = skinMatrix * vec4(objectNormal, 0.0) -- a plain LINEAR
- * transform (w=0, no translation row), NOT a proper inverse-transpose normal-matrix; GPU skinning doesn't
- * correct for non-uniform scale either, so reproducing that exact (non-)correction is what keeps this
- * bake bit-identical to what the GPU skinning path would have rendered, same discipline as
- * boneTransformInto above. Matrix summation IS valid here (not an approximation): matrix multiplication
- * is linear, so sum(w_i * M_i) * v === sum(w_i * (M_i * v)) for any v -- weighting the MATRICES first
- * (like the GPU chunk does) and weighting the TRANSFORMED VECTORS first (like boneTransformInto does for
- * position) are mathematically identical; the position path already accumulates transformed vectors, this
- * one accumulates the matrices per source verbatim to mirror the shader chunk line-for-line for easy
- * cross-reference, both are correct.
- */
-function boneTransformNormalInto(skinnedMesh, vi, target) {
-  const geometry = skinnedMesh.geometry
-  const skeleton = skinnedMesh.skeleton
-  const normalAttr = geometry.attributes.normal
-  const skinIndex = geometry.attributes.skinIndex
-  const skinWeight = geometry.attributes.skinWeight
-  _baseNrm.fromBufferAttribute(normalAttr, vi)
-  _accumMtx.set(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0) // zero matrix accumulator (skinMatrix += ...)
-  for (let j = 0; j < 4; j++) {
-    const weight = skinWeight.getComponent(vi, j)
-    if (weight === 0) continue
-    const boneIndex = skinIndex.getComponent(vi, j)
-    _boneMtx.multiplyMatrices(skeleton.bones[boneIndex].matrixWorld, skeleton.boneInverses[boneIndex])
-    _weightedMtx.copy(_boneMtx)
-    for (let k = 0; k < 16; k++) _weightedMtx.elements[k] *= weight
-    for (let k = 0; k < 16; k++) _accumMtx.elements[k] += _weightedMtx.elements[k]
-  }
-  _skinMtx.multiplyMatrices(skinnedMesh.bindMatrixInverse, _accumMtx)
-  _skinMtx.multiply(skinnedMesh.bindMatrix)
-  // Deliberately NOT Vector3.transformDirection (it normalizes) -- the GPU skinnormal_vertex chunk this
-  // mirrors does a plain un-normalized mat4*vec4(n,0) transform; normalize_vertex/normal_fragment_begin
-  // downstream normalize exactly once, after normalMatrix + instancing are also applied, so normalizing
-  // here would double-normalize a not-yet-fully-transformed intermediate and desync from what the GPU
-  // skinning path (and this bake's own bit-identical-parity goal) actually produces.
-  const e = _skinMtx.elements
-  target.set(
-    e[0] * _baseNrm.x + e[4] * _baseNrm.y + e[8] * _baseNrm.z,
-    e[1] * _baseNrm.x + e[5] * _baseNrm.y + e[9] * _baseNrm.z,
-    e[2] * _baseNrm.x + e[6] * _baseNrm.y + e[10] * _baseNrm.z
-  )
-  return target
-}
-
-/**
- * Bakes `clip` on `skinnedMesh` (must already be skeleton-bound, i.e. skinnedMesh.skeleton is the real
- * pose skeleton, bindMatrixInverse set) into a VAT DataTexture pair. Returns
- * {texture, normalTexture, frameCount, vertexCount, duration, sampleHz} -- both textures are
- * (vertexCount wide) x (frameCount tall), RGBA32F, same (vertexIndex, frame) texel addressing. `texture`'s
- * rgb = (post-skin - bind-pose) POSITION delta for that vertex at that sampled frame (unchanged from the
- * first slice). `normalTexture`'s rgb = (post-skin - bind-pose) un-normalized NORMAL delta (see
- * boneTransformNormalInto's header for why it's deliberately un-normalized), animation-vat-normal-delta-
- * lighting's follow-on: sampling+adding this alongside the position delta lets REDUCED-tier crowd
- * lighting respond to the animated pose instead of shading against the static bind-pose normal baked into
- * the base geometry. Alpha unused on both (reserved, kept at 1 so non-EXT_color_buffer_float readback
- * tooling still sees a valid alpha channel). normalTexture is null if the source mesh has no `normal`
- * attribute (degrades to the pre-existing bind-pose-normal-only behavior, same as before this follow-on).
- *
- * Runs on a REAL THREE.AnimationMixer bound to the mesh's root (mixer.clipAction(clip).play()),
- * advancing mixer.update(dt) at VAT_SAMPLE_HZ and reading back the real post-skin vertex positions (and
- * normals) each step -- not an approximation, the literal same CPU skin math THREE performs to render a
- * frame, captured once instead of every frame forever. The normal sample piggybacks on the SAME per-frame
- * per-vertex loop the position sample already runs (incremental cost on an already-running pass, not a
- * second bake pass), per the row's explicit guidance.
- */
-export function bakeVAT(skinnedMesh, mixerRoot, clip, opts = {}) {
-  const sampleHz = opts.sampleHz || VAT_SAMPLE_HZ
-  const geometry = skinnedMesh.geometry
-  const posAttr = geometry.attributes.position
-  const normalAttr = geometry.attributes.normal
-  const hasNormals = !!normalAttr
-  const vertexCount = posAttr.count
-  const dt = 1 / sampleHz
-  const frameCount = Math.max(2, Math.ceil(clip.duration * sampleHz) + 1)
-
-  const mixer = new THREE.AnimationMixer(mixerRoot)
-  const action = mixer.clipAction(clip)
-  action.play()
-  action.paused = true
-
-  // Cap texture width at a hardware-safe size; vertexCount for a typical VRM body mesh (a few thousand)
-  // comfortably fits one row, so this only matters for an unusually dense source mesh.
-  const maxTexSize = opts.maxTexSize || 4096
-  const width = Math.min(vertexCount, maxTexSize)
-  const rowsPerFrame = Math.ceil(vertexCount / width)
-  const height = frameCount * rowsPerFrame
-
-  const data = new Float32Array(width * height * 4)
-  const normalData = hasNormals ? new Float32Array(width * height * 4) : null
-  const _bindNrm = new THREE.Vector3()
-
-  for (let f = 0; f < frameCount; f++) {
-    const t = Math.min(f * dt, clip.duration)
-    action.time = t
-    mixer.update(0) // 0-dt update after directly setting action.time -- applies the pose for this exact sample time without accumulating drift
-    // mixer.update only writes the new LOCAL bone quaternion/position; matrixWorld (what boneTransformInto
-    // actually reads) is stale until the hierarchy is re-propagated. skeleton.update() alone is NOT enough
-    // -- it recomputes boneMatrices FROM bone.matrixWorld, so a missing updateMatrixWorld here silently
-    // bakes every frame at the bind pose (found live: frame-0 delta was a large CONSTANT offset instead of
-    // ~0, traced to exactly this missing call).
-    mixerRoot.updateMatrixWorld(true)
-    skinnedMesh.skeleton.update()
-    for (let vi = 0; vi < vertexCount; vi++) {
-      boneTransformInto(skinnedMesh, vi, _vtmp)
-      _bindPos.fromBufferAttribute(posAttr, vi)
-      const row = f * rowsPerFrame + Math.floor(vi / width)
-      const col = vi % width
-      const idx = (row * width + col) * 4
-      data[idx] = _vtmp.x - _bindPos.x
-      data[idx + 1] = _vtmp.y - _bindPos.y
-      data[idx + 2] = _vtmp.z - _bindPos.z
-      data[idx + 3] = 1
-      if (hasNormals) {
-        boneTransformNormalInto(skinnedMesh, vi, _skinnedNrm)
-        _bindNrm.fromBufferAttribute(normalAttr, vi)
-        normalData[idx] = _skinnedNrm.x - _bindNrm.x
-        normalData[idx + 1] = _skinnedNrm.y - _bindNrm.y
-        normalData[idx + 2] = _skinnedNrm.z - _bindNrm.z
-        normalData[idx + 3] = 1
-      }
-    }
-  }
-
-  mixer.stopAllAction()
-  mixer.uncacheAction(clip, mixerRoot)
-
-  const texture = new THREE.DataTexture(data, width, height, THREE.RGBAFormat, THREE.FloatType)
-  texture.needsUpdate = true
-  texture.minFilter = THREE.NearestFilter
-  texture.magFilter = THREE.NearestFilter
-  texture.wrapS = THREE.ClampToEdgeWrapping
-  texture.wrapT = THREE.ClampToEdgeWrapping
-  texture.generateMipmaps = false
-
-  let normalTexture = null
-  if (hasNormals) {
-    normalTexture = new THREE.DataTexture(normalData, width, height, THREE.RGBAFormat, THREE.FloatType)
-    normalTexture.needsUpdate = true
-    normalTexture.minFilter = THREE.NearestFilter
-    normalTexture.magFilter = THREE.NearestFilter
-    normalTexture.wrapS = THREE.ClampToEdgeWrapping
-    normalTexture.wrapT = THREE.ClampToEdgeWrapping
-    normalTexture.generateMipmaps = false
-  }
-
-  return { texture, normalTexture, frameCount, vertexCount, width, rowsPerFrame, duration: clip.duration, sampleHz }
-}
-
-/**
- * Bakes MULTIPLE clips against the same skinnedMesh/mixerRoot into independent VAT textures sharing one
- * vertex-index layout (same skinnedMesh.geometry -> same vatVertexIndex attribute works for all of them).
- * `clipsByName` is a Map/plain-object of name -> THREE.AnimationClip; `names` picks which entries to bake
- * and in what order (defaults to every key). Returns { idle, move, names, ... } -- `idle` and `move` are
- * the first two baked vatData results (the only two createVATCrowdRenderer's blend path consumes today),
- * plus `byName` for direct lookup if more than 2 are ever baked.
- */
-export function bakeVATMultiClip(skinnedMesh, mixerRoot, clipsByName, opts = {}) {
-  const entries = clipsByName instanceof Map ? Array.from(clipsByName.entries()) : Object.entries(clipsByName)
-  const names = opts.names || entries.map(([n]) => n)
-  const byName = {}
-  for (const name of names) {
-    const clip = clipsByName instanceof Map ? clipsByName.get(name) : clipsByName[name]
-    if (!clip) continue
-    byName[name] = bakeVAT(skinnedMesh, mixerRoot, clip, opts)
-  }
-  const baked = names.map(n => byName[n]).filter(Boolean)
-  return { idle: baked[0] || null, move: baked[1] || baked[0] || null, names, byName }
-}
+// Bake pipeline (bakeVAT/bakeVATMultiClip) lives in PlayerVATBake.js -- re-exported here for backward
+// compatibility with app.js's existing single-file import.
+export { bakeVAT, bakeVATMultiClip }
 
 // --- GPU crowd material -------------------------------------------------------------------------------
 // Builds a MeshLambertMaterial patched (onBeforeCompile) to displace `position` by a VAT-sampled delta

package/client/core/PlayerVATBake.js

@@ -0,0 +1,230 @@
+// Baked vertex-animation-texture (VAT) bake pipeline: samples a real THREE.AnimationMixer at a fixed
+// rate and encodes post-skin position+normal deltas into float DataTextures. Split from PlayerVAT.js --
+// the GPU crowd material/renderer that CONSUMES these bakes stays there. See that file's own header for
+// the full VAT design rationale (why this exists, multi-clip blend, normal-delta lighting follow-on).
+
+import * as THREE from 'three'
+
+// window.__tickAnimTiming / _tickAnimSamples live in app.js (the actual call site) -- this module only
+// consumes the resulting bake/renderer, it doesn't own the timing surface.
+
+const VAT_SAMPLE_HZ = 24 // resample rate baked into the texture; independent of the source clip's authored keyframe spacing (same discipline as AnimationClipCache.js's RESAMPLE_HZ)
+
+const _vtmp = new THREE.Vector3()
+const _baseVec = new THREE.Vector3()
+const _bindPos = new THREE.Vector3()
+const _boneMtx = new THREE.Matrix4()
+/**
+ * Computes the post-skin world-space (mesh-local-space, i.e. relative to the SkinnedMesh's own
+ * unmoved transform) position of vertex `vi` on `skinnedMesh` at its CURRENT pose (caller must have
+ * already advanced the driving AnimationMixer + called skeleton.update() before calling this).
+ * Exactly mirrors THREE.SkinnedMesh.applyBoneTransform's own CPU skin math (see
+ * three/src/objects/SkinnedMesh.js): baseVector = bindPos * bindMatrix, accumulate per-bone
+ * (bone.matrixWorld * boneInverse) * baseVector weighted, then multiply by bindMatrixInverse -- NOT the
+ * skeleton's own precomputed boneMatrices array directly (that buffer already premultiplies bindMatrix
+ * differently for GPU upload; reproducing the CPU-path formula verbatim, bone-by-bone, is what keeps
+ * this bake bit-identical to what the GPU skinning path would have rendered).
+ */
+function boneTransformInto(skinnedMesh, vi, target) {
+  const geometry = skinnedMesh.geometry
+  const skeleton = skinnedMesh.skeleton
+  const posAttr = geometry.attributes.position
+  const skinIndex = geometry.attributes.skinIndex
+  const skinWeight = geometry.attributes.skinWeight
+  // _baseVec is a SEPARATE scratch from `target` -- target is caller-supplied and may alias a module-level
+  // scratch (bakeVAT passes _vtmp as target); reusing the same scratch for the internal base-vector AND the
+  // output accumulator caused target.set(0,0,0) below to wipe the base vector before it was consumed
+  // (found live: every baked frame read back as the raw un-skinned bind pose, a large CONSTANT delta at
+  // "frame 0" that should have been ~0 -- traced to exactly this aliasing bug).
+  _baseVec.fromBufferAttribute(posAttr, vi).applyMatrix4(skinnedMesh.bindMatrix)
+  target.set(0, 0, 0)
+  for (let j = 0; j < 4; j++) {
+    const weight = skinWeight.getComponent(vi, j)
+    if (weight === 0) continue
+    const boneIndex = skinIndex.getComponent(vi, j)
+    _boneMtx.multiplyMatrices(skeleton.bones[boneIndex].matrixWorld, skeleton.boneInverses[boneIndex])
+    const p = _baseVec.clone().applyMatrix4(_boneMtx)
+    target.x += p.x * weight; target.y += p.y * weight; target.z += p.z * weight
+  }
+  target.applyMatrix4(skinnedMesh.bindMatrixInverse)
+  return target
+}
+
+const _baseNrm = new THREE.Vector3()
+const _skinnedNrm = new THREE.Vector3()
+const _skinMtx = new THREE.Matrix4()
+const _accumMtx = new THREE.Matrix4()
+const _weightedMtx = new THREE.Matrix4()
+/**
+ * Computes the post-skin (mesh-local-space) NORMAL of vertex `vi` at the CURRENT pose, writing it into
+ * `target`. Mirrors three's own GPU `skinnormal_vertex` chunk (see
+ * three/src/renderers/shaders/ShaderChunk/skinnormal_vertex.glsl.js) verbatim rather than a generic
+ * inverse-transpose normal-matrix recompute: skinMatrix = bindMatrixInverse * (per-bone-weighted sum of
+ * boneMatrices) * bindMatrix, then objectNormal = skinMatrix * vec4(objectNormal, 0.0) -- a plain LINEAR
+ * transform (w=0, no translation row), NOT a proper inverse-transpose normal-matrix; GPU skinning doesn't
+ * correct for non-uniform scale either, so reproducing that exact (non-)correction is what keeps this
+ * bake bit-identical to what the GPU skinning path would have rendered, same discipline as
+ * boneTransformInto above. Matrix summation IS valid here (not an approximation): matrix multiplication
+ * is linear, so sum(w_i * M_i) * v === sum(w_i * (M_i * v)) for any v -- weighting the MATRICES first
+ * (like the GPU chunk does) and weighting the TRANSFORMED VECTORS first (like boneTransformInto does for
+ * position) are mathematically identical; the position path already accumulates transformed vectors, this
+ * one accumulates the matrices per source verbatim to mirror the shader chunk line-for-line for easy
+ * cross-reference, both are correct.
+ */
+function boneTransformNormalInto(skinnedMesh, vi, target) {
+  const geometry = skinnedMesh.geometry
+  const skeleton = skinnedMesh.skeleton
+  const normalAttr = geometry.attributes.normal
+  const skinIndex = geometry.attributes.skinIndex
+  const skinWeight = geometry.attributes.skinWeight
+  _baseNrm.fromBufferAttribute(normalAttr, vi)
+  _accumMtx.set(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0) // zero matrix accumulator (skinMatrix += ...)
+  for (let j = 0; j < 4; j++) {
+    const weight = skinWeight.getComponent(vi, j)
+    if (weight === 0) continue
+    const boneIndex = skinIndex.getComponent(vi, j)
+    _boneMtx.multiplyMatrices(skeleton.bones[boneIndex].matrixWorld, skeleton.boneInverses[boneIndex])
+    _weightedMtx.copy(_boneMtx)
+    for (let k = 0; k < 16; k++) _weightedMtx.elements[k] *= weight
+    for (let k = 0; k < 16; k++) _accumMtx.elements[k] += _weightedMtx.elements[k]
+  }
+  _skinMtx.multiplyMatrices(skinnedMesh.bindMatrixInverse, _accumMtx)
+  _skinMtx.multiply(skinnedMesh.bindMatrix)
+  // Deliberately NOT Vector3.transformDirection (it normalizes) -- the GPU skinnormal_vertex chunk this
+  // mirrors does a plain un-normalized mat4*vec4(n,0) transform; normalize_vertex/normal_fragment_begin
+  // downstream normalize exactly once, after normalMatrix + instancing are also applied, so normalizing
+  // here would double-normalize a not-yet-fully-transformed intermediate and desync from what the GPU
+  // skinning path (and this bake's own bit-identical-parity goal) actually produces.
+  const e = _skinMtx.elements
+  target.set(
+    e[0] * _baseNrm.x + e[4] * _baseNrm.y + e[8] * _baseNrm.z,
+    e[1] * _baseNrm.x + e[5] * _baseNrm.y + e[9] * _baseNrm.z,
+    e[2] * _baseNrm.x + e[6] * _baseNrm.y + e[10] * _baseNrm.z
+  )
+  return target
+}
+
+/**
+ * Bakes `clip` on `skinnedMesh` (must already be skeleton-bound, i.e. skinnedMesh.skeleton is the real
+ * pose skeleton, bindMatrixInverse set) into a VAT DataTexture pair. Returns
+ * {texture, normalTexture, frameCount, vertexCount, duration, sampleHz} -- both textures are
+ * (vertexCount wide) x (frameCount tall), RGBA32F, same (vertexIndex, frame) texel addressing. `texture`'s
+ * rgb = (post-skin - bind-pose) POSITION delta for that vertex at that sampled frame (unchanged from the
+ * first slice). `normalTexture`'s rgb = (post-skin - bind-pose) un-normalized NORMAL delta (see
+ * boneTransformNormalInto's header for why it's deliberately un-normalized), animation-vat-normal-delta-
+ * lighting's follow-on: sampling+adding this alongside the position delta lets REDUCED-tier crowd
+ * lighting respond to the animated pose instead of shading against the static bind-pose normal baked into
+ * the base geometry. Alpha unused on both (reserved, kept at 1 so non-EXT_color_buffer_float readback
+ * tooling still sees a valid alpha channel). normalTexture is null if the source mesh has no `normal`
+ * attribute (degrades to the pre-existing bind-pose-normal-only behavior, same as before this follow-on).
+ *
+ * Runs on a REAL THREE.AnimationMixer bound to the mesh's root (mixer.clipAction(clip).play()),
+ * advancing mixer.update(dt) at VAT_SAMPLE_HZ and reading back the real post-skin vertex positions (and
+ * normals) each step -- not an approximation, the literal same CPU skin math THREE performs to render a
+ * frame, captured once instead of every frame forever. The normal sample piggybacks on the SAME per-frame
+ * per-vertex loop the position sample already runs (incremental cost on an already-running pass, not a
+ * second bake pass), per the row's explicit guidance.
+ */
+export function bakeVAT(skinnedMesh, mixerRoot, clip, opts = {}) {
+  const sampleHz = opts.sampleHz || VAT_SAMPLE_HZ
+  const geometry = skinnedMesh.geometry
+  const posAttr = geometry.attributes.position
+  const normalAttr = geometry.attributes.normal
+  const hasNormals = !!normalAttr
+  const vertexCount = posAttr.count
+  const dt = 1 / sampleHz
+  const frameCount = Math.max(2, Math.ceil(clip.duration * sampleHz) + 1)
+
+  const mixer = new THREE.AnimationMixer(mixerRoot)
+  const action = mixer.clipAction(clip)
+  action.play()
+  action.paused = true
+
+  // Cap texture width at a hardware-safe size; vertexCount for a typical VRM body mesh (a few thousand)
+  // comfortably fits one row, so this only matters for an unusually dense source mesh.
+  const maxTexSize = opts.maxTexSize || 4096
+  const width = Math.min(vertexCount, maxTexSize)
+  const rowsPerFrame = Math.ceil(vertexCount / width)
+  const height = frameCount * rowsPerFrame
+
+  const data = new Float32Array(width * height * 4)
+  const normalData = hasNormals ? new Float32Array(width * height * 4) : null
+  const _bindNrm = new THREE.Vector3()
+
+  for (let f = 0; f < frameCount; f++) {
+    const t = Math.min(f * dt, clip.duration)
+    action.time = t
+    mixer.update(0) // 0-dt update after directly setting action.time -- applies the pose for this exact sample time without accumulating drift
+    // mixer.update only writes the new LOCAL bone quaternion/position; matrixWorld (what boneTransformInto
+    // actually reads) is stale until the hierarchy is re-propagated. skeleton.update() alone is NOT enough
+    // -- it recomputes boneMatrices FROM bone.matrixWorld, so a missing updateMatrixWorld here silently
+    // bakes every frame at the bind pose (found live: frame-0 delta was a large CONSTANT offset instead of
+    // ~0, traced to exactly this missing call).
+    mixerRoot.updateMatrixWorld(true)
+    skinnedMesh.skeleton.update()
+    for (let vi = 0; vi < vertexCount; vi++) {
+      boneTransformInto(skinnedMesh, vi, _vtmp)
+      _bindPos.fromBufferAttribute(posAttr, vi)
+      const row = f * rowsPerFrame + Math.floor(vi / width)
+      const col = vi % width
+      const idx = (row * width + col) * 4
+      data[idx] = _vtmp.x - _bindPos.x
+      data[idx + 1] = _vtmp.y - _bindPos.y
+      data[idx + 2] = _vtmp.z - _bindPos.z
+      data[idx + 3] = 1
+      if (hasNormals) {
+        boneTransformNormalInto(skinnedMesh, vi, _skinnedNrm)
+        _bindNrm.fromBufferAttribute(normalAttr, vi)
+        normalData[idx] = _skinnedNrm.x - _bindNrm.x
+        normalData[idx + 1] = _skinnedNrm.y - _bindNrm.y
+        normalData[idx + 2] = _skinnedNrm.z - _bindNrm.z
+        normalData[idx + 3] = 1
+      }
+    }
+  }
+
+  mixer.stopAllAction()
+  mixer.uncacheAction(clip, mixerRoot)
+
+  const texture = new THREE.DataTexture(data, width, height, THREE.RGBAFormat, THREE.FloatType)
+  texture.needsUpdate = true
+  texture.minFilter = THREE.NearestFilter
+  texture.magFilter = THREE.NearestFilter
+  texture.wrapS = THREE.ClampToEdgeWrapping
+  texture.wrapT = THREE.ClampToEdgeWrapping
+  texture.generateMipmaps = false
+
+  let normalTexture = null
+  if (hasNormals) {
+    normalTexture = new THREE.DataTexture(normalData, width, height, THREE.RGBAFormat, THREE.FloatType)
+    normalTexture.needsUpdate = true
+    normalTexture.minFilter = THREE.NearestFilter
+    normalTexture.magFilter = THREE.NearestFilter
+    normalTexture.wrapS = THREE.ClampToEdgeWrapping
+    normalTexture.wrapT = THREE.ClampToEdgeWrapping
+    normalTexture.generateMipmaps = false
+  }
+
+  return { texture, normalTexture, frameCount, vertexCount, width, rowsPerFrame, duration: clip.duration, sampleHz }
+}
+
+/**
+ * Bakes MULTIPLE clips against the same skinnedMesh/mixerRoot into independent VAT textures sharing one
+ * vertex-index layout (same skinnedMesh.geometry -> same vatVertexIndex attribute works for all of them).
+ * `clipsByName` is a Map/plain-object of name -> THREE.AnimationClip; `names` picks which entries to bake
+ * and in what order (defaults to every key). Returns { idle, move, names, ... } -- `idle` and `move` are
+ * the first two baked vatData results (the only two createVATCrowdRenderer's blend path consumes today),
+ * plus `byName` for direct lookup if more than 2 are ever baked.
+ */
+export function bakeVATMultiClip(skinnedMesh, mixerRoot, clipsByName, opts = {}) {
+  const entries = clipsByName instanceof Map ? Array.from(clipsByName.entries()) : Object.entries(clipsByName)
+  const names = opts.names || entries.map(([n]) => n)
+  const byName = {}
+  for (const name of names) {
+    const clip = clipsByName instanceof Map ? clipsByName.get(name) : clipsByName[name]
+    if (!clip) continue
+    byName[name] = bakeVAT(skinnedMesh, mixerRoot, clip, opts)
+  }
+  const baked = names.map(n => byName[n]).filter(Boolean)
+  return { idle: baked[0] || null, move: baked[1] || baked[0] || null, names, byName }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spoint",
-  "version": "0.1.650",
+  "version": "0.1.652",
   "description": "Physics and netcode SDK for multiplayer game servers",
   "type": "module",
   "workspaces": [

package/src/sdk/StaticCache.js

@@ -0,0 +1,281 @@
+// Byte-budgeted LRU caching + gzip/brotli compression infrastructure for StaticHandler.js's static
+// file server: raw file bytes, compressed variants, and transformed (GLB/VRM-optimized) variants.
+// No HTTP request/response handling here -- pure caching/compression, split out for a smaller,
+// single-responsibility file.
+
+import { readFileSync, existsSync, statSync, writeFileSync, readdirSync } from 'node:fs'
+import { join, extname, sep } from 'node:path'
+import { gzipSync, brotliCompressSync, gzip, brotliCompress, constants as zlibConstants } from 'node:zlib'
+import { promisify } from 'node:util'
+
+// quality 5: q11 default is 100x+ slower for marginal gain; q5 still beats gzip -6 by ~14% (measured on anim-lib.glb)
+const BROTLI_OPTS = { params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 5 } }
+
+const gzipAsync = promisify(gzip)
+const brotliCompressAsync = promisify(brotliCompress)
+
+// Below this size, the sync zlib call costs sub-millisecond -- not worth the promise/microtask
+// overhead, and small-file callers (e.g. tests driving the handler with a bare mock `res` and
+// reading `res` synchronously right after the call returns) rely on the response being written
+// before the call returns. Above it (large JS bundles, GLB/VRM/wasm) sync compression can run
+// long enough to visibly stall the 128Hz tick sharing this event loop, so it goes through the
+// async zlib API instead.
+const ASYNC_COMPRESS_THRESHOLD = 50 * 1024
+
+export function compress(raw, encoding) {
+  return encoding === 'br' ? brotliCompressSync(raw, BROTLI_OPTS) : gzipSync(raw)
+}
+
+export async function compressAsync(raw, encoding) {
+  if (raw.length < ASYNC_COMPRESS_THRESHOLD) return compress(raw, encoding)
+  return encoding === 'br' ? brotliCompressAsync(raw, BROTLI_OPTS) : gzipAsync(raw)
+}
+
+// excludes already-compressed/high-entropy image formats; GLB/VRM/glTF still win since they carry uncompressed JSON+animation data
+export const GZIP_EXTENSIONS = new Set(['.glb', '.vrm', '.gltf', '.js', '.mjs', '.css', '.html', '.json'])
+
+// Raw bytes for anything bigger than this never enter the in-memory cache -- a single huge asset
+// (large baked GLB, video, etc) would otherwise dominate the byte budget and evict everything else
+// for one requester's benefit. Still served fine, just re-read from disk (OS page cache absorbs the
+// repeat cost) instead of being pinned in process memory.
+export const MAX_CACHEABLE_BYTES = 20 * 1024 * 1024
+
+// Total byte budget across both LRU caches combined (raw file bytes + compressed variants +
+// transformed/optimized GLB variants). Split proportionally isn't necessary -- one shared budget,
+// evicted oldest-first, keeps the accounting simple and self-balancing between the two caches.
+const CACHE_BYTE_BUDGET = 256 * 1024 * 1024
+
+// Minimal Map-based LRU: `Map` iterates insertion order, so a re-set on touch (delete+set) moves an
+// entry to the "most recently used" end for free, and eviction just shifts from the front.
+export class ByteBudgetLRU {
+  constructor(budget) {
+    this.budget = budget
+    this.bytes = 0
+    this.map = new Map()
+  }
+  _sizeOf(entry) {
+    // entry.raw for fileCache rows, entry.variants Map values, entry.content for pass-through rows
+    let n = entry.raw ? entry.raw.length : 0
+    if (entry.variants) for (const v of entry.variants.values()) n += v.length
+    if (entry.content) n += entry.content.length
+    return n
+  }
+  get(key) {
+    const entry = this.map.get(key)
+    if (!entry) return undefined
+    // touch: move to MRU position
+    this.map.delete(key)
+    this.map.set(key, entry)
+    return entry
+  }
+  set(key, entry) {
+    const prior = this.map.get(key)
+    if (prior) this.bytes -= this._sizeOf(prior)
+    this.map.delete(key)
+    this.map.set(key, entry)
+    this.bytes += this._sizeOf(entry)
+    this._evictOverBudget()
+  }
+  // call after mutating an entry already in the map in-place (e.g. adding a new compressed variant)
+  // so the tracked byte total stays accurate without a full re-set/re-promote.
+  resync(key) {
+    if (!this.map.has(key)) return
+    let total = 0
+    for (const entry of this.map.values()) total += this._sizeOf(entry)
+    this.bytes = total
+    this._evictOverBudget()
+  }
+  delete(key) {
+    const entry = this.map.get(key)
+    if (entry) this.bytes -= this._sizeOf(entry)
+    this.map.delete(key)
+  }
+  _evictOverBudget() {
+    while (this.bytes > this.budget && this.map.size > 0) {
+      const oldestKey = this.map.keys().next().value
+      this.delete(oldestKey)
+    }
+  }
+}
+
+export const fileCache = new ByteBudgetLRU(CACHE_BYTE_BUDGET)
+export const transformedCache = new ByteBudgetLRU(CACHE_BYTE_BUDGET)
+
+// Content-hash ETag for /node_modules: third-party deps are re-materialized byte-identical on every
+// redeploy (fresh `npm install`/checkout gives every file a NEW mtime even when its bytes didn't
+// change), so an mtime-based ETag (the general path below) forces a needless revalidation round-trip
+// on every redeploy. Hashing raw content instead means an unchanged file keeps the SAME ETag across
+// redeploys, so a client's cached copy still 304s. Same fnv1a-1a used by SnapshotEncoder.js for
+// dirty-detection -- non-cryptographic, fast, adequate for a weak validator (ETag is not a security
+// boundary). Cached per (path, mtime) so a warm process only hashes each file once; a real content
+// edit still gets a fresh mtime and recomputes.
+const _contentHashCache = new Map() // fp -> { mtime, hash }
+export function contentHashETag(fp, raw, mtime) {
+  const cached = _contentHashCache.get(fp)
+  if (cached && cached.mtime === mtime) return cached.hash
+  let hash = 2166136261
+  for (let i = 0; i < raw.length; i++) { hash ^= raw[i]; hash = Math.imul(hash, 16777619) }
+  const hex = (hash >>> 0).toString(16)
+  _contentHashCache.set(fp, { mtime, hash: hex })
+  return hex
+}
+export function isNodeModulesPath(fp) {
+  return fp.includes(sep + 'node_modules' + sep) || fp.endsWith(sep + 'node_modules')
+}
+
+const SIBLING_EXT = { br: '.br', gzip: '.gz' }
+
+// Disk-persisted sibling (<file>.br / <file>.gz next to the source) so a compressed variant
+// survives a process restart/redeploy instead of being recomputed from scratch every boot --
+// this is the actual "precompress at bake time" behavior; the in-memory Map above is still the
+// hot per-process cache layered on top so a warm process never touches disk twice for the same
+// (file, encoding) pair. A stale sibling (source mtime moved on) is detected via a ".meta" JSON
+// stamp recording the source mtime it was built from, same pattern as GLBTransformer's cache.
+function siblingPaths(fp, encoding) {
+  const ext = SIBLING_EXT[encoding]
+  return { body: fp + ext, meta: fp + ext + '.meta' }
+}
+
+function readSiblingIfFresh(fp, encoding, srcMtime) {
+  const { body, meta } = siblingPaths(fp, encoding)
+  if (!existsSync(body) || !existsSync(meta)) return null
+  try {
+    const m = JSON.parse(readFileSync(meta, 'utf8'))
+    if (m.srcMtime !== srcMtime) return null
+    return readFileSync(body)
+  } catch { return null }
+}
+
+function writeSibling(fp, encoding, srcMtime, content) {
+  const { body, meta } = siblingPaths(fp, encoding)
+  try {
+    writeFileSync(body, content)
+    writeFileSync(meta, JSON.stringify({ srcMtime }))
+  } catch { /* read-only fs (e.g. some CDN/edge mounts) -- in-memory cache above still serves fine */ }
+}
+
+// lazily-populated compressed variants keyed by encoding, so each of a br- and non-br-capable client pays the compression cost once
+export async function getCached(fp, ext, encoding) {
+  const key = fp
+  const mtime = statSync(fp).mtimeMs
+  let cached = fileCache.get(key)
+  const size = cached?.raw ? cached.raw.length : statSync(fp).size
+  const cacheable = size <= MAX_CACHEABLE_BYTES
+  if (!cached || cached.mtime !== mtime) {
+    const raw = readFileSync(fp)
+    cached = { mtime, raw, variants: new Map() }
+    if (raw.length <= MAX_CACHEABLE_BYTES) fileCache.set(key, cached)
+    else fileCache.delete(key)
+  }
+  const shouldCompress = encoding && GZIP_EXTENSIONS.has(ext) && cached.raw.length > 100
+  if (!shouldCompress) return { mtime: cached.mtime, content: cached.raw, encoding: null, raw: cached.raw }
+  let variant = cached.variants.get(encoding)
+  if (!variant) {
+    variant = readSiblingIfFresh(fp, encoding, cached.mtime)
+    if (!variant) {
+      variant = await compressAsync(cached.raw, encoding)
+      writeSibling(fp, encoding, cached.mtime, variant)
+    }
+    cached.variants.set(encoding, variant)
+    if (cacheable) fileCache.resync(key)
+  }
+  return { mtime: cached.mtime, content: variant, encoding, raw: cached.raw }
+}
+
+export async function getTransformedCached(fp, srcMtime, rawBuffer, encoding) {
+  let cached = transformedCache.get(fp)
+  if (!cached || cached.srcMtime !== srcMtime) {
+    cached = { srcMtime, variants: new Map(), raw: rawBuffer.length <= MAX_CACHEABLE_BYTES ? rawBuffer : null }
+    if (rawBuffer.length <= MAX_CACHEABLE_BYTES) transformedCache.set(fp, cached)
+    else transformedCache.delete(fp)
+  }
+  if (!encoding) return { srcMtime, content: rawBuffer, encoding: null }
+  let variant = cached.variants.get(encoding)
+  if (!variant) {
+    variant = await compressAsync(rawBuffer, encoding)
+    cached.variants.set(encoding, variant)
+    if (rawBuffer.length <= MAX_CACHEABLE_BYTES) transformedCache.resync(fp)
+  }
+  return { srcMtime, content: variant, encoding }
+}
+
+// Bake-time precompression: walk each mounted static dir and populate the .br/.gz disk siblings
+// for every GZIP_EXTENSIONS file up front, so the very first request for any given asset already
+// hits a warm sibling instead of paying brotli-q5 compression inline. Safe to call repeatedly
+// (mtime-gated, same as the lazy path) -- intended to run once at server boot, backgrounded.
+// A node_modules-rooted mount (third-party deps, can be 10⁴-10⁵ files) is deliberately excluded --
+// walking + brotli-compressing the whole dependency tree at boot is unbounded work for code this
+// app doesn't own; those files still compress fine on the lazy per-request path (getCached), just
+// without the boot-time head start. Same for any nested node_modules encountered mid-walk.
+const PREWARM_SKIP_DIRS = new Set(['node_modules', '.glb-cache', '.progressive-cache', '.git'])
+
+export async function prewarmCompression(dirs) {
+  let count = 0
+  async function walk(dir) {
+    let entries
+    try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return }
+    for (const e of entries) {
+      if (e.isDirectory() && PREWARM_SKIP_DIRS.has(e.name)) continue
+      const fp = join(dir, e.name)
+      if (e.isDirectory()) { await walk(fp); continue }
+      const ext = extname(e.name)
+      if (!GZIP_EXTENSIONS.has(ext)) continue
+      if (ext === '.br' || ext === '.gz') continue
+      try {
+        if (statSync(fp).size <= 100) continue
+        await getCached(fp, ext, 'br')
+        await getCached(fp, ext, 'gzip')
+        count++
+      } catch { /* unreadable file -- skip, request-time path still covers it */ }
+    }
+  }
+  for (const { dir, prefix } of dirs) {
+    if (prefix === '/node_modules/' || dir.endsWith(sep + 'node_modules') || dir.endsWith('/node_modules')) continue
+    await walk(dir)
+  }
+  return count
+}
+
+// Parses a single-range `Range: bytes=start-end` header (the only form browsers/download managers
+// send for a resumed GLB/wasm fetch; multi-range is not worth supporting here). Returns null for
+// anything absent/malformed/unsatisfiable so the caller falls back to a plain 200.
+export function parseRange(rangeHeader, totalSize) {
+  if (!rangeHeader || !rangeHeader.startsWith('bytes=')) return null
+  const spec = rangeHeader.slice(6).split(',')[0].trim()
+  const m = /^(\d*)-(\d*)$/.exec(spec)
+  if (!m) return null
+  let start, end
+  if (m[1] === '' && m[2] === '') return null
+  if (m[1] === '') {
+    // suffix range: last N bytes
+    const suffixLen = parseInt(m[2], 10)
+    if (!Number.isFinite(suffixLen) || suffixLen <= 0) return null
+    start = Math.max(0, totalSize - suffixLen)
+    end = totalSize - 1
+  } else {
+    start = parseInt(m[1], 10)
+    end = m[2] === '' ? totalSize - 1 : parseInt(m[2], 10)
+  }
+  if (!Number.isFinite(start) || !Number.isFinite(end) || start > end || start < 0 || start >= totalSize) return null
+  end = Math.min(end, totalSize - 1)
+  return { start, end }
+}
+
+// Range/206 is only meaningful against the UNCOMPRESSED body -- a byte offset into a brotli/gzip
+// stream is meaningless to the client, so a Range request always gets the identity encoding.
+export function serveRangeable(req, res, buf, headers) {
+  headers['Accept-Ranges'] = 'bytes'
+  const range = parseRange(req.headers['range'], buf.length)
+  if (!range) {
+    headers['Content-Length'] = buf.length
+    res.writeHead(200, headers)
+    res.end(buf)
+    return
+  }
+  const { start, end } = range
+  headers['Content-Range'] = `bytes ${start}-${end}/${buf.length}`
+  headers['Content-Length'] = end - start + 1
+  delete headers['ETag'] // ETag above was computed for the whole-file 200 case; a 206 still names the same resource via Content-Range so omit rather than mismatch
+  res.writeHead(206, headers)
+  res.end(buf.subarray(start, end + 1))
+}

package/src/sdk/StaticHandler.js

@@ -1,26 +1,18 @@
-import { readFileSync, existsSync, statSync, realpathSync, writeFileSync, readdirSync } from 'node:fs'
+import { existsSync, statSync, realpathSync } from 'node:fs'
 import { join, extname, resolve, sep } from 'node:path'
-import { gzipSync, brotliCompressSync, gzip, brotliCompress, constants as zlibConstants } from 'node:zlib'
-import { promisify } from 'node:util'
 import { getTransformedAsync, getTransformedHashAsync } from '../static/GLBTransformer.js'
 import { getProgressive, resolveBakedFile } from '../static/ProgressiveBake.js'
 import { getKtx2Extracted, resolveKtx2File } from '../static/KTX2Extract.js'
 import { buildFetchManifest } from '../static/FetchManifest.js'
 import { getServerIdentity } from '../sdk/ServerIdentity.js'
+import {
+  GZIP_EXTENSIONS, contentHashETag, isNodeModulesPath, getCached, getTransformedCached,
+  prewarmCompression, serveRangeable
+} from './StaticCache.js'
 
-// quality 5: q11 default is 100x+ slower for marginal gain; q5 still beats gzip -6 by ~14% (measured on anim-lib.glb)
-const BROTLI_OPTS = { params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 5 } }
-
-const gzipAsync = promisify(gzip)
-const brotliCompressAsync = promisify(brotliCompress)
-
-// Below this size, the sync zlib call costs sub-millisecond -- not worth the promise/microtask
-// overhead, and small-file callers (e.g. tests driving the handler with a bare mock `res` and
-// reading `res` synchronously right after the call returns) rely on the response being written
-// before the call returns. Above it (large JS bundles, GLB/VRM/wasm) sync compression can run
-// long enough to visibly stall the 128Hz tick sharing this event loop, so it goes through the
-// async zlib API instead.
-const ASYNC_COMPRESS_THRESHOLD = 50 * 1024
+// Re-exported from StaticCache.js for backward compatibility -- server.js/ServerBoot.js imports
+// prewarmCompression from this file's own path.
+export { prewarmCompression }
 
 function negotiateEncoding(req) {
   const ae = req.headers['accept-encoding'] || ''
@@ -29,15 +21,6 @@ function negotiateEncoding(req) {
   return null
 }
 
-function compress(raw, encoding) {
-  return encoding === 'br' ? brotliCompressSync(raw, BROTLI_OPTS) : gzipSync(raw)
-}
-
-async function compressAsync(raw, encoding) {
-  if (raw.length < ASYNC_COMPRESS_THRESHOLD) return compress(raw, encoding)
-  return encoding === 'br' ? brotliCompressAsync(raw, BROTLI_OPTS) : gzipAsync(raw)
-}
-
 const MIME_TYPES = {
   '.html': 'text/html', '.js': 'text/javascript', '.mjs': 'text/javascript', '.css': 'text/css',
   '.json': 'application/json', '.glb': 'model/gltf-binary', '.gltf': 'model/gltf+json', '.vrm': 'model/gltf-binary',
@@ -57,9 +40,6 @@ const MIME_TYPES = {
 // of GLBTransformer's separate transformed-bytes hash cache.
 const CONTENT_HASHED_EXTENSIONS = new Set(['.hf'])
 
-// excludes already-compressed/high-entropy image formats; GLB/VRM/glTF still win since they carry uncompressed JSON+animation data
-const GZIP_EXTENSIONS = new Set(['.glb', '.vrm', '.gltf', '.js', '.mjs', '.css', '.html', '.json'])
-
 // Extensions worth serving Range/206 for -- large downloadable binaries where a dropped connection
 // resuming from a byte offset beats re-downloading from zero. Text/JS assets are small and revalidated
 // per-request anyway, so Range support for them buys nothing and adds surface area. .ktx2 added for the
@@ -79,252 +59,6 @@ const RANGE_EXTENSIONS = new Set(['.glb', '.vrm', '.gltf', '.wasm', '.ktx2'])
 // would itself become a real bytes-on-the-wire cost paid before any hint work even starts.
 const EARLY_HINTS_MAX = 12
 
-// Raw bytes for anything bigger than this never enter the in-memory cache -- a single huge asset
-// (large baked GLB, video, etc) would otherwise dominate the byte budget and evict everything else
-// for one requester's benefit. Still served fine, just re-read from disk (OS page cache absorbs the
-// repeat cost) instead of being pinned in process memory.
-const MAX_CACHEABLE_BYTES = 20 * 1024 * 1024
-
-// Total byte budget across both LRU caches combined (raw file bytes + compressed variants +
-// transformed/optimized GLB variants). Split proportionally isn't necessary -- one shared budget,
-// evicted oldest-first, keeps the accounting simple and self-balancing between the two caches.
-const CACHE_BYTE_BUDGET = 256 * 1024 * 1024
-
-// Minimal Map-based LRU: `Map` iterates insertion order, so a re-set on touch (delete+set) moves an
-// entry to the "most recently used" end for free, and eviction just shifts from the front.
-class ByteBudgetLRU {
-  constructor(budget) {
-    this.budget = budget
-    this.bytes = 0
-    this.map = new Map()
-  }
-  _sizeOf(entry) {
-    // entry.raw for fileCache rows, entry.variants Map values, entry.content for pass-through rows
-    let n = entry.raw ? entry.raw.length : 0
-    if (entry.variants) for (const v of entry.variants.values()) n += v.length
-    if (entry.content) n += entry.content.length
-    return n
-  }
-  get(key) {
-    const entry = this.map.get(key)
-    if (!entry) return undefined
-    // touch: move to MRU position
-    this.map.delete(key)
-    this.map.set(key, entry)
-    return entry
-  }
-  set(key, entry) {
-    const prior = this.map.get(key)
-    if (prior) this.bytes -= this._sizeOf(prior)
-    this.map.delete(key)
-    this.map.set(key, entry)
-    this.bytes += this._sizeOf(entry)
-    this._evictOverBudget()
-  }
-  // call after mutating an entry already in the map in-place (e.g. adding a new compressed variant)
-  // so the tracked byte total stays accurate without a full re-set/re-promote.
-  resync(key) {
-    if (!this.map.has(key)) return
-    let total = 0
-    for (const entry of this.map.values()) total += this._sizeOf(entry)
-    this.bytes = total
-    this._evictOverBudget()
-  }
-  delete(key) {
-    const entry = this.map.get(key)
-    if (entry) this.bytes -= this._sizeOf(entry)
-    this.map.delete(key)
-  }
-  _evictOverBudget() {
-    while (this.bytes > this.budget && this.map.size > 0) {
-      const oldestKey = this.map.keys().next().value
-      this.delete(oldestKey)
-    }
-  }
-}
-
-const fileCache = new ByteBudgetLRU(CACHE_BYTE_BUDGET)
-const transformedCache = new ByteBudgetLRU(CACHE_BYTE_BUDGET)
-
-// Content-hash ETag for /node_modules: third-party deps are re-materialized byte-identical on every
-// redeploy (fresh `npm install`/checkout gives every file a NEW mtime even when its bytes didn't
-// change), so an mtime-based ETag (the general path below) forces a needless revalidation round-trip
-// on every redeploy. Hashing raw content instead means an unchanged file keeps the SAME ETag across
-// redeploys, so a client's cached copy still 304s. Same fnv1a-1a used by SnapshotEncoder.js for
-// dirty-detection -- non-cryptographic, fast, adequate for a weak validator (ETag is not a security
-// boundary). Cached per (path, mtime) so a warm process only hashes each file once; a real content
-// edit still gets a fresh mtime and recomputes.
-const _contentHashCache = new Map() // fp -> { mtime, hash }
-function contentHashETag(fp, raw, mtime) {
-  const cached = _contentHashCache.get(fp)
-  if (cached && cached.mtime === mtime) return cached.hash
-  let hash = 2166136261
-  for (let i = 0; i < raw.length; i++) { hash ^= raw[i]; hash = Math.imul(hash, 16777619) }
-  const hex = (hash >>> 0).toString(16)
-  _contentHashCache.set(fp, { mtime, hash: hex })
-  return hex
-}
-function isNodeModulesPath(fp) {
-  return fp.includes(sep + 'node_modules' + sep) || fp.endsWith(sep + 'node_modules')
-}
-
-const SIBLING_EXT = { br: '.br', gzip: '.gz' }
-
-// Disk-persisted sibling (<file>.br / <file>.gz next to the source) so a compressed variant
-// survives a process restart/redeploy instead of being recomputed from scratch every boot --
-// this is the actual "precompress at bake time" behavior; the in-memory Map above is still the
-// hot per-process cache layered on top so a warm process never touches disk twice for the same
-// (file, encoding) pair. A stale sibling (source mtime moved on) is detected via a ".meta" JSON
-// stamp recording the source mtime it was built from, same pattern as GLBTransformer's cache.
-function siblingPaths(fp, encoding) {
-  const ext = SIBLING_EXT[encoding]
-  return { body: fp + ext, meta: fp + ext + '.meta' }
-}
-
-function readSiblingIfFresh(fp, encoding, srcMtime) {
-  const { body, meta } = siblingPaths(fp, encoding)
-  if (!existsSync(body) || !existsSync(meta)) return null
-  try {
-    const m = JSON.parse(readFileSync(meta, 'utf8'))
-    if (m.srcMtime !== srcMtime) return null
-    return readFileSync(body)
-  } catch { return null }
-}
-
-function writeSibling(fp, encoding, srcMtime, content) {
-  const { body, meta } = siblingPaths(fp, encoding)
-  try {
-    writeFileSync(body, content)
-    writeFileSync(meta, JSON.stringify({ srcMtime }))
-  } catch { /* read-only fs (e.g. some CDN/edge mounts) -- in-memory cache above still serves fine */ }
-}
-
-// lazily-populated compressed variants keyed by encoding, so each of a br- and non-br-capable client pays the compression cost once
-async function getCached(fp, ext, encoding) {
-  const key = fp
-  const mtime = statSync(fp).mtimeMs
-  let cached = fileCache.get(key)
-  const size = cached?.raw ? cached.raw.length : statSync(fp).size
-  const cacheable = size <= MAX_CACHEABLE_BYTES
-  if (!cached || cached.mtime !== mtime) {
-    const raw = readFileSync(fp)
-    cached = { mtime, raw, variants: new Map() }
-    if (raw.length <= MAX_CACHEABLE_BYTES) fileCache.set(key, cached)
-    else fileCache.delete(key)
-  }
-  const shouldCompress = encoding && GZIP_EXTENSIONS.has(ext) && cached.raw.length > 100
-  if (!shouldCompress) return { mtime: cached.mtime, content: cached.raw, encoding: null, raw: cached.raw }
-  let variant = cached.variants.get(encoding)
-  if (!variant) {
-    variant = readSiblingIfFresh(fp, encoding, cached.mtime)
-    if (!variant) {
-      variant = await compressAsync(cached.raw, encoding)
-      writeSibling(fp, encoding, cached.mtime, variant)
-    }
-    cached.variants.set(encoding, variant)
-    if (cacheable) fileCache.resync(key)
-  }
-  return { mtime: cached.mtime, content: variant, encoding, raw: cached.raw }
-}
-
-async function getTransformedCached(fp, srcMtime, rawBuffer, encoding) {
-  let cached = transformedCache.get(fp)
-  if (!cached || cached.srcMtime !== srcMtime) {
-    cached = { srcMtime, variants: new Map(), raw: rawBuffer.length <= MAX_CACHEABLE_BYTES ? rawBuffer : null }
-    if (rawBuffer.length <= MAX_CACHEABLE_BYTES) transformedCache.set(fp, cached)
-    else transformedCache.delete(fp)
-  }
-  if (!encoding) return { srcMtime, content: rawBuffer, encoding: null }
-  let variant = cached.variants.get(encoding)
-  if (!variant) {
-    variant = await compressAsync(rawBuffer, encoding)
-    cached.variants.set(encoding, variant)
-    if (rawBuffer.length <= MAX_CACHEABLE_BYTES) transformedCache.resync(fp)
-  }
-  return { srcMtime, content: variant, encoding }
-}
-
-// Bake-time precompression: walk each mounted static dir and populate the .br/.gz disk siblings
-// for every GZIP_EXTENSIONS file up front, so the very first request for any given asset already
-// hits a warm sibling instead of paying brotli-q5 compression inline. Safe to call repeatedly
-// (mtime-gated, same as the lazy path) -- intended to run once at server boot, backgrounded.
-// A node_modules-rooted mount (third-party deps, can be 10⁴-10⁵ files) is deliberately excluded --
-// walking + brotli-compressing the whole dependency tree at boot is unbounded work for code this
-// app doesn't own; those files still compress fine on the lazy per-request path (getCached), just
-// without the boot-time head start. Same for any nested node_modules encountered mid-walk.
-const PREWARM_SKIP_DIRS = new Set(['node_modules', '.glb-cache', '.progressive-cache', '.git'])
-
-export async function prewarmCompression(dirs) {
-  let count = 0
-  async function walk(dir) {
-    let entries
-    try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return }
-    for (const e of entries) {
-      if (e.isDirectory() && PREWARM_SKIP_DIRS.has(e.name)) continue
-      const fp = join(dir, e.name)
-      if (e.isDirectory()) { await walk(fp); continue }
-      const ext = extname(e.name)
-      if (!GZIP_EXTENSIONS.has(ext)) continue
-      if (ext === '.br' || ext === '.gz') continue
-      try {
-        if (statSync(fp).size <= 100) continue
-        await getCached(fp, ext, 'br')
-        await getCached(fp, ext, 'gzip')
-        count++
-      } catch { /* unreadable file -- skip, request-time path still covers it */ }
-    }
-  }
-  for (const { dir, prefix } of dirs) {
-    if (prefix === '/node_modules/' || dir.endsWith(sep + 'node_modules') || dir.endsWith('/node_modules')) continue
-    await walk(dir)
-  }
-  return count
-}
-
-// Parses a single-range `Range: bytes=start-end` header (the only form browsers/download managers
-// send for a resumed GLB/wasm fetch; multi-range is not worth supporting here). Returns null for
-// anything absent/malformed/unsatisfiable so the caller falls back to a plain 200.
-function parseRange(rangeHeader, totalSize) {
-  if (!rangeHeader || !rangeHeader.startsWith('bytes=')) return null
-  const spec = rangeHeader.slice(6).split(',')[0].trim()
-  const m = /^(\d*)-(\d*)$/.exec(spec)
-  if (!m) return null
-  let start, end
-  if (m[1] === '' && m[2] === '') return null
-  if (m[1] === '') {
-    // suffix range: last N bytes
-    const suffixLen = parseInt(m[2], 10)
-    if (!Number.isFinite(suffixLen) || suffixLen <= 0) return null
-    start = Math.max(0, totalSize - suffixLen)
-    end = totalSize - 1
-  } else {
-    start = parseInt(m[1], 10)
-    end = m[2] === '' ? totalSize - 1 : parseInt(m[2], 10)
-  }
-  if (!Number.isFinite(start) || !Number.isFinite(end) || start > end || start < 0 || start >= totalSize) return null
-  end = Math.min(end, totalSize - 1)
-  return { start, end }
-}
-
-// Range/206 is only meaningful against the UNCOMPRESSED body -- a byte offset into a brotli/gzip
-// stream is meaningless to the client, so a Range request always gets the identity encoding.
-function serveRangeable(req, res, buf, headers) {
-  headers['Accept-Ranges'] = 'bytes'
-  const range = parseRange(req.headers['range'], buf.length)
-  if (!range) {
-    headers['Content-Length'] = buf.length
-    res.writeHead(200, headers)
-    res.end(buf)
-    return
-  }
-  const { start, end } = range
-  headers['Content-Range'] = `bytes ${start}-${end}/${buf.length}`
-  headers['Content-Length'] = end - start + 1
-  delete headers['ETag'] // ETag above was computed for the whole-file 200 case; a 206 still names the same resource via Content-Range so omit rather than mismatch
-  res.writeHead(206, headers)
-  res.end(buf.subarray(start, end + 1))
-}
-
 // buildEarlyHintsLinks(manifest) -> ARRAY of individual Link header value strings (one per hinted
 // entry: `<url>; rel=preload; as=X`), or null if there is nothing to hint (no worldDef, empty
 // manifest). Node's real res.writeEarlyHints({link}) contract requires `link` to be a string OR an