@vgai/engine 0.2.0

package/src/react/game-state.tsx

@@ -0,0 +1,172 @@
+/**
+ * Engine-PUBLISHED `GameProvider`/`useGame`/`useGameState`/`useWorldObservation`
+ * (D-Z5, `docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md` §D-Z5) — the canonical,
+ * opt-in react entry for the T7.4 state bridge (`docs/REACT-STATE-BRIDGE.md`
+ * §3). This is a SEPARATE, react-value-importing module under
+ * `packages/engine/src/react/` — colocated per REACT-STATE-BRIDGE §3's own
+ * "colocate the react-facing hooks with the HUD seam, not the react-free
+ * core" rule, just now living IN the engine package rather than only in the
+ * project template. It is imported by NOTHING in the engine core import
+ * graph (`packages/engine/src/` outside this `react/` directory) — that
+ * invariant is proved by `packages/engine/test/react-core-import-ban.test.ts`
+ * (AC-F1).
+ *
+ * This module is the SPEC others port faithfully: it was originally authored
+ * as `packages/editor/template/src/ui/game-state.tsx` (T7.4); that file is
+ * now a thin re-export of this one (D-Z5 step 3) so every NEW scaffolded
+ * project gets ONE canonical context, while existing projects with their own
+ * full copy (their own `createContext`) keep working untouched — adoption of
+ * THIS module is an option, never a forced migration (D-Z5).
+ *
+ * Context-identity landmine (unchanged from the template file's own history,
+ * still the reason `loadProjectGameProvider`/the virtual-module plugin exist
+ * in `packages/editor/src/adapter-resolver.ts` /
+ * `packages/editor/vite-plugin-react-world-provider.ts`): `<GameProvider>`
+ * and `useGame()` must resolve against the SAME `createContext()` call. A
+ * project that ships its OWN `src/ui/game-state.tsx` (its own
+ * `createContext`) must be wrapped by ITS OWN `GameProvider` — wrapping it
+ * with THIS module's `GameProvider` instead would split context and
+ * `useGame()` would throw "no Game in context" even though a `<GameProvider>`
+ * genuinely wraps the tree (proved by
+ * `packages/editor/test/game-state-context-split.test.tsx`, AC-F1). This is
+ * exactly why the engine-published fallback (`resolveIngestReactAdapter`'s
+ * D-Y3 upgrade, `default-react`'s optional fallback) only ever fires when the
+ * project's OWN `src/ui/game-state.tsx` is ABSENT — an unmodified foreign
+ * entry that imports no vgai hooks has no context to split.
+ */
+
+import { createContext, type ReactNode, useContext, useRef, useSyncExternalStore } from 'react';
+import type { WorldStateObserver } from '../adapter';
+import { createFrameSelectorCache, type Equals, shallow } from '../runtime/frame-selector-cache';
+import type { Game } from '../runtime/game';
+
+/** Re-exported for convenience — the opt-in equality for selectors that
+ *  return a fresh object/array/tuple every call (default is `Object.is`). */
+export { shallow };
+
+const GameContext = createContext<Game | null>(null);
+
+/** Provide the `Game` to `useGameState`/`useGame` for everything mounted
+ *  beneath it. Compose it around whatever renders your tree (`mountUI`, a
+ *  react world's `createRoot(...).render(...)`, etc.) — see the module doc
+ *  comment above for the context-identity rule this hook family depends on. */
+export function GameProvider({ game, children }: { game: Game; children: ReactNode }) {
+  return <GameContext.Provider value={game}>{children}</GameContext.Provider>;
+}
+
+/** Read the `Game` provided by the nearest `GameProvider`. Throws
+ *  descriptively when called outside one — matching the repo's loud-failure
+ *  habit rather than silently returning `null`. */
+export function useGame(): Game {
+  const game = useContext(GameContext);
+  if (!game) {
+    throw new Error(
+      'useGame: no Game in context — wrap this component in <GameProvider game={ctx.game!}>.',
+    );
+  }
+  return game;
+}
+
+/**
+ * Subscribe to a selected slice of game state (`docs/REACT-STATE-BRIDGE.md`
+ * §3). Re-renders only when the selected value changes: the selector re-runs
+ * at most once per completed frame (`game.state.frameVersion`), and
+ * `equals` (default `Object.is`; pass {@link shallow} for tuples/objects)
+ * gates whether the fresh result actually counts as a change.
+ *
+ * `selector` reads the live graph (e.g.
+ * `g => g.queryByComponent(Hp)[0]?.hp`) at post-frame quiescence — no
+ * copies. A selector that returns a fresh object every call must pass
+ * `shallow` (or an equivalent `equals`), or it will re-render every frame.
+ *
+ * Note: `equals` is captured once, when this hook first mounts (in the
+ * per-instance cache created below) — pass a stable function (module-level
+ * `shallow`/`Object.is`, or a value that doesn't change across renders),
+ * not a fresh inline arrow every render.
+ */
+export function useGameState<T>(selector: (game: Game) => T, equals: Equals<T> = Object.is): T {
+  const game = useGame();
+  const cacheRef = useRef<ReturnType<typeof createFrameSelectorCache<T>> | null>(null);
+  if (cacheRef.current === null) {
+    cacheRef.current = createFrameSelectorCache<T>(equals);
+  }
+
+  return useSyncExternalStore(
+    (onStoreChange) => game.state.subscribe(onStoreChange),
+    () => cacheRef.current!.get(game.state.frameVersion, () => selector(game)),
+  );
+}
+
+/**
+ * Pure, react-free lookup for the `useWorldObservation` hook below — factored
+ * out so the hook body stays a thin `useSyncExternalStore` wrapper. Throws
+ * descriptively (loud, not `undefined`-forever) when `worldId` doesn't name a
+ * registered world, or that world's mount has no `observe`
+ * (`WorldStateObserver`, `@engine/adapter`) — matching the `Game.registerWorld`
+ * "no state bridge" report (`runtime/game.ts`) this is the react-side half of.
+ */
+export function requireWorldObserver(game: Game, worldId: string): WorldStateObserver {
+  const world = game.world(worldId);
+  if (!world) {
+    throw new Error(
+      `useWorldObservation: no world registered with id "${worldId}" — check game.worlds for the ` +
+        'ids actually registered.',
+    );
+  }
+  const observer = world.mounted.observe;
+  if (!observer) {
+    throw new Error(
+      `useWorldObservation: world "${worldId}" (kind: ${world.kind}, adapter: "${world.adapter.id}") ` +
+        'has no state bridge — its mount has no `observe` (WorldStateObserver). This world cannot ' +
+        'be observed from React (docs/REACT-STATE-BRIDGE.md §4).',
+    );
+  }
+  return observer;
+}
+
+/**
+ * Subscribe to a selected slice of a FOREIGN (non-first-party) world's
+ * observed state (`docs/REACT-STATE-BRIDGE.md` §4) — the ingested-world
+ * counterpart of `useGameState` above; both are sugar over the same
+ * subscribe/snapshot shape, so a react HUD reads native and ingested sources
+ * through one mental model.
+ *
+ * `selector` runs over that world's `snapshot()` — NOT the `Game` — since a
+ * foreign world hosts no `GameComponent`s to query. Re-renders only when the
+ * selected value changes (`equals`, default `Object.is`; pass {@link shallow}
+ * for tuples/objects returned fresh every call).
+ *
+ * Cadence note: unlike `useGameState`, this does NOT key its cache off
+ * `game.state.frameVersion` — a foreign/self-driven world may notify on its
+ * OWN rAF cadence, unrelated to our frame timing (§4's "consumers must not
+ * assume our frame timing"). Instead this keeps a local version counter,
+ * bumped once per `onChange` notification from the observer itself.
+ *
+ * Throws (loud, not a silently-undefined subscription) if `worldId` isn't
+ * registered, or its mount has no `observe` — see `requireWorldObserver`.
+ */
+export function useWorldObservation<T>(
+  worldId: string,
+  selector: (snapshot: unknown) => T,
+  equals: Equals<T> = Object.is,
+): T {
+  const game = useGame();
+  const observer = requireWorldObserver(game, worldId);
+  const cacheRef = useRef<ReturnType<typeof createFrameSelectorCache<T>> | null>(null);
+  if (cacheRef.current === null) {
+    cacheRef.current = createFrameSelectorCache<T>(equals);
+  }
+  // Local notification-version counter — see the cadence note above. A
+  // plain mutable ref (not React state): bumping it must not itself trigger
+  // a render, `useSyncExternalStore`'s `onStoreChange` is what does that.
+  const versionRef = useRef(0);
+
+  return useSyncExternalStore(
+    (onStoreChange) =>
+      observer.subscribe(() => {
+        versionRef.current++;
+        onStoreChange();
+      }),
+    () => cacheRef.current!.get(versionRef.current, () => selector(observer.snapshot())),
+  );
+}

