murow 0.0.71 → 0.0.73

package/dist/webgpu/esm/index.js

@@ -8,7 +8,7 @@ var std = { ..._std };
 import tgpu4 from "typegpu";
 import * as d4 from "typegpu/data";
 import { FreeList as FreeList2 } from "murow/core/free-list";
-import { Base2DRenderer } from "murow/renderer/base-2d-renderer";
+import { Base2DRenderer } from "murow/renderer";
 
 // src/core/constants.ts
 var DYNAMIC_OFFSET_PREV_X = 0;
@@ -527,6 +527,11 @@ function createSpriteFragment(_spriteLayout, textureLayout) {
 }
 
 // src/spritesheet/spritesheet.ts
+import {
+  computeGridUVs,
+  computeTexturePackerUVs,
+  loadImage
+} from "murow/renderer";
 var Spritesheet = class {
   constructor(id, texture, textureView, sampler, uvs, width, height) {
     this.id = id;
@@ -551,41 +556,6 @@ var Spritesheet = class {
     return this._height;
   }
 };
-function computeGridUVs(imageWidth, imageHeight, frameWidth, frameHeight) {
-  const cols = Math.floor(imageWidth / frameWidth);
-  const rows = Math.floor(imageHeight / frameHeight);
-  const uvs = [];
-  for (let row = 0; row < rows; row++) {
-    for (let col = 0; col < cols; col++) {
-      uvs.push({
-        minX: col * frameWidth / imageWidth,
-        minY: row * frameHeight / imageHeight,
-        maxX: (col + 1) * frameWidth / imageWidth,
-        maxY: (row + 1) * frameHeight / imageHeight
-      });
-    }
-  }
-  return uvs;
-}
-function computeTexturePackerUVs(data) {
-  const { w, h } = data.meta.size;
-  const uvs = [];
-  for (const key of Object.keys(data.frames)) {
-    const frame = data.frames[key].frame;
-    uvs.push({
-      minX: frame.x / w,
-      minY: frame.y / h,
-      maxX: (frame.x + frame.w) / w,
-      maxY: (frame.y + frame.h) / h
-    });
-  }
-  return uvs;
-}
-async function loadImage(url) {
-  const response = await fetch(url);
-  const blob = await response.blob();
-  return createImageBitmap(blob);
-}
 function createTextureFromBitmap(device, bitmap) {
   const texture = device.createTexture({
     size: [bitmap.width, bitmap.height, 1],
@@ -600,6 +570,9 @@ function createTextureFromBitmap(device, bitmap) {
   return { texture, view: texture.createView() };
 }
 
+// src/2d/renderer.ts
+import { parseSpritesheet } from "murow/renderer";
+
 // src/geometry/geometry-builder.ts
 import tgpu2 from "typegpu";
 
@@ -2078,9 +2051,23 @@ var ComputeBuilder = class {
 };
 
 // src/2d/renderer.ts
+var prefab2DHandles = /* @__PURE__ */ new WeakMap();
+function isPrefab2D(value) {
+  return value.type === "spritesheet";
+}
+function resolveSpritePrefabHandle(prefab) {
+  const h = prefab2DHandles.get(prefab);
+  if (!h) {
+    throw new Error(
+      `Prefab '${prefab.id}' has no GPU handle \u2014 has the renderer's init() been called with this bucket?`
+    );
+  }
+  return h;
+}
 var WebGPU2DRenderer = class extends Base2DRenderer {
   constructor(canvas, options) {
-    super(canvas, options);
+    const resolvedMaxSprites = options.maxSprites ?? options.maxInstances ?? 1024;
+    super(canvas, { ...options, maxSprites: resolvedMaxSprites });
     this.staticDirty = false;
     // Per-sheet bind groups
     this.sheetBindGroups = /* @__PURE__ */ new Map();
@@ -2089,12 +2076,13 @@ var WebGPU2DRenderer = class extends Base2DRenderer {
     this.uniformData = new Float32Array(20);
     this.resizeObserver = null;
     this.resizeCallbacks = [];
+    this._prefabs = options.prefabs ?? null;
     this.camera = new Camera2D(canvas.width || 800, canvas.height || 600);
-    this.freeList = new FreeList2(options.maxSprites);
-    this.batcher = new SparseBatcher(options.maxSprites);
-    this.dynamicData = new Float32Array(options.maxSprites * DYNAMIC_FLOATS_PER_SPRITE);
-    this.staticData = new Float32Array(options.maxSprites * STATIC_FLOATS_PER_SPRITE);
-    this.slotIndexData = new Uint32Array(options.maxSprites);
+    this.freeList = new FreeList2(resolvedMaxSprites);
+    this.batcher = new SparseBatcher(resolvedMaxSprites);
+    this.dynamicData = new Float32Array(resolvedMaxSprites * DYNAMIC_FLOATS_PER_SPRITE);
+    this.staticData = new Float32Array(resolvedMaxSprites * STATIC_FLOATS_PER_SPRITE);
+    this.slotIndexData = new Uint32Array(resolvedMaxSprites);
   }
   get device() {
     return this._device;
@@ -2148,9 +2136,25 @@ var WebGPU2DRenderer = class extends Base2DRenderer {
     this.rawStaticBuffer = this.root.unwrap(this.staticBuffer);
     this.rawSlotIndexBuffer = this.root.unwrap(this.slotIndexBuffer);
     this.rawUniformBuffer = this.root.unwrap(this.uniformBuffer);
+    if (this._prefabs) {
+      this.uploadPrefabBucket(this._prefabs);
+    }
     this.setupResizeObserver();
     this._initialized = true;
   }
+  /**
+   * Upload every prefab in the bucket to the GPU and stash the resulting
+   * SpritesheetHandle on each prefab so `bucket.get(id)` returns something
+   * usable as a sprite source.
+   */
+  uploadPrefabBucket(bucket) {
+    for (const prefab of bucket.entries()) {
+      if (prefab.type === "spritesheet") {
+        const handle = this.uploadParsedSpritesheet(prefab.parsed);
+        prefab2DHandles.set(prefab, handle);
+      }
+    }
+  }
   setupResizeObserver() {
     const supportsDevicePixelBox = (() => {
       try {
@@ -2204,24 +2208,22 @@ var WebGPU2DRenderer = class extends Base2DRenderer {
     this.resizeCallbacks.push(callback);
   }
   async loadSpritesheet(source) {
-    const bitmap = await loadImage(source.image);
-    const { texture, view } = createTextureFromBitmap(this._device, bitmap);
+    const parsed = await parseSpritesheet(source);
+    return this.uploadParsedSpritesheet(parsed);
+  }
+  /**
+   * Upload a previously-parsed spritesheet to the GPU. Returns a SpritesheetHandle.
+   * Splitting parse (CPU) from upload (GPU) lets callers parse spritesheets in parallel
+   * before a renderer exists.
+   */
+  uploadParsedSpritesheet(parsed) {
+    const { texture, view } = createTextureFromBitmap(this._device, parsed.bitmap);
     const sampler = this._device.createSampler({
       magFilter: "nearest",
       minFilter: "nearest"
     });
-    let uvs;
-    if (source.data) {
-      const resp = await fetch(source.data);
-      const json = await resp.json();
-      uvs = computeTexturePackerUVs(json);
-    } else if (source.frameWidth && source.frameHeight) {
-      uvs = computeGridUVs(bitmap.width, bitmap.height, source.frameWidth, source.frameHeight);
-    } else {
-      uvs = [{ minX: 0, minY: 0, maxX: 1, maxY: 1 }];
-    }
     const id = this.nextSheetId++;
-    const sheet = new Spritesheet(id, texture, view, sampler, uvs, bitmap.width, bitmap.height);
+    const sheet = new Spritesheet(id, texture, view, sampler, parsed.uvs, parsed.width, parsed.height);
     this.sheets.set(id, sheet);
     const bindGroup = this._device.createBindGroup({
       layout: this.rawTextureLayout,
@@ -2239,18 +2241,20 @@ var WebGPU2DRenderer = class extends Base2DRenderer {
       throw new Error(`Max sprites (${this.maxSprites}) reached`);
     const dynBase = slot * DYNAMIC_FLOATS_PER_SPRITE;
     const statBase = slot * STATIC_FLOATS_PER_SPRITE;
-    const x = opts.x ?? 0;
-    const y = opts.y ?? 0;
-    this.dynamicData[dynBase + DYNAMIC_OFFSET_PREV_X] = x;
-    this.dynamicData[dynBase + DYNAMIC_OFFSET_PREV_Y] = y;
-    this.dynamicData[dynBase + DYNAMIC_OFFSET_CURR_X] = x;
-    this.dynamicData[dynBase + DYNAMIC_OFFSET_CURR_Y] = y;
+    const sheet = isPrefab2D(opts.sheet) ? resolveSpritePrefabHandle(opts.sheet) : opts.sheet;
+    const [px, py] = opts.position ?? [0, 0];
+    this.dynamicData[dynBase + DYNAMIC_OFFSET_PREV_X] = px;
+    this.dynamicData[dynBase + DYNAMIC_OFFSET_PREV_Y] = py;
+    this.dynamicData[dynBase + DYNAMIC_OFFSET_CURR_X] = px;
+    this.dynamicData[dynBase + DYNAMIC_OFFSET_CURR_Y] = py;
     const rotation = opts.rotation ?? 0;
     this.dynamicData[dynBase + DYNAMIC_OFFSET_PREV_ROTATION] = rotation;
     this.dynamicData[dynBase + DYNAMIC_OFFSET_CURR_ROTATION] = rotation;
-    this.staticData[statBase + STATIC_OFFSET_SCALE_X] = opts.scaleX ?? 1;
-    this.staticData[statBase + STATIC_OFFSET_SCALE_Y] = opts.scaleY ?? 1;
-    const uv = opts.sheet.getUV(opts.sprite ?? 0);
+    const s = opts.scale;
+    const [sx, sy] = typeof s === "number" ? [s, s] : s ?? [1, 1];
+    this.staticData[statBase + STATIC_OFFSET_SCALE_X] = sx;
+    this.staticData[statBase + STATIC_OFFSET_SCALE_Y] = sy;
+    const uv = sheet.getUV(opts.sprite ?? 0);
     this.staticData[statBase + STATIC_OFFSET_UV_MIN_X] = uv.minX;
     this.staticData[statBase + STATIC_OFFSET_UV_MIN_Y] = uv.minY;
     this.staticData[statBase + STATIC_OFFSET_UV_MAX_X] = uv.maxX;
@@ -2265,12 +2269,12 @@ var WebGPU2DRenderer = class extends Base2DRenderer {
     this.staticData[statBase + STATIC_OFFSET_TINT_B] = tint[2];
     this.staticData[statBase + STATIC_OFFSET_TINT_A] = tint[3];
     this.staticDirty = true;
-    this.batcher.add(opts.layer ?? 0, opts.sheet.id, slot);
+    this.batcher.add(opts.layer ?? 0, sheet.id, slot);
     return new SpriteAccessor(
       this.dynamicData,
       this.staticData,
       slot,
-      opts.sheet.id,
+      sheet.id,
       () => {
         this.staticDirty = true;
       }
@@ -2392,9 +2396,112 @@ var WebGPU2DRenderer = class extends Base2DRenderer {
   }
 };
 
+// src/2d/animation.ts
+var AnimationController = class {
+  constructor() {
+    this.clips = [];
+    this.clipsByName = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Register an animation clip. Returns the clip ID.
+   */
+  loadClip(config) {
+    const id = this.clips.length;
+    const clip = {
+      id,
+      name: config.name,
+      frames: new Uint16Array(config.frames),
+      durations: new Float32Array(config.durations),
+      frameCount: config.frames.length,
+      totalDuration: config.durations.reduce((sum, d7) => sum + d7, 0),
+      loop: config.loop
+    };
+    this.clips.push(clip);
+    this.clipsByName.set(config.name, id);
+    return id;
+  }
+  /**
+   * Get a clip by name.
+   */
+  getClipId(name) {
+    const id = this.clipsByName.get(name);
+    if (id === void 0)
+      throw new Error(`Animation clip "${name}" not found`);
+    return id;
+  }
+  /**
+   * Get a clip by ID.
+   */
+  getClip(id) {
+    return this.clips[id];
+  }
+  /**
+   * Create a new animation state for an entity. This is the per-entity data
+   * that tracks playback progress. Store it however you like (flat array, component, etc).
+   */
+  createState(clipId, speed = 1, playing = true) {
+    return { clipId, frame: 0, time: 0, speed, playing };
+  }
+  /**
+   * Advance an animation state by deltaTime (in seconds).
+   * Returns the current sprite frame ID, or -1 if not playing.
+   * Zero allocations.
+   */
+  update(state, deltaTime) {
+    if (!state.playing) {
+      return this.clips[state.clipId].frames[state.frame];
+    }
+    const clip = this.clips[state.clipId];
+    state.time += deltaTime * state.speed * 1e3;
+    while (state.time >= clip.durations[state.frame]) {
+      state.time -= clip.durations[state.frame];
+      state.frame++;
+      if (state.frame >= clip.frameCount) {
+        if (clip.loop) {
+          state.frame = 0;
+        } else {
+          state.frame = clip.frameCount - 1;
+          state.playing = false;
+          break;
+        }
+      }
+    }
+    return clip.frames[state.frame];
+  }
+  /**
+   * Play a different clip on an existing state. Resets frame and time.
+   */
+  play(state, clipId, speed) {
+    state.clipId = clipId;
+    state.frame = 0;
+    state.time = 0;
+    state.playing = true;
+    if (speed !== void 0)
+      state.speed = speed;
+  }
+  /**
+   * Stop playback.
+   */
+  stop(state) {
+    state.playing = false;
+  }
+  /**
+   * Resume playback.
+   */
+  resume(state) {
+    state.playing = true;
+  }
+  /**
+   * Number of loaded clips.
+   */
+  get clipCount() {
+    return this.clips.length;
+  }
+};
+
 // src/3d/renderer.ts
 import tgpu6 from "typegpu";
-import { Base3DRenderer } from "murow/renderer/base-3d-renderer";
+import { Base3DRenderer } from "murow/renderer";
 import { FreeList as FreeList3 } from "murow/core/free-list";
 import { SparseBatcher as SparseBatcher2 } from "murow/core/sparse-batcher";
 
@@ -3039,750 +3146,102 @@ function createSkinnedMeshVertex(layout) {
   });
 }
 
-// src/core/math.ts
-function mat4IdentityNew() {
-  const m = new Float32Array(16);
-  m[0] = 1;
-  m[5] = 1;
-  m[10] = 1;
-  m[15] = 1;
-  return m;
-}
-function trsToMat4(tx, ty, tz, qx, qy, qz, qw, sx, sy, sz, dst, offset) {
-  const xx = qx * qx, yy = qy * qy, zz = qz * qz;
-  const xy = qx * qy, xz = qx * qz, yz = qy * qz;
-  const wx = qw * qx, wy = qw * qy, wz = qw * qz;
-  dst[offset] = (1 - 2 * (yy + zz)) * sx;
-  dst[offset + 1] = 2 * (xy + wz) * sx;
-  dst[offset + 2] = 2 * (xz - wy) * sx;
-  dst[offset + 3] = 0;
-  dst[offset + 4] = 2 * (xy - wz) * sy;
-  dst[offset + 5] = (1 - 2 * (xx + zz)) * sy;
-  dst[offset + 6] = 2 * (yz + wx) * sy;
-  dst[offset + 7] = 0;
-  dst[offset + 8] = 2 * (xz + wy) * sz;
-  dst[offset + 9] = 2 * (yz - wx) * sz;
-  dst[offset + 10] = (1 - 2 * (xx + yy)) * sz;
-  dst[offset + 11] = 0;
-  dst[offset + 12] = tx;
-  dst[offset + 13] = ty;
-  dst[offset + 14] = tz;
-  dst[offset + 15] = 1;
-}
-function nodeToMat4(node) {
-  const m = new Float32Array(16);
-  if (node.matrix) {
-    m.set(node.matrix);
-    return m;
-  }
-  const t = node.translation ?? [0, 0, 0];
-  const r = node.rotation ?? [0, 0, 0, 1];
-  const s = node.scale ?? [1, 1, 1];
-  trsToMat4(t[0], t[1], t[2], r[0], r[1], r[2], r[3], s[0], s[1], s[2], m, 0);
-  return m;
-}
-var _mulTemp = new Float32Array(16);
-function mat4Mul(a, aO, b, bO, dst, dO) {
-  for (let i = 0; i < 4; i++) {
-    for (let j = 0; j < 4; j++) {
-      _mulTemp[j * 4 + i] = a[aO + i] * b[bO + j * 4] + a[aO + 4 + i] * b[bO + j * 4 + 1] + a[aO + 8 + i] * b[bO + j * 4 + 2] + a[aO + 12 + i] * b[bO + j * 4 + 3];
-    }
-  }
-  dst.set(_mulTemp, dO);
-}
-function mat4MulNew(a, b) {
-  const o = new Float32Array(16);
-  for (let i = 0; i < 4; i++) {
-    for (let j = 0; j < 4; j++) {
-      o[j * 4 + i] = a[i] * b[j * 4] + a[4 + i] * b[j * 4 + 1] + a[8 + i] * b[j * 4 + 2] + a[12 + i] * b[j * 4 + 3];
-    }
-  }
-  return o;
-}
+// src/3d/renderer.ts
+import {
+  createPackedAnimationData,
+  packSkinAndAnimations,
+  parseGltf,
+  SkeletalAnimation
+} from "murow/renderer";
 
-// src/3d/gltf-skin-parser.ts
-function parseSkin(gltf, skinIndex, getAccessorData) {
-  const skin = gltf.skins[skinIndex];
-  const joints = skin.joints;
-  const jointCount = joints.length;
-  const ibmAccess = getAccessorData(skin.inverseBindMatrices);
-  const inverseBindMatrices = new Float32Array(ibmAccess.data);
-  const jointNodeIndices = new Uint16Array(joints);
-  const nodeToJoint = /* @__PURE__ */ new Map();
-  for (let j = 0; j < jointCount; j++) {
-    nodeToJoint.set(joints[j], j);
-  }
-  const nodeParent = /* @__PURE__ */ new Map();
-  for (let i = 0; i < gltf.nodes.length; i++) {
-    const children = gltf.nodes[i].children;
-    if (children) {
-      for (const child of children) {
-        nodeParent.set(child, i);
-      }
-    }
-  }
-  const parentJointIndices = new Int16Array(jointCount).fill(-1);
-  for (let j = 0; j < jointCount; j++) {
-    let parentNode = nodeParent.get(joints[j]);
-    while (parentNode !== void 0) {
-      const parentJoint = nodeToJoint.get(parentNode);
-      if (parentJoint !== void 0) {
-        parentJointIndices[j] = parentJoint;
-        break;
-      }
-      parentNode = nodeParent.get(parentNode);
-    }
-  }
-  let skeletonRootMatrix = null;
-  for (let j = 0; j < jointCount; j++) {
-    if (parentJointIndices[j] !== -1)
-      continue;
-    let ancestorNode = nodeParent.get(joints[j]);
-    const ancestorChain = [];
-    while (ancestorNode !== void 0 && !nodeToJoint.has(ancestorNode)) {
-      ancestorChain.push(ancestorNode);
-      ancestorNode = nodeParent.get(ancestorNode);
-    }
-    if (ancestorChain.length > 0) {
-      skeletonRootMatrix = mat4IdentityNew();
-      for (let i = ancestorChain.length - 1; i >= 0; i--) {
-        const nodeMat = nodeToMat4(gltf.nodes[ancestorChain[i]]);
-        skeletonRootMatrix = mat4MulNew(skeletonRootMatrix, nodeMat);
-      }
-    }
-    break;
+// src/3d/skeletal-animation-compute/packer.ts
+function packAnimationData(packed) {
+  const numSkins = packed.skins.length;
+  const numClips = packed.clips.length;
+  const numChannels = packed.channels.length;
+  const SKIN_ENTRY = 10;
+  const CLIP_ENTRY = 4;
+  const CH_ENTRY = 4;
+  const skinEnd = numSkins * SKIN_ENTRY;
+  const parentEnd = skinEnd + packed.parentIndices.length;
+  const topoEnd = parentEnd + packed.topoOrder.length;
+  const clipEnd = topoEnd + numClips * CLIP_ENTRY;
+  const channelEnd = clipEnd + numChannels * CH_ENTRY;
+  const jointLookupEnd = channelEnd + packed.jointChannelLookup.length;
+  const clipTableOffset = topoEnd;
+  const channelTableOffset = clipEnd;
+  const jointLookupOffset = channelEnd;
+  const skelI32 = new Int32Array(jointLookupEnd || 1);
+  for (let s = 0; s < numSkins; s++) {
+    const sk = packed.skins[s];
+    const base = s * SKIN_ENTRY;
+    skelI32[base + 0] = sk.jointCount;
+    skelI32[base + 1] = skinEnd + sk.parentOffset;
+    skelI32[base + 2] = parentEnd + sk.topoOffset;
+    skelI32[base + 3] = sk.ibmOffset;
+    skelI32[base + 4] = sk.restTRSOffset * 10;
+    skelI32[base + 5] = sk.skelRootMatIndex;
+    skelI32[base + 6] = sk.clipOffset;
+    skelI32[base + 7] = jointLookupOffset + sk.jointLookupStart;
+    skelI32[base + 8] = 0;
+    skelI32[base + 9] = 0;
   }
-  return {
-    jointCount,
-    jointNodeIndices,
-    inverseBindMatrices,
-    parentJointIndices,
-    skeletonRootMatrix
-  };
-}
-function parseAnimations(gltf, skinData, getAccessorData) {
-  if (!gltf.animations?.length)
-    return [];
-  const nodeToJoint = /* @__PURE__ */ new Map();
-  for (let j = 0; j < skinData.jointCount; j++) {
-    nodeToJoint.set(skinData.jointNodeIndices[j], j);
-  }
-  const clips = [];
-  for (const anim of gltf.animations) {
-    const channels = [];
-    let maxTime = 0;
-    for (const channel of anim.channels) {
-      const targetNode = channel.target.node;
-      const jointIndex = nodeToJoint.get(targetNode);
-      if (jointIndex === void 0)
-        continue;
-      const path = channel.target.path;
-      if (path !== "translation" && path !== "rotation" && path !== "scale")
-        continue;
-      const sampler = anim.samplers[channel.sampler];
-      const interpolation = sampler.interpolation ?? "LINEAR";
-      if (interpolation !== "LINEAR" && interpolation !== "STEP")
-        continue;
-      const inputAccess = getAccessorData(sampler.input);
-      const timestamps = new Float32Array(inputAccess.data);
-      const outputAccess = getAccessorData(sampler.output);
-      const values = new Float32Array(outputAccess.data);
-      if (timestamps.length > 0) {
-        const lastTime = timestamps[timestamps.length - 1];
-        if (lastTime > maxTime)
-          maxTime = lastTime;
-      }
-      channels.push({
-        jointIndex,
-        path,
-        timestamps,
-        values,
-        interpolation
-      });
-    }
-    if (channels.length > 0) {
-      clips.push({
-        name: anim.name ?? `animation_${clips.length}`,
-        duration: maxTime,
-        channels
-      });
-    }
+  for (let i = 0; i < packed.parentIndices.length; i++)
+    skelI32[skinEnd + i] = packed.parentIndices[i];
+  for (let i = 0; i < packed.topoOrder.length; i++)
+    skelI32[parentEnd + i] = packed.topoOrder[i];
+  const dv = new DataView(skelI32.buffer);
+  for (let c = 0; c < numClips; c++) {
+    const cl = packed.clips[c];
+    const base = topoEnd + c * CLIP_ENTRY;
+    skelI32[base + 0] = cl.channelStart;
+    skelI32[base + 1] = cl.channelCount;
+    dv.setFloat32(base * 4 + 8, cl.duration, true);
+    skelI32[base + 3] = cl.looping;
   }
-  return clips;
-}
-function parsePrimitiveSkinAttributes(primitive, getAccessorData) {
-  if (primitive.attributes.JOINTS_0 === void 0 || primitive.attributes.WEIGHTS_0 === void 0) {
-    return null;
+  for (let c = 0; c < numChannels; c++) {
+    const ch = packed.channels[c];
+    const base = clipEnd + c * CH_ENTRY;
+    skelI32[base + 0] = ch.jointIndex;
+    skelI32[base + 1] = ch.pathAndInterp;
+    skelI32[base + 2] = ch.keyframeCount;
+    skelI32[base + 3] = ch.dataOffset;
   }
-  const jointsAccess = getAccessorData(primitive.attributes.JOINTS_0);
-  const weightsAccess = getAccessorData(primitive.attributes.WEIGHTS_0);
-  const joints = jointsAccess.data instanceof Uint16Array ? jointsAccess.data : new Uint16Array(jointsAccess.data);
-  let weights;
-  if (weightsAccess.data instanceof Float32Array) {
-    weights = weightsAccess.data;
-  } else if (weightsAccess.data instanceof Uint8Array) {
-    weights = new Float32Array(weightsAccess.data.length);
-    for (let i = 0; i < weightsAccess.data.length; i++) {
-      weights[i] = weightsAccess.data[i] / 255;
-    }
-  } else if (weightsAccess.data instanceof Uint16Array) {
-    weights = new Float32Array(weightsAccess.data.length);
-    for (let i = 0; i < weightsAccess.data.length; i++) {
-      weights[i] = weightsAccess.data[i] / 65535;
-    }
-  } else {
-    weights = new Float32Array(weightsAccess.data);
+  for (let i = 0; i < packed.jointChannelLookup.length; i++) {
+    skelI32[channelEnd + i] = packed.jointChannelLookup[i];
   }
-  return { joints, weights };
-}
-function getNodeTRS(node) {
-  const trs = new Float32Array(10);
-  if (node.matrix) {
-    trs[0] = node.matrix[12];
-    trs[1] = node.matrix[13];
-    trs[2] = node.matrix[14];
-    trs[3] = 0;
-    trs[4] = 0;
-    trs[5] = 0;
-    trs[6] = 1;
-    trs[7] = 1;
-    trs[8] = 1;
-    trs[9] = 1;
-    return trs;
-  }
-  const t = node.translation ?? [0, 0, 0];
-  const r = node.rotation ?? [0, 0, 0, 1];
-  const s = node.scale ?? [1, 1, 1];
-  trs[0] = t[0];
-  trs[1] = t[1];
-  trs[2] = t[2];
-  trs[3] = r[0];
-  trs[4] = r[1];
-  trs[5] = r[2];
-  trs[6] = r[3];
-  trs[7] = s[0];
-  trs[8] = s[1];
-  trs[9] = s[2];
-  return trs;
-}
-function createPackedAnimationData() {
-  return {
-    channels: [],
-    keyframeData: [],
-    clips: [],
-    skins: [],
-    parentIndices: [],
-    topoOrder: [],
-    ibmData: [],
-    restTRS: [],
-    skelRootMats: [],
-    jointChannelLookup: []
-  };
-}
-function packSkinAndAnimations(packed, skinData, clips, gltfNodes) {
-  const skinIndex = packed.skins.length;
-  const jc = skinData.jointCount;
-  const parentOffset = packed.parentIndices.length;
-  const topoOffset = packed.topoOrder.length;
-  const ibmOffset = packed.ibmData.length / 16;
-  const restTRSOffset = packed.restTRS.length / 10;
-  const skelRootMatIndex = packed.skelRootMats.length / 16;
-  for (let j = 0; j < jc; j++) {
-    packed.parentIndices.push(skinData.parentJointIndices[j]);
-  }
-  const visited = new Uint8Array(jc);
-  const visit = (j) => {
-    if (visited[j])
-      return;
-    visited[j] = 1;
-    const parent = skinData.parentJointIndices[j];
-    if (parent !== -1)
-      visit(parent);
-    packed.topoOrder.push(j);
-  };
-  for (let j = 0; j < jc; j++)
-    visit(j);
-  for (let i = 0; i < skinData.inverseBindMatrices.length; i++) {
-    packed.ibmData.push(skinData.inverseBindMatrices[i]);
-  }
-  for (let j = 0; j < jc; j++) {
-    const trs = getNodeTRS(gltfNodes[skinData.jointNodeIndices[j]]);
-    for (let k = 0; k < 10; k++)
-      packed.restTRS.push(trs[k]);
-  }
-  if (skinData.skeletonRootMatrix) {
-    for (let i = 0; i < 16; i++)
-      packed.skelRootMats.push(skinData.skeletonRootMatrix[i]);
-  } else {
-    const id = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
-    for (let i = 0; i < 16; i++)
-      packed.skelRootMats.push(id[i]);
-  }
-  const clipOffset = packed.clips.length;
-  const jointLookupStart = packed.jointChannelLookup.length;
-  packed.skins.push({ jointCount: jc, parentOffset, topoOffset, ibmOffset, restTRSOffset, skelRootMatIndex, clipOffset, jointLookupStart });
-  const nodeToJoint = /* @__PURE__ */ new Map();
-  for (let j = 0; j < jc; j++) {
-    nodeToJoint.set(skinData.jointNodeIndices[j], j);
-  }
-  for (const clip of clips) {
-    const channelStart = packed.channels.length;
-    const sortedChannels = [...clip.channels].sort((a, b) => a.jointIndex - b.jointIndex);
-    for (const ch of sortedChannels) {
-      const pathCode = ch.path === "translation" ? 0 : ch.path === "rotation" ? 1 : 2;
-      const isStep = ch.interpolation === "STEP" ? 4 : 0;
-      const dataOffset = packed.keyframeData.length;
-      const n = ch.timestamps.length;
-      const compCount = ch.path === "rotation" ? 4 : 3;
-      for (let i = 0; i < n; i++)
-        packed.keyframeData.push(ch.timestamps[i]);
-      for (let i = 0; i < n * compCount; i++)
-        packed.keyframeData.push(ch.values[i]);
-      packed.channels.push({
-        jointIndex: ch.jointIndex,
-        pathAndInterp: pathCode | isStep,
-        keyframeCount: n,
-        dataOffset
-      });
-    }
-    const clipChannelCount = sortedChannels.length;
-    let ci = 0;
-    for (let j = 0; j < jc; j++) {
-      const lookupStart = ci;
-      while (ci < clipChannelCount && sortedChannels[ci].jointIndex === j)
-        ci++;
-      packed.jointChannelLookup.push(channelStart + lookupStart);
-      packed.jointChannelLookup.push(ci - lookupStart);
-    }
-    packed.clips.push({
-      channelStart,
-      channelCount: clipChannelCount,
-      duration: clip.duration,
-      looping: 1
-    });
+  const keyframeDataSize = packed.keyframeData.length;
+  const restTRSOffset = keyframeDataSize;
+  const animF32 = new Float32Array(keyframeDataSize + packed.restTRS.length || 1);
+  for (let i = 0; i < keyframeDataSize; i++)
+    animF32[i] = packed.keyframeData[i];
+  for (let i = 0; i < packed.restTRS.length; i++)
+    animF32[keyframeDataSize + i] = packed.restTRS[i];
+  const totalIBM = packed.ibmData.length / 16;
+  for (let s = 0; s < numSkins; s++) {
+    skelI32[s * SKIN_ENTRY + 5] += totalIBM;
+    skelI32[s * SKIN_ENTRY + 4] += restTRSOffset;
   }
-  return skinIndex;
-}
-
-// src/3d/skeletal-animation.ts
-var SkeletalAnimation = class {
-  // 16 floats, identity if no non-joint ancestors
-  constructor(skinData, clips, gltfNodes) {
-    this.clips = [];
-    this.clipsByName = /* @__PURE__ */ new Map();
-    this._scratchVec3 = new Float32Array(3);
-    this._scratchQuat = new Float32Array(4);
-    this.skinData = skinData;
-    const jc = skinData.jointCount;
-    this.localMatrices = new Float32Array(jc * 16);
-    this.worldMatrices = new Float32Array(jc * 16);
-    this.blendScratch = new Float32Array(jc * 16);
-    this.originalRestPoseTRS = new Float32Array(jc * 10);
-    this.currentTRS = new Float32Array(jc * 10);
-    for (let j = 0; j < jc; j++) {
-      const nodeTRS = getNodeTRS(gltfNodes[skinData.jointNodeIndices[j]]);
-      this.originalRestPoseTRS.set(nodeTRS, j * 10);
-    }
-    this.skelRootMat = new Float32Array(16);
-    if (skinData.skeletonRootMatrix) {
-      this.skelRootMat.set(skinData.skeletonRootMatrix);
-    } else {
-      this.skelRootMat[0] = 1;
-      this.skelRootMat[5] = 1;
-      this.skelRootMat[10] = 1;
-      this.skelRootMat[15] = 1;
-    }
-    this.topoOrder = new Uint16Array(jc);
-    const visited = new Uint8Array(jc);
-    let writeIdx = 0;
-    const visit = (j) => {
-      if (visited[j])
-        return;
-      visited[j] = 1;
-      const parent = skinData.parentJointIndices[j];
-      if (parent !== -1)
-        visit(parent);
-      this.topoOrder[writeIdx++] = j;
-    };
-    for (let j = 0; j < jc; j++)
-      visit(j);
-    for (const clip of clips) {
-      this.loadClip(clip);
-    }
-  }
-  loadClip(clip, loop = true) {
-    const id = this.clips.length;
-    this.clips.push({
-      id,
-      name: clip.name,
-      duration: clip.duration,
-      channels: clip.channels,
-      loop
-    });
-    this.clipsByName.set(clip.name, id);
-    return id;
-  }
-  getClipId(name) {
-    const id = this.clipsByName.get(name);
-    if (id === void 0)
-      throw new Error(`Skeletal clip "${name}" not found`);
-    return id;
-  }
-  getClipNames() {
-    return this.clips.map((c) => c.name);
-  }
-  getClip(id) {
-    return this.clips[id] ?? null;
-  }
-  get clipCount() {
-    return this.clips.length;
-  }
-  createState(clipIdOrName, speed = 1, playing = true) {
-    const clipId = typeof clipIdOrName === "string" ? this.getClipId(clipIdOrName) : clipIdOrName;
-    return { clipId, time: 0, speed, playing, loop: true, prevClipId: -1, prevTime: 0, prevSpeed: 1, blendWeight: 1, blendDuration: 0, onEnd: () => null };
-  }
-  play(state, clipIdOrName, opts) {
-    const newClipId = typeof clipIdOrName === "string" ? this.getClipId(clipIdOrName) : clipIdOrName;
-    const crossfade = opts?.crossfade ?? 0;
-    if (crossfade > 0 && state.playing) {
-      state.prevClipId = state.clipId;
-      state.prevTime = state.time;
-      state.prevSpeed = state.speed;
-      state.blendWeight = 0;
-      state.blendDuration = crossfade;
-    } else {
-      state.prevClipId = -1;
-      state.blendWeight = 1;
-      state.blendDuration = 0;
-    }
-    state.onEnd = opts?.onEnd ?? (() => null);
-    state.loop = opts?.loop ?? true;
-    state.clipId = newClipId;
-    state.time = 0;
-    state.playing = true;
-    if (opts?.speed !== void 0)
-      state.speed = opts.speed;
-  }
-  stop(state) {
-    state.playing = false;
-  }
-  resume(state) {
-    state.playing = true;
-  }
-  /**
-   * Advance time and compute bone matrices.
-   * Writes jointCount mat4s into `output` starting at float index `outputOffset`.
-   * Handles crossfade blending automatically.
-   */
-  update(state, deltaTime, output, outputOffset = 0) {
-    const jc = this.skinData.jointCount;
-    if (state.playing) {
-      this.advanceTime(state, deltaTime);
-    }
-    const blending = state.prevClipId !== -1 && state.blendDuration > 0 && state.blendWeight < 1;
-    if (blending) {
-      state.blendWeight += deltaTime / state.blendDuration;
-      if (state.blendWeight >= 1) {
-        state.blendWeight = 1;
-        state.prevClipId = -1;
-        state.blendDuration = 0;
-      }
-    }
-    if (blending && state.prevClipId !== -1) {
-      const prevClip = this.clips[state.prevClipId];
-      if (prevClip) {
-        state.prevTime += deltaTime * state.prevSpeed;
-        if (prevClip.loop && state.prevTime >= prevClip.duration) {
-          state.prevTime %= prevClip.duration;
-        }
-      }
-      this.evaluateClip(state.prevClipId, state.prevTime, this.blendScratch, 0);
-      this.evaluateClip(state.clipId, state.time, output, outputOffset);
-      const w = state.blendWeight;
-      const oneMinusW = 1 - w;
-      const scratch = this.blendScratch;
-      const floatCount = jc * 16;
-      for (let i = 0; i < floatCount; i++) {
-        output[outputOffset + i] = scratch[i] * oneMinusW + output[outputOffset + i] * w;
-      }
-    } else {
-      this.evaluateClip(state.clipId, state.time, output, outputOffset);
-    }
-  }
-  /** Advance clip time with looping/clamping. */
-  advanceTime(state, deltaTime) {
-    const clip = this.clips[state.clipId];
-    if (!clip || clip.duration <= 0)
-      return;
-    state.time += deltaTime * state.speed;
-    if (state.time >= clip.duration) {
-      if (clip.loop)
-        state.time %= clip.duration;
-      else {
-        state.time = clip.duration - 1e-4;
-        state.playing = false;
-      }
-    }
-    if (state.time < 0) {
-      if (clip.loop)
-        state.time = clip.duration + state.time % clip.duration;
-      else {
-        state.time = 0;
-        state.playing = false;
-      }
-    }
-  }
-  /** Evaluate a clip at a specific time and write bone matrices. */
-  evaluateClip(clipId, time, output, outputOffset) {
-    const clip = this.clips[clipId];
-    if (!clip)
-      return;
-    const skin = this.skinData;
-    const jc = skin.jointCount;
-    const local = this.localMatrices;
-    const world = this.worldMatrices;
-    const cur = this.currentTRS;
-    cur.set(this.originalRestPoseTRS);
-    for (const ch of clip.channels) {
-      const j = ch.jointIndex;
-      if (j >= jc)
-        continue;
-      const ro = j * 10;
-      const sampled = this.sampleChannel(ch, time);
-      if (ch.path === "translation") {
-        cur[ro] = sampled[0];
-        cur[ro + 1] = sampled[1];
-        cur[ro + 2] = sampled[2];
-      } else if (ch.path === "rotation") {
-        cur[ro + 3] = sampled[0];
-        cur[ro + 4] = sampled[1];
-        cur[ro + 5] = sampled[2];
-        cur[ro + 6] = sampled[3];
-      } else if (ch.path === "scale") {
-        cur[ro + 7] = sampled[0];
-        cur[ro + 8] = sampled[1];
-        cur[ro + 9] = sampled[2];
-      }
-    }
-    for (let j = 0; j < jc; j++) {
-      const ro = j * 10;
-      trsToMat4(
-        cur[ro],
-        cur[ro + 1],
-        cur[ro + 2],
-        cur[ro + 3],
-        cur[ro + 4],
-        cur[ro + 5],
-        cur[ro + 6],
-        cur[ro + 7],
-        cur[ro + 8],
-        cur[ro + 9],
-        local,
-        j * 16
-      );
-    }
-    const topo = this.topoOrder;
-    const srm = this.skelRootMat;
-    for (let i = 0; i < jc; i++) {
-      const j = topo[i];
-      const parentJ = skin.parentJointIndices[j];
-      if (parentJ === -1) {
-        mat4Mul(srm, 0, local, j * 16, world, j * 16);
-      } else {
-        mat4Mul(world, parentJ * 16, local, j * 16, world, j * 16);
-      }
-    }
-    const ibm = skin.inverseBindMatrices;
-    for (let j = 0; j < jc; j++) {
-      mat4Mul(world, j * 16, ibm, j * 16, output, outputOffset + j * 16);
-    }
-  }
-  /**
-   * Compute bone matrices for the rest/bind pose (no animation).
-   */
-  computeRestPose(output, outputOffset = 0) {
-    const skin = this.skinData;
-    const jc = skin.jointCount;
-    const local = this.localMatrices;
-    const world = this.worldMatrices;
-    const rest = this.originalRestPoseTRS;
-    for (let j = 0; j < jc; j++) {
-      const ro = j * 10;
-      trsToMat4(
-        rest[ro],
-        rest[ro + 1],
-        rest[ro + 2],
-        rest[ro + 3],
-        rest[ro + 4],
-        rest[ro + 5],
-        rest[ro + 6],
-        rest[ro + 7],
-        rest[ro + 8],
-        rest[ro + 9],
-        local,
-        j * 16
-      );
-    }
-    const topo = this.topoOrder;
-    const srm = this.skelRootMat;
-    for (let i = 0; i < jc; i++) {
-      const j = topo[i];
-      const parentJ = skin.parentJointIndices[j];
-      if (parentJ === -1) {
-        mat4Mul(srm, 0, local, j * 16, world, j * 16);
-      } else {
-        mat4Mul(world, parentJ * 16, local, j * 16, world, j * 16);
-      }
-    }
-    const ibm = skin.inverseBindMatrices;
-    for (let j = 0; j < jc; j++) {
-      mat4Mul(world, j * 16, ibm, j * 16, output, outputOffset + j * 16);
-    }
-  }
-  // --- Private helpers (zero-alloc, operate on Float32Array sub-regions) ---
-  /** Sample an animation channel at time t. Returns 3 or 4 floats. */
-  sampleChannel(ch, t) {
-    const ts = ch.timestamps;
-    const vals = ch.values;
-    const compCount = ch.path === "rotation" ? 4 : 3;
-    if (t <= ts[0])
-      return vals.subarray(0, compCount);
-    if (t >= ts[ts.length - 1])
-      return vals.subarray((ts.length - 1) * compCount, ts.length * compCount);
-    let lo = 0, hi = ts.length - 1;
-    while (lo < hi - 1) {
-      const mid = lo + hi >> 1;
-      if (ts[mid] <= t)
-        lo = mid;
-      else
-        hi = mid;
-    }
-    if (ch.interpolation === "STEP") {
-      return vals.subarray(lo * compCount, lo * compCount + compCount);
-    }
-    const t0 = ts[lo], t1 = ts[hi];
-    const f = t1 > t0 ? (t - t0) / (t1 - t0) : 0;
-    const a = lo * compCount;
-    const b = hi * compCount;
-    if (ch.path === "rotation") {
-      return this.nlerpQuat(vals, a, vals, b, f);
-    }
-    const out = this._scratchVec3;
-    out[0] = vals[a] + (vals[b] - vals[a]) * f;
-    out[1] = vals[a + 1] + (vals[b + 1] - vals[a + 1]) * f;
-    out[2] = vals[a + 2] + (vals[b + 2] - vals[a + 2]) * f;
-    return out;
-  }
-  /** Normalized lerp for quaternions (nlerp). */
-  nlerpQuat(a, ao, b, bo, t) {
-    const out = this._scratchQuat;
-    let dot2 = a[ao] * b[bo] + a[ao + 1] * b[bo + 1] + a[ao + 2] * b[bo + 2] + a[ao + 3] * b[bo + 3];
-    const sign = dot2 < 0 ? -1 : 1;
-    const oneMinusT = 1 - t;
-    out[0] = oneMinusT * a[ao] + t * b[bo] * sign;
-    out[1] = oneMinusT * a[ao + 1] + t * b[bo + 1] * sign;
-    out[2] = oneMinusT * a[ao + 2] + t * b[bo + 2] * sign;
-    out[3] = oneMinusT * a[ao + 3] + t * b[bo + 3] * sign;
-    const len = Math.sqrt(out[0] * out[0] + out[1] * out[1] + out[2] * out[2] + out[3] * out[3]);
-    if (len > 0) {
-      const inv = 1 / len;
-      out[0] *= inv;
-      out[1] *= inv;
-      out[2] *= inv;
-      out[3] *= inv;
-    }
-    return out;
-  }
-};
-
-// src/3d/skeletal-animation-compute/packer.ts
-function packAnimationData(packed) {
-  const numSkins = packed.skins.length;
-  const numClips = packed.clips.length;
-  const numChannels = packed.channels.length;
-  const SKIN_ENTRY = 10;
-  const CLIP_ENTRY = 4;
-  const CH_ENTRY = 4;
-  const skinEnd = numSkins * SKIN_ENTRY;
-  const parentEnd = skinEnd + packed.parentIndices.length;
-  const topoEnd = parentEnd + packed.topoOrder.length;
-  const clipEnd = topoEnd + numClips * CLIP_ENTRY;
-  const channelEnd = clipEnd + numChannels * CH_ENTRY;
-  const jointLookupEnd = channelEnd + packed.jointChannelLookup.length;
-  const clipTableOffset = topoEnd;
-  const channelTableOffset = clipEnd;
-  const jointLookupOffset = channelEnd;
-  const skelI32 = new Int32Array(jointLookupEnd || 1);
-  for (let s = 0; s < numSkins; s++) {
-    const sk = packed.skins[s];
-    const base = s * SKIN_ENTRY;
-    skelI32[base + 0] = sk.jointCount;
-    skelI32[base + 1] = skinEnd + sk.parentOffset;
-    skelI32[base + 2] = parentEnd + sk.topoOffset;
-    skelI32[base + 3] = sk.ibmOffset;
-    skelI32[base + 4] = sk.restTRSOffset * 10;
-    skelI32[base + 5] = sk.skelRootMatIndex;
-    skelI32[base + 6] = sk.clipOffset;
-    skelI32[base + 7] = jointLookupOffset + sk.jointLookupStart;
-    skelI32[base + 8] = 0;
-    skelI32[base + 9] = 0;
-  }
-  for (let i = 0; i < packed.parentIndices.length; i++)
-    skelI32[skinEnd + i] = packed.parentIndices[i];
-  for (let i = 0; i < packed.topoOrder.length; i++)
-    skelI32[parentEnd + i] = packed.topoOrder[i];
-  const dv = new DataView(skelI32.buffer);
-  for (let c = 0; c < numClips; c++) {
-    const cl = packed.clips[c];
-    const base = topoEnd + c * CLIP_ENTRY;
-    skelI32[base + 0] = cl.channelStart;
-    skelI32[base + 1] = cl.channelCount;
-    dv.setFloat32(base * 4 + 8, cl.duration, true);
-    skelI32[base + 3] = cl.looping;
-  }
-  for (let c = 0; c < numChannels; c++) {
-    const ch = packed.channels[c];
-    const base = clipEnd + c * CH_ENTRY;
-    skelI32[base + 0] = ch.jointIndex;
-    skelI32[base + 1] = ch.pathAndInterp;
-    skelI32[base + 2] = ch.keyframeCount;
-    skelI32[base + 3] = ch.dataOffset;
-  }
-  for (let i = 0; i < packed.jointChannelLookup.length; i++) {
-    skelI32[channelEnd + i] = packed.jointChannelLookup[i];
-  }
-  const keyframeDataSize = packed.keyframeData.length;
-  const restTRSOffset = keyframeDataSize;
-  const animF32 = new Float32Array(keyframeDataSize + packed.restTRS.length || 1);
-  for (let i = 0; i < keyframeDataSize; i++)
-    animF32[i] = packed.keyframeData[i];
-  for (let i = 0; i < packed.restTRS.length; i++)
-    animF32[keyframeDataSize + i] = packed.restTRS[i];
-  const totalIBM = packed.ibmData.length / 16;
-  for (let s = 0; s < numSkins; s++) {
-    skelI32[s * SKIN_ENTRY + 5] += totalIBM;
-    skelI32[s * SKIN_ENTRY + 4] += restTRSOffset;
-  }
-  const totalSkelRoot = packed.skelRootMats.length / 16;
-  const totalMats = totalIBM + totalSkelRoot || 1;
-  const matFloats = new Float32Array(totalMats * 16);
-  for (let i = 0; i < packed.ibmData.length; i++)
-    matFloats[i] = packed.ibmData[i];
-  for (let i = 0; i < packed.skelRootMats.length; i++)
-    matFloats[totalIBM * 16 + i] = packed.skelRootMats[i];
-  return { skelI32, animF32, matFloats, clipTableOffset, channelTableOffset, jointLookupOffset, totalMats };
+  const totalSkelRoot = packed.skelRootMats.length / 16;
+  const totalMats = totalIBM + totalSkelRoot || 1;
+  const matFloats = new Float32Array(totalMats * 16);
+  for (let i = 0; i < packed.ibmData.length; i++)
+    matFloats[i] = packed.ibmData[i];
+  for (let i = 0; i < packed.skelRootMats.length; i++)
+    matFloats[totalIBM * 16 + i] = packed.skelRootMats[i];
+  return { skelI32, animF32, matFloats, clipTableOffset, channelTableOffset, jointLookupOffset, totalMats };
 }
 
 // src/3d/skeletal-animation-compute/kernel.ts
 var WORKGROUP_SIZE = 64;
-function buildAnimationKernel(root, packed, maxInstances, maxTotalBones) {
+function buildAnimationKernel(root, packed, maxInstances, maxTotalBones, budgets) {
   const pb = packAnimationData(packed);
   const kernel = new ComputeBuilder("skeletal-animation", { workgroupSize: WORKGROUP_SIZE }, root).buffers({
     uniforms: { uniform: AnimComputeUniforms },
     instances: { storage: d.arrayOf(InstanceAnimStateGPU, maxInstances) },
-    skelI32: { storage: d.arrayOf(d.i32, pb.skelI32.length) },
-    animF32: { storage: d.arrayOf(d.f32, pb.animF32.length) },
-    matrices: { storage: d.arrayOf(d.mat4x4f, pb.totalMats) },
+    skelI32: { storage: d.arrayOf(d.i32, budgets.skelI32Capacity) },
+    animF32: { storage: d.arrayOf(d.f32, budgets.animF32Capacity) },
+    matrices: { storage: d.arrayOf(d.mat4x4f, budgets.matricesCapacity) },
     boneMatrices: { storage: d.arrayOf(d.mat4x4f, maxTotalBones), readwrite: true }
   }).shader(({ uniforms, instances, skelI32, animF32, matrices, boneMatrices }, { globalId }) => {
     const idx = globalId.x;
@@ -4124,13 +3583,50 @@ function buildAnimationKernel(root, packed, maxInstances, maxTotalBones) {
       }
     }
   }).build();
-  kernel.write("skelI32", Array.from(pb.skelI32));
-  kernel.write("animF32", Array.from(pb.animF32));
-  const matBuffer = kernel.getBuffer("matrices");
-  const rawMatBuffer = root.unwrap(matBuffer);
-  root.device.queue.writeBuffer(rawMatBuffer, 0, pb.matFloats);
-  return { kernel, packedBuffers: pb };
+  uploadPackedToKernel(root, kernel, pb);
+  return { kernel, packedBuffers: pb, budgets };
 }
+function uploadPackedToKernel(root, kernel, pb) {
+  const queue = root.device.queue;
+  const skelBuf = root.unwrap(kernel.getBuffer("skelI32"));
+  queue.writeBuffer(skelBuf, 0, pb.skelI32);
+  const animBuf = root.unwrap(kernel.getBuffer("animF32"));
+  queue.writeBuffer(animBuf, 0, pb.animF32);
+  const matBuf = root.unwrap(kernel.getBuffer("matrices"));
+  queue.writeBuffer(matBuf, 0, pb.matFloats);
+}
+
+// src/3d/clip-resync-coordinator.ts
+var GltfClipResyncCoordinator = class {
+  constructor(bucket) {
+    this.bucket = bucket;
+    this.skinIndexByPrefabId = /* @__PURE__ */ new Map();
+    this._pending = /* @__PURE__ */ new Set();
+    this.bucket.events.on("clips-changed", ({ prefabId }) => {
+      const skinIndex = this.skinIndexByPrefabId.get(prefabId);
+      if (skinIndex !== void 0)
+        this._pending.add(skinIndex);
+    });
+  }
+  /** Map a prefab id to its index in the renderer's `skinnedModels` list. */
+  registerSkin(prefabId, skinIndex) {
+    this.skinIndexByPrefabId.set(prefabId, skinIndex);
+  }
+  /** Skin indices whose clip set has changed since the last `clear()`. */
+  get pending() {
+    return this._pending;
+  }
+  clear() {
+    this._pending.clear();
+  }
+  /** Unsubscribe from the bucket and reset its animation clip sets. */
+  dispose() {
+    this.bucket.events.clear("clips-changed");
+    this.bucket.resetAnimations();
+    this.skinIndexByPrefabId.clear();
+    this._pending.clear();
+  }
+};
 
 // src/3d/renderer.ts
 var DYN_PREV_PX = 0;
@@ -4158,9 +3654,45 @@ var SSTAT_CR = 3;
 var SSTAT_CG = 4;
 var SSTAT_CB = 5;
 var SSTAT_BONE_OFFSET = 6;
+var prefabHandles = /* @__PURE__ */ new WeakMap();
+function isPrefab3D(value) {
+  const t = value.type;
+  return t === "gltf" || t === "grid" || t === "cube" || t === "composite";
+}
+function resolveTransform(opts) {
+  const [px, py, pz] = opts.position ?? [0, 0, 0];
+  const [rx, ry, rz] = opts.rotation ?? [0, 0, 0];
+  const s = opts.scale;
+  const [sx, sy, sz] = typeof s === "number" ? [s, s, s] : s ?? [1, 1, 1];
+  const [cr, cg, cb] = opts.color ?? [1, 1, 1];
+  return { px, py, pz, rx, ry, rz, sx, sy, sz, cr, cg, cb };
+}
+function resolvePrefabHandle(prefab) {
+  const h = prefabHandles.get(prefab);
+  if (!h) {
+    throw new Error(
+      `Prefab '${prefab.id}' has no GPU handle \u2014 has the renderer's init() been called with this bucket?`
+    );
+  }
+  return h;
+}
+function computeBucketStats(bucket) {
+  let maxSkinnedParts = 0;
+  let maxJointCount = 0;
+  for (const prefab of bucket.entries()) {
+    if (prefab.type === "gltf") {
+      if (prefab.skinnedPartCount > maxSkinnedParts)
+        maxSkinnedParts = prefab.skinnedPartCount;
+      if (prefab.jointCount > maxJointCount)
+        maxJointCount = prefab.jointCount;
+    }
+  }
+  return { maxSkinnedParts, maxJointCount };
+}
 var WebGPU3DRenderer = class extends Base3DRenderer {
   constructor(canvas, options) {
-    super(canvas, options);
+    const resolvedMaxInstances = options.maxInstances ?? (options.prefabs ? options.prefabs.size + 16 : 32);
+    super(canvas, { ...options, maxInstances: resolvedMaxInstances });
     this.resizeObserver = null;
     this.resizeCallbacks = [];
     // layer=0, sheetId=modelId
@@ -4170,11 +3702,15 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
     this.nextModelId = 0;
     // Skinned model data
     this.skinnedModels = [];
+    // Null when constructed without a `prefabs` bucket; lazy load/unload requires it as event source.
+    this.clipResync = null;
     this.boneMatrixDirty = true;
     // GPU animation compute
     this.packedAnimData = createPackedAnimationData();
     this.animComputeKernel = null;
     this.animComputeNeedsRebuild = false;
+    // Capacities the active kernel was built with — used to gate the in-place upload path on resync.
+    this.animKernelBudgets = null;
     this.animClipTableOffset = 0;
     this.animChannelTableOffset = 0;
     this.animJointLookupOffset = 0;
@@ -4182,27 +3718,37 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
     this.skinnedStaticDirty = false;
     this.skinnedAnimStates = [];
     this.nextBoneOffset = 0;
+    /** Reusable bone-offset blocks per skinIndex. Pushed on remove, popped on add. Indexed by skinIndex (low cardinality), so a Map of lists is fine. */
+    this.freedBoneOffsets = /* @__PURE__ */ new Map();
     // Frustum planes (6 planes × 4 floats each), extracted from VP matrix
     this.frustumPlanes = new Float32Array(24);
     this.uniformData = new Float32Array(24);
     // mat4x4 (16) + alpha (1) + lightDir (3) + padding (4)
     this.lastRenderTime = 0;
     this.camera = new Camera3D();
-    this.maxSkinnedInstances = options.maxSkinnedInstances ?? 5e3;
-    this.maxBonesPerSkin = options.maxBonesPerSkin ?? 64;
+    this._prefabs = options.prefabs ?? null;
+    const SKINNED_PARTS_PER_INSTANCE_DEFAULT_CAP = 3;
+    const bucketStats = this._prefabs ? computeBucketStats(this._prefabs) : null;
+    this.maxSkinnedInstances = options.maxSkinnedInstances ?? (bucketStats ? resolvedMaxInstances * Math.max(1, Math.min(bucketStats.maxSkinnedParts, SKINNED_PARTS_PER_INSTANCE_DEFAULT_CAP)) : 5e3);
+    this.maxBonesPerSkin = options.maxBonesPerSkin ?? (bucketStats ? Math.max(1, bucketStats.maxJointCount) : 64);
+    const cullDist = options.animationCullDistance ?? 50;
+    this.animationCullDistanceSq = cullDist * cullDist;
     this.maxTotalBones = this.maxSkinnedInstances * this.maxBonesPerSkin * 2;
     this.updatedBoneOffsets = new Uint8Array(this.maxTotalBones);
-    this.freeList = new FreeList3(options.maxModels);
-    this.batcher = new SparseBatcher2(options.maxModels);
-    this.dynamicData = new Float32Array(options.maxModels * DYNAMIC_MESH_FLOATS);
-    this.staticData = new Float32Array(options.maxModels * STATIC_MESH_FLOATS);
-    this.slotIndexData = new Uint32Array(options.maxModels);
-    this.instanceModelIds = new Uint8Array(options.maxModels);
+    this.boneOffsetRefcount = new Uint32Array(this.maxTotalBones);
+    this.boneOffsetSkinIndex = new Uint32Array(this.maxTotalBones);
+    this.freeList = new FreeList3(resolvedMaxInstances);
+    this.batcher = new SparseBatcher2(resolvedMaxInstances);
+    this.dynamicData = new Float32Array(resolvedMaxInstances * DYNAMIC_MESH_FLOATS);
+    this.staticData = new Float32Array(resolvedMaxInstances * STATIC_MESH_FLOATS);
+    this.slotIndexData = new Uint32Array(resolvedMaxInstances);
+    this.instanceModelIds = new Uint8Array(resolvedMaxInstances);
     const msi = this.maxSkinnedInstances;
     this.skinnedFreeList = new FreeList3(msi);
     this.skinnedBatcher = new SparseBatcher2(msi);
     this.skinnedDynamicData = new Float32Array(msi * DYNAMIC_MESH_FLOATS);
     this.skinnedStaticData = new Float32Array(msi * SKINNED_STATIC_MESH_FLOATS);
+    this.skinnedStaticDV = new DataView(this.skinnedStaticData.buffer);
     this.skinnedSlotIndexData = new Uint32Array(msi);
     this.skinnedInstanceModelIds = new Uint8Array(msi);
     this.skinnedInstanceBoneOffsets = new Uint32Array(msi);
@@ -4213,7 +3759,19 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
     this.gpuInstDV = new DataView(this.gpuInstData.buffer);
   }
   async init() {
-    this.root = await tgpu6.init();
+    const adapter = await navigator.gpu.requestAdapter();
+    if (!adapter)
+      throw new Error("WebGPU3DRenderer: no GPU adapter available");
+    const a = adapter.limits;
+    const requiredLimits = {
+      maxBufferSize: a.maxBufferSize,
+      maxStorageBufferBindingSize: a.maxStorageBufferBindingSize,
+      maxStorageBuffersPerShaderStage: a.maxStorageBuffersPerShaderStage,
+      maxComputeWorkgroupStorageSize: a.maxComputeWorkgroupStorageSize,
+      maxComputeInvocationsPerWorkgroup: a.maxComputeInvocationsPerWorkgroup
+    };
+    const device = await adapter.requestDevice({ requiredLimits });
+    this.root = tgpu6.initFromDevice({ device });
     this.device = this.root.device;
     this.context = this.canvas.getContext("webgpu");
     this.format = navigator.gpu.getPreferredCanvasFormat();
@@ -4230,7 +3788,7 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
       format: "depth24plus",
       usage: GPUTextureUsage.RENDER_ATTACHMENT
     });
-    this.meshLayout = createMeshLayout(this.maxModels);
+    this.meshLayout = createMeshLayout(this.maxInstances);
     const depthStencil = {
       format: "depth24plus",
       depthWriteEnabled: true,
@@ -4277,10 +3835,10 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
       primitive,
       depthStencil
     });
-    this.dynamicBuffer = this.root.createBuffer(d.arrayOf(DynamicMesh, this.maxModels)).$usage("storage");
-    this.staticBuffer = this.root.createBuffer(d.arrayOf(StaticMesh, this.maxModels)).$usage("storage");
+    this.dynamicBuffer = this.root.createBuffer(d.arrayOf(DynamicMesh, this.maxInstances)).$usage("storage");
+    this.staticBuffer = this.root.createBuffer(d.arrayOf(StaticMesh, this.maxInstances)).$usage("storage");
     this.uniformBuffer = this.root.createBuffer(MeshUniforms).$usage("uniform");
-    this.slotIndexBuffer = this.root.createBuffer(d.arrayOf(d.u32, this.maxModels)).$usage("storage");
+    this.slotIndexBuffer = this.root.createBuffer(d.arrayOf(d.u32, this.maxInstances)).$usage("storage");
     this.rawDynamicBuffer = this.root.unwrap(this.dynamicBuffer);
     this.rawStaticBuffer = this.root.unwrap(this.staticBuffer);
     this.rawUniformBuffer = this.root.unwrap(this.uniformBuffer);
@@ -4353,9 +3911,41 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
         { binding: 4, resource: { buffer: this.rawBoneMatrixBuffer } }
       ]
     });
+    if (this._prefabs) {
+      this.uploadPrefabBucket(this._prefabs);
+    }
     this.setupResizeObserver();
     this._initialized = true;
   }
+  /**
+   * Upload every prefab in the bucket to the GPU and stash the handle on
+   * each prefab so `bucket.get(id)` resolves to a usable model. Also
+   * subscribes the resync coordinator to the bucket's `clips-changed`
+   * channel for lazy load/unload.
+   */
+  uploadPrefabBucket(bucket) {
+    this.clipResync = new GltfClipResyncCoordinator(bucket);
+    for (const prefab of bucket.entries()) {
+      if (prefab.type === "gltf") {
+        const beforeSkinCount = this.skinnedModels.length;
+        const model = this.uploadParsedGltf(prefab.parsed);
+        prefabHandles.set(prefab, model);
+        if (this.skinnedModels.length > beforeSkinCount) {
+          this.clipResync.registerSkin(prefab.id, beforeSkinCount);
+        }
+      } else if (prefab.type === "grid") {
+        const model = this.createGrid({
+          size: prefab.size,
+          step: prefab.step,
+          lineWidth: prefab.lineWidth
+        });
+        prefabHandles.set(prefab, model);
+      } else if (prefab.type === "cube") {
+        const model = this.createCube({ size: prefab.size });
+        prefabHandles.set(prefab, model);
+      }
+    }
+  }
   setupResizeObserver() {
     const supportsDevicePixelBox = (() => {
       try {
@@ -4417,6 +4007,36 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
   createCompute(name, options) {
     return new ComputeBuilder(name, options, this.root);
   }
+  /**
+   * Set the maximum distance (in world units) at which the renderer keeps
+   * computing skeletal animation. Skinned instances farther than this are
+   * still drawn, but with their last-computed bone matrices instead of
+   * fresh ones, which saves GPU compute work. Their internal animation
+   * clocks keep ticking on CPU, so when they come back into range they
+   * resume in sync.
+   *
+   * Lower values trade visual smoothness on distant characters for FPS.
+   * Pass `Infinity` to disable culling entirely (always animate).
+   *
+   * Safe to call any time; takes effect on the next frame.
+   *
+   * @param distance Max distance to animate at, in world units.
+   */
+  setAnimationCullDistance(distance) {
+    this.animationCullDistanceSq = distance * distance;
+  }
+  /** Current animation cull distance (in world units). See `setAnimationCullDistance`. */
+  get animationCullDistance() {
+    return Math.sqrt(this.animationCullDistanceSq);
+  }
+  /**
+   * Max skinned instances the renderer was sized for at construction.
+   * Independent budget from `maxInstances` since skinned characters use a
+   * separate set of GPU buffers. Read-only.
+   */
+  get maxSkinned() {
+    return this.maxSkinnedInstances;
+  }
   /**
    * Create a flat grid mesh on the XZ plane at Y=0.
    *
@@ -4448,6 +4068,245 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
       indices: new Uint16Array(indices)
     });
   }
+  /**
+   * Create a unit-cube mesh centered at the origin. Pass `size` to scale the
+   * edge length, or keep size = 1 and scale at the instance level.
+   *
+   * ```ts
+   * const cube = renderer.createCube();
+   * renderer.addInstance({ model: cube, color: [1, 0.5, 0.2], scale: 2 });
+   * ```
+   */
+  createCube(opts = {}) {
+    const h = (opts.size ?? 1) / 2;
+    const positions = new Float32Array([
+      // +Z
+      -h,
+      -h,
+      h,
+      h,
+      -h,
+      h,
+      h,
+      h,
+      h,
+      -h,
+      -h,
+      h,
+      h,
+      h,
+      h,
+      -h,
+      h,
+      h,
+      // -Z
+      h,
+      -h,
+      -h,
+      -h,
+      -h,
+      -h,
+      -h,
+      h,
+      -h,
+      h,
+      -h,
+      -h,
+      -h,
+      h,
+      -h,
+      h,
+      h,
+      -h,
+      // +Y
+      -h,
+      h,
+      h,
+      h,
+      h,
+      h,
+      h,
+      h,
+      -h,
+      -h,
+      h,
+      h,
+      h,
+      h,
+      -h,
+      -h,
+      h,
+      -h,
+      // -Y
+      -h,
+      -h,
+      -h,
+      h,
+      -h,
+      -h,
+      h,
+      -h,
+      h,
+      -h,
+      -h,
+      -h,
+      h,
+      -h,
+      h,
+      -h,
+      -h,
+      h,
+      // +X
+      h,
+      -h,
+      h,
+      h,
+      -h,
+      -h,
+      h,
+      h,
+      -h,
+      h,
+      -h,
+      h,
+      h,
+      h,
+      -h,
+      h,
+      h,
+      h,
+      // -X
+      -h,
+      -h,
+      -h,
+      -h,
+      -h,
+      h,
+      -h,
+      h,
+      h,
+      -h,
+      -h,
+      -h,
+      -h,
+      h,
+      h,
+      -h,
+      h,
+      -h
+    ]);
+    const normals = new Float32Array([
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0,
+      -1,
+      0,
+      0
+    ]);
+    return this.loadModel({ positions, normals });
+  }
   /**
    * Register a model. Returns a handle for addInstance().
    *
@@ -4689,108 +4548,20 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
    * ```
    */
   async loadGltf(url, opts) {
-    const response = await fetch(url);
-    const baseUrl = url.substring(0, url.lastIndexOf("/") + 1);
-    let gltf;
-    let glbBinaryChunk = null;
-    const arrayBuffer = await response.arrayBuffer();
-    const magic = new Uint32Array(arrayBuffer, 0, 1)[0];
-    if (magic === 1179937895) {
-      let offset = 12;
-      while (offset < arrayBuffer.byteLength) {
-        const chunkLength = new Uint32Array(arrayBuffer, offset, 1)[0];
-        const chunkType = new Uint32Array(arrayBuffer, offset + 4, 1)[0];
-        offset += 8;
-        if (chunkType === 1313821514) {
-          const jsonBytes = new Uint8Array(arrayBuffer, offset, chunkLength);
-          gltf = JSON.parse(new TextDecoder().decode(jsonBytes));
-        } else if (chunkType === 5130562) {
-          glbBinaryChunk = arrayBuffer.slice(offset, offset + chunkLength);
-        }
-        offset += chunkLength;
-      }
-      if (!gltf)
-        throw new Error(`Invalid GLB: no JSON chunk in ${url}`);
-    } else {
-      gltf = JSON.parse(new TextDecoder().decode(arrayBuffer));
-    }
-    if (!gltf.meshes?.length)
-      throw new Error(`No meshes found in ${url}`);
-    const buffers = [];
-    for (let i = 0; i < (gltf.buffers?.length ?? 0); i++) {
-      const buf = gltf.buffers[i];
-      if (glbBinaryChunk && (!buf.uri || buf.uri === "")) {
-        buffers.push(glbBinaryChunk);
-      } else if (buf.uri) {
-        const r = await fetch(baseUrl + buf.uri);
-        buffers.push(await r.arrayBuffer());
-      }
-    }
-    const getAccessorData = (accessorIndex) => {
-      const accessor = gltf.accessors[accessorIndex];
-      const bufferView = gltf.bufferViews[accessor.bufferView];
-      const buffer = buffers[bufferView.buffer];
-      const typeMap = { 5120: Int8Array, 5121: Uint8Array, 5122: Int16Array, 5123: Uint16Array, 5125: Uint32Array, 5126: Float32Array };
-      const byteSizeMap = { 5120: 1, 5121: 1, 5122: 2, 5123: 2, 5125: 4, 5126: 4 };
-      const sizeMap = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT2: 4, MAT3: 9, MAT4: 16 };
-      const TypedArray = typeMap[accessor.componentType];
-      const componentBytes = byteSizeMap[accessor.componentType];
-      const elementSize = sizeMap[accessor.type] ?? 1;
-      const baseOffset = (bufferView.byteOffset ?? 0) + (accessor.byteOffset ?? 0);
-      const stride = bufferView.byteStride ?? componentBytes * elementSize;
-      const tightStride = componentBytes * elementSize;
-      if (stride === tightStride) {
-        const data = new TypedArray(buffer, baseOffset, accessor.count * elementSize);
-        return { data, count: accessor.count, elementSize };
-      }
-      const out = new TypedArray(accessor.count * elementSize);
-      const src = new Uint8Array(buffer);
-      const dst = new Uint8Array(out.buffer);
-      for (let i = 0; i < accessor.count; i++) {
-        const srcOff = baseOffset + i * stride;
-        const dstOff = i * tightStride;
-        for (let b = 0; b < tightStride; b++) {
-          dst[dstOff + b] = src[srcOff + b];
-        }
-      }
-      return { data: out, count: accessor.count, elementSize };
-    };
-    const textureCache = /* @__PURE__ */ new Map();
-    const loadTexture = async (imageIndex) => {
-      if (textureCache.has(imageIndex))
-        return textureCache.get(imageIndex);
-      const image = gltf.images?.[imageIndex];
-      if (!image)
-        return void 0;
-      let blob;
-      if (image.bufferView !== void 0) {
-        const bv = gltf.bufferViews[image.bufferView];
-        const buf = buffers[bv.buffer];
-        const data = new Uint8Array(buf, bv.byteOffset ?? 0, bv.byteLength);
-        blob = new Blob([data], { type: image.mimeType ?? "image/png" });
-      } else if (image.uri) {
-        const imgUrl = image.uri.startsWith("data:") ? image.uri : baseUrl + image.uri;
-        blob = await (await fetch(imgUrl)).blob();
-      }
-      if (blob) {
-        const bmp = await createImageBitmap(blob);
-        textureCache.set(imageIndex, bmp);
-        return bmp;
-      }
-      return void 0;
-    };
-    const meshNodeIndex = gltf.nodes?.findIndex((n) => n.mesh !== void 0) ?? -1;
-    const skinIndex = meshNodeIndex !== -1 ? gltf.nodes?.[meshNodeIndex]?.skin : void 0;
-    let skinData = null;
-    let animClips = [];
+    const parsed = await parseGltf(url, opts);
+    return this.uploadParsedGltf(parsed);
+  }
+  /**
+   * Upload a previously-parsed glTF to the GPU. Returns a GltfModel handle.
+   * Splitting parse (CPU) from upload (GPU) lets callers parse models in parallel
+   * before a renderer exists and inspect joint counts / vertex totals to size the
+   * renderer appropriately.
+   */
+  uploadParsedGltf(parsed) {
     let skinnedModelSkinIndex = -1;
-    if (skinIndex !== void 0 && gltf.skins?.[skinIndex]) {
-      skinData = parseSkin(gltf, skinIndex, getAccessorData);
-      animClips = parseAnimations(gltf, skinData, getAccessorData);
-      if (opts?.animations) {
-        animClips = animClips.filter((clip) => opts.animations.includes(clip.name));
-      }
-      const animation = new SkeletalAnimation(skinData, animClips, gltf.nodes);
+    if (parsed.skin) {
+      const { data: skinData, animClips } = parsed.skin;
+      const animation = new SkeletalAnimation(skinData, animClips);
       const ibm = skinData.inverseBindMatrices;
       let maxRadSq = 0;
       for (let j = 0; j < skinData.jointCount; j++) {
@@ -4804,91 +4575,34 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
       this.skinnedModels.push({
         animation,
         jointCount: skinData.jointCount,
-        boundingRadius: skinnedRadius
+        boundingRadius: skinnedRadius,
+        parsedSkin: parsed.skin
       });
-      packSkinAndAnimations(this.packedAnimData, skinData, animClips, gltf.nodes);
+      packSkinAndAnimations(this.packedAnimData, skinData, animClips);
       this.animComputeNeedsRebuild = true;
     }
     const handles = [];
-    const meshNodeIndices = [];
-    for (let i = 0; i < gltf.nodes.length; i++) {
-      if (gltf.nodes[i].mesh !== void 0)
-        meshNodeIndices.push(i);
-    }
-    const meshIndicesToLoad = meshNodeIndices.length > 0 ? meshNodeIndices.map((ni) => gltf.nodes[ni].mesh) : [0];
-    for (const meshIdx of meshIndicesToLoad) {
-      const mesh = gltf.meshes[meshIdx];
-      if (!mesh)
-        continue;
-      const meshNodeForThis = gltf.nodes.find((n) => n.mesh === meshIdx);
-      const meshSkinIndex = meshNodeForThis?.skin;
-      const isSkinned = skinData && meshSkinIndex !== void 0;
-      let thisMeshNodeMatrix = null;
-      if (meshNodeForThis && !isSkinned) {
-        if (meshNodeForThis.scale || meshNodeForThis.rotation || meshNodeForThis.translation || meshNodeForThis.matrix) {
-          thisMeshNodeMatrix = nodeToMat4(meshNodeForThis);
-        }
-      }
-      for (const primitive of mesh.primitives) {
-        const posAccess = getAccessorData(primitive.attributes.POSITION);
-        const positions = new Float32Array(posAccess.data);
-        let normals;
-        if (primitive.attributes.NORMAL !== void 0) {
-          normals = new Float32Array(getAccessorData(primitive.attributes.NORMAL).data);
-        }
-        let uvs;
-        if (primitive.attributes.TEXCOORD_0 !== void 0) {
-          uvs = new Float32Array(getAccessorData(primitive.attributes.TEXCOORD_0).data);
-        }
-        let indices;
-        if (primitive.indices !== void 0) {
-          const idxAccess = getAccessorData(primitive.indices);
-          indices = idxAccess.data.length > 65535 ? new Uint32Array(idxAccess.data) : new Uint16Array(idxAccess.data);
-        }
-        if (thisMeshNodeMatrix && !isSkinned) {
-          const meshNodeMatrix = thisMeshNodeMatrix;
-          const mm = meshNodeMatrix;
-          const vertexCount = positions.length / 3;
-          for (let v = 0; v < vertexCount; v++) {
-            const o = v * 3;
-            const px = positions[o], py = positions[o + 1], pz = positions[o + 2];
-            positions[o] = mm[0] * px + mm[4] * py + mm[8] * pz + mm[12];
-            positions[o + 1] = mm[1] * px + mm[5] * py + mm[9] * pz + mm[13];
-            positions[o + 2] = mm[2] * px + mm[6] * py + mm[10] * pz + mm[14];
-            if (normals) {
-              const nx = normals[o], ny = normals[o + 1], nz = normals[o + 2];
-              const tnx = mm[0] * nx + mm[4] * ny + mm[8] * nz;
-              const tny = mm[1] * nx + mm[5] * ny + mm[9] * nz;
-              const tnz = mm[2] * nx + mm[6] * ny + mm[10] * nz;
-              const len = Math.sqrt(tnx * tnx + tny * tny + tnz * tnz);
-              if (len > 0) {
-                normals[o] = tnx / len;
-                normals[o + 1] = tny / len;
-                normals[o + 2] = tnz / len;
-              }
-            }
-          }
-        }
-        let texture;
-        if (primitive.material !== void 0) {
-          const material = gltf.materials?.[primitive.material];
-          const texIndex = material?.pbrMetallicRoughness?.baseColorTexture?.index;
-          if (texIndex !== void 0 && gltf.textures?.[texIndex]) {
-            texture = await loadTexture(gltf.textures[texIndex].source);
-          }
-        }
-        if (isSkinned) {
-          const skinAttrs = parsePrimitiveSkinAttributes(primitive, getAccessorData);
-          if (skinAttrs) {
-            handles.push(this.loadSkinnedModel(
-              { positions, normals, uvs, indices, texture },
-              skinAttrs,
-              skinnedModelSkinIndex
-            ));
-            continue;
-          }
-        }
-        handles.push(this.loadModel({ positions, normals, uvs, indices, texture }));
+    for (const prim of parsed.primitives) {
+      if (prim.skinned && prim.skinAttrs) {
+        handles.push(this.loadSkinnedModel(
+          {
+            positions: prim.positions,
+            normals: prim.normals,
+            uvs: prim.uvs,
+            indices: prim.indices,
+            texture: prim.texture
+          },
+          prim.skinAttrs,
+          skinnedModelSkinIndex
+        ));
+      } else {
+        handles.push(this.loadModel({
+          positions: prim.positions,
+          normals: prim.normals,
+          uvs: prim.uvs,
+          indices: prim.indices,
+          texture: prim.texture
+        }));
       }
     }
     let totalVertexCount = 0;
@@ -4900,7 +4614,7 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
       totalVertexCount,
       skinned: handles.some((h) => h.skinned),
       animations: animNames,
-      src: url
+      src: parsed.src
     };
   }
   /**
@@ -4908,7 +4622,10 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
    * with another instance (e.g., when spawning all parts of a character).
    */
   addInstance(opts) {
-    const modelOrGltf = opts.model;
+    if (isPrefab3D(opts.model) && opts.model.type === "composite") {
+      return this.addCompositeInstance(opts, opts.model);
+    }
+    const modelOrGltf = isPrefab3D(opts.model) ? resolvePrefabHandle(opts.model) : opts.model;
     if ("parts" in modelOrGltf) {
       return this.addGltfInstance(opts, modelOrGltf);
     }
@@ -4919,36 +4636,38 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
     }
     const slot = this.freeList.allocate();
     if (slot === -1)
-      throw new Error(`Max instances (${this.maxModels}) reached`);
+      throw new Error(`Max instances (${this.maxInstances}) reached`);
     const dynBase = slot * DYNAMIC_MESH_FLOATS;
     const statBase = slot * STATIC_MESH_FLOATS;
-    const x = opts.x ?? 0, y = opts.y ?? 0, z = opts.z ?? 0;
-    this.dynamicData[dynBase + DYN_PREV_PX] = x;
-    this.dynamicData[dynBase + DYN_PREV_PY] = y;
-    this.dynamicData[dynBase + DYN_PREV_PZ] = z;
-    this.dynamicData[dynBase + DYN_CURR_PX] = x;
-    this.dynamicData[dynBase + DYN_CURR_PY] = y;
-    this.dynamicData[dynBase + DYN_CURR_PZ] = z;
-    const rx = opts.rotX ?? 0, ry = opts.rotY ?? 0, rz = opts.rotZ ?? 0;
-    this.dynamicData[dynBase + DYN_PREV_RX] = rx;
-    this.dynamicData[dynBase + DYN_PREV_RY] = ry;
-    this.dynamicData[dynBase + DYN_PREV_RZ] = rz;
-    this.dynamicData[dynBase + DYN_CURR_RX] = rx;
-    this.dynamicData[dynBase + DYN_CURR_RY] = ry;
-    this.dynamicData[dynBase + DYN_CURR_RZ] = rz;
-    this.staticData[statBase + STAT_SX] = opts.scaleX ?? 1;
-    this.staticData[statBase + STAT_SY] = opts.scaleY ?? 1;
-    this.staticData[statBase + STAT_SZ] = opts.scaleZ ?? 1;
-    const color = opts.color ?? [1, 1, 1];
-    this.staticData[statBase + STAT_CR] = color[0];
-    this.staticData[statBase + STAT_CG] = color[1];
-    this.staticData[statBase + STAT_CB] = color[2];
+    const t = resolveTransform(opts);
+    this.dynamicData[dynBase + DYN_PREV_PX] = t.px;
+    this.dynamicData[dynBase + DYN_PREV_PY] = t.py;
+    this.dynamicData[dynBase + DYN_PREV_PZ] = t.pz;
+    this.dynamicData[dynBase + DYN_CURR_PX] = t.px;
+    this.dynamicData[dynBase + DYN_CURR_PY] = t.py;
+    this.dynamicData[dynBase + DYN_CURR_PZ] = t.pz;
+    this.dynamicData[dynBase + DYN_PREV_RX] = t.rx;
+    this.dynamicData[dynBase + DYN_PREV_RY] = t.ry;
+    this.dynamicData[dynBase + DYN_PREV_RZ] = t.rz;
+    this.dynamicData[dynBase + DYN_CURR_RX] = t.rx;
+    this.dynamicData[dynBase + DYN_CURR_RY] = t.ry;
+    this.dynamicData[dynBase + DYN_CURR_RZ] = t.rz;
+    this.staticData[statBase + STAT_SX] = t.sx;
+    this.staticData[statBase + STAT_SY] = t.sy;
+    this.staticData[statBase + STAT_SZ] = t.sz;
+    this.staticData[statBase + STAT_CR] = t.cr;
+    this.staticData[statBase + STAT_CG] = t.cg;
+    this.staticData[statBase + STAT_CB] = t.cb;
     this.staticDirty = true;
     this.instanceModelIds[slot] = modelHandle.id;
     this.batcher.add(0, modelHandle.id, slot);
     const dynamicData = this.dynamicData;
     const staticData = this.staticData;
-    return {
+    const self = this;
+    let destroyed = false;
+    const handle = {
+      slot,
+      modelId: modelHandle.id,
       skinned: false,
       setPosition(nx, ny, nz) {
         dynamicData[dynBase + DYN_CURR_PX] = nx;
@@ -4964,8 +4683,19 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
         staticData[statBase + STAT_SX] = nx;
         staticData[statBase + STAT_SY] = ny;
         staticData[statBase + STAT_SZ] = nz;
+      },
+      destroy() {
+        if (destroyed)
+          return;
+        destroyed = true;
+        self.batcher.remove(0, modelHandle.id, slot);
+        self.freeList.free(slot);
+        dynamicData.fill(0, dynBase, dynBase + DYNAMIC_MESH_FLOATS);
+        staticData.fill(0, statBase, statBase + STATIC_MESH_FLOATS);
+        self.staticDirty = true;
       }
     };
+    return handle;
   }
   addGltfInstance(opts, gltf) {
     const childHandles = [];
@@ -5003,7 +4733,71 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
       } : void 0,
       stop: skinnedHandle?.stop ? () => {
         skinnedHandle.stop();
-      } : void 0
+      } : void 0,
+      destroy() {
+        for (const h of childHandles)
+          h.destroy();
+      }
+    };
+  }
+  /**
+   * Spawn a composite prefab by spawning each of its parts at the composed
+   * (instance + offset) transform. The returned handle broadcasts subsequent
+   * `setPosition` / `setRotation` to every child, keeping each child's
+   * baked offset applied on top of the new value.
+   */
+  addCompositeInstance(opts, composite) {
+    const bucket = this._prefabs;
+    if (!bucket) {
+      throw new Error(
+        `addInstance: composite '${composite.id}' requires the renderer to be constructed with the bucket (\`prefabs\`).`
+      );
+    }
+    const basePos = opts.position ?? [0, 0, 0];
+    const baseRot = opts.rotation ?? [0, 0, 0];
+    const offsets = composite.parts.map((p) => ({
+      px: p.offset?.position?.[0] ?? 0,
+      py: p.offset?.position?.[1] ?? 0,
+      pz: p.offset?.position?.[2] ?? 0,
+      rx: p.offset?.rotation?.[0] ?? 0,
+      ry: p.offset?.rotation?.[1] ?? 0,
+      rz: p.offset?.rotation?.[2] ?? 0
+    }));
+    const childHandles = [];
+    for (let i = 0; i < composite.parts.length; i++) {
+      const part = composite.parts[i];
+      const off = offsets[i];
+      const partPrefab = bucket.get(part.partId);
+      const partOpts = {
+        ...opts,
+        model: partPrefab,
+        position: [basePos[0] + off.px, basePos[1] + off.py, basePos[2] + off.pz],
+        rotation: [baseRot[0] + off.rx, baseRot[1] + off.ry, baseRot[2] + off.rz]
+      };
+      childHandles.push(this.addInstance(partOpts));
+    }
+    return {
+      skinned: childHandles.some((h) => h.skinned),
+      setPosition(x, y, z) {
+        for (let i = 0; i < childHandles.length; i++) {
+          const o = offsets[i];
+          childHandles[i].setPosition(x + o.px, y + o.py, z + o.pz);
+        }
+      },
+      setRotation(x, y, z) {
+        for (let i = 0; i < childHandles.length; i++) {
+          const o = offsets[i];
+          childHandles[i].setRotation(x + o.rx, y + o.ry, z + o.rz);
+        }
+      },
+      setScale(x, y, z) {
+        for (const h of childHandles)
+          h.setScale(x, y, z);
+      },
+      destroy() {
+        for (const h of childHandles)
+          h.destroy();
+      }
     };
   }
   addSkinnedInstance(opts, modelHandle, skinIndex, linkedSlot) {
@@ -5017,43 +4811,53 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
     if (linkedSlot !== void 0) {
       boneOffset = this.skinnedInstanceBoneOffsets[linkedSlot];
       animState = this.skinnedAnimStates[linkedSlot];
+      this.boneOffsetRefcount[boneOffset]++;
     } else {
-      boneOffset = this.nextBoneOffset + jointCount;
-      this.nextBoneOffset += jointCount * 2;
-      skinModel.animation.computeRestPose(this.boneMatrixData, boneOffset * 16);
-      this.boneMatrixDirty = true;
+      const pool = this.freedBoneOffsets.get(skinIndex);
+      if (pool && pool.length > 0) {
+        boneOffset = pool.pop();
+      } else {
+        boneOffset = this.nextBoneOffset + jointCount;
+        this.nextBoneOffset += jointCount * 2;
+      }
+      this.boneOffsetRefcount[boneOffset] = 1;
+      this.boneOffsetSkinIndex[boneOffset] = skinIndex;
+      const restOffsetFloats = boneOffset * 16;
+      const restLengthFloats = jointCount * 16;
+      skinModel.animation.computeRestPose(this.boneMatrixData, restOffsetFloats);
+      this.device.queue.writeBuffer(
+        this.rawBoneMatrixBuffer,
+        restOffsetFloats * 4,
+        this.boneMatrixData.buffer,
+        this.boneMatrixData.byteOffset + restOffsetFloats * 4,
+        restLengthFloats * 4
+      );
       animState = skinModel.animation.clipCount > 0 ? skinModel.animation.createState(0, 1, true) : null;
     }
     this.skinnedInstanceBoneOffsets[slot] = boneOffset;
     this.skinnedAnimStates[slot] = animState;
     const dynBase = slot * DYNAMIC_MESH_FLOATS;
     const statBase = slot * SKINNED_STATIC_MESH_FLOATS;
-    const x = opts.x ?? 0, y = opts.y ?? 0, z = opts.z ?? 0;
-    this.skinnedDynamicData[dynBase + DYN_PREV_PX] = x;
-    this.skinnedDynamicData[dynBase + DYN_PREV_PY] = y;
-    this.skinnedDynamicData[dynBase + DYN_PREV_PZ] = z;
-    this.skinnedDynamicData[dynBase + DYN_CURR_PX] = x;
-    this.skinnedDynamicData[dynBase + DYN_CURR_PY] = y;
-    this.skinnedDynamicData[dynBase + DYN_CURR_PZ] = z;
-    const rx = opts.rotX ?? 0, ry = opts.rotY ?? 0, rz = opts.rotZ ?? 0;
-    this.skinnedDynamicData[dynBase + DYN_PREV_RX] = rx;
-    this.skinnedDynamicData[dynBase + DYN_PREV_RY] = ry;
-    this.skinnedDynamicData[dynBase + DYN_PREV_RZ] = rz;
-    this.skinnedDynamicData[dynBase + DYN_CURR_RX] = rx;
-    this.skinnedDynamicData[dynBase + DYN_CURR_RY] = ry;
-    this.skinnedDynamicData[dynBase + DYN_CURR_RZ] = rz;
-    this.skinnedStaticData[statBase + SSTAT_SX] = opts.scaleX ?? 1;
-    this.skinnedStaticData[statBase + SSTAT_SY] = opts.scaleY ?? 1;
-    this.skinnedStaticData[statBase + SSTAT_SZ] = opts.scaleZ ?? 1;
-    const color = opts.color ?? [1, 1, 1];
-    this.skinnedStaticData[statBase + SSTAT_CR] = color[0];
-    this.skinnedStaticData[statBase + SSTAT_CG] = color[1];
-    this.skinnedStaticData[statBase + SSTAT_CB] = color[2];
-    new DataView(this.skinnedStaticData.buffer).setUint32(
-      (statBase + SSTAT_BONE_OFFSET) * 4,
-      boneOffset,
-      true
-    );
+    const t = resolveTransform(opts);
+    this.skinnedDynamicData[dynBase + DYN_PREV_PX] = t.px;
+    this.skinnedDynamicData[dynBase + DYN_PREV_PY] = t.py;
+    this.skinnedDynamicData[dynBase + DYN_PREV_PZ] = t.pz;
+    this.skinnedDynamicData[dynBase + DYN_CURR_PX] = t.px;
+    this.skinnedDynamicData[dynBase + DYN_CURR_PY] = t.py;
+    this.skinnedDynamicData[dynBase + DYN_CURR_PZ] = t.pz;
+    this.skinnedDynamicData[dynBase + DYN_PREV_RX] = t.rx;
+    this.skinnedDynamicData[dynBase + DYN_PREV_RY] = t.ry;
+    this.skinnedDynamicData[dynBase + DYN_PREV_RZ] = t.rz;
+    this.skinnedDynamicData[dynBase + DYN_CURR_RX] = t.rx;
+    this.skinnedDynamicData[dynBase + DYN_CURR_RY] = t.ry;
+    this.skinnedDynamicData[dynBase + DYN_CURR_RZ] = t.rz;
+    this.skinnedStaticData[statBase + SSTAT_SX] = t.sx;
+    this.skinnedStaticData[statBase + SSTAT_SY] = t.sy;
+    this.skinnedStaticData[statBase + SSTAT_SZ] = t.sz;
+    this.skinnedStaticData[statBase + SSTAT_CR] = t.cr;
+    this.skinnedStaticData[statBase + SSTAT_CG] = t.cg;
+    this.skinnedStaticData[statBase + SSTAT_CB] = t.cb;
+    this.skinnedStaticDV.setUint32((statBase + SSTAT_BONE_OFFSET) * 4, boneOffset, true);
     this.skinnedStaticDirty = true;
     this.skinnedInstanceModelIds[slot] = modelHandle.id;
     this.skinnedBatcher.add(0, modelHandle.id, slot);
@@ -5061,6 +4865,10 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
     const staticData = this.skinnedStaticData;
     const animStates = this.skinnedAnimStates;
     const animation = skinModel.animation;
+    const self = this;
+    const capturedBoneOffset = boneOffset;
+    const capturedSkinIndex = skinIndex;
+    let destroyed = false;
     return {
       slot,
       modelId: modelHandle.id,
@@ -5089,19 +4897,149 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
         const state = animStates[slot];
         if (state)
           animation.stop(state);
+      },
+      destroy() {
+        if (destroyed)
+          return;
+        destroyed = true;
+        self.skinnedBatcher.remove(0, modelHandle.id, slot);
+        self.skinnedFreeList.free(slot);
+        dynamicData.fill(0, dynBase, dynBase + DYNAMIC_MESH_FLOATS);
+        staticData.fill(0, statBase, statBase + SKINNED_STATIC_MESH_FLOATS);
+        animStates[slot] = null;
+        self.skinnedStaticDirty = true;
+        if (--self.boneOffsetRefcount[capturedBoneOffset] === 0) {
+          let pool = self.freedBoneOffsets.get(capturedSkinIndex);
+          if (!pool) {
+            pool = [];
+            self.freedBoneOffsets.set(capturedSkinIndex, pool);
+          }
+          pool.push(capturedBoneOffset);
+        }
       }
     };
   }
+  /**
+   * Drain pending resyncs from the coordinator. Per affected skin: rebuild
+   * its `SkeletalAnimation` clip list densely, remap in-flight animStates,
+   * then full-repack `packedAnimData`. Falls back to a kernel rebuild only
+   * when the new data exceeds the kernel's allocated budgets.
+   *
+   * The dense renumbering is load-bearing: the kernel reads each clip by
+   * its per-skin index, which must equal `SkeletalAnimation`'s clip id.
+   */
+  syncLazyAnimationChanges() {
+    const resync = this.clipResync;
+    if (!resync || resync.pending.size === 0)
+      return;
+    const remapsBySkin = /* @__PURE__ */ new Map();
+    for (const skinIndex of resync.pending) {
+      const sm = this.skinnedModels[skinIndex];
+      if (!sm)
+        continue;
+      remapsBySkin.set(skinIndex, sm.animation.replaceClips(sm.parsedSkin.animClips));
+    }
+    resync.clear();
+    for (let slot = 0; slot < this.maxSkinnedInstances; slot++) {
+      const animState = this.skinnedAnimStates[slot];
+      if (!animState)
+        continue;
+      const modelId = this.skinnedInstanceModelIds[slot];
+      const model = this.models[modelId];
+      if (!model || model.skinIndex < 0)
+        continue;
+      const remap3 = remapsBySkin.get(model.skinIndex);
+      if (!remap3)
+        continue;
+      if (animState.clipId >= 0 && animState.clipId < remap3.length) {
+        const next = remap3[animState.clipId];
+        if (next < 0) {
+          animState.clipId = -1;
+          animState.playing = false;
+        } else {
+          animState.clipId = next;
+        }
+      }
+      if (animState.prevClipId >= 0 && animState.prevClipId < remap3.length) {
+        animState.prevClipId = remap3[animState.prevClipId];
+      }
+    }
+    this.packedAnimData = createPackedAnimationData();
+    for (const sm of this.skinnedModels) {
+      packSkinAndAnimations(this.packedAnimData, sm.parsedSkin.data, sm.parsedSkin.animClips);
+    }
+    if (this.tryUploadInPlace())
+      return;
+    this.animComputeNeedsRebuild = true;
+  }
+  /** Doubling-growth budgets for kernel storage buffers, with sensible floors. */
+  growBudgetsForPacked(packed, previous) {
+    const pb = packAnimationData(packed);
+    const grow = (cur, prev, floor) => Math.max(cur * 2, prev, floor);
+    return {
+      skelI32Capacity: grow(pb.skelI32.length, previous?.skelI32Capacity ?? 0, 256),
+      animF32Capacity: grow(pb.animF32.length, previous?.animF32Capacity ?? 0, 4096),
+      matricesCapacity: grow(pb.totalMats, previous?.matricesCapacity ?? 0, 8)
+    };
+  }
+  /** Upload `packedAnimData` to the existing kernel iff it fits the current budgets. Returns false to force a rebuild. */
+  tryUploadInPlace() {
+    const kernel = this.animComputeKernel;
+    const budgets = this.animKernelBudgets;
+    if (!kernel || !budgets)
+      return false;
+    const pb = packAnimationData(this.packedAnimData);
+    if (pb.skelI32.length > budgets.skelI32Capacity)
+      return false;
+    if (pb.animF32.length > budgets.animF32Capacity)
+      return false;
+    if (pb.totalMats > budgets.matricesCapacity)
+      return false;
+    uploadPackedToKernel(this.root, kernel, pb);
+    this.animClipTableOffset = pb.clipTableOffset;
+    this.animChannelTableOffset = pb.channelTableOffset;
+    this.animJointLookupOffset = pb.jointLookupOffset;
+    return true;
+  }
+  /**
+   * Returns true if a skinned instance's bone-matrix compute should be
+   * dispatched this frame. Combines frustum culling (scaled bounding sphere)
+   * and a configurable distance cull from the camera. Callers pass the
+   * camera position + cullDistSq once outside the loop to avoid re-reading.
+   */
+  shouldDispatchSkinning(slot, model, camX, camY, camZ, cullDistSq) {
+    const skinModel = model && model.skinIndex >= 0 ? this.skinnedModels[model.skinIndex] : null;
+    const baseRadius = skinModel?.boundingRadius ?? 10;
+    const base = slot * DYNAMIC_MESH_FLOATS;
+    const sBase = slot * SKINNED_STATIC_MESH_FLOATS;
+    const cx = this.skinnedDynamicData[base + DYN_CURR_PX];
+    const cy = this.skinnedDynamicData[base + DYN_CURR_PY];
+    const cz = this.skinnedDynamicData[base + DYN_CURR_PZ];
+    const sx = Math.abs(this.skinnedStaticData[sBase + SSTAT_SX]);
+    const sy = Math.abs(this.skinnedStaticData[sBase + SSTAT_SY]);
+    const sz = Math.abs(this.skinnedStaticData[sBase + SSTAT_SZ]);
+    const maxScale = sx > sy ? sx > sz ? sx : sz : sy > sz ? sy : sz;
+    if (!this.isInFrustum(cx, cy, cz, baseRadius * maxScale))
+      return false;
+    const dxv = cx - camX, dyv = cy - camY, dzv = cz - camZ;
+    if (dxv * dxv + dyv * dyv + dzv * dzv > cullDistSq)
+      return false;
+    return true;
+  }
   updateAnimations(deltaTime) {
+    this.syncLazyAnimationChanges();
     if (this.animComputeNeedsRebuild && this.packedAnimData.clips.length > 0) {
       this.animComputeKernel?.destroy();
+      const budgets = this.growBudgetsForPacked(this.packedAnimData, null);
       const { kernel, packedBuffers } = buildAnimationKernel(
         this.root,
         this.packedAnimData,
         this.maxSkinnedInstances,
-        this.maxTotalBones
+        this.maxTotalBones,
+        budgets
       );
       this.animComputeKernel = kernel;
+      this.animKernelBudgets = budgets;
       this.animClipTableOffset = packedBuffers.clipTableOffset;
       this.animChannelTableOffset = packedBuffers.channelTableOffset;
       this.animJointLookupOffset = packedBuffers.jointLookupOffset;
@@ -5118,11 +5056,22 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
           { binding: 4, resource: { buffer: rawBoneBuffer } }
         ]
       });
+      this.device.queue.writeBuffer(
+        this.rawBoneMatrixBuffer,
+        0,
+        this.boneMatrixData.buffer,
+        this.boneMatrixData.byteOffset,
+        this.boneMatrixData.byteLength
+      );
+      this.boneMatrixDirty = false;
       this.animComputeNeedsRebuild = false;
     }
     this.updatedBoneOffsets.fill(0);
     let count = 0;
     const dv = this.gpuInstDV;
+    const camPos = this.camera.position;
+    const camX = camPos[0], camY = camPos[1], camZ = camPos[2];
+    const cullDistSq = this.animationCullDistanceSq;
     for (let slot = 0; slot < this.maxSkinnedInstances; slot++) {
       const animState = this.skinnedAnimStates[slot];
       if (!animState)
@@ -5161,6 +5110,8 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
       const modelId = this.skinnedInstanceModelIds[slot];
       const model = this.models[modelId];
       const skinIdx = model?.skinIndex ?? 0;
+      if (!this.shouldDispatchSkinning(slot, model, camX, camY, camZ, cullDistSq))
+        continue;
       const off = count * 32;
       dv.setInt32(off, animState.clipId, true);
       dv.setFloat32(off + 4, animState.time, true);
@@ -5205,14 +5156,12 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
       }
     }
   }
+  /**
+   * Free an instance's renderer slot. Equivalent to `handle.destroy()` -
+   * kept as a convenience for direct lookup. Safe to call multiple times.
+   */
   removeInstance(handle) {
-    this.batcher.remove(0, handle.modelId, handle.slot);
-    this.freeList.free(handle.slot);
-    const dynBase = handle.slot * DYNAMIC_MESH_FLOATS;
-    const statBase = handle.slot * STATIC_MESH_FLOATS;
-    this.dynamicData.fill(0, dynBase, dynBase + DYNAMIC_MESH_FLOATS);
-    this.staticData.fill(0, statBase, statBase + STATIC_MESH_FLOATS);
-    this.staticDirty = true;
+    handle.destroy();
   }
   storePreviousState() {
     this.camera.storePrevious();
@@ -5518,6 +5467,8 @@ var WebGPU3DRenderer = class extends Base3DRenderer {
     this.resizeObserver?.disconnect();
     this.resizeObserver = null;
     this.resizeCallbacks.length = 0;
+    this.clipResync?.dispose();
+    this.clipResync = null;
     this.dynamicBuffer?.destroy();
     this.staticBuffer?.destroy();
     this.uniformBuffer?.destroy();
@@ -5665,10 +5616,8 @@ var ParticleEmitter = class {
         const sprite = this.renderer.addSprite({
           sheet: this.config.sheet,
           sprite: this.config.sprite ?? 0,
-          x,
-          y,
-          scaleX: size,
-          scaleY: size,
+          position: [x, y],
+          scale: size,
           opacity: 1,
           tint: this.config.color,
           layer: 255
@@ -5720,109 +5669,6 @@ var ParticleEmitter = class {
   }
 };
 
-// src/2d/animation.ts
-var AnimationController = class {
-  constructor() {
-    this.clips = [];
-    this.clipsByName = /* @__PURE__ */ new Map();
-  }
-  /**
-   * Register an animation clip. Returns the clip ID.
-   */
-  loadClip(config) {
-    const id = this.clips.length;
-    const clip = {
-      id,
-      name: config.name,
-      frames: new Uint16Array(config.frames),
-      durations: new Float32Array(config.durations),
-      frameCount: config.frames.length,
-      totalDuration: config.durations.reduce((sum, d7) => sum + d7, 0),
-      loop: config.loop
-    };
-    this.clips.push(clip);
-    this.clipsByName.set(config.name, id);
-    return id;
-  }
-  /**
-   * Get a clip by name.
-   */
-  getClipId(name) {
-    const id = this.clipsByName.get(name);
-    if (id === void 0)
-      throw new Error(`Animation clip "${name}" not found`);
-    return id;
-  }
-  /**
-   * Get a clip by ID.
-   */
-  getClip(id) {
-    return this.clips[id];
-  }
-  /**
-   * Create a new animation state for an entity. This is the per-entity data
-   * that tracks playback progress. Store it however you like (flat array, component, etc).
-   */
-  createState(clipId, speed = 1, playing = true) {
-    return { clipId, frame: 0, time: 0, speed, playing };
-  }
-  /**
-   * Advance an animation state by deltaTime (in seconds).
-   * Returns the current sprite frame ID, or -1 if not playing.
-   * Zero allocations.
-   */
-  update(state, deltaTime) {
-    if (!state.playing) {
-      return this.clips[state.clipId].frames[state.frame];
-    }
-    const clip = this.clips[state.clipId];
-    state.time += deltaTime * state.speed * 1e3;
-    while (state.time >= clip.durations[state.frame]) {
-      state.time -= clip.durations[state.frame];
-      state.frame++;
-      if (state.frame >= clip.frameCount) {
-        if (clip.loop) {
-          state.frame = 0;
-        } else {
-          state.frame = clip.frameCount - 1;
-          state.playing = false;
-          break;
-        }
-      }
-    }
-    return clip.frames[state.frame];
-  }
-  /**
-   * Play a different clip on an existing state. Resets frame and time.
-   */
-  play(state, clipId, speed) {
-    state.clipId = clipId;
-    state.frame = 0;
-    state.time = 0;
-    state.playing = true;
-    if (speed !== void 0)
-      state.speed = speed;
-  }
-  /**
-   * Stop playback.
-   */
-  stop(state) {
-    state.playing = false;
-  }
-  /**
-   * Resume playback.
-   */
-  resume(state) {
-    state.playing = true;
-  }
-  /**
-   * Number of loaded clips.
-   */
-  get clipCount() {
-    return this.clips.length;
-  }
-};
-
 // src/shaders/utils.ts
 import tgpu7 from "typegpu";
 import * as d6 from "typegpu/data";
@@ -5944,7 +5790,6 @@ export {
   STATIC_OFFSET_UV_MAX_Y,
   STATIC_OFFSET_UV_MIN_X,
   STATIC_OFFSET_UV_MIN_Y,
-  SkeletalAnimation,
   SkinnedStaticMesh,
   SpriteAccessor,
   SpriteUniforms,
@@ -5954,14 +5799,11 @@ export {
   StaticSprite,
   WebGPU2DRenderer,
   WebGPU3DRenderer,
-  computeGridUVs,
-  computeTexturePackerUVs,
   createGeometryDataLayout,
   createTextureFromBitmap,
   d,
   getFieldFloats,
   inverseLerp,
-  loadImage,
   remap,
   resolveBuiltInGeometry,
   rotate2d,