@volter/threejs-runtime 0.5.66 → 0.5.67

package/package.json

@@ -2,7 +2,7 @@
   "name": "@volter/threejs-runtime",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.66",
+  "version": "0.5.67",
   "publishConfig": {
     "access": "public"
   },
@@ -43,7 +43,7 @@
     "@dimforge/rapier3d-compat": "^0.14.0",
     "@recast-navigation/three": "^0.43.0",
     "@sparkjsdev/spark": "^2.1.0",
-    "@volter/editor-project": "0.5.66",
+    "@volter/editor-project": "0.5.67",
     "n8ao": "^1.10.1",
     "postprocessing": "^6.38.0",
     "quarks.core": "0.16.0",

package/src/adapter/first-party-navigation-system.ts

@@ -5,11 +5,9 @@
  * external game can supply its own equivalent.
  *
  * Its AUDIO sibling (`createAudioSystemAdapter`, `releaseAudioMeters`) is the
- * game runtime's — `@volter/game-runtime/adapter/first-party-audio-system` — for
+ * game runtime's — `@volter/editor-game/runtime/adapter/first-party-audio-system` — for
  * the same reason this one is three.js's: each lives with the subsystem it
- * wraps. (The former `AnimationAdapter` over the `AnimGraph` map was removed
- * by E5; `createInputManagerAdapter`/`createVgaiAssetAdapter` went with
- * `SystemAdapters.input`/`.assets`, registered and never read.)
+ * wraps.
  */
 
 import type {
@@ -40,7 +38,7 @@ export function createNavigationAdapter(
     hasNavMesh: () => nav.hasNavMesh(),
     findPath: (start: NavPoint, end: NavPoint) => nav.findPath(start, end) as NavPoint[],
     debugMesh: (scene: THREE.Scene) => nav.getDebugMesh(scene) as unknown as THREE.Object3D | null,
-    bake: ownerCapabilities.bake ?? ((meshes, params) => nav.buildFromMeshes(meshes, params)),
+    bake: ownerCapabilities.bake ?? ((meshes: THREE.Mesh[], params?: NavBakeParams) => nav.buildFromMeshes(meshes, params)),
     exportData: () => nav.exportData(),
     ...(ownerCapabilities.clear ? { clear: ownerCapabilities.clear } : {}),
     crowdAgents: () => nav.getCrowdAgents(),

package/src/adapter/rapier-physics-adapter.ts

@@ -57,7 +57,7 @@ export interface RapierEditableBody {
  * mount is no longer the only Rapier in this engine: an R3F world does its
  * physics with `@react-three/rapier` inside the fiber tree, which owns its own
  * bodies and its own `Object3D` mapping, and reaches these same four verbs
- * through `world3d-react/rapier-physics-bridge.tsx`. The optional members
+ * through the editor's observer of that world (`editor-game/src/services/game-physics.ts`). The optional members
  * (`debugDraw`, `setDebugDrawEnabled`, `contactPoints`) are NOT here: each is
  * answered differently by each Rapier owner, and a caller that cannot answer
  * one honestly omits it.

package/src/adapter/renderer-config.ts

@@ -4,9 +4,8 @@
  * The SHAPE is the project contract's (`@volter/editor-project/adapter/renderer-config`,
  * whose header states the rule and the three load-bearing properties); this
  * file is what writes it onto a live `WebGLRenderer` and hands back the
- * restore. `world3d-react/r3f-root-factory.tsx` is the declarer,
- * `runtime/create-runtime.ts` the host, the editor's world-root stage the
- * applier.
+ * restore. A mounted three root declares it (`MountedThreeRoot.rendererConfig`)
+ * and the editor's world-root stage applies it.
  */
 
 import type {
@@ -28,7 +27,7 @@ export type {
  * Apply `config` to `renderer`, returning the restore function that puts back what was there.
  *
  * `three` is passed in rather than imported for values so the enum constants come from the HOST's
- * three instance — the same identity rule `r3f-root-factory.tsx` follows for the scene and camera.
+ * three instance — the same identity rule `r3f-root.tsx` follows for the scene and camera.
  */
 export function applyWorldRendererConfig(
   three: typeof THREE,

package/src/assets.ts

@@ -11,10 +11,21 @@
  * Cache lives for the app lifetime — no dispose needed.
  */
 
-import type { AssetCache, GLTFResult } from '@volter/editor-project/adapter/asset-cache';
+import type * as THREE from 'three';
 import { gltfLoader, resolveUrl } from './loader';
 
-export type { AssetCache, GLTFResult } from '@volter/editor-project/adapter/asset-cache';
+/** Result of loading a .glb/.gltf file. */
+export interface GLTFResult {
+  scene: THREE.Group;
+  animations: THREE.AnimationClip[];
+}
+
+export interface AssetCache {
+  /** Load an asset by URL. Returns a cached promise if already loading/loaded. */
+  load<T = unknown>(url: string): Promise<T>;
+  /** Get a previously-loaded asset synchronously. Throws if not yet loaded. */
+  get<T = unknown>(url: string): T;
+}
 
 export function createAssetCache(): AssetCache {
   const cache = new Map<string, Promise<unknown>>();

package/src/ecs/object-marks.ts

@@ -33,7 +33,7 @@ export type EditorHelperType =
   | 'trigger-volumes'
   | 'skeletons'
   // A package's own helper kind, shown through the editor's viewport door
-  // (`host.viewport.setHelper`): the host lists the kinds it toggles by name,
+  // (the viewport door's `setViewportHelper`): the host lists the kinds it toggles by name,
   // any other follows the master Helpers toggle.
   | (string & {});
 

package/src/ecs/user-data.ts

@@ -40,11 +40,6 @@
  * - `gaussianSplat`       — native Spark splat metadata used for renderer discovery,
  *                           inspector facts, bounds, and deterministic disposal.
  *
- * Animation (load-bearing — ED5 disposal contract):
- * - `_animMixer`          — THREE.AnimationMixer driving this subtree's clips.
- * - `_availableClips`     — string[] of clip names discovered on the GLTF
- *                           (inspector dropdown).
- *
  * Disposal contract:
  * - `__sharedGeometry`    — `true` when a mesh's geometry is shared/cached and MUST
  *                           NOT be disposed by per-object cleanup (P0.2 contract).
@@ -144,8 +139,6 @@ export interface UserDataSchema extends ObjectMarkSchema {
   _camera: THREE.Camera;
   _particleSystem: ParticleSystem;
   gaussianSplat: { src: string; numSplats: number };
-  _animMixer: THREE.AnimationMixer;
-  _availableClips: string[];
   __sharedGeometry: boolean;
   __shadeOrig: THREE.Material | THREE.Material[];
   __shadeUnlit: THREE.Material[];
@@ -197,8 +190,6 @@ export const UserDataKeys = {
   _camera: '_camera',
   _particleSystem: '_particleSystem',
   gaussianSplat: 'gaussianSplat',
-  _animMixer: '_animMixer',
-  _availableClips: '_availableClips',
   __sharedGeometry: '__sharedGeometry',
   __shadeOrig: '__shadeOrig',
   __shadeUnlit: '__shadeUnlit',

package/src/render/render-features.ts

@@ -13,9 +13,7 @@ import { z } from 'zod';
  * until `schema-consumption-map.ts` names the file that reads it.
  *
  * Three entries were deleted when that enforcement first ran, having reached it
- * with no reader at all: `autoBatch` (its only mention was a COMMENT in
- * `render-batch-system.ts`, a class whose own header says nothing calls it),
- * `lod`, and `backend` (which offered a `webgpu` option while
+ * with no reader at all: `autoBatch`, `lod`, and `backend` (which offered a `webgpu` option while
  * `setup-renderer.ts` unconditionally constructs a `THREE.WebGLRenderer`). A
  * toggle that changes nothing is worse than a missing one — it tells an author
  * the engine has a dial it does not have.

package/src/render/structural-signature.ts

@@ -3,13 +3,12 @@
  * place that answers "may this draw be collapsed at all?" and "are these two
  * meshes the same thing drawn twice?".
  *
- * Three consumers, which is the whole reason it is a module rather than three
- * private helpers: `render/render-batch-system.ts` (the engine's own
- * lab-driven instancer), `dev/render-census.ts`'s structural scan (what the
- * advisor and `render.families` measure), and the `static-batch` capability's
- * `<Frozen>` (what a game actually installs). A batcher and the advisor that
- * routes people to it MUST agree about what is batchable, or the advisor
- * promises a win the wrapper then declines to take.
+ * Two consumers, which is the whole reason it is a module rather than private
+ * helpers: `dev/render-census.ts`'s structural scan (what the advisor and
+ * `render.families` measure) and the `static-batch` capability's `<Frozen>`
+ * (what a game actually installs). A batcher and the advisor that routes
+ * people to it MUST agree about what is batchable, or the advisor promises a
+ * win the wrapper then declines to take.
  *
  * ── THE UUID TRAP, WHICH IS WHY THIS MODULE EXISTS ──────────────────────────
  * The obvious key for "can these two meshes be drawn as one" is object
@@ -28,9 +27,7 @@
  * OWN `THREE.MeshStandardMaterial`. Five hundred crates are five hundred
  * distinct uuids describing one identical appearance. A uuid-keyed grouper
  * reports five hundred families of one, finds nothing to do, and is indistin-
- * guishable from a correct batcher over an unbatchable scene. The engine's own
- * scene construction has the same property, which is why
- * `render/render-batch-system.ts` has keyed on VALUE since it was written.
+ * guishable from a correct batcher over an unbatchable scene.
  *
  * So the key here is the STRUCTURE: geometry `type` + its construction
  * `parameters`, material `type` + the props that decide what the draw looks
@@ -49,14 +46,10 @@
  *   - a shader material ({@link materialMergeSignature} only): its appearance
  *     lives in shader source and uniforms that no fixed prop list can read.
  *
- * ── TWO KEYS, DELIBERATELY ──────────────────────────────────────────────────
- * {@link staticBatchSignature} is `RenderBatchSystem`'s key, extracted here
- * unchanged so there is one owner of the answer rather than two that drift.
- * {@link materialMergeSignature} is STRICTER, and it is what the `static-batch`
- * capability's `<Frozen>` groups by: that path hands ONE material instance to
- * a merged/instanced product, so its members must be interchangeable, not
- * merely similar. The looser key predates it and is kept exactly as it was —
- * see that constant's own note.
+ * ── THE KEY ─────────────────────────────────────────────────────────────────
+ * {@link materialMergeSignature} is what `<Frozen>` groups by: that path hands
+ * ONE material instance to a merged/instanced product, so its members must be
+ * interchangeable, not merely similar.
  */
 
 import type * as THREE from 'three';
@@ -144,14 +137,10 @@ export function geometrySignature(geometry: THREE.BufferGeometry): string {
 }
 
 /**
- * Material identity as `RenderBatchSystem` has always computed it: type plus
- * the standard-material props that change the draw.
- *
- * FROZEN ON PURPOSE. This is one half of {@link staticBatchSignature}, which
- * is a live batcher's grouping key; widening or narrowing it silently
- * regroups that batcher's scenes. New discrimination goes in
- * {@link materialMergeSignature}, which is free to be stricter because
- * stricter only ever means "batches less".
+ * The standard-material props that change the draw: type, colour, roughness,
+ * metalness, colour map, side, transparency and vertex colours. The base of
+ * {@link materialMergeSignature}, which adds everything else that decides the
+ * picture.
  */
 export function materialSignature(material: THREE.Material): string {
   const standard = material as THREE.MeshStandardMaterial;
@@ -160,19 +149,6 @@ export function materialSignature(material: THREE.Material): string {
   return `${material.type}:${color}:${standard.roughness ?? ''}:${standard.metalness ?? ''}:${map}:${material.side}:${material.transparent}:${material.vertexColors}`;
 }
 
-/**
- * One mesh's batch key: geometry, material, and the shadow flags.
- *
- * The shadow flags are part of the key because a batched product carries ONE
- * `castShadow`/`receiveShadow` pair for every member it swallowed — mixing a
- * caster and a non-caster into one draw changes the picture.
- */
-export function staticBatchSignature(mesh: THREE.Mesh): string {
-  const geometry = mesh.geometry as THREE.BufferGeometry;
-  const material = mesh.material as THREE.Material;
-  return `${geometrySignature(geometry)}|${materialSignature(material)}|${mesh.castShadow ? 1 : 0}${mesh.receiveShadow ? 1 : 0}`;
-}
-
 /**
  * Which vertex attributes a geometry carries, and whether it is indexed —
  * the compatibility precondition for `mergeGeometries`, which refuses a batch
@@ -192,9 +168,9 @@ export function geometryLayoutSignature(geometry: THREE.BufferGeometry): string
 
 /**
  * Material identity for a path that will SHARE one material instance between
- * every member it collapses — stricter than {@link materialSignature}.
+ * every member it collapses.
  *
- * Everything the looser key reads, plus the props that decide the picture
+ * Everything {@link materialSignature} reads, plus the props that decide the picture
  * without touching colour/roughness/metalness: opacity and the depth/blend
  * state, emissive, the remaining standard maps, and the flags that change the
  * compiled program. A shader material answers with its uuid instead (see the

package/src/render/viewport-shading.ts

@@ -4,6 +4,10 @@ import { createNeutralMatcapTexture } from './matcap-texture';
 /** Temporary developer-facing shading modes. These never become scene data. */
 export type ViewportShadingMode =
   | 'solid'
+  /** Authored materials, as `solid`; a stage lights it by a preview (Blender's Material Preview). */
+  | 'preview'
+  /** Authored materials, as `solid`; a stage lights it by the scene (Blender's Rendered). */
+  | 'rendered'
   | 'clay'
   | 'unlit'
   | 'wireframe'
@@ -65,7 +69,7 @@ export class ViewportShadingRenderer {
     draw: () => void,
     include: (mesh: THREE.Mesh) => boolean = () => true,
   ): void {
-    if (mode === 'solid') {
+    if (mode === 'solid' || mode === 'preview' || mode === 'rendered') {
       draw();
       return;
     }
@@ -107,7 +111,7 @@ export class ViewportShadingRenderer {
 
   private _materialFor(
     material: THREE.Material,
-    mode: Exclude<ViewportShadingMode, 'solid'>,
+    mode: Exclude<ViewportShadingMode, 'solid' | 'preview' | 'rendered'>,
   ): THREE.Material {
     if (mode === 'normals') return this._normals;
     if (mode === 'overdraw') return this._overdraw;

package/src/render/render-batch-system.ts

@@ -1,260 +0,0 @@
-import * as THREE from 'three';
-import { getUserData } from '../ecs/user-data';
-import type { ResolvedRenderSettings } from './render-settings';
-import { staticBatchSignature } from './structural-signature';
-
-/**
- * Runtime STATIC render-batching (the framework-level transparent perf delivery).
- *
- * Scans a loaded scene graph for STATIC meshes sharing geometry+material and draws
- * each group through ONE InstancedMesh. The originals are DETACHED from the render
- * tree (so the renderer never walks them — zero per-frame cost), but retained here
- * as the logical handles: re-attached on teardown, and resolvable via raycast().
- * N logical objects → 1 draw call, ~0 CPU/frame. This is the classic "static
- * batching" technique (cf. Unity/PlayCanvas static batch groups).
- *
- * Strategy 1 (keep identity, don't merge). Moving entities (boids-style,
- * all-frame churn) are a separate concern, and the engine does not answer it:
- * a game's production answer is the `static-batch` capability's `<Frozen>`
- * (see the scope note below).
- *
- * Eligibility (anything failing stays an ordinary draw — degrade, don't break):
- *   - plain THREE.Mesh (not Instanced/Skinned/Batched)
- *   - single, opaque material (transparency needs per-object sorting)
- *   - group of ≥2 sharing (geometry, material, shadow flags)
- *   - (there is no per-entity opt-out setting: this docblock used to name
- *     `entity.render.autoBatch === false`, a render-feature field NO CODE HERE
- *     OR ANYWHERE EVER READ. The field was deleted with R-2's coverage fix;
- *     opting a subtree out is the `static-batch` capability's `<Frozen>`
- *     declaration, per the scope note below.)
- *   - STATIC members (no physics/components/animation) → detached; MOVING members →
- *     kept in-graph hidden + dirty-synced each frame. A bucket may split into both.
- *
- * Scope / limitations (v1):
- *   - NOT WIRED: nothing in the engine calls build(), and nothing constructs
- *     this class. The only remaining reference is the hosted editor's
- *     project-script module map (`editor/src/served-bundle-runtime-modules.ts`),
- *     which loads the module so a project script MAY drive it; the example
- *     that used to is gone. That is settled, not pending: a game's
- *     production answer is the `static-batch` capability's `<Frozen>`, a
- *     DECLARED mount-static subtree in the game's own TSX, and `dev/static-
- *     batch-advisor.ts` is what routes an author to it by measurement. Full-
- *     auto inference over a scene nobody declared static is what this class
- *     would need to become, and it was rejected (issue #1503).
- *   - build() is a one-shot scan of the scene handed to it. Entities spawned
- *     AFTER build do not join a batch; call build() again to re-scan. Removing a batched
- *     source leaves a stale instance until rebuild. (Static scenery is load-time stable.)
- *   - The batch culls as ONE unit (no per-instance frustum culling yet — Tier-2).
- */
-
-interface Group {
-  instanced: THREE.InstancedMesh;
-  sources: THREE.Mesh[]; // instanceId → source (raycast mapping + restore on teardown)
-  dynamic: boolean; // true = sources kept in the graph & re-synced each frame (movers)
-  cache?: Float32Array; // dynamic only: last-synced matrixWorld elements (16/source)
-}
-
-// Structural signature — groups meshes that are VALUE-identical, not object-identical.
-// The engine scene-loader instantiates a fresh geometry+material per entity (no dedup),
-// so keying on .uuid would never batch a real scene; a TSX/R3F world writing inline
-// `<meshStandardMaterial>` elements has exactly the same property. That key lives in
-// `render/structural-signature.ts` — ONE owner, shared with the `static-batch`
-// capability's `<Frozen>`, so the two cannot drift into disagreeing about what
-// "the same draw" means. `staticBatchSignature` is this file's original key, moved.
-const SIG = staticBatchSignature;
-
-/** Match Three.js renderer visibility: a hidden ancestor hides the whole subtree. */
-function isEffectivelyVisible(obj: THREE.Object3D): boolean {
-  let cur: THREE.Object3D | null = obj;
-  while (cur) {
-    if (!cur.visible) return false;
-    cur = cur.parent;
-  }
-  return true;
-}
-
-function isBatchCandidate(object: THREE.Object3D, batchRoot: THREE.Group): object is THREE.Mesh {
-  const mesh = object as THREE.Mesh;
-  if (!mesh.isMesh) return false;
-  if ((mesh as THREE.InstancedMesh).isInstancedMesh) return false;
-  if ((mesh as THREE.SkinnedMesh).isSkinnedMesh) return false;
-  if ((mesh as unknown as THREE.BatchedMesh).isBatchedMesh) return false;
-  if (!isEffectivelyVisible(mesh)) return false;
-  if (!mesh.geometry || !mesh.material || Array.isArray(mesh.material)) return false;
-  if ((mesh.material as THREE.Material).transparent) return false;
-  return batchRoot !== mesh.parent;
-}
-
-/**
- * Static-batching eligibility: only objects that won't move are safe to freeze
- * and instance. An object (or an ancestor) carrying its own animation mixer is
- * a likely mover → left as an ordinary draw. Plain scenery is eligible. This is
- * the safe, transparent default; a future dynamic-batch path (markMoved-driven)
- * can include movers.
- */
-function isLikelyStatic(obj: THREE.Object3D): boolean {
-  let cur: THREE.Object3D | null = obj;
-  while (cur) {
-    if (getUserData(cur, '_animMixer')) return false;
-    cur = cur.parent;
-  }
-  return true;
-}
-
-export class RenderBatchSystem {
-  private root = new THREE.Group();
-  private groups: Group[] = [];
-  private dynamicGroups: Group[] = []; // subset needing per-frame sync
-  // Original parent of each detached (static) source, to re-attach on teardown.
-  private parentOf = new WeakMap<THREE.Mesh, THREE.Object3D>();
-  // instanceId mapping for raycast: which group + slot an InstancedMesh belongs to.
-  private membersOf = new WeakMap<THREE.InstancedMesh, THREE.Mesh[]>();
-
-  constructor(
-    private scene: THREE.Scene,
-    private settings: ResolvedRenderSettings,
-  ) {
-    this.root.name = 'RenderBatchSystem';
-    this.root.matrixAutoUpdate = false; // instances carry world matrices directly
-  }
-
-  /** Scan the scene and build instanced groups. Idempotent (rebuilds). */
-  build(): void {
-    this.teardown();
-    this.scene.add(this.root);
-    this.scene.updateMatrixWorld(true);
-
-    // collect eligible candidates, grouped by (geometry, material)
-    const buckets = new Map<string, THREE.Mesh[]>();
-    this.scene.traverse((obj) => {
-      if (!isBatchCandidate(obj, this.root)) return;
-      const key = SIG(obj);
-      const arr = buckets.get(key) ?? [];
-      arr.push(obj);
-      buckets.set(key, arr);
-    });
-
-    // Each signature bucket is partitioned into STATIC (detached, zero-cost) and
-    // DYNAMIC (kept in-place, dirty-synced) members, each ≥2 forming its own batch.
-    for (const bucket of buckets.values()) {
-      const staticMembers: THREE.Mesh[] = [];
-      const dynamicMembers: THREE.Mesh[] = [];
-      for (const m of bucket) (isLikelyStatic(m) ? staticMembers : dynamicMembers).push(m);
-      if (staticMembers.length >= 2) this.makeGroup(staticMembers, false);
-      if (dynamicMembers.length >= 2) this.makeGroup(dynamicMembers, true);
-    }
-  }
-
-  private makeGroup(sources: THREE.Mesh[], dynamic: boolean): void {
-    const frustum = this.settings['frustumCulling'] !== false;
-    const tmp = new THREE.Matrix4();
-    const proto = sources[0]!;
-    const inst = new THREE.InstancedMesh(
-      proto.geometry,
-      proto.material as THREE.Material,
-      sources.length,
-    );
-    inst.frustumCulled = frustum && !dynamic; // moving batches can leave the padded sphere
-    // Inherit shadow flags from the prototype so batched objects still cast/receive
-    // shadows (otherwise detaching the sources would silently drop them from shadows).
-    inst.castShadow = proto.castShadow;
-    inst.receiveShadow = proto.receiveShadow;
-    const cache = dynamic ? new Float32Array(sources.length * 16) : undefined;
-    for (let i = 0; i < sources.length; i++) {
-      const s = sources[i]!;
-      tmp.copy(s.matrixWorld);
-      inst.setMatrixAt(i, tmp);
-      if (dynamic) {
-        // keep the source in the graph (physics/animation still updates its matrixWorld),
-        // just hide its own draw; we copy its world matrix into the instance each frame.
-        cache!.set(tmp.elements, i * 16);
-        s.visible = false;
-      } else if (s.parent) {
-        // static: detach entirely so the renderer never walks it (zero per-frame cost)
-        this.parentOf.set(s, s.parent);
-        s.parent.remove(s);
-      }
-    }
-    inst.instanceMatrix.needsUpdate = true;
-    if (frustum && !dynamic) inst.computeBoundingSphere();
-    this.membersOf.set(inst, sources);
-    this.root.add(inst);
-    const group: Group = cache
-      ? { instanced: inst, sources, dynamic, cache }
-      : { instanced: inst, sources, dynamic };
-    this.groups.push(group);
-    if (dynamic) this.dynamicGroups.push(group);
-  }
-
-  /**
-   * Per-frame sync for DYNAMIC groups only (static are detached & immutable → free).
-   * Called in the preRender phase. Refreshes world matrices once (the engine's movers
-   * set matrixWorldNeedsUpdate via physics/animation), then re-writes only the instances
-   * whose source moved (element-wise cache compare). No-op when there are no movers.
-   */
-  update(): void {
-    if (this.dynamicGroups.length === 0) return;
-    this.scene.updateMatrixWorld(false); // refresh moved subtrees (force=false → cheap)
-    for (const g of this.dynamicGroups) {
-      const cache = g.cache!;
-      let dirty = false;
-      for (let i = 0; i < g.sources.length; i++) {
-        const el = g.sources[i]!.matrixWorld.elements;
-        const off = i * 16;
-        let changed = false;
-        for (let k = 0; k < 16; k++) {
-          if (el[k] !== cache[off + k]) {
-            changed = true;
-            break;
-          }
-        }
-        if (!changed) continue;
-        g.instanced.setMatrixAt(i, g.sources[i]!.matrixWorld);
-        cache.set(el, off);
-        dirty = true;
-      }
-      if (dirty) g.instanced.instanceMatrix.needsUpdate = true;
-    }
-  }
-
-  /**
-   * Raycast against the batched instances, mapping a hit back to the logical source
-   * Object3D (so editor/gameplay picking still resolves a detached entity).
-   */
-  raycast(raycaster: THREE.Raycaster): THREE.Mesh | null {
-    const hits = raycaster.intersectObject(this.root, true);
-    for (const h of hits) {
-      const members = this.membersOf.get(h.object as THREE.InstancedMesh);
-      if (members && h.instanceId != null) return members[h.instanceId] ?? null;
-    }
-    return null;
-  }
-
-  /** Number of draw calls the batcher contributes (1 per group). */
-  get drawCalls(): number {
-    return this.groups.length;
-  }
-
-  /** How many source meshes were collapsed into instances. */
-  get batchedCount(): number {
-    return this.groups.reduce((n, g) => n + g.sources.length, 0);
-  }
-
-  teardown(): void {
-    for (const g of this.groups) {
-      for (const s of g.sources) {
-        if (g.dynamic)
-          s.visible = true; // dynamic sources stayed in-graph, hidden
-        else {
-          const parent = this.parentOf.get(s); // static sources were detached — re-attach
-          if (parent) parent.add(s);
-        }
-      }
-      g.instanced.dispose();
-      this.root.remove(g.instanced);
-    }
-    this.groups = [];
-    this.dynamicGroups = [];
-    if (this.root.parent) this.root.parent.remove(this.root);
-  }
-}