@vgai/engine 0.5.4 → 0.5.6

package/dist/react/world-state.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Canonical `WorldProvider`/`useGame`/`useWorldState`/`useRootObservation`
+ * entry for React adapter roots. Also home to `useDebugProvider` and
+ * `useDebugCommand`/`useDebugEmit`, the React-facing debug seam.
+ *
+ * This is a SEPARATE, react-value-importing module under
+ * `packages/engine/src/react/` — colocated per the "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).
+ *
+ * Every host and game imports this one module, so provider and hooks share
+ * one `createContext()` identity. The engine core outside `src/react/`
+ * remains React-free, enforced by `react-core-import-ban.test.ts`.
+ */
+import { type PropsWithChildren } from 'react';
+import type { z } from 'zod';
+import type { RootStateObserver } from '../adapter';
+import { type Equals, shallow } from '../runtime/frame-selector-cache';
+import type { Game } from '../runtime/game';
+import type { DebugCommandArgs } from '../runtime/types';
+/** 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 };
+/** Provide the `Game` to `useWorldState`/`useGame` for everything mounted
+ *  beneath it. Adapter-root hosts install this provider automatically — see the module doc
+ *  comment above for the context-identity rule this hook family depends on.
+ *
+ *  Props use `PropsWithChildren` (children optional in the TYPE, not
+ *  runtime-optional in practice — you always want children mounted under
+ *  the provider) rather than a bare `{ children: ReactNode }` field: a
+ *  required `children` in `P` makes TS's `createElement<P>(type, props?:
+ *  Attributes & P, ...children)` overload reject the plain 3-arg call
+ *  `React.createElement(WorldProvider, { game }, child)` (no JSX transform,
+ *  e.g. a `.ts` main composing a sibling `.tsx` HUD) with "Property
+ *  'children' is missing" even though the 3rd arg supplies it — issue #97.
+ *  Making `children` optional in the type lets that overload resolve; the
+ *  rest-arg children are still wired through to `children` at runtime by
+ *  React itself, unchanged. See `test/game-state-create-element-types.test.tsx`. */
+export declare function WorldProvider({ game, children }: PropsWithChildren<{
+    game: Game;
+}>): import("react").JSX.Element;
+/** Read the `Game` provided by the nearest `WorldProvider`. Throws
+ *  descriptively when called outside one — matching the repo's loud-failure
+ *  habit rather than silently returning `null`. */
+export declare function useGame(): Game;
+/**
+ * Subscribe to a selected slice of game state. 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.world('main')?.threeScene().getObjectByName('Hero')?.position.y`)
+ * 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 declare function useWorldState<T>(selector: (game: Game) => T, equals?: Equals<T>): T;
+/**
+ * Pure, react-free lookup for the `useRootObservation` 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`
+ * (`RootStateObserver`, `@engine/adapter`) — matching the `Game.registerRoot`
+ * "no state bridge" report (`runtime/game.ts`) this is the react-side half of.
+ */
+export declare function requireRootObserver(game: Game, worldId: string): RootStateObserver;
+/**
+ * Subscribe to a selected slice of a FOREIGN (non-first-party) world's
+ * observed state — the ingested-world counterpart of `useWorldState` 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 exposes no first-party state. 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 `useWorldState`, 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 `requireRootObserver`.
+ */
+export declare function useRootObservation<T>(worldId: string, selector: (snapshot: unknown) => T, equals?: Equals<T>): T;
+/**
+ * The debug seam's react-world registration door (Task 1.5): react roots
+ * have no `setup()`/ `ctx.debug` of their own, so this hook registers a
+ * named state provider into the SAME game-scoped registry every root's
+ * `ctx.debug` feeds (`getDebugRegistry(game)`, `runtime/debug-registry.ts`),
+ * readable through `game.systemAdapters.debug.state(name)` exactly like a
+ * `ctx.debug.registerStateProvider` call.
+ *
+ * Registers ONCE per mount (keyed on `name`) and unregisters on unmount —
+ * silently, like hot-reload's `strip()`. Re-renders never re-register or
+ * re-warn: `fn` is kept in a ref updated every render, so the registered
+ * closure always calls the CURRENT `fn` without touching the registry.
+ * Outside a `<WorldProvider>` (or against a bare test `Game` built without a
+ * registry) this is an inert no-op — it never throws, matching the "no seam
+ * without a consumer" degrade every optional `ctx.*` surface follows.
+ */
+export declare function useDebugProvider(name: string, fn: () => unknown, opts?: {
+    tier?: 'observable' | 'assisted';
+}): void;
+/**
+ * The command-side counterpart of {@link useDebugProvider} — registers an
+ * invokable debug command into the same game-scoped registry, readable
+ * through `game.systemAdapters.debug.commands()`/`invoke(name, args)`.
+ *
+ * Same mount/unmount/ref-latest contract as {@link useDebugProvider}: `spec`
+ * (description/args/locus) is captured at registration time, `fn` always
+ * calls through to the latest render's closure via a ref, and the hook is an
+ * inert no-op with no `<WorldProvider>` in scope.
+ *
+ * Generic over the declared `args` Zod tuple, same as
+ * `DebugCtxSurface.registerCommand` ({@link DebugCommandArgs}, dry-run
+ * finding — ledger): declaring `args: z.tuple([z.number(), z.string()])`
+ * types `fn`'s parameters as `(n: number, s: string) => ...` with no
+ * `unknown[]` cast; omitting `args` keeps `fn` typed `(...args: unknown[])
+ * => ...` as before.
+ */
+export declare function useDebugCommand<T extends z.ZodTuple | undefined = undefined>(name: string, spec: {
+    description?: string;
+    args?: T;
+    locus?: 'client' | 'server';
+}, fn: (...args: DebugCommandArgs<T>) => unknown | Promise<unknown>): void;
+/**
+ * The event-side counterpart of {@link useDebugProvider} and
+ * {@link useDebugCommand}. Returns a stable callback that writes a
+ * tick-stamped event to the game-scoped debug flight recorder:
+ *
+ * ```tsx
+ * const emit = useDebugEmit();
+ * emit('score-changed', { score });
+ * ```
+ *
+ * It is an inert no-op outside a `<WorldProvider>`, matching the optional
+ * behavior of the other React debug hooks. Games never need to import the
+ * debug registry or know its internal React provenance id.
+ */
+export declare function useDebugEmit(): (event: string, detail?: unknown) => void;
+//# sourceMappingURL=world-state.d.ts.map

