@pascal-app/viewer 0.8.0 → 0.9.2

package/dist/components/viewer/post-processing.js

@@ -1,13 +1,26 @@
 import { useFrame, useThree } from '@react-three/fiber';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { Color, Layers, UnsignedByteType } from 'three';
+import { Color, Layers, Matrix4, Scene, UnsignedByteType } from 'three';
 import { ssgi } from 'three/addons/tsl/display/SSGINode.js';
 import { denoise } from 'three/examples/jsm/tsl/display/DenoiseNode.js';
-import { add, colorToDirection, diffuseColor, directionToColor, float, mix, mrt, normalView, oscSine, output, pass, sample, time, uniform, vec4, } from 'three/tsl';
+import { add, diffuseColor, float, mix, mrt, normalView, oscSine, output, pass, premultiplyAlpha, renderOutput, sample, saturation, screenUV, smoothstep, time, uniform, vec3, vec4, } from 'three/tsl';
 import { RenderPipeline } from 'three/webgpu';
-import { SCENE_LAYER, ZONE_LAYER } from '../../lib/layers';
+import { backdropGradient, deepSkyColor, horizonHazeColor } from '../../lib/backdrop';
+import { edgeColorFor, edgeOpacityScaleFor } from '../../lib/edge-style';
+import { PERF_OVERLAY_ENABLED, pushGpuSample } from '../../lib/gpu-perf';
+import { inkedEdges } from '../../lib/ink-edges';
+import { GRID_LAYER, OVERLAY_LAYER, SCENE_LAYER, ZONE_LAYER } from '../../lib/layers';
 import { mergedOutline } from '../../lib/merged-outline-node';
+import { getSceneTheme } from '../../lib/scene-themes';
+import { packNormalToRGB, unpackRGBToNormal } from '../../lib/tsl-compat';
 import useViewer from '../../store/use-viewer';
+// Scene-referred grade applied before the output tone mapping (AgX). AgX rolls
+// highlights off gently but reads flat on its own; a mild mid-gray-pivot
+// contrast + saturation lift restores the punch. Rendered shading only.
+export const GRADE_PARAMS = {
+    contrast: 1.05,
+    saturation: 1.1,
+};
 // SSGI Parameters - adjust these to fine-tune global illumination and ambient occlusion
 export const SSGI_PARAMS = {
     enabled: true,
@@ -23,10 +36,49 @@ export const SSGI_PARAMS = {
     useScreenSpaceSampling: true,
     useTemporalFiltering: false,
 };
+// Diagnostic toggles for thermal A/B testing. Add `?disable=ao,denoise,outline,postFx`
+// to the URL (any subset) and reload to skip those passes. Each flag prevents
+// allocation + per-frame work for that stage, so device temperature deltas
+// across combos isolate which pass is the actual culprit. Picked up once at
+// pipeline build; reload after changing the URL.
+//   - ao:      skip SSGI entirely (and denoise, since denoise has nothing to denoise)
+//   - denoise: keep SSGI but feed its raw noisy AO straight to the composite
+//   - outline: skip the merged-outline node and its 14 internal RTs
+//   - postFx:  bypass the whole RenderPipeline and use renderer.render(scene, camera)
+//              directly — isolates raw scene-render cost from any post-FX overhead
+//   - draw:    skip the render call entirely — frames still tick (useFrame
+//              systems, scene-ready) but no draw is ever submitted. For
+//              consumers that only need the built scene graph, never pixels:
+//              the headless bake worker renders on SwiftShader (CPU), where
+//              per-frame vertex/draw cost dominates the whole capture.
+function readPerfDisableFlags() {
+    if (typeof window === 'undefined') {
+        return { ao: false, denoise: false, outline: false, postFx: false };
+    }
+    const raw = new URLSearchParams(window.location.search).get('disable') ?? '';
+    const set = new Set(raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean));
+    return {
+        ao: set.has('ao'),
+        denoise: set.has('denoise'),
+        outline: set.has('outline'),
+        postFx: set.has('postFx'),
+    };
+}
+const PERF_POST_FX_DISABLED = typeof window !== 'undefined' &&
+    new Set((new URLSearchParams(window.location.search).get('disable') ?? '')
+        .split(',')
+        .map((s) => s.trim())).has('postFx');
+const PERF_DRAW_DISABLED = typeof window !== 'undefined' &&
+    new Set((new URLSearchParams(window.location.search).get('disable') ?? '')
+        .split(',')
+        .map((s) => s.trim())).has('draw');
+// Stand-in scene for `?disable=draw` frames — cleared, never populated.
+const emptyScene = new Scene();
 const MAX_PIPELINE_RETRIES = 3;
 const RETRY_DELAY_MS = 500;
