@jgengine/shell 0.25.0 → 0.26.0

package/dist/postfx/autoExposure.js

@@ -0,0 +1,189 @@
+import * as THREE from "three";
+import { FullScreenQuad, Pass } from "three-stdlib";
+/**
+ * Grid the beauty buffer is averaged down to before readback, per axis. 16×16 cells × 4×4 taps
+ * covers 4096 samples of the frame — enough for a stable key luminance, small enough to read back
+ * (1 KB of encoded log-luminance) without a measurable stall.
+ */
+const METER_SIZE = 16;
+const TAPS_PER_AXIS = 4;
+/** Encoded range of the log-luminance bytes: 2^-16 .. 2^8. */
+const LOG_MIN = -16;
+const LOG_MAX = 8;
+const LOG_RANGE = LOG_MAX - LOG_MIN;
+const reduceShader = {
+    uniforms: { tDiffuse: { value: null } },
+    vertexShader: /* glsl */ `
+    varying vec2 vUv;
+    void main() {
+      vUv = uv;
+      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+    }
+  `,
+    fragmentShader: /* glsl */ `
+    uniform sampler2D tDiffuse;
+    varying vec2 vUv;
+
+    void main() {
+      vec2 cell = vec2(${METER_SIZE.toFixed(1)});
+      vec2 texel = 1.0 / cell;
+      vec2 origin = floor(vUv * cell) * texel;
+      float logSum = 0.0;
+      for (int y = 0; y < ${TAPS_PER_AXIS}; y++) {
+        for (int x = 0; x < ${TAPS_PER_AXIS}; x++) {
+          vec2 jitter = (vec2(float(x), float(y)) + 0.5) / ${TAPS_PER_AXIS.toFixed(1)};
+          vec3 color = texture2D(tDiffuse, origin + jitter * texel).rgb;
+          float luma = dot(color, vec3(0.2126, 0.7152, 0.0722));
+          // Log-encoded so one bright window cannot outweigh the room around it.
+          logSum += clamp(log2(max(luma, 1e-6)), ${LOG_MIN.toFixed(1)}, ${LOG_MAX.toFixed(1)});
+        }
+      }
+      float encoded = (logSum / ${(TAPS_PER_AXIS * TAPS_PER_AXIS).toFixed(1)} - ${LOG_MIN.toFixed(1)}) / ${LOG_RANGE.toFixed(1)};
+      gl_FragColor = vec4(encoded, encoded, encoded, 1.0);
+    }
+  `,
+};
+const copyShader = {
+    uniforms: { tDiffuse: { value: null } },
+    vertexShader: reduceShader.vertexShader,
+    fragmentShader: /* glsl */ `
+    uniform sampler2D tDiffuse;
+    varying vec2 vUv;
+    void main() { gl_FragColor = texture2D(tDiffuse, vUv); }
+  `,
+};
+/** Linear luminance encoded in one byte by {@link ExposureMeterPass}. @internal */
+export function decodeMeterByte(value, target, targetIndex) {
+    target[targetIndex] = Math.pow(2, (value / 255) * LOG_RANGE + LOG_MIN);
+}
+/**
+ * Meters the pre-tone-map beauty buffer for auto-exposure. Every `sampleInterval` frames it reduces
+ * the frame to a 16×16 grid of log-luminance (GPU) and reads that back (1 KB), then hands the decoded
+ * samples to `onSample` with the wall time since the previous sample. The pass itself is a pass-through,
+ * so it can sit anywhere before the tone-mapping output pass without changing the picture.
+ * @internal
+ */
+export class ExposureMeterPass extends Pass {
+    onSample;
+    sampleInterval;
+    meterTarget;
+    reduceUniforms = reduceShader.uniforms;
+    copyUniforms = copyShader.uniforms;
+    reduceQuad;
+    copyQuad;
+    pixels = new Uint8Array(METER_SIZE * METER_SIZE * 4);
+    samples = new Float32Array(METER_SIZE * METER_SIZE);
+    frames = 0;
+    taken = 0;
+    elapsed = 0;
+    pendingSeconds = 0;
+    gl = null;
+    pbo = null;
+    fence = null;
+    constructor(onSample, 
+    /** Frames between readbacks once warmed up. Reading the GPU back stalls the pipeline, so this is
+     * as rare as exposure adaptation tolerates. */
+    sampleInterval = 32) {
+        super();
+        this.onSample = onSample;
+        this.sampleInterval = sampleInterval;
+        this.meterTarget = new THREE.WebGLRenderTarget(METER_SIZE, METER_SIZE, {
+            type: THREE.UnsignedByteType,
+            depthBuffer: false,
+            stencilBuffer: false,
+        });
+        this.meterTarget.texture.minFilter = THREE.NearestFilter;
+        this.meterTarget.texture.magFilter = THREE.NearestFilter;
+        this.meterTarget.texture.generateMipmaps = false;
+        this.reduceQuad = new FullScreenQuad(new THREE.ShaderMaterial(reduceShader));
+        this.copyQuad = new FullScreenQuad(new THREE.ShaderMaterial(copyShader));
+    }
+    render(renderer, writeBuffer, readBuffer, deltaTime) {
+        const previous = renderer.getRenderTarget();
+        this.reduceUniforms.tDiffuse.value = readBuffer.texture;
+        renderer.setRenderTarget(this.meterTarget);
+        this.reduceQuad.render(renderer);
+        this.frames += 1;
+        this.elapsed += deltaTime;
+        this.collectPendingSample();
+        // The first few frames sample every frame so a load starts at its metered exposure, not at the
+        // authored one; after that a readback is queued on a schedule.
+        if (this.fence === null && (this.taken < 4 || this.frames % this.sampleInterval === 0)) {
+            this.queueReadback(renderer);
+        }
+        this.copyUniforms.tDiffuse.value = readBuffer.texture;
+        if (this.renderToScreen) {
+            renderer.setRenderTarget(null);
+        }
+        else {
+            renderer.setRenderTarget(writeBuffer);
+            if (this.clear)
+                renderer.clear();
+        }
+        this.copyQuad.render(renderer);
+        renderer.setRenderTarget(previous);
+    }
+    /**
+     * Queues a readback through a pixel-pack buffer and a fence, so the CPU never waits on the GPU: the
+     * samples arrive a frame or two later through {@link collectPendingSample}. A renderer without WebGL2
+     * buffers falls back to the synchronous read, which costs one stall per sample.
+     */
+    queueReadback(renderer) {
+        this.pendingSeconds = this.elapsed;
+        this.elapsed = 0;
+        this.gl ??= renderer.getContext?.() ?? null;
+        const gl = this.gl;
+        if (gl === null || typeof gl.fenceSync !== "function") {
+            renderer.readRenderTargetPixels(this.meterTarget, 0, 0, METER_SIZE, METER_SIZE, this.pixels);
+            this.emit();
+            return;
+        }
+        this.pbo ??= gl.createBuffer();
+        renderer.setRenderTarget(this.meterTarget);
+        gl.bindBuffer(gl.PIXEL_PACK_BUFFER, this.pbo);
+        gl.readPixels(0, 0, METER_SIZE, METER_SIZE, gl.RGBA, gl.UNSIGNED_BYTE, 0);
+        gl.bindBuffer(gl.PIXEL_PACK_BUFFER, null);
+        this.fence = gl.fenceSync(gl.SYNC_GPU_COMMANDS_COMPLETE, 0);
+    }
+    collectPendingSample() {
+        const gl = this.gl;
+        if (gl === null || this.fence === null || this.pbo === null)
+            return;
+        const status = gl.clientWaitSync(this.fence, 0, 0);
+        if (status === gl.TIMEOUT_EXPIRED)
+            return;
+        if (status === gl.WAIT_FAILED) {
+            gl.deleteSync(this.fence);
+            this.fence = null;
+            return;
+        }
+        gl.bindBuffer(gl.PIXEL_PACK_BUFFER, this.pbo);
+        gl.getBufferSubData(gl.PIXEL_PACK_BUFFER, 0, this.pixels);
+        gl.bindBuffer(gl.PIXEL_PACK_BUFFER, null);
+        gl.deleteSync(this.fence);
+        this.fence = null;
+        this.emit();
+    }
+    emit() {
+        for (let index = 0; index < this.samples.length; index += 1) {
+            decodeMeterByte(this.pixels[index * 4] ?? 0, this.samples, index);
+        }
+        this.taken += 1;
+        this.onSample(this.samples, this.pendingSeconds);
+    }
+    dispose() {
+        if (this.gl !== null) {
+            if (this.fence !== null)
+                this.gl.deleteSync(this.fence);
+            if (this.pbo !== null)
+                this.gl.deleteBuffer(this.pbo);
+            this.fence = null;
+            this.pbo = null;
+        }
+        this.meterTarget.dispose();
+        this.reduceQuad.material.dispose();
+        this.reduceQuad.dispose();
+        this.copyQuad.material.dispose();
+        this.copyQuad.dispose();
+    }
+}

