@vgai/engine 0.5.0 → 0.5.2

package/dist/react/use-data.d.ts

@@ -1,60 +0,0 @@
-/**
- * React hooks for data assets — the tool-hooks half of
- * `docs/DATA-TOOLS-DESIGN.md` §3.3, shipped with W4 (dock tools).
- *
- * Lives under `packages/engine/src/react/` deliberately: this is the ONE
- * directory of the engine allowed to value-import react (colocated with
- * `game-state.tsx` per the react-free-core rule proved by
- * `test/react-core-import-ban.test.ts`). Game roots that aren't react keep
- * using `DataHandle.get()`/`subscribe()` directly (§2.3).
- *
- * - {@link useData} — subscribe a component to any W1 `DataHandle`; works in
- *   project tools, react roots, and HUD overlays alike.
- * - {@link writeData} — EDITOR-TOOL plumbing: write a whole `.data.json`
- *   back through the editor dev server, closing the live-tuning loop
- *   (widget → file write → Vite HMR → `hotSwap` → {@link useData} re-render
- *   → the running game reads the new value). Not for game code.
- */
-import type { DataHandle } from '../data/data-asset';
-/**
- * Read a data asset's current values and re-render whenever a hot edit lands
- * (§3.3). A thin `useSyncExternalStore` over the handle's
- * `subscribe`/`get` — any `defineData` handle works, no provider needed:
- *
- * ```tsx
- * import { tuning } from '../data/tuning';
- * const values = useData(tuning);   // fresh parsed object after every hotSwap
- * ```
- *
- * `get()` returns the same reference between successful hot swaps, so this
- * re-renders exactly once per accepted edit and never in between.
- */
-export declare function useData<T>(handle: DataHandle<T>): T;
-/**
- * Write a data asset's ENTIRE new value back to its `.data.json` — the write
- * half of a project tool's live-tuning loop (§3.3, D1: writes are file
- * writes, always). POSTs to the editor dev server's `/__editor/data-file`
- * route (see its doc comment in `packages/editor/server/editor-server.ts`),
- * which accepts only `src/data/**\/*.data.json` and writes immediately; the
- * running game then receives the change through the normal `.data.json` HMR
- * path, exactly as if VS Code had saved the file.
- *
- * ```tsx
- * // inside a tool's onChange — spread the live values, replace one field:
- * void writeData('src/data/tuning.data.json', { ...tuning.get(), gravity: v });
- * ```
- *
- * FOR TOOLS, NOT GAME CODE: data assets are immutable at runtime (§2.1) —
- * runtime state belongs in your game's own store, never written back into
- * data files. Outside a running editor there is no `/__editor` server, so
- * this rejects with a teaching error (a shipped game could never reach the
- * route anyway — builds strip `src/tools/` entirely, §4).
- *
- * Serialization matches the editor Data panel's diff-minimal contract:
- * `"$schema"` first, 2-space indent, trailing newline. When `value` carries
- * no `"$schema"` key (the common case — `DataHandle.get()` strips it), the
- * conventional sibling reference (`./<name>.schema.json`, §2.1) is restored
- * so a tool write never silently drops VS Code validation from the file.
- */
-export declare function writeData(projectRelativePath: string, value: Record<string, unknown>): Promise<void>;
-//# sourceMappingURL=use-data.d.ts.map

package/dist/react/use-data.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-data.d.ts","sourceRoot":"","sources":["../../src/react/use-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;;;;;GAYG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAKnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,SAAS,CAC7B,mBAAmB,EAAE,MAAM,EAC3B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC,CAqDf"}

package/dist/react/use-data.js

