@aura3d/engine 4.0.3 → 4.0.4

package/dist/engine/agent-api/lodMarkers.d.ts

@@ -0,0 +1,23 @@
+import type { AuraSceneNode, AuraVec3 } from "./nodes/types.js";
+export interface AuraLodRootSpec {
+    readonly thresholds: readonly {
+        readonly maxDistance?: number;
+    }[];
+    readonly hysteresis: number;
+    readonly position: AuraVec3;
+    readonly name?: string;
+}
+export interface AuraLodMarker {
+    readonly root: AuraLodRootSpec;
+    readonly levelIndex: number;
+}
+export declare const lodMarkerOf: (node: unknown) => AuraLodMarker | undefined;
+/** Tag `node` (and its group descendants) with `marker`; an existing inner marker wins (nested LOD). */
+export declare function tagLodLevel(node: AuraSceneNode, marker: AuraLodMarker): AuraSceneNode;
+/**
+ * True when `node` is outside any LOD tag or its level is selected at the
+ * current camera distance. Recomputing per node is idempotent within a frame
+ * (hysteresis keeps the previous index until a threshold is crossed).
+ */
+export declare function lodLevelVisible(node: unknown, cameraPosition: AuraVec3): boolean;
+//# sourceMappingURL=lodMarkers.d.ts.map

package/dist/engine/agent-api/lodMarkers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lodMarkers.d.ts","sourceRoot":"","sources":["../../../../../packages/engine/src/agent-api/lodMarkers.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAGhE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,SAAS;QAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAID,eAAO,MAAM,WAAW,GAAI,MAAM,OAAO,KAAG,aAAa,GAAG,SACjC,CAAC;AAE5B,wGAAwG;AACxG,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,GAAG,aAAa,CAMrF;AAID;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,GAAG,OAAO,CAQhF"}

package/dist/engine/agent-api/lodMarkers.js

@@ -0,0 +1,33 @@
+// threejs-parity L7/SG-11: mixed-child LOD (three's `THREE.LOD` where every
+// level is an arbitrary object). `groups.lod` tags each level's subtree with
+// an `AuraLodMarker`; the production render input consults `lodLevelVisible`
+// once per flattened node per frame and skips deselected subtrees. Selection
+// state lives in a WeakMap keyed by the shared root spec object, so it is
+// per-authored-LOD (stable across frames and across mounts).
+import { selectAuraRootLodLevel } from "./RootGeometry.js";
+export const lodMarkerOf = (node) => node.__lod;
+/** Tag `node` (and its group descendants) with `marker`; an existing inner marker wins (nested LOD). */
+export function tagLodLevel(node, marker) {
+    const tagged = Object.assign({}, node, { __lod: lodMarkerOf(node) ?? marker });
+    if (node.kind === "group") {
+        return Object.assign({}, tagged, { children: node.children.map((child) => tagLodLevel(child, marker)) });
+    }
+    return tagged;
+}
+const levelIndexByRoot = new WeakMap();
+/**
+ * True when `node` is outside any LOD tag or its level is selected at the
+ * current camera distance. Recomputing per node is idempotent within a frame
+ * (hysteresis keeps the previous index until a threshold is crossed).
+ */
+export function lodLevelVisible(node, cameraPosition) {
+    const marker = lodMarkerOf(node);
+    if (!marker)
+        return true;
+    const [x, y, z] = marker.root.position;
+    const distance = Math.hypot(cameraPosition[0] - x, cameraPosition[1] - y, cameraPosition[2] - z);
+    const selection = selectAuraRootLodLevel(distance, marker.root.thresholds, levelIndexByRoot.get(marker.root), marker.root.hysteresis);
+    levelIndexByRoot.set(marker.root, selection.levelIndex);
+    return selection.levelIndex === marker.levelIndex;
+}
+//# sourceMappingURL=lodMarkers.js.map

package/dist/engine/agent-api/lodMarkers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lodMarkers.js","sourceRoot":"","sources":["../../../../../packages/engine/src/agent-api/lodMarkers.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,6EAA6E;AAC7E,6EAA6E;AAC7E,6EAA6E;AAC7E,0EAA0E;AAC1E,6DAA6D;AAG7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAgB3D,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAa,EAA6B,EAAE,CACrE,IAAkB,CAAC,KAAK,CAAC;AAE5B,wGAAwG;AACxG,MAAM,UAAU,WAAW,CAAC,IAAmB,EAAE,MAAqB;IACpE,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,WAAW,CAAC,IAAI,CAAC,IAAI,MAAM,EAAE,CAA6B,CAAC;IAC3G,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC1B,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,EAAE,CAA6B,CAAC;IACvI,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,gBAAgB,GAAG,IAAI,OAAO,EAA2B,CAAC;AAEhE;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,IAAa,EAAE,cAAwB;IACrE,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC;IACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACjG,MAAM,SAAS,GAAG,sBAAsB,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACtI,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC;IACxD,OAAO,SAAS,CAAC,UAAU,KAAK,MAAM,CAAC,UAAU,CAAC;AACpD,CAAC"}

