@expofp/renderer 0.0.0-experimental.2d6c681

package/dist/objects/lighting/OcclusionPasses.js

@@ -0,0 +1,271 @@
+import { useFrame } from '@react-three/fiber';
+import { useEffect, useState } from 'react';
+import { DoubleSide, Matrix4, Mesh, MeshBasicMaterial, NoBlending, PlaneGeometry, Scene, ShaderMaterial, } from 'three';
+import { useSpace } from '../../space/Space';
+import { AO_FRAGMENT_SHADER, AO_VERTEX_SHADER, BLUR_FRAGMENT_SHADER, createAoPassUniforms, createBlurPassUniforms, NOISE_TILE, } from '../materials/effects/ao';
+import { useSceneEffects } from '../materials/effects/effects-context';
+import { OCCLUSION_LAYER } from './occluder';
+import { OcclusionTargets } from './occlusion-targets';
+/**
+ * Screen-space ambient occlusion, in three passes a frame.
+ *
+ * The prepass draws {@link OCCLUSION_LAYER} into the one target that carries the depth texture. The
+ * AO pass reads that depth and writes how closed in each fragment is. The blur pass reads that
+ * output and the same depth, and writes what the lit materials read. Both quad passes bind a target
+ * with no depth attachment, because WebGL2 leaves a draw that samples its own framebuffer undefined.
+ * See `occlusion-targets.ts` for the three targets and the two textures under them.
+ *
+ * All three run on a frustum wider than the visible one. Geometry just outside the view then still
+ * occludes what is inside it, so no seam of missing darkening runs down the screen edges.
+ *
+ * Three things switch the passes off, and each one clears `aoActive` first. The debug GUI clears
+ * `enabled`, or the `occluders` registry is empty, and both of those free the render targets. A failed
+ * `renderTargets.sync()` is a capability gate that frees nothing, because it built nothing.
+ *
+ * The default frame priority puts this after the camera, which settles at negative priorities. It also
+ * puts this before R3F's own draw, so the texture is ready before any material samples it.
+ * @returns Nothing. This renders no scene node.
+ */
+export function OcclusionPasses() {
+    const occlusion = useSceneEffects();
+    const space = useSpace();
+    const [renderTargets] = useState(() => new OcclusionTargets());
+    // Both passes are built here rather than declared as `<shaderMaterial uniforms={...}>`, because
+    // R3F copies a uniform record into the material's own to keep that target stable — which leaves
+    // the frame writing wrappers no shader reads. `ShaderMaterial` takes the record as given. The
+    // quads join them here for the same reason: neither ever changes after this, and a portal would
+    // spin up a nested R3F root to reconcile a subtree that never does.
+    const [aoPass] = useState(() => createPass('occlusion-ao', AO_FRAGMENT_SHADER, createAoPassUniforms()));
+    const [blurPass] = useState(() => createPass('occlusion-blur', BLUR_FRAGMENT_SHADER, createBlurPassUniforms(occlusion)));
+    useEffect(() => {
+        return () => {
+            renderTargets.dispose();
+            // Everything freed here is this mount's own, for the reason the uniform objects are: a
+            // texture, a program and a buffer upload into whichever context drew with them, and a second
+            // mounted scene has a second one.
+            aoPass.uniforms.uNoise.value.dispose();
+            disposePass(aoPass);
+            disposePass(blurPass);
+            unpublish(occlusion);
+        };
+    }, [aoPass, blurPass, occlusion, renderTargets]);
+    useFrame((state) => {
+        // First, so every path out of here leaves the shader reading nothing rather than a stale
+        // texture. Every write below goes through a function of this module rather than landing inline,
+        // because the React Compiler treats what a hook returned as frozen for the callback's own body.
+        unpublish(occlusion);
+        // The master switch and the registry, in one branch because they free the same thing: the debug
+        // GUI turned the term off, or nothing on this plan asked for it. Released once, not every
+        // frame — disposing the targets is what makes `held` false, and nothing rebuilds them until one
+        // of the two conditions lifts.
+        if (!occlusion.enabled || occlusion.occluders.size === 0) {
+            if (renderTargets.held)
+                renderTargets.dispose();
+            return;
+        }
+        // A capability gate, not a switch: see `OcclusionTargets`. Nothing to free on this path, since
+        // a failed sync never built anything.
+        if (!renderTargets.sync(state.gl))
+            return;
+        draw(state.gl, state.scene, state.camera, renderTargets, aoPass, blurPass, occlusion.aoGuard.value, occlusion.radius * space.scale, occlusion.taps);
+        publish(occlusion, renderTargets, state.gl);
+    });
+    return null;
+}
+/**
+ * Builds one full-screen pass: a clip-space quad in a scene of its own, drawn with a material over
+ * the uniforms it is handed.
+ * @param name - The quad's name, for a debugger's scene graph.
+ * @param fragmentShader - The pass's fragment stage.
+ * @param uniforms - The uniforms that stage reads, whose identity outlives every write into it.
+ * @returns The pass, ready to draw and to dispose.
+ */
+function createPass(name, fragmentShader, uniforms) {
+    const material = new ShaderMaterial({
+        uniforms,
+        vertexShader: AO_VERTEX_SHADER,
+        fragmentShader,
+        depthTest: false,
+        depthWrite: false,
+        blending: NoBlending,
+    });
+    const quad = new Mesh(new PlaneGeometry(2, 2), material);
+    quad.name = name;
+    // Culling would test the untransformed unit quad, not where the vertex shader puts it — which is
+    // clip space, exactly as `Background` places its own.
+    quad.frustumCulled = false;
+    const scene = new Scene();
+    scene.add(quad);
+    return { scene, material, quad, uniforms };
+}
+/**
+ * Draws all three passes, and refreshes every uniform that moves with the frame.
+ *
+ * The guard band is built here rather than published, because the prepass has to be drawn through it
+ * and the AO pass has to unproject through the very same matrix. Both are written in place into the
+ * AO pass's own uniforms, so nothing here allocates.
+ * @param gl - The renderer, whose bound target this borrows and puts back.
+ * @param scene - The scene to draw the occlusion layer of.
+ * @param camera - The camera the frame will be drawn with.
+ * @param renderTargets - The three targets to draw into, already synced.
+ * @param aoPass - The AO pass, whose uniforms are refreshed here.
+ * @param blurPass - The blur pass, whose uniforms are refreshed here.
+ * @param guard - How much wider than the main frustum every pass runs.
+ * @param viewRadius - How far the kernel reaches, in view units.
+ * @param taps - How many of the kernel's offsets the AO pass walks.
+ */
+function draw(gl, scene, camera, renderTargets, aoPass, blurPass, guard, viewRadius, taps) {
+    const depth = renderTargets.depth;
+    const ao = renderTargets.ao;
+    const blur = renderTargets.blur;
+    if (!depth?.depthTexture || !ao || !blur)
+        return;
+    // P_guard = scale(1 / (1 + g), 1 / (1 + g), 1) · P_main. The scale touches the x and y clip rows
+    // and leaves the depth rows alone, which is what makes a depth value the prepass stores the value
+    // the main pass would have stored for the same point — and it works on any projection matrix,
+    // including one three never built.
+    const widen = 1 / (1 + guard);
+    aoPass.uniforms.uProjection.value
+        .copy(camera.projectionMatrix)
+        .premultiply(_widen.makeScale(widen, widen, 1));
+    aoPass.uniforms.uUnprojection.value.copy(aoPass.uniforms.uProjection.value).invert();
+    aoPass.uniforms.uDepth.value = depth.depthTexture;
+    aoPass.uniforms.uRadius.value = viewRadius;
+    aoPass.uniforms.uTaps.value = taps;
+    aoPass.uniforms.uTexel.value.set(1 / renderTargets.size.x, 1 / renderTargets.size.y);
+    aoPass.uniforms.uNoiseScale.value.set(renderTargets.size.x / NOISE_TILE, renderTargets.size.y / NOISE_TILE);
+    // The blur runs at the very size the AO pass wrote, so it walks the same texel step — its own,
+    // not the one a lit fragment used to walk. Its kernel side is the scene's own uniform object,
+    // which the debug GUI writes directly, so nothing here copies it.
+    blurPass.uniforms.uOcclusion.value = ao.texture;
+    blurPass.uniforms.uDepth.value = depth.depthTexture;
+    blurPass.uniforms.uTexel.value.copy(aoPass.uniforms.uTexel.value);
+    drawPrepass(gl, scene, camera, depth, aoPass.uniforms);
+    const previous = gl.getRenderTarget();
+    try {
+        drawQuad(gl, ao, aoPass.scene, camera);
+        drawQuad(gl, blur, blurPass.scene, camera);
+    }
+    finally {
+        gl.setRenderTarget(previous);
+    }
+}
+/**
+ * Draws the plan's opaque solid content into the depth target, through the guard band's projection.
+ *
+ * The camera is narrowed to one channel rather than the scene filtered, because a channel is the
+ * only membership three's own traversal reads — `projectObject` and `renderObjects` both test it.
+ * Everything borrowed is put back in a `finally`: the layer mask, the override material, the
+ * projection, and the bound target, which is what keeps a shared context unaware this ran.
+ * @param gl - The renderer.
+ * @param scene - The scene to draw.
+ * @param camera - The camera to draw it with, borrowed and restored.
+ * @param target - The depth target to draw into.
+ * @param uniforms - The AO pass's uniforms, for the guard band already built into them.
+ */
+function drawPrepass(gl, scene, camera, target, uniforms) {
+    const previous = gl.getRenderTarget();
+    const mask = camera.layers.mask;
+    const override = scene.overrideMaterial;
+    const projection = _projection.copy(camera.projectionMatrix);
+    const unprojection = _unprojection.copy(camera.projectionMatrixInverse);
+    camera.layers.set(OCCLUSION_LAYER);
+    scene.overrideMaterial = PREPASS_MATERIAL;
+    camera.projectionMatrix.copy(uniforms.uProjection.value);
+    camera.projectionMatrixInverse.copy(uniforms.uUnprojection.value);
+    gl.setRenderTarget(target);
+    try {
+        // By hand rather than through `autoClear`, which the MapLibre embed turns off so its renderer
+        // never wipes the host's own layers — and which would otherwise leave the previous frame's
+        // depth standing here. Depth alone: this target's color attachment is the texture the blur pass
+        // owns, which nothing writes in this pass and the blur pass overwrites in full.
+        gl.clear(false, true, false);
+        gl.render(scene, camera);
+    }
+    finally {
+        camera.projectionMatrix.copy(projection);
+        camera.projectionMatrixInverse.copy(unprojection);
+        scene.overrideMaterial = override;
+        camera.layers.mask = mask;
+        gl.setRenderTarget(previous);
+    }
+}
+/**
+ * Draws one full-screen quad into one target.
+ *
+ * No clear: the quad covers every texel with the depth test off, so whatever was there is
+ * overwritten. Any camera does, too — the quad's vertex shader writes clip space and reads no
+ * matrix. The bound target is not put back here, because the caller draws more than one of these
+ * and restores it once.
+ * @param gl - The renderer.
+ * @param target - The target to bind.
+ * @param scene - The scene holding this pass's quad and nothing else.
+ * @param camera - Any camera, since the quad reads no matrix.
+ */
+function drawQuad(gl, target, scene, camera) {
+    gl.setRenderTarget(target);
+    gl.render(scene, camera);
+}
+/**
+ * Frees what one pass allocated in a GL context.
+ * @param pass - The pass to free.
+ */
+function disposePass(pass) {
+    pass.material.dispose();
+    pass.quad.geometry.dispose();
+}
+/**
+ * Publishes what the lit materials read, for the passes just drawn.
+ *
+ * The map is the blur target's texture, which is the smoothed term, and never the AO target's raw
+ * one — that is the whole of what the third pass bought.
+ * @param occlusion - The scene's shared occlusion state.
+ * @param renderTargets - The targets just drawn into.
+ * @param gl - The renderer, for the drawing buffer's size.
+ */
+function publish(occlusion, renderTargets, gl) {
+    const depth = renderTargets.depth;
+    const blur = renderTargets.blur;
+    if (!depth?.depthTexture || !blur)
+        return;
+    occlusion.aoMap.value = blur.texture;
+    occlusion.aoDepth.value = depth.depthTexture;
+    gl.getDrawingBufferSize(occlusion.aoViewport.value);
+    occlusion.aoActive.value = 1;
+}
+/**
+ * Puts the shared state back to the off position, so nothing reads a texture that no longer exists.
+ * @param occlusion - The scene's shared occlusion state.
+ */
+function unpublish(occlusion) {
+    occlusion.aoActive.value = 0;
+    occlusion.aoMap.value = null;
+    occlusion.aoDepth.value = null;
+}
+/**
+ * What the solid batches are drawn with into the depth target.
+ *
+ * Unlit and color-blind: `colorWrite` is off, because that target's color attachment is the texture
+ * the blur pass owns in full, so the cheapest fragment shader that still writes depth is the right
+ * one — and `MeshBasicMaterial` carries the batching and instancing chunks a `BatchedMesh` and an
+ * `InstancedMesh` need. `DoubleSide` matches the material the volumes really draw with, so the depth
+ * the taps read is the depth the main pass tests against.
+ *
+ * One for the process rather than one per mount: it holds no per-scene state and owns no texture,
+ * and three compiles a program for it per context that draws with it.
+ */
+const PREPASS_MATERIAL = new MeshBasicMaterial({
+    side: DoubleSide,
+    colorWrite: false,
+    depthWrite: true,
+    depthTest: true,
+    blending: NoBlending,
+    polygonOffset: false,
+    toneMapped: false,
+});
+/** Scratch for the camera's own projection, borrowed for the length of the prepass. */
+const _projection = new Matrix4();
+/** Scratch for its inverse. */
+const _unprojection = new Matrix4();
+/** Scratch for the guard band's own scale, rebuilt per frame so a GUI edit takes effect at once. */
+const _widen = new Matrix4();

