@expofp/renderer 3.34.1 → 3.35.0

package/dist/objects/materials/effects/ao/index.d.ts

@@ -0,0 +1,129 @@
+import { type DepthTexture, type IUniform, type Object3D, type Texture, Vector2 } from 'three';
+export * from './ambient-occlusion-pass';
+export * from './ambient-occlusion-patch';
+export * from './blur-pass';
+/**
+ * The scene-wide state this term owns: the uniforms every lit material reads, the values the debug
+ * GUI tunes, and the registry of what asks for the term.
+ *
+ * The term declares its own state, so it sits here rather than in `effects-context.ts`, and
+ * `OCCLUSION_DEFAULTS` sits here for the same reason.
+ *
+ * Every field keeps its `ao` prefix because the bundle is flat, and the contact shadow brings a
+ * strength and a color of its own. The last four fields carry no prefix, because no shader reads
+ * them.
+ *
+ * A uniform here is a uniform some shader captures by identity, so a GUI write lands straight in a
+ * shader. A value a pass reads by copy is a plain number instead.
+ */
+export interface AmbientOcclusion {
+    /**
+     * The smoothed occlusion the blur pass wrote, or `null` before the first frame. `0` is open, `1`
+     * is closed. The blur pass writes this one, and the AO pass writes the raw term behind it.
+     */
+    aoMap: IUniform<Texture | null>;
+    /**
+     * The prepass's depth, or `null` before the first frame.
+     *
+     * A depth texture rather than any texture, so nothing assigns this and the map to each other by
+     * mistake. three binds it like any other texture.
+     *
+     * The lit read weights the term with it, which keeps a translucent surface from taking the
+     * occlusion of whatever stands behind it. The main pass binds no framebuffer that carries this
+     * texture, so the sample there is legal.
+     */
+    aoDepth: IUniform<DepthTexture | null>;
+    /**
+     * `1` while the passes drew this frame, `0` when they did not. Every gate clears it before it
+     * returns, so a frame that skipped the passes shades correctly rather than sampling a stale
+     * texture.
+     */
+    aoActive: IUniform<number>;
+    /**
+     * The guard band, `g`: how much wider than the main frustum the two passes run.
+     *
+     * The main pass finds its own fragment in the AO texture with this one scalar rather than a
+     * matrix: `((gl_FragCoord.xy / viewport) * 2 - 1) / (1 + g) * 0.5 + 0.5`.
+     */
+    aoGuard: IUniform<number>;
+    /** How far the read blends an occluded fragment toward the shadow color, from `0` to `1`. */
+    aoStrength: IUniform<number>;
+    /**
+     * The blur kernel's side length in texels, from `1` to {@link NOISE_TILE}.
+     *
+     * A measurement dial rather than a free quality setting. The blur pass costs `2 · side²` texture
+     * fetches a texel, and it bills per texel of a quarter-area target rather than per lit fragment.
+     * Side `1` is the floor, where the pass copies the raw term through.
+     *
+     * A `4 × 4` kernel averages the `4 × 4` rotation tile, which turns rotated sampling into a smooth
+     * result. A smaller side leaves structured noise behind.
+     */
+    aoBlur: IUniform<number>;
+    /** The drawing buffer's size in pixels, the unit `gl_FragCoord` counts in. */
+    aoViewport: IUniform<Vector2>;
+    /** Whether the term runs at all. The debug GUI's switch, not a capability check. */
+    enabled: boolean;
+    /** How far the term looks for an occluder, in plan units. */
+    radius: number;
+    /**
+     * How many of the kernel's {@link AO_TAPS} offsets the AO pass walks. Fewer taps measure less of
+     * the hemisphere, so the pass misses a narrow occluder more often.
+     */
+    taps: number;
+    /**
+     * Every mesh that asks for occlusion, which is every mesh the depth prepass draws.
+     *
+     * A set rather than a count, so React's StrictMode double mount cannot make it drift.
+     * `useOccluder` fills it. An empty set means nothing on this plan asked, so `OcclusionPasses`
+     * holds no render targets and draws no pass.
+     */
+    occluders: Set<Object3D>;
+}
+/**
+ * Builds this term's scene-wide state, at the agreed defaults.
+ *
+ * `createAoPassUniforms` builds what the AO pass alone reads. This builds what the whole scene
+ * shares, and what `createSceneEffects` spreads into the bundle it publishes.
+ * @returns A fresh object, whose identity outlives every write into it.
+ */
+export declare function createAmbientOcclusion(): AmbientOcclusion;
+/**
+ * The occlusion values this design agreed, and what each mount starts from.
+ *
+ * `radius` and `strength` are starting points rather than settled numbers, and the GUI tunes both
+ * per plan. `radius` is an absolute figure in plan units, so it suits one plan's booth sizes and
+ * not another's.
+ *
+ * `blur` and `taps` start at each loop's own bound, which is the shipped look.
+ */
+export declare const OCCLUSION_DEFAULTS: {
+    /** Whether the term runs at all. */
+    enabled: boolean;
+    /**
+     * How far the term looks for an occluder, in plan units.
+     *
+     * Chosen against the story plans, whose booths run about a hundred plan units across. That makes
+     * a band about a tenth of a booth wide, where a junction's shadow reads as shading rather than as
+     * an outline.
+     */
+    radius: number;
+    /** How far the read blends an occluded fragment toward the shadow color, from `0` to `1`. */
+    strength: number;
+    /**
+     * The blur kernel's side length in texels. It starts at the side that covers the rotation tile,
+     * see {@link AmbientOcclusion.aoBlur}.
+     */
+    blur: number;
+    /** How many of the kernel's offsets the AO pass walks, see {@link AmbientOcclusion.taps}. */
+    taps: number;
+    /**
+     * How much wider than the main frustum the two passes run.
+     *
+     * Without the band, geometry just outside the frustum does not occlude geometry inside it, and a
+     * seam of missing darkening runs down the screen edges. `0.15` covers the widest reach a tap
+     * takes at half resolution. The cost is a lower effective resolution and more geometry in the
+     * frustum.
+     */
+    guard: number;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/objects/materials/effects/ao/index.js

@@ -0,0 +1,72 @@
+import { Vector2 } from 'three';
+import { AO_TAPS, NOISE_TILE } from './ambient-occlusion-pass';
+// The folder's public face. One specifier carries every member the outside asks for.
+//
+// The three siblings must never import a value from here. Both pass shaders and the lit read are
+// template literals that interpolate constants at module initialization. A cycle through this file
+// evaluates one of those constants before its own module assigns it. The emit erases the
+// `import type` the siblings use, so that import forms no cycle.
+export * from './ambient-occlusion-pass';
+export * from './ambient-occlusion-patch';
+export * from './blur-pass';
+/**
+ * Builds this term's scene-wide state, at the agreed defaults.
+ *
+ * `createAoPassUniforms` builds what the AO pass alone reads. This builds what the whole scene
+ * shares, and what `createSceneEffects` spreads into the bundle it publishes.
+ * @returns A fresh object, whose identity outlives every write into it.
+ */
+export function createAmbientOcclusion() {
+    return {
+        aoMap: { value: null },
+        aoDepth: { value: null },
+        aoActive: { value: 0 },
+        aoGuard: { value: OCCLUSION_DEFAULTS.guard },
+        aoStrength: { value: OCCLUSION_DEFAULTS.strength },
+        aoBlur: { value: OCCLUSION_DEFAULTS.blur },
+        aoViewport: { value: new Vector2(1, 1) },
+        enabled: OCCLUSION_DEFAULTS.enabled,
+        radius: OCCLUSION_DEFAULTS.radius,
+        taps: OCCLUSION_DEFAULTS.taps,
+        occluders: new Set(),
+    };
+}
+/**
+ * The occlusion values this design agreed, and what each mount starts from.
+ *
+ * `radius` and `strength` are starting points rather than settled numbers, and the GUI tunes both
+ * per plan. `radius` is an absolute figure in plan units, so it suits one plan's booth sizes and
+ * not another's.
+ *
+ * `blur` and `taps` start at each loop's own bound, which is the shipped look.
+ */
+export const OCCLUSION_DEFAULTS = {
+    /** Whether the term runs at all. */
+    enabled: true,
+    /**
+     * How far the term looks for an occluder, in plan units.
+     *
+     * Chosen against the story plans, whose booths run about a hundred plan units across. That makes
+     * a band about a tenth of a booth wide, where a junction's shadow reads as shading rather than as
+     * an outline.
+     */
+    radius: 12,
+    /** How far the read blends an occluded fragment toward the shadow color, from `0` to `1`. */
+    strength: 0.5,
+    /**
+     * The blur kernel's side length in texels. It starts at the side that covers the rotation tile,
+     * see {@link AmbientOcclusion.aoBlur}.
+     */
+    blur: NOISE_TILE,
+    /** How many of the kernel's offsets the AO pass walks, see {@link AmbientOcclusion.taps}. */
+    taps: AO_TAPS,
+    /**
+     * How much wider than the main frustum the two passes run.
+     *
+     * Without the band, geometry just outside the frustum does not occlude geometry inside it, and a
+     * seam of missing darkening runs down the screen edges. `0.15` covers the widest reach a tap
+     * takes at half resolution. The cost is a lower effective resolution and more geometry in the
+     * frustum.
+     */
+    guard: 0.15,
+};

package/dist/objects/materials/{dim.d.ts → effects/color-dim.d.ts}

@@ -1,6 +1,6 @@
 import { type IUniform, type WebGLProgramParametersWithUniforms } from 'three';
-import { type UniformSchemaShader } from '../../core/InstanceUniforms';
-import { type RenderableDef } from '../../types/defs';
+import { type UniformSchemaShader } from '../../../core/InstanceUniforms';
+import { type RenderableDef } from '../../../types/defs';
 /**
  * Patches a compiled shader to dim what it draws. Returned by {@link useDimPatch} and called from a
  * material's own `onBeforeCompile`, so a material that already patches its shader composes the two
@@ -36,7 +36,7 @@ export declare function useDimPatch(): DimPatch;
  * @param parameters - The shader being compiled.
  * @param uniform - The layer's dim amount.
  * @returns Whether the shader was patched.
- * @throws {Error} If the prologue is present but the shader converts no color, which would leave
+ * @throws {Error} If the prologue is present but the shader has no output chain, which would leave
  *   dimming silently absent from a material that asked for it.
  */
 export declare function applyDim(parameters: WebGLProgramParametersWithUniforms, uniform: IUniform<number>): boolean;
@@ -120,4 +120,4 @@ export declare const DIM_INHERIT = -1;
  * and models already declare vertex uniforms, and shapes and text declare none besides this.
  */
 export declare const DIM_SCHEMA: UniformSchemaShader;
-//# sourceMappingURL=dim.d.ts.map
+//# sourceMappingURL=color-dim.d.ts.map

package/dist/objects/materials/{dim.js → effects/color-dim.js}

@@ -1,6 +1,6 @@
 import { useThree } from '@react-three/fiber';
 import { createContext, use, useEffect, useRef, useState } from 'react';
-import { declareBeforeMain } from '../../core/shader-source';
+import { declareBeforeMain, sceneColorAnchor } from '../../../core/shader-source';
 /**
  * The dim patch every material installs, reading the layer amount from {@link LayerDimContext}.
  *
@@ -46,7 +46,7 @@ export function useDimPatch() {
  * @param parameters - The shader being compiled.
  * @param uniform - The layer's dim amount.
  * @returns Whether the shader was patched.
- * @throws {Error} If the prologue is present but the shader converts no color, which would leave
+ * @throws {Error} If the prologue is present but the shader has no output chain, which would leave
  *   dimming silently absent from a material that asked for it.
  */
 export function applyDim(parameters, uniform) {
@@ -58,9 +58,9 @@ export function applyDim(parameters, uniform) {
     // Already installed, which is how a second call after the prologue arrives stays harmless.
     if (fragment.includes(DIM_FUNCTION))
         return false;
-    const anchor = colorspaceAnchor(fragment);
+    const anchor = sceneColorAnchor(fragment);
     if (!anchor)
-        throw new Error('applyDim: the shader has no colorspace conversion to dim before.');
+        throw new Error('applyDim: the shader has no output chain to dim before.');
     parameters.uniforms[LAYER_DIM] = uniform;
     // Ahead of `main`, because these are file-scope declarations — and `dimColor` takes the amount as a
     // parameter precisely so it needs nothing `main` declares.
@@ -125,24 +125,6 @@ export function instanceDim(dim) {
 export function clampDim(dim) {
     return Math.min(Math.max(dim, 0), 1);
 }
-/**
- * Where the fragment's color is final and still linear — the point dimming has to land in front of,
- * spelled whichever way the shader currently spells it.
- *
- * Two spellings because three resolves `#include` late, after every `onBeforeCompile`, while troika
- * resolves them itself while rebuilding `main`. A patch running after troika's rebuild therefore
- * finds the conversion already expanded to its chunk body. Both name the same line; neither is a
- * private marker of troika's.
- * @param fragmentShader - The shader to search.
- * @returns The anchor found, or `undefined` if the shader converts no color.
- */
-function colorspaceAnchor(fragmentShader) {
-    const include = /*glsl*/ `#include <colorspace_fragment>`;
-    const expanded = /*glsl*/ `gl_FragColor = linearToOutputTexel( gl_FragColor );`;
-    if (fragmentShader.includes(include))
-        return include;
-    return fragmentShader.includes(expanded) ? expanded : undefined;
-}
 /**
  * The dim amount a layer draws at, which every material beneath it reads.
  *
@@ -205,8 +187,8 @@ const DIM_DEFS = /* glsl */ `
   }
 `;
 /**
- * Dimming applied to the fragment, while the color is still linear — which is what
- * `darkenFactor`'s gamma correction assumes.
+ * Dimming applied while the color is still linear and scene-referred, which is what `darkenFactor`'s
+ * gamma correction assumes. See {@link sceneColorAnchor}.
  */
 const DIM_APPLY = /* glsl */ `
   gl_FragColor = dimColor(gl_FragColor, ${DIM_UNIFORM} < 0. ? ${LAYER_DIM} : ${DIM_UNIFORM});

package/dist/objects/materials/effects/contact-shadow.d.ts

@@ -0,0 +1,100 @@
+import { Color, type IUniform, Matrix4, type WebGLProgramParametersWithUniforms } from 'three';
+/**
+ * The scene-wide state this term owns: the uniforms every lit material reads, and the hex string a
+ * lil-gui color controller writes.
+ *
+ * Declared here rather than in `effects-context.ts`, because these are the term's own — the bundle
+ * that publishes them only assembles what each term declares. {@link CONTACT_SHADOW_DEFAULTS} sits
+ * here for the same reason.
+ *
+ * **Every field carries a `shadow` prefix**, because the bundle is flat and ambient occlusion brings
+ * a `strength` and a `color` of its own; the prefix is what keeps the two apart.
+ * {@link ContactShadow.planFromWorld} is the exception, because it names the plan rather than the
+ * shadow: it is the plan's own matrix, and the shadow is only its one reader today.
+ */
+export interface ContactShadow {
+    /** The shadow's reach above a volume's base, in plan units. */
+    shadowDistance: IUniform<number>;
+    /** The shadow's depth, from `0` to `1`. */
+    shadowStrength: IUniform<number>;
+    /**
+     * The shade both darkening terms blend toward.
+     *
+     * Shared rather than one per term, so a plan has one shade of shadow rather than two — ambient
+     * occlusion binds this very object under a name of its own.
+     */
+    shadowColor: IUniform<Color>;
+    /**
+     * The shade as a hex string, which is what a lil-gui color controller reads and writes.
+     *
+     * Beside the uniform rather than inside it because three holds a `Color` in the working space
+     * while lil-gui writes display sRGB, and `Color.set` on a string is the conversion.
+     */
+    shadowHex: string;
+    /**
+     * World space back to the plan's own, which is the space's own `Space.matrixInverse`.
+     *
+     * `SceneGraph` points this uniform at that matrix once. The space recomputes the matrix in place
+     * on every refit and never replaces it, so the shader reads the current fit with no copy. Never
+     * write through this value, because the write lands in the space itself.
+     *
+     * The height a volume is shaded by is a height in the plan, and nothing else in the vertex shader
+     * knows the plan. A mesh's own matrices place it in the world, and the world is the fit, whose z
+     * the fit mirrors. This uniform takes a placed vertex back.
+     */
+    planFromWorld: IUniform<Matrix4>;
+}
+/**
+ * Installs the contact shadow into a lit shader about to be compiled.
+ *
+ * A fake, not a measurement. It reads the vertex's height above the plan and darkens toward the base
+ * of every volume, which separates a wall side from a wall top and stands in for the shadow a wall
+ * casts onto the floor it meets. Ambient occlusion is a separate term, applied at the same anchor by
+ * `ao/ambient-occlusion-patch.ts`.
+ *
+ * The reach is a fixed world distance rather than each volume's own height. It needs no new data and
+ * stays consistent across a plan. A roof above the reach keeps its authored color exactly; a volume
+ * shorter than the reach blends its roof as it blends the rest of its height.
+ *
+ * The blend goes toward an authored color rather than multiplying down toward black, so the shade is
+ * a choice and not only its depth. MapLibre multiplies toward black and clamps.
+ *
+ * The patch lands above three's output chain, where the dim patch lands, so the color it changes is
+ * still linear and scene-referred.
+ *
+ * **This reaches solid shape batches and models.** Floors and zones are planar defs drawn with
+ * `MeshBasicMaterial`, which no light and no darkening term reaches — and whose unit plane sits at
+ * `z = 0`, where it would take the whole shadow.
+ * @param parameters - The shader being compiled.
+ * @param shadow - The mount's own shadow state, whose uniform objects the compiled program captures.
+ * @throws {Error} If the shader has no output chain, or no placement to read a vertex's height
+ *   after, either of which would leave the shadow silently absent from a material that asked for it.
+ */
+export declare function applyContactShadow(parameters: WebGLProgramParametersWithUniforms, shadow: ContactShadow): void;
+/**
+ * Builds this term's scene-wide state, at the agreed defaults.
+ *
+ * One object per mounted scene, never module state: a texture is not the only thing two `Renderer`
+ * mounts on one page would fight over — a program built in one context captures these very objects,
+ * so a singleton would let one scene's slider move the other's materials. `createSceneEffects`
+ * spreads this into the bundle it publishes.
+ * @returns A fresh object, whose identity is meant to outlive every write into it.
+ */
+export declare function createContactShadow(): ContactShadow;
+/**
+ * The contact shadow values this design agreed.
+ *
+ * Each one is a starting point rather than a settled number. The distance is an absolute figure in
+ * plan units, so it suits one plan's booth heights and not another's: a plan whose walls are a few
+ * units tall wants a few units of reach, and one whose walls are hundreds wants hundreds. It is
+ * tuned per plan through the GUI.
+ */
+export declare const CONTACT_SHADOW_DEFAULTS: {
+    /** How far above a volume's base the shadow reaches, in plan units. */
+    distance: number;
+    /** How far the base is blended toward the shadow color, from `0` to `1`. */
+    strength: number;
+    /** The shade the shadow blends toward. */
+    color: string;
+};
+//# sourceMappingURL=contact-shadow.d.ts.map

package/dist/objects/materials/effects/contact-shadow.js

@@ -0,0 +1,167 @@
+import { Color, Matrix4 } from 'three';
+import { declareBeforeMain, replaceAnchor, sceneColorAnchor } from '../../../core/shader-source';
+/**
+ * Installs the contact shadow into a lit shader about to be compiled.
+ *
+ * A fake, not a measurement. It reads the vertex's height above the plan and darkens toward the base
+ * of every volume, which separates a wall side from a wall top and stands in for the shadow a wall
+ * casts onto the floor it meets. Ambient occlusion is a separate term, applied at the same anchor by
+ * `ao/ambient-occlusion-patch.ts`.
+ *
+ * The reach is a fixed world distance rather than each volume's own height. It needs no new data and
+ * stays consistent across a plan. A roof above the reach keeps its authored color exactly; a volume
+ * shorter than the reach blends its roof as it blends the rest of its height.
+ *
+ * The blend goes toward an authored color rather than multiplying down toward black, so the shade is
+ * a choice and not only its depth. MapLibre multiplies toward black and clamps.
+ *
+ * The patch lands above three's output chain, where the dim patch lands, so the color it changes is
+ * still linear and scene-referred.
+ *
+ * **This reaches solid shape batches and models.** Floors and zones are planar defs drawn with
+ * `MeshBasicMaterial`, which no light and no darkening term reaches — and whose unit plane sits at
+ * `z = 0`, where it would take the whole shadow.
+ * @param parameters - The shader being compiled.
+ * @param shadow - The mount's own shadow state, whose uniform objects the compiled program captures.
+ * @throws {Error} If the shader has no output chain, or no placement to read a vertex's height
+ *   after, either of which would leave the shadow silently absent from a material that asked for it.
+ */
+export function applyContactShadow(parameters, shadow) {
+    // Already installed, which is how a repeated compile stays harmless.
+    if (parameters.fragmentShader.includes(SHADOW_FUNCTION))
+        return;
+    const anchor = sceneColorAnchor(parameters.fragmentShader);
+    if (!anchor) {
+        throw new Error('applyContactShadow: the shader has no output chain to darken before.');
+    }
+    // Both rewrites before any write, so this either installs the shadow or leaves the parameters
+    // exactly as it found them. A shader whose vertex stage places its vertices some other way throws
+    // from `replaceAnchor` below, and a caller that means to carry on — a material whose asset is not
+    // one three built — must not be left holding four bindings for a program nothing patched.
+    const vertexShader = replaceAnchor(declareBeforeMain(parameters.vertexShader, VERTEX_DEFS), PLACEMENT_ANCHOR, `${PLACEMENT_ANCHOR}\n${VERTEX_APPLY}`);
+    const fragmentShader = declareBeforeMain(parameters.fragmentShader, FRAGMENT_DEFS).replace(anchor, `${SHADOW_APPLY}\n${anchor}`);
+    parameters.uniforms[SHADOW_DISTANCE] = shadow.shadowDistance;
+    parameters.uniforms[SHADOW_STRENGTH] = shadow.shadowStrength;
+    parameters.uniforms[SHADOW_COLOR] = shadow.shadowColor;
+    parameters.uniforms[PLAN_FROM_WORLD] = shadow.planFromWorld;
+    parameters.vertexShader = vertexShader;
+    parameters.fragmentShader = fragmentShader;
+}
+/**
+ * Builds this term's scene-wide state, at the agreed defaults.
+ *
+ * One object per mounted scene, never module state: a texture is not the only thing two `Renderer`
+ * mounts on one page would fight over — a program built in one context captures these very objects,
+ * so a singleton would let one scene's slider move the other's materials. `createSceneEffects`
+ * spreads this into the bundle it publishes.
+ * @returns A fresh object, whose identity is meant to outlive every write into it.
+ */
+export function createContactShadow() {
+    return {
+        shadowDistance: { value: CONTACT_SHADOW_DEFAULTS.distance },
+        shadowStrength: { value: CONTACT_SHADOW_DEFAULTS.strength },
+        shadowColor: { value: new Color(CONTACT_SHADOW_DEFAULTS.color) },
+        shadowHex: CONTACT_SHADOW_DEFAULTS.color,
+        planFromWorld: { value: new Matrix4() },
+    };
+}
+/**
+ * The contact shadow values this design agreed.
+ *
+ * Each one is a starting point rather than a settled number. The distance is an absolute figure in
+ * plan units, so it suits one plan's booth heights and not another's: a plan whose walls are a few
+ * units tall wants a few units of reach, and one whose walls are hundreds wants hundreds. It is
+ * tuned per plan through the GUI.
+ */
+export const CONTACT_SHADOW_DEFAULTS = {
+    /** How far above a volume's base the shadow reaches, in plan units. */
+    distance: 3,
+    /** How far the base is blended toward the shadow color, from `0` to `1`. */
+    strength: 0.35,
+    /** The shade the shadow blends toward. */
+    color: '#4a5260',
+};
+/** The uniform carrying the shadow's reach. */
+const SHADOW_DISTANCE = 'uShadowDistance';
+/** The uniform carrying the shadow's depth. */
+const SHADOW_STRENGTH = 'uShadowStrength';
+/** The uniform carrying the shade the shadow blends toward. */
+const SHADOW_COLOR = 'uShadowColor';
+/** The uniform carrying world space back to the plan's own. */
+const PLAN_FROM_WORLD = 'uPlanFromWorld';
+/** The signature {@link applyContactShadow} looks for, to tell a patched shader from a fresh one. */
+const SHADOW_FUNCTION = 'vec3 contactShadow(';
+/** The varying carrying a vertex's height above the plan. */
+const HEIGHT_VARYING = 'vHeight';
+/** The local three's own placement leaves the vertex's world position in. */
+const WORLD_POSITION = 'worldPosition';
+/**
+ * Where the height read lands: three's own placement of the vertex into world space.
+ *
+ * `<worldpos_vertex>` declares {@link WORLD_POSITION} and applies the batching matrix, the instance
+ * matrix and the model matrix to it, so the read below composes nothing of its own. This package
+ * widens that chunk's instancing guard to fire under indirect instancing as well. See
+ * `instanced-material.ts`.
+ *
+ * The read cannot ride on `openMain` the way the rest of this package's vertex injections do.
+ * `instanceMatrix` is the local that the indirect instancing prologue declares at the top of `main`,
+ * and it shadows the placeholder attribute three declares for any `isInstancedMesh` object.
+ * `openMain` inserts at the top and the last caller runs first, so a patch installed from a
+ * material's own handler would land above the mesh's prologue and read the empty attribute.
+ */
+const PLACEMENT_ANCHOR = /* glsl */ `#include <worldpos_vertex>`;
+/**
+ * The vertex-stage declarations, and the define that makes three build the world position at all.
+ *
+ * three guards the whole body of `<worldpos_vertex>` behind five conditions: `USE_ENVMAP`,
+ * `DISTANCE`, `USE_SHADOWMAP`, `USE_TRANSMISSION`, and a spot light coord count above zero. This
+ * renderer sets none of them, so the chunk expands to nothing and the shader declares no world
+ * position to read. `DISTANCE` is the one of the five that no chunk this renderer includes reads, in
+ * either stage, so defining it buys the world position and changes nothing else. three's own
+ * `distance` material defines it for itself, and nothing here draws with that material.
+ *
+ * `declareBeforeMain` puts this above `main`, which is above every `#include` inside `main`, so the
+ * preprocessor reads the define before it reaches the guard.
+ */
+const VERTEX_DEFS = /* glsl */ `
+  #define DISTANCE
+  uniform mat4 ${PLAN_FROM_WORLD};
+  varying float ${HEIGHT_VARYING};
+`;
+/**
+ * The vertex-stage read: the vertex's height in the plan's own space.
+ *
+ * `<worldpos_vertex>` runs one line above and leaves the vertex's world position in
+ * {@link WORLD_POSITION}. {@link PLAN_FROM_WORLD} takes that position back to the plan, and the
+ * height is its `z`.
+ *
+ * three's chunk composes the placement, which is what makes the read correct for content whose
+ * geometry is not authored in plan coordinates. A model carries GLB-local coordinates and a
+ * per-instance placement matrix, so its own `position.z` means nothing there. The solid shape batches
+ * do carry absolute plan coordinates, and they drew right only while their instance transform stayed
+ * identity. Nothing enforces that.
+ */
+const VERTEX_APPLY = /* glsl */ `
+  ${HEIGHT_VARYING} = (${PLAN_FROM_WORLD} * ${WORLD_POSITION}).z;
+`;
+/** The fragment-stage declarations. */
+const FRAGMENT_DEFS = /* glsl */ `
+  uniform float ${SHADOW_DISTANCE};
+  uniform float ${SHADOW_STRENGTH};
+  uniform vec3 ${SHADOW_COLOR};
+  varying float ${HEIGHT_VARYING};
+
+  ${SHADOW_FUNCTION}vec3 rgb, float height) {
+    float lit = clamp(height / max(${SHADOW_DISTANCE}, 1e-4), 0., 1.);
+    return mix(rgb, ${SHADOW_COLOR}, ${SHADOW_STRENGTH} * (1. - lit));
+  }
+`;
+/**
+ * The shadow applied while the color is still linear and scene-referred.
+ *
+ * The call is spelled out rather than built from {@link SHADOW_FUNCTION}, which stays the
+ * already-patched detector and nothing else.
+ */
+const SHADOW_APPLY = /* glsl */ `
+  gl_FragColor.rgb = contactShadow(gl_FragColor.rgb, ${HEIGHT_VARYING});
+`;

package/dist/objects/materials/effects/effects-context.d.ts

@@ -0,0 +1,52 @@
+import { type AmbientOcclusion } from './ao';
+import { type ContactShadow } from './contact-shadow';
+/**
+ * Everything one mounted scene's shared effects hold: the tuned values, the registry of what asks
+ * for ambient occlusion, and the uniforms the lit shaders read.
+ *
+ * **This is scene-wide shading state, not post processing.** Nothing here runs over the finished
+ * image: the ambient occlusion pass is a *pre*pass, and every term is applied inside the lit shader
+ * itself, so there is no compositing stage for this to be a part of.
+ *
+ * **Each term owns its own state, and this only assembles it.** Every field here is declared by the
+ * term that owns it, and this alias gathers them. The two terms share one shade of shadow, which the
+ * contact shadow declares and ambient occlusion binds under a name of its own.
+ *
+ * **An alias over an intersection, rather than an interface that extends.** An intersection states
+ * what the bundle is, an assembly of what the terms declare, where `extends` reads as a subtype
+ * relationship, which is not what is meant. And an interface that extends exactly one parent and
+ * declares nothing of its own is what `@typescript-eslint/no-empty-object-type` exists to flag, so
+ * that form would need a suppression this one does not.
+ *
+ * **One object per mount, never module state.** Two `Renderer` mounts on one page have two GL
+ * contexts and two sets of render targets, and a module singleton would hand both of their materials
+ * whichever texture wrote last. The identity never changes once created, so the passes write into it
+ * every frame with no React render and no shader recompile behind them — the discipline
+ * `contact-shadow.ts` uses for its three uniforms, published the way `SpaceContext` publishes a
+ * `Space` that is refitted in place.
+ *
+ * **`LayerDimContext` stays where it is and is not merged in.** It carries a single number, it is
+ * re-provided by every `Layer`, and it nests. This bundle is one object per renderer mount whose
+ * identity must never change, which is what lets a material capture it in `onBeforeCompile` and a
+ * frame write `.value` with no recompile. Merging the two would either re-provide this object at
+ * every layer boundary or flatten dim's nesting.
+ */
+export type SceneEffects = AmbientOcclusion & ContactShadow;
+/**
+ * Builds one scene's effect state, from each term's own factory.
+ * @returns A fresh object, whose identity is meant to outlive every write into it.
+ */
+export declare function createSceneEffects(): SceneEffects;
+/**
+ * The effect state of the enclosing scene.
+ * @returns The object `Scene` published, or a standalone one when rendered outside a scene.
+ */
+export declare function useSceneEffects(): SceneEffects;
+/**
+ * The effect state every lit material and both passes read.
+ *
+ * The default is a standalone object rather than `null`, so a material rendered outside a scene
+ * still compiles and simply shades with the terms switched off — the same shape `SpaceContext` takes.
+ */
+export declare const SceneEffectsContext: import("react").Context<SceneEffects>;
+//# sourceMappingURL=effects-context.d.ts.map

package/dist/objects/materials/effects/effects-context.js

@@ -0,0 +1,24 @@
+import { createContext, use } from 'react';
+import { createAmbientOcclusion } from './ao';
+import { createContactShadow } from './contact-shadow';
+/**
+ * Builds one scene's effect state, from each term's own factory.
+ * @returns A fresh object, whose identity is meant to outlive every write into it.
+ */
+export function createSceneEffects() {
+    return { ...createAmbientOcclusion(), ...createContactShadow() };
+}
+/**
+ * The effect state of the enclosing scene.
+ * @returns The object `Scene` published, or a standalone one when rendered outside a scene.
+ */
+export function useSceneEffects() {
+    return use(SceneEffectsContext);
+}
+/**
+ * The effect state every lit material and both passes read.
+ *
+ * The default is a standalone object rather than `null`, so a material rendered outside a scene
+ * still compiles and simply shades with the terms switched off — the same shape `SpaceContext` takes.
+ */
+export const SceneEffectsContext = createContext(createSceneEffects());