@jgengine/shell 0.19.0 → 0.22.0

package/dist/presentationRecovery.d.ts

@@ -0,0 +1,75 @@
+import { Component, type ErrorInfo, type ReactNode } from "react";
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+/** Marks only a rejected presentation import for page reload; browser module failures are cached. @internal */
+export declare function markPresentationCodeLoadFailure(error: unknown): Error;
+/** @internal Distinguishes module loading from recoverable assets without guessing from error text. */
+export declare function presentationRecoveryAction(error: unknown): "reload" | "retry";
+/** @internal Classifies a reported React error after its owning boundary commits. */
+export declare function deferUnhandledPresentationError(error: unknown, report: () => void): void;
+/** @internal Exact pending texture groups owned by one presentation, including uncommitted Suspense. */
+export declare function createPresentationRetryRegistry(defaultClear?: (inputs: string[]) => void): {
+    register(inputs: readonly string[], clear?: ((inputs: string[]) => void) | undefined): () => void;
+    retry(): void;
+};
+type RetryRegistry = ReturnType<typeof createPresentationRetryRegistry>;
+type PresentationRetryScope = {
+    registry: RetryRegistry;
+    fail: (error: unknown, stack?: string) => void;
+    recoveredDraw: () => void;
+};
+/** Renderer-only loader adapters share the DOM owner without importing their libraries here. @internal */
+export declare function usePresentationRetryScope(): PresentationRetryScope | null;
+/** @internal Forwards renderer-local loader errors to the owning DOM presentation. */
+export declare function PresentationAssetBoundary({ children }: {
+    children: ReactNode;
+}): ReactNode;
+/** @internal Retires only diagnostics belonging to this exact handled presentation error. */
+export declare function createPresentationDiagnosticOwnership(): {
+    register(error: unknown, id: number, phase: string): void;
+    recovered(error: unknown): ReadonlySet<number>;
+};
+/** Restores an owned recovered surface only after Suspense has attached and revealed it. @internal */
+export declare function createPlaySurfaceFocusOwnership<Owner>(): {
+    request(owner: Owner): void;
+    reveal(owner: Owner, surface: HTMLElement | null, active: Element | null, body: HTMLElement): boolean;
+};
+/** Reports the owning presentation attempt and recovery lifecycle. @internal */
+export type PresentationRecoveryEvent = {
+    phase: string;
+    attempt: number;
+    scope: number;
+    sameOwner: boolean;
+    pending: boolean;
+    failed: boolean;
+};
+type RecoveryProps = {
+    ctx: GameContext;
+    children: ReactNode;
+    onRuntimeError: (error: unknown, phase: string, componentStack?: string) => void;
+    onRetryCommitted?: () => void;
+    onRecoveredDraw?: (error: unknown) => void;
+    onRecoveryEvent?: (event: PresentationRecoveryEvent) => void;
+};
+type RecoveryState = {
+    owner: GameContext;
+    failed: boolean;
+    error: unknown;
+    registry: RetryRegistry;
+};
+/** @internal Retains the live context for asset Retry; failed browser modules require page reload. */
+export declare class PresentationRecovery extends Component<RecoveryProps, RecoveryState> {
+    state: RecoveryState;
+    static getDerivedStateFromProps(props: RecoveryProps, state: RecoveryState): Partial<RecoveryState> | null;
+    static getDerivedStateFromError(error: unknown): Partial<RecoveryState>;
+    componentDidCatch(error: unknown, info: ErrorInfo): void;
+    componentDidUpdate(previousProps: RecoveryProps, previousState: RecoveryState): void;
+    componentWillUnmount(): void;
+    private attempt;
+    private scopeId;
+    private trace;
+    private scope;
+    private pendingRecovery;
+    private retry;
+    render(): ReactNode;
+}
+export {};

package/dist/presentationRecovery.js