package/dist/objects/lighting/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The lighting folder's public face inside the package.
+ *
+ * `Scene` mounts both of these and nothing else here, so the folder exports the two components, plus
+ * the props one of them takes from a caller through `RendererProps.lighting`. The light settings, the
+ * derived intensities, the occlusion pipeline's own render targets and the GUI folder stay behind
+ * it.
+ */
+export { Lighting, type LightingProps, type ShadowProps } from './Lighting';
+export { OcclusionPasses } from './OcclusionPasses';
+//# sourceMappingURL=index.d.ts.map

package/dist/objects/lighting/index.js

@@ -0,0 +1,10 @@
+/**
+ * The lighting folder's public face inside the package.
+ *
+ * `Scene` mounts both of these and nothing else here, so the folder exports the two components, plus
+ * the props one of them takes from a caller through `RendererProps.lighting`. The light settings, the
+ * derived intensities, the occlusion pipeline's own render targets and the GUI folder stay behind
+ * it.
+ */
+export { Lighting } from './Lighting';
+export { OcclusionPasses } from './OcclusionPasses';

package/dist/objects/lighting/lighting-gui.d.ts

@@ -0,0 +1,24 @@
+import { type LightSettings } from './Lighting';
+/**
+ * Builds the debug folder that settles this design's open values.
+ *
+ * A development tool. While the debug UI is off, `useGui()` returns `null`, and the folder is a
+ * no-op that never reaches the main chunk.
+ *
+ * Most of these values are also a prop, through `RendererProps.lighting`, and both write the very
+ * same objects. The key light's aim is the exception and stays here alone: where it points is the
+ * design's decision rather than a caller's. See `LightingProps`.
+ *
+ * No controller asks for a redraw: `Gui` registers one handler on the root panel and lil-gui walks
+ * every change up to it. Nor does any controller ask for a React render — every write lands on a
+ * uniform's own `value` or on a plain field a frame callback reads, which is what lets the whole
+ * folder move a mounted scene with no recompile and no reconciliation. Nothing here polls, either:
+ * every controller is a control, so what it shows is the value last written through it.
+ *
+ * A controller that cannot affect the current state is hidden rather than disabled, because a value
+ * it could show would mean nothing.
+ * @param light - The mounted light rig, handed over rather than imported, so this module needs no
+ *   runtime import back into `Lighting`.
+ */
+export declare function useLightingGui(light: LightSettings): void;
+//# sourceMappingURL=lighting-gui.d.ts.map

