@threenative/core 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,9 +1,86 @@
-import { AudioListener, Audio, PositionalAudio, Object3D, AnimationMixer, Vector2, Sprite, Raycaster, Plane, Vector3, PerspectiveCamera, OrthographicCamera, Scene as Scene$1 } from 'three';
-import { instancedArray } from 'three/tsl';
-import { RenderPipeline } from 'three/webgpu';
+import { AnimationMixer, AudioListener, Audio, PositionalAudio, Object3D, Scene, OrthographicCamera, Sprite, Raycaster, Vector2, Mesh, CatmullRomCurve3, PerspectiveCamera, Plane, Vector3, Matrix4, Uint32BufferAttribute, Matrix3, Float32BufferAttribute, Texture } from 'three';
+import { mergeGeometries } from 'three/addons/utils/BufferGeometryUtils.js';
+import { instancedArray, attribute, storage, vec4, positionLocal, normalLocal } from 'three/tsl';
+import { StorageBufferAttribute, RenderPipeline } from 'three/webgpu';
+import { MeshBVH } from 'three-mesh-bvh';
 import { createStore } from 'zustand/vanilla';
 
-// src/audio.ts
+// src/animation.ts
+var AnimationPlayer = class {
+  mixer;
+  #actions = /* @__PURE__ */ new Map();
+  #current;
+  #advancedFrames = 0;
+  #fadeFrom;
+  #fadeElapsed = 0;
+  #fadeDuration = 0;
+  constructor(options) {
+    this.mixer = new AnimationMixer(options.root);
+    for (const clip of options.clips) {
+      if (this.#actions.has(clip.name)) throw new Error(`Duplicate animation clip '${clip.name}'.`);
+      const action = this.mixer.clipAction(clip);
+      if (action === null)
+        throw new Error(`Animation clip '${clip.name}' could not create an action.`);
+      this.#actions.set(clip.name, action);
+    }
+  }
+  get current() {
+    return this.#current;
+  }
+  get advancedFrames() {
+    return this.#advancedFrames;
+  }
+  play(name, options = {}) {
+    const next = this.#actions.get(name);
+    if (next === void 0) throw new Error(`Unknown animation clip '${name}'.`);
+    if (this.#current === name) return;
+    const previous = this.#current === void 0 ? void 0 : this.#actions.get(this.#current);
+    const fade = Math.max(0, options.fade ?? 0);
+    for (const action of this.#actions.values()) {
+      if (action !== previous) action.setEffectiveWeight(0).stop();
+    }
+    previous?.setEffectiveWeight(1).play();
+    next.reset().setEffectiveWeight(fade > 0 && previous !== void 0 ? 0 : 1).play();
+    if (previous === void 0 || fade === 0) {
+      previous?.stop();
+      this.#fadeFrom = void 0;
+    } else {
+      previous.play();
+      this.#fadeFrom = previous;
+      this.#fadeElapsed = 0;
+      this.#fadeDuration = fade;
+    }
+    this.#current = name;
+    this.#advancedFrames = 0;
+  }
+  update(dt) {
+    if (!Number.isFinite(dt) || dt < 0)
+      throw new Error("AnimationPlayer.update requires a finite non-negative dt.");
+    const before = this.mixer.time;
+    this.mixer.update(dt);
+    if (this.#fadeFrom !== void 0) {
+      this.#fadeElapsed = Math.min(this.#fadeDuration, this.#fadeElapsed + dt);
+      const progress = this.#fadeDuration === 0 ? 1 : this.#fadeElapsed / this.#fadeDuration;
+      this.#fadeFrom.setEffectiveWeight(1 - progress);
+      this.#actions.get(this.#current ?? "")?.setEffectiveWeight(progress);
+      if (progress >= 1) {
+        this.#fadeFrom.stop();
+        this.#fadeFrom = void 0;
+      }
+    }
+    if (this.#current !== void 0 && this.mixer.time !== before) this.#advancedFrames += 1;
+  }
+  stop() {
+    this.mixer.stopAllAction();
+    this.#current = void 0;
+    this.#advancedFrames = 0;
+    this.#fadeFrom = void 0;
+  }
+  dispose() {
+    this.stop();
+    this.mixer.uncacheRoot(this.mixer.getRoot());
+  }
+};
 var buses = /* @__PURE__ */ new Set();
 var AudioBus = class {
   listener;
@@ -59,6 +136,8 @@ var AudioBus = class {
   }
   playAt(buffer, source, options = {}) {
     assertBuffer(buffer);
+    if (typeof this.listener.context.createPanner !== "function")
+      throw new Error("AudioBus.playAt needs createPanner(); this runtime has none.");
     const voice = new PositionalAudio(this.listener);
     configureVoice(voice, options);
     voice.setBuffer(buffer);
@@ -134,29 +213,116 @@ function assertBuffer(buffer) {
   if (buffer === null || buffer === void 0)
     throw new TypeError("AudioBus requires a non-null AudioBuffer.");
 }
+var CanvasLayer = class {
+  scene = new Scene();
+  camera = new OrthographicCamera();
+  /** Declares that this layer covers the framebuffer, allowing the world pass to be skipped. */
+  opaque = false;
+  #stopResize;
+  constructor(viewport) {
+    this.camera.position.z = 1;
+    this.#resize(viewport.size);
+    this.#stopResize = viewport.onResize(this.#resize);
+  }
+  dispose() {
+    this.#stopResize();
+    this.#stopResize = () => void 0;
+    this.scene.clear();
+  }
+  #resize = ({ height, width }) => {
+    this.camera.left = -width / 2;
+    this.camera.right = width / 2;
+    this.camera.top = height / 2;
+    this.camera.bottom = -height / 2;
+    this.camera.near = 0;
+    this.camera.far = 2;
+    this.camera.updateProjectionMatrix();
+  };
+};
 
-// src/assets.ts
+// src/random.ts
+function createRandom(seed) {
+  if (seed !== void 0 && !Number.isFinite(seed)) throw new TypeError("seed must be finite.");
+  let state = seed === void 0 ? 0 : seed >>> 0;
+  const deterministic = seed !== void 0;
+  const random = (() => {
+    if (!deterministic) return Math.random();
+    state = Math.imul(1664525, state) + 1013904223 >>> 0;
+    return state / 4294967296;
+  });
+  random.range = (min, max) => {
+    if (!Number.isFinite(min) || !Number.isFinite(max) || max <= min) {
+      throw new RangeError("range requires finite bounds with max greater than min.");
+    }
+    return min + random() * (max - min);
+  };
+  random.pick = (items) => {
+    if (items.length === 0) throw new RangeError("pick requires a non-empty list.");
+    return items[Math.floor(random() * items.length)];
+  };
+  Object.defineProperty(random, "state", {
+    get: () => {
+      if (!deterministic) throw new Error("state is unavailable on an unseeded random.");
+      return state;
+    },
+    set: (value) => {
+      if (!deterministic) throw new Error("state is unavailable on an unseeded random.");
+      if (!Number.isFinite(value) || !Number.isInteger(value)) {
+        throw new TypeError("state must be a finite integer.");
+      }
+      state = value >>> 0;
+    }
+  });
+  return random;
+}
 function resolvePath(basePath, path) {
   if (/^(?:[a-z]+:)?\/\//iu.test(path) || path.startsWith("data:")) return path;
   if (basePath.length === 0) return path;
   return `${basePath.replace(/\/$/u, "")}/${path.replace(/^\//u, "")}`;
 }
 function loadWith(loader, url) {
-  return new Promise((resolve, reject) => {
-    loader.load(url, resolve, void 0, reject);
-  });
+  return new Promise((resolve, reject) => loader.load(url, resolve, void 0, reject));
 }
 function createAssetLoader(options = {}) {
   const basePath = options.basePath ?? "";
   const cache = /* @__PURE__ */ new Map();
+  const disposed = {
+    geometries: /* @__PURE__ */ new WeakSet(),
+    surfaces: /* @__PURE__ */ new WeakSet(),
+    textures: /* @__PURE__ */ new WeakSet()
+  };
   const cached = (kind, path, load) => {
     const url = resolvePath(basePath, path);
     const key = `${kind}:${url}`;
     const existing = cache.get(key);
-    if (existing !== void 0) return existing;
-    const promise = load(url);
-    cache.set(key, promise);
-    return promise;
+    if (existing !== void 0) return existing.promise;
+    const entry = {
+      disposed: false,
+      kind,
+      loaded: false,
+      promise: Promise.resolve().then(() => load(url)),
+      released: false
+    };
+    entry.promise = entry.promise.then((value) => {
+      entry.loaded = true;
+      entry.value = value;
+      if (entry.released) disposeEntry(entry, disposed);
+      return value;
+    });
+    entry.promise.catch(() => {
+      if (cache.get(key) === entry) cache.delete(key);
+    });
+    cache.set(key, entry);
+    return entry.promise;
+  };
+  const releaseEntry = (entry) => {
+    entry.released = true;
+    if (entry.loaded) disposeEntry(entry, disposed);
+    else
+      void entry.promise.then(
+        () => disposeEntry(entry, disposed),
+        () => void 0
+      );
   };
   return {
     audio: (path) => cached("audio", path, async (url) => {
@@ -164,93 +330,1285 @@ function createAssetLoader(options = {}) {
       const { AudioLoader: Loader } = await import('three');
       return loadWith(new Loader(), url);
     }),
-    clear: () => cache.clear(),
+    clear: () => {
+      const entries = [...cache.values()];
+      cache.clear();
+      entries.forEach(releaseEntry);
+    },
     model: (path) => cached("model", path, async (url) => {
       if (options.model !== void 0) return await options.model(url);
       const { GLTFLoader } = await import('three/addons/loaders/GLTFLoader.js');
       return await loadWith(new GLTFLoader(), url);
     }),
-    release: (kind, path) => cache.delete(`${kind}:${resolvePath(basePath, path)}`),
+    release: (kind, path) => {
+      const key = `${kind}:${resolvePath(basePath, path)}`;
+      const entry = cache.get(key);
+      if (entry === void 0) return false;
+      cache.delete(key);
+      releaseEntry(entry);
+      return true;
+    },
     texture: (path) => cached("texture", path, async (url) => {
       if (options.texture !== void 0) return options.texture(url);
+      if (typeof Image === "undefined" && typeof createImageBitmap === "function") {
+        const response = await fetch(url);
+        if (!response.ok) throw new Error(`Failed to load texture '${url}': ${response.status}.`);
+        const bitmap = await createImageBitmap(new Blob([await response.arrayBuffer()]));
+        return Object.assign(new Texture(bitmap), { needsUpdate: true });
+      }
       const { TextureLoader: Loader } = await import('three');
       return loadWith(new Loader(), url);
     })
   };
 }
-var AnimationPlayer = class {
-  mixer;
-  #actions = /* @__PURE__ */ new Map();
-  #current;
-  #advancedFrames = 0;
-  #fadeFrom;
-  #fadeElapsed = 0;
-  #fadeDuration = 0;
-  constructor(options) {
-    this.mixer = new AnimationMixer(options.root);
-    for (const clip of options.clips) {
-      if (this.#actions.has(clip.name)) throw new Error(`Duplicate animation clip '${clip.name}'.`);
-      const action = this.mixer.clipAction(clip);
-      if (action === null)
-        throw new Error(`Animation clip '${clip.name}' could not create an action.`);
-      this.#actions.set(clip.name, action);
+function disposeEntry(entry, disposed) {
+  if (entry.disposed || !entry.loaded) return;
+  entry.disposed = true;
+  if (entry.kind === "model") disposeModel(entry.value, disposed);
+  else if (entry.kind === "texture") disposeTexture(entry.value, disposed);
+}
+function disposeModel(value, disposed) {
+  for (const root of modelRoots(value)) {
+    root.traverse((object) => {
+      const renderable = object;
+      disposeResource(renderable.geometry, disposed.geometries);
+      disposeSurface(renderable["material"], disposed);
+    });
+  }
+}
+function modelRoots(value) {
+  if (value instanceof Object3D) return [value];
+  if (!isRecord(value)) return [];
+  const roots = [value.scene, ...Array.isArray(value.scenes) ? value.scenes : []];
+  return roots.filter((root) => root instanceof Object3D);
+}
+function disposeSurface(value, disposed) {
+  if (Array.isArray(value)) {
+    for (const surface of value) disposeSurface(surface, disposed);
+    return;
+  }
+  if (!isRecord(value)) return;
+  if (disposed.surfaces.has(value)) return;
+  disposeSurfaceTextures(value, disposed, /* @__PURE__ */ new WeakSet());
+  disposeResource(value, disposed.surfaces);
+}
+function disposeSurfaceTextures(value, disposed, visited) {
+  if (isTexture(value)) {
+    disposeTexture(value, disposed);
+    return;
+  }
+  if (typeof value !== "object" || value === null || visited.has(value)) return;
+  visited.add(value);
+  if (Array.isArray(value)) {
+    for (const item of value) disposeSurfaceTextures(item, disposed, visited);
+    return;
+  }
+  for (const item of Object.values(value)) disposeSurfaceTextures(item, disposed, visited);
+}
+function disposeTexture(value, disposed) {
+  if (!isDisposable(value) || disposed.textures.has(value)) return;
+  disposed.textures.add(value);
+  value.dispose();
+}
+function disposeResource(value, disposed) {
+  if (!isDisposable(value) || disposed.has(value)) return;
+  disposed.add(value);
+  value.dispose();
+}
+function isDisposable(value) {
+  return typeof value === "object" && value !== null && typeof value.dispose === "function";
+}
+function isTexture(value) {
+  return value instanceof Texture || isRecord(value) && value.isTexture === true;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+var CANONICAL_ATTRIBUTES = ["position", "normal", "uv", "color", "tnOwnerId"];
+var OVERLAY_FLOOR = 12;
+function emptySkippedCounts() {
+  return {
+    belowMeshFloor: 0,
+    cameraOverlay: 0,
+    layers: 0,
+    renderOrder: 0,
+    renderHook: 0,
+    transparency: 0,
+    sprite: 0,
+    points: 0,
+    missingPosition: 0,
+    missingGeometry: 0,
+    missingMaterial: 0
+  };
+}
+function addSkipped(skipped, reason, count = 1) {
+  skipped[reason] += count;
+}
+function mergeSkippedCounts(target, source) {
+  for (const reason of Object.keys(target))
+    target[reason] += source[reason];
+}
+function bakeTransform(geometry, matrix, normalMatrix) {
+  const position = geometry.getAttribute("position");
+  const positions = position?.array;
+  if (positions !== void 0) {
+    const m = matrix.elements;
+    for (let index = 0; index < positions.length; index += 3) {
+      const x = positions[index];
+      const y = positions[index + 1];
+      const z = positions[index + 2];
+      const w = 1 / (m[3] * x + m[7] * y + m[11] * z + m[15] || 1);
+      positions[index] = (m[0] * x + m[4] * y + m[8] * z + m[12]) * w;
+      positions[index + 1] = (m[1] * x + m[5] * y + m[9] * z + m[13]) * w;
+      positions[index + 2] = (m[2] * x + m[6] * y + m[10] * z + m[14]) * w;
     }
   }
-  get current() {
-    return this.#current;
+  const normal = geometry.getAttribute("normal");
+  const normals = normal?.array;
+  if (normals !== void 0) {
+    const n = normalMatrix.elements;
+    for (let index = 0; index < normals.length; index += 3) {
+      const x = normals[index];
+      const y = normals[index + 1];
+      const z = normals[index + 2];
+      const nx = n[0] * x + n[3] * y + n[6] * z;
+      const ny = n[1] * x + n[4] * y + n[7] * z;
+      const nz = n[2] * x + n[5] * y + n[8] * z;
+      const length = Math.sqrt(nx * nx + ny * ny + nz * nz) || 1;
+      normals[index] = nx / length;
+      normals[index + 1] = ny / length;
+      normals[index + 2] = nz / length;
+    }
   }
-  get advancedFrames() {
-    return this.#advancedFrames;
+}
+function containsLight(object) {
+  let found = false;
+  object.traverse((child) => {
+    if (child.isLight === true) found = true;
+  });
+  return found;
+}
+function containsPreserved(object, preserved) {
+  let found = false;
+  object.traverse((child) => {
+    if (preserved.has(child)) found = true;
+  });
+  return found;
+}
+var objectKeys = /* @__PURE__ */ new WeakMap();
+function objectKey(value) {
+  const cached = objectKeys.get(value);
+  if (cached !== void 0) return cached;
+  const isColor = value.isColor === true;
+  let key = isColor ? `rgb:${value.r},${value.g},${value.b}` : String(value.uuid ?? "obj");
+  const image = value.image;
+  const data = image?.data;
+  if (data !== void 0 && typeof data.length === "number") {
+    let hash = 2166136261;
+    for (let index = 0; index < data.length; index += 1) {
+      hash ^= (data[index] ?? 0) & 255;
+      hash = Math.imul(hash, 16777619);
+    }
+    key = `tex:${image?.width}x${image?.height}:${data.length}:${(hash >>> 0).toString(36)}`;
+    for (const field of [
+      "wrapS",
+      "wrapT",
+      "magFilter",
+      "minFilter",
+      "format",
+      "type",
+      "colorSpace",
+      "flipY"
+    ]) {
+      key += `:${String(value[field])}`;
+    }
   }
-  play(name, options = {}) {
-    const next = this.#actions.get(name);
-    if (next === void 0) throw new Error(`Unknown animation clip '${name}'.`);
-    if (this.#current === name) return;
-    const previous = this.#current === void 0 ? void 0 : this.#actions.get(this.#current);
-    const fade = Math.max(0, options.fade ?? 0);
-    for (const action of this.#actions.values()) {
-      if (action !== previous) action.setEffectiveWeight(0).stop();
+  objectKeys.set(value, key);
+  return key;
+}
+function colorOf(material) {
+  const color = material.color;
+  return color === void 0 || typeof color.r !== "number" ? void 0 : color;
+}
+var LOOK_FIELDS = [
+  "alphaHash",
+  "alphaMap",
+  "alphaTest",
+  "alphaToCoverage",
+  "aoMap",
+  "aoMapIntensity",
+  "attenuationColor",
+  "attenuationDistance",
+  "blendAlpha",
+  "blendDst",
+  "blendEquation",
+  "blendSrc",
+  "blending",
+  "bumpMap",
+  "bumpScale",
+  "clearcoat",
+  "clearcoatMap",
+  "clearcoatRoughness",
+  "clipIntersection",
+  "clipShadows",
+  "clippingPlanes",
+  "colorWrite",
+  "combine",
+  "depthFunc",
+  "depthTest",
+  "depthWrite",
+  "displacementBias",
+  "displacementMap",
+  "displacementScale",
+  "dithering",
+  "emissive",
+  "emissiveIntensity",
+  "emissiveMap",
+  "envMap",
+  "envMapIntensity",
+  "flatShading",
+  "fog",
+  "forceSinglePass",
+  "gradientMap",
+  "ior",
+  "iridescence",
+  "lightMap",
+  "lightMapIntensity",
+  "map",
+  "metalness",
+  "metalnessMap",
+  "normalMap",
+  "normalMapType",
+  "normalScale",
+  "opacity",
+  "polygonOffset",
+  "polygonOffsetFactor",
+  "polygonOffsetUnits",
+  "premultipliedAlpha",
+  "reflectivity",
+  "refractionRatio",
+  "roughness",
+  "roughnessMap",
+  "sheen",
+  "sheenColor",
+  "shadowSide",
+  "shininess",
+  "side",
+  "specular",
+  "specularMap",
+  "stencilWrite",
+  "toneMapped",
+  "transmission",
+  "transparent",
+  "vertexColors",
+  "visible",
+  "wireframe"
+];
+function materialSignature(material) {
+  const source = material;
+  const parts = [material.type];
+  for (const key of LOOK_FIELDS) {
+    const value = source[key];
+    if (value === void 0) continue;
+    if (value === null) {
+      parts.push(`${key}:none`);
+      continue;
     }
-    previous?.setEffectiveWeight(1).play();
-    next.reset().setEffectiveWeight(fade > 0 && previous !== void 0 ? 0 : 1).play();
-    if (previous === void 0 || fade === 0) {
-      previous?.stop();
-      this.#fadeFrom = void 0;
-    } else {
-      previous.play();
-      this.#fadeFrom = previous;
-      this.#fadeElapsed = 0;
-      this.#fadeDuration = fade;
+    parts.push(
+      typeof value === "object" ? `${key}:${objectKey(value)}` : `${key}:${String(value)}`
+    );
+  }
+  return parts.join("|");
+}
+function materialOf(object) {
+  const material = object.material;
+  if (material === void 0) return void 0;
+  return Array.isArray(material) ? material[0] : material;
+}
+function writeNormalMatrix(target, offset, source) {
+  const e = source.elements;
+  target[offset] = e[0] ?? 0;
+  target[offset + 1] = e[1] ?? 0;
+  target[offset + 2] = e[2] ?? 0;
+  target[offset + 3] = 0;
+  target[offset + 4] = e[3] ?? 0;
+  target[offset + 5] = e[4] ?? 0;
+  target[offset + 6] = e[5] ?? 0;
+  target[offset + 7] = 0;
+  target[offset + 8] = e[6] ?? 0;
+  target[offset + 9] = e[7] ?? 0;
+  target[offset + 10] = e[8] ?? 0;
+  target[offset + 11] = 0;
+  target[offset + 15] = 1;
+}
+function hasUniformScale(matrix) {
+  const e = matrix.elements;
+  const x = Math.hypot(e[0] ?? 0, e[1] ?? 0, e[2] ?? 0);
+  const y = Math.hypot(e[4] ?? 0, e[5] ?? 0, e[6] ?? 0);
+  const z = Math.hypot(e[8] ?? 0, e[9] ?? 0, e[10] ?? 0);
+  const largest = Math.max(x, y, z);
+  if (largest === 0) return true;
+  return Math.max(Math.abs(x - y), Math.abs(y - z), Math.abs(x - z)) / largest < 1e-4;
+}
+function writeNormals(target, part, scratch) {
+  const offset = part.index * 16;
+  const source = part.detachedLeaf ? part.object.matrix : part.object.matrixWorld;
+  if (part.uniformScale) {
+    const e = source.elements;
+    target[offset] = e[0] ?? 0;
+    target[offset + 1] = e[1] ?? 0;
+    target[offset + 2] = e[2] ?? 0;
+    target[offset + 4] = e[4] ?? 0;
+    target[offset + 5] = e[5] ?? 0;
+    target[offset + 6] = e[6] ?? 0;
+    target[offset + 8] = e[8] ?? 0;
+    target[offset + 9] = e[9] ?? 0;
+    target[offset + 10] = e[10] ?? 0;
+    target[offset + 15] = 1;
+    return;
+  }
+  writeNormalMatrix(target, offset, scratch.getNormalMatrix(source));
+}
+function sameMatrix(a, b) {
+  for (let index = 0; index < a.length; index += 1) if (a[index] !== b[index]) return false;
+  return true;
+}
+function transformSample(object) {
+  const { position, quaternion, scale } = object;
+  if (position === void 0 || quaternion === void 0 || scale === void 0) {
+    return Float64Array.from(object.matrix.elements);
+  }
+  return Float64Array.of(
+    position.x,
+    position.y,
+    position.z,
+    quaternion.x,
+    quaternion.y,
+    quaternion.z,
+    quaternion.w,
+    scale.x,
+    scale.y,
+    scale.z
+  );
+}
+function sharedAttributeNames(chunks) {
+  let shared;
+  for (const chunk of chunks) {
+    const names = Object.keys(chunk.attributes);
+    shared = shared === void 0 ? names : shared.filter((name) => names.includes(name));
+  }
+  return shared ?? [];
+}
+var SceneCollapse = class {
+  #scene;
+  #observeFrames;
+  #minMeshes;
+  #onReport;
+  #samples = /* @__PURE__ */ new Map();
+  #moving = /* @__PURE__ */ new Set();
+  #changes = /* @__PURE__ */ new Map();
+  #observed = 0;
+  #windowOpenedAt;
+  #sampleSpentMs = 0;
+  #mergeSpentMs = 0;
+  #copySpentMs = 0;
+  #transformSpentMs = 0;
+  #colorSpentMs = 0;
+  #prepSpentMs = 0;
+  #observeSpanMs = 0;
+  #meshCount = -1;
+  #reportedSmall = false;
+  #lastScan;
+  #lastSourceRenderables = 0;
+  #lastSourceMaterialIdentities = 0;
+  #refreshCount = 0;
+  #refreshLastMs = 0;
+  #refreshMaxMs = 0;
+  #refreshTotalMs = 0;
+  #report;
+  #bakeBudgetMs;
+  #measureTransformRefresh;
+  #steps;
+  #bakeProgress = 0;
+  #bakeSpentMs = 0;
+  #settled;
+  #markSettled = () => void 0;
+  #restore;
+  #update;
+  /**
+   * Roots the bake lifted out of the scene, each with the child count it had when it left.
+   *
+   * The pass consumes a hierarchy and settles, but the game keeps its references and is entitled
+   * to go on using them — a level that streams its far half in after the loading screen adds to
+   * the very group this pass detached. Without this watch that geometry lands in a subtree no
+   * renderer walks and never draws, with no error to notice: the map is simply missing a piece.
+   */
+  #adoptable = [];
+  #adopted = 0;
+  constructor(scene, options = {}) {
+    const observeFrames = options.observeFrames ?? 8;
+    const minMeshes = options.minMeshes ?? 200;
+    const bakeBudgetMs = options.bakeBudgetMs ?? 100;
+    if (!Number.isInteger(observeFrames) || observeFrames < 1)
+      throw new Error("SceneCollapse.observeFrames must be a positive integer.");
+    if (!Number.isInteger(minMeshes) || minMeshes < 1)
+      throw new Error("SceneCollapse.minMeshes must be a positive integer.");
+    if (!(bakeBudgetMs > 0) || !Number.isFinite(bakeBudgetMs))
+      throw new Error("SceneCollapse.bakeBudgetMs must be a positive number.");
+    this.#scene = scene;
+    this.#observeFrames = observeFrames;
+    this.#minMeshes = minMeshes;
+    this.#bakeBudgetMs = bakeBudgetMs;
+    this.#measureTransformRefresh = options.measureTransformRefresh === true;
+    this.#settled = new Promise((resolve) => {
+      this.#markSettled = resolve;
+    });
+    const report = options.onReport ?? ((value) => {
+      console.info(`TN_SCENE_COLLAPSE:${JSON.stringify(value)}`);
+    });
+    this.#onReport = (value) => {
+      report(value);
+      this.#markSettled();
+    };
+  }
+  /**
+   * Detached roots the pass has put back because the game added to them after the collapse.
+   *
+   * Non-zero means a game is still building into a hierarchy this pass consumed. That is
+   * supported, not a fault, but it is worth seeing: each adoption gives one root its per-frame
+   * traversal back.
+   */
+  get adoptedRoots() {
+    return this.#adopted;
+  }
+  /** The pass has reached a verdict — collapsed or declined. */
+  get settled() {
+    return this.#report !== void 0;
+  }
+  /**
+   * How far through its observation window the pass is, 0 to 1.
+   *
+   * Real progress, not a guess, for the only part of startup whose length is known in advance. The
+   * collapse itself is one blocking call and cannot report from inside; a bar driven by this
+   * fills, holds while the bake runs, and completes.
+   */
+  get progress() {
+    if (this.#report !== void 0) return 1;
+    const observing = Math.min(1, this.#observed / this.#observeFrames);
+    return this.#steps === void 0 && this.#bakeProgress === 0 ? observing * 0.5 : 0.5 + this.#bakeProgress * 0.5;
+  }
+  /**
+   * Resolves once this pass has said something, whatever it said.
+   *
+   * A game needs this to know when it is safe to show the player the world. Without it the launch
+   * looks like the one the operator reported: a half-drawn map for several seconds, because each
+   * shader compiles the first time something using it is drawn, and then a multi-second stall when
+   * the collapse lands. Both costs are real and have to be paid somewhere; a game that can wait on
+   * this pays them behind a loading screen instead of in front of the player.
+   *
+   * It resolves on the *first* report, including the one that declines a scene too small to be
+   * worth collapsing — otherwise a small game would wait forever for a pass that is never going to
+   * run.
+   */
+  whenSettled() {
+    return this.#settled;
+  }
+  get report() {
+    return this.#report;
+  }
+  /**
+   * Latest bounded diagnostics snapshot. `report` is the immutable outcome recorded when the pass
+   * applied/rejected/deferred; this getter is for per-frame transform-refresh timing after an
+   * applied collapse continues updating moving parts.
+   */
+  get diagnostics() {
+    const report = this.#report;
+    if (report === void 0) return void 0;
+    return { ...report.diagnostics, timings: this.#timings() };
+  }
+  /**
+   * Call once per rendered frame. Samples local matrices until the observation window closes, then
+   * collapses; afterwards it refreshes the moving parts' transforms.
+   */
+  frame() {
+    if (this.#report !== void 0) {
+      this.#refreshTransforms();
+      return;
+    }
+    if (this.#meshCount < this.#minMeshes) {
+      this.#meshCount = this.#countMeshes();
+      if (this.#meshCount < this.#minMeshes) {
+        if (!this.#reportedSmall) {
+          this.#reportedSmall = true;
+          this.#onReport(
+            this.#makeReport({
+              collapsed: false,
+              reason: `fewer than ${this.#minMeshes} meshes so far; still watching`,
+              reasonCode: "belowMeshFloorStillWatching",
+              resultDrawCandidates: 0,
+              resultMaterialIdentities: 0,
+              skipped: {
+                ...emptySkippedCounts(),
+                ...this.#lastScan?.skipped ?? {},
+                belowMeshFloor: this.#meshCount
+              },
+              sourceMaterialIdentities: this.#lastSourceMaterialIdentities,
+              sourceMeshes: this.#meshCount,
+              sourceRenderables: this.#lastSourceRenderables || this.#meshCount,
+              status: "deferred"
+            })
+          );
+        }
+        return;
+      }
+    }
+    if (this.#steps !== void 0) {
+      this.#pumpBake();
+      return;
+    }
+    const now = () => globalThis.performance?.now() ?? 0;
+    this.#windowOpenedAt ??= now();
+    const sampledAt = now();
+    this.#sample();
+    this.#sampleSpentMs += now() - sampledAt;
+    this.#observed += 1;
+    if (this.#observed >= this.#observeFrames) {
+      this.#observeSpanMs = now() - this.#windowOpenedAt;
+      this.#steps = this.#collapseSteps();
+      this.#pumpBake();
     }
-    this.#current = name;
-    this.#advancedFrames = 0;
   }
-  update(dt) {
-    if (!Number.isFinite(dt) || dt < 0)
-      throw new Error("AnimationPlayer.update requires a finite non-negative dt.");
-    const before = this.mixer.time;
-    this.mixer.update(dt);
-    if (this.#fadeFrom !== void 0) {
-      this.#fadeElapsed = Math.min(this.#fadeDuration, this.#fadeElapsed + dt);
-      const progress = this.#fadeDuration === 0 ? 1 : this.#fadeElapsed / this.#fadeDuration;
-      this.#fadeFrom.setEffectiveWeight(1 - progress);
-      this.#actions.get(this.#current ?? "")?.setEffectiveWeight(progress);
-      if (progress >= 1) {
-        this.#fadeFrom.stop();
-        this.#fadeFrom = void 0;
+  /**
+   * Spends this frame's budget on the bake.
+   *
+   * The budget is checked between meshes rather than enforced inside one, so a single enormous
+   * mesh can still overrun it — bounding that would mean splitting a geometry mid-transform, and
+   * a half-transformed geometry is a wrong picture rather than a slow one.
+   */
+  #pumpBake() {
+    const steps = this.#steps;
+    if (steps === void 0) return;
+    const startedAt = globalThis.performance?.now() ?? 0;
+    const spend = () => {
+      this.#bakeSpentMs += (globalThis.performance?.now() ?? 0) - startedAt;
+    };
+    for (; ; ) {
+      const step = steps.next();
+      if (step.done === true) {
+        spend();
+        this.#steps = void 0;
+        this.#bakeProgress = 1;
+        if (this.#report === void 0) this.#bakeProgress = 0;
+        return;
+      }
+      this.#bakeProgress = typeof step.value === "number" ? step.value : this.#bakeProgress;
+      if ((globalThis.performance?.now() ?? 0) - startedAt >= this.#bakeBudgetMs) {
+        spend();
+        return;
       }
     }
-    if (this.#current !== void 0 && this.mixer.time !== before) this.#advancedFrames += 1;
   }
-  stop() {
-    this.mixer.stopAllAction();
-    this.#current = void 0;
-    this.#advancedFrames = 0;
-    this.#fadeFrom = void 0;
+  /** Put the original scene back. Used when a supposedly static object turns out to move. */
+  restore() {
+    this.#restore?.();
+    this.#restore = void 0;
+    this.#update = void 0;
+    this.#adoptable.length = 0;
+  }
+  #countMeshes() {
+    const scan = this.#scanSceneRenderables();
+    this.#lastScan = scan;
+    this.#lastSourceRenderables = scan.sourceRenderables;
+    this.#lastSourceMaterialIdentities = scan.materialIdentities.size;
+    return scan.meshes.length;
+  }
+  #skipReason(object) {
+    if (this.#excluded(object)) return "cameraOverlay";
+    if (object.layers !== void 0 && object.layers.mask !== 1) return "layers";
+    if ((object.renderOrder ?? 0) !== 0) return "renderOrder";
+    if (Object.hasOwn(object, "onBeforeRender") || Object.hasOwn(object, "onAfterRender"))
+      return "renderHook";
+    if (object.geometry === void 0) return "missingGeometry";
+    if (object.geometry.getAttribute("position") === void 0) return "missingPosition";
+    const material = materialOf(object);
+    if (material === void 0) return "missingMaterial";
+    if (material.transparent === true)
+      return "transparency";
+    return void 0;
   }
-  dispose() {
-    this.stop();
-    this.mixer.uncacheRoot(this.mixer.getRoot());
+  #scanSceneRenderables() {
+    const skipped = emptySkippedCounts();
+    const meshes = [];
+    const preserved = /* @__PURE__ */ new Set();
+    const materialIdentities = /* @__PURE__ */ new Set();
+    let sourceRenderables = 0;
+    this.#scene.traverse((object) => {
+      if (object.isCamera === true) return;
+      if (object.isSprite === true) {
+        sourceRenderables += 1;
+        preserved.add(object);
+        addSkipped(skipped, "sprite");
+        return;
+      }
+      if (object.isPoints === true) {
+        sourceRenderables += 1;
+        preserved.add(object);
+        addSkipped(skipped, "points");
+        return;
+      }
+      if (object.isMesh !== true) return;
+      sourceRenderables += 1;
+      const material = materialOf(object);
+      if (material !== void 0) materialIdentities.add(material);
+      const reason = this.#skipReason(object);
+      if (reason !== void 0) {
+        preserved.add(object);
+        addSkipped(skipped, reason);
+        return;
+      }
+      meshes.push(object);
+    });
+    return { materialIdentities, meshes, preserved, skipped, sourceRenderables };
+  }
+  #sample() {
+    this.#scene.traverse((object) => {
+      if (object.isCamera === true) return;
+      const current = transformSample(object);
+      const previous = this.#samples.get(object);
+      if (previous === void 0) {
+        this.#samples.set(object, current);
+        return;
+      }
+      if (sameMatrix(previous, current)) return;
+      previous.set(current);
+      const changes = (this.#changes.get(object) ?? 0) + 1;
+      this.#changes.set(object, changes);
+      if (changes >= 2) this.#moving.add(object);
+    });
+  }
+  /**
+   * Folds each camera's own subtree — where every HUD and overlay lives — into one draw per
+   * material instance.
+   *
+   * The scene pass cannot touch these: it bakes world matrices, and a camera-parented mesh baked
+   * in world space strands itself wherever the camera happened to be standing. So it skips them,
+   * and on a real game that left the HUD as ~93 of ~110 draws, worth 11 ms of a 17 ms frame on a
+   * Pixel 8 — the whole gap between 57 fps and the budget, while the scene it did collapse cost
+   * 3.6 ms. This pass bakes in *camera* space instead and attaches the result to the camera, so
+   * the overlay rides along exactly as it did.
+   *
+   * Three things a HUD does that a level does not, and each decides part of the design:
+   *
+   * - **Digits toggle `visible`.** A seven-segment counter hides segments rather than moving them,
+   *   and a 45-frame window will not see a clock tick. So nothing here is classified static:
+   *   every overlay mesh gets a transform slot, and an invisible one is pushed out of the frustum
+   *   the same way a hidden moving part is.
+   * - **Hearts recolour their own material.** So groups are keyed by material *identity*, never
+   *   merged by look and never given baked vertex colours. The game keeps writing to the same
+   *   material object and the merged draw shows it.
+   * - **The source meshes must keep updating.** They are parked on a render layer nothing draws
+   *   rather than detached, so Three.js still refreshes their world matrices and the game's own
+   *   `visible` writes still mean what they say.
+   */
+  #collapseCameras() {
+    let overlayMeshes = 0;
+    let overlayDraws = 0;
+    const skipped = emptySkippedCounts();
+    const materialIdentities = /* @__PURE__ */ new Set();
+    const cameras = [];
+    this.#scene.traverse((object) => {
+      if (object.isCamera === true) cameras.push(object);
+    });
+    for (const camera of cameras) {
+      const meshes = [];
+      camera.traverse((object) => {
+        if (object === camera) return;
+        if (object.isSprite === true) {
+          addSkipped(skipped, "sprite");
+          return;
+        }
+        if (object.isPoints === true) {
+          addSkipped(skipped, "points");
+          return;
+        }
+        if (object.isMesh !== true) return;
+        if (object.geometry?.getAttribute("position") === void 0) {
+          addSkipped(skipped, "missingPosition");
+          return;
+        }
+        if (object.layers === void 0) {
+          addSkipped(skipped, "layers");
+          return;
+        }
+        const material = materialOf(object);
+        if (material !== void 0) materialIdentities.add(material);
+        meshes.push(object);
+      });
+      if (meshes.length < OVERLAY_FLOOR) {
+        addSkipped(skipped, "cameraOverlay", meshes.length);
+        continue;
+      }
+      camera.updateMatrixWorld(true);
+      const cameraInverse = new Matrix4().copy(camera.matrixWorld).invert();
+      const groups = /* @__PURE__ */ new Map();
+      const parts = [];
+      let usable = true;
+      for (const mesh of meshes) {
+        const material = materialOf(mesh);
+        const source = mesh.geometry;
+        if (material === void 0 || source === void 0) {
+          usable = false;
+          break;
+        }
+        const index = parts.length;
+        parts.push({ object: mesh, index });
+        const geometry = source.index !== null ? source.toNonIndexed() : source.clone();
+        for (const name of Object.keys(geometry.attributes)) {
+          if (!CANONICAL_ATTRIBUTES.includes(name)) geometry.deleteAttribute(name);
+        }
+        if (geometry.getAttribute("normal") === void 0)
+          geometry.computeVertexNormals();
+        const count = geometry.getAttribute("position")?.count ?? 0;
+        const ids = new Uint32Array(count);
+        ids.fill(index);
+        geometry.setAttribute("tnOwnerId", new Uint32BufferAttribute(ids, 1));
+        const key = objectKey(material);
+        const group = groups.get(key) ?? { material, chunks: [], renderOrder: 0 };
+        group.renderOrder = Math.max(group.renderOrder, mesh.renderOrder ?? 0);
+        group.chunks.push(geometry);
+        groups.set(key, group);
+      }
+      if (!usable) continue;
+      const slots = Math.max(1, parts.length);
+      const transformData = new Float32Array(slots * 16);
+      const normalData = new Float32Array(slots * 16);
+      const transformAttribute = new StorageBufferAttribute(transformData, 16);
+      const normalAttribute = new StorageBufferAttribute(normalData, 16);
+      const ownerIdNode = attribute("tnOwnerId", "uint");
+      const ownerMatrix = storage(transformAttribute, "mat4", slots).element(ownerIdNode);
+      const ownerNormalMatrix = storage(normalAttribute, "mat4", slots).element(ownerIdNode);
+      const added = [];
+      const patched = [];
+      let failed = false;
+      for (const group of groups.values()) {
+        const shared = sharedAttributeNames(group.chunks);
+        if (!shared.includes("position") || !shared.includes("tnOwnerId")) {
+          failed = true;
+          break;
+        }
+        for (const chunk of group.chunks) {
+          for (const name of Object.keys(chunk.attributes)) {
+            if (!shared.includes(name)) chunk.deleteAttribute(name);
+          }
+        }
+        const overlayMergeStartedAt = globalThis.performance?.now() ?? 0;
+        const geometry = mergeGeometries(group.chunks, false);
+        this.#mergeSpentMs += (globalThis.performance?.now() ?? 0) - overlayMergeStartedAt;
+        if (geometry === null) {
+          failed = true;
+          break;
+        }
+        const material = group.material;
+        patched.push({
+          material,
+          position: material.positionNode,
+          normal: material.normalNode
+        });
+        material.positionNode = ownerMatrix.mul(vec4(positionLocal, 1)).xyz;
+        material.normalNode = ownerNormalMatrix.mul(vec4(normalLocal, 0)).xyz.normalize();
+        const mesh = new Mesh(geometry, material);
+        mesh.frustumCulled = false;
+        mesh.renderOrder = group.renderOrder;
+        camera.add(mesh);
+        added.push(mesh);
+        overlayDraws += 1;
+      }
+      if (failed) {
+        for (const entry of patched) {
+          entry.material.positionNode = entry.position;
+          entry.material.normalNode = entry.normal;
+        }
+        for (const mesh of added) camera.remove(mesh);
+        overlayDraws -= added.length;
+        continue;
+      }
+      const masks = /* @__PURE__ */ new Map();
+      for (const part of parts) {
+        const layers = part.object.layers;
+        if (layers === void 0) continue;
+        masks.set(part.object, layers.mask);
+        layers.mask = 0;
+      }
+      overlayMeshes += parts.length;
+      const normalMatrix = new Matrix3();
+      const world = new Matrix4();
+      const writeTransforms = () => {
+        camera.updateMatrixWorld(true);
+        cameraInverse.copy(camera.matrixWorld).invert();
+        for (const part of parts) {
+          world.copy(cameraInverse).multiply(part.object.matrixWorld);
+          transformData.set(world.elements, part.index * 16);
+          writeNormalMatrix(normalData, part.index * 16, normalMatrix.getNormalMatrix(world));
+          if (!this.#drawn(part.object, camera)) {
+            transformData[part.index * 16 + 12] = 1e9;
+            transformData[part.index * 16 + 13] = 1e9;
+            transformData[part.index * 16 + 14] = 1e9;
+          }
+        }
+        transformAttribute.needsUpdate = true;
+        normalAttribute.needsUpdate = true;
+      };
+      writeTransforms();
+      const previousUpdate = this.#update;
+      this.#update = () => {
+        previousUpdate?.();
+        writeTransforms();
+      };
+      const previousRestore = this.#restore;
+      this.#restore = () => {
+        for (const mesh of added) camera.remove(mesh);
+        for (const entry of patched) {
+          entry.material.positionNode = entry.position;
+          entry.material.normalNode = entry.normal;
+        }
+        for (const [object, mask] of masks) {
+          if (object.layers !== void 0) object.layers.mask = mask;
+        }
+        previousRestore?.();
+      };
+    }
+    return { materialIdentities, overlayMeshes, overlayDraws, skipped };
+  }
+  /** True when the game currently wants this overlay mesh on screen, ancestors included. */
+  #drawn(object, camera) {
+    for (let current = object; current !== null; current = current.parent) {
+      if (current.visible !== true) return false;
+      if (current === camera) break;
+    }
+    return true;
+  }
+  #decline(reason, sourceMeshes, reasonCode) {
+    this.#report = this.#makeReport({
+      collapsed: false,
+      reason,
+      reasonCode,
+      resultDrawCandidates: 0,
+      resultMaterialIdentities: 0,
+      skipped: this.#lastScan?.skipped ?? emptySkippedCounts(),
+      sourceMaterialIdentities: this.#lastSourceMaterialIdentities,
+      sourceMeshes,
+      sourceRenderables: this.#lastSourceRenderables || sourceMeshes,
+      status: "rejected"
+    });
+    this.#onReport(this.#report);
+  }
+  #makeReport(input) {
+    return {
+      schemaVersion: 1,
+      status: input.status,
+      reasonCode: input.reasonCode,
+      collapsed: input.collapsed,
+      ...input.reason === void 0 ? {} : { reason: input.reason },
+      sourceMeshes: input.sourceMeshes,
+      mergedMeshes: input.resultDrawCandidates,
+      movingParts: 0,
+      diagnostics: {
+        sourceRenderables: input.sourceRenderables,
+        resultDrawCandidates: input.resultDrawCandidates,
+        sourceMaterialIdentities: input.sourceMaterialIdentities,
+        resultMaterialIdentities: input.resultMaterialIdentities,
+        groups: { staticWorld: 0, movingOwners: 0, cameraOverlays: 0 },
+        skipped: input.skipped,
+        timings: this.#timings()
+      }
+    };
+  }
+  #timings() {
+    return {
+      bakeMs: this.#bakeSpentMs,
+      observeMs: this.#observeSpanMs,
+      mergeMs: this.#mergeSpentMs,
+      copyMs: this.#copySpentMs,
+      transformMs: this.#transformSpentMs,
+      colorMs: this.#colorSpentMs,
+      sampleMs: this.#sampleSpentMs,
+      transformRefresh: {
+        count: this.#refreshCount,
+        lastMs: this.#refreshLastMs,
+        maxMs: this.#refreshMaxMs,
+        meanMs: this.#refreshCount === 0 ? 0 : this.#refreshTotalMs / this.#refreshCount
+      }
+    };
+  }
+  /**
+   * Puts a detached root back in the scene once the game has added to it.
+   *
+   * The bake consumed what was there and removed each baked mesh from its parent, so a root that
+   * comes back draws only what arrived after the collapse — the merged geometry keeps drawing the
+   * rest and nothing is drawn twice. Re-attaching costs that root's traversal again, which is the
+   * whole reason the pass detached it; paying it for a root the game demonstrably still builds
+   * into is the correct trade, and a root nobody touches never pays.
+   *
+   * One integer compare per detached root per frame. There are tens of them, not thousands.
+   */
+  #adoptGrownRoots() {
+    if (this.#adoptable.length === 0) return;
+    let remaining = 0;
+    for (const entry of this.#adoptable) {
+      if (entry.root.children.length === entry.children) {
+        this.#adoptable[remaining] = entry;
+        remaining += 1;
+        continue;
+      }
+      this.#scene.add(entry.root);
+      this.#adopted += 1;
+    }
+    this.#adoptable.length = remaining;
+  }
+  #refreshTransforms() {
+    this.#adoptGrownRoots();
+    if (this.#update === void 0) return;
+    if (!this.#measureTransformRefresh) {
+      this.#update();
+      return;
+    }
+    const startedAt = globalThis.performance?.now() ?? 0;
+    this.#update();
+    const elapsed = (globalThis.performance?.now() ?? 0) - startedAt;
+    this.#refreshCount += 1;
+    this.#refreshLastMs = elapsed;
+    this.#refreshTotalMs += elapsed;
+    this.#refreshMaxMs = Math.max(this.#refreshMaxMs, elapsed);
+  }
+  /**
+   * A camera-parented subtree is not the scene pass's to bake: its world matrix would strand the
+   * subtree wherever the camera happened to be standing. `#collapseCameras` folds it in camera
+   * space instead, once this pass is done.
+   */
+  #excluded(object) {
+    for (let current = object; current !== null; current = current.parent) {
+      if (current.isCamera === true) return true;
+    }
+    return false;
+  }
+  /**
+   * The owner is the mesh's own parent whenever anything above it animates, not the nearest node
+   * observed moving. Picking the nearest mover assumes every node between it and the mesh is
+   * static, and a joint that happens to hold still during the observation window then freezes its
+   * geometry for good — the fox's limbs glitching mid-stride. Uploading the parent's world matrix
+   * carries the whole chain every frame and assumes nothing.
+   */
+  /**
+   * The nearest node at or above `object` that actually moves, which is the one whose transform the
+   * baked draw has to follow. Returning `object.parent` instead looks equivalent on a rig — a mesh
+   * hanging off an animated bone has that bone as its parent either way — but on a flat scene every
+   * independently-moving sibling shares one parent, so they all resolved to it and were baked into a
+   * single rigid group. Four thousand cubes moving on their own became one that did not.
+   */
+  #ownerOf(object) {
+    for (let current = object; current !== null; current = current.parent) {
+      if (this.#moving.has(current)) return current;
+    }
+    return void 0;
+  }
+  /**
+   * The collapse, as a generator that yields between meshes.
+   *
+   * Done in one call this took 3.6 s on a Pixel 8 — a freeze longer than the launch before it.
+   * Yielding lets `frame()` spend a few milliseconds per frame on it instead, so a loading bar
+   * keeps moving and nothing blocks. The merge at the end is not split: it was 138 ms of the
+   * original 2,518 ms and splitting it would mean holding half-merged geometry across frames.
+   */
+  *#collapseSteps() {
+    this.#scene.updateMatrixWorld(true);
+    const scan = this.#lastScan ?? this.#scanSceneRenderables();
+    this.#lastScan = void 0;
+    this.#lastSourceRenderables = scan.sourceRenderables;
+    this.#lastSourceMaterialIdentities = scan.materialIdentities.size;
+    const meshes = [...scan.meshes];
+    if (meshes.length < this.#minMeshes) {
+      this.#meshCount = 0;
+      this.#observed = 0;
+      return;
+    }
+    const movingParts = [];
+    const movingIndex = /* @__PURE__ */ new Map();
+    const groups = /* @__PURE__ */ new Map();
+    const bakedFrom = [];
+    const inverse = new Matrix4();
+    const bakeMatrix = new Matrix4();
+    const bakeNormalMatrix = new Matrix3();
+    for (const [meshIndex, mesh] of meshes.entries()) {
+      yield meshIndex / meshes.length;
+      const material = materialOf(mesh);
+      if (material === void 0) {
+        this.#decline("a mesh has no material", meshes.length, "missingMaterial");
+        return;
+      }
+      const owner = this.#ownerOf(mesh);
+      let ownerId;
+      if (owner !== void 0) {
+        ownerId = movingIndex.get(owner);
+        if (ownerId === void 0) {
+          ownerId = movingParts.length;
+          movingIndex.set(owner, ownerId);
+          movingParts.push({
+            // Decided later, in `#update`'s setup: parts are still parented to the live scene at
+            // this point and only leave it once the bake detaches them.
+            detachedLeaf: false,
+            index: ownerId,
+            object: owner,
+            uniformScale: hasUniformScale(owner.matrixWorld)
+          });
+        }
+      }
+      const local = owner === void 0 ? mesh.matrixWorld : inverse.copy(owner.matrixWorld).invert().multiply(mesh.matrixWorld);
+      const source = mesh.geometry;
+      if (source === void 0) {
+        this.#decline(
+          "a mesh lost its geometry between the scan and the merge",
+          meshes.length,
+          "missingGeometry"
+        );
+        return;
+      }
+      const copyStartedAt = globalThis.performance?.now() ?? 0;
+      const geometry = source.index !== null ? source.toNonIndexed() : source.clone();
+      this.#copySpentMs += (globalThis.performance?.now() ?? 0) - copyStartedAt;
+      for (const name of Object.keys(geometry.attributes)) {
+        if (!CANONICAL_ATTRIBUTES.includes(name)) geometry.deleteAttribute(name);
+      }
+      if (geometry.getAttribute("normal") === void 0)
+        geometry.computeVertexNormals();
+      bakeMatrix.copy(local);
+      const transformStartedAt = globalThis.performance?.now() ?? 0;
+      bakeTransform(geometry, bakeMatrix, bakeNormalMatrix.getNormalMatrix(bakeMatrix));
+      this.#transformSpentMs += (globalThis.performance?.now() ?? 0) - transformStartedAt;
+      if (ownerId !== void 0) {
+        const count2 = geometry.getAttribute("position")?.count ?? 0;
+        const ids = new Uint32Array(count2);
+        ids.fill(ownerId);
+        geometry.setAttribute("tnOwnerId", new Uint32BufferAttribute(ids, 1));
+      }
+      material.transparent === true;
+      const kind = owner === void 0 ? "static" : "moving";
+      const color = colorOf(material);
+      const count = geometry.getAttribute("position")?.count ?? 0;
+      if (geometry.getAttribute("uv") === void 0)
+        geometry.setAttribute("uv", new Float32BufferAttribute(new Float32Array(count * 2), 2));
+      const rgb = color ?? { r: 1, g: 1, b: 1 };
+      const painted = material.vertexColors === true ? geometry.getAttribute("color") : void 0;
+      const paintedArray = painted?.array;
+      const paintedStride = painted?.itemSize;
+      const fastColors = paintedArray instanceof Float32Array && paintedStride !== void 0 && painted?.normalized !== true ? { source: paintedArray, stride: paintedStride } : void 0;
+      const colorStartedAt = globalThis.performance?.now() ?? 0;
+      const colors = new Float32Array(count * 3);
+      if (painted === void 0) {
+        for (let index = 0; index < count; index += 1) {
+          colors[index * 3] = rgb.r;
+          colors[index * 3 + 1] = rgb.g;
+          colors[index * 3 + 2] = rgb.b;
+        }
+      } else if (fastColors !== void 0) {
+        const { source: source2, stride } = fastColors;
+        for (let index = 0; index < count; index += 1) {
+          const at = index * stride;
+          colors[index * 3] = rgb.r * (source2[at] ?? 0);
+          colors[index * 3 + 1] = rgb.g * (source2[at + 1] ?? 0);
+          colors[index * 3 + 2] = rgb.b * (source2[at + 2] ?? 0);
+        }
+      } else {
+        for (let index = 0; index < count; index += 1) {
+          colors[index * 3] = rgb.r * painted.getX(index);
+          colors[index * 3 + 1] = rgb.g * painted.getY(index);
+          colors[index * 3 + 2] = rgb.b * painted.getZ(index);
+        }
+      }
+      geometry.setAttribute("color", new Float32BufferAttribute(colors, 3));
+      this.#colorSpentMs += (globalThis.performance?.now() ?? 0) - colorStartedAt;
+      const castShadow = mesh.castShadow === true;
+      const receiveShadow = mesh.receiveShadow === true;
+      const key = `${kind}|${materialSignature(material)}|cast:${castShadow}|receive:${receiveShadow}`;
+      const group = groups.get(key) ?? {
+        material,
+        chunks: [],
+        dynamic: owner !== void 0,
+        castShadow,
+        receiveShadow
+      };
+      group.chunks.push(geometry);
+      groups.set(key, group);
+      if (mesh.parent !== null) bakedFrom.push({ mesh, parent: mesh.parent });
+    }
+    const slots = Math.max(1, movingParts.length);
+    const transformData = new Float32Array(slots * 16);
+    const uniformNormals = movingParts.every((part) => part.uniformScale);
+    const normalData = uniformNormals ? transformData : new Float32Array(slots * 16);
+    const normalMatrix = new Matrix3();
+    for (const part of movingParts) {
+      transformData.set(part.object.matrixWorld.elements, part.index * 16);
+      if (!uniformNormals) writeNormals(normalData, part, normalMatrix);
+    }
+    const transformAttribute = new StorageBufferAttribute(transformData, 16);
+    const normalAttribute = uniformNormals ? transformAttribute : new StorageBufferAttribute(normalData, 16);
+    const transformNode = storage(transformAttribute, "mat4", slots);
+    const normalNodes = uniformNormals ? transformNode : storage(normalAttribute, "mat4", slots);
+    const ownerIdNode = attribute("tnOwnerId", "uint");
+    const ownerMatrix = transformNode.element(ownerIdNode);
+    const ownerNormalMatrix = normalNodes.element(ownerIdNode);
+    const added = [];
+    let mergedMeshes = 0;
+    for (const group of groups.values()) {
+      const shared = sharedAttributeNames(group.chunks);
+      if (!shared.includes("position")) {
+        this.#decline(
+          "a merge group disagrees on its position attribute",
+          meshes.length,
+          "mergeGroupMissingPosition"
+        );
+        return;
+      }
+      for (const chunk of group.chunks) {
+        for (const name of Object.keys(chunk.attributes)) {
+          if (!shared.includes(name)) chunk.deleteAttribute(name);
+        }
+      }
+      const mergeStartedAt = globalThis.performance?.now() ?? 0;
+      const geometry = mergeGeometries(group.chunks, false);
+      this.#mergeSpentMs += (globalThis.performance?.now() ?? 0) - mergeStartedAt;
+      if (geometry === null) {
+        this.#decline("three.js refused to merge a group", meshes.length, "mergeRefused");
+        return;
+      }
+      let material = group.material;
+      if (geometry.getAttribute("color") !== void 0) {
+        material = material.clone();
+        const tinted = material;
+        tinted.vertexColors = true;
+        tinted.color?.setRGB(1, 1, 1);
+      }
+      if (geometry.getAttribute("normal") === void 0) {
+        this.#decline("a merge group lost its normals", meshes.length, "mergeLostNormals");
+        return;
+      }
+      if (group.dynamic && geometry.getAttribute("tnOwnerId") === void 0) {
+        this.#decline(
+          "a moving group lost its per-vertex transform id in the merge",
+          meshes.length,
+          "movingGroupLostOwnerId"
+        );
+        return;
+      }
+      if (group.dynamic) {
+        const node = material.clone();
+        node.positionNode = ownerMatrix.mul(vec4(positionLocal, 1)).xyz;
+        node.normalNode = ownerNormalMatrix.mul(vec4(normalLocal, 0)).xyz.normalize();
+        material = node;
+      }
+      const mesh = new Mesh(geometry, material);
+      mesh.frustumCulled = false;
+      mesh.castShadow = group.castShadow;
+      mesh.receiveShadow = group.receiveShadow;
+      this.#scene.add(mesh);
+      added.push(mesh);
+      mergedMeshes += 1;
+    }
+    for (const entry of bakedFrom) entry.parent.remove(entry.mesh);
+    const detached = [];
+    for (const child of [...this.#scene.children]) {
+      if (child.isCamera === true || added.includes(child) || scan.preserved.has(child)) continue;
+      if (containsLight(child)) continue;
+      if (containsPreserved(child, scan.preserved)) continue;
+      detached.push(child);
+      this.#scene.remove(child);
+      this.#adoptable.push({ children: child.children.length, root: child });
+    }
+    const movingRoots = [];
+    for (const part of movingParts) {
+      let root = part.object;
+      while (root.parent !== null) root = root.parent;
+      if (!movingRoots.includes(root)) movingRoots.push(root);
+    }
+    for (const part of movingParts) {
+      part.detachedLeaf = part.object.parent === null && part.object.children.length === 0 && typeof part.object.updateMatrix === "function";
+    }
+    const detachedLeaves = new Set(
+      movingParts.filter((part) => part.detachedLeaf).map((part) => part.object)
+    );
+    const walkedRoots = movingRoots.filter((root) => !detachedLeaves.has(root));
+    const leafParts = movingParts.filter((part) => part.detachedLeaf);
+    const nestedParts = movingParts.filter((part) => !part.detachedLeaf);
+    const hide = (offset) => {
+      transformData[offset + 12] = 1e9;
+      transformData[offset + 13] = 1e9;
+      transformData[offset + 14] = 1e9;
+    };
+    this.#update = () => {
+      for (const root of walkedRoots) root.updateMatrixWorld(true);
+      for (const part of leafParts) {
+        const object = part.object;
+        object.updateMatrix?.();
+        const offset = part.index * 16;
+        transformData.set(object.matrix.elements, offset);
+        if (!uniformNormals) writeNormals(normalData, part, normalMatrix);
+        if (object.visible !== true) hide(offset);
+      }
+      for (const part of nestedParts) {
+        const object = part.object;
+        const offset = part.index * 16;
+        transformData.set(object.matrixWorld.elements, offset);
+        if (!uniformNormals) writeNormals(normalData, part, normalMatrix);
+        if (object.visible !== true) hide(offset);
+      }
+      if (movingParts.length > 0) {
+        transformAttribute.needsUpdate = true;
+        if (!uniformNormals) normalAttribute.needsUpdate = true;
+      }
+    };
+    this.#restore = () => {
+      for (const mesh of added) this.#scene.remove(mesh);
+      for (const entry of bakedFrom) entry.parent.add(entry.mesh);
+      for (const child of detached) this.#scene.add(child);
+    };
+    const overlay = this.#collapseCameras();
+    const skipped = emptySkippedCounts();
+    mergeSkippedCounts(skipped, scan.skipped);
+    mergeSkippedCounts(skipped, overlay.skipped);
+    const resultMaterialIdentities = /* @__PURE__ */ new Set();
+    for (const group of groups.values()) resultMaterialIdentities.add(group.material);
+    for (const material of overlay.materialIdentities) resultMaterialIdentities.add(material);
+    this.#report = {
+      schemaVersion: 1,
+      status: "applied",
+      reasonCode: "applied",
+      collapsed: true,
+      sourceMeshes: meshes.length,
+      mergedMeshes,
+      movingParts: movingParts.length,
+      overlayMeshes: overlay.overlayMeshes,
+      overlayDraws: overlay.overlayDraws,
+      diagnostics: {
+        sourceRenderables: scan.sourceRenderables,
+        resultDrawCandidates: mergedMeshes + overlay.overlayDraws,
+        sourceMaterialIdentities: scan.materialIdentities.size + overlay.materialIdentities.size,
+        resultMaterialIdentities: resultMaterialIdentities.size,
+        groups: {
+          staticWorld: [...groups.values()].filter((group) => !group.dynamic).length,
+          movingOwners: movingParts.length,
+          cameraOverlays: overlay.overlayDraws
+        },
+        skipped,
+        timings: this.#timings()
+      },
+      bakeMs: this.#bakeSpentMs,
+      observeMs: this.#observeSpanMs,
+      mergeMs: this.#mergeSpentMs,
+      copyMs: this.#copySpentMs,
+      transformMs: this.#transformSpentMs,
+      colorMs: this.#colorSpentMs,
+      sampleMs: this.#sampleSpentMs
+    };
+    this.#onReport(this.#report);
   }
 };
 