@@ -0,0 +1,204 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Component, createContext, useContext, useId, useLayoutEffect } from "react";
+import { suspendPlayControls } from "@jgengine/core/game/controlGate";
+import { ErrorReportActions, errorReportContext } from "./diagnostics/RuntimeDiagnostics.js";
+const handledPresentationErrors = new WeakSet();
+const codeLoadFailures = new WeakSet();
+/** Marks only a rejected presentation import for page reload; browser module failures are cached. @internal */
+export function markPresentationCodeLoadFailure(error) {
+    const failure = error instanceof Error ? error : new Error(String(error));
+    codeLoadFailures.add(failure);
+    return failure;
+}
+/** @internal Distinguishes module loading from recoverable assets without guessing from error text. */
+export function presentationRecoveryAction(error) {
+    return typeof error === "object" && error !== null && codeLoadFailures.has(error) ? "reload" : "retry";
+}
+function markPresentationErrorHandled(error) {
+    if ((typeof error === "object" && error !== null) || typeof error === "function")
+        handledPresentationErrors.add(error);
+}
+function forgetPresentationError(error) {
+    if ((typeof error === "object" && error !== null) || typeof error === "function")
+        handledPresentationErrors.delete(error);
+}
+/** @internal Classifies a reported React error after its owning boundary commits. */
+export function deferUnhandledPresentationError(error, report) {
+    queueMicrotask(() => {
+        if (((typeof error === "object" && error !== null) || typeof error === "function") && handledPresentationErrors.has(error))
+            return;
+        report();
+    });
+}
+/** @internal Exact pending texture groups owned by one presentation, including uncommitted Suspense. */
+export function createPresentationRetryRegistry(defaultClear) {
+    const loaders = new Map();
+    return {
+        register(inputs, clear = defaultClear) {
+            if (clear === undefined)
+                throw new Error("A recoverable loader must provide its cache clear callback");
+            let groups = loaders.get(clear);
+            if (groups === undefined) {
+                groups = new Map();
+                loaders.set(clear, groups);
+            }
+            const key = JSON.stringify(inputs);
+            let group = groups.get(key);
+            if (group === undefined) {
+                group = { inputs: [...inputs], loaded: false };
+                groups.set(key, group);
+            }
+            const registered = group;
+            return () => { registered.loaded = true; };
+        },
+        retry() {
+            for (const [clear, groups] of loaders) {
+                for (const [key, group] of groups) {
+                    if (group.loaded)
+                        continue;
+                    clear(group.inputs);
+                    groups.delete(key);
+                }
+            }
+        },
+    };
+}
+const PresentationRetryContext = createContext(null);
+/** Renderer-only loader adapters share the DOM owner without importing their libraries here. @internal */
+export function usePresentationRetryScope() {
+    return useContext(PresentationRetryContext);
+}
+class AssetErrorBoundary extends Component {
+    state = { failed: false };
+    static getDerivedStateFromError() { return { failed: true }; }
+    componentDidCatch(error, info) { this.props.onError(error, info.componentStack ?? undefined); }
+    render() { return this.state.failed ? null : this.props.children; }
+}
+/** @internal Forwards renderer-local loader errors to the owning DOM presentation. */
+export function PresentationAssetBoundary({ children }) {
+    const scope = useContext(PresentationRetryContext);
+    return scope === null ? children : _jsx(AssetErrorBoundary, { onError: scope.fail, children: children });
+}
+/** @internal Retires only diagnostics belonging to this exact handled presentation error. */
+export function createPresentationDiagnosticOwnership() {
+    const ids = new WeakMap();
+    return {
+        register(error, id, phase) {
+            if (phase !== "presentation" || typeof error !== "object" || error === null)
+                return;
+            const owned = ids.get(error) ?? new Set();
+            owned.add(id);
+            ids.set(error, owned);
+        },
+        recovered(error) {
+            if (typeof error !== "object" || error === null)
+                return new Set();
+            const owned = ids.get(error) ?? new Set();
+            ids.delete(error);
+            return owned;
+        },
+    };
+}
+/** Restores an owned recovered surface only after Suspense has attached and revealed it. @internal */
+export function createPlaySurfaceFocusOwnership() {
+    let pending = null;
+    return {
+        request(owner) { pending = owner; },
+        reveal(owner, surface, active, body) {
+            if (pending === null)
+                return false;
+            if (pending !== owner) {
+                pending = null;
+                return false;
+            }
+            if (surface === null || !surface.isConnected || surface.getClientRects().length === 0)
+                return false;
+            const bounds = surface.getBoundingClientRect();
+            if (bounds.width === 0 || bounds.height === 0)
+                return false;
+            pending = null;
+            if (active !== null && active !== body && !surface.contains(active))
+                return false;
+            surface.focus({ preventScroll: true });
+            return true;
+        },
+    };
+}
+function RecoveryFailure({ ctx, error, retry }) {
+    useLayoutEffect(() => suspendPlayControls(ctx), [ctx]);
+    const descriptionId = useId();
+    const message = error instanceof Error ? error.message : String(error);
+    const reload = presentationRecoveryAction(error) === "reload";
+    const report = ["JGengine presentation error", message, error instanceof Error ? error.stack : null, errorReportContext()]
+        .filter((line) => line !== null && line !== undefined).join("\n");
+    return (_jsx("div", { style: { display: "grid", width: "100%", height: "100%", placeItems: "center", padding: 24, background: "#08151d", color: "#e9f6ee", fontFamily: "system-ui" }, "data-presentation-recovery": "failed", children: _jsxs("section", { role: "alert", "aria-describedby": descriptionId, style: { width: "100%", maxWidth: 480, padding: 28, border: "1px solid #35616b", borderRadius: 16, background: "#102735", boxShadow: "0 20px 60px #0006" }, children: [_jsx("h2", { style: { margin: 0, fontSize: 22, fontWeight: 650 }, children: "The game view couldn\u2019t load" }), _jsx("p", { id: descriptionId, style: { margin: "12px 0 20px", color: "#c3d9dd", lineHeight: 1.5 }, children: reload ? "Reload the game to reconnect and load its view. If the problem continues, the technical details can help the game’s author investigate." : "Retry to load the view again. If the problem continues, the technical details can help the game’s author investigate." }), _jsx("button", { type: "button", autoFocus: true, style: { border: "1px solid #8ce0c2", borderRadius: 8, background: "#8ce0c2", color: "#082b22", padding: "10px 18px", font: "inherit", fontWeight: 650, cursor: "pointer" }, onClick: retry, children: reload ? "Reload game" : "Retry display" }), _jsxs("details", { style: { marginTop: 24, borderTop: "1px solid #35616b", paddingTop: 16 }, children: [_jsx("summary", { style: { cursor: "pointer", color: "#b7d3da" }, children: "Technical details" }), _jsx("pre", { style: { whiteSpace: "pre-wrap", overflowWrap: "anywhere", maxHeight: 160, overflow: "auto", fontSize: 12, color: "#c3d9dd" }, children: message }), _jsx(ErrorReportActions, { report: report, issueTitle: `Presentation: ${message}` })] })] }) }));
+}
+/** @internal Retains the live context for asset Retry; failed browser modules require page reload. */
+export class PresentationRecovery extends Component {
+    state = { owner: this.props.ctx, failed: false, error: null, registry: createPresentationRetryRegistry() };
+    static getDerivedStateFromProps(props, state) {
+        if (props.ctx === state.owner)
+            return null;
+        forgetPresentationError(state.error);
+        return { owner: props.ctx, failed: false, error: null, registry: createPresentationRetryRegistry() };
+    }
+    static getDerivedStateFromError(error) { return { failed: true, error }; }
+    componentDidCatch(error, info) {
+        this.pendingRecovery = null;
+        this.trace("caught");
+        markPresentationErrorHandled(error);
+        this.props.onRuntimeError(error, "presentation", info.componentStack ?? undefined);
+    }
+    componentDidUpdate(previousProps, previousState) {
+        if (previousState.failed && !this.state.failed && previousState.owner === this.state.owner && previousProps.ctx === this.props.ctx) {
+            this.trace("retry-committed");
+            this.props.onRetryCommitted?.();
+        }
+    }
+    componentWillUnmount() { forgetPresentationError(this.state.error); }
+    attempt = 0;
+    scopeId = 0;
+    trace(phase) {
+        this.props.onRecoveryEvent?.({ phase, attempt: this.attempt, scope: this.scopeId, sameOwner: this.props.ctx === this.state.owner, pending: this.pendingRecovery !== null, failed: this.state.failed });
+    }
+    scope = null;
+    pendingRecovery = null;
+    retry = () => {
+        if (presentationRecoveryAction(this.state.error) === "reload") {
+            globalThis.location.reload();
+            return;
+        }
+        this.attempt += 1;
+        this.pendingRecovery = { owner: this.state.owner, error: this.state.error };
+        this.trace("retry-requested");
+        this.state.registry.retry();
+        forgetPresentationError(this.state.error);
+        this.setState({ failed: false, error: null });
+    };
+    render() {
+        if (this.state.failed)
+            return _jsx(RecoveryFailure, { ctx: this.props.ctx, error: this.state.error, retry: this.retry });
+        const owner = this.state.owner;
+        if (this.scope === null || this.scope.registry !== this.state.registry) {
+            this.scopeId += 1;
+            this.scope = { registry: this.state.registry, fail: (error, stack) => {
+                    if (this.props.ctx !== owner)
+                        return;
+                    this.pendingRecovery = null;
+                    this.trace("asset-failed");
+                    markPresentationErrorHandled(error);
+                    this.props.onRuntimeError(error, "presentation", stack);
+                    this.setState({ failed: true, error });
+                }, recoveredDraw: () => {
+                    this.trace("draw-observed");
+                    const pending = this.pendingRecovery;
+                    if (pending === null || pending.owner !== owner || this.props.ctx !== owner || this.state.failed)
+                        return;
+                    this.pendingRecovery = null;
+                    this.trace("draw-accepted");
+                    this.props.onRecoveredDraw?.(pending.error);
+                } };
+        }
+        return _jsx(PresentationRetryContext, { value: this.scope, children: this.props.children });
+    }
+}

