@aura3d/engine 4.0.3 → 4.0.4

package/dist/rendering/Renderer.js

@@ -258,6 +258,27 @@ export class Renderer {
         }
         return this.device.getDiagnostics();
     }
+    /**
+     * threejs-parity L7/SR-07: `renderer.precompile` — compiles (and awaits) the
+     * generated programs a source needs before first render, without submitting
+     * a frame. Returns the number of programs this call compiled and wall time.
+     */
+    async precompile(sourceOrInput, camera) {
+        this.assertAlive();
+        const startedAt = typeof performance !== "undefined" ? performance.now() : Date.now();
+        const { source, camera: inputCamera } = normalizeRendererInput(sourceOrInput, camera);
+        sceneFromSource(source)?.updateWorldTransforms();
+        const resolvedCamera = resolveCamera(source, inputCamera, { width: this.width, height: this.height }, { allowSceneCamera: true });
+        const cameraViewProjection = resolvedCamera?.viewProjectionMatrix;
+        const collected = collectRenderItemsWithDiagnostics(source, cameraViewProjection, resolvedCamera?.camera);
+        const before = this.device.getDiagnostics().programCompileCount ?? 0;
+        await this.warmGeneratedPrograms(collected.items, collectRenderLights(source), collectEnvironmentLighting(source), collectEnvironmentFog(source), collectForwardShadowMap(source), cameraViewProjection);
+        const after = this.device.getDiagnostics().programCompileCount ?? before;
+        return {
+            compiledPrograms: Math.max(0, after - before),
+            durationMs: (typeof performance !== "undefined" ? performance.now() : Date.now()) - startedAt
+        };
+    }
     /** C-28 (#91): run `fn` under the frameStats "post" scope when a monitor exists. */
     scopePost(fn) {
         return this.frameStatsMonitor ? this.frameStatsMonitor.scope("post", fn) : fn();
@@ -314,7 +335,7 @@ export class Renderer {
         const devicePixelRatio = resolveCanvasPixelRatio({
             devicePixelRatio: globalThis.devicePixelRatio ?? 1,
             tier: this.qualityTier ?? this.liveQualityTier()?.settings ?? { maxPixelRatio: Number.POSITIVE_INFINITY },
-            explicit: options.devicePixelRatio,
+            explicit: options.devicePixelRatio ?? this.pixelRatioOverride,
             resolution: this.resolutionOptions
         });
         if (![cssWidth, cssHeight, devicePixelRatio].every(Number.isFinite) || cssWidth <= 0 || cssHeight <= 0 || devicePixelRatio <= 0) {
@@ -362,6 +383,68 @@ export class Renderer {
             backingHeight: this.height
         };
     }
+    /**
+     * threejs-parity L7/SH-05: `setPixelRatio` — overrides the device pixel
+     * ratio used by `resizeToDisplay` (a `devicePixelRatio` option there still
+     * wins for that call). Applies immediately on a canvas-backed renderer;
+     * stored for the next resize otherwise.
+     */
+    pixelRatioOverride;
+    setPixelRatio(ratio) {
+        this.assertAlive();
+        if (!Number.isFinite(ratio) || ratio <= 0) {
+            throw new RenderDeviceError("Pixel ratio must be a positive finite number", "INVALID_PIXEL_RATIO", { ratio });
+        }
+        this.pixelRatioOverride = ratio;
+        if (this.canvas)
+            this.resizeToDisplay();
+    }
+    get pixelRatio() {
+        return this.pixelRatioOverride ?? this.resolutionReport.pixelRatio;
+    }
+    /**
+     * threejs-parity L7/SH-05: `setClearColor` — the default clear used when the
+     * scene has no background (three's `setClearColor(color, alpha)`).
+     */
+    setClearColor(color, alpha) {
+        this.assertAlive();
+        const [r, g, b, a] = color;
+        const resolved = [r ?? 0, g ?? 0, b ?? 0, alpha ?? a ?? 1];
+        if (!resolved.every((v) => Number.isFinite(v) && v >= 0 && v <= 1)) {
+            throw new RenderDeviceError("Clear color channels must be finite numbers in [0, 1]", "INVALID_CLEAR_COLOR", { color: [...color], alpha });
+        }
+        this.clearColor = resolved;
+    }
+    get clearColorValue() {
+        return this.clearColor;
+    }
+    /**
+     * threejs-parity L7/SR-05: three's `WebGLRenderer.info` — per-frame render
+     * counters plus live resource gauges from the device diagnostics.
+     */
+    submittedFrames = 0;
+    get info() {
+        const d = this.device.getDiagnostics();
+        const memoryBytes = (d.bufferBytes ?? 0) + (d.textureBytes ?? 0);
+        return {
+            render: {
+                calls: d.drawCalls,
+                triangles: d.triangles ?? 0,
+                points: d.points ?? 0,
+                lines: d.lines ?? 0,
+                frame: this.submittedFrames
+            },
+            memory: {
+                geometries: d.buffers,
+                textures: d.textures ?? 0,
+                ...(d.renderTargets !== undefined ? { renderTargets: d.renderTargets } : {}),
+                programs: d.shaders
+            },
+            ...(d.approximateGpuMemoryBytes !== undefined || memoryBytes > 0
+                ? { approximateGpuMemoryBytes: d.approximateGpuMemoryBytes ?? memoryBytes }
+                : {})
+        };
+    }
     /**
      * Feeds one frame's timings to the resolution governor (C-28 `gpuMs` wins
      * over the CPU interval when lane 11's timer queries provide it).
@@ -399,10 +482,101 @@ export class Renderer {
         this.temporalHistory.commit();
     }
     resetTemporalHistory(_reason = "explicit-reset") { this.temporalHistory.reset(); this.lastTemporalCameraPosition = undefined; }
+    /**
+     * threejs-parity L7/SH-06: a `{ target }` (or `source.renderTarget`) frame
+     * executes at the target's own dimensions — three's `setRenderTarget` +
+     * `render` semantics. Viewport state restores when the frame exits.
+     */
+    adoptExplicitTargetSize(source, run) {
+        const target = collectRenderTarget(source);
+        if (!target || (target.width === this.width && target.height === this.height))
+            return run();
+        const prevWidth = this.width;
+        const prevHeight = this.height;
+        this.width = target.width;
+        this.height = target.height;
+        // Stale temporal history at the old size would misproject; drop it.
+        this.temporalHistory.dispose();
+        try {
+            return run();
+        }
+        finally {
+            this.width = prevWidth;
+            this.height = prevHeight;
+        }
+    }
+    async adoptExplicitTargetSizeAsync(source, run) {
+        const target = collectRenderTarget(source);
+        if (!target || (target.width === this.width && target.height === this.height))
+            return run();
+        const prevWidth = this.width;
+        const prevHeight = this.height;
+        this.width = target.width;
+        this.height = target.height;
+        this.temporalHistory.dispose();
+        try {
+            return await run();
+        }
+        finally {
+            this.width = prevWidth;
+            this.height = prevHeight;
+        }
+    }
     render(sourceOrInput, camera) {
         // T0-28: ambient `rendererQrFlags()` readers (Lighting, Background, post…)
         // see this renderer's flags for the duration of the synchronous frame.
-        return withRendererQrFlags(this.device, () => this.renderFrame(sourceOrInput, camera));
+        const views = collectRendererViews(sourceOrInput);
+        if (views) {
+            let last;
+            views.forEach((view, index) => {
+                const viewInput = viewFrameInput(sourceOrInput, camera, view);
+                this.pendingViewState = { viewport: view.viewport, scissor: view.scissor ?? view.viewport, skipClear: index > 0 };
+                try {
+                    last = withRendererQrFlags(this.device, () => this.adoptExplicitTargetSize(viewInput.source, () => this.renderFrame(viewInput)));
+                }
+                finally {
+                    this.pendingViewState = null;
+                }
+            });
+            return last;
+        }
+        this.pendingViewState = collectSingleViewState(sourceOrInput);
+        try {
+            return withRendererQrFlags(this.device, () => this.adoptExplicitTargetSize(normalizeRendererInput(sourceOrInput, camera).source, () => this.renderFrame(sourceOrInput, camera)));
+        }
+        finally {
+            this.pendingViewState = null;
+        }
+    }
+    /** SC-01: viewport/scissor requested for the frame about to bind its main target; consumed by `clearAndApplyView`. */
+    pendingViewState = null;
+    clearAndApplyView(clearColor) {
+        const state = this.pendingViewState;
+        this.pendingViewState = null;
+        if (!state) {
+            this.device.clear(clearColor);
+            return;
+        }
+        if (!this.device.setViewport || !this.device.setScissor || !this.device.setScissorTest) {
+            throw new RenderDeviceError("This render device does not support viewport/scissor rendering.", "VIEWPORT_UNSUPPORTED", { backend: this.device.kind });
+        }
+        // The clear runs before the viewport/scissor apply so it covers the whole
+        // target (a WebGPU clear is a full-attachment load op and cannot be scissored).
+        if (!state.skipClear)
+            this.device.clear(clearColor);
+        validateViewRect("viewport", state.viewport, this.width, this.height);
+        this.device.setViewport(state.viewport.x, state.viewport.y, state.viewport.width, state.viewport.height);
+        if (state.scissor) {
+            validateViewRect("scissor", state.scissor, this.width, this.height);
+            this.device.setScissor(state.scissor.x, state.scissor.y, state.scissor.width, state.scissor.height);
+            this.device.setScissorTest(true);
+        }
+    }
+    assertViewsSupported(postprocess) {
+        if (this.pendingViewState && postprocess) {
+            this.pendingViewState = null;
+            throw new RenderDeviceError("Viewport/scissor views (ArrayCamera / StereoCamera) cannot be combined with postprocess; render the views without effects.", "VIEWPORT_POSTPROCESS_UNSUPPORTED", { backend: this.device.kind });
+        }
     }
     renderFrame(sourceOrInput, camera) {
         this.assertAlive();
@@ -426,7 +600,7 @@ export class Renderer {
             throw new RenderDeviceError("RenderSource requires an explicit camera but none was supplied or found in the scene.", "CAMERA_REQUIRED");
         }
         let cameraViewProjection = resolvedCamera?.viewProjectionMatrix;
-        const collectedItems = collectRenderItemsWithDiagnostics(source, cameraViewProjection, resolvedCamera?.camera, rendererQrFlags().on("A3D_QR_LIGHTING"));
+        const collectedItems = collectRenderItemsWithDiagnostics(source, cameraViewProjection, resolvedCamera?.camera, rendererQrFlags().on("A3D_QR_LIGHTING"), resolvedCamera?.layerMask);
         const collectionDiagnostics = collectedItems.diagnostics;
         let items = collectedItems.items;
         const lights = collectRenderLights(source);
@@ -440,7 +614,7 @@ export class Renderer {
         this.warmGeneratedProgramsSync(items, lights, environmentLighting, environmentFog, explicitShadowMap, cameraViewProjection);
         const sourceCameraPosition = collectSourceCameraPosition(source);
         const explicitRenderTarget = collectRenderTarget(source);
-        validateExplicitRenderTarget(explicitRenderTarget, this.width, this.height);
+        validateExplicitRenderTarget(explicitRenderTarget);
         let cameraPosition = sourceCameraPosition ?? resolvedCamera?.cameraPosition;
         // C-05/T0-07: decide the frame's output route before the hooks exist, so
         // contributors see the same v2/legacy resource names the graph writes.
@@ -464,6 +638,7 @@ export class Renderer {
             }
         }
         let postprocess = collectPostprocess(source);
+        this.assertViewsSupported(postprocess);
         if (!postprocess?.temporal || (!postprocess.motionBlur && !postprocess.taa)) {
             this.temporalHistory.reset();
             this.lastTemporalCameraPosition = undefined;
@@ -588,7 +763,7 @@ export class Renderer {
             else {
                 this.device.setRenderTarget(explicitRenderTarget ?? null);
             }
-            this.device.clear(qrOutput && !postprocess ? this.outputClearColor ?? this.clearColor : this.clearColor);
+            this.clearAndApplyView(qrOutput && !postprocess ? this.outputClearColor ?? this.clearColor : this.clearColor);
             if (environmentBackground) {
                 this.graph.addPass(new EnvironmentBackgroundPass({
                     ...environmentBackground,
@@ -646,6 +821,9 @@ export class Renderer {
                     cameraPosition,
                     cameraViewMatrix: resolvedCamera?.viewMatrix,
                     cameraViewProjectionMatrix: rasterViewProjection,
+                    // SH-02: `material.custom` frame built-ins (u_projectionMatrix, u_time).
+                    auraFrameCamera: resolvedCamera?.projectionMatrix ? { projectionMatrix: resolvedCamera.projectionMatrix } : undefined,
+                    timeSeconds: typeof performance !== "undefined" ? performance.now() / 1000 : Date.now() / 1000,
                     outputColorSpace: "linear",
                     shaderLibrary: this.shaderLibrary,
                     backgroundCoverage: coverage,
@@ -687,6 +865,9 @@ export class Renderer {
                     cameraPosition,
                     cameraViewMatrix: resolvedCamera?.viewMatrix,
                     cameraViewProjectionMatrix: rasterViewProjection,
+                    // SH-02: `material.custom` frame built-ins (u_projectionMatrix, u_time).
+                    auraFrameCamera: resolvedCamera?.projectionMatrix ? { projectionMatrix: resolvedCamera.projectionMatrix } : undefined,
+                    timeSeconds: typeof performance !== "undefined" ? performance.now() / 1000 : Date.now() / 1000,
                     outputColorSpace: postprocess ? "linear" : "srgb",
                     shaderLibrary: this.shaderLibrary
                 }));
@@ -760,6 +941,7 @@ export class Renderer {
                 target.dispose();
             }
         }
+        this.submittedFrames += 1;
         this.submittedShadowFrameId += 1;
         if (this.lastShadowEvidence)
             this.lastShadowEvidence = { ...this.lastShadowEvidence, submissionFrameId: this.submittedShadowFrameId };
@@ -770,6 +952,32 @@ export class Renderer {
         }));
     }
     async renderAsync(sourceOrInput, camera) {
+        const views = collectRendererViews(sourceOrInput);
+        if (views) {
+            let last;
+            for (let index = 0; index < views.length; index += 1) {
+                const view = views[index];
+                const viewInput = viewFrameInput(sourceOrInput, camera, view);
+                this.pendingViewState = { viewport: view.viewport, scissor: view.scissor ?? view.viewport, skipClear: index > 0 };
+                try {
+                    last = await this.adoptExplicitTargetSizeAsync(viewInput.source, () => this.renderAsyncFrame(viewInput));
+                }
+                finally {
+                    this.pendingViewState = null;
+                }
+            }
+            return last;
+        }
+        this.pendingViewState = collectSingleViewState(sourceOrInput);
+        // threejs-parity L7/SH-06: `{ target }` frames run at the target's size.
+        try {
+            return await this.adoptExplicitTargetSizeAsync(normalizeRendererInput(sourceOrInput, camera).source, () => this.renderAsyncFrame(sourceOrInput, camera));
+        }
+        finally {
+            this.pendingViewState = null;
+        }
+    }
+    async renderAsyncFrame(sourceOrInput, camera) {
         this.assertAlive();
         this.frameStatsMonitor?.begin(typeof performance !== "undefined" ? performance.now() : Date.now());
         // T0-06: reset the per-frame sync-compile bound for this render.
@@ -790,7 +998,7 @@ export class Renderer {
             throw new RenderDeviceError("RenderSource requires an explicit camera but none was supplied or found in the scene.", "CAMERA_REQUIRED");
         }
         let cameraViewProjection = resolvedCamera?.viewProjectionMatrix;
-        const collectedItems = collectRenderItemsWithDiagnostics(source, cameraViewProjection, resolvedCamera?.camera, rendererQrFlags().on("A3D_QR_LIGHTING"));
+        const collectedItems = collectRenderItemsWithDiagnostics(source, cameraViewProjection, resolvedCamera?.camera, rendererQrFlags().on("A3D_QR_LIGHTING"), resolvedCamera?.layerMask);
         const collectionDiagnostics = collectedItems.diagnostics;
         let items = collectedItems.items;
         const lights = collectRenderLights(source);
@@ -807,7 +1015,7 @@ export class Renderer {
         }
         const sourceCameraPosition = collectSourceCameraPosition(source);
         const explicitRenderTarget = collectRenderTarget(source);
-        validateExplicitRenderTarget(explicitRenderTarget, this.width, this.height);
+        validateExplicitRenderTarget(explicitRenderTarget);
         let cameraPosition = sourceCameraPosition ?? resolvedCamera?.cameraPosition;
         // C-05/T0-07: decide the frame's output route before the hooks exist, so
         // contributors see the same v2/legacy resource names the graph writes.
@@ -831,6 +1039,7 @@ export class Renderer {
             }
         }
         let postprocess = collectPostprocess(source);
+        this.assertViewsSupported(postprocess);
         if (!postprocess?.temporal || (!postprocess.motionBlur && !postprocess.taa)) {
             this.temporalHistory.reset();
             this.lastTemporalCameraPosition = undefined;
@@ -955,7 +1164,7 @@ export class Renderer {
             else {
                 this.device.setRenderTarget(explicitRenderTarget ?? null);
             }
-            this.device.clear(qrOutput && !postprocess ? this.outputClearColor ?? this.clearColor : this.clearColor);
+            this.clearAndApplyView(qrOutput && !postprocess ? this.outputClearColor ?? this.clearColor : this.clearColor);
             if (environmentBackground) {
                 this.graph.addPass(new EnvironmentBackgroundPass({
                     ...environmentBackground,
@@ -1013,6 +1222,9 @@ export class Renderer {
                     cameraPosition,
                     cameraViewMatrix: resolvedCamera?.viewMatrix,
                     cameraViewProjectionMatrix: rasterViewProjection,
+                    // SH-02: `material.custom` frame built-ins (u_projectionMatrix, u_time).
+                    auraFrameCamera: resolvedCamera?.projectionMatrix ? { projectionMatrix: resolvedCamera.projectionMatrix } : undefined,
+                    timeSeconds: typeof performance !== "undefined" ? performance.now() / 1000 : Date.now() / 1000,
                     outputColorSpace: "linear",
                     shaderLibrary: this.shaderLibrary,
                     backgroundCoverage: coverage,
@@ -1054,6 +1266,9 @@ export class Renderer {
                     cameraPosition,
                     cameraViewMatrix: resolvedCamera?.viewMatrix,
                     cameraViewProjectionMatrix: rasterViewProjection,
+                    // SH-02: `material.custom` frame built-ins (u_projectionMatrix, u_time).
+                    auraFrameCamera: resolvedCamera?.projectionMatrix ? { projectionMatrix: resolvedCamera.projectionMatrix } : undefined,
+                    timeSeconds: typeof performance !== "undefined" ? performance.now() / 1000 : Date.now() / 1000,
                     outputColorSpace: postprocess ? "linear" : "srgb",
                     shaderLibrary: this.shaderLibrary
                 }));
@@ -1135,6 +1350,7 @@ export class Renderer {
                 target.dispose();
             }
         }
+        this.submittedFrames += 1;
         this.submittedShadowFrameId += 1;
         if (this.lastShadowEvidence)
             this.lastShadowEvidence = { ...this.lastShadowEvidence, submissionFrameId: this.submittedShadowFrameId };
@@ -1548,7 +1764,7 @@ function inferInitialCanvasDimension(canvas, axis) {
 function collectRenderTarget(source) {
     return source instanceof Scene || isIterable(source) ? undefined : source.renderTarget;
 }
-function validateExplicitRenderTarget(target, width, height) {
+function validateExplicitRenderTarget(target) {
     if (!target)
         return;
     if (target.disposed) {
@@ -1556,25 +1772,81 @@ function validateExplicitRenderTarget(target, width, height) {
             renderTarget: target.label
         });
     }
-    if (target.width !== width || target.height !== height) {
-        throw new RenderDeviceError("Renderer renderTarget dimensions must match the renderer viewport.", "RENDER_TARGET_VIEWPORT_MISMATCH", {
-            renderTarget: target.label,
-            targetWidth: target.width,
-            targetHeight: target.height,
-            rendererWidth: width,
-            rendererHeight: height
-        });
-    }
+    // threejs-parity L7/SH-06: no viewport-dimensions check — a `{ target }`
+    // frame executes at the target's own size (`adoptExplicitTargetSize`).
 }
 function normalizeRendererInput(sourceOrInput, camera) {
     if (isRendererInput(sourceOrInput)) {
-        return { source: sourceOrInput.source, camera: camera ?? sourceOrInput.camera };
+        const target = sourceOrInput.target;
+        const source = target ? withExplicitRenderTarget(sourceOrInput.source, target) : sourceOrInput.source;
+        return { source, camera: camera ?? sourceOrInput.camera };
     }
     return { source: sourceOrInput, ...(camera ? { camera } : {}) };
 }
+function collectRendererViews(sourceOrInput) {
+    if (sourceOrInput instanceof Scene || isIterable(sourceOrInput))
+        return undefined;
+    const views = isRendererInput(sourceOrInput)
+        ? sourceOrInput.views ?? (sourceOrInput.source instanceof Scene || isIterable(sourceOrInput.source) ? undefined : sourceOrInput.source.views)
+        : sourceOrInput.views;
+    if (!views)
+        return undefined;
+    if (views.length === 0) {
+        throw new RenderDeviceError("Renderer views must contain at least one view.", "INVALID_VIEWPORT", { views: 0 });
+    }
+    return views;
+}
+function collectSingleViewState(sourceOrInput) {
+    if (sourceOrInput instanceof Scene || isIterable(sourceOrInput) || !isRendererInput(sourceOrInput))
+        return null;
+    if (!sourceOrInput.viewport && !sourceOrInput.scissor)
+        return null;
+    const viewport = sourceOrInput.viewport;
+    const scissor = sourceOrInput.scissor ?? viewport;
+    return {
+        viewport: viewport ?? scissor,
+        scissor,
+        skipClear: false
+    };
+}
+function viewFrameInput(sourceOrInput, camera, view) {
+    const normalized = normalizeRendererInput(sourceOrInput, camera);
+    const base = normalized.source instanceof Scene
+        ? { scene: normalized.source }
+        : isIterable(normalized.source) ? { renderItems: normalized.source } : normalized.source;
+    const { views: _views, ...rest } = base;
+    return {
+        source: { ...rest, ...(view.cameraPosition ? { cameraPosition: view.cameraPosition } : {}) },
+        camera: view.camera
+    };
+}
+function validateViewRect(label, rect, targetWidth, targetHeight) {
+    const values = [rect.x, rect.y, rect.width, rect.height];
+    if (values.some((value) => !Number.isFinite(value))) {
+        throw new RenderDeviceError(`Renderer ${label} values must be finite.`, "INVALID_VIEWPORT", { label, rect });
+    }
+    if (rect.width <= 0 || rect.height <= 0) {
+        throw new RenderDeviceError(`Renderer ${label} dimensions must be positive.`, "INVALID_VIEWPORT", { label, rect });
+    }
+    if (rect.x < 0 || rect.y < 0 || rect.x + rect.width > targetWidth || rect.y + rect.height > targetHeight) {
+        throw new RenderDeviceError(`Renderer ${label} must lie inside the ${targetWidth}x${targetHeight} target.`, "INVALID_VIEWPORT", { label, rect, targetWidth, targetHeight });
+    }
+}
 function isRendererInput(value) {
     return !(value instanceof Scene) && !isIterable(value) && isRecord(value) && "source" in value;
 }
+/**
+ * threejs-parity L7/SH-06: fold a `{ target }` render input into the source's
+ * `renderTarget` carry — Scene wraps as `{ scene }`, iterables as
+ * `{ renderItems }`, a RenderSource keeps every other authored field.
+ */
+function withExplicitRenderTarget(source, target) {
+    if (source instanceof Scene)
+        return { scene: source, renderTarget: target };
+    if (isIterable(source))
+        return { renderItems: source, renderTarget: target };
+    return { ...source, renderTarget: target };
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
@@ -1605,7 +1877,7 @@ function collectSourceCameraPosition(source) {
 export function collectRenderItems(source, cameraViewProjection, camera) {
     return collectRenderItemsWithDiagnostics(source, cameraViewProjection, camera).items;
 }
-function collectRenderItemsWithDiagnostics(source, cameraViewProjection, camera, keepCulledShadowCasters = false) {
+function collectRenderItemsWithDiagnostics(source, cameraViewProjection, camera, keepCulledShadowCasters = false, cameraLayerMask) {
     const diagnostics = createRenderCollectionDiagnostics();
     // 02-S5 (A3D_QR_LIGHTING): frustum-culled items that still cast. A caster
     // outside the view (a pole behind the camera under a low sun) must reach
@@ -1618,7 +1890,7 @@ function collectRenderItemsWithDiagnostics(source, cameraViewProjection, camera,
         return { items, diagnostics, culledShadowCasters: culledShadowCasters ?? [] };
     }
     if (source instanceof Scene) {
-        const items = collectSceneRenderItems(source, {}, cameraViewProjection, camera, diagnostics, culledShadowCasters);
+        const items = collectSceneRenderItems(source, {}, cameraViewProjection, camera, diagnostics, culledShadowCasters, cameraLayerMask);
         return { items, diagnostics, culledShadowCasters: culledShadowCasters ?? [], ...(camera ? { cullingFrustum: camera.frustum } : {}) };
     }
     const items = [];
@@ -1626,7 +1898,7 @@ function collectRenderItemsWithDiagnostics(source, cameraViewProjection, camera,
     if (source.scene) {
         if (source.frustumCulling !== false && camera)
             cullingFrustum = camera.frustum;
-        items.push(...collectSceneRenderItems(source.scene, source, cameraViewProjection, source.frustumCulling === false ? undefined : camera, diagnostics, culledShadowCasters));
+        items.push(...collectSceneRenderItems(source.scene, source, cameraViewProjection, source.frustumCulling === false ? undefined : camera, diagnostics, culledShadowCasters, cameraLayerMask));
     }
     const explicitItems = [];
     if (source.collectRenderItems) {
@@ -1638,14 +1910,14 @@ function collectRenderItemsWithDiagnostics(source, cameraViewProjection, camera,
     if (explicitItems.length > 0) {
         const explicitFrustum = explicitCullingFrustum(source, cameraViewProjection, camera);
         cullingFrustum ??= explicitFrustum;
-        const visibleItems = cullExplicitRenderItems(explicitItems, explicitFrustum, diagnostics, culledShadowCasters);
+        const visibleItems = cullExplicitRenderItems(explicitItems, explicitFrustum, diagnostics, culledShadowCasters, cameraLayerMask ?? camera?.layerMask);
         const optimizedItems = applyRendererOwnedStaticBatching(source, applyRendererOwnedStaticMeshConsolidation(source, visibleItems));
         const projectedItems = applyViewProjection(optimizedItems, cameraViewProjection);
         items.push(...projectedItems);
     }
     return { items, diagnostics, culledShadowCasters: culledShadowCasters ?? [], ...(cullingFrustum ? { cullingFrustum } : {}) };
 }
-function collectSceneRenderItems(scene, source, cameraViewProjection, camera, diagnostics, culledShadowCasters) {
+function collectSceneRenderItems(scene, source, cameraViewProjection, camera, diagnostics, culledShadowCasters, explicitCameraLayerMask) {
     scene.updateWorldTransforms();
     const renderables = scene.collectRenderables();
     if (renderables.length === 0) {
@@ -1657,7 +1929,12 @@ function collectSceneRenderItems(scene, source, cameraViewProjection, camera, di
         });
     }
     const items = [];
+    const cameraLayerMask = explicitCameraLayerMask ?? camera?.layerMask;
     for (const { node, renderable } of renderables) {
+        // threejs-parity L7/SG-10: three's camera.layers test — a node whose
+        // layers do not intersect the camera mask is absent from the frame.
+        if (cameraLayerMask !== undefined && (node.layerMask & cameraLayerMask) === 0)
+            continue;
         const geometry = lookupRenderResource(source.geometryLibrary, renderable.geometry);
         const material = lookupRenderResource(source.materialLibrary, renderable.material);
         if (!geometry) {
@@ -1687,7 +1964,9 @@ function collectSceneRenderItems(scene, source, cameraViewProjection, camera, di
             if (camera)
                 diagnostics.frustumTestedObjects += 1;
         }
-        const culled = camera !== undefined && !camera.frustum.intersectsBox(bounds.toMathBox());
+        // threejs-parity L7/SG-09: `node.frustumCulled === false` skips the test
+        // (three.js `object.frustumCulled` semantics).
+        const culled = camera !== undefined && node.frustumCulled !== false && !camera.frustum.intersectsBox(bounds.toMathBox());
         if (culled && diagnostics)
             diagnostics.culledObjects += 1;
         if (culled && !culledShadowCasters)
@@ -1699,6 +1978,15 @@ function collectSceneRenderItems(scene, source, cameraViewProjection, camera, di
             material,
             label: node.name,
             modelMatrix,
+            // threejs-parity L7/SG-09: carry the node's parity fields onto the item
+            // so sort/cull/onBeforeRender behave like three's Object3D.
+            renderOrder: node.renderOrder,
+            layerMask: node.layerMask,
+            frustumCulled: node.frustumCulled,
+            userData: node.userData,
+            ...(node.onBeforeRender
+                ? { onBeforeRender: () => node.onBeforeRender(undefined, node) }
+                : {}),
             normalMatrix: normalMatrixFromModel(modelMatrix),
             modelViewProjectionMatrix: multiplyMat4(cameraViewProjection ?? identityMat4(), modelMatrix),
             ...(renderable.skinning ? { skinning: renderable.skinning } : {}),
@@ -2055,6 +2343,7 @@ function resolveCamera(source, camera, viewport, options = {}) {
     if (!resolved) {
         return undefined;
     }
+    const resolvedLayerMask = typeof resolved.layerMask === "number" ? { layerMask: resolved.layerMask } : {};
     const resize = maybeCameraResize(resolved);
     if (viewport && resize) {
         resize(viewport.width, viewport.height);
@@ -2064,7 +2353,10 @@ function resolveCamera(source, camera, viewport, options = {}) {
         const viewMatrix = resolved.viewMatrix ? toMat4(resolved.viewMatrix, "viewMatrix") : undefined;
         return {
             viewProjectionMatrix: toMat4(resolved.viewProjectionMatrix, "viewProjectionMatrix"),
+            ...resolvedLayerMask,
             ...(viewMatrix ? { viewMatrix } : {}),
+            // threejs-parity SH-02: custom-shader `u_projectionMatrix` source.
+            ...(resolved.projectionMatrix ? { projectionMatrix: toMat4(resolved.projectionMatrix, "projectionMatrix") } : {}),
             ...(resolved instanceof Camera
                 ? { camera: resolved, cameraPosition: cameraWorldPosition(resolved) }
                 : viewMatrix
@@ -2074,9 +2366,12 @@ function resolveCamera(source, camera, viewport, options = {}) {
     }
     if (resolved.projectionMatrix && resolved.viewMatrix) {
         const viewMatrix = toMat4(resolved.viewMatrix, "viewMatrix");
+        const projectionMatrix = toMat4(resolved.projectionMatrix, "projectionMatrix");
         return {
-            viewProjectionMatrix: multiplyMat4(toMat4(resolved.projectionMatrix, "projectionMatrix"), viewMatrix),
+            viewProjectionMatrix: multiplyMat4(projectionMatrix, viewMatrix),
+            ...resolvedLayerMask,
             viewMatrix,
+            projectionMatrix,
             ...(resolved instanceof Camera
                 ? { camera: resolved, cameraPosition: cameraWorldPosition(resolved) }
                 : { cameraPosition: cameraPositionFromViewMatrix(viewMatrix) })