package/dist/react/world-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world-state.d.ts","sourceRoot":"","sources":["../../src/react/world-state.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAEL,KAAK,iBAAiB,EAMvB,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EAA4B,KAAK,MAAM,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC;AACjG,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD;6EAC6E;AAC7E,OAAO,EAAE,OAAO,EAAE,CAAC;AAInB;;;;;;;;;;;;;;oFAcoF;AACpF,wBAAgB,aAAa,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,iBAAiB,CAAC;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,+BAElF;AAED;;mDAEmD;AACnD,wBAAgB,OAAO,IAAI,IAAI,CAQ9B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,EAAE,MAAM,GAAE,MAAM,CAAC,CAAC,CAAa,GAAG,CAAC,CAW9F;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAiBlF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,CAAC,EAClC,MAAM,GAAE,MAAM,CAAC,CAAC,CAAa,GAC5B,CAAC,CAoBH;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,EACjB,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,YAAY,GAAG,UAAU,CAAA;CAAE,GAC1C,IAAI,CAaN;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,CAAC,CAAC,QAAQ,GAAG,SAAS,GAAG,SAAS,EAC1E,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;CAAE,EACrE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAC/D,IAAI,CAeN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CASxE"}

package/dist/react/world-state.js

@@ -0,0 +1,220 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Canonical `WorldProvider`/`useGame`/`useWorldState`/`useRootObservation`
+ * entry for React adapter roots. Also home to `useDebugProvider` and
+ * `useDebugCommand`/`useDebugEmit`, the React-facing debug seam.
+ *
+ * This is a SEPARATE, react-value-importing module under
+ * `packages/engine/src/react/` — colocated per the "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).
+ *
+ * Every host and game imports this one module, so provider and hooks share
+ * one `createContext()` identity. The engine core outside `src/react/`
+ * remains React-free, enforced by `react-core-import-ban.test.ts`.
+ */
+import { createContext, useCallback, useContext, useEffect, useRef, useSyncExternalStore, } from 'react';
+import { getDebugRegistry } from '../runtime/debug-registry';
+import { createFrameSelectorCache, shallow } from '../runtime/frame-selector-cache';
+/** 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(null);
+/** Provide the `Game` to `useWorldState`/`useGame` for everything mounted
+ *  beneath it. Adapter-root hosts install this provider automatically — see the module doc
+ *  comment above for the context-identity rule this hook family depends on.
+ *
+ *  Props use `PropsWithChildren` (children optional in the TYPE, not
+ *  runtime-optional in practice — you always want children mounted under
+ *  the provider) rather than a bare `{ children: ReactNode }` field: a
+ *  required `children` in `P` makes TS's `createElement<P>(type, props?:
+ *  Attributes & P, ...children)` overload reject the plain 3-arg call
+ *  `React.createElement(WorldProvider, { game }, child)` (no JSX transform,
+ *  e.g. a `.ts` main composing a sibling `.tsx` HUD) with "Property
+ *  'children' is missing" even though the 3rd arg supplies it — issue #97.
+ *  Making `children` optional in the type lets that overload resolve; the
+ *  rest-arg children are still wired through to `children` at runtime by
+ *  React itself, unchanged. See `test/game-state-create-element-types.test.tsx`. */
+export function WorldProvider({ game, children }) {
+    return _jsx(GameContext.Provider, { value: game, children: children });
+}
+/** Read the `Game` provided by the nearest `WorldProvider`. Throws
+ *  descriptively when called outside one — matching the repo's loud-failure
+ *  habit rather than silently returning `null`. */
+export function useGame() {
+    const game = useContext(GameContext);
+    if (!game) {
+        throw new Error('useGame: no Game in context — wrap this component in <WorldProvider game={ctx.game!}>.');
+    }
+    return game;
+}
+/**
+ * Subscribe to a selected slice of game state. 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.world('main')?.threeScene().getObjectByName('Hero')?.position.y`)
+ * 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 useWorldState(selector, equals = Object.is) {
+    const game = useGame();
+    const cacheRef = useRef(null);
+    if (cacheRef.current === null) {
+        cacheRef.current = createFrameSelectorCache(equals);
+    }
+    return useSyncExternalStore((onStoreChange) => game.state.subscribe(onStoreChange), () => cacheRef.current.get(game.state.frameVersion, () => selector(game)));
+}
+/**
+ * Pure, react-free lookup for the `useRootObservation` 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`
+ * (`RootStateObserver`, `@engine/adapter`) — matching the `Game.registerRoot`
+ * "no state bridge" report (`runtime/game.ts`) this is the react-side half of.
+ */
+export function requireRootObserver(game, worldId) {
+    const world = game.world(worldId);
+    if (!world) {
+        throw new Error(`useRootObservation: no world registered with id "${worldId}" — check game.roots for the ` +
+            'ids actually registered.');
+    }
+    const observer = world.mounted.observe;
+    if (!observer) {
+        throw new Error(`useRootObservation: world "${worldId}" (kind: ${world.kind}, adapter: "${world.adapter.id}") ` +
+            'has no state bridge — its mount has no `observe` (RootStateObserver). This world cannot ' +
+            'be observed from React.');
+    }
+    return observer;
+}
+/**
+ * Subscribe to a selected slice of a FOREIGN (non-first-party) world's
+ * observed state — the ingested-world counterpart of `useWorldState` 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 exposes no first-party state. 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 `useWorldState`, 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 `requireRootObserver`.
+ */
+export function useRootObservation(worldId, selector, equals = Object.is) {
+    const game = useGame();
+    const observer = requireRootObserver(game, worldId);
+    const cacheRef = useRef(null);
+    if (cacheRef.current === null) {
+        cacheRef.current = createFrameSelectorCache(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())));
+}
+/**
+ * The debug seam's react-world registration door (Task 1.5): react roots
+ * have no `setup()`/ `ctx.debug` of their own, so this hook registers a
+ * named state provider into the SAME game-scoped registry every root's
+ * `ctx.debug` feeds (`getDebugRegistry(game)`, `runtime/debug-registry.ts`),
+ * readable through `game.systemAdapters.debug.state(name)` exactly like a
+ * `ctx.debug.registerStateProvider` call.
+ *
+ * Registers ONCE per mount (keyed on `name`) and unregisters on unmount —
+ * silently, like hot-reload's `strip()`. Re-renders never re-register or
+ * re-warn: `fn` is kept in a ref updated every render, so the registered
+ * closure always calls the CURRENT `fn` without touching the registry.
+ * Outside a `<WorldProvider>` (or against a bare test `Game` built without a
+ * registry) this is an inert no-op — it never throws, matching the "no seam
+ * without a consumer" degrade every optional `ctx.*` surface follows.
+ */
+export function useDebugProvider(name, fn, opts) {
+    const game = useContext(GameContext);
+    const fnRef = useRef(fn);
+    fnRef.current = fn;
+    const tier = opts?.tier;
+    useEffect(() => {
+        const registry = game && getDebugRegistry(game);
+        if (!registry)
+            return;
+        return registry.registerReactProvider(name, () => fnRef.current(), { tier });
+        // `tier` is deliberately NOT a dep (same reasoning as `useDebugCommand`'s
+        // `spec`) — captured once at mount, so it never forces re-registration.
+    }, [game, name]);
+}
+/**
+ * The command-side counterpart of {@link useDebugProvider} — registers an
+ * invokable debug command into the same game-scoped registry, readable
+ * through `game.systemAdapters.debug.commands()`/`invoke(name, args)`.
+ *
+ * Same mount/unmount/ref-latest contract as {@link useDebugProvider}: `spec`
+ * (description/args/locus) is captured at registration time, `fn` always
+ * calls through to the latest render's closure via a ref, and the hook is an
+ * inert no-op with no `<WorldProvider>` in scope.
+ *
+ * Generic over the declared `args` Zod tuple, same as
+ * `DebugCtxSurface.registerCommand` ({@link DebugCommandArgs}, dry-run
+ * finding — ledger): declaring `args: z.tuple([z.number(), z.string()])`
+ * types `fn`'s parameters as `(n: number, s: string) => ...` with no
+ * `unknown[]` cast; omitting `args` keeps `fn` typed `(...args: unknown[])
+ * => ...` as before.
+ */
+export function useDebugCommand(name, spec, fn) {
+    const game = useContext(GameContext);
+    const fnRef = useRef(fn);
+    fnRef.current = fn;
+    useEffect(() => {
+        const registry = game && getDebugRegistry(game);
+        if (!registry)
+            return;
+        return registry.registerReactCommand(name, spec, (...args) => fnRef.current(...args));
+        // `spec` is deliberately NOT a dep (like `equals` above) — captured once
+        // at mount, so a fresh inline object literal every render never forces
+        // re-registration.
+    }, [game, name]);
+}
+/**
+ * The event-side counterpart of {@link useDebugProvider} and
+ * {@link useDebugCommand}. Returns a stable callback that writes a
+ * tick-stamped event to the game-scoped debug flight recorder:
+ *
+ * ```tsx
+ * const emit = useDebugEmit();
+ * emit('score-changed', { score });
+ * ```
+ *
+ * It is an inert no-op outside a `<WorldProvider>`, matching the optional
+ * behavior of the other React debug hooks. Games never need to import the
+ * debug registry or know its internal React provenance id.
+ */
+export function useDebugEmit() {
+    const game = useContext(GameContext);
+    return useCallback((event, detail) => {
+        if (!game)
+            return;
+        getDebugRegistry(game)?.emitReact(event, detail);
+    }, [game]);
+}