package/src/render/auto-batcher.ts

@@ -0,0 +1,169 @@
+import * as THREE from 'three';
+
+/**
+ * Transparent auto-batcher (Strategy 1 — see docs/research/THREEJS-NATIVE-COMPILE.md §5
+ * and FAST-RENDER-BY-DEFAULT.md).
+ *
+ * The framework keeps each entity's Object3D as the logical handle (transform,
+ * gameplay, physics, picking) and renders eligible entities through a shared
+ * InstancedMesh under the hood — N logical objects, 1 draw call — WITHOUT the
+ * user changing any code. Identity is never merged, so selection/raycast survive
+ * (we keep an instanceId → entity map). The whole thing flips on/off live.
+ *
+ * Eligibility: an entity is a THREE.Mesh sharing geometry+material with others.
+ * Entities marked `userData.__noBatch` (the per-entity opt-out) always render
+ * individually. Custom/unique materials simply form their own (size-1) groups and
+ * cost a draw each — they degrade, they don't break.
+ *
+ * Cost model (measured in docs/research/bench/): per-frame cost is paid only for
+ * entities that MOVED (dirty-tracked via markMoved). A static scene re-syncs
+ * nothing — write-once at build, then 1 draw/frame.
+ */
+
+interface Batch {
+  key: string;
+  instanced: THREE.InstancedMesh;
+  members: THREE.Mesh[]; // localIndex → entity mesh (for picking + sync)
+}
+
+const SIG = (m: THREE.Mesh): string => {
+  const mat = Array.isArray(m.material) ? m.material[0]! : m.material;
+  return `${(m.geometry as THREE.BufferGeometry).uuid}|${mat.uuid}`;
+};
+
+export class AutoBatcher {
+  /** Root the batcher owns under the scene (instanced meshes when on, entities when off). */
+  readonly root = new THREE.Group();
+
+  private entities: THREE.Mesh[] = [];
+  private batches = new Map<string, Batch>();
+  private enabled: boolean;
+  /** Indices of entities whose transform changed since last sync. */
+  private dirty = new Set<number>();
+  private touchedBatches = new Set<Batch>();
+  // Per-mesh bookkeeping is kept in WeakMaps, NOT on userData (the typed userData
+  // registry is reserved for documented engine keys — see user-data.ts).
+  private indexOf = new WeakMap<THREE.Mesh, number>();
+  private optOut = new WeakSet<THREE.Mesh>();
+  private batchOf = new WeakMap<THREE.Mesh, { key: string; localIndex: number }>();
+  private membersOf = new WeakMap<THREE.InstancedMesh, THREE.Mesh[]>();
+
+  constructor(parent: THREE.Object3D, enabled = true) {
+    this.enabled = enabled;
+    this.root.name = 'AutoBatcher';
+    parent.add(this.root);
+  }
+
+  /** Register an entity (a Mesh) as the logical handle. Call build() after adding. */
+  add(entity: THREE.Mesh, optOut = false): void {
+    this.indexOf.set(entity, this.entities.length);
+    if (optOut) this.optOut.add(entity);
+    this.entities.push(entity);
+  }
+
+  /** Mark an entity moved this frame (dirty-tracking input). */
+  markMoved(entity: THREE.Mesh): void {
+    const i = this.indexOf.get(entity);
+    if (i !== undefined) this.dirty.add(i);
+  }
+
+  /** (Re)build the render representation for the current enabled state. */
+  build(): void {
+    this.clearRoot();
+    this.batches.clear();
+    if (!this.enabled) {
+      for (const e of this.entities) this.root.add(e);
+      return;
+    }
+    const m = new THREE.Matrix4();
+    // group eligible entities; opt-outs render individually
+    const groups = new Map<string, THREE.Mesh[]>();
+    for (const e of this.entities) {
+      if (this.optOut.has(e)) {
+        this.root.add(e);
+        continue;
+      }
+      const key = SIG(e);
+      const arr = groups.get(key) ?? [];
+      arr.push(e);
+      groups.set(key, arr);
+    }
+    for (const [key, members] of groups) {
+      const proto = members[0]!;
+      const mat = Array.isArray(proto.material) ? proto.material[0]! : proto.material;
+      const inst = new THREE.InstancedMesh(proto.geometry, mat, members.length);
+      inst.frustumCulled = false;
+      for (let i = 0; i < members.length; i++) {
+        const e = members[i]!;
+        e.updateMatrix();
+        m.copy(e.matrix);
+        inst.setMatrixAt(i, m);
+        this.batchOf.set(e, { key, localIndex: i });
+      }
+      inst.instanceMatrix.needsUpdate = true;
+      this.membersOf.set(inst, members); // localIndex → entity (picking)
+      this.root.add(inst);
+      this.batches.set(key, { key, instanced: inst, members });
+    }
+  }
+
+  /** Apply the dirty set to the instance buffers. Cheap when few moved. */
+  sync(): void {
+    if (!this.enabled) return;
+    const m = new THREE.Matrix4();
+    this.touchedBatches.clear();
+    for (const i of this.dirty) {
+      const e = this.entities[i]!;
+      const info = this.batchOf.get(e);
+      if (!info) continue; // opt-out or not batched
+      const batch = this.batches.get(info.key);
+      if (!batch) continue;
+      e.updateMatrix();
+      m.copy(e.matrix);
+      batch.instanced.setMatrixAt(info.localIndex, m);
+      this.touchedBatches.add(batch);
+    }
+    for (const b of this.touchedBatches) b.instanced.instanceMatrix.needsUpdate = true;
+    this.dirty.clear();
+  }
+
+  /** Live toggle: rebuilds the representation (one-time cost, not per-frame). */
+  setEnabled(on: boolean): void {
+    if (on === this.enabled) return;
+    this.enabled = on;
+    this.build();
+  }
+
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+
+  /** Map a raycast hit on a batch back to the logical entity (editor/gameplay picking). */
+  resolvePick(intersection: THREE.Intersection): THREE.Mesh | null {
+    const obj = intersection.object;
+    if ((obj as THREE.InstancedMesh).isInstancedMesh && intersection.instanceId != null) {
+      const members = this.membersOf.get(obj as THREE.InstancedMesh);
+      return members?.[intersection.instanceId] ?? null;
+    }
+    return obj instanceof THREE.Mesh ? obj : null;
+  }
+
+  /** Per-frame draw-call count this batcher contributes (for stats). */
+  get drawCallCount(): number {
+    return this.enabled ? this.batches.size + this.optOutCount : this.entities.length;
+  }
+
+  private get optOutCount(): number {
+    let n = 0;
+    for (const e of this.entities) if (this.optOut.has(e)) n++;
+    return n;
+  }
+
+  private clearRoot(): void {
+    for (let i = this.root.children.length - 1; i >= 0; i--) {
+      const c = this.root.children[i]!;
+      this.root.remove(c);
+      if ((c as THREE.InstancedMesh).isInstancedMesh) (c as THREE.InstancedMesh).dispose();
+    }
+  }
+}

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