package/dist/postfx/gradeShader.js

@@ -27,10 +27,15 @@ const fragmentShader = /* glsl */ `
 
   vec3 sampleLut(vec3 color) {
     float size = max(uLutSize, 2.0);
-    vec3 c = clamp(color, 0.0, 1.0) * (size - 1.0);
-    float blue = floor(c.b);
-    vec2 uv = vec2((blue * size + c.r + 0.5) / (size * size), (c.g + 0.5) / size);
-    return texture2D(uLut, uv).rgb;
+    float levels = size - 1.0;
+    vec3 c = clamp(color, 0.0, 1.0) * levels;
+    // One tile per blue slice, sampled at texel centres so linear filtering never reads across
+    // into the neighbouring slice, and the two nearest slices blend the blue axis by hand.
+    float slice = floor(c.b);
+    float next = min(slice + 1.0, levels);
+    vec2 uvA = vec2((slice * size + 0.5 + c.r) / (size * size), (0.5 + c.g) / size);
+    vec2 uvB = vec2((next * size + 0.5 + c.r) / (size * size), (0.5 + c.g) / size);
+    return mix(texture2D(uLut, uvA).rgb, texture2D(uLut, uvB).rgb, c.b - slice);
   }
 
   void main() {
@@ -61,6 +66,34 @@ const vertexShader = /* glsl */ `
     gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
   }
 `;
+/** Packs a baked cube into the strip layout the sampler expects: `size` tiles side by side per blue slice. */
+function lutStripTexture(cube) {
+    const size = cube.size;
+    const data = new Uint8Array(size * size * size * 4);
+    for (let slice = 0; slice < size; slice += 1) {
+        for (let green = 0; green < size; green += 1) {
+            for (let red = 0; red < size; red += 1) {
+                const from = (slice * size * size + green * size + red) * 3;
+                const to = (green * size * size + slice * size + red) * 4;
+                data[to] = cube.data[from] ?? 0;
+                data[to + 1] = cube.data[from + 1] ?? 0;
+                data[to + 2] = cube.data[from + 2] ?? 0;
+                data[to + 3] = 255;
+            }
+        }
+    }
+    const texture = new THREE.DataTexture(data, size * size, size, THREE.RGBAFormat, THREE.UnsignedByteType);
+    // Display-space values sampled raw in the shader, so no colour-space decode on the way in.
+    texture.colorSpace = THREE.NoColorSpace;
+    texture.minFilter = THREE.LinearFilter;
+    texture.magFilter = THREE.LinearFilter;
+    texture.wrapS = THREE.ClampToEdgeWrapping;
+    texture.wrapT = THREE.ClampToEdgeWrapping;
+    texture.generateMipmaps = false;
+    texture.flipY = false;
+    texture.needsUpdate = true;
+    return texture;
+}
 /** Build the display-space colour-grade pass and load its optional LUT. Dispose the pass to release its LUT; advance `uniforms.uTime.value` each frame to animate grain. */
 export function createGradePass(config = {}) {
     const lift = config.lift ?? DEFAULT_LIFT;
@@ -95,6 +128,12 @@ export function createGradePass(config = {}) {
     };
     if (config.lut !== undefined) {
         const lut = config.lut;
+        if ("cube" in lut) {
+            lutTexture = lutStripTexture(lut.cube);
+            pass.uniforms.uLut.value = lutTexture;
+            pass.uniforms.uLutSize.value = lut.cube.size;
+            return pass;
+        }
         void new THREE.TextureLoader().loadAsync(lut.url).then((texture) => {
             if (disposed) {
                 texture.dispose();

package/dist/presentationRecovery3d.js

@@ -2,6 +2,7 @@ import { addAfterEffect, useThree } from "@react-three/fiber";
 import { useTexture } from "@react-three/drei";
 import { useLayoutEffect } from "react";
 import { usePresentationRetryScope } from "./presentationRecovery.js";
+import { useStableTextureSet } from "./render/stableTextureSet.js";
 /** Registers exact loader inputs and their cache clear before a load can suspend. @internal */
 export function useRecoverableTexture(input) {
     const scope = usePresentationRetryScope();
@@ -9,7 +10,7 @@ export function useRecoverableTexture(input) {
     const loaded = scope?.registry.register(inputs, useTexture.clear);
     const textures = useTexture(input);
     loaded?.();
-    return textures;
+    return useStableTextureSet(textures);
 }
 /** Observes the owning renderer after the restored material subtree commits and draws. @internal */
 export function PresentationRecoveredDraw() {

package/dist/render/CascadedShadows.d.ts

@@ -1,6 +1,7 @@
 import * as THREE from "three";
 import { CSM } from "three/examples/jsm/csm/CSM.js";
 import type { DirectionalLightingConfig } from "@jgengine/core/game/playableGame";
+import type { DaylightModulation } from "./SceneLighting.js";
 /** @internal Default PCF penumbra in shadow-map texels for configured directional lights. */
 export declare const DEFAULT_SHADOW_RADIUS = 1.25;
 /**
@@ -12,8 +13,9 @@ export declare const DEFAULT_SHADOW_RADIUS = 1.25;
  *
  * @internal shell SceneLighting helper — games set `cascades` on directional lighting config.
  */
-export declare function CascadedShadows({ entry }: {
+export declare function CascadedShadows({ entry, modulation }: {
     entry: DirectionalLightingConfig;
+    modulation?: DaylightModulation;
 }): null;
 /** Structural slice of CSM so the patcher is testable without a renderer. */
 export interface CsmMaterialSetup {

package/dist/render/CascadedShadows.js

@@ -16,10 +16,11 @@ function isStandardMaterial(mat) {
  *
  * @internal shell SceneLighting helper — games set `cascades` on directional lighting config.
  */
-export function CascadedShadows({ entry }) {
+export function CascadedShadows({ entry, modulation }) {
     const camera = useThree((s) => s.camera);
     const scene = useThree((s) => s.scene);
     const csmRef = useRef(null);
+    const baseIntensity = entry.intensity ?? 1.3;
     useEffect(() => {
         const cascades = Math.max(2, Math.min(4, Math.floor(entry.cascades ?? 3)));
         const lightDirection = new THREE.Vector3(-entry.position[0], -entry.position[1], -entry.position[2]);
@@ -71,6 +72,13 @@ export function CascadedShadows({ entry }) {
         const csm = csmRef.current;
         if (csm === null)
             return;
+        if (modulation !== undefined) {
+            // Mutated in place: changing `entry.intensity` would rebuild every cascade's shadow map.
+            for (const light of csm.lights) {
+                light.intensity = baseIntensity * modulation.sunFactor;
+                light.color.set(modulation.sunColor);
+            }
+        }
         csm.camera = camera;
         csm.update();
     });

package/dist/render/EnvironmentLighting.d.ts

@@ -19,6 +19,15 @@ export interface EnvironmentLightingProps {
     sunDirection?: readonly [number, number, number];
     /** Sun disc tint. Default warm white. */
     sunColor?: string;
+    /**
+     * Day-cycle scaling for the probe's brightness. Rebuilding a PMREM every frame is not free, so a
+     * cycle dims the applied environment instead of re-baking it; without this the sky turns black at
+     * night while the IBL keeps lighting the world like noon.
+     */
+    daylight?: {
+        sunFactor: number;
+        ambientFactor: number;
+    };
 }
 /**
  * Image-based lighting from a procedural sky/horizon/ground probe with an HDR sun (not three's stock
@@ -29,7 +38,7 @@ export interface EnvironmentLightingProps {
  * Opt out of cinematic IBL with `look: "flat"` on the shell presentation.
  * @internal shell-internal default lighting; games never import it.
  */
-export declare function EnvironmentLighting({ source, intensity, skyColor, groundColor, horizonTint, sunDirection, sunColor, }: EnvironmentLightingProps): null;
+export declare function EnvironmentLighting({ source, intensity, skyColor, groundColor, horizonTint, sunDirection, sunColor, daylight, }: EnvironmentLightingProps): null;
 /** @internal Default IBL strength for the procedural probe: enough sky fill and sun lobe to model forms. */
 export declare const DEFAULT_IBL_INTENSITY = 0.45;
 /** @internal Fallback probe sun when no directional light is authored: high and off to one side. */

package/dist/render/EnvironmentLighting.js

@@ -1,5 +1,5 @@
 import { reportTextureLoadError } from "@jgengine/core/devtools/textureErrors";
-import { useThree } from "@react-three/fiber";
+import { useThree, useFrame } from "@react-three/fiber";
 import { useEffect } from "react";
 import * as THREE from "three";
 import { EXRLoader } from "three/examples/jsm/loaders/EXRLoader.js";
@@ -13,7 +13,7 @@ import { RGBELoader } from "three/examples/jsm/loaders/RGBELoader.js";
  * Opt out of cinematic IBL with `look: "flat"` on the shell presentation.
  * @internal shell-internal default lighting; games never import it.
  */
-export function EnvironmentLighting({ source, intensity = DEFAULT_IBL_INTENSITY, skyColor = "#87b5e0", groundColor = "#3d4a38", horizonTint = "#ffffff", sunDirection, sunColor = "#fff2d6", }) {
+export function EnvironmentLighting({ source, intensity = DEFAULT_IBL_INTENSITY, skyColor = "#87b5e0", groundColor = "#3d4a38", horizonTint = "#ffffff", sunDirection, sunColor = "#fff2d6", daylight, }) {
     const gl = useThree((state) => state.gl);
     const scene = useThree((state) => state.scene);
     useEffect(() => {
@@ -32,8 +32,10 @@ export function EnvironmentLighting({ source, intensity = DEFAULT_IBL_INTENSITY,
             if (cancelled)
                 return;
             cancelled = true;
-            if (target !== undefined && scene.environment === target.texture)
+            if (target !== undefined && scene.environment === target.texture) {
                 scene.environment = previous;
+                scene.environmentIntensity = previousIntensity;
+            }
             if (appliedRotation !== undefined && scene.environmentRotation === appliedRotation && appliedRotation.equals(appliedRotationValue))
                 scene.environmentRotation = previousRotation;
             if (scene.environmentIntensity === appliedIntensity)
@@ -106,6 +108,12 @@ export function EnvironmentLighting({ source, intensity = DEFAULT_IBL_INTENSITY,
         }
         return release;
     }, [gl, scene, source, intensity, skyColor, groundColor, horizonTint, sunColor, sunDirection?.[0], sunDirection?.[1], sunDirection?.[2]]);
+    useFrame(() => {
+        if (daylight === undefined || scene.environment === null)
+            return;
+        // Ambient fill and the probe's sun lobe fade together; the probe's colours stay authored.
+        scene.environmentIntensity = (source?.intensity ?? intensity) * (daylight.ambientFactor * 0.6 + daylight.sunFactor * 0.4);
+    });
     return null;
 }
 /** @internal Default IBL strength for the procedural probe: enough sky fill and sun lobe to model forms. */

package/dist/render/IrradianceVolumeLighting.d.ts

@@ -0,0 +1,18 @@
+import { type IrradianceVolume } from "@jgengine/core/render/lightProbes";
+/** @internal Props for shell {@link IrradianceVolumeLighting}. */
+export interface IrradianceVolumeLightingProps {
+    /** Baked volumes authored on the scene document; the one covering the camera wins. */
+    volumes: readonly IrradianceVolume[];
+}
+/**
+ * Ambient light from an authored irradiance volume: each frame it samples the volume that covers the
+ * camera and writes the nine SH coefficients into three's scene light probe. This is what makes an
+ * interior read as its own space — a room gets the fill from its own lamps and bounce instead of the
+ * sky's hemisphere, and the ambient varies as you walk through it.
+ *
+ * One light probe serves the whole scene, so a world with several volumes is sampled by camera
+ * position; that is exact while the camera is inside a room and approximate at the doorways between
+ * them.
+ * @internal shell-internal lighting; games author the volume on the scene document.
+ */
+export declare function IrradianceVolumeLighting({ volumes }: IrradianceVolumeLightingProps): import("react").JSX.Element;

package/dist/render/IrradianceVolumeLighting.js

@@ -0,0 +1,35 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useFrame } from "@react-three/fiber";
+import { useMemo, useRef } from "react";
+import * as THREE from "three";
+import { PROBE_STRIDE, sampleIrradianceVolume, selectIrradianceVolume, SH_COEFFICIENTS, } from "@jgengine/core/render/lightProbes";
+/**
+ * Ambient light from an authored irradiance volume: each frame it samples the volume that covers the
+ * camera and writes the nine SH coefficients into three's scene light probe. This is what makes an
+ * interior read as its own space — a room gets the fill from its own lamps and bounce instead of the
+ * sky's hemisphere, and the ambient varies as you walk through it.
+ *
+ * One light probe serves the whole scene, so a world with several volumes is sampled by camera
+ * position; that is exact while the camera is inside a room and approximate at the doorways between
+ * them.
+ * @internal shell-internal lighting; games author the volume on the scene document.
+ */
+export function IrradianceVolumeLighting({ volumes }) {
+    const probeRef = useRef(null);
+    const sampled = useMemo(() => new Float32Array(PROBE_STRIDE), []);
+    useFrame((state) => {
+        const probe = probeRef.current;
+        if (probe === null)
+            return;
+        const position = state.camera.position;
+        const volume = selectIrradianceVolume(volumes, [position.x, position.y, position.z]);
+        if (volume === undefined)
+            return;
+        if (!sampleIrradianceVolume(volume, [position.x, position.y, position.z], sampled))
+            return;
+        for (let band = 0; band < SH_COEFFICIENTS; band += 1) {
+            probe.sh.coefficients[band].set(sampled[band * 3], sampled[band * 3 + 1], sampled[band * 3 + 2]);
+        }
+    });
+    return _jsx("lightProbe", { ref: probeRef });
+}

package/dist/render/SceneLighting.d.ts

@@ -3,6 +3,17 @@ import type { BackdropConfig, LightingConfig, PointLightingConfig } from "@jgeng
 import type { GraphicsProfile } from "@jgengine/core/settings/graphicsProfile";
 /** Default cap for combined dynamic point and spot lights. */
 export declare const POINT_LIGHT_BUDGET = 8;
+/**
+ * Per-frame scaling a day cycle applies to a game's authored sun and ambient fill, so an authored
+ * sun sets and a moon rises instead of the world staying lit like noon after dark. `sunFactor` and
+ * `ambientFactor` are 1 at the authored noon peak; colors come from the atmosphere.
+ * @internal
+ */
+export interface DaylightModulation {
+    sunFactor: number;
+    sunColor: string;
+    ambientFactor: number;
+}
 /** @internal Clamp point lights for the runtime budget. */
 export declare function resolvePointLightBudget(entries: readonly PointLightingConfig[] | undefined): readonly PointLightingConfig[];
 /**
@@ -12,9 +23,11 @@ export declare function resolvePointLightBudget(entries: readonly PointLightingC
  * and `shadowCameraSize` is silently inert.
  */
 export declare function syncShadowProjection(light: DirectionalLight): void;
-export declare function ConfiguredLighting({ lighting, profile }: {
+export declare function ConfiguredLighting({ lighting, profile, modulation, }: {
     lighting: LightingConfig;
     profile?: GraphicsProfile;
+    /** Day-cycle scaling for the first directional (the sun) and the ambient fill. */
+    modulation?: DaylightModulation;
 }): import("react").JSX.Element;
 export declare function BackdropFog({ fog }: {
     fog: BackdropConfig["fog"];

package/dist/render/SceneLighting.js

@@ -1,5 +1,6 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useLayoutEffect, useRef } from "react";
+import { useFrame } from "@react-three/fiber";
 import { CascadedShadows, DEFAULT_SHADOW_RADIUS } from "./CascadedShadows.js";
 const DEFAULT_BACKDROP_FOG_COLOR = "#1a1c22";
 /** Default cap for combined dynamic point and spot lights. */
@@ -26,12 +27,12 @@ function resolveDynamicLights(lighting) {
 function usesCascades(entry) {
     return (entry.castShadow ?? false) && (entry.cascades ?? 1) > 1;
 }
-function DirectionalShadowLight({ entry, profile }) {
+function DirectionalShadowLight({ entry, profile, modulation }) {
     const resolved = profile === undefined ? entry : { ...entry, shadowMapSize: entry.shadowMapSize ?? profile.shadowMapSize, cascades: entry.cascades ?? profile.cascades };
     if (usesCascades(resolved)) {
-        return _jsx(CascadedShadows, { entry: resolved });
+        return _jsx(CascadedShadows, { entry: resolved, modulation: modulation });
     }
-    return _jsx(SingleShadowLight, { entry: resolved });
+    return _jsx(SingleShadowLight, { entry: resolved, modulation: modulation });
 }
 /**
  * Refresh a directional light's shadow projection after its frustum bounds change.
@@ -42,11 +43,19 @@ function DirectionalShadowLight({ entry, profile }) {
 export function syncShadowProjection(light) {
     light.shadow.camera.updateProjectionMatrix();
 }
-function SingleShadowLight({ entry }) {
+function SingleShadowLight({ entry, modulation }) {
     const lightRef = useRef(null);
     const size = entry.shadowCameraSize ?? 40;
     const far = Math.max(200, size * 6);
     const mapSize = entry.shadowMapSize ?? 1024;
+    const baseIntensity = entry.intensity ?? 1.3;
+    useFrame(() => {
+        const light = lightRef.current;
+        if (light === null || modulation === undefined)
+            return;
+        light.intensity = baseIntensity * modulation.sunFactor;
+        light.color.set(modulation.sunColor);
+    });
     useLayoutEffect(() => {
         if (lightRef.current !== null)
             syncShadowProjection(lightRef.current);
@@ -60,13 +69,25 @@ function SingleShadowLight({ entry }) {
     }, [mapSize]);
     return (_jsx("directionalLight", { ref: lightRef, position: [entry.position[0], entry.position[1], entry.position[2]], intensity: entry.intensity ?? 1.3, color: entry.color, castShadow: entry.castShadow ?? false, "shadow-mapSize-width": mapSize, "shadow-mapSize-height": mapSize, "shadow-camera-left": -size, "shadow-camera-right": size, "shadow-camera-top": size, "shadow-camera-bottom": -size, "shadow-camera-near": 0.5, "shadow-camera-far": far, "shadow-bias": entry.shadowBias ?? -0.0004, "shadow-normalBias": entry.shadowNormalBias ?? 0.02, "shadow-radius": entry.shadowRadius ?? DEFAULT_SHADOW_RADIUS }));
 }
-export function ConfiguredLighting({ lighting, profile }) {
+export function ConfiguredLighting({ lighting, profile, modulation, }) {
     const dynamic = resolveDynamicLights(lighting);
-    return (_jsxs(_Fragment, { children: [lighting.ambient !== undefined ? (_jsx("ambientLight", { color: lighting.ambient.color, intensity: lighting.ambient.intensity ?? 0.55 })) : null, lighting.hemisphere !== undefined ? (_jsx("hemisphereLight", { args: [
+    const ambientRef = useRef(null);
+    const hemisphereRef = useRef(null);
+    const baseAmbient = lighting.ambient?.intensity ?? 0.55;
+    const baseHemisphere = lighting.hemisphere?.intensity ?? 0.55;
+    useFrame(() => {
+        if (modulation === undefined)
+            return;
+        if (ambientRef.current !== null)
+            ambientRef.current.intensity = baseAmbient * modulation.ambientFactor;
+        if (hemisphereRef.current !== null)
+            hemisphereRef.current.intensity = baseHemisphere * modulation.ambientFactor;
+    });
+    return (_jsxs(_Fragment, { children: [lighting.ambient !== undefined ? (_jsx("ambientLight", { ref: ambientRef, color: lighting.ambient.color, intensity: baseAmbient })) : null, lighting.hemisphere !== undefined ? (_jsx("hemisphereLight", { ref: hemisphereRef, args: [
                     lighting.hemisphere.skyColor ?? "#bfe3ff",
                     lighting.hemisphere.groundColor ?? "#4c6b34",
-                    lighting.hemisphere.intensity ?? 0.55,
-                ] })) : null, (lighting.directional ?? []).map((entry, index) => (_jsx(DirectionalShadowLight, { entry: entry, profile: profile }, index))), dynamic.point.map((entry, index) => (_jsx("pointLight", { position: [entry.position[0], entry.position[1], entry.position[2]], intensity: entry.intensity ?? 1, color: entry.color, distance: entry.distance ?? 0, decay: entry.decay ?? 2, castShadow: entry.castShadow ?? false }, index))), dynamic.spot.map((entry, index) => (_jsx("spotLight", { position: [entry.position[0], entry.position[1], entry.position[2]], intensity: entry.intensity ?? 1, color: entry.color, distance: entry.distance ?? 0, decay: entry.decay ?? 2, angle: entry.angle ?? Math.PI / 6, penumbra: entry.penumbra ?? 0, castShadow: entry.castShadow ?? false, "target-position": [...(entry.target ?? [0, 0, 0])] }, index)))] }));
+                    baseHemisphere,
+                ] })) : null, (lighting.directional ?? []).map((entry, index) => (_jsx(DirectionalShadowLight, { entry: entry, profile: profile, ...(index === 0 && modulation !== undefined ? { modulation } : {}) }, index))), dynamic.point.map((entry, index) => (_jsx("pointLight", { position: [entry.position[0], entry.position[1], entry.position[2]], intensity: entry.intensity ?? 1, color: entry.color, distance: entry.distance ?? 0, decay: entry.decay ?? 2, castShadow: entry.castShadow ?? false }, index))), dynamic.spot.map((entry, index) => (_jsx("spotLight", { position: [entry.position[0], entry.position[1], entry.position[2]], intensity: entry.intensity ?? 1, color: entry.color, distance: entry.distance ?? 0, decay: entry.decay ?? 2, angle: entry.angle ?? Math.PI / 6, penumbra: entry.penumbra ?? 0, castShadow: entry.castShadow ?? false, "target-position": [...(entry.target ?? [0, 0, 0])] }, index)))] }));
 }
 export function BackdropFog({ fog }) {
     if (fog === undefined)

package/dist/render/authoredGrade.d.ts

@@ -0,0 +1,11 @@
+import type { DocumentColorGrade } from "@jgengine/core/editor/environment";
+import type { ResolvedGameLook } from "@jgengine/core/render/lookPreset";
+/**
+ * Folds a scene document's authored grade into the resolved look. The document is the authoring
+ * source, so its baked LUT and exposure range win over the game's static post config, and everything
+ * the document left unauthored stays exactly as the game or look preset set it. With no authored
+ * grade the look comes back untouched (same identity), so an ungraded game mounts the pipeline it
+ * always mounted.
+ * @internal
+ */
+export declare function withAuthoredGrade(look: ResolvedGameLook, grade: DocumentColorGrade | undefined): ResolvedGameLook;

package/dist/render/authoredGrade.js

@@ -0,0 +1,26 @@
+/**
+ * Folds a scene document's authored grade into the resolved look. The document is the authoring
+ * source, so its baked LUT and exposure range win over the game's static post config, and everything
+ * the document left unauthored stays exactly as the game or look preset set it. With no authored
+ * grade the look comes back untouched (same identity), so an ungraded game mounts the pipeline it
+ * always mounted.
+ * @internal
+ */
+export function withAuthoredGrade(look, grade) {
+    if (grade === undefined)
+        return look;
+    const post = look.postProcessing ?? { toneMapping: "agx", bloom: false };
+    const graded = grade.lut === undefined
+        ? post
+        : { ...post, grade: { ...(typeof post.grade === "object" ? post.grade : {}), lut: { cube: grade.lut } } };
+    if (grade.autoExposure === undefined) {
+        return { ...look, postProcessing: graded };
+    }
+    return {
+        ...look,
+        postProcessing: {
+            ...graded,
+            autoExposure: { ...(typeof graded.autoExposure === "object" ? graded.autoExposure : {}), ...grade.autoExposure },
+        },
+    };
+}

package/dist/render/presentationLook.d.ts

@@ -0,0 +1,15 @@
+import type { DocumentColorGrade } from "@jgengine/core/editor/environment";
+import { type GameLookInput, type ResolvedGameLook } from "@jgengine/core/render/lookPreset";
+import { type SkyEnvironmentDescriptor } from "@jgengine/core/world/features";
+/** The look the shell renders, resolved once per authored value. @internal */
+export interface PresentationLook {
+    look: ResolvedGameLook;
+    backdropSky: SkyEnvironmentDescriptor | undefined;
+}
+/**
+ * Resolve a game's look preset and backdrop sky, keeping one identity until an authored value
+ * changes. The post chain, sky dome and lighting rebuild on identity, so a fresh object per
+ * render recompiled every pass each frame.
+ * @internal
+ */
+export declare function usePresentationLook(input: GameLookInput, authoredGrade: DocumentColorGrade | undefined): PresentationLook;

package/dist/render/presentationLook.js

@@ -0,0 +1,18 @@
+import { useMemo } from "react";
+import { resolveGameLook } from "@jgengine/core/render/lookPreset";
+import { sky as resolveSkyDescriptor } from "@jgengine/core/world/features";
+import { withAuthoredGrade } from "./authoredGrade.js";
+/**
+ * Resolve a game's look preset and backdrop sky, keeping one identity until an authored value
+ * changes. The post chain, sky dome and lighting rebuild on identity, so a fresh object per
+ * render recompiled every pass each frame.
+ * @internal
+ */
+export function usePresentationLook(input, authoredGrade) {
+    const { look, lighting, backdrop, postProcessing, hasWorldSky } = input;
+    return useMemo(() => {
+        const resolved = withAuthoredGrade(resolveGameLook({ look, lighting, backdrop, postProcessing, hasWorldSky }), authoredGrade);
+        const sky = resolved.backdrop?.sky;
+        return { look: resolved, backdropSky: sky === undefined ? undefined : resolveSkyDescriptor(sky) };
+    }, [look, lighting, backdrop, postProcessing, hasWorldSky, authoredGrade]);
+}

package/dist/render/stableTextureSet.d.ts

@@ -0,0 +1,9 @@
+/** Whether two texture sets hold the same roles and texture instances. @internal */
+export declare function sameTextureSet(a: unknown, b: unknown): boolean;
+/**
+ * Keep one texture-set identity while its roles and texture instances are unchanged. The drei
+ * loader hands back a fresh keyed object per render, and materials built from it rebuilt and
+ * recompiled their shaders every frame.
+ * @internal
+ */
+export declare function useStableTextureSet<T extends object>(textures: T): T;