package/dist/presentationRecovery3d.d.ts

@@ -0,0 +1,4 @@
+/** Registers exact loader inputs and their cache clear before a load can suspend. @internal */
+export declare function useRecoverableTexture<T extends string[] | string | Record<string, string>>(input: T): import("@react-three/drei").MappedTextureType<T>;
+/** Observes the owning renderer after the restored material subtree commits and draws. @internal */
+export declare function PresentationRecoveredDraw(): null;

package/dist/presentationRecovery3d.js

@@ -0,0 +1,32 @@
+import { addAfterEffect, useThree } from "@react-three/fiber";
+import { useTexture } from "@react-three/drei";
+import { useLayoutEffect } from "react";
+import { usePresentationRetryScope } from "./presentationRecovery.js";
+/** Registers exact loader inputs and their cache clear before a load can suspend. @internal */
+export function useRecoverableTexture(input) {
+    const scope = usePresentationRetryScope();
+    const inputs = typeof input === "string" ? [input] : Array.isArray(input) ? input : Object.values(input);
+    const loaded = scope?.registry.register(inputs, useTexture.clear);
+    const textures = useTexture(input);
+    loaded?.();
+    return textures;
+}
+/** Observes the owning renderer after the restored material subtree commits and draws. @internal */
+export function PresentationRecoveredDraw() {
+    const gl = useThree((state) => state.gl);
+    const scope = usePresentationRetryScope();
+    useLayoutEffect(() => {
+        if (scope === null)
+            return;
+        const baseline = gl.info.render.frame;
+        let stop = () => { };
+        stop = addAfterEffect(() => {
+            if (gl.info.render.frame <= baseline || gl.info.render.calls <= 0 || !gl.domElement.isConnected || gl.getContext().isContextLost())
+                return;
+            stop();
+            scope.recoveredDraw();
+        });
+        return () => stop();
+    }, [gl, scope]);
+    return null;
+}

