@aura3d/engine 4.0.3 → 4.0.4

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

@@ -0,0 +1,100 @@
+import { AuraNodeBuilder } from "./builder.js";
+import type { AuraColor, AuraLineNode, AuraVec3 } from "./types.js";
+export interface AuraHelperBaseOptions {
+    readonly name?: string;
+    readonly visible?: boolean;
+    readonly position?: AuraVec3;
+    readonly rotation?: AuraVec3;
+    readonly scale?: number | AuraVec3;
+}
+/** `helpers.axes({ size = 1 })` — X red, Y green, Z blue (three's `AxesHelper`). */
+export declare function axes(options?: AuraHelperBaseOptions & {
+    readonly size?: number;
+}): AuraNodeBuilder<AuraLineNode>;
+/** `helpers.grid({ size = 10, divisions = 10, colorCenterLine?, colorGrid? })` — XZ grid (three's `GridHelper`). */
+export declare function grid(options?: AuraHelperBaseOptions & {
+    readonly size?: number;
+    readonly divisions?: number;
+    readonly colorCenterLine?: AuraColor;
+    readonly colorGrid?: AuraColor;
+}): AuraNodeBuilder<AuraLineNode>;
+/** `helpers.polarGrid({ radius = 10, sectors = 16, rings = 5, division = 64 })` (three's `PolarGridHelper`). */
+export declare function polarGrid(options?: AuraHelperBaseOptions & {
+    readonly radius?: number;
+    readonly sectors?: number;
+    readonly rings?: number;
+    readonly division?: number;
+    readonly colorCenterLine?: AuraColor;
+    readonly colorGrid?: AuraColor;
+}): AuraNodeBuilder<AuraLineNode>;
+/** `helpers.box3({ min, max })` — the 12 edges of an AABB (three's `Box3Helper`). */
+export declare function box3(options: AuraHelperBaseOptions & {
+    readonly min: AuraVec3;
+    readonly max: AuraVec3;
+    readonly color?: AuraColor;
+}): AuraNodeBuilder<AuraLineNode>;
+/** `helpers.box({ size = 1, center = [0,0,0] })` — centred AABB convenience over `box3` (three's `BoxHelper` static form). */
+export declare function box(options?: AuraHelperBaseOptions & {
+    readonly size?: number | AuraVec3;
+    readonly center?: AuraVec3;
+    readonly color?: AuraColor;
+}): AuraNodeBuilder<AuraLineNode>;
+/** `helpers.arrow({ dir, origin?, length?, headLength?, headWidth?, color? })` (three's `ArrowHelper`, line-only). */
+export declare function arrow(options: AuraHelperBaseOptions & {
+    readonly dir: AuraVec3;
+    readonly origin?: AuraVec3;
+    readonly length?: number;
+    readonly headLength?: number;
+    readonly headWidth?: number;
+    readonly color?: AuraColor;
+}): AuraNodeBuilder<AuraLineNode>;
+/** `helpers.camera({ position?, rotation?, fov?, aspect?, near?, far? })` — frustum lines (three's `CameraHelper`, static pose form). */
+export declare function camera(options?: AuraHelperBaseOptions & {
+    readonly fov?: number;
+    readonly aspect?: number;
+    readonly near?: number;
+    readonly far?: number;
+    readonly color?: AuraColor;
+}): AuraNodeBuilder<AuraLineNode>;
+/** `helpers.directionalLight({ position?, target?, size?, color? })` — plane glyph + rays (three's `DirectionalLightHelper`). */
+export declare function directionalLight(options?: AuraHelperBaseOptions & {
+    readonly target?: AuraVec3;
+    readonly size?: number;
+    readonly color?: AuraColor;
+}): AuraNodeBuilder<AuraLineNode>;
+/** `helpers.pointLight({ sphereSize?, distance?, color? })` — wireframe bulb rings (three's `PointLightHelper`). */
+export declare function pointLight(options?: AuraHelperBaseOptions & {
+    readonly sphereSize?: number;
+    readonly color?: AuraColor;
+}): AuraNodeBuilder<AuraLineNode>;
+/** `helpers.spotLight({ angle?, distance?, color? })` — cone wireframe (three's `SpotLightHelper`). */
+export declare function spotLight(options?: AuraHelperBaseOptions & {
+    readonly angle?: number;
+    readonly distance?: number;
+    readonly color?: AuraColor;
+}): AuraNodeBuilder<AuraLineNode>;
+/**
+ * `helpers.skeleton({ positions, parents? })` — bone lines joint→parent
+ * (three's `SkeletonHelper` static form). `parents[i]` is the parent joint
+ * index, `-1` for roots; absent → a sequential chain.
+ */
+export declare function skeleton(options: AuraHelperBaseOptions & {
+    readonly positions: readonly AuraVec3[];
+    readonly parents?: readonly number[];
+    readonly color?: AuraColor;
+}): AuraNodeBuilder<AuraLineNode>;
+/** `helpers.*` namespace (SC-03): every glyph is a real line-segment node. */
+export declare const helpers: {
+    readonly axes: typeof axes;
+    readonly grid: typeof grid;
+    readonly polarGrid: typeof polarGrid;
+    readonly box: typeof box;
+    readonly box3: typeof box3;
+    readonly arrow: typeof arrow;
+    readonly camera: typeof camera;
+    readonly directionalLight: typeof directionalLight;
+    readonly spotLight: typeof spotLight;
+    readonly pointLight: typeof pointLight;
+    readonly skeleton: typeof skeleton;
+};
+//# sourceMappingURL=helpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/nodes/helpers.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,254 @@
+// threejs-parity lane L6 (§5.6, SC-03 — P2): `helpers.*` debug glyphs composed
+// entirely over `lines.*` — every helper returns an `AuraLineNode` builder
+// (segment pairs, optionally vertex-coloured) drawn by the L6 line compiler.
+// three.js counterparts: AxesHelper, GridHelper, PolarGridHelper, Box3Helper,
+// ArrowHelper, CameraHelper, DirectionalLightHelper, SpotLightHelper,
+// PointLightHelper, SkeletonHelper.
+import { AuraNodeBuilder } from "./builder.js";
+import { segments } from "./lines.js";
+const push = (s, a, b, color) => {
+    s.positions.push(a, b);
+    s.colors.push(color, color);
+};
+const v = (x, y, z) => [x, y, z];
+function build(id, s, options = {}) {
+    if (s.positions.length === 0)
+        throw new Error(`helpers.${id} produced no segments`);
+    const b = segments({ positions: s.positions, colors: s.colors, name: options.name, visible: options.visible, position: options.position, rotation: options.rotation, scale: options.scale });
+    return b;
+}
+/** `helpers.axes({ size = 1 })` — X red, Y green, Z blue (three's `AxesHelper`). */
+export function axes(options = {}) {
+    const size = options.size ?? 1;
+    if (!Number.isFinite(size) || size <= 0)
+        throw new Error("helpers.axes size must be a positive finite number");
+    const s = { positions: [], colors: [] };
+    push(s, v(0, 0, 0), v(size, 0, 0), "#ff0000");
+    push(s, v(0, 0, 0), v(0, size, 0), "#00ff00");
+    push(s, v(0, 0, 0), v(0, 0, size), "#0000ff");
+    return build("axes", s, options);
+}
+/** `helpers.grid({ size = 10, divisions = 10, colorCenterLine?, colorGrid? })` — XZ grid (three's `GridHelper`). */
+export function grid(options = {}) {
+    const size = options.size ?? 10;
+    const divisions = Math.max(1, Math.floor(options.divisions ?? 10));
+    const center = options.colorCenterLine ?? "#444444";
+    const color = options.colorGrid ?? "#888888";
+    if (!Number.isFinite(size) || size <= 0)
+        throw new Error("helpers.grid size must be a positive finite number");
+    const half = size / 2;
+    const step = size / divisions;
+    const s = { positions: [], colors: [] };
+    for (let i = 0; i <= divisions; i += 1) {
+        const t = -half + i * step;
+        const c = i === Math.floor(divisions / 2) && divisions % 2 === 0 ? center : color;
+        push(s, v(t, 0, -half), v(t, 0, half), c);
+        push(s, v(-half, 0, t), v(half, 0, t), c);
+    }
+    return build("grid", s, options);
+}
+/** `helpers.polarGrid({ radius = 10, sectors = 16, rings = 5, division = 64 })` (three's `PolarGridHelper`). */
+export function polarGrid(options = {}) {
+    const radius = options.radius ?? 10;
+    const sectors = Math.max(1, Math.floor(options.sectors ?? 16));
+    const rings = Math.max(1, Math.floor(options.rings ?? 5));
+    const division = Math.max(8, Math.floor(options.division ?? 64));
+    const spoke = options.colorCenterLine ?? "#444444";
+    const ring = options.colorGrid ?? "#888888";
+    if (!Number.isFinite(radius) || radius <= 0)
+        throw new Error("helpers.polarGrid radius must be a positive finite number");
+    const s = { positions: [], colors: [] };
+    // Concentric rings (segment pairs around each circle, closing included).
+    for (let r = 1; r <= rings; r += 1) {
+        const rr = (radius * r) / rings;
+        for (let i = 0; i < division; i += 1) {
+            const a0 = (i / division) * Math.PI * 2;
+            const a1 = ((i + 1) / division) * Math.PI * 2;
+            push(s, v(Math.cos(a0) * rr, 0, Math.sin(a0) * rr), v(Math.cos(a1) * rr, 0, Math.sin(a1) * rr), ring);
+        }
+    }
+    // Radial spokes.
+    for (let i = 0; i < sectors; i += 1) {
+        const a = (i / sectors) * Math.PI * 2;
+        push(s, v(0, 0, 0), v(Math.cos(a) * radius, 0, Math.sin(a) * radius), spoke);
+    }
+    return build("polarGrid", s, options);
+}
+/** `helpers.box3({ min, max })` — the 12 edges of an AABB (three's `Box3Helper`). */
+export function box3(options) {
+    const [ax, ay, az] = options.min;
+    const [bx, by, bz] = options.max;
+    const color = options.color ?? "#ffff00";
+    const s = { positions: [], colors: [] };
+    const c = [
+        v(ax, ay, az), v(bx, ay, az), v(bx, ay, bz), v(ax, ay, bz),
+        v(ax, by, az), v(bx, by, az), v(bx, by, bz), v(ax, by, bz)
+    ];
+    const edges = [[0, 1], [1, 2], [2, 3], [3, 0], [4, 5], [5, 6], [6, 7], [7, 4], [0, 4], [1, 5], [2, 6], [3, 7]];
+    for (const [a, b] of edges)
+        push(s, c[a], c[b], color);
+    return build("box3", s, options);
+}
+/** `helpers.box({ size = 1, center = [0,0,0] })` — centred AABB convenience over `box3` (three's `BoxHelper` static form). */
+export function box(options = {}) {
+    const center = options.center ?? [0, 0, 0];
+    const size = typeof options.size === "number" ? [options.size, options.size, options.size] : options.size ?? [1, 1, 1];
+    return box3({
+        ...options,
+        min: [center[0] - size[0] / 2, center[1] - size[1] / 2, center[2] - size[2] / 2],
+        max: [center[0] + size[0] / 2, center[1] + size[1] / 2, center[2] + size[2] / 2]
+    });
+}
+/** `helpers.arrow({ dir, origin?, length?, headLength?, headWidth?, color? })` (three's `ArrowHelper`, line-only). */
+export function arrow(options) {
+    const dir = normalize3(options.dir);
+    if (dir === null)
+        throw new Error("helpers.arrow dir must be a non-zero finite vec3");
+    const origin = options.origin ?? [0, 0, 0];
+    const length = options.length ?? 1;
+    const headLength = Math.min(options.headLength ?? length * 0.2, length * 0.999);
+    const headWidth = options.headWidth ?? headLength * 0.5;
+    const color = options.color ?? "#ffff00";
+    const tip = [origin[0] + dir[0] * length, origin[1] + dir[1] * length, origin[2] + dir[2] * length];
+    // Two perpendicular vectors spanning the plane ⊥ dir for the V-fins.
+    const up = Math.abs(dir[1]) < 0.95 ? v(0, 1, 0) : v(1, 0, 0);
+    const u = normalize3(cross3(dir, up));
+    const w = normalize3(cross3(dir, u));
+    const base = [tip[0] - dir[0] * headLength, tip[1] - dir[1] * headLength, tip[2] - dir[2] * headLength];
+    const s = { positions: [], colors: [] };
+    push(s, origin, tip, color);
+    for (const axis of [u, w]) {
+        for (const sign of [-1, 1]) {
+            push(s, tip, [base[0] + axis[0] * headWidth * sign, base[1] + axis[1] * headWidth * sign, base[2] + axis[2] * headWidth * sign], color);
+        }
+    }
+    return build("arrow", s, options);
+}
+/** `helpers.camera({ position?, rotation?, fov?, aspect?, near?, far? })` — frustum lines (three's `CameraHelper`, static pose form). */
+export function camera(options = {}) {
+    const fov = (options.fov ?? 50) * (Math.PI / 180);
+    const aspect = options.aspect ?? 1;
+    const near = options.near ?? 1;
+    const far = options.far ?? 100;
+    const color = options.color ?? "#ffffff";
+    if (!(far > near) || !(near > 0))
+        throw new Error("helpers.camera requires 0 < near < far");
+    const nh = Math.tan(fov / 2) * near;
+    const nw = nh * aspect;
+    const fh = Math.tan(fov / 2) * far;
+    const fw = fh * aspect;
+    const s = { positions: [], colors: [] };
+    // near rect (z = −near, camera looks down −Z like three's convention)
+    const nr = [v(-nw, -nh, -near), v(nw, -nh, -near), v(nw, nh, -near), v(-nw, nh, -near)];
+    const fr = [v(-fw, -fh, -far), v(fw, -fh, -far), v(fw, fh, -far), v(-fw, fh, -far)];
+    for (let i = 0; i < 4; i += 1) {
+        push(s, nr[i], nr[(i + 1) % 4], color);
+        push(s, fr[i], fr[(i + 1) % 4], color);
+        push(s, nr[i], fr[i], color);
+        push(s, v(0, 0, 0), nr[i], color); // eye → near corners (three's camera glyph)
+    }
+    return build("camera", s, options);
+}
+/** `helpers.directionalLight({ position?, target?, size?, color? })` — plane glyph + rays (three's `DirectionalLightHelper`). */
+export function directionalLight(options = {}) {
+    const size = options.size ?? 1;
+    const color = options.color ?? "#ffffff";
+    const target = options.target ?? [0, 0, 0];
+    const s = { positions: [], colors: [] };
+    const h = size / 2;
+    const quad = [v(-h, h, 0), v(h, h, 0), v(h, -h, 0), v(-h, -h, 0)];
+    for (let i = 0; i < 4; i += 1)
+        push(s, quad[i], quad[(i + 1) % 4], color);
+    // Rays toward the target (helper convention: glyph sits at position, −Z faces target).
+    for (const off of [v(-h, h, 0), v(h, h, 0), v(0, 0, 0), v(-h, -h, 0), v(h, -h, 0)]) {
+        push(s, off, [off[0], off[1], off[2] - size], color);
+    }
+    void target; // aim comes from the node rotation (lookAt the target on the builder)
+    return build("directionalLight", s, options);
+}
+/** `helpers.pointLight({ sphereSize?, distance?, color? })` — wireframe bulb rings (three's `PointLightHelper`). */
+export function pointLight(options = {}) {
+    const r = options.sphereSize ?? 0.5;
+    const color = options.color ?? "#ffffff";
+    if (!Number.isFinite(r) || r <= 0)
+        throw new Error("helpers.pointLight sphereSize must be a positive finite number");
+    const s = { positions: [], colors: [] };
+    const seg = 24;
+    for (const project of [
+        (a) => v(Math.cos(a) * r, Math.sin(a) * r, 0),
+        (a) => v(Math.cos(a) * r, 0, Math.sin(a) * r),
+        (a) => v(0, Math.cos(a) * r, Math.sin(a) * r)
+    ]) {
+        for (let i = 0; i < seg; i += 1) {
+            push(s, project((i / seg) * Math.PI * 2), project(((i + 1) / seg) * Math.PI * 2), color);
+        }
+    }
+    return build("pointLight", s, options);
+}
+/** `helpers.spotLight({ angle?, distance?, color? })` — cone wireframe (three's `SpotLightHelper`). */
+export function spotLight(options = {}) {
+    const angle = options.angle ?? Math.PI / 3;
+    const distance = options.distance ?? 10;
+    const color = options.color ?? "#ffffff";
+    if (!(angle > 0 && angle < Math.PI / 2))
+        throw new Error("helpers.spotLight angle must be in (0, π/2)");
+    if (!Number.isFinite(distance) || distance <= 0)
+        throw new Error("helpers.spotLight distance must be a positive finite number");
+    const r = Math.tan(angle) * distance;
+    const s = { positions: [], colors: [] };
+    const seg = 24;
+    for (let i = 0; i < seg; i += 1) {
+        const a0 = (i / seg) * Math.PI * 2;
+        const a1 = ((i + 1) / seg) * Math.PI * 2;
+        push(s, v(Math.cos(a0) * r, Math.sin(a0) * r, -distance), v(Math.cos(a1) * r, Math.sin(a1) * r, -distance), color);
+    }
+    for (const a of [0, Math.PI / 2, Math.PI, (3 * Math.PI) / 2]) {
+        push(s, v(0, 0, 0), v(Math.cos(a) * r, Math.sin(a) * r, -distance), color);
+    }
+    return build("spotLight", s, options);
+}
+/**
+ * `helpers.skeleton({ positions, parents? })` — bone lines joint→parent
+ * (three's `SkeletonHelper` static form). `parents[i]` is the parent joint
+ * index, `-1` for roots; absent → a sequential chain.
+ */
+export function skeleton(options) {
+    const { positions, parents } = options;
+    const color = options.color ?? "#00e5ff";
+    if (positions.length < 2)
+        throw new Error("helpers.skeleton requires at least two joints");
+    const s = { positions: [], colors: [] };
+    for (let i = 0; i < positions.length; i += 1) {
+        const parent = parents ? parents[i] : i - 1;
+        if (parent === undefined || parent < 0 || parent === i)
+            continue;
+        if (parent >= positions.length)
+            throw new Error(`helpers.skeleton parents[${i}] out of range`);
+        push(s, positions[parent], positions[i], color);
+    }
+    return build("skeleton", s, options);
+}
+function normalize3(a) {
+    const l = Math.hypot(a[0], a[1], a[2]);
+    if (!Number.isFinite(l) || l <= 0)
+        return null;
+    return [a[0] / l, a[1] / l, a[2] / l];
+}
+function cross3(a, b) {
+    return [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+}
+/** `helpers.*` namespace (SC-03): every glyph is a real line-segment node. */
+export const helpers = {
+    axes,
+    grid,
+    polarGrid,
+    box,
+    box3,
+    arrow,
+    camera,
+    directionalLight,
+    spotLight,
+    pointLight,
+    skeleton
+};
+//# sourceMappingURL=helpers.js.map

package/dist/engine/agent-api/nodes/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/nodes/helpers.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,87 @@
+/**
+ * SG-01 / parity-L5 — `instances.mesh(geometry, material, count)`: three.js
+ * `InstancedMesh` parity over the L5 dense-instance store.
+ *
+ * The node is `kind:"batched"` with `instanced: true`: all `count` slots are
+ * alive at creation and `count` acts as the draw bound, matching three.js
+ * `InstancedMesh.count`. `setMatrixAt`/`setColorAt` write the same flat
+ * `matrices`/`colors` arrays the renderer uploads through the C-07
+ * `InstanceBufferLike` contract — writes are the real GPU path (L5-01), not
+ * a decompose-to-spec fallback. `computeBoundingSphere` unions the geometry
+ * bounds transformed by every live instance matrix.
+ */
+import { AuraNodeBuilder } from "./builder.js";
+import { BatchedMeshState, type AuraBatchedGeometryInput } from "./batchedState.js";
+import type { AuraBatchedNode, AuraColor, AuraMaterialSpec } from "./types.js";
+/** `instances.mesh` geometry input: pooled `Geometry`, builtin name, or custom spec. */
+export type AuraInstancedGeometryInput = AuraBatchedGeometryInput;
+export interface AuraInstancedMeshBoundingSphere {
+    readonly center: readonly [number, number, number];
+    readonly radius: number;
+}
+/** Buffer view matching three.js `mesh.instanceMatrix`/`instanceColor`. */
+export interface AuraInstancedBufferView {
+    /** Backing dense store — mutate through `setMatrixAt`/`setColorAt` or flip `needsUpdate`. */
+    readonly array: Float32Array;
+    needsUpdate: boolean;
+}
+/**
+ * `instances.mesh` handle — an `AuraNodeBuilder` (scene-addable) plus the
+ * three.js `InstancedMesh` API. The builder's spread-clone keeps the same
+ * `batchedId`, so chained handles share one dense state.
+ */
+export declare class AuraInstancedMeshHandle extends AuraNodeBuilder<AuraBatchedNode> {
+    readonly state: BatchedMeshState;
+    readonly instanceMatrix: AuraInstancedBufferView;
+    readonly instanceColor: AuraInstancedBufferView;
+    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;
+    }>;
+    /** The one registered geometryId (always 0 for instances.mesh). */
+    get geometryId(): number;
+    /** three.js `InstancedMesh.count` — draw bound ≤ capacity, get/set. */
+    get count(): number;
+    set count(value: number);
+    /** Allocated capacity (constructor `count`); `count` may draw fewer. */
+    get capacity(): 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;
+    /** three.js-style explicit flush — uploads are per-frame; bumps the store version. */
+    set needsUpdate(_v: boolean);
+    /** Union bounding sphere: geometry bounds transformed by each live instance matrix. */
+    computeBoundingSphere(): AuraInstancedMeshBoundingSphere;
+    get boundingSphere(): AuraInstancedMeshBoundingSphere;
+    dispose(): void;
+}
+/**
+ * `instances.mesh(geometry, material, count)` — three.js `new InstancedMesh`
+ * parity: `count` instances of one geometry under one material.
+ */
+export declare function instancedMesh(geometry: AuraBatchedGeometryInput, material: AuraMaterialSpec | undefined, count: number): AuraInstancedMeshHandle;
+//# sourceMappingURL=instancedMesh.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"instancedMesh.d.ts","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/nodes/instancedMesh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EACL,gBAAgB,EAKhB,KAAK,wBAAwB,EAC9B,MAAM,mBAAmB,CAAC;AAG3B,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,gBAAgB,EAAqB,MAAM,YAAY,CAAC;AAElG,wFAAwF;AACxF,MAAM,MAAM,0BAA0B,GAAG,wBAAwB,CAAC;AAElE,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,2EAA2E;AAC3E,MAAM,WAAW,uBAAuB;IACtC,6FAA6F;IAC7F,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,eAAe,CAAC,eAAe,CAAC;IAC3E,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,uBAAuB,CAAC;IACjD,QAAQ,CAAC,aAAa,EAAE,uBAAuB,CAAC;gBAEpC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,gBAAgB;IAgB1D,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,mEAAmE;IACnE,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,uEAAuE;IACvE,IAAI,KAAK,IAAI,MAAM,CAElB;IACD,IAAI,KAAK,CAAC,KAAK,EAAE,MAAM,EAEtB;IAED,wEAAwE;IACxE,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,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,sFAAsF;IACtF,IAAI,WAAW,CAAC,EAAE,EAAE,OAAO,EAE1B;IAED,uFAAuF;IACvF,qBAAqB,IAAI,+BAA+B;IAaxD,IAAI,cAAc,IAAI,+BAA+B,CAEpD;IAED,OAAO,IAAI,IAAI;CAGhB;AAID;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,wBAAwB,EAClC,QAAQ,EAAE,gBAAgB,GAAG,SAAS,EACtC,KAAK,EAAE,MAAM,GACZ,uBAAuB,CAazB"}

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

