@jgengine/shell 0.18.0 → 0.19.0

package/dist/input/pointerLock.d.ts

@@ -0,0 +1,11 @@
+interface LockableElement {
+    requestPointerLock?: (options?: {
+        unadjustedMovement?: boolean;
+    }) => Promise<void> | void;
+}
+/**
+ * Request pointer lock with raw (unaccelerated) mouse deltas, falling back to a plain lock when
+ * the browser or OS rejects `unadjustedMovement`.
+ */
+export declare function requestRawPointerLock(element: LockableElement): void;
+export {};

package/dist/input/pointerLock.js

@@ -0,0 +1,19 @@
+/**
+ * Request pointer lock with raw (unaccelerated) mouse deltas, falling back to a plain lock when
+ * the browser or OS rejects `unadjustedMovement`.
+ */
+export function requestRawPointerLock(element) {
+    const request = element.requestPointerLock;
+    if (request === undefined)
+        return;
+    let pending;
+    try {
+        pending = request.call(element, { unadjustedMovement: true });
+    }
+    catch {
+        pending = request.call(element);
+    }
+    if (pending !== undefined && typeof pending.catch === "function") {
+        pending.catch(() => request.call(element)?.catch?.(() => undefined));
+    }
+}

package/dist/materialOverride.d.ts

@@ -2,7 +2,7 @@ import * as THREE from "three";
 import type { ModelMaterialOverride } from "@jgengine/core/game/playableGame";
 export interface MaterialOverrideOptions {
     clone?: boolean;
-    /** Loaded PBR textures matching `ModelMaterialOverride.maps`' roles, applied onto each `MeshStandardMaterial` alongside the tint override. The caller (a React component, via `useTexture`) owns loading; this function never fetches a URL. */
+    /** Loaded PBR textures matching `ModelMaterialOverride.maps`' roles, applied onto each standard or physical material alongside the tint override. The caller (a React component, via `useTexture`) owns loading; this function never fetches a URL. */
     textures?: MaterialOverrideTextures;
 }
 /** Loaded PBR textures for `applyMaterialOverride`'s `textures` option — matches `ModelMaterialMaps`' roles. */
@@ -11,6 +11,9 @@ export interface MaterialOverrideTextures {
     normal?: THREE.Texture;
     roughness?: THREE.Texture;
     ao?: THREE.Texture;
+    metalness?: THREE.Texture;
+    emissive?: THREE.Texture;
+    height?: THREE.Texture;
 }
 /** @internal */
 export declare function applyMaterialOverride(root: THREE.Object3D, override: ModelMaterialOverride, options?: MaterialOverrideOptions): void;

package/dist/materialOverride.js