@@ -1,101 +0,0 @@
-/**
- * React hooks for data assets — the tool-hooks half of
- * `docs/DATA-TOOLS-DESIGN.md` §3.3, shipped with W4 (dock tools).
- *
- * Lives under `packages/engine/src/react/` deliberately: this is the ONE
- * directory of the engine allowed to value-import react (colocated with
- * `game-state.tsx` per the react-free-core rule proved by
- * `test/react-core-import-ban.test.ts`). Game roots that aren't react keep
- * using `DataHandle.get()`/`subscribe()` directly (§2.3).
- *
- * - {@link useData} — subscribe a component to any W1 `DataHandle`; works in
- *   project tools, react roots, and HUD overlays alike.
- * - {@link writeData} — EDITOR-TOOL plumbing: write a whole `.data.json`
- *   back through the editor dev server, closing the live-tuning loop
- *   (widget → file write → Vite HMR → `hotSwap` → {@link useData} re-render
- *   → the running game reads the new value). Not for game code.
- */
-import { useSyncExternalStore } from 'react';
-/**
- * Read a data asset's current values and re-render whenever a hot edit lands
- * (§3.3). A thin `useSyncExternalStore` over the handle's
- * `subscribe`/`get` — any `defineData` handle works, no provider needed:
- *
- * ```tsx
- * import { tuning } from '../data/tuning';
- * const values = useData(tuning);   // fresh parsed object after every hotSwap
- * ```
- *
- * `get()` returns the same reference between successful hot swaps, so this
- * re-renders exactly once per accepted edit and never in between.
- */
-export function useData(handle) {
-    return useSyncExternalStore((onStoreChange) => handle.subscribe(() => onStoreChange()), () => handle.get());
-}
-/**
- * Write a data asset's ENTIRE new value back to its `.data.json` — the write
- * half of a project tool's live-tuning loop (§3.3, D1: writes are file
- * writes, always). POSTs to the editor dev server's `/__editor/data-file`
- * route (see its doc comment in `packages/editor/server/editor-server.ts`),
- * which accepts only `src/data/**\/*.data.json` and writes immediately; the
- * running game then receives the change through the normal `.data.json` HMR
- * path, exactly as if VS Code had saved the file.
- *
- * ```tsx
- * // inside a tool's onChange — spread the live values, replace one field:
- * void writeData('src/data/tuning.data.json', { ...tuning.get(), gravity: v });
- * ```
- *
- * FOR TOOLS, NOT GAME CODE: data assets are immutable at runtime (§2.1) —
- * runtime state belongs in your game's own store, never written back into
- * data files. Outside a running editor there is no `/__editor` server, so
- * this rejects with a teaching error (a shipped game could never reach the
- * route anyway — builds strip `src/tools/` entirely, §4).
- *
- * Serialization matches the editor Data panel's diff-minimal contract:
- * `"$schema"` first, 2-space indent, trailing newline. When `value` carries
- * no `"$schema"` key (the common case — `DataHandle.get()` strips it), the
- * conventional sibling reference (`./<name>.schema.json`, §2.1) is restored
- * so a tool write never silently drops VS Code validation from the file.
- */
-export async function writeData(projectRelativePath, value) {
-    if (!projectRelativePath.startsWith('src/data/') || !projectRelativePath.endsWith('.data.json')) {
-        throw new Error(`writeData: invalid path ${JSON.stringify(projectRelativePath)} — data assets live at ` +
-            'src/data/**/*.data.json, addressed project-relative (docs/DATA-TOOLS-DESIGN.md §2.1), ' +
-            "e.g. writeData('src/data/tuning.data.json', next).");
-    }
-    // "$schema" first for minimal diffs; restore the conventional sibling
-    // reference when the caller's object (typically `{ ...handle.get() }`,
-    // which never carries it) omits the line.
-    const { $schema, ...rest } = value;
-    const schemaRef = $schema ??
-        `./${projectRelativePath
-            .split('/')
-            .pop()
-            ?.replace(/\.data\.json$/, '')}.schema.json`;
-    const content = `${JSON.stringify({ $schema: schemaRef, ...rest }, null, 2)}\n`;
-    const transactionalWriter = globalThis.__vgaiHistoryWriteData;
-    if (transactionalWriter) {
-        await transactionalWriter(projectRelativePath, content);
-        return;
-    }
-    let res;
-    try {
-        res = await fetch('/__editor/data-file', {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ path: projectRelativePath, content }),
-        });
-    }
-    catch (err) {
-        throw new Error('writeData: could not reach the editor dev server (/__editor/data-file) — this helper is ' +
-            'editor-tool plumbing (docs/DATA-TOOLS-DESIGN.md §3.3) and only works inside the running ' +
-            'editor. Game code must not write data assets: they are immutable at runtime (§2.1) — ' +
-            `keep runtime state in your game's own store. (${String(err)})`);
-    }
-    if (!res.ok) {
-        const detail = await res.text().catch(() => '');
-        throw new Error(`writeData: the editor rejected the write to "${projectRelativePath}" ` +
-            `(HTTP ${res.status}${detail ? `: ${detail}` : ''}).`);
-    }
-}

