@aura3d/engine 4.0.3 → 4.0.4

package/dist/engine/agent-api/compiler/primitives.d.ts

@@ -1,6 +1,6 @@
 import type { AuraColor, AuraModelNode, AuraPrimitiveNode, AuraRuntimeNodeRegistry, AuraSceneNode, AuraTransformSpec, AuraVec3, ProductionRuntimePrimitiveEntry, ProductionRuntimePrimitiveResource, ProductionRuntimePrimitiveState } from "../nodes/types.js";
 import { type TextureStreamingResidency } from "../../../assets/browser-index.js";
-import { type EnvironmentLightingOptions } from "../../../rendering/index.js";
+import { PortableShaderMaterial, type EnvironmentLightingOptions } from "../../../rendering/index.js";
 /**
  * Q-15-2: `qr` (from `qrPrimitiveGeometryOptions(flags, quality)`) routes the
  * builtin primitives through @aura3d/rendering `createPrimitiveGeometry` under
@@ -86,7 +86,7 @@ interface ProductionPrimitiveScalars {
     readonly envMapIntensity: number;
 }
 export declare function resolveProductionPrimitiveScalars(node: AuraPrimitiveNode): ProductionPrimitiveScalars;
-export declare function createProductionPrimitiveMaterial(node: AuraPrimitiveNode): PBRMaterial | InstancedPBRMaterial;
+export declare function createProductionPrimitiveMaterial(node: AuraPrimitiveNode): PBRMaterial | InstancedPBRMaterial | PortableShaderMaterial;
 /** Q-15-2: the flag-on mesh for a builtin primitive node; undefined = legacy path (flag off, custom, geometry spec). */
 export declare function qrPrimitiveMeshFor(node: AuraPrimitiveNode, qr: QrPrimitiveGeometryOptions | undefined): ProductionPrimitiveMesh | undefined;
 /** Q-15-2: flag-on geometry + bounds, pooled per mount when `qr.pool` is set (#545). */