package/dist/render/auto-batcher.d.ts

@@ -0,0 +1,34 @@
+import * as THREE from 'three';
+export declare class AutoBatcher {
+    /** Root the batcher owns under the scene (instanced meshes when on, entities when off). */
+    readonly root: THREE.Group<THREE.Object3DEventMap>;
+    private entities;
+    private batches;
+    private enabled;
+    /** Indices of entities whose transform changed since last sync. */
+    private dirty;
+    private touchedBatches;
+    private indexOf;
+    private optOut;
+    private batchOf;
+    private membersOf;
+    constructor(parent: THREE.Object3D, enabled?: boolean);
+    /** Register an entity (a Mesh) as the logical handle. Call build() after adding. */
+    add(entity: THREE.Mesh, optOut?: boolean): void;
+    /** Mark an entity moved this frame (dirty-tracking input). */
+    markMoved(entity: THREE.Mesh): void;
+    /** (Re)build the render representation for the current enabled state. */
+    build(): void;
+    /** Apply the dirty set to the instance buffers. Cheap when few moved. */
+    sync(): void;
+    /** Live toggle: rebuilds the representation (one-time cost, not per-frame). */
+    setEnabled(on: boolean): void;
+    isEnabled(): boolean;
+    /** Map a raycast hit on a batch back to the logical entity (editor/gameplay picking). */
+    resolvePick(intersection: THREE.Intersection): THREE.Mesh | null;
+    /** Per-frame draw-call count this batcher contributes (for stats). */
+    get drawCallCount(): number;
+    private get optOutCount();
+    private clearRoot;
+}
+//# sourceMappingURL=auto-batcher.d.ts.map