-const DARK_BG = '#1f2433';
-const LIGHT_BG = '#ffffff';
 const DEFAULT_HOVER_STYLE = {
     visibleColor: 0x00_aa_ff,
     hiddenColor: 0xf3_ff_47,
@@ -47,24 +99,69 @@ function sanitizeOutlineObjects(objects) {
     }
     objects.length = nextIndex;
 }
-const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, }) => {
-    const { gl: renderer, invalidate, scene, camera } = useThree();
+const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, disablePostFx = false, }) => {
+    const { gl: renderer, invalidate, scene, camera, size } = useThree();
     const renderPipelineRef = useRef(null);
     const hasPipelineErrorRef = useRef(false);
     const retryCountRef = useRef(0);
     const rebuildTimeoutRef = useRef(null);
+    const skippedZeroSizeRef = useRef(false);
     // Background color uniform — updated every frame via lerp, read by the TSL pipeline.
-    // Initialised from the current theme so there's no flash on first render.
-    const initBg = useViewer.getState().theme === 'dark' ? DARK_BG : LIGHT_BG;
+    // Initialised from the current scene theme so there's no flash on first render.
+    const initTheme = getSceneTheme(useViewer.getState().sceneTheme);
+    const initBg = initTheme.background;
     const bgUniform = useRef(uniform(new Color(initBg)));
     const bgCurrent = useRef(new Color(initBg));
     const bgTarget = useRef(new Color());
+    // Zenith colour of the backdrop gradient (falls back to the flat background).
+    const initSky = initTheme.backgroundSky ?? initBg;
+    const bgSkyUniform = useRef(uniform(new Color(initSky)));
+    const bgSkyCurrent = useRef(new Color(initSky));
+    const bgSkyTarget = useRef(new Color());
+    // Horizon haze band + deep zenith (derived — see lib/backdrop.ts).
+    const initHaze = horizonHazeColor(initSky, initTheme.appearance);
+    const bgHazeUniform = useRef(uniform(new Color(initHaze)));
+    const bgHazeCurrent = useRef(new Color(initHaze));
+    const bgHazeTarget = useRef(new Color());
+    const initSkyDeep = deepSkyColor(initSky);
+    const bgSkyDeepUniform = useRef(uniform(new Color(initSkyDeep)));
+    const bgSkyDeepCurrent = useRef(new Color(initSkyDeep));
+    const bgSkyDeepTarget = useRef(new Color());
+    // Scene-camera matrices for the backdrop: the pipeline's fullscreen quad has
+    // its own camera, so the sky gradient reconstructs each pixel's world-space
+    // view ray from these to find the true horizon (dir.y = 0).
+    const camProjInvUniform = useRef(uniform(new Matrix4()));
+    const camWorldUniform = useRef(uniform(new Matrix4()));
+    // Ink-line colour follows the scene-theme background luminance (dark lines on
+    // light scenes, light on dark), refreshed each frame like the background.
+    // Dark scenes also scale the ink opacity down (see edge-style.ts).
+    const inkColorUniform = useRef(uniform(new Color(edgeColorFor(initBg))));
+    const inkOpacityScaleUniform = useRef(uniform(edgeOpacityScaleFor(initBg)));
     const zoneLayers = useMemo(() => {
         const l = new Layers();
         l.enable(ZONE_LAYER);
         l.disable(SCENE_LAYER);
         return l;
     }, []);
+    // Scene pass renders the main geometry layer plus the grid. The default camera
+    // mask also has the overlay layer enabled (custom controls enable it for
+    // picking), so without this the gizmos/handles/tool previews land in the
+    // depth+normal MRT and get inked / AO'd as if they were geometry. The grid is
+    // kept in here (not the overlay pass) so scene geometry depth-occludes it; it's
+    // a flat, depth-non-writing plane so the ink never picks it up.
+    const sceneOnlyLayers = useMemo(() => {
+        const l = new Layers();
+        l.set(SCENE_LAYER);
+        l.enable(GRID_LAYER);
+        return l;
+    }, []);
+    // Editor overlays render in their own pass, composited on top after the ink
+    // and outlines so they read as crisp UI rather than scene geometry.
+    const overlayLayers = useMemo(() => {
+        const l = new Layers();
+        l.set(OVERLAY_LAYER);
+        return l;
+    }, []);
     const hoverHighlightMode = useViewer((s) => s.hoverHighlightMode);
     const hoverVisibleColor = useMemo(() => uniform(new Color(DEFAULT_HOVER_STYLE.visibleColor)), []);
     const hoverHiddenColor = useMemo(() => uniform(new Color(DEFAULT_HOVER_STYLE.hiddenColor)), []);
@@ -72,6 +169,11 @@ const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, }) => {
     const hoverPulseMix = useMemo(() => uniform(DEFAULT_HOVER_STYLE.pulse ? 0 : 1), []);
     // Subscribe to projectId so the pipeline rebuilds on project switch
     const projectId = useViewer((s) => s.projectId);
+    const shading = useViewer((s) => s.shading);
+    const edges = useViewer((s) => s.edges);
+    const inkOpacityOverride = useViewer((s) => s.inkOpacity);
+    const transparentBackground = useViewer((s) => s.transparentBackground);
+    const lastProjectIdRef = useRef(projectId);
     // Bump this to force a pipeline rebuild (used by retry logic)
     const [pipelineVersion, setPipelineVersion] = useState(0);
     const requestPipelineRebuild = useCallback(() => {
@@ -83,6 +185,9 @@ const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, }) => {
     }, []);
     // Reset retry state when project changes
     useEffect(() => {
+        if (lastProjectIdRef.current === projectId)
+            return;
+        lastProjectIdRef.current = projectId;
         retryCountRef.current = 0;
         if (rebuildTimeoutRef.current !== null) {
             clearTimeout(rebuildTimeoutRef.current);
@@ -115,6 +220,8 @@ const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, }) => {
     ]);
     // Build / rebuild the post-processing pipeline
     useEffect(() => {
+        const width = Math.floor(size.width);
+        const height = Math.floor(size.height);
         if (!(renderer && scene && camera)) {
             console.warn('[viewer/post-processing] Skipping pipeline build — missing dependency.', {
                 hasRenderer: !!renderer,
@@ -123,14 +230,72 @@ const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, }) => {
             });
             return;
         }
+        if (width < 1 || height < 1) {
+            skippedZeroSizeRef.current = true;
+            hasPipelineErrorRef.current = false;
+            if (renderPipelineRef.current) {
+                renderPipelineRef.current.dispose();
+            }
+            renderPipelineRef.current = null;
+            return;
+        }
+        if (skippedZeroSizeRef.current) {
+            skippedZeroSizeRef.current = false;
+        }
+        const perfDisable = readPerfDisableFlags();
+        // postFx off (host prop or ?disable=postFx): never allocate the pipeline —
+        // useFrame's null-pipeline branch direct-renders. Before this check the
+        // URL flag only skipped the pipeline at render time; the build still
+        // allocated every pass.
+        if (disablePostFx || perfDisable.postFx) {
+            hasPipelineErrorRef.current = false;
+            if (renderPipelineRef.current) {
+                renderPipelineRef.current.dispose();
+            }
+            renderPipelineRef.current = null;
+            return;
+        }
+        const ssgiEnabled = shading === 'rendered' && SSGI_PARAMS.enabled && !perfDisable.ao;
+        const denoiseEnabled = ssgiEnabled && !perfDisable.denoise;
+        const outlineEnabled = !perfDisable.outline;
+        const inkEnabled = edges !== 'off';
+        // The depth+normal MRT feeds both SSGI and the screen-space ink pass.
+        const needsNormalMRT = ssgiEnabled || inkEnabled;
+        // Soft = thin (1px sample radius) + faint (50% opacity); strong = thick
+        // (2px, ~2× wider detected band) + solid (100%). The edge masks saturate,
+        // so radius+opacity are what actually separate the two modes — gain wouldn't.
+        // Same 1px line thickness for both (soft's thickness is the nice one);
+        // strong reads heavier purely by being fully solid vs soft's lighter 50%.
+        const inkRadius = 1;
+        const inkOpacity = inkOpacityOverride ?? (edges === 'strong' ? 1 : 0.5);
         console.log('[viewer/post-processing] Building pipeline', {
             version: pipelineVersion,
-            ssgi: SSGI_PARAMS.enabled,
-            hoverHighlightMode,
+            ssgi: ssgiEnabled,
+            denoise: denoiseEnabled,
+            outline: outlineEnabled,
+            perfDisable,
             projectId,
+            shading,
+            transparentBackground,
             rendererCtor: renderer.constructor?.name,
+            width,
+            height,
         });
         hasPipelineErrorRef.current = false;
+        // WebGPU availability check: SSGI, denoise, and RenderPipeline are all
+        // WebGPU-only APIs. When the browser falls back to WebGL2 (no
+        // `navigator.gpu`, or the device couldn't be created), building the
+        // pipeline either throws silently or produces a broken output where
+        // the scene renders for a few frames and then goes black as the retry
+        // loop fights the direct-render fallback path. Short-circuit here so
+        // `useFrame` uses the direct `renderer.render(scene, camera)` path
+        // exclusively and never attempts the TSL pipeline.
+        const hasWebGPU = typeof navigator !== 'undefined' && 'gpu' in navigator;
+        if (!hasWebGPU) {
+            hasPipelineErrorRef.current = true;
+            renderPipelineRef.current = null;
+            return;
+        }
         // Clear outliner arrays synchronously to prevent stale Object3D refs
         // from the previous project leaking into the new pipeline's outline passes.
         const outliner = useViewer.getState().outliner;
@@ -140,8 +305,15 @@ const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, }) => {
         outliner.hoveredObjects.length = 0;
         try {
             const scenePass = pass(scene, camera);
+            scenePass.setLayers(sceneOnlyLayers);
             const zonePass = pass(scene, camera);
             zonePass.setLayers(zoneLayers);
+            // Editor overlays (gizmos, move handles, tool previews, grid) on their own
+            // layer, kept out of the depth/normal MRT above so the ink + SSGI ignore
+            // them, then composited on top of the final image below.
+            const overlayPass = pass(scene, camera);
+            overlayPass.setLayers(overlayLayers);
+            const overlayColor = overlayPass.getTextureNode('output');
             const scenePassColor = scenePass.getTextureNode('output');
             // Background detection via alpha: renderer clears with alpha=0 (setClearAlpha(0) in useFrame),
             // so background pixels have scenePassColor.a=0 while geometry pixels have output.a=1.
@@ -149,24 +321,32 @@ const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, }) => {
             // is the reliable geometry mask — no normals, no flicker.
             const hasGeometry = scenePassColor.a;
             const contentAlpha = hasGeometry.max(zonePass.a);
-            let sceneColor = scenePassColor;
-            if (SSGI_PARAMS.enabled) {
-                // MRT only needed for SSGI (diffuse for GI, normal for SSGI sampling)
+            // Composite the zone-pass tint into the base scene so rooms show whether or
+            // not SSGI is enabled. When SSGI is on, the branch below overwrites this
+            // with its own zone-inclusive composite (no double-add).
+            let sceneColor = vec4(add(scenePassColor.rgb, zonePass.rgb), contentAlpha);
+            // Depth + normal MRT — shared by SSGI (diffuse/normal) and the ink pass
+            // (depth/normal). Built whenever either is active.
+            let scenePassDepth = null;
+            let scenePassNormal = null;
+            let sceneNormal = null;
+            if (needsNormalMRT) {
                 scenePass.setMRT(mrt({
                     output,
                     diffuseColor,
-                    normal: directionToColor(normalView),
+                    normal: packNormalToRGB(normalView),
                 }));
+                scenePassDepth = scenePass.getTextureNode('depth');
+                scenePassNormal = scenePass.getTextureNode('normal');
+                const normalTexture = scenePass.getTexture('normal');
+                normalTexture.type = UnsignedByteType;
+                // Extract normal from color-encoded texture (SSGI consumes the node form)
+                sceneNormal = sample((uv) => unpackRGBToNormal(scenePassNormal.sample(uv)));
+            }
+            if (ssgiEnabled) {
                 const scenePassDiffuse = scenePass.getTextureNode('diffuseColor');
-                const scenePassDepth = scenePass.getTextureNode('depth');
-                const scenePassNormal = scenePass.getTextureNode('normal');
-                // Optimize texture bandwidth
                 const diffuseTexture = scenePass.getTexture('diffuseColor');
                 diffuseTexture.type = UnsignedByteType;
-                const normalTexture = scenePass.getTexture('normal');
-                normalTexture.type = UnsignedByteType;
-                // Extract normal from color-encoded texture
-                const sceneNormal = sample((uv) => colorToDirection(scenePassNormal.sample(uv)));
                 const giPass = ssgi(scenePassColor, scenePassDepth, sceneNormal, camera);
                 giPass.sliceCount.value = SSGI_PARAMS.sliceCount;
                 giPass.stepCount.value = SSGI_PARAMS.stepCount;
@@ -179,50 +359,127 @@ const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, }) => {
                 giPass.useLinearThickness.value = SSGI_PARAMS.useLinearThickness;
                 giPass.useScreenSpaceSampling.value = SSGI_PARAMS.useScreenSpaceSampling;
                 giPass.useTemporalFiltering = SSGI_PARAMS.useTemporalFiltering;
-                const giTexture = giPass.getTextureNode();
-                // DenoiseNode only denoises RGB — alpha is passed through unchanged.
-                // SSGI packs AO into alpha, so we remap it into RGB before denoising.
-                const aoAsRgb = vec4(giTexture.a, giTexture.a, giTexture.a, float(1));
-                const denoisePass = denoise(aoAsRgb, scenePassDepth, sceneNormal, camera);
-                denoisePass.index.value = 0;
-                denoisePass.radius.value = 4;
-                const gi = giPass.rgb;
-                const ao = denoisePass.r;
+                // r185: SSGI renders AO and GI into two separate textures (R8 + RG11B10)
+                // exposed via getAONode()/getGINode() instead of one rgba texture.
+                const aoTexture = giPass.getAONode();
+                const gi = giPass.getGINode().rgb;
+                let ao;
+                if (denoiseEnabled) {
+                    // DenoiseNode only denoises RGB — alpha is passed through unchanged.
+                    // SSGI's AO is a single red channel, so we remap it into RGB before denoising.
+                    const aoAsRgb = vec4(aoTexture.r, aoTexture.r, aoTexture.r, float(1));
+                    const denoisePass = denoise(aoAsRgb, scenePassDepth, sceneNormal, camera);
+                    denoisePass.index.value = 0;
+                    denoisePass.radius.value = 4;
+                    ao = denoisePass.r;
+                }
+                else {
+                    // Diagnostic path: feed raw noisy SSGI AO straight through. Will
+                    // look grainy — that's the point, it isolates denoise cost.
+                    ao = aoTexture.r;
+                }
+                // AO is a near/mid-field cue like the ink: fade it out with raw depth
+                // (same ≈150→350 m window as ink-edges' distanceFade) so the horizon
+                // disc and the geometry↔sky depth cliff never grow an AO band — that
+                // band read as a visible line along the horizon.
+                const aoFarFade = smoothstep(float(0.9994), float(0.9998), scenePassDepth.sample(screenUV).r);
+                ao = mix(ao, float(1), aoFarFade);
                 // Composite: scene * AO + diffuse * GI
                 sceneColor = vec4(add(scenePassColor.rgb.mul(ao), add(zonePass.rgb, scenePassDiffuse.rgb.mul(gi))), contentAlpha);
             }
+            // Screen-space ink outline (SketchUp look) — depth/normal edge detection
+            // over the composited scene. Topology-agnostic, so it handles CSG-cut
+            // walls cleanly. Applied before the selection outline + background mix.
+            if (inkEnabled) {
+                sceneColor = vec4(inkedEdges({
+                    sceneRgb: sceneColor.rgb,
+                    depthTex: scenePassDepth,
+                    normalTex: scenePassNormal,
+                    inkColor: inkColorUniform.current,
+                    radius: inkRadius,
+                    opacity: float(inkOpacity).mul(inkOpacityScaleUniform.current),
+                }), sceneColor.a);
+            }
+            // Scene-referred grade (contrast around mid-gray + saturation) before the
+            // pipeline's output tone mapping. Kept out of solid/schematic shading so
+            // the flat presets stay exact. The same transform is applied to the
+            // backdrop below so geometry that fades to the background colour (the
+            // horizon disc) matches it exactly.
+            const gradeRgb = (rgb) => saturation(rgb.div(0.18).pow(vec3(GRADE_PARAMS.contrast)).mul(0.18), GRADE_PARAMS.saturation);
+            if (shading === 'rendered') {
+                sceneColor = vec4(gradeRgb(sceneColor.rgb), sceneColor.a);
+            }
             // Single merged outline node: one shared depth pass for both selected + hovered groups.
             const outliner = useViewer.getState().outliner;
-            const outlineNode = mergedOutline(scene, camera, {
-                primaryObjects: outliner.selectedObjects,
-                secondaryObjects: outliner.hoveredObjects,
-                primaryEdgeThickness: uniform(1),
-                secondaryEdgeThickness: uniform(1.5),
+            let compositeWithOutlines = sceneColor;
+            let visualAlpha = contentAlpha;
+            if (outlineEnabled) {
+                const outlineNode = mergedOutline(scene, camera, {
+                    primaryObjects: outliner.selectedObjects,
+                    secondaryObjects: outliner.hoveredObjects,
+                    primaryEdgeThickness: uniform(1),
+                    secondaryEdgeThickness: uniform(1.5),
+                });
+                // Selected: white visible, yellow hidden
+                const selectedVisibleColor = uniform(new Color(0xff_ff_ff));
+                const selectedHiddenColor = uniform(new Color(0xf3_ff_47));
+                const selectedStrength = uniform(3);
+                const selectedOutline = outlineNode.primaryVisibleEdge
+                    .mul(selectedVisibleColor)
+                    .add(outlineNode.primaryHiddenEdge.mul(selectedHiddenColor))
+                    .mul(selectedStrength);
+                // Hovered: blue visible, yellow hidden, pulsing
+                const pulsePeriod = uniform(3);
+                const oscillating = oscSine(time.div(pulsePeriod).mul(2)).mul(0.5).add(0.5);
+                const osc = mix(oscillating, float(1), hoverPulseMix);
+                const hoverOutline = outlineNode.secondaryVisibleEdge
+                    .mul(hoverVisibleColor)
+                    .add(outlineNode.secondaryHiddenEdge.mul(hoverHiddenColor))
+                    .mul(hoverStrength)
+                    .mul(osc);
+                const outlineAlpha = outlineNode.primaryVisibleEdge
+                    .max(outlineNode.primaryHiddenEdge)
+                    .max(outlineNode.secondaryVisibleEdge)
+                    .max(outlineNode.secondaryHiddenEdge);
+                visualAlpha = visualAlpha.max(outlineAlpha);
+                compositeWithOutlines = vec4(add(sceneColor.rgb, selectedOutline.add(hoverOutline)), sceneColor.a);
+            }
+            // Backdrop: world-space view ray per pixel → background / horizon haze /
+            // sky gradient (shared formula in lib/backdrop.ts). The horizon disc
+            // dissolves into the same formula, so backdrop and ground meet
+            // seamlessly exactly where the disc vanishes.
+            const ndc = vec4(screenUV.x.mul(2).sub(1), float(1).sub(screenUV.y).mul(2).sub(1), 1, 1);
+            const viewRay = camProjInvUniform.current.mul(ndc);
+            const worldDir = camWorldUniform.current.mul(vec4(viewRay.xyz, 0)).xyz.normalize();
+            let bgGradient = backdropGradient({
+                dirY: worldDir.y,
+                background: bgUniform.current,
+                haze: bgHazeUniform.current,
+                sky: bgSkyUniform.current,
+                skyDeep: bgSkyDeepUniform.current,
             });
-            // Selected: white visible, yellow hidden
-            const selectedVisibleColor = uniform(new Color(0xff_ff_ff));
-            const selectedHiddenColor = uniform(new Color(0xf3_ff_47));
-            const selectedStrength = uniform(3);
-            const selectedOutline = outlineNode.primaryVisibleEdge
-                .mul(selectedVisibleColor)
-                .add(outlineNode.primaryHiddenEdge.mul(selectedHiddenColor))
-                .mul(selectedStrength);
-            // Hovered: blue visible, yellow hidden, pulsing
-            const pulsePeriod = uniform(3);
-            const oscillating = oscSine(time.div(pulsePeriod).mul(2)).mul(0.5).add(0.5);
-            const osc = mix(oscillating, float(1), hoverPulseMix);
-            const hoverOutline = outlineNode.secondaryVisibleEdge
-                .mul(hoverVisibleColor)
-                .add(outlineNode.secondaryHiddenEdge.mul(hoverHiddenColor))
-                .mul(hoverStrength)
-                .mul(osc);
-            const compositeWithOutlines = vec4(add(sceneColor.rgb, selectedOutline.add(hoverOutline)), sceneColor.a);
-            const finalOutput = vec4(mix(bgUniform.current, compositeWithOutlines.rgb, contentAlpha), float(1));
+            if (shading === 'rendered') {
+                bgGradient = gradeRgb(bgGradient);
+            }
+            const composited = mix(bgGradient, compositeWithOutlines.rgb, contentAlpha);
+            // Editor overlays painted on top by their own alpha — they never get inked,
+            // AO'd, or outlined, and always read crisp regardless of scene depth.
+            const withOverlay = mix(composited, overlayColor.rgb, overlayColor.a);
+            let finalOutput = vec4(withOverlay, float(1));
+            if (transparentBackground) {
+                const overlayAlpha = overlayColor.a;
+                const alpha = overlayAlpha.add(visualAlpha.mul(overlayAlpha.oneMinus()));
+                const straightRgb = overlayColor.rgb
+                    .mul(overlayAlpha)
+                    .add(compositeWithOutlines.rgb.mul(visualAlpha).mul(overlayAlpha.oneMinus()))
+                    .div(alpha.max(float(0.00001)));
+                finalOutput = premultiplyAlpha(renderOutput(vec4(straightRgb, alpha)));
+            }
             const renderPipeline = new RenderPipeline(renderer);
+            renderPipeline.outputColorTransform = !transparentBackground;
             renderPipeline.outputNode = finalOutput;
             renderPipelineRef.current = renderPipeline;
             retryCountRef.current = 0;
-            console.log('[viewer/post-processing] Pipeline built OK', { version: pipelineVersion });
         }
         catch (error) {
             hasPipelineErrorRef.current = true;
@@ -243,33 +500,97 @@ const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, }) => {
             renderPipelineRef.current = null;
         };
     }, [
+        // NOTE: hoverHighlightMode intentionally excluded — the hover style is
+        // pushed to uniforms in a separate effect, so a hover must NOT rebuild the
+        // whole pipeline. The uniform refs below are stable (useMemo), so they
+        // never trigger a rebuild either.
         camera,
+        disablePostFx,
         hoverHiddenColor,
         hoverPulseMix,
         hoverStrength,
         hoverVisibleColor,
+        edges,
+        inkOpacityOverride,
         pipelineVersion,
         projectId,
         renderer,
         scene,
+        shading,
+        transparentBackground,
+        size.height,
+        size.width,
         zoneLayers,
+        sceneOnlyLayers,
+        overlayLayers,
     ]);
     useFrame((_, delta) => {
-        // Animate background colour toward the current theme target (same lerp as AnimatedBackground)
-        bgTarget.current.set(useViewer.getState().theme === 'dark' ? DARK_BG : LIGHT_BG);
+        if (size.width < 1 || size.height < 1) {
+            return;
+        }
+        // `?disable=draw`: nothing downstream wants pixels — render an EMPTY scene
+        // instead of the real one. This is the only render call (positive-priority
+        // useFrame subscribers already disable R3F's automatic render), so the real
+        // scene is never drawn: per-frame vertex/draw cost drops to a single 64×64
+        // clear, which is what makes headless bakes viable on SwiftShader (CPU).
+        // Rendering nothing at all is NOT an option — with zero submitted frames
+        // Chromium's no-damage scheduler throttles rAF to 1Hz (measured), stalling
+        // the useFrame systems the bake still needs.
+        if (PERF_DRAW_DISABLED) {
+            try {
+                ;
+                renderer.render(emptyScene, camera);
+            }
+            catch {
+                // A failed empty draw changes nothing — systems keep ticking.
+            }
+            return;
+        }
+        // Animate background colour toward the current scene theme target (same lerp as AnimatedBackground)
+        const bgTheme = getSceneTheme(useViewer.getState().sceneTheme);
+        bgTarget.current.set(bgTheme.background);
         bgCurrent.current.lerp(bgTarget.current, Math.min(delta, 0.1) * 4);
         bgUniform.current.value.copy(bgCurrent.current);
+        bgSkyTarget.current.set(bgTheme.backgroundSky ?? bgTheme.background);
+        bgSkyCurrent.current.lerp(bgSkyTarget.current, Math.min(delta, 0.1) * 4);
+        bgSkyUniform.current.value.copy(bgSkyCurrent.current);
+        bgHazeTarget.current.set(horizonHazeColor(bgTheme.backgroundSky ?? bgTheme.background, bgTheme.appearance));
+        bgHazeCurrent.current.lerp(bgHazeTarget.current, Math.min(delta, 0.1) * 4);
+        bgHazeUniform.current.value.copy(bgHazeCurrent.current);
+        bgSkyDeepTarget.current.set(deepSkyColor(bgTheme.backgroundSky ?? bgTheme.background));
+        bgSkyDeepCurrent.current.lerp(bgSkyDeepTarget.current, Math.min(delta, 0.1) * 4);
+        bgSkyDeepUniform.current.value.copy(bgSkyDeepCurrent.current);
+        camProjInvUniform.current.value.copy(camera.projectionMatrixInverse);
+        camWorldUniform.current.value.copy(camera.matrixWorld);
+        // Ink colour follows the (lerping) background luminance — snaps dark↔light.
+        const bgHex = `#${bgCurrent.current.getHexString()}`;
+        inkColorUniform.current.value.set(edgeColorFor(bgHex));
+        inkOpacityScaleUniform.current.value = edgeOpacityScaleFor(bgHex);
         const outliner = useViewer.getState().outliner;
         sanitizeOutlineObjects(outliner.selectedObjects);
         sanitizeOutlineObjects(outliner.hoveredObjects);
-        if (hasPipelineErrorRef.current || !renderPipelineRef.current) {
+        if (disablePostFx ||
+            PERF_POST_FX_DISABLED ||
+            hasPipelineErrorRef.current ||
+            !renderPipelineRef.current) {
             try {
-                if (renderer.setClearAlpha) {
+                const clearAlpha = transparentBackground ? 0 : 1;
+                if (renderer.setClearColor) {
                     ;
-                    renderer.setClearAlpha(1);
+                    renderer.setClearColor(bgCurrent.current, clearAlpha);
                 }
-                ;
+                else if (renderer.setClearAlpha) {
+                    ;
+                    renderer.setClearAlpha(clearAlpha);
+                }
+                const submittedAt = PERF_OVERLAY_ENABLED ? performance.now() : 0;
                 renderer.render(scene, camera);
+                if (PERF_OVERLAY_ENABLED) {
+                    const queue = renderer.backend?.device?.queue;
+                    queue?.onSubmittedWorkDone?.().then(() => {
+                        pushGpuSample(performance.now() - submittedAt);
+                    });
+                }
             }
             catch (fallbackError) {
                 console.error('[viewer/post-processing] Fallback render failed.', fallbackError);
@@ -281,7 +602,19 @@ const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, }) => {
             // making scenePassColor.a a reliable geometry mask (geometry pixels write a=1 via output node).
             ;
             renderer.setClearAlpha(0);
+            const submittedAt = PERF_OVERLAY_ENABLED ? performance.now() : 0;
             renderPipelineRef.current.render();
+            if (PERF_OVERLAY_ENABLED) {
+                // device.queue.onSubmittedWorkDone() resolves once the GPU has
+                // finished the work we just submitted — the delta from our submit
+                // timestamp is a clean per-frame GPU duration. Doesn't block CPU
+                // (no await) and works for the custom RenderPipeline path that
+                // bypasses three.js's timestamp-query infrastructure.
+                const queue = renderer.backend?.device?.queue;
+                queue?.onSubmittedWorkDone?.().then(() => {
+                    pushGpuSample(performance.now() - submittedAt);
+                });
+            }
         }
         catch (error) {
             hasPipelineErrorRef.current = true;
@@ -297,7 +630,6 @@ const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, }) => {
             if (retryCountRef.current < MAX_PIPELINE_RETRIES) {
                 // Auto-retry: schedule a pipeline rebuild if we haven't exceeded the retry limit
                 retryCountRef.current++;
-                console.warn(`[viewer/post-processing] Scheduling pipeline rebuild (attempt ${retryCountRef.current}/${MAX_PIPELINE_RETRIES})`);
                 if (rebuildTimeoutRef.current !== null) {
                     clearTimeout(rebuildTimeoutRef.current);
                 }

package/dist/components/viewer/registered-systems.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Mounts every registered node kind's system component, ordered by
+ * `system.priority` (default {@link DEFAULT_PRIORITY}).
+ *
+ * Today the registry is empty so this component mounts nothing — coexists
+ * with legacy `*-System` components in `<Viewer>`. Once kinds register via
+ * `@pascal-app/nodes`, each kind's registry-driven system takes over and
+ * its legacy counterpart short-circuits via the `nodeRegistry.has(kind)`
+ * guard added to each legacy system.
+ */
+export declare function RegisteredSystems(): import("react").JSX.Element | null;
+//# sourceMappingURL=registered-systems.d.ts.map

package/dist/components/viewer/registered-systems.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registered-systems.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/registered-systems.tsx"],"names":[],"mappings":"AA8BA;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,uCAyBhC"}