@pascal-app/viewer 0.9.1 → 1.0.0-beta.1

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);
@@ -463,6 +618,7 @@ const PostProcessingPasses = ({ hoverStyles = DEFAULT_HOVER_STYLES, }) => {
         }
         catch (error) {
             hasPipelineErrorRef.current = true;
+            renderer.setRenderTarget?.(null);
             console.error('[viewer/post-processing] Render pass failed.', {
                 retryCount: retryCountRef.current,
                 rendererCtor: renderer.constructor?.name,

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"scene-environment.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/scene-environment.tsx"],"names":[],"mappings":"AAmEA,wBAAgB,gBAAgB,SAkB/B"}

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

@@ -0,0 +1,79 @@
+'use client';
+import { useThree } from '@react-three/fiber';
+import { useEffect, useMemo } from 'react';
+import * as THREE from 'three/webgpu';
+import { getSceneTheme } from '../../lib/scene-themes';
+import useViewer from '../../store/use-viewer';
+/**
+ * Scene IBL — a small procedural gradient sky (cool zenith → warm horizon →
+ * dim ground bounce) used purely as the environment light source. The visible
+ * backdrop stays the flat theme background (composited in post-processing);
+ * this texture is never shown. Replaces the old `venice_sunset_1k.hdr` fetch:
+ * no network dependency, and the vertical color split means upward-facing
+ * surfaces read cooler than vertical ones instead of everything getting the
+ * same directionless warm wash. Exported as an opt-in <Viewer> child so
+ * embed / thumbnail surfaces that don't want IBL simply don't mount it.
+ * Only affects `rendered` shading (Lambert ignores env maps).
+ */
+// Linear-space gradient stops.
+const ZENITH = [0.4, 0.56, 0.78];
+const HORIZON = [0.95, 0.84, 0.66];
+const GROUND = [0.38, 0.35, 0.3];
+const ENV_INTENSITY = 0.6;
+// The gradient sky is a daylight source; dark themes only want a whisper of it.
+const ENV_INTENSITY_DARK = 0.2;
+const WIDTH = 64;
+const HEIGHT = 32;
+function buildGradientSky() {
+    const data = new Float32Array(WIDTH * HEIGHT * 4);
+    for (let y = 0; y < HEIGHT; y++) {
+        // Row 0 = v0 = nadir, top row = zenith (equirect v spans -90°..+90°).
+        const lat = ((y + 0.5) / HEIGHT) * 2 - 1;
+        let r;
+        let g;
+        let b;
+        if (lat <= 0) {
+            // Below the horizon: flat ground bounce, slightly darker toward nadir.
+            const k = 1 + lat * 0.35;
+            r = GROUND[0] * k;
+            g = GROUND[1] * k;
+            b = GROUND[2] * k;
+        }
+        else {
+            // pow < 1 widens the warm horizon band.
+            const t = lat ** 0.65;
+            r = HORIZON[0] + (ZENITH[0] - HORIZON[0]) * t;
+            g = HORIZON[1] + (ZENITH[1] - HORIZON[1]) * t;
+            b = HORIZON[2] + (ZENITH[2] - HORIZON[2]) * t;
+        }
+        for (let x = 0; x < WIDTH; x++) {
+            const i = (y * WIDTH + x) * 4;
+            data[i] = r;
+            data[i + 1] = g;
+            data[i + 2] = b;
+            data[i + 3] = 1;
+        }
+    }
+    const texture = new THREE.DataTexture(data, WIDTH, HEIGHT, THREE.RGBAFormat, THREE.FloatType);
+    texture.mapping = THREE.EquirectangularReflectionMapping;
+    texture.colorSpace = THREE.LinearSRGBColorSpace;
+    texture.needsUpdate = true;
+    return texture;
+}
+export function SceneEnvironment() {
+    const scene = useThree((state) => state.scene);
+    const texture = useMemo(buildGradientSky, []);
+    const appearance = useViewer((state) => getSceneTheme(state.sceneTheme).appearance);
+    useEffect(() => {
+        const prevEnvironment = scene.environment;
+        const prevIntensity = scene.environmentIntensity;
+        scene.environment = texture;
+        scene.environmentIntensity = appearance === 'dark' ? ENV_INTENSITY_DARK : ENV_INTENSITY;
+        return () => {
+            scene.environment = prevEnvironment;
+            scene.environmentIntensity = prevIntensity;
+            texture.dispose();
+        };
+    }, [scene, texture, appearance]);
+    return null;
+}

package/dist/components/viewer/selection-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"selection-manager.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/selection-manager.tsx"],"names":[],"mappings":"AA0SA,eAAO,MAAM,gBAAgB,mCA0F5B,CAAA"}
+{"version":3,"file":"selection-manager.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/selection-manager.tsx"],"names":[],"mappings":"AAiTA,eAAO,MAAM,gBAAgB,mCAqG5B,CAAA"}