package/dist/react/use-selection.d.ts

@@ -1,75 +0,0 @@
-/**
- * W3.1 of docs/DATA-TOOLS-DESIGN.md §3.3 — `useSelection()`, the third
- * tool-hooks contract member (alongside `useData`/`writeData` from
- * `use-data.ts`). Where those two hooks are about DATA ASSETS, this one is
- * about the currently-selected ENTITY and the components authored on it —
- * the gap a real consumer (`critter-types-w3b`'s `critter-type.tool.tsx`,
- * §9.4) hit hard: with no way to read a component's own authored config, it
- * had to recover species from `node.label` (a display string, not data).
- *
- * Scope, v1:
- *  - INSPECTOR-placement tools only (`placement: 'inspector'`,
- *    `define-tool.ts`). `EditorSelectionProvider` is host plumbing —
- *    `InspectorToolSection` wraps every tool render in it; dock tools
- *    (`ToolHost`/`BottomPanel`) have no adapter/selection in scope and never
- *    get a provider. Calling `useSelection()` there throws a teaching error,
- *    contained by the tool's `ToolErrorBoundary` (the editor survives).
- *  - READ-only. `config` is a shallow copy of the authored record; write
- *    through `InspectorProvider.set('components.<Type>.<field>', v)` /
- *    `writeData` (the existing paths), never by mutating what this hook
- *    returns. Per-entity WRITE-from-tool is deferred with `useTunable` (§10).
- *  - Honest degrades, not errors, when the adapter is thinner than the vgai
- *    first-party one: no `components` provider at all ⇒ `components: []`;
- *    a `components` provider present but with no optional `config()`
- *    accessor ⇒ each entry still appears (from `list()`) but with
- *    `config: null`. Both mirror the `AuthoringAdapter` optional-provider
- *    doctrine (§4) — an ingest/UI adapter that never implements `components`
- *    was already legal, and stays legal.
- *
- * Liveness — two existing paths reused, no new mechanism (§4's "reuse that
- * path" rule):
- *  1. Selection changes: `Inspector.tsx`'s own
- *     `useSyncExternalStore(store.subscribe, store.getSnapshot)` re-renders
- *     the panel, each matched `Section` gets the new `nodeId` prop, and
- *     `InspectorToolSection` re-creates this provider's context value.
- *  2. Config edits while the SAME node stays selected: `adapter.subscribe`
- *     fires (the vgai adapter's store notifies on every `updateEntity`,
- *     which is what `InspectorProvider.set` goes through) — this hook keeps
- *     a local version counter bumped per notification (exactly
- *     `game-state.tsx`'s `useWorldObservation` pattern: the adapter has no
- *     snapshot/version of its own, `subscribe` is fire-only) and recomputes.
- */
-import { type ReactNode } from 'react';
-import type { AuthoringAdapter, EditorNode } from '../adapter';
-/**
- * EDITOR-side host plumbing: `InspectorToolSection` wraps a tool's rendered
- * `<Component/>` in this, passing the adapter + nodeId it already holds.
- * Project tools never render this themselves — it exists so `useSelection()`
- * has something to read.
- */
-export declare function EditorSelectionProvider({ adapter, nodeId, children, }: {
-    adapter: AuthoringAdapter;
-    nodeId: string | null;
-    children: ReactNode;
-}): import("react").JSX.Element;
-/** One component attached to the selected entity, with its authored config
- *  if the adapter can produce one (see the module doc's degrade rules). */
-export interface SelectedComponent {
-    type: string;
-    config: Record<string, unknown> | null;
-}
-export interface EditorSelection {
-    nodeId: string | null;
-    node: EditorNode | null;
-    components: SelectedComponent[];
-}
-/**
- * The selected entity, live: its node, and every component attached to it
- * with that component's own authored config (read-only — see module doc).
- *
- * Throws outside an `EditorSelectionProvider` — inspector tools always render
- * inside one; a dock tool or game-code caller does not, and the error names
- * the fix rather than failing silently.
- */
-export declare function useSelection(): EditorSelection;
-//# sourceMappingURL=use-selection.d.ts.map