package/dist/render/auto-batcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-batcher.d.ts","sourceRoot":"","sources":["../../src/render/auto-batcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAgC/B,qBAAa,WAAW;IACtB,2FAA2F;IAC3F,QAAQ,CAAC,IAAI,sCAAqB;IAElC,OAAO,CAAC,QAAQ,CAAoB;IACpC,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,OAAO,CAAU;IACzB,mEAAmE;IACnE,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,cAAc,CAAoB;IAG1C,OAAO,CAAC,OAAO,CAAqC;IACpD,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,OAAO,CAAkE;IACjF,OAAO,CAAC,SAAS,CAAoD;gBAEzD,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,OAAO,UAAO;IAMlD,oFAAoF;IACpF,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,UAAQ,GAAG,IAAI;IAM7C,8DAA8D;IAC9D,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,GAAG,IAAI;IAKnC,yEAAyE;IACzE,KAAK,IAAI,IAAI;IAuCb,yEAAyE;IACzE,IAAI,IAAI,IAAI;IAmBZ,+EAA+E;IAC/E,UAAU,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI;IAM7B,SAAS,IAAI,OAAO;IAIpB,yFAAyF;IACzF,WAAW,CAAC,YAAY,EAAE,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC,IAAI,GAAG,IAAI;IAShE,sEAAsE;IACtE,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,OAAO,KAAK,WAAW,GAItB;IAED,OAAO,CAAC,SAAS;CAOlB"}

