@pascal-app/viewer 0.9.1 → 0.9.2

package/dist/components/viewer/lights.js

@@ -3,6 +3,7 @@ import { sceneRegistry } from '@pascal-app/core';
 import { useFrame } from '@react-three/fiber';
 import { useMemo, useRef } from 'react';
 import * as THREE from 'three/webgpu';
+import { SHADOW_ONLY_LAYER } from '../../lib/layers';
 import { getSceneTheme } from '../../lib/scene-themes';
 import useViewer from '../../store/use-viewer';
 // Diagnostic toggle: `?disable=shadows` skips the shadow-map render pass
@@ -12,10 +13,27 @@ const SHADOWS_DISABLED = typeof window !== 'undefined' &&
     new Set((new URLSearchParams(window.location.search).get('disable') ?? '')
         .split(',')
         .map((s) => s.trim())).has('shadows');
+// Diagnostic toggle: `?debug=shadowcamera` draws a CameraHelper for each
+// shadow camera so the building-fit frustum (and thus shadow texel density)
+// can be inspected while tuning margins/bias.
+const SHADOW_CAMERA_DEBUG = typeof window !== 'undefined' &&
+    new Set((new URLSearchParams(window.location.search).get('debug') ?? '')
+        .split(',')
+        .map((s) => s.trim())).has('shadowcamera');
 // Shadow darkness for the bright key lights (themes drive most lights past
-// intensity 1). The aesthetic prototype runs these near-black (≈1.0); this is a
-// deliberate middle ground — present, but not the heavy contact shadow there.
-const MAX_SHADOW_INTENSITY = 0.55;
+// intensity 1). Runs high so shadowed areas actually lose the sun's
+// contribution — the ambient/hemisphere/IBL stack provides the fill. The old
+// 0.55 clamp leaked 45% of the key light into shadow and flattened interiors;
+// 0.9 read too heavy in review.
+const MAX_SHADOW_INTENSITY = 0.75;
+// `normalBias` is measured in world units. The previous 0.3 moved shadow
+// lookups 30 cm off their surfaces, visibly detaching wall shadows at the
+// floor; 0.07 and below still acnes on the building-fit 1024 map (large
+// texels), so 0.08 is the smallest acne-free value at that resolution — even
+// with the depth bias at -0.0005 (which is itself needed: 0.08 alone still
+// showed faint acne at -0.0001).
+const SHADOW_DEPTH_BIAS = -0.0005;
+const SHADOW_NORMAL_BIAS = 0.08;
 // Shadow frustum framing. The frustum is fit to the BUILDING geometry (not the
 // camera): we union the bounds of all registered scene nodes, fit a sphere, and
 // size the directional light's ortho shadow camera to that sphere plus a margin.
@@ -54,6 +72,7 @@ export function Lights() {
     const boundsBox = useRef(new THREE.Box3()); // scratch: union AABB
     const boundsSphere = useRef(new THREE.Sphere()); // scratch: fitted sphere
     const lastBoundsTime = useRef(-1); // last refresh timestamp (-1 = never)
+    const shadowHelpers = useRef([]);
     const hemiRef = useRef(null);
     const ambientRef = useRef(null);
     const initialized = useRef(false);
@@ -129,6 +148,9 @@ export function Lights() {
                 // the <orthographicCamera attach="shadow-camera"> below.
                 const cam = light.shadow?.camera;
                 if (cam) {
+                    // Shadow-caster-only geometry (hidden roofs/levels in cutaway views)
+                    // is visible to the shadow pass alone — see lib/shadow-only.ts.
+                    cam.layers.enable(SHADOW_ONLY_LAYER);
                     cam.left = -size;
                     cam.right = size;
                     cam.top = size;
@@ -136,6 +158,15 @@ export function Lights() {
                     cam.near = near;
                     cam.far = far;
                     cam.updateProjectionMatrix();
+                    if (SHADOW_CAMERA_DEBUG) {
+                        let helper = shadowHelpers.current[index];
+                        if (!helper) {
+                            helper = new THREE.CameraHelper(cam);
+                            shadowHelpers.current[index] = helper;
+                            state.scene.add(helper);
+                        }
+                        helper.update();
+                    }
                 }
             }
         }
@@ -195,7 +226,7 @@ export function Lights() {
             ambientRef.current.color.lerp(targets.ambColor, dt);
         }
     });