package/dist/react/use-selection.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-selection.d.ts","sourceRoot":"","sources":["../../src/react/use-selection.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAEL,KAAK,SAAS,EAKf,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAS/D;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,EACtC,OAAO,EACP,MAAM,EACN,QAAQ,GACT,EAAE;IACD,OAAO,EAAE,gBAAgB,CAAC;IAC1B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,SAAS,CAAC;CACrB,+BAGA;AAED;2EAC2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,iBAAiB,EAAE,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,IAAI,eAAe,CAmC9C"}

package/dist/react/use-selection.js

@@ -1,90 +0,0 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-/**
- * W3.1 of docs/DATA-TOOLS-DESIGN.md §3.3 — `useSelection()`, the third
- * tool-hooks contract member (alongside `useData`/`writeData` from
- * `use-data.ts`). Where those two hooks are about DATA ASSETS, this one is
- * about the currently-selected ENTITY and the components authored on it —
- * the gap a real consumer (`critter-types-w3b`'s `critter-type.tool.tsx`,
- * §9.4) hit hard: with no way to read a component's own authored config, it
- * had to recover species from `node.label` (a display string, not data).
- *
- * Scope, v1:
- *  - INSPECTOR-placement tools only (`placement: 'inspector'`,
- *    `define-tool.ts`). `EditorSelectionProvider` is host plumbing —
- *    `InspectorToolSection` wraps every tool render in it; dock tools
- *    (`ToolHost`/`BottomPanel`) have no adapter/selection in scope and never
- *    get a provider. Calling `useSelection()` there throws a teaching error,
- *    contained by the tool's `ToolErrorBoundary` (the editor survives).
- *  - READ-only. `config` is a shallow copy of the authored record; write
- *    through `InspectorProvider.set('components.<Type>.<field>', v)` /
- *    `writeData` (the existing paths), never by mutating what this hook
- *    returns. Per-entity WRITE-from-tool is deferred with `useTunable` (§10).
- *  - Honest degrades, not errors, when the adapter is thinner than the vgai
- *    first-party one: no `components` provider at all ⇒ `components: []`;
- *    a `components` provider present but with no optional `config()`
- *    accessor ⇒ each entry still appears (from `list()`) but with
- *    `config: null`. Both mirror the `AuthoringAdapter` optional-provider
- *    doctrine (§4) — an ingest/UI adapter that never implements `components`
- *    was already legal, and stays legal.
- *
- * Liveness — two existing paths reused, no new mechanism (§4's "reuse that
- * path" rule):
- *  1. Selection changes: `Inspector.tsx`'s own
- *     `useSyncExternalStore(store.subscribe, store.getSnapshot)` re-renders
- *     the panel, each matched `Section` gets the new `nodeId` prop, and
- *     `InspectorToolSection` re-creates this provider's context value.
- *  2. Config edits while the SAME node stays selected: `adapter.subscribe`
- *     fires (the vgai adapter's store notifies on every `updateEntity`,
- *     which is what `InspectorProvider.set` goes through) — this hook keeps
- *     a local version counter bumped per notification (exactly
- *     `game-state.tsx`'s `useWorldObservation` pattern: the adapter has no
- *     snapshot/version of its own, `subscribe` is fire-only) and recomputes.
- */
-import { createContext, useContext, useMemo, useRef, useSyncExternalStore, } from 'react';
-const SelectionContext = createContext(null);
-/**
- * EDITOR-side host plumbing: `InspectorToolSection` wraps a tool's rendered
- * `<Component/>` in this, passing the adapter + nodeId it already holds.
- * Project tools never render this themselves — it exists so `useSelection()`
- * has something to read.
- */
-export function EditorSelectionProvider({ adapter, nodeId, children, }) {
-    const value = useMemo(() => ({ adapter, nodeId }), [adapter, nodeId]);
-    return _jsx(SelectionContext.Provider, { value: value, children: children });
-}
-/**
- * The selected entity, live: its node, and every component attached to it
- * with that component's own authored config (read-only — see module doc).
- *
- * Throws outside an `EditorSelectionProvider` — inspector tools always render
- * inside one; a dock tool or game-code caller does not, and the error names
- * the fix rather than failing silently.
- */
-export function useSelection() {
-    const ctx = useContext(SelectionContext);
-    if (!ctx) {
-        throw new Error('useSelection: no editor selection in context — this hook only works inside an editor-hosted ' +
-            "INSPECTOR tool (placement: 'inspector', docs/DATA-TOOLS-DESIGN.md §3.3/§3.2). Dock tools and " +
-            'game code have no selection to read.');
-    }
-    const { adapter, nodeId } = ctx;
-    // Local version counter bumped per adapter notification — the adapter has
-    // no snapshot/version of its own, `subscribe` is fire-only (same pattern
-    // as `useWorldObservation`'s `versionRef`, game-state.tsx).
-    const versionRef = useRef(0);
-    const version = useSyncExternalStore((onStoreChange) => adapter.subscribe?.(() => {
-        versionRef.current++;
-        onStoreChange();
-    }) ?? (() => { }), () => versionRef.current);
-    return useMemo(() => {
-        const node = nodeId ? adapter.hierarchy.node(nodeId) : null;
-        const types = nodeId ? (adapter.components?.list(nodeId) ?? []) : [];
-        const components = types.map(({ type }) => ({
-            type,
-            config: nodeId ? (adapter.components?.config?.(nodeId, type) ?? null) : null,
-        }));
-        return { nodeId, node, components };
-        // `version` has no value of its own — only its CHANGE matters, as the
-        // liveness signal described above.
-    }, [adapter, nodeId, version]);
-}

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

