@aura3d/engine 4.0.3 → 4.0.4

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

@@ -1,16 +1,62 @@
 import type { SdfTextStyle } from "../../rendering/index.js";
+import type { AuraColor } from "./nodes/types.js";
 export type AuraRootVec3 = readonly [number, number, number];
+/**
+ * SG-05 (threejs-parity L2): vertex data accepts the legacy tuple layout or a
+ * flat packed array (Float32Array or plain number[]). Tuple input keeps the
+ * pre-L2 `defineAuraCustomGeometry` shape bit-for-bit; flat input is the
+ * typed-array `geometry.dynamic` / `handle.setGeometry` path.
+ */
+export type AuraVec3Attribute = readonly AuraRootVec3[] | Float32Array | readonly number[];
+export type AuraVec2Attribute = readonly (readonly [number, number])[] | Float32Array | readonly number[];
+export type AuraIndexAttribute = readonly number[] | Uint16Array | Uint32Array;
+export interface AuraGeometryGroupSpec {
+    readonly start: number;
+    readonly count: number;
+    readonly materialIndex?: number;
+}
+export interface AuraGeometryDrawRangeSpec {
+    readonly start: number;
+    readonly count: number;
+}
+export interface AuraGeometryMorphTargetSpec {
+    readonly name?: string;
+    readonly positions: Float32Array | readonly number[];
+}
+/**
+ * R-23: one author-named per-vertex attribute (three's `setAttribute(name, new
+ * BufferAttribute(array, itemSize))`). `data.length` must equal
+ * `vertexCount * itemSize`; the vertex shader reads it as `in <type> <name>;`.
+ */
+export interface AuraCustomVertexAttributeSpec {
+    readonly itemSize: 1 | 2 | 3 | 4;
+    readonly data: Float32Array | readonly number[];
+}
 export interface AuraCustomGeometrySpec {
     readonly kind: "aura-custom-geometry";
-    readonly positions: readonly AuraRootVec3[];
-    readonly normals?: readonly AuraRootVec3[];
+    readonly positions: AuraVec3Attribute;
+    readonly normals?: AuraVec3Attribute;
     /** Optional UVs (one per position) — the decal batch path samples pages with them. */
-    readonly uvs?: readonly (readonly [number, number])[];
-    readonly indices: readonly number[];
+    readonly uvs?: AuraVec2Attribute;
+    /** SG-05: per-vertex RGBA colors (Float32Array or `[r,g,b,a]` tuples/`AuraColor` list). */
+    readonly colors?: Float32Array | readonly number[] | readonly AuraColor[];
+    readonly indices: AuraIndexAttribute;
+    /** R-23: author-named per-vertex attributes (max 11), bound by name in `material.custom` GLSL. */
+    readonly attributes?: Readonly<Record<string, AuraCustomVertexAttributeSpec>>;
     readonly bounds?: {
         readonly min: AuraRootVec3;
         readonly max: AuraRootVec3;
     };
+    /** SG-05: three's geometry.groups — material-index index ranges. */
+    readonly groups?: readonly AuraGeometryGroupSpec[];
+    /** SG-05: three's setDrawRange — only this index range draws. */
+    readonly drawRange?: AuraGeometryDrawRangeSpec;
+    /** SG-05: authored morph-target position arrays (absolute or delta per the morph pipeline). */
+    readonly morphTargets?: readonly AuraGeometryMorphTargetSpec[];
+    /** SG-05: `"lines"` produces line-segment topology (geometry.edges/wireframe). R-23: `"points"` draws one point per vertex (the vertex shader sets gl_PointSize). Default `"triangles"`. */
+    readonly topology?: "triangles" | "lines" | "points";
+    /** SG-05: set by `geometry.dynamic` — flags the spec as a `handle.setGeometry` target. */
+    readonly dynamic?: boolean;
 }
 export interface AuraText3DOptions {
     readonly size?: number;
@@ -48,6 +94,80 @@ export interface AuraRootLodSelection {
 /** Select a distance LOD while preserving the previous level inside a symmetric hysteresis band. */
 export declare function selectAuraRootLodLevel(distance: number, levels: readonly AuraRootLodThreshold[], previousLevelIndex?: number, hysteresis?: number): AuraRootLodSelection;
 export declare function defineAuraCustomGeometry(spec: Omit<AuraCustomGeometrySpec, "kind">): AuraCustomGeometrySpec;
+export interface NormalizedCustomVertexAttribute {
+    readonly name: string;
+    readonly itemSize: 1 | 2 | 3 | 4;
+    readonly data: Float32Array;
+}
+export declare const MAX_CUSTOM_VERTEX_ATTRIBUTES = 11;
+export declare function assertCustomAttributeName(name: string): void;
+/** R-23: validate and flatten `spec.attributes`; entries come back sorted by name (the stable location order). */
+export declare function normalizeCustomVertexAttributes(attributes: Readonly<Record<string, AuraCustomVertexAttributeSpec>> | undefined, vertexCount: number): readonly NormalizedCustomVertexAttribute[];
+export interface NormalizedGeometryAttributes {
+    readonly positions: Float32Array;
+    readonly vertexCount: number;
+    readonly custom: readonly NormalizedCustomVertexAttribute[];
+    readonly normals?: Float32Array;
+    readonly uvs?: Float32Array;
+    readonly colors?: Float32Array;
+    readonly indices?: Uint16Array | Uint32Array;
+}
+/** True when `value` is a flat packed component array rather than a tuple list. */
+export declare function isFlatAttributeArray(value: unknown): value is Float32Array | readonly number[];
+/** Normalize every SG-05 attribute shape into flat Float32/Uint arrays for the buffer path. */
+export declare function normalizeGeometryAttributes(spec: {
+    readonly positions: AuraVec3Attribute;
+    readonly normals?: AuraVec3Attribute;
+    readonly uvs?: AuraVec2Attribute;
+    readonly colors?: Float32Array | readonly number[] | readonly AuraColor[];
+    readonly indices?: AuraIndexAttribute;
+    readonly attributes?: Readonly<Record<string, AuraCustomVertexAttributeSpec>>;
+}): NormalizedGeometryAttributes;
+/** SG-05: `geometry.dynamic(spec)` — validate and tag the spec as a runtime-mutable target. */
+export declare function defineAuraDynamicGeometry(spec: {
+    readonly positions: AuraVec3Attribute;
+    readonly normals?: AuraVec3Attribute;
+    readonly uvs?: AuraVec2Attribute;
+    readonly colors?: Float32Array | readonly number[] | readonly AuraColor[];
+    readonly indices?: AuraIndexAttribute;
+    readonly attributes?: Readonly<Record<string, AuraCustomVertexAttributeSpec>>;
+    readonly topology?: "triangles" | "points";
+    readonly groups?: readonly AuraGeometryGroupSpec[];
+    readonly drawRange?: AuraGeometryDrawRangeSpec;
+    readonly morphTargets?: readonly AuraGeometryMorphTargetSpec[];
+    readonly bounds?: {
+        readonly min: AuraRootVec3;
+        readonly max: AuraRootVec3;
+    };
+}): AuraCustomGeometrySpec;
+/** three's `BufferGeometry.computeVertexNormals` over an Aura spec — returns a fresh flat normal array. */
+export declare function computeAuraGeometryNormals(spec: {
+    readonly positions: AuraVec3Attribute;
+    readonly indices?: AuraIndexAttribute;
+}): Float32Array;
+/** three's `BufferGeometry.computeBoundingBox` — finite min/max over positions. */
+export declare function computeAuraGeometryBounds(spec: {
+    readonly positions: AuraVec3Attribute;
+}): {
+    readonly min: AuraRootVec3;
+    readonly max: AuraRootVec3;
+};
+/**
+ * three's `BufferGeometry.applyMatrix4` — positions take the full column-major
+ * mat4; normals take the upper 3x3 (the three `normalMatrix` inverse-transpose
+ * reduces to the same rotation/scale here for rigid+scale matrices, matching
+ * the engine mergeGeometries convention) and are renormalized.
+ */
+export declare function applyAuraGeometryMatrix4(spec: AuraCustomGeometrySpec, matrix: readonly number[]): AuraCustomGeometrySpec;
+/** three's `BufferGeometryUtils.toNonIndexed` — one vertex per index, in index order. */
+export declare function auraGeometryToNonIndexed(spec: AuraCustomGeometrySpec): AuraCustomGeometrySpec;
+/**
+ * three's `BufferGeometryUtils.mergeGeometries` — concatenates specs (no
+ * transform baking; the R/MeshConsolidation merge bakes model matrices for
+ * the static path, while the authored merge keeps authored coordinates).
+ * Index-bearing specs share the index stream; attribute sets must match.
+ */
+export declare function mergeAuraGeometries(specs: readonly AuraCustomGeometrySpec[]): AuraCustomGeometrySpec;
 /** Build depth-bearing triangle geometry; this is not a DOM label or canvas texture. */
 export declare function createAuraText3DGeometry(text: string, options?: AuraText3DOptions): AuraText3DGeometry;
 //# sourceMappingURL=RootGeometry.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"RootGeometry.d.ts","sourceRoot":"","sources":["../../../../../packages/engine/src/agent-api/RootGeometry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGtD,MAAM,MAAM,YAAY,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAE7D,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,SAAS,YAAY,EAAE,CAAC;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,sFAAsF;IACtF,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;IACtD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAA;KAAE,CAAC;CAC9E;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,qBAAqB,EAAE,SAAS,MAAM,EAAE,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE,4BAA4B,GAAG,gBAAgB,CAAC;IACjE,yIAAyI;IACzI,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,KAAK,CAAC;IAC3C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,YAAY,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;CACjD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,GAAG,mBAAmB,GAAG,kBAAkB,GAAG,iBAAiB,CAAC;CACpG;AAED,oGAAoG;AACpG,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,SAAS,oBAAoB,EAAE,EACvC,kBAAkB,CAAC,EAAE,MAAM,EAC3B,UAAU,SAAI,GACb,oBAAoB,CAuBtB;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,IAAI,CAAC,sBAAsB,EAAE,MAAM,CAAC,GAAG,sBAAsB,CAuB3G;AAED,wFAAwF;AACxF,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,kBAAkB,CA+B1G"}
+{"version":3,"file":"RootGeometry.d.ts","sourceRoot":"","sources":["../../../../../packages/engine/src/agent-api/RootGeometry.ts"],"names":[],"mappings":"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"}

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

@@ -32,21 +32,20 @@ export function selectAuraRootLodLevel(distance, levels, previousLevelIndex, hys
     return { levelIndex: selected, reason: "hysteresis-hold" };
 }
 export function defineAuraCustomGeometry(spec) {
-    if (spec.positions.length < 3)
-        throw new Error("Aura3D custom geometry requires at least three positions.");
-    if (spec.indices.length < 3 || spec.indices.length % 3 !== 0)
-        throw new Error("Aura3D custom triangle geometry indices must contain complete triangles.");
-    for (const [index, position] of spec.positions.entries())
-        validateVec3(position, `position ${index}`);
-    for (const [index, value] of spec.indices.entries()) {
-        if (!Number.isInteger(value) || value < 0 || value >= spec.positions.length)
-            throw new Error(`Aura3D custom geometry index ${index} is outside the position buffer.`);
-    }
-    if (spec.normals && spec.normals.length !== spec.positions.length)
-        throw new Error("Aura3D custom geometry normals must match the position count.");
-    spec.normals?.forEach((normal, index) => validateVec3(normal, `normal ${index}`));
-    if (spec.uvs && spec.uvs.length !== spec.positions.length)
-        throw new Error("Aura3D custom geometry uvs must match the position count.");
+    const normalized = normalizeGeometryAttributes(spec);
+    const lines = spec.topology === "lines";
+    const points = spec.topology === "points";
+    if (points) {
+        if (normalized.vertexCount < 1)
+            throw new Error("Aura3D custom point geometry requires at least one position.");
+    }
+    else {
+        if (normalized.vertexCount < (lines ? 2 : 3))
+            throw new Error(`Aura3D custom ${lines ? "line" : "triangle"} geometry requires at least ${lines ? "two" : "three"} positions.`);
+        const indexCount = normalized.indices?.length ?? normalized.vertexCount;
+        if (lines ? indexCount % 2 !== 0 : indexCount % 3 !== 0)
+            throw new Error(`Aura3D custom ${lines ? "line" : "triangle"} geometry indices must contain complete ${lines ? "segments" : "triangles"}.`);
+    }
     if (spec.bounds) {
         validateVec3(spec.bounds.min, "bounds min");
         validateVec3(spec.bounds.max, "bounds max");
@@ -56,13 +55,421 @@ export function defineAuraCustomGeometry(spec) {
     }
     return {
         kind: "aura-custom-geometry",
-        positions: spec.positions.map((value) => [...value]),
-        ...(spec.normals ? { normals: spec.normals.map((value) => [...value]) } : {}),
-        ...(spec.uvs ? { uvs: spec.uvs.map((value) => [...value]) } : {}),
-        indices: [...spec.indices],
+        positions: spec.positions,
+        ...(spec.normals ? { normals: spec.normals } : {}),
+        ...(spec.uvs ? { uvs: spec.uvs } : {}),
+        ...(spec.colors ? { colors: spec.colors } : {}),
+        indices: spec.indices,
+        ...(normalized.custom.length > 0 ? { attributes: customAttributesRecord(normalized.custom) } : {}),
+        ...(spec.groups ? { groups: [...spec.groups] } : {}),
+        ...(spec.drawRange ? { drawRange: { ...spec.drawRange } } : {}),
+        ...(spec.morphTargets ? { morphTargets: spec.morphTargets.map((target) => ({ ...target })) } : {}),
+        ...(spec.topology ? { topology: spec.topology } : {}),
+        ...(spec.dynamic === true ? { dynamic: true } : {}),
         ...(spec.bounds ? { bounds: { min: [...spec.bounds.min], max: [...spec.bounds.max] } } : {})
     };
 }
+function customAttributesRecord(custom) {
+    return Object.fromEntries(custom.map((entry) => [entry.name, { itemSize: entry.itemSize, data: entry.data }]));
+}
+/** R-23: names a custom attribute may not take — engine semantics, their updateAttribute aliases, and the `a_` engine prefix. */
+const RESERVED_CUSTOM_ATTRIBUTE_NAMES = new Set([
+    "position", "positions", "normal", "normals", "uv", "uv0", "uvs", "uv1", "color", "colors", "tangent", "tangents",
+    "joints", "weights", "joints1", "weights1", "lineStart", "lineEnd", "lineCorner", "lineDistance", "index",
+    "instanceMatrix", "instanceColor"
+]);
+export const MAX_CUSTOM_VERTEX_ATTRIBUTES = 11;
+export function assertCustomAttributeName(name) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+        throw new Error(`Aura3D custom vertex attribute name "${name}" must be a GLSL identifier ([A-Za-z_][A-Za-z0-9_]*).`);
+    if (name.startsWith("gl_") || name.includes("__"))
+        throw new Error(`Aura3D custom vertex attribute name "${name}" is reserved by GLSL (gl_ prefix or double underscore).`);
+    if (name.startsWith("a_") || name.startsWith("u_"))
+        throw new Error(`Aura3D custom vertex attribute name "${name}" uses a prefix reserved for engine attributes/uniforms (a_, u_).`);
+    if (RESERVED_CUSTOM_ATTRIBUTE_NAMES.has(name))
+        throw new Error(`Aura3D custom vertex attribute name "${name}" collides with a built-in vertex semantic.`);
+}
+/** R-23: validate and flatten `spec.attributes`; entries come back sorted by name (the stable location order). */
+export function normalizeCustomVertexAttributes(attributes, vertexCount) {
+    if (attributes === undefined)
+        return [];
+    const names = Object.keys(attributes).sort();
+    if (names.length > MAX_CUSTOM_VERTEX_ATTRIBUTES) {
+        throw new Error(`Aura3D geometry supports at most ${MAX_CUSTOM_VERTEX_ATTRIBUTES} custom vertex attributes, got ${names.length}.`);
+    }
+    return names.map((name) => {
+        assertCustomAttributeName(name);
+        const entry = attributes[name];
+        const itemSize = entry?.itemSize;
+        if (itemSize !== 1 && itemSize !== 2 && itemSize !== 3 && itemSize !== 4)
+            throw new Error(`Aura3D custom vertex attribute "${name}" itemSize must be 1, 2, 3 or 4.`);
+        const raw = entry.data;
+        if (!(raw instanceof Float32Array) && !Array.isArray(raw))
+            throw new Error(`Aura3D custom vertex attribute "${name}" data must be a Float32Array or number[].`);
+        const data = raw instanceof Float32Array ? raw : Float32Array.from(raw);
+        if (data.length !== vertexCount * itemSize) {
+            throw new Error(`Aura3D custom vertex attribute "${name}" has ${data.length} values; expected ${vertexCount} vertices x ${itemSize} = ${vertexCount * itemSize}.`);
+        }
+        for (let i = 0; i < data.length; i += 1) {
+            if (!Number.isFinite(data[i]))
+                throw new Error(`Aura3D custom vertex attribute "${name}" value ${i} must be finite.`);
+        }
+        return { name, itemSize, data };
+    });
+}
+/** True when `value` is a flat packed component array rather than a tuple list. */
+export function isFlatAttributeArray(value) {
+    return value instanceof Float32Array || (Array.isArray(value) && (value.length === 0 || typeof value[0] === "number"));
+}
+function readVec3Attribute(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (isFlatAttributeArray(value)) {
+        const flat = value instanceof Float32Array ? value : Float32Array.from(value);
+        if (flat.length % 3 !== 0)
+            throw new Error(`Aura3D geometry ${label} array length must be a multiple of 3.`);
+        return flat;
+    }
+    const flat = new Float32Array(value.length * 3);
+    value.forEach((tuple, index) => {
+        validateVec3(tuple, `${label} ${index}`);
+        flat[index * 3] = tuple[0];
+        flat[index * 3 + 1] = tuple[1];
+        flat[index * 3 + 2] = tuple[2];
+    });
+    return flat;
+}
+function readVec2Attribute(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (isFlatAttributeArray(value)) {
+        const flat = value instanceof Float32Array ? value : Float32Array.from(value);
+        if (flat.length % 2 !== 0)
+            throw new Error(`Aura3D geometry ${label} array length must be a multiple of 2.`);
+        return flat;
+    }
+    const flat = new Float32Array(value.length * 2);
+    value.forEach((tuple, index) => {
+        if (tuple.length !== 2 || !Number.isFinite(tuple[0]) || !Number.isFinite(tuple[1]))
+            throw new Error(`Aura3D geometry ${label} ${index} must be a finite vec2.`);
+        flat[index * 2] = tuple[0];
+        flat[index * 2 + 1] = tuple[1];
+    });
+    return flat;
+}
+/** Normalize every SG-05 attribute shape into flat Float32/Uint arrays for the buffer path. */
+export function normalizeGeometryAttributes(spec) {
+    const positions = readVec3Attribute(spec.positions, "positions");
+    if (!positions)
+        throw new Error("Aura3D geometry requires positions.");
+    const vertexCount = positions.length / 3;
+    const normals = readVec3Attribute(spec.normals, "normals");
+    if (normals && normals.length !== positions.length)
+        throw new Error("Aura3D geometry normals must match the position count.");
+    const uvs = readVec2Attribute(spec.uvs, "uvs");
+    if (uvs && uvs.length !== vertexCount * 2)
+        throw new Error("Aura3D geometry uvs must match the position count.");
+    let colors;
+    if (spec.colors !== undefined) {
+        if (isFlatAttributeArray(spec.colors)) {
+            colors = spec.colors instanceof Float32Array ? spec.colors : Float32Array.from(spec.colors);
+            if (colors.length !== vertexCount * 4 && colors.length !== vertexCount * 3) {
+                throw new Error("Aura3D geometry colors must be 3 or 4 components per vertex.");
+            }
+            if (colors.length === vertexCount * 3) {
+                const rgba = new Float32Array(vertexCount * 4);
+                for (let i = 0; i < vertexCount; i += 1) {
+                    rgba[i * 4] = colors[i * 3];
+                    rgba[i * 4 + 1] = colors[i * 3 + 1];
+                    rgba[i * 4 + 2] = colors[i * 3 + 2];
+                    rgba[i * 4 + 3] = 1;
+                }
+                colors = rgba;
+            }
+        }
+        else {
+            colors = new Float32Array(vertexCount * 4);
+            spec.colors.forEach((color, index) => {
+                if (index >= vertexCount)
+                    return;
+                const rgba = colorToFlatRgba(color);
+                colors[index * 4] = rgba[0];
+                colors[index * 4 + 1] = rgba[1];
+                colors[index * 4 + 2] = rgba[2];
+                colors[index * 4 + 3] = rgba[3];
+            });
+        }
+    }
+    let indices;
+    // An empty index list means "non-indexed" (sequential 0..n-1) — e.g. the
+    // edges/wireframe helpers emit line-vertex pairs with no index stream.
+    if (spec.indices !== undefined && spec.indices.length > 0) {
+        indices = spec.indices instanceof Uint16Array || spec.indices instanceof Uint32Array ? spec.indices : null;
+        if (!indices) {
+            const list = spec.indices;
+            let max = 0;
+            for (const value of list) {
+                if (!Number.isInteger(value) || value < 0)
+                    throw new Error("Aura3D geometry indices must be non-negative integers.");
+                if (value > max)
+                    max = value;
+            }
+            indices = max > 65535 ? Uint32Array.from(list) : Uint16Array.from(list);
+        }
+        for (const [offset, value] of indices.entries()) {
+            if (!Number.isInteger(value) || value < 0 || value >= vertexCount)
+                throw new Error(`Aura3D geometry index ${offset} is outside the position buffer.`);
+        }
+    }
+    return { positions, vertexCount, custom: normalizeCustomVertexAttributes(spec.attributes, vertexCount), normals, uvs, colors, indices };
+}
+function colorToFlatRgba(color) {
+    if (typeof color === "string") {
+        // Inline the hex grammar so RootGeometry stays dependency-light: #rgb/#rrggbb/#rrggbbaa.
+        const hex = color.trim().replace(/^#/, "");
+        const expand = (s) => (s.length === 3 || s.length === 4 ? s.split("").map((c) => c + c).join("") : s);
+        const full = expand(hex);
+        const r = parseInt(full.slice(0, 2), 16) / 255;
+        const g = parseInt(full.slice(2, 4), 16) / 255;
+        const b = parseInt(full.slice(4, 6), 16) / 255;
+        const a = full.length >= 8 ? parseInt(full.slice(6, 8), 16) / 255 : 1;
+        return [srgbToLinear(r), srgbToLinear(g), srgbToLinear(b), a];
+    }
+    if (Array.isArray(color)) {
+        const tuple = color;
+        return [srgbToLinear(tuple[0] ?? 0), srgbToLinear(tuple[1] ?? 0), srgbToLinear(tuple[2] ?? 0), tuple[3] ?? 1];
+    }
+    return [1, 1, 1, 1];
+}
+function srgbToLinear(value) {
+    return value <= 0.04045 ? value / 12.92 : Math.pow((value + 0.055) / 1.055, 2.4);
+}
+/** SG-05: `geometry.dynamic(spec)` — validate and tag the spec as a runtime-mutable target. */
+export function defineAuraDynamicGeometry(spec) {
+    if (spec.topology !== undefined && spec.topology !== "triangles" && spec.topology !== "points") {
+        throw new Error(`Aura3D geometry.dynamic topology must be "triangles" or "points", got ${String(spec.topology)}.`);
+    }
+    const normalized = normalizeGeometryAttributes(spec);
+    if (normalized.vertexCount === 0)
+        throw new Error("Aura3D dynamic geometry requires at least one vertex.");
+    const indexCount = normalized.indices?.length ?? normalized.vertexCount;
+    if (indexCount === 0)
+        throw new Error("Aura3D dynamic geometry requires at least one index or vertex.");
+    return {
+        kind: "aura-custom-geometry",
+        positions: normalized.positions,
+        ...(spec.normals !== undefined ? { normals: normalized.normals } : {}),
+        ...(spec.uvs !== undefined ? { uvs: normalized.uvs } : {}),
+        ...(spec.colors !== undefined ? { colors: normalized.colors } : {}),
+        indices: normalized.indices ?? Uint16Array.from({ length: normalized.vertexCount }, (_, i) => i),
+        ...(normalized.custom.length > 0 ? { attributes: customAttributesRecord(normalized.custom) } : {}),
+        ...(spec.topology === "points" ? { topology: "points" } : {}),
+        ...(spec.groups ? { groups: [...spec.groups] } : {}),
+        ...(spec.drawRange ? { drawRange: { ...spec.drawRange } } : {}),
+        ...(spec.morphTargets ? { morphTargets: spec.morphTargets.map((target) => ({ ...target })) } : {}),
+        ...(spec.bounds ? { bounds: { min: [...spec.bounds.min], max: [...spec.bounds.max] } } : {}),
+        dynamic: true
+    };
+}
+// ── SG-05 helpers: three's BufferGeometryUtils equivalents (L2-05) ───────────
+/** three's `BufferGeometry.computeVertexNormals` over an Aura spec — returns a fresh flat normal array. */
+export function computeAuraGeometryNormals(spec) {
+    const positions = readVec3Attribute(spec.positions, "positions");
+    const count = positions.length / 3;
+    const normals = new Float32Array(positions.length);
+    const faceNormal = (ia, ib, ic) => {
+        const cbx = positions[ic * 3] - positions[ib * 3];
+        const cby = positions[ic * 3 + 1] - positions[ib * 3 + 1];
+        const cbz = positions[ic * 3 + 2] - positions[ib * 3 + 2];
+        const abx = positions[ia * 3] - positions[ib * 3];
+        const aby = positions[ia * 3 + 1] - positions[ib * 3 + 1];
+        const abz = positions[ia * 3 + 2] - positions[ib * 3 + 2];
+        let nx = cby * abz - cbz * aby;
+        let ny = cbz * abx - cbx * abz;
+        let nz = cbx * aby - cby * abx;
+        const len = Math.hypot(nx, ny, nz);
+        if (len > 0) {
+            nx /= len;
+            ny /= len;
+            nz /= len;
+        }
+        return [nx, ny, nz];
+    };
+    if (spec.indices && spec.indices.length > 0) {
+        for (let i = 0; i + 2 < spec.indices.length; i += 3) {
+            const ia = spec.indices[i];
+            const ib = spec.indices[i + 1];
+            const ic = spec.indices[i + 2];
+            const n = faceNormal(ia, ib, ic);
+            for (const v of [ia, ib, ic]) {
+                normals[v * 3] = normals[v * 3] + n[0];
+                normals[v * 3 + 1] = normals[v * 3 + 1] + n[1];
+                normals[v * 3 + 2] = normals[v * 3 + 2] + n[2];
+            }
+        }
+        for (let i = 0; i < count; i += 1) {
+            const len = Math.hypot(normals[i * 3], normals[i * 3 + 1], normals[i * 3 + 2]);
+            if (len > 0) {
+                normals[i * 3] = normals[i * 3] / len;
+                normals[i * 3 + 1] = normals[i * 3 + 1] / len;
+                normals[i * 3 + 2] = normals[i * 3 + 2] / len;
+            }
+        }
+    }
+    else {
+        for (let i = 0; i < count; i += 3) {
+            const n = faceNormal(i, i + 1, i + 2);
+            for (const v of [i, i + 1, i + 2]) {
+                normals[v * 3] = n[0];
+                normals[v * 3 + 1] = n[1];
+                normals[v * 3 + 2] = n[2];
+            }
+        }
+    }
+    return normals;
+}
+/** three's `BufferGeometry.computeBoundingBox` — finite min/max over positions. */
+export function computeAuraGeometryBounds(spec) {
+    const positions = readVec3Attribute(spec.positions, "positions");
+    const min = [Infinity, Infinity, Infinity];
+    const max = [-Infinity, -Infinity, -Infinity];
+    for (let i = 0; i < positions.length; i += 3) {
+        for (let axis = 0; axis < 3; axis += 1) {
+            const v = positions[i + axis];
+            if (v < min[axis])
+                min[axis] = v;
+            if (v > max[axis])
+                max[axis] = v;
+        }
+    }
+    return { min, max };
+}
+/**
+ * three's `BufferGeometry.applyMatrix4` — positions take the full column-major
+ * mat4; normals take the upper 3x3 (the three `normalMatrix` inverse-transpose
+ * reduces to the same rotation/scale here for rigid+scale matrices, matching
+ * the engine mergeGeometries convention) and are renormalized.
+ */
+export function applyAuraGeometryMatrix4(spec, matrix) {
+    if (matrix.length !== 16 || ![...matrix].every(Number.isFinite))
+        throw new Error("applyAuraGeometryMatrix4 requires a finite mat4.");
+    const positions = readVec3Attribute(spec.positions, "positions").slice();
+    for (let i = 0; i < positions.length; i += 3) {
+        const x = positions[i], y = positions[i + 1], z = positions[i + 2];
+        positions[i] = matrix[0] * x + matrix[4] * y + matrix[8] * z + matrix[12];
+        positions[i + 1] = matrix[1] * x + matrix[5] * y + matrix[9] * z + matrix[13];
+        positions[i + 2] = matrix[2] * x + matrix[6] * y + matrix[10] * z + matrix[14];
+    }
+    let normals;
+    if (spec.normals !== undefined) {
+        normals = readVec3Attribute(spec.normals, "normals").slice();
+        for (let i = 0; i < normals.length; i += 3) {
+            const x = normals[i], y = normals[i + 1], z = normals[i + 2];
+            const nx = matrix[0] * x + matrix[4] * y + matrix[8] * z;
+            const ny = matrix[1] * x + matrix[5] * y + matrix[9] * z;
+            const nz = matrix[2] * x + matrix[6] * y + matrix[10] * z;
+            const len = Math.hypot(nx, ny, nz) || 1;
+            normals[i] = nx / len;
+            normals[i + 1] = ny / len;
+            normals[i + 2] = nz / len;
+        }
+    }
+    return {
+        ...spec,
+        positions,
+        ...(normals ? { normals } : {}),
+        bounds: spec.bounds ? computeAuraGeometryBounds({ positions }) : undefined
+    };
+}
+/** three's `BufferGeometryUtils.toNonIndexed` — one vertex per index, in index order. */
+export function auraGeometryToNonIndexed(spec) {
+    const positions = readVec3Attribute(spec.positions, "positions");
+    const normals = readVec3Attribute(spec.normals, "normals");
+    const uvs = readVec2Attribute(spec.uvs, "uvs");
+    const colors = spec.colors !== undefined ? normalizeGeometryAttributes({ positions: spec.positions, colors: spec.colors }).colors : undefined;
+    const indices = spec.indices;
+    if (!indices || indices.length === 0)
+        return spec;
+    const custom = normalizeCustomVertexAttributes(spec.attributes, positions.length / 3);
+    const expand = (source, components) => {
+        if (!source)
+            return undefined;
+        const out = new Float32Array(indices.length * components);
+        for (let i = 0; i < indices.length; i += 1) {
+            const v = indices[i];
+            for (let c = 0; c < components; c += 1)
+                out[i * components + c] = source[v * components + c];
+        }
+        return out;
+    };
+    return {
+        ...spec,
+        positions: expand(positions, 3),
+        ...(normals ? { normals: expand(normals, 3) } : {}),
+        ...(uvs ? { uvs: expand(uvs, 2) } : {}),
+        ...(colors ? { colors: expand(colors, 4) } : {}),
+        ...(custom.length > 0 ? { attributes: Object.fromEntries(custom.map((entry) => [entry.name, { itemSize: entry.itemSize, data: expand(entry.data, entry.itemSize) }])) } : {}),
+        indices: []
+    };
+}
+/**
+ * three's `BufferGeometryUtils.mergeGeometries` — concatenates specs (no
+ * transform baking; the R/MeshConsolidation merge bakes model matrices for
+ * the static path, while the authored merge keeps authored coordinates).
+ * Index-bearing specs share the index stream; attribute sets must match.
+ */
+export function mergeAuraGeometries(specs) {
+    if (specs.length === 0)
+        throw new Error("mergeAuraGeometries requires at least one geometry spec.");
+    const normalized = specs.map((spec) => normalizeGeometryAttributes(spec));
+    const withUvs = normalized.every((entry) => entry.uvs !== undefined);
+    const withNormals = normalized.every((entry) => entry.normals !== undefined);
+    const withColors = normalized.every((entry) => entry.colors !== undefined);
+    const withIndex = normalized.every((entry) => entry.indices !== undefined && entry.indices.length > 0);
+    const customNames = normalized[0].custom.map((entry) => entry.name);
+    for (const entry of normalized) {
+        if (entry.custom.length !== customNames.length || entry.custom.some((attribute, i) => attribute.name !== customNames[i] || attribute.itemSize !== normalized[0].custom[i].itemSize)) {
+            throw new Error("mergeAuraGeometries requires every geometry to carry the same custom vertex attributes (names and itemSize), like three's mergeGeometries.");
+        }
+    }
+    const totalVertices = normalized.reduce((sum, entry) => sum + entry.vertexCount, 0);
+    const positions = new Float32Array(totalVertices * 3);
+    const normals = withNormals ? new Float32Array(totalVertices * 3) : undefined;
+    const uvs = withUvs ? new Float32Array(totalVertices * 2) : undefined;
+    const colors = withColors ? new Float32Array(totalVertices * 4) : undefined;
+    const customMerged = normalized[0].custom.map((attribute) => ({ name: attribute.name, itemSize: attribute.itemSize, data: new Float32Array(totalVertices * attribute.itemSize) }));
+    const indices = [];
+    const groups = [];
+    let cursor = 0;
+    for (const entry of normalized) {
+        entry.custom.forEach((attribute, i) => customMerged[i].data.set(attribute.data, cursor * attribute.itemSize));
+        positions.set(entry.positions, cursor * 3);
+        if (normals && entry.normals)
+            normals.set(entry.normals, cursor * 3);
+        if (uvs && entry.uvs)
+            uvs.set(entry.uvs, cursor * 2);
+        if (colors && entry.colors)
+            colors.set(entry.colors, cursor * 4);
+        if (withIndex) {
+            const source = entry.indices;
+            const start = indices.length;
+            for (let i = 0; i < source.length; i += 1)
+                indices.push(source[i] + cursor);
+            groups.push({ start, count: source.length });
+        }
+        cursor += entry.vertexCount;
+    }
+    return {
+        kind: "aura-custom-geometry",
+        positions,
+        ...(normals ? { normals } : {}),
+        ...(uvs ? { uvs } : {}),
+        ...(colors ? { colors } : {}),
+        ...(customMerged.length > 0 ? { attributes: customAttributesRecord(customMerged) } : {}),
+        indices,
+        ...(withIndex ? { groups } : {})
+    };
+}
 /** Build depth-bearing triangle geometry; this is not a DOM label or canvas texture. */
 export function createAuraText3DGeometry(text, options = {}) {
     if (!text.length)