@@ -105,8 +105,21 @@ export declare function primitiveGeometryBounds(nodeOrPrimitive: AuraPrimitiveNo
 export interface ProductionPrimitiveMesh {
     readonly positions: Float32Array;
     readonly normals: Float32Array;
-    readonly indices: Uint16Array;
+    readonly indices: Uint16Array | Uint32Array;
     readonly bounds: GltfBounds;
+    /** threejs-parity L2: `"lines"`/`"points"` topologies (edges/wireframe paths). Default `"triangles"`. */
+    readonly topology?: "triangles" | "lines" | "points";
+    /** threejs-parity L2: three's geometry.groups — material-index index ranges. */
+    readonly groups?: readonly {
+        readonly start: number;
+        readonly count: number;
+        readonly materialIndex?: number;
+    }[];
+    /** threejs-parity L2: three's setDrawRange. */
+    readonly drawRange?: {
+        readonly start: number;
+        readonly count: number;
+    };
     readonly uvs?: Float32Array;
     readonly uv1s?: Float32Array;
     /**
@@ -116,6 +129,12 @@ export interface ProductionPrimitiveMesh {
     readonly tangents?: Float32Array;
 }
 export declare function tilingSecondUnwrap(uvs: Float32Array): Float32Array;
+/** Queued partial attribute write produced by `handle.updateAttribute` (region parity:L2). */
+export interface AuraL2AttributeUpdate {
+    readonly name: string;
+    readonly array: Float32Array | Uint16Array | Uint32Array;
+    readonly offset: number;
+}
 export {};
 /**
  * Build the production `PBRMaterial` for a primitive node.

package/dist/engine/agent-api/compiler/primitives.d.ts.map

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

package/dist/engine/agent-api/compiler/primitives.js

@@ -7,8 +7,10 @@ import { primitive } from "../nodes/primitives.js";
 import { createModelMatrix, primitiveSize, shouldNormalizeModelNode } from "../sceneMath.js";
 import { selectAuraRootLodLevel } from "../RootGeometry.js";
 import { evaluateDistancePrioritizedMipResidency } from "../../../assets/browser-index.js";
-import { createDualProbeEnvironmentLightingResources, createProductionEnvironmentLightingResources, createProductionPbrHdrPipelineFromRadiance } from "../../../rendering/index.js";
+import { PortableShaderMaterial, createDualProbeEnvironmentLightingResources, createProductionEnvironmentLightingResources, createProductionPbrHdrPipelineFromRadiance } from "../../../rendering/index.js";
+import { applyCustomUniformWrites, createCustomShaderMaterial, customUniformWritesFor } from "./customMaterial.js";
 import { normalizeTextureBudgetBytes } from "../app/rendererOptions.js";
+import { AuraRuntimeError } from "./errors.js";
 import { blankProductionPrimitiveTextureState, createSdfTextPrimitiveResource } from "./textures.js";
 import { material } from "../nodes/material.js";
 /**
@@ -38,6 +40,10 @@ export function createProductionPrimitiveResources(node, qr) {
             sourceNode: node,
             ...blankProductionPrimitiveTextureState()
         };
+        // threejs-parity L2: the spec object the resource geometry was built from.
+        // `handle.setGeometry` mutates `node.geometry` in place, so the applied
+        // marker must be captured here rather than re-read from `sourceNode`.
+        fallback.__parityL2AppliedGeometry = node.geometry;
         // Sampler failures stay visible on the fallback resource (surfaced via
         // texturedMaterials diagnostics), never swallowed by the mesh swap.
         fallback.textureWarnings.push(...sdfWarnings);
@@ -67,6 +73,7 @@ export function createProductionPrimitiveResources(node, qr) {
             sourceNode: levelNode,
             ...blankProductionPrimitiveTextureState()
         };
+        levelFallback.__parityL2AppliedGeometry = levelNode.geometry;
         levelFallback.textureWarnings.push(...levelWarnings);
         return levelFallback;
     });
@@ -79,6 +86,10 @@ export function selectProductionPrimitiveResource(entry, node, cameraPosition, l
             mutableResource.materialSpec = node.material;
             mutableResource.material = createProductionPrimitiveMaterial(node);
         }
+        // threejs-parity L2 (SG-05): `handle.setGeometry`/`updateAttribute` —
+        // in-place buffer writes when the vertex count is unchanged, replace
+        // otherwise. Tracked per resource so unchanged frames cost nothing.
+        syncRuntimePrimitiveGeometry(resource, node);
         return resource;
     }
     const position = node.position ?? [0, 0, 0];
@@ -116,22 +127,41 @@ export function resolveProductionPrimitiveRuntimeState(entry, runtimeNodes) {
     const runtimeId = entry.node.runtime?.id;
     if (!runtimeId)
         return { node: entry.node, visible: true };
-    const runtimeSnapshot = runtimeNodes?.get(runtimeId)?.snapshot();
+    const runtimeHandle = runtimeNodes?.get(runtimeId);
+    const runtimeSnapshot = runtimeHandle?.snapshot();
+    // parity:L1 (SH-02): staged `handle.setUniform` writes land on the compiled
+    // portable material here — `setParameter` updates uniform state only, never
+    // the shader key, so no program is recompiled.
+    const uniformWrites = customUniformWritesFor(runtimeId);
+    if (uniformWrites?.size) {
+        for (const resource of entry.resources) {
+            if (resource.material instanceof PortableShaderMaterial) {
+                applyCustomUniformWrites(resource.material, uniformWrites);
+            }
+        }
+    }
     if (!runtimeSnapshot)
         return { node: entry.node, visible: true };
-    return {
-        node: {
-            ...entry.node,
-            position: runtimeSnapshot.position,
-            rotation: runtimeSnapshot.rotation,
-            scale: runtimeSnapshot.scale,
-            material: runtimeSnapshot.material ?? entry.node.material,
-            animation: runtimeSnapshot.animation ?? entry.node.animation,
-            ...(runtimeSnapshot.instances ? { instances: runtimeSnapshot.instances } : {}),
-            ...(runtimeSnapshot.instanceColors ? { instanceColors: runtimeSnapshot.instanceColors } : {})
-        },
-        visible: runtimeSnapshot.visible
+    // L2: drain the queued attribute writes so they apply exactly once.
+    const pendingAttributes = runtimeHandle?.__parityL2AttributeUpdates;
+    if (runtimeHandle && pendingAttributes && pendingAttributes.length > 0) {
+        runtimeHandle.__parityL2AttributeUpdates = [];
+    }
+    const resolvedNode = {
+        ...entry.node,
+        position: runtimeSnapshot.position,
+        rotation: runtimeSnapshot.rotation,
+        scale: runtimeSnapshot.scale,
+        material: runtimeSnapshot.material ?? entry.node.material,
+        animation: runtimeSnapshot.animation ?? entry.node.animation,
+        ...(runtimeSnapshot.instances ? { instances: runtimeSnapshot.instances } : {}),
+        ...(runtimeSnapshot.instanceColors ? { instanceColors: runtimeSnapshot.instanceColors } : {}),
+        ...(runtimeHandle?.__parityL2Geometry !== undefined ? { geometry: runtimeHandle.__parityL2Geometry } : {})
     };
+    if (pendingAttributes && pendingAttributes.length > 0) {
+        resolvedNode.__parityL2AttributeUpdates = pendingAttributes;
+    }
+    return { node: resolvedNode, visible: runtimeSnapshot.visible };
 }
 export function describeTextureStreamingResidency(table, budgetBytes) {
     const candidates = table.map((entry) => ({
@@ -190,13 +220,13 @@ export async function upgradeProductionEnvironmentHdri(url, intensity, reflectio
         dualProbe: true
     };
 }
-import { Geometry, IndexBuffer, InstancedPBRMaterial, PBRMaterial, VertexBuffer, VertexFormat } from "../../../rendering/index.js";
-import { defineAuraCustomGeometry } from "../RootGeometry.js";
+import { Geometry, IndexBuffer, InstancedPBRMaterial, PBRMaterial, VertexBuffer, VertexFormat, assignCustomAttributeLocations, customAttributeSemantic } from "../../../rendering/index.js";
+import { computeAuraGeometryBounds, computeAuraGeometryNormals, defineAuraCustomGeometry, normalizeGeometryAttributes } from "../RootGeometry.js";
 import { instances } from "../nodes/instances.js";
 import { renderer } from "../rendererDiagnostics.js";
 import { scene } from "../nodes/scene.js";
 import { colorToLinearRgb } from "../colorUtils.js";
-import { createPlaneGeometry, createBoxGeometry, createSphereGeometry, createCylinderGeometry, createTorusGeometry, createCapsuleApproxGeometry, createQrPrimitiveMesh, qrPrimitiveGeometryKey } from "./geometry.js";
+import { createPlaneGeometry, createBoxGeometry, createSphereGeometry, createCylinderGeometry, createTorusGeometry, createCapsuleApproxGeometry, createQrPrimitiveMesh, qrPrimitiveGeometryKey, qrPrimitiveParamsPoolable } from "./geometry.js";
 import { clamp01 } from "../sceneMath.js";
 export function resolveProductionPrimitiveScalars(node) {
     const materialSpec = node.material;
@@ -239,6 +269,11 @@ export function resolveProductionPrimitiveScalars(node) {
 }
 export function createProductionPrimitiveMaterial(node) {
     const materialSpec = node.material;
+    // parity:L1 (SH-02): `material.custom(spec)` routes to the portable-shader
+    // adapter — a validated `PortableShaderMaterial`, never a PBR downgrade.
+    if (materialSpec?.kind === "custom" && materialSpec.custom) {
+        return createCustomShaderMaterial(materialSpec.custom, `primitive-${node.primitive}${node.name ? `-${node.name}` : ""}`);
+    }
     const { baseColor, opacity, emissiveColor, clearcoat, sheenColor, declaresExtension, transmission, thicknessRange, sheen, iridescence, anisotropy, environmentIntensity, envMapIntensity } = resolveProductionPrimitiveScalars(node);
     /*
      * Native instance submission requires the renderer's instanced shader contract. The ordinary
@@ -258,6 +293,8 @@ export function createProductionPrimitiveMaterial(node) {
             emissiveStrength: Math.max(0, materialSpec?.emissiveIntensity ?? (materialSpec?.emissive ? 1.35 : 0)),
             environmentIntensity,
             envMapIntensity,
+            // threejs-parity L7/SR-02: forward the frozen `AuraMaterialSpec.fog` opt-out.
+            fog: materialSpec?.fog,
             renderState: {
                 blend: opacity < 0.999,
                 depthWrite: opacity >= 0.999,
@@ -289,6 +326,8 @@ export function createProductionPrimitiveMaterial(node) {
         ...(materialSpec?.attenuationDistance === undefined ? {} : { volumeAttenuationDistance: Math.max(0, materialSpec.attenuationDistance) }),
         environmentIntensity,
         envMapIntensity,
+        // threejs-parity L7/SR-02: forward the frozen `AuraMaterialSpec.fog` opt-out.
+        fog: materialSpec?.fog,
         renderState: {
             blend: opacity < 0.999,
             depthWrite: opacity >= 0.999,
@@ -296,23 +335,52 @@ export function createProductionPrimitiveMaterial(node) {
         }
     });
 }
+/**
+ * threejs-parity L2 (§6 L2-01/02): every `AuraBuiltinPrimitive` kind now maps
+ * onto a real `createPrimitiveGeometry` generator — no fail-closed dispatch
+ * remains. `"custom"` still resolves through the geometry-spec path.
+ */
+function qrBuiltinPrimitive(primitive) {
+    switch (primitive) {
+        case "box":
+        case "sphere":
+        case "plane":
+        case "cylinder":
+        case "capsule":
+        case "torus":
+        case "cone":
+        case "circle":
+        case "ring":
+        case "tube":
+        case "lathe":
+        case "extrude":
+        case "shape":
+        case "torusKnot":
+        case "polyhedron":
+        case "roundedBox":
+            return primitive;
+        default:
+            throw new AuraRuntimeError("parity-not-implemented", `Aura3D primitive "${String(primitive)}" is not implemented (A3D_PARITY_GEOMETRY). See docs/workflows/threejs-parity-gaps.md.`);
+    }
+}
 /** Q-15-2: the flag-on mesh for a builtin primitive node; undefined = legacy path (flag off, custom, geometry spec). */
 export function qrPrimitiveMeshFor(node, qr) {
     if (!qr?.core || node.geometry || node.primitive === "custom")
         return undefined;
-    return createQrPrimitiveMesh(node.primitive, primitiveSize(node), qr);
+    return createQrPrimitiveMesh(qrBuiltinPrimitive(node.primitive), primitiveSize(node), qr, node.params);
 }
 /** Q-15-2: flag-on geometry + bounds, pooled per mount when `qr.pool` is set (#545). */
 export function qrPrimitiveGeometryFor(node, qr) {
     if (!qr?.core || node.geometry || node.primitive === "custom")
         return undefined;
     const size = primitiveSize(node);
-    if (!qr.pool) {
-        const mesh = createQrPrimitiveMesh(node.primitive, size, qr);
+    // L2: params carrying live curve/shape objects can't key a shared pool entry.
+    if (!qr.pool || !qrPrimitiveParamsPoolable(node.params)) {
+        const mesh = createQrPrimitiveMesh(qrBuiltinPrimitive(node.primitive), size, qr, node.params);
         return { geometry: createProductionGeometryFromPrimitiveMesh(mesh), bounds: mesh.bounds };
     }
-    const primitive = node.primitive;
-    const geometry = qr.pool.acquire(qrPrimitiveGeometryKey(primitive, size, qr), () => createProductionGeometryFromPrimitiveMesh(createQrPrimitiveMesh(primitive, size, qr)));
+    const primitive = qrBuiltinPrimitive(node.primitive);
+    const geometry = qr.pool.acquire(qrPrimitiveGeometryKey(primitive, size, qr, node.params), () => createProductionGeometryFromPrimitiveMesh(createQrPrimitiveMesh(primitive, size, qr, node.params)));
     return { geometry, bounds: geometry.bounds };
 }
 export function createProductionPrimitiveGeometry(node) {
@@ -320,7 +388,7 @@ export function createProductionPrimitiveGeometry(node) {
         return createProductionGeometryFromCustomSpec(node.geometry);
     if (node.primitive === "custom")
         throw new Error("Aura3D custom primitive requires geometry.");
-    return createProductionGeometryFromPrimitiveMesh(createProductionPrimitiveMesh(node.primitive));
+    return createProductionGeometryFromPrimitiveMesh(createProductionPrimitiveMesh(node.primitive, node));
 }
 export function primitiveGeometryBounds(nodeOrPrimitive) {
     if (typeof nodeOrPrimitive === "object" && nodeOrPrimitive.geometry)
@@ -328,7 +396,7 @@ export function primitiveGeometryBounds(nodeOrPrimitive) {
     const primitive = typeof nodeOrPrimitive === "string" ? nodeOrPrimitive : nodeOrPrimitive.primitive;
     if (primitive === "custom")
         throw new Error("Aura3D custom primitive requires geometry.");
-    return createProductionPrimitiveMesh(primitive).bounds;
+    return createProductionPrimitiveMesh(primitive, typeof nodeOrPrimitive === "object" ? nodeOrPrimitive : undefined).bounds;
 }
 export function tilingSecondUnwrap(uvs) {
     const uv1s = new Float32Array(uvs.length);
@@ -336,7 +404,12 @@ export function tilingSecondUnwrap(uvs) {
         uv1s[i] = (uvs[i] ?? 0) * 2;
     return uv1s;
 }
-function createProductionPrimitiveMesh(primitive) {
+/**
+ * Legacy (flag-off) primitive mesh. The six original kinds keep their bespoke
+ * generators byte-for-byte; the ten threejs-parity L2 kinds route through the
+ * shared `createPrimitiveGeometry` factory with the node's params.
+ */
+function createProductionPrimitiveMesh(primitive, node) {
     if (primitive === "sphere")
         return createSphereGeometry();
     if (primitive === "capsule")
@@ -347,43 +420,87 @@ function createProductionPrimitiveMesh(primitive) {
         return createBoxGeometry();
     if (primitive === "cylinder")
         return createCylinderGeometry();
-    return createPlaneGeometry();
+    if (primitive === "plane")
+        return createPlaneGeometry();
+    // threejs-parity L2: the ten new kinds share the QR generator path (full
+    // segments — the C-27 tier halving only applies under A3D_QR_CORE).
+    const size = node ? primitiveSize(node) : [1, 1, 1];
+    return createQrPrimitiveMesh(qrBuiltinPrimitive(primitive), size, { core: true, primitiveSegments: "full" }, node?.params);
 }
+/**
+ * SG-05 (threejs-parity L2): custom/dynamic specs normalize flat or tuple
+ * attributes, optional colors, `"lines"` topology (edges/wireframe), groups,
+ * drawRange and morph targets onto the production `Geometry`.
+ */
 function createProductionGeometryFromCustomSpec(spec) {
-    const normalized = defineAuraCustomGeometry(spec);
-    const normals = normalized.normals ?? calculateCustomGeometryNormals(normalized);
-    const vertexCount = normalized.positions.length;
-    const vertices = new VertexBuffer(VertexFormat.P3N3, vertexCount);
-    normalized.positions.forEach((position, index) => {
-        vertices.setAttribute(index, "position", position);
-        vertices.setAttribute(index, "normal", normals[index] ?? [0, 1, 0]);
-    });
-    return new Geometry(vertices, new IndexBuffer(normalized.indices, vertexCount), "triangles", customGeometryBounds(normalized));
+    const normalized = normalizeGeometryAttributes(spec);
+    const normals = resolveSpecNormals(spec, normalized);
+    const vertexCount = normalized.vertexCount;
+    const attributes = [
+        { semantic: "position", components: 3, offset: 0 },
+        { semantic: "normal", components: 3, offset: 12 }
+    ];
+    let cursor = 24;
+    if (normalized.uvs) {
+        attributes.push({ semantic: "uv", components: 2, offset: cursor });
+        cursor += 8;
+    }
+    if (normalized.colors) {
+        attributes.push({ semantic: "color", components: 4, offset: cursor });
+        cursor += 16;
+    }
+    // R-23: custom attributes follow the built-ins in name order and bind by
+    // their GLSL name; locations come from the stable pool.
+    const customLocations = assignCustomAttributeLocations(normalized.custom.map((entry) => entry.name));
+    for (const entry of normalized.custom) {
+        attributes.push({
+            semantic: customAttributeSemantic(entry.name),
+            components: entry.itemSize,
+            offset: cursor,
+            shaderName: entry.name,
+            shaderLocation: customLocations.get(entry.name)
+        });
+        cursor += entry.itemSize * 4;
+    }
+    const vertices = new VertexBuffer(new VertexFormat(attributes), vertexCount);
+    for (let index = 0; index < vertexCount; index += 1) {
+        vertices.setAttribute(index, "position", [normalized.positions[index * 3], normalized.positions[index * 3 + 1], normalized.positions[index * 3 + 2]]);
+        vertices.setAttribute(index, "normal", [normals[index * 3], normals[index * 3 + 1], normals[index * 3 + 2]]);
+        if (normalized.uvs)
+            vertices.setAttribute(index, "uv", [normalized.uvs[index * 2], normalized.uvs[index * 2 + 1]]);
+        if (normalized.colors)
+            vertices.setAttribute(index, "color", [normalized.colors[index * 4], normalized.colors[index * 4 + 1], normalized.colors[index * 4 + 2], normalized.colors[index * 4 + 3]]);
+    }
+    for (const entry of normalized.custom)
+        writeCustomAttribute(vertices, entry.name, entry.itemSize, entry.data, 0);
+    const indexList = normalized.indices ?? Uint32Array.from({ length: vertexCount }, (_, i) => i);
+    const indexBuffer = indexList.length > 0 ? new IndexBuffer(Array.from(indexList), vertexCount) : null;
+    const geometry = new Geometry(vertices, indexBuffer, spec.topology === "lines" ? "lines" : spec.topology === "points" ? "points" : "triangles", customGeometryBounds(spec));
+    if (spec.groups)
+        geometry.groups = [...spec.groups];
+    if (spec.drawRange)
+        geometry.drawRange = { ...spec.drawRange };
+    if (spec.morphTargets)
+        geometry.morphTargets = spec.morphTargets.map((target) => ({ ...target }));
+    return geometry;
+}
+/** Authored normals, else computed; points carry a constant +Y (a vertex count that is not a multiple of 3 would yield NaN face normals). */
+function resolveSpecNormals(spec, normalized) {
+    if (normalized.normals)
+        return normalized.normals;
+    if (spec.topology === "points") {
+        const up = new Float32Array(normalized.positions.length);
+        for (let i = 1; i < up.length; i += 3)
+            up[i] = 1;
+        return up;
+    }
+    return computeAuraGeometryNormals({ positions: normalized.positions, indices: normalized.indices });
 }
 function customGeometryBounds(spec) {
     if (spec.bounds)
         return { min: spec.bounds.min, max: spec.bounds.max };
-    const min = [Infinity, Infinity, Infinity];
-    const max = [-Infinity, -Infinity, -Infinity];
-    spec.positions.forEach((position) => { for (let axis = 0; axis < 3; axis += 1) {
-        min[axis] = Math.min(min[axis], position[axis]);
-        max[axis] = Math.max(max[axis], position[axis]);
-    } });
-    return { min, max };
-}
-function calculateCustomGeometryNormals(spec) {
-    const totals = Array.from({ length: spec.positions.length }, () => [0, 0, 0]);
-    for (let offset = 0; offset < spec.indices.length; offset += 3) {
-        const ia = spec.indices[offset], ib = spec.indices[offset + 1], ic = spec.indices[offset + 2];
-        const a = spec.positions[ia], b = spec.positions[ib], c = spec.positions[ic];
-        const ab = [b[0] - a[0], b[1] - a[1], b[2] - a[2]];
-        const ac = [c[0] - a[0], c[1] - a[1], c[2] - a[2]];
-        const normal = [ab[1] * ac[2] - ab[2] * ac[1], ab[2] * ac[0] - ab[0] * ac[2], ab[0] * ac[1] - ab[1] * ac[0]];
-        for (const index of [ia, ib, ic])
-            for (let axis = 0; axis < 3; axis += 1)
-                totals[index][axis] += normal[axis];
-    }
-    return totals.map((normal) => { const length = Math.hypot(...normal) || 1; return [normal[0] / length, normal[1] / length, normal[2] / length]; });
+    const computed = computeAuraGeometryBounds({ positions: spec.positions });
+    return { min: computed.min, max: computed.max };
 }
 function createProductionGeometryFromPrimitiveMesh(mesh) {
     const vertexCount = mesh.positions.length / 3;
@@ -406,7 +523,153 @@ function createProductionGeometryFromPrimitiveMesh(mesh) {
             vertices.setAttribute(index, "uv1", [uv1[uvBase] ?? 0, uv1[uvBase + 1] ?? 0]);
         }
     }
-    return new Geometry(vertices, new IndexBuffer(Array.from(mesh.indices), vertexCount), "triangles", mesh.bounds);
+    const geometry = new Geometry(vertices, new IndexBuffer(Array.from(mesh.indices), vertexCount), mesh.topology ?? "triangles", mesh.bounds);
+    // threejs-parity L2: carry three's groups/drawRange through to the draw path.
+    if (mesh.groups)
+        geometry.groups = [...mesh.groups];
+    if (mesh.drawRange)
+        geometry.drawRange = { ...mesh.drawRange };
+    return geometry;
+}
+const L2_UPDATE_SEMANTICS = {
+    position: "position",
+    positions: "position",
+    normal: "normal",
+    normals: "normal",
+    uv: "uv",
+    uv0: "uv",
+    uvs: "uv",
+    uv1: "uv1",
+    color: "color",
+    colors: "color",
+    tangent: "tangent",
+    tangents: "tangent"
+};
+/**
+ * SG-05: apply `handle.setGeometry` + `handle.updateAttribute` writes to the
+ * live resource. Same vertex count + same attribute set ⇒ write into the
+ * existing `VertexBuffer` (dirty ranges flush on the next `upload()` — the
+ * GPU allocation is never re-created). A different vertex count or attribute
+ * footprint rebuilds the `Geometry` once (realloc allowed then).
+ */
+function syncRuntimePrimitiveGeometry(resource, node) {
+    const tracked = resource;
+    const spec = node.geometry;
+    // `__parityL2AppliedGeometry` is tagged at resource build — `handle.setGeometry`
+    // also mutates `node.geometry` in place, so `sourceNode.geometry` can NOT
+    // serve as the applied marker (it already holds the new spec).
+    if (spec !== undefined && spec !== tracked.__parityL2AppliedGeometry) {
+        applyDynamicGeometrySpec(resource, spec);
+        tracked.__parityL2AppliedGeometry = spec;
+        if (tracked.sourceNode)
+            tracked.sourceNode = { ...tracked.sourceNode, geometry: spec };
+    }
+    const updates = node.__parityL2AttributeUpdates;
+    if (updates) {
+        for (const update of updates)
+            applyAttributeUpdateToGeometry(resource.geometry, update);
+    }
+}
+function applyDynamicGeometrySpec(resource, spec) {
+    const tracked = resource;
+    const normalized = normalizeGeometryAttributes(spec);
+    const geometry = resource.geometry;
+    const vertexBuffer = geometry.vertexBuffer;
+    const has = (semantic) => vertexBuffer.format.hasAttribute(semantic);
+    const sameFootprint = vertexBuffer.vertexCount === normalized.vertexCount
+        && has("uv") === (normalized.uvs !== undefined)
+        && has("color") === (normalized.colors !== undefined)
+        && customFootprintMatches(vertexBuffer, normalized.custom)
+        && geometry.topology === (spec.topology ?? "triangles")
+        && vertexBuffer.format.hasAttribute("normal")
+        && !has("tangent");
+    const normals = resolveSpecNormals(spec, normalized);
+    if (sameFootprint) {
+        // In-place path (L2-04): attribute writes mark byte ranges dirty; the next
+        // upload() flushes only those ranges — no new GPU buffer.
+        for (let index = 0; index < normalized.vertexCount; index += 1) {
+            vertexBuffer.setAttribute(index, "position", [normalized.positions[index * 3], normalized.positions[index * 3 + 1], normalized.positions[index * 3 + 2]]);
+            vertexBuffer.setAttribute(index, "normal", [normals[index * 3], normals[index * 3 + 1], normals[index * 3 + 2]]);
+            if (normalized.uvs)
+                vertexBuffer.setAttribute(index, "uv", [normalized.uvs[index * 2], normalized.uvs[index * 2 + 1]]);
+            if (normalized.colors)
+                vertexBuffer.setAttribute(index, "color", [normalized.colors[index * 4], normalized.colors[index * 4 + 1], normalized.colors[index * 4 + 2], normalized.colors[index * 4 + 3]]);
+        }
+        for (const entry of normalized.custom)
+            writeCustomAttribute(vertexBuffer, entry.name, entry.itemSize, entry.data, 0);
+        if (normalized.indices && geometry.indexBuffer && normalized.indices.length === geometry.indexBuffer.count) {
+            geometry.indexBuffer.setIndices(0, normalized.indices);
+        }
+        else if (normalized.indices) {
+            // Same vertex count but a different index count still fits the existing
+            // vertex allocation; only the index buffer is swapped.
+            geometry.indexBuffer?.dispose();
+            geometry.indexBuffer = new IndexBuffer(Array.from(normalized.indices), normalized.vertexCount);
+        }
+        const bounds = spec.bounds ? { min: spec.bounds.min, max: spec.bounds.max } : computeAuraGeometryBounds({ positions: normalized.positions });
+        geometry.bounds = { min: [...bounds.min], max: [...bounds.max] };
+        geometry.groups = spec.groups ? [...spec.groups] : undefined;
+        geometry.drawRange = spec.drawRange ? { ...spec.drawRange } : undefined;
+        geometry.morphTargets = spec.morphTargets ? spec.morphTargets.map((target) => ({ ...target })) : undefined;
+        tracked.bounds = { min: [...bounds.min], max: [...bounds.max] };
+        return;
+    }
+    // Realloc path: different vertex count, attribute footprint, or topology.
+    const next = createProductionGeometryFromCustomSpec(spec);
+    geometry.dispose();
+    tracked.geometry = next;
+    tracked.bounds = { min: [...next.bounds.min], max: [...next.bounds.max] };
+}
+/** R-23: write `data` (itemSize floats per vertex) into the named custom attribute starting at vertex `start`. */
+function writeCustomAttribute(vertexBuffer, name, itemSize, data, start) {
+    const semantic = customAttributeSemantic(name);
+    const elements = data.length / itemSize;
+    const scratch = new Array(itemSize);
+    for (let element = 0; element < elements; element += 1) {
+        for (let component = 0; component < itemSize; component += 1)
+            scratch[component] = data[element * itemSize + component] ?? 0;
+        vertexBuffer.setAttribute(start + element, semantic, scratch);
+    }
+}
+/** R-23: the live buffer holds exactly the spec's custom attributes (same names, same itemSize). */
+function customFootprintMatches(vertexBuffer, custom) {
+    const live = vertexBuffer.format.attributes.filter((attribute) => String(attribute.semantic).startsWith("custom:"));
+    if (live.length !== custom.length)
+        return false;
+    return custom.every((entry) => {
+        const semantic = customAttributeSemantic(entry.name);
+        return vertexBuffer.format.hasAttribute(semantic) && vertexBuffer.format.getAttribute(semantic).components === entry.itemSize;
+    });
+}
+/** SG-05 `updateAttribute`: partial write by element offset — dirty-ranged, never reallocates. */
+function applyAttributeUpdateToGeometry(geometry, update) {
+    // R-23: exact-name custom attributes win; validated names never collide with the built-in aliases.
+    const customSemantic = customAttributeSemantic(update.name);
+    const semantic = geometry.vertexBuffer.format.hasAttribute(customSemantic) ? customSemantic : L2_UPDATE_SEMANTICS[update.name.toLowerCase()];
+    if (!semantic) {
+        throw new Error(`Aura3D updateAttribute name "${update.name}" is not a writable vertex semantic (position/normal/uv/uv1/color/tangent) or a custom attribute on this geometry.`);
+    }
+    const vertexBuffer = geometry.vertexBuffer;
+    if (!vertexBuffer.format.hasAttribute(semantic)) {
+        throw new Error(`Aura3D updateAttribute("${update.name}") — the live geometry has no "${semantic}" attribute.`);
+    }
+    const components = vertexBuffer.format.getAttribute(semantic).components;
+    const data = update.array;
+    if (data.length % components !== 0) {
+        throw new Error(`Aura3D updateAttribute("${update.name}") array length must be a multiple of ${components}.`);
+    }
+    const start = Math.max(0, Math.floor(update.offset));
+    const elements = data.length / components;
+    if (start + elements > vertexBuffer.vertexCount) {
+        throw new Error(`Aura3D updateAttribute("${update.name}") overruns the vertex buffer (${vertexBuffer.vertexCount} vertices).`);
+    }
+    const scratch = new Array(components);
+    for (let element = 0; element < elements; element += 1) {
+        for (let component = 0; component < components; component += 1) {
+            scratch[component] = data[element * components + component] ?? 0;
+        }
+        vertexBuffer.setAttribute(start + element, semantic, scratch);
+    }
 }
 /**
  * Build the production `PBRMaterial` for a primitive node.