package/dist/engine/agent-api/nodes/batched.d.ts

@@ -0,0 +1,96 @@
+import type { NodeHandler, SceneCompileContext } from "../../contracts/compiler.js";
+import { AuraNodeBuilder } from "./builder.js";
+import type { AuraBatchedNode, AuraColor, AuraMaterialSpec } from "./types.js";
+import { BatchedMeshState } from "./batchedState.js";
+export { BatchedMeshState, batchedStateFor, batchedStateForNode, registerBatchedState } from "./batchedState.js";
+export type { AuraBatchedGeometryInput, AuraBatchedMeshMode } from "./batchedState.js";
+import type { AuraBatchedGeometryInput, AuraBatchedMeshMode } from "./batchedState.js";
+/** Register the L5 feature + chunks once (idempotent; engine import side effect). */
+export declare function registerBatchedDrawShader(): void;
+export interface AuraBatchedEmitReport {
+    readonly mode: "multi-draw" | "loop" | "instanced";
+    readonly geometries: number;
+    readonly instances: number;
+    readonly draws: number;
+    readonly fallbackReason?: string;
+}
+export declare function resolveBatchedMode(state: BatchedMeshState, node: AuraBatchedNode, ctx: SceneCompileContext): {
+    readonly mode: "multi-draw" | "loop" | "instanced";
+    readonly fallbackReason?: string;
+};
+export declare const batchedNodeHandler: NodeHandler<{
+    readonly kind: "batched";
+}>;
+export interface AuraBatchedMeshOptions {
+    readonly maxInstances: number;
+    readonly maxVertices?: number;
+    readonly maxIndices?: number;
+    readonly material?: AuraMaterialSpec;
+    /** "auto" (default): packed multi-draw on the generated path, per-geometry instancing otherwise. */
+    readonly multiDraw?: AuraBatchedMeshMode;
+    readonly name?: string;
+    readonly geometries?: readonly AuraBatchedGeometryInput[];
+}
+/**
+ * `batched.mesh` handle — an `AuraNodeBuilder` (scene-addable, chainable
+ * transforms) plus the three.js BatchedMesh mutation API. Builder methods
+ * return a fresh handle sharing the same dense state (`batchedId` survives
+ * the builder's spread-clone).
+ */
+export declare class AuraBatchedMeshHandle extends AuraNodeBuilder<AuraBatchedNode> {
+    readonly state: BatchedMeshState;
+    constructor(node: AuraBatchedNode, state: BatchedMeshState);
+    private rewrap;
+    position(x: number, y: number, z: number): AuraNodeBuilder<AuraBatchedNode & {
+        readonly position: import("./types.js").AuraVec3;
+    }>;
+    rotate(x: number, y: number, z: number, order?: import("../../contracts/sceneGraph.js").AuraEulerOrder): AuraNodeBuilder<AuraBatchedNode & {
+        readonly rotation: import("./types.js").AuraVec3;
+        readonly rotationOrder?: import("../../contracts/sceneGraph.js").AuraEulerOrder;
+    }>;
+    quaternion(x: number, y: number, z: number, w: number): AuraNodeBuilder<AuraBatchedNode & {
+        readonly quaternion: import("../../contracts/sceneGraph.js").AuraQuat;
+    }>;
+    scale(value: number | import("./types.js").AuraVec3): AuraNodeBuilder<AuraBatchedNode & {
+        readonly scale: number | import("./types.js").AuraVec3;
+    }>;
+    lookAt(x: number, y: number, z: number): AuraNodeBuilder<AuraBatchedNode & {
+        readonly lookAt: import("./types.js").AuraVec3;
+    }>;
+    material(spec: AuraMaterialSpec): AuraNodeBuilder<AuraBatchedNode & {
+        readonly material: AuraMaterialSpec;
+    }>;
+    runtime(spec: import("./types.js").AuraRuntimeNodeSpec): AuraNodeBuilder<AuraBatchedNode & {
+        readonly runtime: import("./types.js").AuraRuntimeNodeSpec;
+    }>;
+    /** Register a geometry; returns its geometryId (insertion order). */
+    addGeometry(geometry: AuraBatchedGeometryInput): number;
+    addInstance(geometryId: number): number;
+    setMatrixAt(index: number, matrix: Float32Array | readonly number[] | {
+        readonly elements: ArrayLike<number>;
+    }): this;
+    getMatrixAt(index: number, out?: Float32Array | number[]): Float32Array | number[];
+    setColorAt(index: number, color: AuraColor | readonly number[]): this;
+    getColorAt(index: number, out?: number[]): number[];
+    setVisibleAt(index: number, visible: boolean): this;
+    deleteInstance(index: number): this;
+    get count(): number;
+    /** three.js `instanceMatrix.needsUpdate`-style explicit flush (uploads are per-frame already). */
+    set needsUpdate(_v: boolean);
+    /** Union bounding sphere over live instances (three.js `computeBoundingSphere`). */
+    computeBoundingSphere(): {
+        readonly center: readonly [number, number, number];
+        readonly radius: number;
+    };
+    get boundingSphere(): {
+        readonly center: readonly [number, number, number];
+        readonly radius: number;
+    };
+    dispose(): void;
+}
+declare function batchedMesh(options: AuraBatchedMeshOptions): AuraBatchedMeshHandle;
+/** `batched` namespace — parity-L5 multi-geometry instancing (SG-02). */
+export declare const batched: {
+    readonly mesh: typeof batchedMesh;
+};
+//# sourceMappingURL=batched.d.ts.map