package/dist/objects/lighting/lighting-gui.js

@@ -0,0 +1,114 @@
+import { useEffect } from 'react';
+import { useGui } from '../../debug/debug-context';
+import { useSceneEffects } from '../materials/effects/effects-context';
+/**
+ * Builds the debug folder that settles this design's open values.
+ *
+ * A development tool. While the debug UI is off, `useGui()` returns `null`, and the folder is a
+ * no-op that never reaches the main chunk.
+ *
+ * Most of these values are also a prop, through `RendererProps.lighting`, and both write the very
+ * same objects. The key light's aim is the exception and stays here alone: where it points is the
+ * design's decision rather than a caller's. See `LightingProps`.
+ *
+ * No controller asks for a redraw: `Gui` registers one handler on the root panel and lil-gui walks
+ * every change up to it. Nor does any controller ask for a React render — every write lands on a
+ * uniform's own `value` or on a plain field a frame callback reads, which is what lets the whole
+ * folder move a mounted scene with no recompile and no reconciliation. Nothing here polls, either:
+ * every controller is a control, so what it shows is the value last written through it.
+ *
+ * A controller that cannot affect the current state is hidden rather than disabled, because a value
+ * it could show would mean nothing.
+ * @param light - The mounted light rig, handed over rather than imported, so this module needs no
+ *   runtime import back into `Lighting`.
+ */
+export function useLightingGui(light) {
+    const gui = useGui();
+    const effects = useSceneEffects();
+    useEffect(() => {
+        if (!gui)
+            return undefined;
+        const folder = addLightingFolder(gui, light, effects);
+        return () => {
+            folder.destroy();
+        };
+    }, [effects, gui, light]);
+}
+/**
+ * The Lighting folder: the light's aim, the two lights' colors, the contrast, and the Occlusion
+ * folder nested inside it.
+ *
+ * `contrast` needs no moving bound the way the intensity ratio it replaced did: its range is `0`–`1`
+ * at every pitch, so there is nothing here to keep in sync with the pitch controller.
+ * @param gui - The GUI to add the folder to.
+ * @param light - The rig each controller binds to.
+ * @param effects - The mounted scene's effect state, which the nested folder binds to.
+ * @returns The folder.
+ */
+function addLightingFolder(gui, light, effects) {
+    const folder = gui.addFolder('Lighting');
+    const track = folder.add(light, 'trackPitch').name('track camera pitch');
+    const pitch = folder.add(light, 'pitchDegrees', 0, 89, 1).name('pitch°');
+    track.onChange((on) => toggle(pitch, !on));
+    toggle(pitch, !light.trackPitch);
+    folder.addColor(light, 'skyColor').name('sky color');
+    folder.addColor(light, 'groundColor').name('ground color');
+    folder.addColor(light, 'directionalColor').name('directional color');
+    folder.add(light, 'contrast', 0, 1, 0.01).name('contrast');
+    addDarkening(folder, effects);
+    return folder;
+}
+/**
+ * Adds the darkening controls to the Lighting folder.
+ *
+ * They belong beside the lights because darkening describes the plan's shading, not the values of
+ * any one material. They sit in the Lighting folder itself rather than a folder of their own, so a
+ * reader finds every shading control in one list.
+ *
+ * The two effects share a shade and keep their own strengths. The names say which effect each
+ * strength belongs to, because a plain `strength` beside `ao strength` invites a change to the wrong
+ * one.
+ *
+ * The switch hides the ambient occlusion controls, the way `track camera pitch` hides `pitch°`. The
+ * contact shadow's own numbers stay visible, because the contact shadow does not switch off with
+ * ambient occlusion. It is the darkening every device gets.
+ * @param folder - The Lighting folder.
+ * @param effects - The mounted scene's effect state. Every controller binds a uniform's `value` or a
+ *   plain field on this one object.
+ */
+function addDarkening(folder, effects) {
+    folder
+        .addColor(effects, 'shadowHex')
+        .name('shadow color')
+        // lil-gui writes display sRGB and three holds the working space, so `Color.set` converts. Both
+        // effects read this one object, so the shade moves for both or for neither.
+        .onChange((hex) => effects.shadowColor.value.set(hex));
+    folder.add(effects.shadowDistance, 'value', 1, 5, 0.1).name('contact distance');
+    folder.add(effects.shadowStrength, 'value', 0, 1, 0.01).name('contact strength');
+    const term = folder.add(effects, 'enabled').name('ambient occlusion');
+    // The controls ambient occlusion owns, hidden together while it is off. `enabled` is a plain
+    // boolean rather than a uniform. `OcclusionPasses` reads it in its frame callback and frees the
+    // render targets once when it goes false, so a click takes effect on the next frame and no React
+    // render follows.
+    const owned = [
+        folder.add(effects, 'radius', 1, 30, 0.5).name('ao radius'),
+        folder.add(effects.aoStrength, 'value', 0, 1, 0.01).name('ao strength'),
+    ];
+    term.onChange((on) => {
+        for (const controller of owned)
+            toggle(controller, on);
+    });
+    for (const controller of owned)
+        toggle(controller, effects.enabled);
+}
+/**
+ * Shows or hides a controller.
+ * @param controller - The controller to move.
+ * @param visible - Whether it should show.
+ */
+function toggle(controller, visible) {
+    if (visible)
+        controller.show();
+    else
+        controller.hide();
+}