-    return (_jsxs(_Fragment, { children: [theme.lights.map((light, index) => (_jsx("directionalLight", { castShadow: Boolean(light.castShadow) && !SHADOWS_DISABLED && shadows, position: light.position, ref: (ref) => {
+    return (_jsxs(_Fragment, { children: [theme.lights.map((light, index) => (_jsx("directionalLight", { castShadow: Boolean(light.castShadow) && !SHADOWS_DISABLED, position: light.position, ref: (ref) => {
                     lightRefs.current[index] = ref;
-                }, "shadow-bias": -0.002, "shadow-mapSize": [1024, 1024], "shadow-normalBias": 0.3, "shadow-radius": 1.5, children: light.castShadow && !SHADOWS_DISABLED && shadows ? (_jsx("orthographicCamera", { attach: "shadow-camera", bottom: -shadowCameraSize, far: 400, left: -shadowCameraSize, near: 1, ref: shadowCamera, right: shadowCameraSize, top: shadowCameraSize })) : null }, `${index}-${light.position.join(',')}`))), theme.hemi ? _jsx("hemisphereLight", { ref: hemiRef }) : null, _jsx("ambientLight", { ref: ambientRef })] }));
+                }, "shadow-bias": SHADOW_DEPTH_BIAS, "shadow-mapSize": [1024, 1024], "shadow-normalBias": SHADOW_NORMAL_BIAS, "shadow-radius": 2, children: light.castShadow && !SHADOWS_DISABLED ? (_jsx("orthographicCamera", { attach: "shadow-camera", bottom: -shadowCameraSize, far: 400, left: -shadowCameraSize, near: 1, ref: shadowCamera, right: shadowCameraSize, top: shadowCameraSize })) : null }, `${index}-${light.position.join(',')}`))), theme.hemi ? _jsx("hemisphereLight", { ref: hemiRef }) : null, _jsx("ambientLight", { ref: ambientRef })] }));
 }

package/dist/components/viewer/perf-monitor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"perf-monitor.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/perf-monitor.tsx"],"names":[],"mappings":"AAQA,eAAO,MAAM,WAAW,mCAuIvB,CAAA"}
+{"version":3,"file":"perf-monitor.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/perf-monitor.tsx"],"names":[],"mappings":"AAQA,eAAO,MAAM,WAAW,mCAsJvB,CAAA"}

package/dist/components/viewer/perf-monitor.js