package/dist/engine/agent-api/nodes/batched.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batched.d.ts","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/nodes/batched.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EAAE,WAAW,EAA6B,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAG/G,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAM/C,OAAO,KAAK,EAAE,eAAe,EAAwB,SAAS,EAAE,gBAAgB,EAAqB,MAAM,YAAY,CAAC;AACxH,OAAO,EAGL,gBAAgB,EAMjB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACvF,OAAO,KAAK,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AA0GvF,qFAAqF;AACrF,wBAAgB,yBAAyB,IAAI,IAAI,CAyChD;AAMD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,GAAG,WAAW,CAAC;IACnD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAaD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,eAAe,EAAE,GAAG,EAAE,mBAAmB,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,GAAG,WAAW,CAAC;IAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,CAUrM;AAqHD,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAoBxE,CAAC;AAWF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IACrC,oGAAoG;IACpG,QAAQ,CAAC,SAAS,CAAC,EAAE,mBAAmB,CAAC;IACzC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,wBAAwB,EAAE,CAAC;CAC3D;AAED;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,eAAe,CAAC,eAAe,CAAC;IACzE,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;gBAErB,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,gBAAgB;IAK1D,OAAO,CAAC,MAAM;IAML,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC,eAAe,GAAG;QAAE,QAAQ,CAAC,QAAQ,EAAE,OAAO,YAAY,EAAE,QAAQ,CAAA;KAAE,CAAC;IAGlI,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,4BAA4B,EAAE,cAAc,GAAG,eAAe,CAAC,eAAe,GAAG;QAAE,QAAQ,CAAC,QAAQ,EAAE,OAAO,YAAY,EAAE,QAAQ,CAAC;QAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,4BAA4B,EAAE,cAAc,CAAA;KAAE,CAAC;IAG3Q,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC,eAAe,GAAG;QAAE,QAAQ,CAAC,UAAU,EAAE,OAAO,4BAA4B,EAAE,QAAQ,CAAA;KAAE,CAAC;IAGjK,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,YAAY,EAAE,QAAQ,GAAG,eAAe,CAAC,eAAe,GAAG;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,YAAY,EAAE,QAAQ,CAAA;KAAE,CAAC;IAGnJ,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC,eAAe,GAAG;QAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,YAAY,EAAE,QAAQ,CAAA;KAAE,CAAC;IAG9H,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,eAAe,CAAC,eAAe,GAAG;QAAE,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;KAAE,CAAC;IAG5G,OAAO,CAAC,IAAI,EAAE,OAAO,YAAY,EAAE,mBAAmB,GAAG,eAAe,CAAC,eAAe,GAAG;QAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,YAAY,EAAE,mBAAmB,CAAA;KAAE,CAAC;IAInK,qEAAqE;IACrE,WAAW,CAAC,QAAQ,EAAE,wBAAwB,GAAG,MAAM;IAIvD,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAIvC,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,SAAS,MAAM,EAAE,GAAG;QAAE,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,MAAM,CAAC,CAAA;KAAE,GAAG,IAAI;IAKrH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,YAAY,GAAG,MAAM,EAAE,GAAG,YAAY,GAAG,MAAM,EAAE;IAIlF,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,SAAS,MAAM,EAAE,GAAG,IAAI;IAKrE,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE;IAInD,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAKnD,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKnC,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,kGAAkG;IAClG,IAAI,WAAW,CAAC,EAAE,EAAE,OAAO,EAE1B;IAED,oFAAoF;IACpF,qBAAqB,IAAI;QAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE;IAWxG,IAAI,cAAc,IAAI;QAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAEpG;IAED,OAAO,IAAI,IAAI;CAGhB;AAED,iBAAS,WAAW,CAAC,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAsB3E;AAED,yEAAyE;AACzE,eAAO,MAAM,OAAO;;CAER,CAAC"}