@@ -0,0 +1,156 @@
+/**
+ * SG-01 / parity-L5 — `instances.mesh(geometry, material, count)`: three.js
+ * `InstancedMesh` parity over the L5 dense-instance store.
+ *
+ * The node is `kind:"batched"` with `instanced: true`: all `count` slots are
+ * alive at creation and `count` acts as the draw bound, matching three.js
+ * `InstancedMesh.count`. `setMatrixAt`/`setColorAt` write the same flat
+ * `matrices`/`colors` arrays the renderer uploads through the C-07
+ * `InstanceBufferLike` contract — writes are the real GPU path (L5-01), not
+ * a decompose-to-spec fallback. `computeBoundingSphere` unions the geometry
+ * bounds transformed by every live instance matrix.
+ */
+import { AuraNodeBuilder } from "./builder.js";
+import { BatchedMeshState, registerBatchedState, registerBatchedColorConverter, registerBatchedGeometryResolver, registerInstancedMeshFactory } from "./batchedState.js";
+import { createProductionPrimitiveGeometry } from "../compiler/primitives.js";
+import { colorToRgba } from "../colorUtils.js";
+/**
+ * `instances.mesh` handle — an `AuraNodeBuilder` (scene-addable) plus the
+ * three.js `InstancedMesh` API. The builder's spread-clone keeps the same
+ * `batchedId`, so chained handles share one dense state.
+ */
+export class AuraInstancedMeshHandle extends AuraNodeBuilder {
+    state;
+    instanceMatrix;
+    instanceColor;
+    constructor(node, state) {
+        super(node);
+        this.state = state;
+        const self = this;
+        this.instanceMatrix = {
+            array: state.matrices,
+            set needsUpdate(_v) { self.state.version += 1; },
+            get needsUpdate() { return false; }
+        };
+        this.instanceColor = {
+            array: state.colors,
+            set needsUpdate(_v) { self.state.version += 1; },
+            get needsUpdate() { return false; }
+        };
+    }
+    rewrap(builder) {
+        return new AuraInstancedMeshHandle(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));
+    }
+    /** The one registered geometryId (always 0 for instances.mesh). */
+    get geometryId() {
+        return 0;
+    }
+    /** three.js `InstancedMesh.count` — draw bound ≤ capacity, get/set. */
+    get count() {
+        return this.state.count;
+    }
+    set count(value) {
+        this.state.setCount(value);
+    }
+    /** Allocated capacity (constructor `count`); `count` may draw fewer. */
+    get capacity() {
+        return this.state.capacity;
+    }
+    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;
+    }
+    /** three.js-style explicit flush — uploads are per-frame; bumps the store version. */
+    set needsUpdate(_v) {
+        this.state.version += 1;
+    }
+    /** Union bounding sphere: geometry bounds transformed by each live instance matrix. */
+    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
+        ];
+        return {
+            center,
+            radius: Math.hypot(box.max[0] - box.min[0], box.max[1] - box.min[1], box.max[2] - box.min[2]) / 2
+        };
+    }
+    get boundingSphere() {
+        return this.computeBoundingSphere();
+    }
+    dispose() {
+        this.state.dispose();
+    }
+}
+let nextInstancedId = 1;
+/**
+ * `instances.mesh(geometry, material, count)` — three.js `new InstancedMesh`
+ * parity: `count` instances of one geometry under one material.
+ */
+export function instancedMesh(geometry, material, count) {
+    const id = `instanced-${nextInstancedId++}`;
+    const state = new BatchedMeshState({ id, capacity: count, instanced: true });
+    state.addGeometry(geometry);
+    const node = {
+        kind: "batched",
+        batchedId: id,
+        maxInstances: count,
+        multiDraw: "instanced",
+        ...(material !== undefined ? { material } : {})
+    };
+    registerBatchedState(state);
+    return new AuraInstancedMeshHandle(node, state);
+}
+// Registered into the batchedState leaf so `instances.mesh` can reach the
+// factory without `instances.ts` statically importing this module — that edge
+// closed the builder→physics→primitives→instances→instancedMesh→builder
+// eval cycle (see batchedState.ts header). The resolver registration mirrors
+// batched.ts so deep imports of this module still resolve geometry inputs.
+registerInstancedMeshFactory(instancedMesh);
+registerBatchedColorConverter(colorToRgba);
+registerBatchedGeometryResolver((input) => {
+    if (typeof input === "string") {
+        return createProductionPrimitiveGeometry({ kind: "primitive", primitive: input });
+    }
+    return createProductionPrimitiveGeometry({ kind: "primitive", primitive: "custom", geometry: input });
+});
+//# sourceMappingURL=instancedMesh.js.map