@@ -14,6 +14,7 @@ export const PerfMonitor = () => {
         drawCalls: 0,
         triangles: 0,
         dirty: 0,
+        dirtyDetail: '',
         meshes: 0,
         lines: 0,
         sprites: 0,
@@ -57,7 +58,20 @@ export const PerfMonitor = () => {
             const drawCalls = Math.round(totalCalls / Math.max(1, frameCount.current));
             const triangles = totalTriangles / Math.max(1, frameCount.current);
             info.reset();
-            const dirty = useScene.getState().dirtyNodes.size;
+            const sceneState = useScene.getState();
+            const dirty = sceneState.dirtyNodes.size;
+            let dirtyDetail = '';
+            if (dirty > 0) {
+                const counts = new Map();
+                for (const id of sceneState.dirtyNodes) {
+                    const type = sceneState.nodes[id]?.type ?? 'missing';
+                    counts.set(type, (counts.get(type) ?? 0) + 1);
+                }
+                dirtyDetail = [...counts.entries()]
+                    .sort((a, b) => b[1] - a[1])
+                    .map(([type, count]) => `${count} ${type}`)
+                    .join(', ');
+            }
             // Count visible drawables by type so we can match scene contents
             // against the renderer's draw count and find hidden contributors.
             let meshes = 0;
@@ -99,6 +113,7 @@ export const PerfMonitor = () => {
                 drawCalls,
                 triangles,
                 dirty,
+                dirtyDetail,
                 meshes,
                 lines,
                 sprites,
@@ -122,7 +137,7 @@ export const PerfMonitor = () => {
 GPU    ${stats.gpuMs > 0 ? `${stats.gpuMs.toFixed(1)}ms (max ${stats.gpuMaxMs.toFixed(1)})` : '—'}
 DRAW   ${stats.drawCalls}
 TRI    ${(stats.triangles / 1000).toFixed(1)}k
-DIRTY  ${stats.dirty}
+DIRTY  ${stats.dirty}${stats.dirtyDetail ? ` (${stats.dirtyDetail})` : ''}
 MESH   ${stats.meshes}
 LINE   ${stats.lines}
 SPRITE ${stats.sprites}

package/dist/components/viewer/post-processing.d.ts

@@ -1,3 +1,7 @@
+export declare const GRADE_PARAMS: {
+    contrast: number;
+    saturation: number;
+};
 export declare const SSGI_PARAMS: {
     enabled: boolean;
     sliceCount: number;
@@ -22,8 +26,10 @@ export type HoverStyles = {
     default: HoverStyle;
 } & Record<string, HoverStyle>;
 export declare const DEFAULT_HOVER_STYLES: HoverStyles;
-declare const PostProcessingPasses: ({ hoverStyles, }: {
+declare const PostProcessingPasses: ({ hoverStyles, disablePostFx, }: {
     hoverStyles?: HoverStyles;
+    /** Host-controlled equivalent of `?disable=postFx` — see the Viewer prop. */
+    disablePostFx?: boolean;
 }) => null;
 export default PostProcessingPasses;
 //# sourceMappingURL=post-processing.d.ts.map

package/dist/components/viewer/post-processing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"post-processing.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/post-processing.tsx"],"names":[],"mappings":"AAgCA,eAAO,MAAM,WAAW;;;;;;;;;;;;;CAavB,CAAA;AA0CD,MAAM,MAAM,UAAU,GAAG;IACvB,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,OAAO,CAAA;CACf,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,UAAU,CAAA;CACpB,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;AAS9B,eAAO,MAAM,oBAAoB,EAAE,WAElC,CAAA;AAiBD,QAAA,MAAM,oBAAoB,GAAI,kBAE3B;IACD,WAAW,CAAC,EAAE,WAAW,CAAA;CAC1B,SAgdA,CAAA;AAED,eAAe,oBAAoB,CAAA"}
+{"version":3,"file":"post-processing.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/post-processing.tsx"],"names":[],"mappings":"AAwCA,eAAO,MAAM,YAAY;;;CAGxB,CAAA;AAGD,eAAO,MAAM,WAAW;;;;;;;;;;;;;CAavB,CAAA;AA0DD,MAAM,MAAM,UAAU,GAAG;IACvB,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,OAAO,CAAA;CACf,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,UAAU,CAAA;CACpB,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;AAS9B,eAAO,MAAM,oBAAoB,EAAE,WAElC,CAAA;AAiBD,QAAA,MAAM,oBAAoB,GAAI,iCAG3B;IACD,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB,6EAA6E;IAC7E,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB,SA8mBA,CAAA;AAED,eAAe,oBAAoB,CAAA"}

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

@@ -1,17 +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 { edgeColorFor } from '../../lib/edge-style';
+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,
@@ -37,6 +46,11 @@ export const SSGI_PARAMS = {
 //   - 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 };
@@ -57,6 +71,12 @@ 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 DEFAULT_HOVER_STYLE = {
@@ -79,7 +99,7 @@ function sanitizeOutlineObjects(objects) {
     }
     objects.length = nextIndex;
 }
-const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, }) => {
+const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, disablePostFx = false, }) => {
     const { gl: renderer, invalidate, scene, camera, size } = useThree();
     const renderPipelineRef = useRef(null);
     const hasPipelineErrorRef = useRef(false);
@@ -88,13 +108,35 @@ const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, }) => {
     const skippedZeroSizeRef = useRef(false);
     // Background color uniform — updated every frame via lerp, read by the TSL pipeline.
     // Initialised from the current scene theme so there's no flash on first render.
-    const initBg = getSceneTheme(useViewer.getState().sceneTheme).background;
+    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);
@@ -129,6 +171,8 @@ const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, }) => {
     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);
@@ -199,6 +243,18 @@ const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, }) => {
             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;
@@ -211,16 +267,16 @@ const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, }) => {
         // 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 = edges === 'strong' ? 1 : 0.5;
+        const inkOpacity = inkOpacityOverride ?? (edges === 'strong' ? 1 : 0.5);
         console.log('[viewer/post-processing] Building pipeline', {
             version: pipelineVersion,
             ssgi: ssgiEnabled,
             denoise: denoiseEnabled,
             outline: outlineEnabled,
             perfDisable,
-            hoverHighlightMode,
             projectId,
             shading,
+            transparentBackground,
             rendererCtor: renderer.constructor?.name,
             width,
             height,
@@ -265,7 +321,10 @@ 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;
+            // 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;
@@ -275,14 +334,14 @@ const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, }) => {
                 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) => colorToDirection(scenePassNormal.sample(uv)));