@@ -13,7 +13,7 @@ export function applyMaterialOverride(root, override, options) {
     });
 }
 function overrideOne(material, override, clone, textures) {
-    if (!(material instanceof THREE.MeshStandardMaterial))
+    if (!isStandardOrPhysicalMaterial(material))
         return material;
     const target = clone ? material.clone() : material;
     if (override.color !== undefined)
@@ -34,12 +34,21 @@ function overrideOne(material, override, clone, textures) {
         target.roughnessMap = textures.roughness;
     if (textures?.ao !== undefined)
         target.aoMap = textures.ao;
+    if (textures?.metalness !== undefined)
+        target.metalnessMap = textures.metalness;
+    if (textures?.emissive !== undefined)
+        target.emissiveMap = textures.emissive;
+    if (textures?.height !== undefined)
+        target.displacementMap = textures.height;
     if (textures !== undefined)
         target.needsUpdate = true;
     if (override.rim !== undefined)
         applyRimLight(target, override.rim);
     return target;
 }
+function isStandardOrPhysicalMaterial(material) {
+    return material.isMeshStandardMaterial === true;
+}
 /**
  * Adds a fresnel rim term to a standard material's outgoing light. Patched through
  * `onBeforeCompile` rather than as a second pass so the rim shadows, fogs, and tonemaps with the

package/dist/postfx/PostProcessing.d.ts

@@ -3,17 +3,20 @@ import type { GraphicsQuality } from "@jgengine/core/settings/settingsModel";
 /**
  * Mounts an `EffectComposer` inside the shell Canvas and takes over rendering
  * (priority-1 `useFrame`, which disables R3F auto-render) to run the configured
- * post chain: RenderPass → GTAO → UnrealBloom → SMAA → OutputPass → Grade. Rendered only
+ * post chain: RenderPass → GTAO → UnrealBloom → SMAA → OutputPass → Stylize → Grade. Rendered only
  * when `PlayableGame.postProcessing` is set, so games without it draw unchanged.
  *
- * `quality` (the player's graphics-quality setting) gates the passes whose cost
- * scales with scene geometry or resolution beyond the dpr cap: GTAO re-renders
- * the whole scene for depth/normals and runs a multi-sample full-screen pass,
- * and Bokeh DOF renders scene depth again — both run on "high" only. Bloom,
- * SMAA, tone mapping, and grade stay on every tier (SMAA is the cheap edge fix
- * for alpha-tested foliage that MSAA samples alone leave crawling).
+ * `stages` (resolved from the player's graphics profile) controls expensive passes
+ * independently. Medium keeps AO and DOF with reduced AO sampling; low can disable
+ * them while retaining cheaper bloom, SMAA, tone mapping, and grade stages.
  */
-export declare function PostProcessing({ config, quality }: {
+export declare function PostProcessing({ config, quality, stages }: {
     config: PostProcessingConfig;
     quality?: GraphicsQuality;
+    stages?: {
+        ao: boolean;
+        bloom: boolean;
+        dof: boolean;
+        smaa: boolean;
+    };
 }): null;

package/dist/postfx/PostProcessing.js

@@ -7,6 +7,7 @@ import { GTAOPass } from "three/examples/jsm/postprocessing/GTAOPass.js";
 import { BokehPass } from "three/examples/jsm/postprocessing/BokehPass.js";
 import { SMAAPass } from "three/examples/jsm/postprocessing/SMAAPass.js";
 import { createGradePass } from "./gradeShader.js";
+import { StylizePass } from "./stylizePass.js";
 import { hidePostfxOverlays, restorePostfxOverlays } from "./postfxOverlay.js";
 /**
  * GTAO renders the scene with an `overrideMaterial` normal/depth prepass, which stamps
@@ -60,17 +61,14 @@ function syncSize(built, width, height, pixelRatio) {
 /**
  * Mounts an `EffectComposer` inside the shell Canvas and takes over rendering
  * (priority-1 `useFrame`, which disables R3F auto-render) to run the configured
- * post chain: RenderPass → GTAO → UnrealBloom → SMAA → OutputPass → Grade. Rendered only
+ * post chain: RenderPass → GTAO → UnrealBloom → SMAA → OutputPass → Stylize → Grade. Rendered only
  * when `PlayableGame.postProcessing` is set, so games without it draw unchanged.
  *
- * `quality` (the player's graphics-quality setting) gates the passes whose cost
- * scales with scene geometry or resolution beyond the dpr cap: GTAO re-renders
- * the whole scene for depth/normals and runs a multi-sample full-screen pass,
- * and Bokeh DOF renders scene depth again — both run on "high" only. Bloom,
- * SMAA, tone mapping, and grade stay on every tier (SMAA is the cheap edge fix
- * for alpha-tested foliage that MSAA samples alone leave crawling).
+ * `stages` (resolved from the player's graphics profile) controls expensive passes
+ * independently. Medium keeps AO and DOF with reduced AO sampling; low can disable
+ * them while retaining cheaper bloom, SMAA, tone mapping, and grade stages.
  */
-export function PostProcessing({ config, quality = "high" }) {
+export function PostProcessing({ config, quality = "high", stages }) {
     const gl = useThree((s) => s.gl);
     const scene = useThree((s) => s.scene);
     const camera = useThree((s) => s.camera);
@@ -87,8 +85,8 @@ export function PostProcessing({ config, quality = "high" }) {
         });
         const composer = new EffectComposer(gl, target);
         composer.addPass(new RenderPass(scene, camera));
-        const heavyPasses = quality === "high";
-        if (heavyPasses && config.ao !== undefined && config.ao !== false) {
+        const resolvedStages = stages ?? { ao: quality === "high", bloom: true, dof: quality === "high", smaa: true };
+        if (resolvedStages.ao && config.ao !== undefined && config.ao !== false) {
             const ao = new OverlayAwareGTAOPass(scene, camera, width, height);
             ao.blendIntensity = config.ao.blend ?? 1;
             ao.updateGtaoMaterial({
@@ -96,29 +94,32 @@ export function PostProcessing({ config, quality = "high" }) {
                 distanceExponent: 1,
                 thickness: config.ao.distanceFalloff ?? 3.6,
                 scale: config.ao.intensity ?? 2.4,
-                samples: 16,
+                samples: quality === "high" ? 16 : 8,
             });
             composer.addPass(ao);
         }
-        if (config.bloom !== false) {
+        if (resolvedStages.bloom && config.bloom !== false) {
             const b = config.bloom ?? {};
             composer.addPass(new UnrealBloomPass(new THREE.Vector2(width, height), b.strength ?? 0.32, b.radius ?? 0.55, b.threshold ?? 0.85));
         }
         let dof = null;
-        if (heavyPasses && config.dof !== undefined && config.dof !== false) {
+        if (resolvedStages.dof && config.dof !== undefined && config.dof !== false) {
             const d = config.dof;
             dof = new OverlayAwareBokehPass(scene, camera, {
                 focus: d.focus ?? 18,
-                aperture: d.aperture ?? 0.00025,
+                aperture: d.aperture ?? (quality === "high" ? 0.00025 : 0.00012),
                 maxblur: d.maxBlur ?? 0.01,
             });
             composer.addPass(dof);
         }
         // SMAA must run before OutputPass (linear-sRGB). Default on for post chains.
-        if (aa === "smaa") {
+        if (resolvedStages.smaa && aa === "smaa") {
             composer.addPass(new SMAAPass());
         }
         composer.addPass(new OutputPass());
+        if (config.stylize !== undefined && config.stylize !== false) {
+            composer.addPass(new StylizePass(scene, camera, config.stylize));
+        }
         let grade = null;
         if (config.grade !== false) {
             grade = createGradePass(config.grade ?? {});
@@ -131,7 +132,28 @@ export function PostProcessing({ config, quality = "high" }) {
             disposeGraph(graph);
             builtRef.current = null;
         };
-    }, [gl, scene, camera, config, quality]);
+    }, [gl, scene, camera, config, quality, stages]);
+    useEffect(() => {
+        const lut = config.grade !== undefined && config.grade !== false ? config.grade.lut : undefined;
+        const grade = builtRef.current?.grade;
+        if (lut === undefined || grade === null || grade === undefined)
+            return;
+        let cancelled = false;
+        const loader = new THREE.TextureLoader();
+        loader.loadAsync(lut.url).then((texture) => {
+            if (cancelled) {
+                texture.dispose();
+                return;
+            }
+            texture.colorSpace = THREE.SRGBColorSpace;
+            texture.minFilter = THREE.NearestFilter;
+            texture.magFilter = THREE.NearestFilter;
+            texture.generateMipmaps = false;
+            grade.uniforms.uLut.value = texture;
+            grade.uniforms.uLutSize.value = lut.size ?? 32;
+        }).catch(() => undefined);
+        return () => { cancelled = true; };
+    }, [config.grade]);
     useEffect(() => {
         const prevTone = gl.toneMapping;
         const prevExposure = gl.toneMappingExposure;

package/dist/postfx/gradeShader.js

@@ -17,12 +17,22 @@ const fragmentShader = /* glsl */ `
   uniform float uGrain;
   uniform float uChroma;
   uniform float uTime;
+  uniform sampler2D uLut;
+  uniform float uLutSize;
   varying vec2 vUv;
 
   float hash(vec2 p) {
     return fract(sin(dot(p, vec2(12.9898, 78.233))) * 43758.5453);
   }
 
+  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;
+  }
+
   void main() {
     vec2 dir = vUv - 0.5;
     // Chromatic aberration: split RGB along the radial direction, growing toward the edges.
@@ -35,6 +45,7 @@ const fragmentShader = /* glsl */ `
     c = pow(max(c, 0.0), vec3(uGamma));
     float luma = dot(c, vec3(0.2126, 0.7152, 0.0722));
     c = mix(vec3(luma), c, uSaturation);
+    if (uLutSize > 1.0) c = sampleLut(c);
     vec2 d = vUv - 0.5;
     float vig = 1.0 - uVignette * smoothstep(0.6, 0.95, dot(d, d) * 2.2);
     c *= vig;
@@ -65,6 +76,8 @@ export function createGradePass(config = {}) {
             uGrain: { value: config.grain ?? DEFAULT_GRAIN },
             uChroma: { value: config.chromaticAberration ?? DEFAULT_CHROMA },
             uTime: { value: 0 },
+            uLut: { value: null },
+            uLutSize: { value: 0 },
         },
         vertexShader,
         fragmentShader,

package/dist/postfx/stylizePass.d.ts

@@ -0,0 +1,23 @@
+import * as THREE from "three";
+import { Pass } from "three-stdlib";
+import type { StylizeConfig } from "@jgengine/core/render/postProcessing";
+/**
+ * Art-style post pass: ink outlines from a normal+depth prepass, cel luminance bands, and
+ * pixelation. Runs on the display-space frame after `OutputPass`. The prepass renders only
+ * when outlines are on, and reuses the frame's shadow maps instead of re-rendering them.
+ */
+export declare class StylizePass extends Pass {
+    private readonly scene;
+    private readonly camera;
+    private readonly quad;
+    private readonly material;
+    private readonly normalTarget;
+    private readonly normalMaterial;
+    private readonly hidden;
+    private readonly clearColor;
+    constructor(scene: THREE.Scene, camera: THREE.Camera, config: StylizeConfig);
+    setSize(width: number, height: number): void;
+    render(renderer: THREE.WebGLRenderer, writeBuffer: THREE.WebGLRenderTarget, readBuffer: THREE.WebGLRenderTarget): void;
+    private renderPrepass;
+    dispose(): void;
+}

package/dist/postfx/stylizePass.js

@@ -0,0 +1,216 @@
+import * as THREE from "three";
+import { FullScreenQuad, Pass } from "three-stdlib";
+import { isPostfxOverlay } from "./postfxOverlay.js";
+const DEFAULT_OUTLINE_COLOR = "#101014";
+const DEFAULT_DEPTH_THRESHOLD = 0.08;
+const DEFAULT_NORMAL_THRESHOLD = 0.35;
+const DEFAULT_FADE_DISTANCE = 160;
+const fragmentShader = /* glsl */ `
+  #include <packing>
+  uniform sampler2D tDiffuse;
+  uniform sampler2D tNormal;
+  uniform sampler2D tDepth;
+  uniform vec2 uResolution;
+  uniform float uNear;
+  uniform float uFar;
+  uniform bool uOrtho;
+  uniform bool uOutline;
+  uniform vec3 uOutlineColor;
+  uniform float uOutlineOpacity;
+  uniform float uThickness;
+  uniform float uDepthThreshold;
+  uniform float uNormalThreshold;
+  uniform float uFade;
+  uniform float uBands;
+  uniform float uPixel;
+  varying vec2 vUv;
+
+  float viewDepth(vec2 uv) {
+    float d = texture2D(tDepth, uv).x;
+    return -(uOrtho ? orthographicDepthToViewZ(d, uNear, uFar) : perspectiveDepthToViewZ(d, uNear, uFar));
+  }
+
+  vec3 viewNormal(vec2 uv) {
+    return texture2D(tNormal, uv).xyz * 2.0 - 1.0;
+  }
+
+  // Ink a normal crease only on its nearer side, so a thin or tiny feature stays one line wide
+  // instead of stamping a plus-shaped blot onto the surface behind it.
+  float crease(vec3 nc, float dc, vec2 uv, float dn) {
+    return (1.0 - dot(nc, viewNormal(uv))) * step(dc, dn + dc * 0.02);
+  }
+
+  void main() {
+    vec2 uv = vUv;
+    if (uPixel > 1.0) {
+      vec2 block = uPixel / uResolution;
+      uv = (floor(uv / block) + 0.5) * block;
+    }
+    vec3 c = texture2D(tDiffuse, uv).rgb;
+
+    if (uBands > 0.5) {
+      float luma = dot(c, vec3(0.2126, 0.7152, 0.0722));
+      float x = min(luma * uBands, uBands - 0.001);
+      // Each band takes its centre brightness: the darkest band keeps colour instead of going black
+      // and the top band never clips a bright sky to flat white. A narrow soft step hides aliasing.
+      float q = (floor(x) + 0.5 + smoothstep(0.92, 1.0, fract(x))) / uBands;
+      c *= q / max(luma, 1e-4);
+    }
+
+    if (uOutline) {
+      vec2 px = uThickness / uResolution;
+      float dc = viewDepth(uv);
+      float dl = viewDepth(uv - vec2(px.x, 0.0));
+      float dr = viewDepth(uv + vec2(px.x, 0.0));
+      float dd = viewDepth(uv - vec2(0.0, px.y));
+      float du = viewDepth(uv + vec2(0.0, px.y));
+      // Laplacian is zero across flat planes at any angle, so only real depth breaks draw lines.
+      float lap = abs(dl + dr + dd + du - 4.0 * dc) / max(dc, 1e-3);
+      float nearest = min(dc, min(min(dl, dr), min(dd, du)));
+      // Same nearer-side rule as creases: the background around a silhouette stays clean.
+      float depthEdge = smoothstep(uDepthThreshold, uDepthThreshold * 2.0, lap) * step(dc, nearest + dc * 0.03);
+
+      vec3 nc = viewNormal(uv);
+      float nd = max(
+        max(crease(nc, dc, uv - vec2(px.x, 0.0), dl), crease(nc, dc, uv + vec2(px.x, 0.0), dr)),
+        max(crease(nc, dc, uv - vec2(0.0, px.y), dd), crease(nc, dc, uv + vec2(0.0, px.y), du))
+      );
+      float normalEdge = smoothstep(uNormalThreshold, uNormalThreshold + 0.25, nd);
+
+      float fade = 1.0 - smoothstep(uFade * 0.5, uFade, nearest);
+      float edge = max(depthEdge, normalEdge) * fade * uOutlineOpacity;
+      c = mix(c, uOutlineColor, clamp(edge, 0.0, 1.0));
+    }
+
+    gl_FragColor = vec4(c, 1.0);
+  }
+`;
+const vertexShader = /* glsl */ `
+  varying vec2 vUv;
+  void main() {
+    vUv = uv;
+    gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+  }
+`;
+function skipsDepthPrepass(material) {
+    const list = Array.isArray(material) ? material : [material];
+    // Shader materials place vertices in their own code, which the override material cannot reproduce.
+    return list.some((m) => m.transparent || m.alphaTest > 0 || !m.depthWrite || !m.colorWrite || m.isShaderMaterial === true);
+}
+/**
+ * Hide what the outline prepass must not see: marked overlays, points/lines/sprites, custom
+ * shader meshes, and transparent or alpha-cut meshes (foliage cards would otherwise outline as
+ * solid quads).
+ */
+function hideForPrepass(scene, out) {
+    out.length = 0;
+    scene.traverse((object) => {
+        if (!object.visible)
+            return;
+        const drawable = object;
+        const hide = isPostfxOverlay(object) ||
+            object.isPoints === true ||
+            object.isLine === true ||
+            object.isSprite === true ||
+            (drawable.isMesh === true && skipsDepthPrepass(drawable.material));
+        if (!hide)
+            return;
+        object.visible = false;
+        out.push(object);
+    });
+}
+/**
+ * Art-style post pass: ink outlines from a normal+depth prepass, cel luminance bands, and
+ * pixelation. Runs on the display-space frame after `OutputPass`. The prepass renders only
+ * when outlines are on, and reuses the frame's shadow maps instead of re-rendering them.
+ */
+export class StylizePass extends Pass {
+    scene;
+    camera;
+    quad;
+    material;
+    normalTarget;
+    normalMaterial = new THREE.MeshNormalMaterial();
+    hidden = [];
+    clearColor = new THREE.Color();
+    constructor(scene, camera, config) {
+        super();
+        this.scene = scene;
+        this.camera = camera;
+        const outline = config.outline === undefined || config.outline === false ? null : config.outline;
+        this.normalTarget = outline === null
+            ? null
+            : new THREE.WebGLRenderTarget(1, 1, { depthTexture: new THREE.DepthTexture(1, 1), type: THREE.UnsignedByteType });
+        this.material = new THREE.ShaderMaterial({
+            uniforms: {
+                tDiffuse: { value: null },
+                tNormal: { value: this.normalTarget?.texture ?? null },
+                tDepth: { value: this.normalTarget?.depthTexture ?? null },
+                uResolution: { value: new THREE.Vector2(1, 1) },
+                uNear: { value: 0.1 },
+                uFar: { value: 1000 },
+                uOrtho: { value: false },
+                uOutline: { value: outline !== null },
+                uOutlineColor: { value: new THREE.Color(outline?.color ?? DEFAULT_OUTLINE_COLOR) },
+                uOutlineOpacity: { value: outline?.opacity ?? 1 },
+                uThickness: { value: Math.max(0.5, outline?.thickness ?? 1) },
+                uDepthThreshold: { value: outline?.depthThreshold ?? DEFAULT_DEPTH_THRESHOLD },
+                uNormalThreshold: { value: outline?.normalThreshold ?? DEFAULT_NORMAL_THRESHOLD },
+                uFade: { value: outline?.fadeDistance ?? DEFAULT_FADE_DISTANCE },
+                uBands: { value: Math.max(0, Math.floor(config.bands ?? 0)) },
+                uPixel: { value: Math.max(0, config.pixelSize ?? 0) },
+            },
+            vertexShader,
+            fragmentShader,
+            depthTest: false,
+            depthWrite: false,
+        });
+        this.quad = new FullScreenQuad(this.material);
+    }
+    setSize(width, height) {
+        this.material.uniforms.uResolution.value.set(width, height);
+        this.normalTarget?.setSize(width, height);
+    }
+    render(renderer, writeBuffer, readBuffer) {
+        const uniforms = this.material.uniforms;
+        if (this.normalTarget !== null)
+            this.renderPrepass(renderer, this.normalTarget);
+        const camera = this.camera;
+        uniforms.uNear.value = camera.near;
+        uniforms.uFar.value = camera.far;
+        uniforms.uOrtho.value = camera.isOrthographicCamera === true;
+        uniforms.tDiffuse.value = readBuffer.texture;
+        renderer.setRenderTarget(this.renderToScreen ? null : writeBuffer);
+        this.quad.render(renderer);
+    }
+    renderPrepass(renderer, target) {
+        const scene = this.scene;
+        const previousOverride = scene.overrideMaterial;
+        const previousBackground = scene.background;
+        const previousShadowUpdate = renderer.shadowMap.autoUpdate;
+        const previousClearAlpha = renderer.getClearAlpha();
+        renderer.getClearColor(this.clearColor);
+        hideForPrepass(scene, this.hidden);
+        scene.overrideMaterial = this.normalMaterial;
+        scene.background = null;
+        renderer.shadowMap.autoUpdate = false;
+        renderer.setRenderTarget(target);
+        renderer.setClearColor(0x8080ff, 1);
+        renderer.clear();
+        renderer.render(scene, this.camera);
+        renderer.setClearColor(this.clearColor, previousClearAlpha);
+        renderer.shadowMap.autoUpdate = previousShadowUpdate;
+        scene.background = previousBackground;
+        scene.overrideMaterial = previousOverride;
+        for (const object of this.hidden)
+            object.visible = true;
+        this.hidden.length = 0;
+    }
+    dispose() {
+        this.material.dispose();
+        this.normalMaterial.dispose();
+        this.quad.dispose();
+        this.normalTarget?.depthTexture?.dispose();
+        this.normalTarget?.dispose();
+    }
+}

package/dist/render/CascadedShadows.d.ts

@@ -1,3 +1,4 @@
+import * as THREE from "three";
 import type { DirectionalLightingConfig } from "@jgengine/core/game/playableGame";
 /**
  * Cascaded shadow maps for one directional light — outdoor scenes keep shadows past a
@@ -11,3 +12,13 @@ import type { DirectionalLightingConfig } from "@jgengine/core/game/playableGame
 export declare function CascadedShadows({ entry }: {
     entry: DirectionalLightingConfig;
 }): null;
+/** Structural slice of CSM so the patcher is testable without a renderer. */
+export interface CsmMaterialSetup {
+    setupMaterial(material: THREE.Material): void;
+}
+/**
+ * Run CSM's `setupMaterial` over every unpatched standard material in the scene,
+ * chaining rather than clobbering a material's own `onBeforeCompile`. Called every
+ * frame (WeakSet-guarded) so streamed meshes never render lit by all cascades at once.
+ */
+export declare function patchSceneMaterials(scene: THREE.Scene, csm: CsmMaterialSetup, patched: WeakSet<THREE.Material>): void;

package/dist/render/CascadedShadows.js

@@ -19,7 +19,6 @@ export function CascadedShadows({ entry }) {
     const scene = useThree((s) => s.scene);
     const csmRef = useRef(null);
     const patchedRef = useRef(new WeakSet());
-    const frameRef = useRef(0);
     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]);
@@ -47,7 +46,6 @@ export function CascadedShadows({ entry }) {
         patchedRef.current = new WeakSet();
         patchSceneMaterials(scene, csm, patchedRef.current);
         csmRef.current = csm;
-        frameRef.current = 0;
         return () => {
             csm.dispose();
             csmRef.current = null;
@@ -71,16 +69,19 @@ export function CascadedShadows({ entry }) {
         if (csm === null)
             return;
         csm.camera = camera;
-        frameRef.current += 1;
-        // Async model mounts need setupMaterial — re-scan every 30 frames after the first.
-        if (frameRef.current === 1 || frameRef.current % 30 === 0) {
-            patchSceneMaterials(scene, csm, patchedRef.current);
-        }
+        // Every frame: a mesh that renders before setupMaterial receives all cascade
+        // lights at once (a cascades× sun) — the WeakSet keeps the traverse cheap.
+        patchSceneMaterials(scene, csm, patchedRef.current);
         csm.update();
     });
     return null;
 }
-function patchSceneMaterials(scene, csm, patched) {
+/**
+ * Run CSM's `setupMaterial` over every unpatched standard material in the scene,
+ * chaining rather than clobbering a material's own `onBeforeCompile`. Called every
+ * frame (WeakSet-guarded) so streamed meshes never render lit by all cascades at once.
+ */
+export function patchSceneMaterials(scene, csm, patched) {
     scene.traverse((obj) => {
         const mesh = obj;
         if (!mesh.isMesh)
@@ -89,7 +90,17 @@ function patchSceneMaterials(scene, csm, patched) {
         for (const mat of materials) {
             if (!isStandardMaterial(mat) || patched.has(mat))
                 continue;
+            const prior = mat.onBeforeCompile;
             csm.setupMaterial(mat);
+            const csmHook = mat.onBeforeCompile;
+            if (prior !== THREE.Material.prototype.onBeforeCompile && prior !== csmHook) {
+                // setupMaterial assigns onBeforeCompile, which would drop a material's own
+                // shader surgery (rim light, detail maps) — run both, the material's first.
+                mat.onBeforeCompile = function (shader, renderer) {
+                    prior.call(this, shader, renderer);
+                    csmHook.call(this, shader, renderer);
+                };
+            }
             patched.add(mat);
         }
     });

package/dist/render/EnvironmentLighting.d.ts

@@ -1,5 +1,8 @@
+import type { EnvironmentSource } from "@jgengine/core/render/environment";
 /** @internal Props for shell {@link EnvironmentLighting}. */
 export interface EnvironmentLightingProps {
+    /** Optional authored environment map; absent or `gradient` uses the procedural probe. */
+    source?: EnvironmentSource;
     /** IBL intensity. Default 0.35. */
     intensity?: number;
     /** Upper-hemisphere tint for the procedural sky probe. Default cool daylight. */
@@ -23,4 +26,4 @@ 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({ intensity, skyColor, groundColor, sunDirection, sunColor, }: EnvironmentLightingProps): null;
+export declare function EnvironmentLighting({ source, intensity, skyColor, groundColor, sunDirection, sunColor, }: EnvironmentLightingProps): null;