package/dist/engine/agent-api/nodes/batched.js

@@ -0,0 +1,456 @@
+/**
+ * SG-02 / parity-L5 — `batched.mesh` (three.js `BatchedMesh` parity) and the
+ * shared dense-instance state that also backs `instances.mesh` (SG-01).
+ *
+ * One `kind:"batched"` node carries multiple geometries and a fixed-capacity
+ * instance pool: `addGeometry` packs each `Geometry` into a
+ * `BatchedGeometryPool` (shared vertex/index arenas, `geometryId` = insertion
+ * order), `addInstance` allocates a slot, and `setMatrixAt`/`setColorAt`/
+ * `setVisibleAt`/`deleteInstance` mutate dense per-instance storage.
+ *
+ * Render routes (resolved per update by {@link resolveBatchedMode}):
+ *
+ *   - "multi-draw": one `RenderItem` per live instance, all sharing the pooled
+ *     `Geometry`; `drawRange` selects the instance's packed slice and the
+ *     `multiDraw` marker selects the `parity.batchDraw` shader feature, which
+ *     fetches model matrix + base colour + visibility flags from a
+ *     `DrawDataTexture` row. `DrawSubmit` enqueues consecutive markers into a
+ *     single `device.multiDrawElementsInstanced` — one real
+ *     `WEBGL_multi_draw` call when the extension exists (the program uses
+ *     `gl_DrawID`), else an honest one-draw-per-member loop (`u_drawId`).
+ *     Requires the generated-program path (A3D_QR_CORE_GENERATOR) — otherwise
+ *     degrades to "instanced".
+ *   - "instanced": one `RenderItem` per geometry bucket carrying dense
+ *     `instanceTransforms`/`instanceColors` — the native instanced-material
+     * path, an honest one-draw-per-geometry fallback that works on every
+ *     renderer path.
+ *
+ * The dense `matrices`/`colors` stores are the same arrays uploaded via the
+ * C-07 `InstanceBufferLike.setMatrices/setColors` contract — writes are the
+ * real GPU-write path (L5-01), not a decompose-to-spec stub.
+ */
+import { Geometry } from "../../../rendering/index.js";
+import { BatchedGeometryPool, DrawDataTexture, packDrawDataFlags } from "../../../rendering/index.js";
+import { qrCoreGeneratorOn } from "../../../rendering/index.js";
+import { registerShaderChunk, registerShaderFeature, registerDepthVariantFeature } from "../../../rendering/contracts/index.js";
+import { registerNodeHandler } from "../../contracts/compiler.js";
+import { AuraRuntimeError } from "../compiler/errors.js";
+import { AuraNodeBuilder } from "./builder.js";
+import { lazyNamespace } from "../lazyNamespace.js";
+import { colorToRgba } from "../colorUtils.js";
+import { createModelMatrix } from "../sceneMath.js";
+import { createProductionPrimitiveGeometry, createProductionPrimitiveMaterial } from "../compiler/primitives.js";
+import { allocBatchedStateId, batchedIdentityMatrix, BatchedMeshState, batchedStateForNode, registerBatchedColorConverter, registerBatchedGeometryResolver, registerBatchedNodeSeeder, registerBatchedState } from "./batchedState.js";
+export { BatchedMeshState, batchedStateFor, batchedStateForNode, registerBatchedState } from "./batchedState.js";
+// Injected impls for the leaf module (see batchedState.ts header): geometry
+// resolution needs `compiler/primitives`, authored-node seeding needs
+// `sceneMath` — both cyclic — so they register here at module eval.
+registerBatchedGeometryResolver((input) => {
+    if (typeof input === "string") {
+        return createProductionPrimitiveGeometry({ kind: "primitive", primitive: input });
+    }
+    return createProductionPrimitiveGeometry({ kind: "primitive", primitive: "custom", geometry: input });
+});
+registerBatchedColorConverter(colorToRgba);
+registerBatchedNodeSeeder((node, state) => {
+    (node.instances ?? []).forEach((transform) => {
+        const slot = state.addInstance(0);
+        const m = createModelMatrix({ kind: "primitive", primitive: "box", ...transform }, { min: [-0.5, -0.5, -0.5], max: [0.5, 0.5, 0.5] }, false, 0);
+        state.setMatrixAt(slot, m);
+        const color = node.instanceColors?.[slot];
+        if (color !== undefined)
+            state.setColorAt(slot, color);
+    });
+});
+/* ------------------------------------------------------------------ */
+/* `parity.batchDraw` shader feature (generated-program path)          */
+/* ------------------------------------------------------------------ */
+const L5_BATCH_PARS_CHUNK = "a3d_l5_batch_draw_pars";
+const L5_BATCH_WORLD_CHUNK = "a3d_l5_batch_draw_world";
+const L5_BATCH_FRAG_CHUNK = "a3d_l5_batch_draw_frag";
+const L5_BATCH_FEATURE = "parity.batchDraw";
+const L5_BATCH_DEPTH_FEATURE = "parity.batchDraw.depth";
+/**
+ * Declarations shared by both stages. `a3d_l5_draw_index` resolves to
+ * `gl_DrawID` when the driver exposes `WEBGL_multi_draw` AND the feature's
+ * multi-draw bit is set — `#extension ... : warn` (emitted by the generator
+ * for `A3D_L5_MULTI_DRAW`) leaves the macro undefined on drivers without it,
+ * selecting the `u_drawId` uniform loop instead. That is exactly the
+ * distinction `canMultiDraw` keys on (a program declaring `u_drawId` is the
+ * uniform-loop fallback).
+ */
+const L5_BATCH_PARS_GLSL = /* glsl */ `
+#if defined(WEBGL_multi_draw) && defined(A3D_L5_MULTI_DRAW)
+#define a3d_l5_draw_index gl_DrawID
+#else
+uniform highp int u_drawId;
+#define a3d_l5_draw_index u_drawId
+#endif
+uniform highp sampler2D u_a3dDrawData;
+#ifdef A3D_STAGE_VERTEX
+out vec4 v_a3dL5DrawColor;
+#else
+in vec4 v_a3dL5DrawColor;
+#endif
+vec4 a3dL5DrawTexel(int draw, int row) {
+  return texelFetch(u_a3dDrawData, ivec2(draw * 6 + row, 0), 0);
+}
+mat4 a3dL5DrawModel(int draw) {
+  return mat4(a3dL5DrawTexel(draw, 0), a3dL5DrawTexel(draw, 1), a3dL5DrawTexel(draw, 2), a3dL5DrawTexel(draw, 3));
+}
+vec4 a3dL5DrawBaseColor(int draw) {
+  return a3dL5DrawTexel(draw, 4);
+}
+vec4 a3dL5DrawMeta(int draw) {
+  return a3dL5DrawTexel(draw, 5);
+}
+`;
+/**
+ * World hook: the draw row's model matrix replaces `u_modelMatrix *
+ * instanceMatrix` entirely — the engine folds node×instance transforms into
+ * the draw-data texture so one packed draw = one (geometry-slice, instance)
+ * pair. meta.w bit 0 is the visibility flag: hidden rows collapse to a
+ * degenerate point at the origin (no fragments).
+ */
+const L5_BATCH_WORLD_GLSL = /* glsl */ `
+#ifdef A3D_L5_BATCH_DRAW
+  {
+    int a3dL5Draw = a3d_l5_draw_index;
+    vec4 a3dL5Meta = a3dL5DrawMeta(a3dL5Draw);
+    mat4 a3dL5Model = a3dL5DrawModel(a3dL5Draw);
+    v_a3dL5DrawColor = a3dL5DrawBaseColor(a3dL5Draw);
+    a3dWorld = a3dL5Model * a3dLocal;
+    if ((floatBitsToUint(a3dL5Meta.w) & 1u) == 0u) a3dWorld = vec4(0.0);
+  }
+#endif
+`;
+/**
+ * Material hook: per-draw base colour, applied to `a3dBaseColor` and (when
+ * lit) to the already-constructed `PhysicalMaterial`'s colour-derived fields
+ * so diffuse and specular both track the draw colour.
+ */
+const L5_BATCH_FRAG_GLSL = /* glsl */ `
+#ifdef A3D_L5_BATCH_DRAW
+  a3dBaseColor *= v_a3dL5DrawColor;
+  #ifdef A3D_LIT
+    material.baseColor *= v_a3dL5DrawColor.rgb;
+    material.diffuseContribution *= v_a3dL5DrawColor.rgb;
+    material.specularColorBlended *= v_a3dL5DrawColor.rgb;
+  #endif
+#endif
+`;
+let batchDrawShaderRegistered = false;
+/** Register the L5 feature + chunks once (idempotent; engine import side effect). */
+export function registerBatchedDrawShader() {
+    if (batchDrawShaderRegistered)
+        return;
+    batchDrawShaderRegistered = true;
+    registerShaderChunk({ name: L5_BATCH_PARS_CHUNK, owner: "prd15", glsl: L5_BATCH_PARS_GLSL, stage: "both" });
+    registerShaderChunk({ name: L5_BATCH_WORLD_CHUNK, owner: "prd15", glsl: L5_BATCH_WORLD_GLSL, stage: "vertex" });
+    registerShaderChunk({ name: L5_BATCH_FRAG_CHUNK, owner: "prd15", glsl: L5_BATCH_FRAG_GLSL, stage: "fragment" });
+    registerShaderFeature({
+        id: L5_BATCH_FEATURE,
+        owner: "prd15",
+        flag: "A3D_PARITY_BATCHING",
+        order: 40,
+        select: (input) => {
+            if (input.pass !== "forward")
+                return undefined;
+            const marker = input.item.multiDraw;
+            return marker ? marker.mode : undefined;
+        },
+        defines: (value) => value === "multi-draw"
+            ? { A3D_L5_BATCH_DRAW: true, A3D_L5_MULTI_DRAW: true }
+            : { A3D_L5_BATCH_DRAW: true },
+        chunks: [L5_BATCH_PARS_CHUNK, L5_BATCH_PARS_CHUNK, L5_BATCH_WORLD_CHUNK, L5_BATCH_FRAG_CHUNK],
+        hooks: ["vertex:pars", "fragment:pars", "vertex:world", "fragment:material"],
+        bindUniforms: (_value, item, set) => {
+            const marker = item.multiDraw;
+            if (!marker)
+                return;
+            set("u_drawId", marker.drawIndex);
+            if (marker.drawData)
+                set("u_a3dDrawData", marker.drawData);
+        }
+    });
+    // Depth/distance passes run through the depth-variant registry — same
+    // fetch, vertex stage only, so shadow casters stay correct.
+    registerDepthVariantFeature({
+        id: L5_BATCH_DEPTH_FEATURE,
+        owner: "prd15",
+        flag: "A3D_PARITY_BATCHING",
+        passes: ["depth", "distance"],
+        select: (input) => input.item.multiDraw ? true : undefined,
+        defines: () => ({ A3D_L5_BATCH_DRAW: true }),
+        chunks: [L5_BATCH_PARS_CHUNK, L5_BATCH_WORLD_CHUNK],
+        hooks: ["vertex:pars", "vertex:world"]
+    });
+}
+const SHARED_DEFAULT_MATERIAL = Object.freeze({ name: "a3d-batched-default" });
+function pseudoNodeFor(node, instances) {
+    return { kind: "primitive", primitive: "box", material: node.material, ...(instances ? { instances: instances } : {}) };
+}
+/** Node transform (position/rotation/scale/quaternion) as a model matrix, sans fit/normalize. */
+function batchedNodeModelMatrix(node, bounds, time) {
+    return createModelMatrix(node, bounds, false, time);
+}
+export function resolveBatchedMode(state, node, ctx) {
+    const requested = state.mode !== "auto" ? state.mode : node.multiDraw ?? "auto";
+    const single = state.geometries.length <= 1;
+    if (requested === "instanced" || single) {
+        return { mode: "instanced", ...(requested !== "instanced" && single ? { fallbackReason: "single-geometry" } : {}) };
+    }
+    if (!qrCoreGeneratorOn(ctx.flags)) {
+        return { mode: "instanced", fallbackReason: "generated-programs-off" };
+    }
+    return { mode: requested === "auto" ? "multi-draw" : requested };
+}
+/**
+ * Emit the render items for a batched node. Packed mode uploads the draw-data
+ * rows (`model = nodeModel × instanceMatrix`, base colour, visible flag |
+ * geometryId in meta.w) then emits one marker item per live instance — the
+ * enqueue inside `DrawSubmit` turns a compatible run into one
+ * `multiDrawElementsInstanced` call; otherwise each draws once (loop).
+ */
+function emitBatchedItems(state, node, ctx, out, time) {
+    const { mode, fallbackReason } = resolveBatchedMode(state, node, ctx);
+    if (node.visible === false) {
+        return { mode, geometries: state.geometries.length, instances: 0, draws: 0, ...(fallbackReason ? { fallbackReason } : {}) };
+    }
+    const bounds = state.boundingBox();
+    const nodeModel = batchedNodeModelMatrix(node, bounds, time);
+    const slots = state.liveSlots();
+    if (mode === "instanced") {
+        // One item per geometry bucket; dense slices ride the C-07 instance path.
+        const buckets = new Map();
+        for (const slot of slots) {
+            const gid = state.geometryIdAt(slot);
+            const list = buckets.get(gid) ?? [];
+            list.push(slot);
+            buckets.set(gid, list);
+        }
+        const items = [];
+        const pseudo = pseudoNodeFor(node, [{}]);
+        const materialKey = node.material ?? SHARED_DEFAULT_MATERIAL;
+        for (const [gid, list] of buckets) {
+            const geometry = state.geometries[gid];
+            if (!geometry)
+                continue;
+            const transforms = new Float32Array(list.length * 16);
+            const colors = new Float32Array(list.length * 4);
+            list.forEach((slot, i) => {
+                transforms.set(state.matrices.subarray(slot * 16, slot * 16 + 16), i * 16);
+                colors.set(state.colors.subarray(slot * 4, slot * 4 + 4), i * 4);
+            });
+            const material = state.materialFor(materialKey, () => createProductionPrimitiveMaterial(pseudo));
+            items.push({
+                geometry,
+                material: material,
+                modelMatrix: nodeModel,
+                instanceTransforms: transforms,
+                instanceColors: colors,
+                castShadow: node.castShadow ?? true
+            });
+        }
+        out.addItems(items);
+        return { mode, geometries: buckets.size, instances: slots.length, draws: items.length, ...(fallbackReason ? { fallbackReason } : {}) };
+    }
+    // Packed route — pooled geometry + draw-data rows + multiDraw markers.
+    const { geometry, entries } = state.packedGeometry();
+    const drawData = state.packedDrawData();
+    const pseudo = pseudoNodeFor(node, undefined);
+    const material = state.materialFor(node.material ?? SHARED_DEFAULT_MATERIAL, () => createProductionPrimitiveMaterial(pseudo));
+    const items = [];
+    slots.forEach((slot, drawIndex) => {
+        const gid = state.geometryIdAt(slot);
+        const entry = entries[gid];
+        if (!entry)
+            return;
+        // Fold node model × instance local matrix into the draw row.
+        const row = new Float32Array(16);
+        multiplyMat4Into(row, nodeModel, state.matrices.subarray(slot * 16, slot * 16 + 16));
+        drawData.setDraw(drawIndex, {
+            model: row,
+            baseColor: state.colors.subarray(slot * 4, slot * 4 + 4),
+            meta: [entry.firstIndex, entry.baseVertex, entry.indexCount, packDrawDataFlags(state.isVisible(slot), gid)]
+        });
+        items.push({
+            geometry,
+            material,
+            drawRange: entry.firstIndex >= 0
+                ? { start: entry.firstIndex, count: entry.indexCount }
+                : { start: entry.baseVertex, count: entry.vertexCount },
+            modelMatrix: batchedIdentityMatrix,
+            castShadow: node.castShadow ?? true,
+            multiDraw: { mode, drawIndex, drawData: drawData.upload() }
+        });
+    });
+    out.addItems(items);
+    return { mode, geometries: state.geometries.length, instances: slots.length, draws: mode === "multi-draw" ? 1 : items.length, ...(fallbackReason ? { fallbackReason } : {}) };
+}
+/** Column-major `out = a * b`. */
+function multiplyMat4Into(out, a, b) {
+    for (let col = 0; col < 4; col += 1) {
+        const b0 = b[col * 4], b1 = b[col * 4 + 1], b2 = b[col * 4 + 2], b3 = b[col * 4 + 3];
+        out[col * 4] = a[0] * b0 + a[4] * b1 + a[8] * b2 + a[12] * b3;
+        out[col * 4 + 1] = a[1] * b0 + a[5] * b1 + a[9] * b2 + a[13] * b3;
+        out[col * 4 + 2] = a[2] * b0 + a[6] * b1 + a[10] * b2 + a[14] * b3;
+        out[col * 4 + 3] = a[3] * b0 + a[7] * b1 + a[11] * b2 + a[15] * b3;
+    }
+}
+const L5_FLAG = "A3D_PARITY_BATCHING";
+/** Any non-"prd15" owner runs: "prd15" is the C-36 bridge/skip sentinel. */
+const L5_OWNER = "prd11";
+/** Fail closed while the lane flag is off (identical code path to parityPending). */
+function assertL5Flag(ctx) {
+    if (!ctx.flags.on(L5_FLAG)) {
+        throw new AuraRuntimeError("parity-not-implemented", `Aura3D scene node kind "batched" is not yet implemented (${L5_FLAG}). See docs/workflows/threejs-parity-gaps.md.`);
+    }
+}
+export const batchedNodeHandler = {
+    kind: "batched",
+    owner: L5_OWNER,
+    flag: "A3D_PARITY_BATCHING",
+    compile(node, ctx, out) {
+        assertL5Flag(ctx);
+        registerBatchedDrawShader();
+        const batchedNode = node;
+        const state = batchedStateForNode(batchedNode);
+        const report = emitBatchedItems(state, batchedNode, ctx, out, 0);
+        if (report.mode === "instanced")
+            out.feature("instancing");
+        out.set("parityBatched", report);
+    },
+    update(node, _handle, ctx, out, timeSeconds) {
+        registerBatchedDrawShader();
+        const batchedNode = node;
+        const state = batchedStateForNode(batchedNode);
+        const report = emitBatchedItems(state, batchedNode, ctx, out, timeSeconds);
+        out.set("parityBatched", report);
+    }
+};
+// The registered handler wins over the flag-off `parityPending` table default
+// whenever A3D_PARITY_BATCHING is on (resolveNodeHandler); the pending entry
+// remains the fail-closed stub when the flag is off.
+registerNodeHandler(batchedNodeHandler);
+/**
+ * `batched.mesh` handle — an `AuraNodeBuilder` (scene-addable, chainable
+ * transforms) plus the three.js BatchedMesh mutation API. Builder methods
+ * return a fresh handle sharing the same dense state (`batchedId` survives
+ * the builder's spread-clone).
+ */
+export class AuraBatchedMeshHandle extends AuraNodeBuilder {
+    state;
+    constructor(node, state) {
+        super(node);
+        this.state = state;
+    }
+    rewrap(builder) {
+        return new AuraBatchedMeshHandle(builder.toJSON(), this.state);
+    }
+    // Chainables keep the base signatures (a chained call still returns a live
+    // handle sharing `state` — the cast only erases the builder's patch type).
+    position(x, y, z) {
+        return this.rewrap(super.position(x, y, z));
+    }
+    rotate(x, y, z, order) {
+        return this.rewrap(super.rotate(x, y, z, order));
+    }
+    quaternion(x, y, z, w) {
+        return this.rewrap(super.quaternion(x, y, z, w));
+    }
+    scale(value) {
+        return this.rewrap(super.scale(value));
+    }
+    lookAt(x, y, z) {
+        return this.rewrap(super.lookAt(x, y, z));
+    }
+    material(spec) {
+        return this.rewrap(super.material(spec));
+    }
+    runtime(spec) {
+        return this.rewrap(super.runtime(spec));
+    }
+    /** Register a geometry; returns its geometryId (insertion order). */
+    addGeometry(geometry) {
+        return this.state.addGeometry(geometry);
+    }
+    addInstance(geometryId) {
+        return this.state.addInstance(geometryId);
+    }
+    setMatrixAt(index, matrix) {
+        this.state.setMatrixAt(index, matrix);
+        return this;
+    }
+    getMatrixAt(index, out) {
+        return this.state.getMatrixAt(index, out);
+    }
+    setColorAt(index, color) {
+        this.state.setColorAt(index, color);
+        return this;
+    }
+    getColorAt(index, out) {
+        return this.state.getColorAt(index, out);
+    }
+    setVisibleAt(index, visible) {
+        this.state.setVisibleAt(index, visible);
+        return this;
+    }
+    deleteInstance(index) {
+        this.state.deleteInstance(index);
+        return this;
+    }
+    get count() {
+        return this.state.count;
+    }
+    /** three.js `instanceMatrix.needsUpdate`-style explicit flush (uploads are per-frame already). */
+    set needsUpdate(_v) {
+        this.state.version += 1;
+    }
+    /** Union bounding sphere over live instances (three.js `computeBoundingSphere`). */
+    computeBoundingSphere() {
+        const box = this.state.boundingBox();
+        const center = [
+            (box.min[0] + box.max[0]) / 2,
+            (box.min[1] + box.max[1]) / 2,
+            (box.min[2] + box.max[2]) / 2
+        ];
+        const radius = Math.hypot(box.max[0] - box.min[0], box.max[1] - box.min[1], box.max[2] - box.min[2]) / 2;
+        return { center, radius };
+    }
+    get boundingSphere() {
+        return this.computeBoundingSphere();
+    }
+    dispose() {
+        this.state.dispose();
+    }
+}
+function batchedMesh(options) {
+    const id = allocBatchedStateId();
+    const state = new BatchedMeshState({
+        id,
+        capacity: options.maxInstances,
+        ...(options.maxVertices !== undefined ? { maxVertices: options.maxVertices } : {}),
+        ...(options.maxIndices !== undefined ? { maxIndices: options.maxIndices } : {}),
+        ...(options.multiDraw !== undefined ? { mode: options.multiDraw } : {})
+    });
+    for (const input of options.geometries ?? [])
+        state.addGeometry(input);
+    const node = {
+        kind: "batched",
+        batchedId: id,
+        maxInstances: options.maxInstances,
+        ...(options.maxVertices !== undefined ? { maxVertices: options.maxVertices } : {}),
+        ...(options.maxIndices !== undefined ? { maxIndices: options.maxIndices } : {}),
+        ...(options.material !== undefined ? { material: options.material } : {}),
+        ...(options.multiDraw !== undefined ? { multiDraw: options.multiDraw } : {}),
+        ...(options.name !== undefined ? { name: options.name } : {})
+    };
+    registerBatchedState(state);
+    return new AuraBatchedMeshHandle(node, state);
+}
+/** `batched` namespace — parity-L5 multi-geometry instancing (SG-02). */
+export const batched = lazyNamespace(() => ({
+    mesh: batchedMesh
+}));
+//# sourceMappingURL=batched.js.map