@@ -275,6 +1633,8 @@ function disposeEntity(entity) {
 }
 var Registry = class {
   #named = /* @__PURE__ */ new Map();
+  #pendingFree = /* @__PURE__ */ new Set();
+  #iterating = false;
   add(name, entity) {
     if (this.#named.has(name)) throw new Error(`Entity "${name}" already registered.`);
     this.#named.set(name, entity);
@@ -284,28 +1644,64 @@ var Registry = class {
     return this.#named.get(name);
   }
   remove(name) {
+    this.#assertNotIterating("remove");
+    this.#pendingFree.delete(name);
     const entity = this.#named.get(name);
     this.#named.delete(name);
     if (entity !== void 0) disposeEntity(entity);
   }
+  queueFree(target) {
+    const name = typeof target === "string" ? target : this.#nameOf(target);
+    if (name === void 0 || !this.#named.has(name))
+      throw new Error("Cannot queue an entity that is not registered.");
+    this.#pendingFree.add(name);
+  }
+  sweep() {
+    this.#assertNotIterating("sweep");
+    const pending = [...this.#pendingFree];
+    this.#pendingFree.clear();
+    for (const name of pending) {
+      const entity = this.#named.get(name);
+      if (entity === void 0) continue;
+      this.#named.delete(name);
+      disposeEntity(entity);
+    }
+  }
   clear() {
+    this.#assertNotIterating("clear");
+    this.#pendingFree.clear();
     const entities = [...new Set(this.#named.values())];
     this.#named.clear();
     for (const entity of entities) disposeEntity(entity);
   }
   snapshot() {
     const result = {};
-    for (const [name, entity] of this.#named) {
-      const debug = entity.debug;
-      const fields = typeof debug === "function" ? debug.call(entity) : autoFields(entity);
-      const tags = entity.tags;
-      result[name] = {
-        ...fields,
-        ...Array.isArray(tags) && tags.every((tag) => typeof tag === "string") ? { tags: [...tags] } : {}
-      };
+    this.#iterating = true;
+    try {
+      for (const [name, entity] of this.#named) {
+        const debug = entity.debug;
+        const fields = typeof debug === "function" ? debug.call(entity) : autoFields(entity);
+        const tags = entity.tags;
+        result[name] = {
+          ...fields,
+          ...Array.isArray(tags) && tags.every((tag) => typeof tag === "string") ? { tags: [...tags] } : {}
+        };
+      }
+    } finally {
+      this.#iterating = false;
     }
     return result;
   }
+  #nameOf(entity) {
+    for (const [name, registered] of this.#named) {
+      if (registered === entity) return name;
+    }
+    return void 0;
+  }
+  #assertNotIterating(operation) {
+    if (this.#iterating)
+      throw new TypeError(`Registry.${operation}() cannot mutate during snapshot.`);
+  }
 };
 var DEFAULT_BINDINGS = {
   move: {
@@ -326,8 +1722,8 @@ var InputMap = class {
   #target;
   #heldKeys = /* @__PURE__ */ new Set();
   #pointerPosition = new Vector2();
-  #pointerDown = false;
   #pointerButtons = 0;
+  #pointers = /* @__PURE__ */ new Map();
   #gamepadAxes = [];
   #gamepadButtons = [];
   #previousPressed = /* @__PURE__ */ new Map();
@@ -346,9 +1742,10 @@ var InputMap = class {
       keys: this.#heldKeys,
       pointer: {
         buttons: this.#pointerButtons,
-        down: this.#pointerDown,
+        down: false,
         position: this.#pointerPosition
-      }
+      },
+      pointers: this.#pointers
     };
     this.#listen(this.#target, "keydown", (event2) => {
       const code = eventCode(event2);
@@ -359,14 +1756,16 @@ var InputMap = class {
       if (code !== void 0) this.#heldKeys.delete(code);
     });
     this.#listen(this.#pointerTarget, "pointerdown", (event2) => this.#pointerEvent(event2, true));
-    this.#listen(
-      this.#pointerTarget,
-      "pointermove",
-      (event2) => this.#pointerEvent(event2, this.#pointerDown)
-    );
+    this.#listen(this.#pointerTarget, "pointermove", (event2) => this.#pointerEvent(event2));
     this.#listen(this.#pointerTarget, "pointerup", (event2) => this.#pointerEvent(event2, false));
+    this.#listen(this.#pointerTarget, "pointercancel", (event2) => this.#pointerEvent(event2, false));
     this.#listen(this.#target, "blur", () => this.clear());
   }
+  /**
+   * Returns a 2D action vector where +y is up. On a conventional XZ ground plane whose
+   * forward direction is -z, map `vector.y` to `-z`. This differs from Godot's
+   * `Input.get_vector`, where up is -y.
+   */
   vector(name) {
     const binding = this.#bindings[name];
     if (binding === void 0) return new Vector2();
@@ -385,7 +1784,7 @@ var InputMap = class {
   pressed(name) {
     const binding = this.#bindings[name];
     if (binding === void 0) return false;
-    return this.#isHeld(binding.down) || this.#isHeld(binding.left) || this.#isHeld(binding.right) || this.#isHeld(binding.up) || binding.pointer === true && this.#pointerDown || (binding.buttons?.some((button) => this.#gamepadButtons[button] === true) ?? false);
+    return this.#isHeld(binding.keys) || this.#isHeld(binding.down) || this.#isHeld(binding.left) || this.#isHeld(binding.right) || this.#isHeld(binding.up) || binding.pointer === true && this.#pointers.size > 0 || (binding.buttons?.some((button) => this.#gamepadButtons[button] === true) ?? false);
   }
   justPressed(name) {
     return this.#justPressed.has(name);
@@ -411,7 +1810,7 @@ var InputMap = class {
   }
   clear() {
     this.#heldKeys.clear();
-    this.#pointerDown = false;
+    this.#pointers.clear();
     this.#pointerButtons = 0;
     this.#pointerPosition.set(0, 0);
     this.raw.pointer.buttons = 0;
@@ -435,21 +1834,44 @@ var InputMap = class {
   }
   #pointerEvent(event2, down) {
     const pointer = event2;
-    this.#pointerDown = down;
-    this.#pointerButtons = pointer.buttons ?? 0;
-    this.#pointerPosition.set(pointer.clientX ?? 0, pointer.clientY ?? 0);
+    const id = pointer.pointerId ?? 0;
+    const buttons = pointer.buttons ?? 0;
+    const x = pointer.clientX ?? 0;
+    const y = pointer.clientY ?? 0;
+    const tracked = this.#pointers.get(id);
+    if (down === true) {
+      if (tracked === void 0) {
+        this.#pointers.set(id, { buttons, id, position: new Vector2(x, y) });
+      } else {
+        tracked.buttons = buttons;
+        tracked.position.set(x, y);
+      }
+    } else if (down === false) {
+      this.#pointers.delete(id);
+    } else if (tracked !== void 0) {
+      tracked.buttons = buttons;
+      tracked.position.set(x, y);
+    }
+    const primary = this.#pointers.values().next().value;
+    if (primary !== void 0) {
+      this.#pointerButtons = primary.buttons;
+      this.#pointerPosition.copy(primary.position);
+    } else if (down !== false || tracked !== void 0) {
+      this.#pointerButtons = buttons;
+      this.#pointerPosition.set(x, y);
+    }
     this.raw.pointer.buttons = this.#pointerButtons;
-    this.raw.pointer.down = down;
+    this.raw.pointer.down = primary !== void 0;
     const capture = this.#pointerTarget;
-    if (down) capture.setPointerCapture?.(pointer.pointerId ?? 0);
-    else capture.releasePointerCapture?.(pointer.pointerId ?? 0);
+    if (pointer.isTrusted !== false) {
+      if (down === true) capture.setPointerCapture?.(id);
+      if (down === false) capture.releasePointerCapture?.(id);
+    }
   }
 };
-function input(bindings, target, pointerTarget, source) {
-  return new InputMap(bindings, target, pointerTarget, source);
-}
 
 // src/loop.ts
+var MAX_RENDER_PERFORMANCE_SAMPLES = 1024;
 var FixedStepLoop = class {
   step;
   maxSteps;
@@ -461,8 +1883,10 @@ var FixedStepLoop = class {
   #lastTime;
   #frameHandle;
   #running = false;
+  #tick = 0;
   #fps = 0;
   #lastRenderTime;
+  #renderPerformanceSamples = [];
   constructor(options) {
     this.step = options.step ?? 1 / 60;
     this.maxSteps = options.maxSteps ?? 5;
@@ -480,12 +1904,18 @@ var FixedStepLoop = class {
   get fps() {
     return this.#fps;
   }
+  runtimeDiagnosticsSeries() {
+    return this.#renderPerformanceSamples.map((sample) => ({ ...sample }));
+  }
+  tick = () => this.#tick;
   start(now = globalThis.performance?.now() ?? 0) {
     if (this.#running) return;
     this.#running = true;
     this.#lastTime = now;
     this.#lastRenderTime = void 0;
+    this.#tick = 0;
     this.#fps = 0;
+    this.#renderPerformanceSamples = [];
     this.#frameHandle = this.#requestFrame((time) => this.#frame(time));
   }
   stop() {
@@ -496,34 +1926,46 @@ var FixedStepLoop = class {
     this.#accumulator = 0;
   }
   stepFrame(now) {
-    const last = this.#lastTime ?? now;
-    const elapsed = Math.max(0, (now - last) / 1e3);
-    this.#lastTime = now;
+    const elapsed = Math.max(0, (now - (this.#lastTime ?? now)) / 1e3);
+    this.#lastTime = Math.max(this.#lastTime ?? now, now);
     this.#accumulator += elapsed;
     let updates = 0;
     while (this.#accumulator + Number.EPSILON >= this.step && updates < this.maxSteps) {
       this.#onUpdate(this.step);
+      this.#tick += 1;
       this.#accumulator -= this.step;
       updates += 1;
     }
     if (updates === this.maxSteps && this.#accumulator >= this.step) this.#accumulator = 0;
+    let frameMs;
     if (Number.isFinite(now)) {
       if (this.#lastRenderTime !== void 0) {
-        const frameMs = now - this.#lastRenderTime;
+        frameMs = now - this.#lastRenderTime;
         if (frameMs > 0) this.#fps += (1e3 / frameMs - this.#fps) * 0.1;
       }
       this.#lastRenderTime = now;
     }
-    this.#onRender();
+    const metrics = this.#onRender();
+    if (frameMs !== void 0 && frameMs > 0) {
+      const sample = {
+        frameMs,
+        ...metrics === void 0 || metrics.drawCalls === void 0 ? {} : { drawCalls: metrics.drawCalls },
+        ...metrics === void 0 || metrics.triangles === void 0 ? {} : { triangles: metrics.triangles }
+      };
+      this.#renderPerformanceSamples.push(sample);
+      if (this.#renderPerformanceSamples.length > MAX_RENDER_PERFORMANCE_SAMPLES)
+        this.#renderPerformanceSamples.shift();
+    }
     return updates;
   }
   advance(ticks) {
     if (!this.#running) throw new Error("Cannot advance a stopped loop.");
     if (!Number.isInteger(ticks) || ticks <= 0)
       throw new Error("advance ticks must be a positive integer.");
+    this.#lastTime = Number.POSITIVE_INFINITY;
     for (let index = 0; index < ticks; index += 1) {
-      this.#lastTime = (this.#lastTime ?? 0) + this.step * 1e3;
       this.#onUpdate(this.step);
+      this.#tick += 1;
     }
     return ticks;
   }
@@ -604,42 +2046,70 @@ var GPUParticles3D = class extends Sprite {
   }
   #onRemoved = () => this.detach();
 };
-
-// src/random.ts
-function createRandom(seed) {
-  if (seed !== void 0 && !Number.isFinite(seed)) throw new TypeError("seed must be finite.");
-  let state = seed === void 0 ? 0 : seed >>> 0;
-  const deterministic = seed !== void 0;
-  const random = (() => {
-    if (!deterministic) return Math.random();
-    state = Math.imul(1664525, state) + 1013904223 >>> 0;
-    return state / 4294967296;
-  });
-  random.range = (min, max) => {
-    if (!Number.isFinite(min) || !Number.isFinite(max) || max <= min) {
-      throw new RangeError("range requires finite bounds with max greater than min.");
+var ScenePicker = class {
+  #camera;
+  #pointer;
+  #scene;
+  #viewport;
+  #raycaster = new Raycaster();
+  #ndc = new Vector2();
+  #hits = [];
+  #trees = /* @__PURE__ */ new WeakMap();
+  constructor(options) {
+    this.#camera = options.camera;
+    this.#pointer = options.pointer;
+    this.#scene = options.scene;
+    this.#viewport = options.viewport;
+    this.#raycaster.firstHitOnly = true;
+  }
+  /** The closest hit under the screen point, or `undefined` when the ray hits nothing. */
+  raycast(options = {}) {
+    const screen = options.screen ?? this.#pointer();
+    if (!Number.isFinite(screen.x) || !Number.isFinite(screen.y))
+      throw new Error("ICtx.raycast screen point must be finite.");
+    const { height, width } = this.#viewport.size;
+    if (width <= 0 || height <= 0) throw new Error("ICtx.raycast needs a sized viewport.");
+    this.#ndc.set(screen.x / width * 2 - 1, -(screen.y / height) * 2 + 1);
+    this.#raycaster.setFromCamera(this.#ndc, this.#camera);
+    const targets = options.targets ?? this.#scene;
+    const roots = Array.isArray(targets) ? targets : [targets];
+    this.#hits.length = 0;
+    for (const root of roots) {
+      root.updateMatrixWorld();
+      this.#collect(root);
     }
-    return min + random() * (max - min);
-  };
-  random.pick = (items) => {
-    if (items.length === 0) throw new RangeError("pick requires a non-empty list.");
-    return items[Math.floor(random() * items.length)];
-  };
-  Object.defineProperty(random, "state", {
-    get: () => {
-      if (!deterministic) throw new Error("state is unavailable on an unseeded random.");
-      return state;
-    },
-    set: (value) => {
-      if (!deterministic) throw new Error("state is unavailable on an unseeded random.");
-      if (!Number.isFinite(value) || !Number.isInteger(value)) {
-        throw new TypeError("state must be a finite integer.");
-      }
-      state = value >>> 0;
+    if (this.#hits.length === 0) return void 0;
+    this.#hits.sort((first, second) => first.distance - second.distance);
+    return this.#hits[0];
+  }
+  /** Drops every cached hierarchy. The next `raycast` rebuilds what it needs. */
+  dispose() {
+    this.#trees = /* @__PURE__ */ new WeakMap();
+    this.#hits.length = 0;
+  }
+  #collect(object) {
+    if (object.layers.test(this.#raycaster.layers)) {
+      const tree = this.#treeFor(object);
+      if (tree === void 0) object.raycast(this.#raycaster, this.#hits);
+      else tree.raycastObject3D(object, this.#raycaster, this.#hits);
     }
-  });
-  return random;
-}
+    for (const child of object.children) this.#collect(child);
+  }
+  #treeFor(object) {
+    if (!(object instanceof Mesh)) return void 0;
+    const deformed = object;
+    if (deformed.isSkinnedMesh === true || deformed.isInstancedMesh === true || deformed.isBatchedMesh === true || (object.morphTargetInfluences?.length ?? 0) > 0)
+      return void 0;
+    const geometry = object.geometry;
+    const position = geometry.attributes.position;
+    if (position === void 0 || position.count === 0) return void 0;
+    const cached = this.#trees.get(geometry);
+    if (cached !== void 0 && cached.version === position.version) return cached.tree;
+    const tree = new MeshBVH(geometry);
+    this.#trees.set(geometry, { tree, version: position.version });
+    return tree;
+  }
+};
 function readCanvasSize(canvas) {
   return [
     Math.max(1, canvas.clientWidth || globalThis.innerWidth || 1),
@@ -662,6 +2132,10 @@ function wrapRenderer(raw, kind) {
     domElement: raw.domElement,
     kind,
     raw,
+    compileAsync: async (scene, camera) => {
+      if (typeof raw.compileAsync !== "function") return;
+      await raw.compileAsync(scene, camera);
+    },
     compute: (node) => {
       if (kind !== "webgpu") throw new Error(`compute is unavailable on the ${kind} renderer.`);
       if (typeof raw.compute !== "function")
@@ -677,6 +2151,17 @@ function wrapRenderer(raw, kind) {
       if (outputPipeline === void 0) raw.render(scene, camera);
       else outputPipeline.render();
     },
+    renderOverlay: (scene, camera) => {
+      const hadOwnAutoClear = Object.hasOwn(raw, "autoClear");
+      const autoClear = raw.autoClear;
+      raw.autoClear = false;
+      try {
+        raw.render(scene, camera);
+      } finally {
+        if (hadOwnAutoClear) raw.autoClear = autoClear;
+        else Reflect.deleteProperty(raw, "autoClear");
+      }
+    },
     setOutputNode: (node) => {
       if (kind !== "webgpu")
         throw new Error(`setOutputNode is unavailable on the ${kind} renderer.`);
@@ -689,16 +2174,23 @@ function wrapRenderer(raw, kind) {
     setSize: (width, height, updateStyle = false) => raw.setSize(width, height, updateStyle)
   };
 }
-function addResizeHandling(renderer, source) {
+function addResizeHandling(renderer, source, resolutionScale) {
   const resize = () => {
     const [width, height] = source?.readSize(renderer.domElement) ?? readCanvasSize(renderer.domElement);
-    renderer.setSize(width, height, false);
+    renderer.setSize(
+      Math.max(1, Math.round(width * resolutionScale)),
+      Math.max(1, Math.round(height * resolutionScale)),
+      false
+    );
   };
   resize();
   return source?.observeResize(renderer.domElement, resize) ?? observeCanvasResize(renderer.domElement, resize);
 }
 async function createRenderer(options = {}) {
   const source = options.source;
+  const resolutionScale = options.resolutionScale ?? 1;
+  if (!Number.isFinite(resolutionScale) || resolutionScale <= 0)
+    throw new Error("renderer.resolutionScale must be finite and positive.");
   const canvas = options.canvas ?? source?.createCanvas() ?? document.createElement("canvas");
   const preferWebGPU = options.preferWebGPU ?? true;
   let renderer;
@@ -716,7 +2208,7 @@ async function createRenderer(options = {}) {
     const raw = options.webgl2Factory ? options.webgl2Factory(canvas) : new (await import('three')).WebGLRenderer({ canvas, antialias: true });
     renderer = wrapRenderer(raw, "webgl2");
   }
-  const stopResize = addResizeHandling(renderer, source);
+  const stopResize = addResizeHandling(renderer, source, resolutionScale);
   const dispose = renderer.dispose;
   renderer.dispose = () => {
     stopResize();
@@ -826,8 +2318,10 @@ function assertDelay(value, label) {
 }
 function createGameStore(initial, intervalMs = 100) {
   const store = createStore(() => ({ ...initial }));
+  const current = { value: store.getState() };
   let pending;
   let timer;
+  store.subscribe((state) => Object.assign(current, { value: state }));
   const flush = () => {
     if (pending === void 0) return;
     const patch = pending;
@@ -835,9 +2329,11 @@ function createGameStore(initial, intervalMs = 100) {
     store.setState(patch);
   };
   const gameStore = store;
+  gameStore.getState = () => current.value;
   gameStore.set = (patch) => {
-    const next = typeof patch === "function" ? patch(store.getState()) : patch;
+    const next = typeof patch === "function" ? patch(current.value) : patch;
     pending = { ...pending, ...next };
+    current.value = { ...current.value, ...next };
   };
   gameStore.flush = flush;
   gameStore.start = () => {
@@ -969,6 +2465,26 @@ function clearScene(scene, particles) {
   scene.environment = null;
   scene.fog = null;
 }
+function rendererPerformanceMetrics(raw) {
+  if (typeof raw !== "object" || raw === null) return {};
+  const info = raw.info;
+  if (typeof info !== "object" || info === null) return {};
+  const render = info.render;
+  if (typeof render !== "object" || render === null) return {};
+  const drawCalls = render.drawCalls;
+  const calls = drawCalls ?? render.calls;
+  const triangles = render.triangles;
+  return {
+    ...typeof calls === "number" && Number.isFinite(calls) && calls >= 0 ? { drawCalls: calls } : {},
+    ...typeof triangles === "number" && Number.isFinite(triangles) && triangles >= 0 ? { triangles } : {}
+  };
+}
+function addRenderPerformanceMetrics(world, overlay) {
+  return {
+    ...world.drawCalls === void 0 || overlay.drawCalls === void 0 ? {} : { drawCalls: world.drawCalls + overlay.drawCalls },
+    ...world.triangles === void 0 || overlay.triangles === void 0 ? {} : { triangles: world.triangles + overlay.triangles }
+  };
+}
 function createCamera(config) {
   if (config === void 0) return new PerspectiveCamera(60, 1, 0.1, 2e3);
   validateCameraConfig(config);
@@ -990,10 +2506,12 @@ var GameImpl = class {
   #state;
   #initialState;
   #loop;
+  #collapse;
   #cleanup = [];
   #particles = /* @__PURE__ */ new Set();
   #entities;
   #random;
+  #picker;
   #scheduler;
   #activePlugins = [];
   #disposedPlugins = /* @__PURE__ */ new Set();
@@ -1043,6 +2561,7 @@ var GameImpl = class {
     for (const plugin of this.#config.plugins ?? []) {
       if (typeof plugin !== "function") plugin.sceneExit?.(ctx);
     }
+    this.#collapse?.restore();
     clearScene(ctx.scene, this.#particles);
     const scene = new SceneType();
     this.#scene = scene;
@@ -1102,15 +2621,26 @@ var GameImpl = class {
     const inputTarget = this.#config.inputTarget ?? (platform === void 0 ? typeof window === "undefined" ? canvas : window : platform.inputTarget ?? canvas);
     this.#input = new InputMap(this.#config.input, inputTarget, canvas, platform?.input);
     this.#state.start();
-    const threeScene = new Scene$1();
+    const threeScene = new Scene();
     const camera = createCamera(this.#config.camera);
     const viewport = new Viewport({ camera, renderer: this.#renderer, source: platform?.viewport });
+    const canvasLayer = new CanvasLayer(viewport);
     this.#viewport = viewport;
     const assets = createAssetLoader(this.#config.assets);
     const entities = new Registry();
     const random = createRandom(this.#config.seed);
     const scheduler = new Scheduler();
+    const input = this.#input;
+    const picker = new ScenePicker({
+      camera,
+      pointer: () => input.raw.pointer.position,
+      scene: threeScene,
+      viewport
+    });
+    this.#picker = picker;
     const loopState = {};
+    const collapse = new SceneCollapse(threeScene);
+    this.#collapse = collapse;
     const ctx = {
       add: (object) => {
         threeScene.add(object);
@@ -1126,6 +2656,7 @@ var GameImpl = class {
       assets,
       after: (delay, callback) => scheduler.after(delay, callback),
       camera,
+      canvasLayer,
       entities,
       every: (callback) => scheduler.every(callback),
       get fps() {
@@ -1135,6 +2666,17 @@ var GameImpl = class {
       input: this.#input,
       physics: void 0,
       random,
+      raycast: (options) => picker.raycast(options),
+      startup: {
+        get phase() {
+          if (collapse.settled) return "ready";
+          return collapse.progress >= 1 ? "collapsing" : "observing";
+        },
+        get progress() {
+          return collapse.progress;
+        },
+        whenReady: () => collapse.whenSettled()
+      },
       renderer: this.#renderer,
       viewport,
       scene: threeScene,
@@ -1159,8 +2701,19 @@ var GameImpl = class {
             particle.process(this.#renderer);
           }
         }
-        renderer.render(threeScene, camera);
-        this.#scene?.render(ctx);
+        this.#collapse?.frame();
+        let worldMetrics;
+        if (!canvasLayer.opaque) {
+          renderer.render(threeScene, camera);
+          this.#scene?.render(ctx);
+          worldMetrics = rendererPerformanceMetrics(renderer.raw);
+        }
+        if (canvasLayer.scene.children.length > 0) {
+          renderer.renderOverlay(canvasLayer.scene, canvasLayer.camera);
+          const overlayMetrics = rendererPerformanceMetrics(renderer.raw);
+          return worldMetrics === void 0 ? overlayMetrics : addRenderPerformanceMetrics(worldMetrics, overlayMetrics);
+        }
+        return worldMetrics ?? {};
       },
       onUpdate: (dt) => {
         if (this.#paused) return;
@@ -1173,17 +2726,23 @@ var GameImpl = class {
         else scene2?.update(ctx, dt);
         if (this.#scene !== scene2 || this.#sceneFrame !== frame) return;
         for (const plugin of this.#activePlugins) plugin.update?.(ctx, dt);
+        this.#entities?.sweep();
       },
       step: this.#config.step
     });
     loopState.current = gameLoop;
     this.#loop = gameLoop;
+    const startGates = [];
     const runtime = {
       fixedStep: (ticks) => gameLoop.advance(ticks),
+      holdStart: (gate) => startGates.push(gate),
+      observations: createRuntimeObservations(),
+      tick: gameLoop.tick,
       random,
       rapier: null,
       seed: this.#config.seed ?? null,
-      step: gameLoop.step
+      step: gameLoop.step,
+      runtimeDiagnosticsSeries: () => gameLoop.runtimeDiagnosticsSeries()
     };
     for (const plugin of this.#config.plugins ?? []) {
       const cleanup = typeof plugin === "function" ? plugin(ctx) : await plugin.setup?.(ctx, runtime);
@@ -1210,6 +2769,18 @@ var GameImpl = class {
       this.#teardown(ctx);
       return;
     }
+    if (startGates.length > 0) {
+      try {
+        await Promise.all(startGates);
+      } catch (error) {
+        this.#teardown(ctx);
+        throw error;
+      }
+      if (this.#aborted) {
+        this.#teardown(ctx);
+        return;
+      }
+    }
     this.#started = true;
     gameLoop.start();
   }
@@ -1244,6 +2815,7 @@ var GameImpl = class {
     if (ctx !== void 0) clearScene(ctx.scene, this.#particles);
     this.#input?.dispose();
     this.#state.stop();
+    ctx?.canvasLayer.dispose();
     this.#viewport?.dispose();
     const renderer = this.#renderer;
     renderer?.dispose();
@@ -1258,15 +2830,126 @@ var GameImpl = class {
     this.#ctx = void 0;
     this.#loop = void 0;
     this.#random = void 0;
+    this.#picker?.dispose();
+    this.#picker = void 0;
     this.#scheduler = void 0;
     this.#disposedPlugins.clear();
     this.#paused = false;
     this.#started = false;
+    if ((ctx?.scene.children.length ?? 0) > 0)
+      throw new Error("IGame teardown leaked scene objects.");
   }
 };
+function createRuntimeObservations() {
+  const contributions = /* @__PURE__ */ new Set();
+  return {
+    contribute: (contribution) => {
+      contributions.add(contribution);
+      return () => contributions.delete(contribution);
+    },
+    contributions: () => [...contributions]
+  };
+}
 function defineGame(config) {
   return new GameImpl(config);
 }
+var CURVE_DIVISIONS = 128;
+var PathFollow3D = class {
+  curve;
+  loop;
+  totalLength;
+  #samples;
+  #progress = 0;
+  #speed;
+  constructor(options) {
+    if (options.points.length < 3) throw new Error("PathFollow3D requires at least three points.");
+    if (options.speed !== void 0 && (!Number.isFinite(options.speed) || options.speed < 0))
+      throw new Error("PathFollow3D speed must be a finite non-negative number.");
+    const points = options.points.map((point) => {
+      if (![point.x, point.y, point.z].every(Number.isFinite))
+        throw new Error("PathFollow3D points must be finite.");
+      return point.clone();
+    });
+    this.loop = options.loop ?? false;
+    this.#speed = options.speed ?? 0;
+    this.curve = new CatmullRomCurve3(points, this.loop, "centripetal", 0.5);
+    this.totalLength = this.curve.getLengths(CURVE_DIVISIONS).at(-1) ?? 0;
+    if (!(this.totalLength > 0)) throw new Error("PathFollow3D requires a positive-length path.");
+    const spaced = this.curve.getSpacedPoints(CURVE_DIVISIONS);
+    this.#samples = this.loop ? spaced.slice(0, CURVE_DIVISIONS) : spaced;
+  }
+  get completed() {
+    return !this.loop && this.#progress >= this.totalLength;
+  }
+  get progress() {
+    return this.#progress;
+  }
+  get speed() {
+    return this.#speed;
+  }
+  set speed(value) {
+    if (!Number.isFinite(value) || value < 0)
+      throw new Error("PathFollow3D speed must be a finite non-negative number.");
+    this.#speed = value;
+  }
+  advance(dt) {
+    if (!Number.isFinite(dt) || dt < 0)
+      throw new Error("PathFollow3D.advance requires a finite non-negative delta.");
+    this.progressTo(this.#progress + this.#speed * dt);
+    return this.sample();
+  }
+  progressTo(distance) {
+    if (!Number.isFinite(distance) || distance < 0)
+      throw new Error("PathFollow3D progress must be a finite non-negative number.");
+    this.#progress = this.loop ? distance % this.totalLength : Math.min(distance, this.totalLength);
+    return this;
+  }
+  sample(distance = this.#progress) {
+    if (!Number.isFinite(distance) || distance < 0)
+      throw new Error("PathFollow3D sample distance must be a finite non-negative number.");
+    const progress = this.loop ? distance % this.totalLength : Math.min(distance, this.totalLength);
+    const u = progress / this.totalLength;
+    return {
+      point: this.curve.getPointAt(u),
+      progress,
+      tangent: this.curve.getTangentAt(u).normalize()
+    };
+  }
+  pointAt(distance) {
+    return this.sample(distance);
+  }
+  project(position) {
+    if (![position.x, position.y, position.z].every(Number.isFinite))
+      throw new Error("PathFollow3D projection position must be finite.");
+    let nearest = Number.POSITIVE_INFINITY;
+    let nearestIndex = 0;
+    for (const [index, sample] of this.#samples.entries()) {
+      const distance = sample.distanceToSquared(position);
+      if (distance < nearest) {
+        nearest = distance;
+        nearestIndex = index;
+      }
+    }
+    const last = this.#samples.length - 1;
+    const segmentCount = this.loop ? this.#samples.length : last;
+    const segment = Math.min(nearestIndex, Math.max(0, segmentCount - 1));
+    const point = this.#samples[nearestIndex];
+    if (point === void 0) throw new Error("PathFollow3D projection sample is missing.");
+    const tangentStart = this.#samples[segment];
+    if (tangentStart === void 0) throw new Error("PathFollow3D projection tangent is missing.");
+    const nextIndex = this.loop ? (segment + 1) % this.#samples.length : Math.min(segment + 1, last);
+    const next = this.#samples[nextIndex];
+    if (next === void 0) throw new Error("PathFollow3D projection tangent is missing.");
+    const distanceFromSample = nearestIndex / segmentCount * this.totalLength;
+    return {
+      distanceFromStart: distanceFromSample,
+      lateralDistance: point.distanceTo(position),
+      point: point.clone(),
+      segment,
+      tangent: next.clone().sub(tangentStart).normalize()
+    };
+  }
+};
 
 // ../playtest/dist/index.js
 var PLAYTEST_CAPABILITY_REGISTRY = [
@@ -1285,10 +2968,11 @@ var PLAYTEST_CAPABILITY_REGISTRY = [
   capability("runtime.audio", "Samples application-owned audio runtime state."),
   capability("runtime.components", "Samples registered JSON-safe component state."),
   capability("runtime.contacts", "Samples bounded collision and trigger contacts."),
-  capability("runtime.diagnostics", "Samples application-owned runtime diagnostics."),
+  capability("runtime.diagnostics", "Captures application runtime errors."),
   capability("runtime.events", "Drains bounded application event observations."),
   capability("runtime.fixedStep", "Advances an application-owned deterministic tick."),
   capability("runtime.physics", "Samples bounded application-owned physics observations."),
+  capability("runtime.performance", "Samples bounded per-render frame cost and renderer counts."),
   capability("runtime.resources", "Reads and writes registered JSON-safe application state."),
   capability("runtime.state", "Samples application-owned state-machine state."),
   capability("runtime.tags", "Samples bounded application-owned entity tags."),
@@ -1320,14 +3004,14 @@ function parseReplayRecording(value) {
     fail("bad header");
   const ticks = root.ticks;
   if (!Number.isInteger(ticks) || ticks < 1) fail("ticks must be positive");
-  const input2 = root.input;
-  if (!Array.isArray(input2) || input2.length === 0) fail("empty input", "TN_REPLAY_EMPTY");
+  const input = root.input;
+  if (!Array.isArray(input) || input.length === 0) fail("empty input", "TN_REPLAY_EMPTY");
   const runtime = checked(root.runtime, ["agent", "core", "rapier", "step"]);
   const step = runtime.step;
   if (typeof runtime.agent !== "string" || !runtime.agent || typeof runtime.core !== "string" || !runtime.core || runtime.rapier !== null && typeof runtime.rapier !== "string" || !Number.isFinite(step) || step <= 0)
     fail("runtime fingerprint is invalid");
   let previousTick = -1;
-  for (const rawSample of input2) {
+  for (const rawSample of input) {
     const sample = checked(rawSample, ["keys", "pointer", "tick"]);
     const tick = sample.tick;
     if (!Number.isInteger(tick) || tick <= previousTick || tick >= ticks) fail("bad tick");
@@ -1493,7 +3177,7 @@ function createReplayDriver(recording, target, pointerTarget = target) {
 }
 
 // src/scene.ts
-var Scene = class {
+var Scene2 = class {
   static initialState = void 0;
   load(_ctx) {
   }
@@ -1511,4 +3195,4 @@ var Scene = class {
 // src/index.ts
 var version = "0.1.0";
 
-export { AnimationPlayer, AudioBus, FixedStepLoop, GPUParticles3D, InputMap, Registry, Scene, Scheduler, Viewport, autoFields, createAssetLoader, createGameStore, createRandom, createRenderer, createReplayDriver, defineGame, input, replay, version };
+export { AnimationPlayer, AudioBus, CanvasLayer, GPUParticles3D, PathFollow3D, Scene2 as Scene, ScenePicker, Scheduler, createRandom, createReplayDriver, defineGame, replay, version };