+                sceneNormal = sample((uv) => unpackRGBToNormal(scenePassNormal.sample(uv)));
             }
             if (ssgiEnabled) {
                 const scenePassDiffuse = scenePass.getTextureNode('diffuseColor');
@@ -300,13 +359,15 @@ 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();
-                const gi = giPass.rgb;
+                // 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 packs AO into alpha, so we remap it into RGB before denoising.
-                    const aoAsRgb = vec4(giTexture.a, giTexture.a, giTexture.a, float(1));
+                    // 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;
@@ -315,8 +376,14 @@ const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, }) => {
                 else {
                     // Diagnostic path: feed raw noisy SSGI AO straight through. Will
                     // look grainy — that's the point, it isolates denoise cost.
-                    ao = giTexture.a;
+                    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);
             }
@@ -330,12 +397,22 @@ const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, }) => {
                     normalTex: scenePassNormal,
                     inkColor: inkColorUniform.current,
                     radius: inkRadius,
-                    opacity: inkOpacity,
+                    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;
             let compositeWithOutlines = sceneColor;
+            let visualAlpha = contentAlpha;
             if (outlineEnabled) {
                 const outlineNode = mergedOutline(scene, camera, {
                     primaryObjects: outliner.selectedObjects,
@@ -360,14 +437,46 @@ const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, }) => {
                     .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);
             }
-            const composited = mix(bgUniform.current, compositeWithOutlines.rgb, contentAlpha);
+            // 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,
+            });
+            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);
-            const finalOutput = vec4(withOverlay, float(1));
+            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;
@@ -391,18 +500,24 @@ 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,
-        hoverHighlightMode,
         hoverPulseMix,
         hoverStrength,
         hoverVisibleColor,
         edges,
+        inkOpacityOverride,
         pipelineVersion,
         projectId,
         renderer,
         scene,
         shading,
+        transparentBackground,
         size.height,
         size.width,
         zoneLayers,
@@ -413,20 +528,60 @@ const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, }) => {
         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)
-        bgTarget.current.set(getSceneTheme(useViewer.getState().sceneTheme).background);
+        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.
-        inkColorUniform.current.value.set(edgeColorFor(`#${bgCurrent.current.getHexString()}`));
+        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 (PERF_POST_FX_DISABLED || 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.setClearColor(bgCurrent.current, clearAlpha);
+                }
+                else if (renderer.setClearAlpha) {
                     ;
-                    renderer.setClearAlpha(1);
+                    renderer.setClearAlpha(clearAlpha);
                 }
                 const submittedAt = PERF_OVERLAY_ENABLED ? performance.now() : 0;
                 renderer.render(scene, camera);

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

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

package/dist/components/viewer/registered-systems.js

@@ -1,10 +1,8 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import { nodeRegistry } from '@pascal-app/core';
+import { createSceneApi, isNodeKindEnabled, nodeRegistry, useScene, } from '@pascal-app/core';
 import { lazy, Suspense, useMemo } from 'react';
 const DEFAULT_PRIORITY = 5;