package/dist/objects/lighting/occluder.d.ts

@@ -0,0 +1,34 @@
+import { type Object3D } from 'three';
+/**
+ * Asks the scene for occlusion, on behalf of one mesh.
+ *
+ * Two things follow from a call, and they are one decision rather than two: the mesh joins
+ * {@link OCCLUSION_LAYER}, which is what the depth prepass draws, and it joins the scene's registry,
+ * which is what tells `OcclusionPasses` that anything at all wants the passes run. A caller enabling
+ * the layer by hand would leave the two free to drift, and a plan with no 3D content would pay for a
+ * pair of render targets and a full-screen pass over an empty depth buffer.
+ *
+ * **The registry is a set, so React's StrictMode double mount cannot make it drift.** Adding the
+ * same mesh twice is adding it once, where a count would climb; the mesh last bound is remembered
+ * here rather than by the caller, because React hands a detaching `ref` a `null` and nothing else.
+ *
+ * **Not a traversal of the scene.** The renderer avoids per-frame traversal deliberately, and a
+ * registry is exact where a traversal is a guess about what will draw.
+ * @returns The function a `ref` callback calls: with the mesh while it occludes, and with `null`
+ *   when it stops — which is exactly what React hands a `ref` on detach.
+ */
+export declare function useOccluder(): (occluder: Object3D | null) => void;
+/**
+ * The layer a mesh joins to be drawn into the depth prepass.
+ *
+ * A channel rather than a flag because that is the only membership three's own traversal reads: the
+ * prepass narrows the camera to this one channel, and `projectObject` and `renderObjects` both test
+ * it.
+ *
+ * Opaque solid shape batches and opaque model meshes join it, through {@link useOccluder}.
+ * Translucent batches of either kind stay out, because a surface you can see through must not cast
+ * full occlusion. Planar batches stay out, which is what keeps this term and the contact shadow
+ * disjoint.
+ */
+export declare const OCCLUSION_LAYER = 1;
+//# sourceMappingURL=occluder.d.ts.map