package/dist/presentationResolve.d.ts

@@ -1,3 +1,4 @@
+import type { SceneEntity } from "@jgengine/core/scene/entityStore";
 import type { CatalogEntityRole } from "@jgengine/core/runtime/gameContext";
 import type { PresentationEffectsConfig } from "@jgengine/core/game/playableGame";
 /** Resolved world-bar / nameplate config, or `null` when the feature is off. @internal */
@@ -5,9 +6,12 @@ export interface ResolvedWorldOverlayBars {
     statId: string;
     roles?: readonly CatalogEntityRole[];
     maxDistance?: number;
+    maxSamples?: number;
+    tickMs?: number;
     /** Nameplates only: draw the built-in HP bar. `false` yields a name-only plate. Defaults to `true`. */
     showHealth?: boolean;
-    occlude?: boolean;
+    occlude: boolean;
+    resolveName?: (entity: SceneEntity) => string | null;
 }
 /**
  * Normalize `worldHealthBars` / `nameplates` (`boolean | object | undefined`) into a
@@ -20,8 +24,11 @@ export declare function resolveWorldOverlayBars(config: boolean | {
     statId?: string;
     roles?: readonly CatalogEntityRole[];
     maxDistance?: number;
+    maxSamples?: number;
+    tickMs?: number;
     showHealth?: boolean;
     occlude?: boolean;
+    resolveName?: (entity: SceneEntity) => string | null;
 } | undefined): ResolvedWorldOverlayBars | null;
 /** Resolved combat presentation channels (each boolean is whether that stack piece mounts). @internal */
 export interface ResolvedPresentationEffects {

package/dist/presentationResolve.js

@@ -9,13 +9,16 @@ export function resolveWorldOverlayBars(config) {
     if (config === undefined || config === false)
         return null;
     if (config === true)
-        return { statId: "health" };
+        return { statId: "health", occlude: true };
     return {
         statId: config.statId ?? "health",
         ...(config.roles === undefined ? {} : { roles: config.roles }),
+        ...(config.maxSamples === undefined ? {} : { maxSamples: config.maxSamples }),
+        ...(config.tickMs === undefined ? {} : { tickMs: config.tickMs }),
         ...(config.maxDistance === undefined ? {} : { maxDistance: config.maxDistance }),
         ...(config.showHealth === undefined ? {} : { showHealth: config.showHealth }),
-        ...(config.occlude === undefined ? {} : { occlude: config.occlude }),
+        occlude: config.occlude ?? true,
+        ...(config.resolveName === undefined ? {} : { resolveName: config.resolveName }),
     };
 }
 // Every channel defaults on EXCEPT tracers. `fireProjectile` is a generic seam (bullets,

package/dist/render/CascadedShadows.d.ts

@@ -1,4 +1,5 @@
 import * as THREE from "three";
+import { CSM } from "three/examples/jsm/csm/CSM.js";
 import type { DirectionalLightingConfig } from "@jgengine/core/game/playableGame";
 /**
  * Cascaded shadow maps for one directional light — outdoor scenes keep shadows past a
@@ -15,10 +16,14 @@ export declare function CascadedShadows({ entry }: {
 /** Structural slice of CSM so the patcher is testable without a renderer. */
 export interface CsmMaterialSetup {
     setupMaterial(material: THREE.Material): void;
+    shaders?: Map<unknown, unknown>;
 }
+/** Release the lights and GPU targets that three.js CSM.dispose does not own. @internal */
+export declare function releaseCascadedShadows(csm: Pick<CSM, "remove" | "dispose" | "lights">): void;
+/** Patch streamed meshes on attachment and material replacement without scanning the world each frame. @internal */
+export declare function bindCsmMaterials(scene: THREE.Scene, csm: CsmMaterialSetup): () => 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.
+ * chaining rather than clobbering a material's own `onBeforeCompile`.
  */
 export declare function patchSceneMaterials(scene: THREE.Scene, csm: CsmMaterialSetup, patched: WeakSet<THREE.Material>): void;

package/dist/render/CascadedShadows.js

@@ -18,7 +18,6 @@ export function CascadedShadows({ entry }) {
     const camera = useThree((s) => s.camera);
     const scene = useThree((s) => s.scene);
     const csmRef = useRef(null);
-    const patchedRef = useRef(new WeakSet());
     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]);