-// Cache lazy components keyed by the module-loader function so React.lazy
-// isn't re-invoked across renders.
 const lazyCache = new WeakMap();
 function loadSystem(def) {
     if (!def.system)
@@ -27,6 +25,8 @@ function loadSystem(def) {
  * guard added to each legacy system.
  */
 export function RegisteredSystems() {
+    const sceneApi = useMemo(() => createSceneApi(useScene), []);
+    const installedPlugins = useScene((state) => state.installedPlugins);
     const entries = useMemo(() => {
         return Array.from(nodeRegistry.entries())
             .filter(([, def]) => def.system != null)
@@ -39,9 +39,11 @@ export function RegisteredSystems() {
     if (entries.length === 0)
         return null;
     return (_jsx(Suspense, { fallback: null, children: entries.map(([kind, def]) => {
+            if (!isNodeKindEnabled(kind, installedPlugins))
+                return null;
             const Comp = loadSystem(def);
             if (!Comp)
                 return null;
-            return _jsx(Comp, {}, `registered-system:${kind}`);
+            return _jsx(Comp, { sceneApi: sceneApi }, `registered-system:${kind}`);
         }) }));
 }

package/dist/components/viewer/scene-bvh.d.ts

@@ -1,5 +1,5 @@
 import { type ReactNode } from 'react';
-import { type Group } from 'three';
+import { type Group, Mesh } from 'three';
 import { type SplitStrategy } from 'three-mesh-bvh';
 type SceneBvhProps = {
     children?: ReactNode;
@@ -12,6 +12,7 @@ type SceneBvhProps = {
     maxLeafSize?: number;
     indirect?: boolean;
 };
+export declare const isSceneBvhExcluded: (object: Mesh) => boolean;
 export declare const SceneBvh: import("react").ForwardRefExoticComponent<SceneBvhProps & import("react").RefAttributes<Group<import("three").Object3DEventMap>>>;
 export {};
 //# sourceMappingURL=scene-bvh.d.ts.map

package/dist/components/viewer/scene-bvh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scene-bvh.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/scene-bvh.tsx"],"names":[],"mappings":"AACA,OAAO,EAAc,KAAK,SAAS,EAA0C,MAAM,OAAO,CAAA;AAC1F,OAAO,EAAuB,KAAK,KAAK,EAAQ,MAAM,OAAO,CAAA;AAC7D,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAA;AAEvB,KAAK,aAAa,GAAG;IACnB,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,EAAE,aAAa,CAAA;IACxB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAeD,eAAO,MAAM,QAAQ,mIAmGpB,CAAA"}
+{"version":3,"file":"scene-bvh.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/scene-bvh.tsx"],"names":[],"mappings":"AACA,OAAO,EAAc,KAAK,SAAS,EAA0C,MAAM,OAAO,CAAA;AAC1F,OAAO,EAAuB,KAAK,KAAK,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AAC7D,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAA;AAEvB,KAAK,aAAa,GAAG;IACnB,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,EAAE,aAAa,CAAA;IACxB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAKD,eAAO,MAAM,kBAAkB,GAAI,QAAQ,IAAI,YAA4C,CAAA;AAY3F,eAAO,MAAM,QAAQ,mIAoGpB,CAAA"}

package/dist/components/viewer/scene-bvh.js

@@ -4,6 +4,7 @@ import { forwardRef, useEffect, useImperativeHandle, useRef } from 'react';
 import { Mesh } from 'three';
 import { acceleratedRaycast, computeBoundsTree, disposeBoundsTree, SAH, } from 'three-mesh-bvh';
 const isMesh = (object) => !!object && typeof object === 'object' && object.isMesh === true;
+export const isSceneBvhExcluded = (object) => object.userData.excludeFromBvh === true;
 const hasBvhCompatibleGeometry = (geometry) => {
     if (!geometry)
         return false;
@@ -35,6 +36,8 @@ export const SceneBvh = forwardRef(({ children, enabled = true, firstHitOnly = f
         group.traverse((child) => {
             if (!isMesh(child))
                 return;
+            if (isSceneBvhExcluded(child))
+                return;
             if (child.raycast === Mesh.prototype.raycast) {
                 child.raycast = acceleratedRaycast;
                 acceleratedMeshes.add(child);

package/dist/components/viewer/scene-bvh.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=scene-bvh.test.d.ts.map

package/dist/components/viewer/scene-bvh.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-bvh.test.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/scene-bvh.test.ts"],"names":[],"mappings":""}

package/dist/components/viewer/scene-bvh.test.js

@@ -0,0 +1,13 @@
+// @ts-expect-error — bun:test is provided by the Bun runtime; viewer does not
+// include Bun ambient types in its production declaration build.
+import { describe, expect, test } from 'bun:test';
+import { Mesh } from 'three';
+import { isSceneBvhExcluded } from './scene-bvh';
+describe('scene BVH exclusions', () => {
+    test('keeps annotation meshes on their normal raycast path', () => {
+        expect(isSceneBvhExcluded(new Mesh())).toBe(false);
+        const annotation = new Mesh();
+        annotation.userData.excludeFromBvh = true;
+        expect(isSceneBvhExcluded(annotation)).toBe(true);
+    });
+});

package/dist/components/viewer/scene-environment.d.ts

@@ -0,0 +1,2 @@
+export declare function SceneEnvironment(): null;
+//# sourceMappingURL=scene-environment.d.ts.map