package/dist/objects/lighting/occluder.js

@@ -0,0 +1,62 @@
+import { useRef } from 'react';
+import { useSceneEffects } from '../materials/effects/effects-context';
+/**
+ * Asks the scene for occlusion, on behalf of one mesh.
+ *
+ * Two things follow from a call, and they are one decision rather than two: the mesh joins
+ * {@link OCCLUSION_LAYER}, which is what the depth prepass draws, and it joins the scene's registry,
+ * which is what tells `OcclusionPasses` that anything at all wants the passes run. A caller enabling
+ * the layer by hand would leave the two free to drift, and a plan with no 3D content would pay for a
+ * pair of render targets and a full-screen pass over an empty depth buffer.
+ *
+ * **The registry is a set, so React's StrictMode double mount cannot make it drift.** Adding the
+ * same mesh twice is adding it once, where a count would climb; the mesh last bound is remembered
+ * here rather than by the caller, because React hands a detaching `ref` a `null` and nothing else.
+ *
+ * **Not a traversal of the scene.** The renderer avoids per-frame traversal deliberately, and a
+ * registry is exact where a traversal is a guess about what will draw.
+ * @returns The function a `ref` callback calls: with the mesh while it occludes, and with `null`
+ *   when it stops — which is exactly what React hands a `ref` on detach.
+ */
+export function useOccluder() {
+    const effects = useSceneEffects();
+    // What this caller last bound, so the `null` a detaching `ref` is handed still names something to
+    // remove. A ref rather than state, because no render depends on it.
+    const boundRef = useRef(null);
+    // Through a function of this module rather than a write inside the closure, because the React
+    // Compiler treats what a hook returned as frozen for the closure's own body — the discipline
+    // `lighting-gui.ts` and `OcclusionPasses` both keep for their own writes.
+    return (occluder) => bindOccluder(effects.occluders, boundRef, occluder);
+}
+/**
+ * Moves one caller's membership from whatever it last bound to whatever it binds now.
+ * @param registry - The scene's occluder registry.
+ * @param boundRef - What this caller last bound; read and rewritten here.
+ * @param occluder - The mesh that occludes from now on, or `null` for none.
+ */
+function bindOccluder(registry, boundRef, occluder) {
+    if (boundRef.current === occluder)
+        return;
+    if (boundRef.current)
+        registry.delete(boundRef.current);
+    boundRef.current = occluder;
+    if (!occluder)
+        return;
+    // Enabling a second channel leaves channel `0` enabled, so the mesh still draws in the main pass
+    // and still picks — `Raycaster` tests channel `0` alone.
+    occluder.layers.enable(OCCLUSION_LAYER);
+    registry.add(occluder);
+}
+/**
+ * The layer a mesh joins to be drawn into the depth prepass.
+ *
+ * A channel rather than a flag because that is the only membership three's own traversal reads: the
+ * prepass narrows the camera to this one channel, and `projectObject` and `renderObjects` both test
+ * it.
+ *
+ * Opaque solid shape batches and opaque model meshes join it, through {@link useOccluder}.
+ * Translucent batches of either kind stay out, because a surface you can see through must not cast
+ * full occlusion. Planar batches stay out, which is what keeps this term and the contact shadow
+ * disjoint.
+ */
+export const OCCLUSION_LAYER = 1;