@@ -0,0 +1,268 @@
+import * as THREE from 'three';
+import { getUserData } from '../scene/user-data';
+import type { ResolvedRenderSettings } from './render-settings';
+
+/**
+ * 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): see docs/research/THREEJS-NATIVE-COMPILE.md §5,
+ * FAST-RENDER-BY-DEFAULT.md, RENDER-SETTINGS-UX.md. Moving entities (boids-style,
+ * all-frame churn) are a separate concern — see render/auto-batcher.ts (dynamic).
+ *
+ * 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)
+ *   - not explicitly opted out (`entity.render.autoBatch === false`)
+ *   - 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):
+ *   - Runs once per scene load (build() is called after loadScene). 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.)
+ *   - Installed for scene-file loads (scenePath/sceneData), not the imperative setup()
+ *     path — setup() games manage their own scene/spawning.
+ *   - 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. Keying on geometry type+parameters
+// and material type+key-props groups identical authored primitives (e.g. 10k boxes of
+// the same size+color → one batch). Non-primitive geometry (GLTF, no `.parameters`)
+// falls back to uuid → it simply won't group, which is the safe default.
+const geoKey = (g: THREE.BufferGeometry): string => {
+  const params = (g as unknown as { parameters?: object }).parameters;
+  return params ? `${g.type}:${JSON.stringify(params)}` : `uuid:${g.uuid}`;
+};
+const matKey = (m: THREE.Material): string => {
+  const s = m as THREE.MeshStandardMaterial;
+  const col = s.color?.getHexString?.() ?? '';
+  const map = s.map?.uuid ?? '';
+  return `${m.type}:${col}:${s.roughness ?? ''}:${s.metalness ?? ''}:${map}:${m.side}:${m.transparent}:${m.vertexColors}`;
+};
+const SIG = (m: THREE.Mesh): string =>
+  // include shadow flags: meshes with different cast/receive must not share a batch
+  // (the InstancedMesh carries one flag for the whole group).
+  `${geoKey(m.geometry as THREE.BufferGeometry)}|${matKey(m.material as THREE.Material)}|${m.castShadow ? 1 : 0}${m.receiveShadow ? 1 : 0}`;
+
+interface EntityDef {
+  render?: { autoBatch?: boolean };
+  physics?: unknown;
+  components?: Record<string, unknown>;
+  animation?: unknown;
+}
+
+/** Nearest self/ancestor entity descriptor, if any. */
+function nearestEntity(obj: THREE.Object3D): EntityDef | undefined {
+  let cur: THREE.Object3D | null = obj;
+  while (cur) {
+    const entity = getUserData(cur, 'entity') as unknown as EntityDef | undefined;
+    if (entity) return entity;
+    cur = cur.parent;
+  }
+  return undefined;
+}
+
+/** Explicit per-entity opt-out (`render.autoBatch === false`). */
+function entityOptOut(obj: THREE.Object3D): boolean {
+  return nearestEntity(obj)?.render?.autoBatch === false;
+}
+
+/**
+ * Static-batching eligibility: only entities that won't move are safe to freeze
+ * and instance. An entity with physics, behavior components, or its own animation
+ * is a likely mover → left as an ordinary draw. Plain scenery (no def, or a def
+ * with none of those) is eligible. This is the safe, transparent default; a future
+ * dynamic-batch path (markMoved-driven) can include movers.
+ */
+function isLikelyStatic(obj: THREE.Object3D): boolean {
+  const e = nearestEntity(obj);
+  if (!e) return true; // un-tagged scenery
+  if (e.physics) return false;
+  if (e.animation) return false;
+  if (e.components && Object.keys(e.components).length > 0) return false;
+  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) => {
+      const m = obj as THREE.Mesh;
+      if (!m.isMesh) return;
+      if ((m as THREE.InstancedMesh).isInstancedMesh) return;
+      if ((m as THREE.SkinnedMesh).isSkinnedMesh) return;
+      if ((m as unknown as THREE.BatchedMesh).isBatchedMesh) return;
+      if (!m.visible) return;
+      if (!m.geometry || !m.material || Array.isArray(m.material)) return;
+      if ((m.material as THREE.Material).transparent) return;
+      if (this.root === m.parent) return; // our own instances
+      if (entityOptOut(m)) return;
+      const key = SIG(m);
+      const arr = buckets.get(key) ?? [];
+      arr.push(m);
+      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);
+  }
+}