@@ -43,11 +42,11 @@ export function CascadedShadows({ entry }) {
             light.color = new THREE.Color(entry.color ?? "#ffffff");
             light.castShadow = true;
         }
-        patchedRef.current = new WeakSet();
-        patchSceneMaterials(scene, csm, patchedRef.current);
+        const unbind = bindCsmMaterials(scene, csm);
         csmRef.current = csm;
         return () => {
-            csm.dispose();
+            unbind();
+            releaseCascadedShadows(csm);
             csmRef.current = null;
         };
     }, [
@@ -69,17 +68,106 @@ export function CascadedShadows({ entry }) {
         if (csm === null)
             return;
         csm.camera = camera;
-        // 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;
 }
+/** Release the lights and GPU targets that three.js CSM.dispose does not own. @internal */
+export function releaseCascadedShadows(csm) {
+    csm.remove();
+    for (const light of csm.lights)
+        light.shadow.dispose();
+    csm.dispose();
+}
+function setupMaterial(material, csm) {
+    const prior = material.onBeforeCompile;
+    csm.setupMaterial(material);
+    const csmHook = material.onBeforeCompile;
+    if (prior !== THREE.Material.prototype.onBeforeCompile && prior !== csmHook) {
+        material.onBeforeCompile = function (shader, renderer) {
+            prior.call(this, shader, renderer);
+            csmHook.call(this, shader, renderer);
+        };
+    }
+    material.needsUpdate = true;
+}
+/** Patch streamed meshes on attachment and material replacement without scanning the world each frame. @internal */
+export function bindCsmMaterials(scene, csm) {
+    const nodes = new Map();
+    const materials = new Map();
+    const patch = (material) => {
+        if (!isStandardMaterial(material) || materials.has(material))
+            return;
+        const prior = material.onBeforeCompile;
+        const priorDefines = { ...material.defines };
+        setupMaterial(material, csm);
+        const hook = material.onBeforeCompile;
+        const release = () => {
+            material.removeEventListener("dispose", release);
+            csm.shaders?.delete(material);
+            if (material.onBeforeCompile === hook)
+                material.onBeforeCompile = prior;
+            for (const key of ["USE_CSM", "CSM_CASCADES", "CSM_FADE"]) {
+                if (key in priorDefines)
+                    (material.defines ??= {})[key] = priorDefines[key];
+                else if (material.defines !== undefined)
+                    delete material.defines[key];
+            }
+            material.needsUpdate = true;
+            materials.delete(material);
+        };
+        materials.set(material, release);
+        material.addEventListener("dispose", release);
+    };
+    const patchMesh = (node) => {
+        const mesh = node;
+        if (!mesh.isMesh)
+            return;
+        if (Array.isArray(mesh.material))
+            mesh.material.forEach(patch);
+        else
+            patch(mesh.material);
+    };
+    const detach = (node) => {
+        nodes.get(node)?.();
+        nodes.delete(node);
+        for (const child of node.children)
+            detach(child);
+    };
+    const attach = (node) => {
+        if (nodes.has(node))
+            return;
+        patchMesh(node);
+        const added = ({ child }) => attach(child);
+        const removed = ({ child }) => detach(child);
+        const prior = node.onBeforeRender;
+        const before = function (...args) {
+            prior.apply(this, args);
+            patchMesh(this);
+        };
+        node.addEventListener("childadded", added);
+        node.addEventListener("childremoved", removed);
+        if (node.isMesh)
+            node.onBeforeRender = before;
+        nodes.set(node, () => {
+            node.removeEventListener("childadded", added);
+            node.removeEventListener("childremoved", removed);
+            if (node.onBeforeRender === before)
+                node.onBeforeRender = prior;
+        });
+        for (const child of node.children)
+            attach(child);
+    };
+    attach(scene);
+    return () => {
+        detach(scene);
+        for (const release of materials.values())
+            release();
+    };
+}
 /**
  * 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.
+ * chaining rather than clobbering a material's own `onBeforeCompile`.
  */
 export function patchSceneMaterials(scene, csm, patched) {
     scene.traverse((obj) => {
@@ -90,17 +178,7 @@ export 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);
-                };
-            }
+            setupMaterial(mat, csm);
             patched.add(mat);
         }
     });