package/dist/render/auto-batcher.js

@@ -0,0 +1,140 @@
+import * as THREE from 'three';
+const SIG = (m) => {
+    const mat = Array.isArray(m.material) ? m.material[0] : m.material;
+    return `${m.geometry.uuid}|${mat.uuid}`;
+};
+export class AutoBatcher {
+    /** Root the batcher owns under the scene (instanced meshes when on, entities when off). */
+    root = new THREE.Group();
+    entities = [];
+    batches = new Map();
+    enabled;
+    /** Indices of entities whose transform changed since last sync. */
+    dirty = new Set();
+    touchedBatches = new Set();
+    // Per-mesh bookkeeping is kept in WeakMaps, NOT on userData (the typed userData
+    // registry is reserved for documented engine keys — see user-data.ts).
+    indexOf = new WeakMap();
+    optOut = new WeakSet();
+    batchOf = new WeakMap();
+    membersOf = new WeakMap();
+    constructor(parent, 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, optOut = false) {
+        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) {
+        const i = this.indexOf.get(entity);
+        if (i !== undefined)
+            this.dirty.add(i);
+    }
+    /** (Re)build the render representation for the current enabled state. */
+    build() {
+        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();
+        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() {
+        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) {
+        if (on === this.enabled)
+            return;
+        this.enabled = on;
+        this.build();
+    }
+    isEnabled() {
+        return this.enabled;
+    }
+    /** Map a raycast hit on a batch back to the logical entity (editor/gameplay picking). */
+    resolvePick(intersection) {
+        const obj = intersection.object;
+        if (obj.isInstancedMesh && intersection.instanceId != null) {
+            const members = this.membersOf.get(obj);
+            return members?.[intersection.instanceId] ?? null;
+        }
+        return obj instanceof THREE.Mesh ? obj : null;
+    }
+    /** Per-frame draw-call count this batcher contributes (for stats). */
+    get drawCallCount() {
+        return this.enabled ? this.batches.size + this.optOutCount : this.entities.length;
+    }
+    get optOutCount() {
+        let n = 0;
+        for (const e of this.entities)
+            if (this.optOut.has(e))
+                n++;
+        return n;
+    }
+    clearRoot() {
+        for (let i = this.root.children.length - 1; i >= 0; i--) {
+            const c = this.root.children[i];
+            this.root.remove(c);
+            if (c.isInstancedMesh)
+                c.dispose();
+        }
+    }
+}

package/dist/render/instance-mesh.d.ts

@@ -0,0 +1,5 @@
+import * as THREE from 'three';
+import type { InstancesFile } from '../asset-formats/instances';
+/** Build one native InstancedMesh from a parsed `.instances.json` tuple array. */
+export declare function buildInstancedMeshFromTuples(geometry: THREE.BufferGeometry, material: THREE.Material, tuples: InstancesFile): THREE.InstancedMesh;
+//# sourceMappingURL=instance-mesh.d.ts.map

package/dist/render/instance-mesh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-mesh.d.ts","sourceRoot":"","sources":["../../src/render/instance-mesh.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEhE,kFAAkF;AAClF,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,KAAK,CAAC,cAAc,EAC9B,QAAQ,EAAE,KAAK,CAAC,QAAQ,EACxB,MAAM,EAAE,aAAa,GACpB,KAAK,CAAC,aAAa,CAgBrB"}

package/dist/render/instance-mesh.js

@@ -0,0 +1,19 @@
+import * as THREE from 'three';
+/** Build one native InstancedMesh from a parsed `.instances.json` tuple array. */
+export function buildInstancedMeshFromTuples(geometry, material, tuples) {
+    const mesh = new THREE.InstancedMesh(geometry, material, tuples.length);
+    const position = new THREE.Vector3();
+    const quaternion = new THREE.Quaternion();
+    const scale = new THREE.Vector3();
+    const matrix = new THREE.Matrix4();
+    for (let index = 0; index < tuples.length; index += 1) {
+        const tuple = tuples[index];
+        position.set(tuple[0], tuple[1], tuple[2]);
+        quaternion.set(tuple[3], tuple[4], tuple[5], tuple[6]);
+        scale.set(tuple[7], tuple[8], tuple[9]);
+        matrix.compose(position, quaternion, scale);
+        mesh.setMatrixAt(index, matrix);
+    }
+    mesh.instanceMatrix.needsUpdate = true;
+    return mesh;
+}

package/dist/render/light-camera-factory.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared light + camera factory (T1.13 — DEFAULTS truth).
+ *
+ * `createLight`/`createCamera` used to be duplicated verbatim between the
+ * runtime loader (`scene-loader.ts`) and the editor preview
+ * (`entity-factory.ts`) — both hardcoded the same fallback literals (color
+ * '#ffffff', fov 60, near 0.1, far 1000, etc.) that happened to agree with
+ * `DEFAULTS.light`/`DEFAULTS.camera` by luck rather than by reading them. Any
+ * edit to one copy (or to `DEFAULTS`) could silently diverge from the other.
+ *
+ * This module is now the ONE place that builds a `THREE.Light`/`THREE.Camera`
+ * from a `LightDescriptor`/`CameraDescriptor` descriptor, reading its fallbacks from
+ * `DEFAULTS` (the single source of truth for scene default values — see
+ * `defaults.ts`). Both the loader and the editor import it, so they
+ * can no longer disagree.
+ */
+import * as THREE from 'three';
+import type { CameraDescriptor } from '../asset-formats/camera';
+import type { LightDescriptor } from '../asset-formats/light';
+/** Build a Three.js light from a `LightDescriptor` descriptor. */
+export declare function createLight(def: LightDescriptor): THREE.Light;
+/** Build a Three.js camera from a `CameraDescriptor` descriptor. */
+export declare function createCamera(def: CameraDescriptor): THREE.Camera;
+//# sourceMappingURL=light-camera-factory.d.ts.map

package/dist/render/light-camera-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"light-camera-factory.d.ts","sourceRoot":"","sources":["../../src/render/light-camera-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAY/B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAK9D,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,GAAG,EAAE,eAAe,GAAG,KAAK,CAAC,KAAK,CA8C7D;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,KAAK,CAAC,MAAM,CAoBhE"}