@@ -1,34 +0,0 @@
-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

@@ -1 +0,0 @@
-{"version":3,"file":"auto-batcher.d.ts","sourceRoot":"","sources":["../../src/render/auto-batcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAiC/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

@@ -1,140 +0,0 @@
-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/render-batch-system.d.ts

@@ -1,33 +0,0 @@
-import * as THREE from 'three';
-import type { ResolvedRenderSettings } from './render-settings';
-export declare class RenderBatchSystem {
-    private scene;
-    private settings;
-    private root;
-    private groups;
-    private dynamicGroups;
-    private parentOf;
-    private membersOf;
-    constructor(scene: THREE.Scene, settings: ResolvedRenderSettings);
-    /** Scan the scene and build instanced groups. Idempotent (rebuilds). */
-    build(): void;
-    private makeGroup;
-    /**
-     * 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;
-    /**
-     * 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;
-    /** Number of draw calls the batcher contributes (1 per group). */
-    get drawCalls(): number;
-    /** How many source meshes were collapsed into instances. */
-    get batchedCount(): number;
-    teardown(): void;
-}
-//# sourceMappingURL=render-batch-system.d.ts.map

package/dist/render/render-batch-system.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"render-batch-system.d.ts","sourceRoot":"","sources":["../../src/render/render-batch-system.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAoGhE,qBAAa,iBAAiB;IAU1B,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,QAAQ;IAVlB,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,aAAa,CAAe;IAEpC,OAAO,CAAC,QAAQ,CAA6C;IAE7D,OAAO,CAAC,SAAS,CAAoD;gBAG3D,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,QAAQ,EAAE,sBAAsB;IAM1C,wEAAwE;IACxE,KAAK,IAAI,IAAI;IAmCb,OAAO,CAAC,SAAS;IAyCjB;;;;;OAKG;IACH,MAAM,IAAI,IAAI;IAyBd;;;OAGG;IACH,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,IAAI,GAAG,IAAI;IAStD,kEAAkE;IAClE,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,4DAA4D;IAC5D,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,QAAQ,IAAI,IAAI;CAiBjB"}