@expofp/renderer 3.34.2 → 3.35.0

package/dist/objects/materials/ColorMaterial.js

@@ -1,89 +1,111 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useState } from 'react';
-import { useDimPatch } from './dim';
+import { applyAmbientOcclusion } from './effects/ao';
+import { useDimPatch } from './effects/color-dim';
+import { applyContactShadow } from './effects/contact-shadow';
+import { useSceneEffects } from './effects/effects-context';
 import { sharedParams } from './shared';
 /**
- * The material a shape batch draws with, rendered as a child of the mesh so R3F attaches, updates,
- * and disposes it. Also troika's base material for text (see `Texts`), which never asks for `solid`.
+ * The material a shape batch draws with. It renders as a child of the mesh, so R3F attaches, updates
+ * and disposes it. It is also troika's base material for text, which never asks for `solid`. See
+ * `Texts`.
  *
- * One component with a branch rather than two files, because the two are the same thing along one
- * axis — what a batch of shapes draws with — and the three differences are the whole point, best
- * read side by side:
+ * One component with a branch rather than two files. The two are the same thing along one axis, which
+ * is what a batch of shapes draws with. The three differences read best side by side:
  *
  * | | flat (default) | `solid` |
  * | --- | --- | --- |
- * | base | `MeshBasicMaterial`, unlit | `MeshPhysicalMaterial`, lit |
- * | `depthWrite` | off, from {@link sharedParams} | **on** |
- * | polygon offset | on, from {@link sharedParams} | **off** |
+ * | base | `MeshBasicMaterial`, unlit | `MeshLambertMaterial`, lit |
+ * | `depthWrite` | off, from {@link sharedParams} | on |
+ * | polygon offset | on, from {@link sharedParams} | off |
  *
- * Each difference is load-bearing. A volume is the one kind of content that writes depth: that is how
- * its own faces resolve against each other, and what lets 2D content drawn afterwards be occluded by
- * it. It carries no polygon offset because solids are what everything else is biased *against* —
- * offsetting them too would only move the problem.
+ * Each difference carries its own weight. A volume is the one kind of content that writes depth. That
+ * is how its own faces resolve against each other, and it is what lets 2D content drawn afterwards be
+ * occluded by it. A volume carries no polygon offset, because solids are what everything else is
+ * biased against. An offset on the solids too only moves the problem.
  *
- * `ior: 1` and `specularIntensity: 0` drive the lit material's `F0` to zero, so no specular lobe sits
- * on top of the diffuse term. That is what makes the lighting identity exact: with the two lights
- * summing to intensity `π`, a face square-on to the camera renders at precisely the authored color
- * (see `Lighting`). A default `MeshPhysicalMaterial` would put a sheen on every wall and push it
- * above its albedo.
+ * The lit branch is `MeshLambertMaterial` alone. It has no specular lobe at all, so this never sets
+ * `ior` or `specularIntensity`. three evaluates it per fragment with `BRDF_Lambert`, which is
+ * `albedo / π`. Its vertex shader carries `batching_vertex` and `color_vertex`, so
+ * `BatchedMesh.setColorAt` keeps working. Its fragment shader carries the output chain, so the dim
+ * patch keeps its anchor.
  *
- * Per-instance color arrives through `BatchedMesh.setColorAt` either way: three injects the
+ * The light rig alone holds a roof to its authored color now. `Lighting` derives both intensities from
+ * the one `contrast` control every frame. An up-facing surface then lands on the color it was authored
+ * with, and no surface the design accounts for clips.
+ *
+ * Per-instance color arrives through `BatchedMesh.setColorAt` on either branch. three injects the
  * batching-color chunk for whatever material the batch draws with.
  *
- * **`translucent` is the one place the array-order contract bends, and it is deliberate.** It sets
- * `transparent: true`, which moves the batch into three's transparent list — drawn after *every*
- * opaque object in the scene, whatever `renderOrder` says (`WebGLRenderer.renderScene`). That is
- * exactly what makes a translucent volume blend with the opaque content behind it even when that
- * content lives in a later layer, which no position in the ordered stream can achieve: a translucent
- * surface can only blend with what is already in the framebuffer.
+ * `translucent` is the one place the array-order contract bends, and it bends on purpose. It sets
+ * `transparent: true`, which moves the batch into three's transparent list. three draws that list
+ * after every opaque object in the scene, whatever `renderOrder` says. See
+ * `WebGLRenderer.renderScene`. That is what lets a translucent volume blend with the opaque content
+ * behind it, even when that content lives in a later layer. No position in the ordered stream can do
+ * the same, because a translucent surface can only blend with what already sits in the framebuffer.
  *
- * What it costs is the reverse case. A planar def sitting *on* a translucent volume — a label or logo
- * on a glass roof — draws in the opaque pass and so lands **before** it: the label composites against
- * whatever was under the glass rather than onto it, and the volume then glazes over the label. So a
- * translucent solid is right about what is behind it and wrong about what is on it. Flat content is
- * never given this flag for the same reason, plus one of its own: 2D is coplanar, so it has no depth
- * order to sort by and order is all it has.
+ * The reverse case is what it costs. Take a planar def sitting on a translucent volume, such as a
+ * label or a logo on a glass roof. It draws in the opaque pass, so it lands before the volume. The
+ * label composites against whatever was under the glass rather than onto it, and the volume then
+ * glazes over the label. So a translucent solid is right about what is behind it and wrong about what is on it. Flat
+ * content never takes this flag for the same reason, and for one of its own: 2D content is coplanar,
+ * so it has no depth order to sort by and order is all it has.
  *
- * `forceSinglePass` is switched off here alone. three renders a `DoubleSide` transparent material
- * twice — back faces, then front (`WebGLRenderer.js:1348`) — which is a correctly ordered two-pass
- * for free, and the reason a closed translucent volume does not blend its own far and near surfaces
- * in whatever order the batch happened to pack them.
+ * `forceSinglePass` is switched off here alone. three draws a `DoubleSide` transparent material
+ * twice, back faces and then front. See `WebGLRenderer.js:1348`. That is a correctly ordered two-pass
+ * for free. It is why a closed translucent volume does not blend its own far and near surfaces in
+ * whatever order the batch packed them.
  *
- * Depth writes stay **on** even when translucent, which is not three's usual convention. Two rules
- * depend on it: a translucent volume must still be occluded by anything nearer, and a farther one
- * drawn later must not paint over it. MapLibre makes the same choice for `fill-extrusion`
- * (`DepthMode.ReadWrite` in both of its passes). The trade and the two rejected alternatives are
- * recorded in the design spec's Decision 2.
+ * Depth writes stay on even when translucent, which is not three's usual convention. Two rules depend
+ * on it. A translucent volume must still be occluded by anything nearer, and a farther volume drawn
+ * later must not paint over it. MapLibre makes the same choice for `fill-extrusion`, with
+ * `DepthMode.ReadWrite` in both of its passes. The design spec's Decision 2 records the trade and the
+ * two rejected alternatives.
  *
- * The branch is stable for a mounted batch — `Shapes` renders a separate element per kind, each with
- * a constant `solid` — so R3F never swaps one base class for the other under a live mesh.
+ * The branch is stable for a mounted batch, because `Shapes` renders a separate element per kind and
+ * each one carries a constant `solid`. So R3F never swaps one base class for the other under a live
+ * mesh.
  * @param props - The material's base color, and whether it draws volumes.
  * @returns The material element.
  */
 export function ColorMaterial(props) {
-    // Read-then-default rather than a destructuring default: the React Compiler cannot lower
+    // Read and then default, rather than a destructuring default. The React Compiler cannot lower
     // `const { color = 'white' } = props` (BuildHIR::lowerAssignment, AssignmentPattern), and
     // floorplan's dev build runs the compiler with `panicThreshold: 'all_errors'`, which turns that
     // into a hard 500 for the whole app. Storybook's pass defaults to `panicThreshold: 'none'` and
-    // silently skips the component instead, so only the running app surfaces it.
+    // skips the component in silence, so only the running app shows the failure.
     const color = props.color ?? 'white';
-    // Before the branch, because it is a hook — and passed to both, because a volume dims exactly as
-    // flat content does: the patch runs on whatever `gl_FragColor` the material arrived at, which for
-    // a lit material is the shaded color.
+    const solid = props.solid === true;
+    // Handed to both branches, because a volume dims the way flat content does. The patch runs on
+    // whatever `gl_FragColor` the material arrived at, which for a lit material is the shaded color.
     const dimPatch = useDimPatch();
-    // The caller's surgery first, then dimming — so a pre-patch that declares the dim uniform's
-    // stand-in is already in the shader when the dim patch looks for it. One stable handler, for the
-    // same reason `useDimPatch` keeps its own.
+    // The scene's own effect state, captured once. Its identity never changes, so the compiled program
+    // holds the uniform objects a frame and a slider write into, and neither one costs a recompile.
+    const effects = useSceneEffects();
+    // The caller's surgery first, then dimming. A pre-patch that declares the dim uniform's stand-in
+    // then sits in the shader before the dim patch looks for it. One stable handler, for the reason
+    // `useDimPatch` keeps its own.
     const [onBeforeCompile] = useState(() => {
         const pre = props.onBeforeCompile;
         return (parameters) => {
             pre?.(parameters);
+            // Volumes only. Flat content has no height to read, and its unit plane sits at `z = 0`, where
+            // the contact shadow takes the whole surface. Flat content also stays out of the depth prepass,
+            // so an occlusion read finds no stored depth that agrees with it.
+            //
+            // Both effects land ahead of the dim patch, so the three run in the order they describe: the
+            // shadow and the occlusion shade the surface, and dimming desaturates the result. All three
+            // insert above the same anchor, so the later install runs last.
+            if (solid) {
+                applyContactShadow(parameters, effects);
+                applyAmbientOcclusion(parameters, effects);
+            }
             dimPatch(parameters);
         };
     });
-    if (props.solid) {
+    if (solid) {
         const translucent = props.translucent ?? false;
-        return (_jsx("meshPhysicalMaterial", { ...sharedParams, color: color, depthWrite: true, polygonOffset: false, ior: 1, specularIntensity: 0, transparent: translucent, forceSinglePass: !translucent, onBeforeCompile: onBeforeCompile }));
+        return (_jsx("meshLambertMaterial", { ...sharedParams, color: color, depthWrite: true, polygonOffset: false, transparent: translucent, forceSinglePass: !translucent, onBeforeCompile: onBeforeCompile }));
     }
     return _jsx("meshBasicMaterial", { ...sharedParams, color: color, onBeforeCompile: onBeforeCompile });
 }

package/dist/objects/materials/LineMaterial.js

@@ -2,7 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { extend } from '@react-three/fiber';
 import { NotEqualStencilFunc, ReplaceStencilOp, } from 'three';
 import { LineMaterial as LineMaterialBase } from 'three/addons/lines/LineMaterial.js';
-import { useDimPatch } from './dim';
+import { useDimPatch } from './effects/color-dim';
 import { sharedParams } from './shared';
 /**
  * The stencil value a line layer stamps on every pixel it covers.

package/dist/objects/materials/ModelMaterial.d.ts

@@ -2,38 +2,50 @@ import { type Material } from 'three';
 /** Props for {@link ModelMaterial}. */
 export interface ModelMaterialProps {
     /**
-     * The material the GLB authored. Shared across every layer drawing the same model, so it is never
-     * mutated — this clones it and adjusts the clone.
+     * The material the GLB authored. Every layer drawing the same model shares it, so nothing mutates
+     * it. This component clones it and adjusts the clone.
      */
     source: Material;
     /**
-     * The name of a per-instance `float` uniform to multiply alpha by, so one mesh can hold instances
-     * of differing opacity. The mesh owns the name and declares it; the material only patches its
-     * shader to read it.
+     * The name of a per-instance `float` uniform to multiply alpha by, so one mesh can hold instances of
+     * differing opacity. The mesh owns the name and declares it. The material only patches its shader to
+     * read it.
      */
     opacityUniform: string;
     /**
      * Whether any instance drawing this material is translucent.
      *
-     * Per-instance opacity is a *fragment* multiplier, but whether alpha blends at all is a **material**
-     * decision: three drops a `NormalBlending` material with `transparent: false` to `NoBlending`
-     * (`WebGLState.setMaterial`), which discards the alpha entirely — the instance then composites
-     * against the page rather than against the scene. So the mesh has to tell the material that at
-     * least one of its instances needs blending.
+     * Per-instance opacity is a fragment multiplier, and whether alpha blends at all is a material
+     * decision. three drops a `NormalBlending` material with `transparent: false` to `NoBlending`, in
+     * `WebGLState.setMaterial`, which discards the alpha. The instance then composites against the page
+     * rather than against the scene. So the mesh has to tell the material that at least one of its
+     * instances needs blending.
      */
     translucent?: boolean;
 }
 /**
- * The material a model draws with: the GLB's own, cloned and adjusted for the plan's depth rules and
- * for per-instance opacity.
+ * The material a model draws with: the GLB's own, cloned and adjusted for the plan's depth rules, for
+ * the plan's shading, and for per-instance opacity.
  *
- * A model is one of the two kinds of content that **write depth**, translucent ones included — that
- * is what makes it occlude itself, other models, and any 2D content drawn after it. The rest of the
- * scene draws with `depthWrite: false` and a small polygon offset precisely so it can be biased
- * against surfaces like these, so a model carries no offset of its own.
+ * A model is one of the two kinds of content that write depth, translucent models included. That is
+ * what makes a model occlude itself, other models, and any 2D content drawn after it. The rest of the
+ * scene draws with `depthWrite: false` and a small polygon offset so that it can be biased against
+ * surfaces like these, so a model carries no offset of its own.
  *
- * Everything else about the material is left as the GLB authored it — maps, roughness, metalness,
- * emissive, side. A model's appearance is the asset's business, not the renderer's.
+ * A model takes both darkening terms, the way a solid shape batch does. The GLTF loader produces a
+ * `MeshStandardMaterial`, which carries the same output chain and the same placement chunk, so both
+ * patches apply unchanged. The contact shadow reads a plan-space height. That is what makes it correct
+ * for geometry authored in the GLB's own coordinates and placed by a per-instance matrix.
+ *
+ * An asset declaring `KHR_materials_unlit` takes both terms too, on purpose. The loader hands such a
+ * material over as a `MeshBasicMaterial`, which carries both anchors, so nothing here has to sniff a
+ * type to include it. Neither term is a light. They are the plan's own depth cue, applied to whatever
+ * color the material arrived at. The design asks for one shade of shadow across the plan. An unlit
+ * booth with no darkening at its base reads as floating beside a lit one. That is a worse answer to
+ * "unlit" than shading it.
+ *
+ * Everything else about the material stays as the GLB authored it: maps, roughness, metalness,
+ * emissive, side. A model's own appearance is the asset's business. How the plan is shaded is not.
  * @param props - The source material and the per-instance opacity uniform's name.
  * @returns The material element.
  */

package/dist/objects/materials/ModelMaterial.js

@@ -1,82 +1,109 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useState } from 'react';
 import { LessEqualDepth, } from 'three';
-import { useDimPatch } from './dim';
+import { applyAmbientOcclusion } from './effects/ao';
+import { useDimPatch } from './effects/color-dim';
+import { applyContactShadow } from './effects/contact-shadow';
+import { useSceneEffects } from './effects/effects-context';
 /**
- * The material a model draws with: the GLB's own, cloned and adjusted for the plan's depth rules and
- * for per-instance opacity.
+ * The material a model draws with: the GLB's own, cloned and adjusted for the plan's depth rules, for
+ * the plan's shading, and for per-instance opacity.
  *
- * A model is one of the two kinds of content that **write depth**, translucent ones included — that
- * is what makes it occlude itself, other models, and any 2D content drawn after it. The rest of the
- * scene draws with `depthWrite: false` and a small polygon offset precisely so it can be biased
- * against surfaces like these, so a model carries no offset of its own.
+ * A model is one of the two kinds of content that write depth, translucent models included. That is
+ * what makes a model occlude itself, other models, and any 2D content drawn after it. The rest of the
+ * scene draws with `depthWrite: false` and a small polygon offset so that it can be biased against
+ * surfaces like these, so a model carries no offset of its own.
  *
- * Everything else about the material is left as the GLB authored it — maps, roughness, metalness,
- * emissive, side. A model's appearance is the asset's business, not the renderer's.
+ * A model takes both darkening terms, the way a solid shape batch does. The GLTF loader produces a
+ * `MeshStandardMaterial`, which carries the same output chain and the same placement chunk, so both
+ * patches apply unchanged. The contact shadow reads a plan-space height. That is what makes it correct
+ * for geometry authored in the GLB's own coordinates and placed by a per-instance matrix.
+ *
+ * An asset declaring `KHR_materials_unlit` takes both terms too, on purpose. The loader hands such a
+ * material over as a `MeshBasicMaterial`, which carries both anchors, so nothing here has to sniff a
+ * type to include it. Neither term is a light. They are the plan's own depth cue, applied to whatever
+ * color the material arrived at. The design asks for one shade of shadow across the plan. An unlit
+ * booth with no darkening at its base reads as floating beside a lit one. That is a worse answer to
+ * "unlit" than shading it.
+ *
+ * Everything else about the material stays as the GLB authored it: maps, roughness, metalness,
+ * emissive, side. A model's own appearance is the asset's business. How the plan is shaded is not.
  * @param props - The source material and the per-instance opacity uniform's name.
  * @returns The material element.
  */
 export function ModelMaterial(props) {
     const { source, opacityUniform } = props;
     const dimPatch = useDimPatch();
+    // The scene's own effect state, captured once. Its identity never changes, so the compiled program
+    // holds the uniform objects a frame and a slider write into, and neither one costs a recompile.
+    const effects = useSceneEffects();
     const translucent = props.translucent ?? false;
-    // Cloned once and held in state: R3F would dispose a material it created on unmount, and the
-    // source belongs to the module-level model cache, which may still be serving other layers. The
-    // dim patch is installed with it, once — the patch is stable and reads the current amount through
-    // the uniform it owns.
-    const [material] = useState(() => adjust(source.clone(), opacityUniform, dimPatch, translucent));
+    // Cloned once and held in state. R3F disposes a material it created on unmount, and the source
+    // belongs to the module-level model cache, which can still be serving other layers. Every patch
+    // goes on with the clone, once. Each patch is stable and reads its current values through the
+    // uniforms it owns.
+    const [material] = useState(() => adjust(source.clone(), opacityUniform, dimPatch, effects, translucent));
     useEffect(() => () => material.dispose(), [material]);
     return _jsx("primitive", { object: material, attach: "material" });
 }
 /**
- * Applies the plan's depth rules and the per-instance opacity patch to a cloned GLB material.
+ * Applies the plan's depth rules, its two darkening terms and the per-instance opacity patch to a
+ * cloned GLB material.
  * @param material - The clone to adjust.
  * @param opacityUniform - The per-instance uniform's name.
  * @param dimPatch - Installs dimming on the compiled shader.
+ * @param effects - The scene's shared effect state, which both darkening terms read.
  * @param translucent - Whether any instance drawing it needs its alpha blended.
  * @returns The same material.
  */
-function adjust(material, opacityUniform, dimPatch, translucent) {
+function adjust(material, opacityUniform, dimPatch, effects, translucent) {
     material.depthFunc = LessEqualDepth;
     material.polygonOffset = false;
-    // `transparent` moves a material into three's transparent list, drawn after *every* opaque object
-    // in the scene whatever the layer order says — which is what lets a translucent model blend with
-    // the content behind it instead of with an empty frame. It is a **material** property and never a
-    // per-instance one, so which list a def belongs in is a partition rather than a flag: `Models`
-    // keeps a layer's translucent copies in a batch of their own and re-splits when a def's opacity
-    // crosses 1, exactly as `Shapes` splits its volumes. `ColorMaterial` makes the same trade and
-    // records what it costs — a planar def sitting *on* a translucent one is drawn before it.
+    // `transparent` moves a material into three's transparent list, which three draws after every
+    // opaque object in the scene whatever the layer order says. That is what lets a translucent model
+    // blend with the content behind it instead of with an empty frame.
+    //
+    // It is a material property and never a per-instance one, so which list a def belongs in is a
+    // partition rather than a flag. `Models` keeps a layer's translucent copies in a batch of their own,
+    // the way `Shapes` splits its volumes. It re-splits when a def's opacity crosses 1. `ColorMaterial`
+    // makes the same trade and records what it costs: a planar def sitting on a translucent one draws
+    // before it.
     material.transparent =
         material.transparent || translucent || material.opacity < 1;
-    // Depth writes stay on even when translucent, which is not three's usual convention and is
-    // deliberate. Two of the plan's rules depend on it: a translucent model must still be occluded by
-    // anything nearer the camera, and a planar def drawn after it — a label or logo on a booth roof —
-    // must be occluded by it. Both are depth-buffer questions, and switching writes off answers them
-    // wrongly: a *farther* solid drawn later would have nothing to reject it and would paint straight
-    // over the translucent one in front of it.
+    // Depth writes stay on even when translucent, which is not three's usual convention and is the
+    // choice this renderer makes. Two of the plan's rules depend on it. A translucent model must still
+    // be occluded by anything nearer the camera. A planar def drawn after it, a label or a logo on a
+    // booth roof, must be occluded by it. Both are depth-buffer questions, and switching
+    // writes off answers them wrongly: a farther solid drawn later has nothing to reject it, and it
+    // paints straight over the translucent one in front of it.
     //
-    // What it costs is seeing *through* a translucent surface to content drawn after it, which no
-    // painter's-order renderer can offer — blending needs depth order, and array order is authoring
-    // order. MapLibre makes the same trade for `fill-extrusion` (`DepthMode.ReadWrite` in both of its
-    // passes), degrading to a color error rather than a structural one. The obligation it puts on
-    // callers — order a translucent model's layer after whatever should show through it — is spelled
-    // out in the design spec's Decision 2, along with the two alternatives and why each loses more
+    // What it costs is a view through a translucent surface to content drawn after it, and no
+    // painter's-order renderer can offer that. Blending needs depth order, and array order is authoring
+    // order. MapLibre makes the same trade for `fill-extrusion`, with `DepthMode.ReadWrite` in both of
+    // its passes, and degrades to a color error rather than a structural one. The obligation it puts on
+    // callers is to order a translucent model's layer after whatever has to show through it. The design
+    // spec's Decision 2 spells that out, along with the two alternatives and why each one loses more
     // than it gains.
     material.depthWrite = true;
     const chained = material.onBeforeCompile.bind(material);
     material.onBeforeCompile = (parameters, ...rest) => {
         chained(parameters, ...rest);
-        // Applied at the very end of the fragment chain, after `<dithering_fragment>`, so it multiplies
-        // the final composed alpha rather than an intermediate one. The instanced mesh injects the
-        // uniform fetch at the top of `main()`, so the name is in scope by the time this runs.
+        // Applied at the end of the fragment chain, after `<dithering_fragment>`, so it multiplies the
+        // final composed alpha rather than an intermediate one. The instanced mesh injects the uniform
+        // fetch at the top of `main()`, so the name is in scope by the time this runs.
         parameters.fragmentShader = parameters.fragmentShader.replace('#include <dithering_fragment>', 
         /*glsl*/ `
         #include <dithering_fragment>
         gl_FragColor.a *= ${opacityUniform};
       `.trim());
-        // Dim touches rgb and opacity touches alpha, so the two patches are independent however they
-        // are ordered — and dim lands ahead of the colorspace conversion either way, which is where a
-        // gamma-corrected darken has to be.
+        // The plan's shading, ahead of the dim patch. All three insert above the same anchor, so the later
+        // install runs last, and the order they run in is the order they describe: the shadow and the
+        // occlusion shade the surface, and dimming desaturates the result.
+        applyContactShadow(parameters, effects);
+        applyAmbientOcclusion(parameters, effects);
+        // Dim touches rgb and opacity touches alpha, so the two patches stay independent in any order. Dim
+        // lands ahead of the colorspace conversion either way, which is where a gamma-corrected darken has
+        // to be.
         dimPatch(parameters);
     };
     material.needsUpdate = true;

package/dist/objects/materials/TextureMaterial.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useDimPatch } from './dim';
+import { useDimPatch } from './effects/color-dim';
 import { sharedParams } from './shared';
 /**
  * The material used to render a texture, optionally through a per-instance uv-offset uniform so an

package/dist/objects/materials/effects/ao/ambient-occlusion-pass.d.ts

@@ -0,0 +1,77 @@
+import { type IUniform, Matrix4, type Texture, Vector2, Vector3 } from 'three';
+/** The AO pass's uniforms, as {@link createAoPassUniforms} builds them. */
+export type AoPassUniforms = ReturnType<typeof createAoPassUniforms>;
+/**
+ * Builds one AO pass's uniforms: its own kernel, its own rotation tile, and the matrices and sizes
+ * `OcclusionPasses` refreshes every frame.
+ *
+ * Per mount rather than per module: a `DataTexture` uploads into whichever GL context first draws
+ * with it, and disposal from one mounted scene takes it away from the other. The caller owns the
+ * rotation tile's disposal.
+ *
+ * The frame writes into the matrices and vectors rather than replacing them, so a frame costs no
+ * allocation and no shader recompile.
+ * @returns The uniform record, ready to hand to a `ShaderMaterial`.
+ */
+export declare function createAoPassUniforms(): {
+    /** The prepass's depth. The shader unprojects it per tap. `null` until the first pass runs. */
+    uDepth: IUniform<Texture | null>;
+    /** The rotation tile, which repeats over the target. See {@link createNoiseTexture}. */
+    uNoise: IUniform<Texture>;
+    /** The guard band's projection, which places a view-space tap back on the depth texture. */
+    uProjection: IUniform<Matrix4>;
+    /** Its inverse, which turns a stored depth back into a view position. */
+    uUnprojection: IUniform<Matrix4>;
+    /** One texel of the target in uv, the step the normal reconstruction walks. */
+    uTexel: IUniform<Vector2>;
+    /** The target's size in rotation tiles, so the tile repeats every {@link NOISE_TILE} texels. */
+    uNoiseScale: IUniform<Vector2>;
+    /** How far the kernel reaches, in view units. */
+    uRadius: IUniform<number>;
+    /**
+     * How many of the kernel's offsets to walk, from `1` to {@link AO_TAPS}. `OcclusionPasses`
+     * rewrites it each frame from `AmbientOcclusion.taps`, the way it rewrites the radius.
+     */
+    uTaps: IUniform<number>;
+    /** The hemisphere kernel around `+z`, which the shader rotates per fragment. */
+    uKernel: IUniform<Vector3[]>;
+};
+/** How many taps the kernel holds, which is the AO pass loop's bound and its default count. */
+export declare const AO_TAPS = 16;
+/**
+ * The rotation tile's edge in texels, which is the blur pass's kernel bound and its default side.
+ *
+ * One decision with the blur kernel rather than two: a `4 × 4` tile needs a `4 × 4` kernel to
+ * average out. The GUI reaches a smaller kernel, which trades structured noise for the fetches it
+ * skips.
+ */
+export declare const NOISE_TILE = 4;
+/**
+ * Both full-screen passes' vertex stage: a clip-space quad, the way `Background` draws one.
+ *
+ * `position.xy` of a `2 × 2` plane already spans clip space, so the stage reads no matrix and the
+ * camera means nothing. `z` sits at `0` rather than the far plane, because the passes draw with no
+ * depth test.
+ */
+export declare const AO_VERTEX_SHADER = "\n  varying vec2 vUv;\n\n  void main() {\n    vUv = uv;\n    gl_Position = vec4(position.xy, 0.0, 1.0);\n  }\n";
+/**
+ * The AO pass's fragment stage: a hemisphere-kernel occlusion pass, with the one substitution a
+ * floor plan renderer forces.
+ *
+ * There is no G-buffer. The pass unprojects the fragment's own view position from the prepass
+ * depth, and `normalAt` reconstructs the normal from that same depth.
+ *
+ * Every position and length below sits in view space, which is where three's own lighting works and
+ * where this pass's inverse projection lands. View space looks down `-z`, so a larger `z` is nearer
+ * the camera, and `occlusionTap` compares depths that way.
+ *
+ * The pass writes occlusion, not visibility: `0` is open, `1` is closed, raw and unblurred. A pass
+ * of its own smooths it, see `BLUR_FRAGMENT_SHADER`.
+ *
+ * `AO_BIAS` is the slack that keeps a tap on the fragment's own flat face from reading as an
+ * occluder. It is a share of the radius, so it holds at any zoom. A tap keeps its full value until
+ * the surface it found is a radius away in depth, then falls to nothing. That keeps a wall from
+ * darkening whatever stands far behind it.
+ */
+export declare const AO_FRAGMENT_SHADER = "\n  uniform sampler2D uDepth;\n  uniform sampler2D uNoise;\n  uniform mat4 uProjection;\n  uniform mat4 uUnprojection;\n  uniform vec2 uTexel;\n  uniform vec2 uNoiseScale;\n  uniform float uRadius;\n  uniform int uTaps;\n  uniform vec3 uKernel[16];\n  varying vec2 vUv;\n\n  const float AO_BIAS = 0.02;\n\n  // Where the grazing fade starts and ends, as the absolute dot of the normal against the view\n  // direction: fully faded about seventeen degrees from edge on, fully open by about forty. See the\n  // fade at the end of main.\n  const float AO_GRAZING_MIN = 0.30;\n  const float AO_GRAZING_MAX = 0.64;\n\n  // How far apart the two neighbors of an axis have to be before blendAxis takes the nearer one\n  // outright. Measured as a share of their sum. Larger crosses over more gently and softens a\n  // silhouette. Smaller sharpens the silhouette and brings the normal jump back.\n  const float AO_CROSSOVER = 0.45;\n\n  float depthAt(vec2 uv) {\n    return texture2D(uDepth, uv).x;\n  }\n\n  vec3 viewAt(vec2 uv, float depth) {\n    vec4 clip = vec4(uv * 2. - 1., depth * 2. - 1., 1.);\n    vec4 view = uUnprojection * clip;\n    return view.xyz / view.w;\n  }\n\n  vec3 blendAxis(vec3 back, vec3 forward, float backApart, float forwardApart) {\n    // Positive when the backward neighbor is the worse of the two, which moves the result toward\n    // the forward one. Normalized by the sum, so AO_CROSSOVER is a share rather than a depth.\n    float ratio = (backApart - forwardApart) / max(backApart + forwardApart, 1e-6);\n    return mix(back, forward, smoothstep(-AO_CROSSOVER, AO_CROSSOVER, ratio));\n  }\n\n  vec3 normalAt(vec2 uv, vec3 here, float depth) {\n    vec2 stepX = vec2(uTexel.x, 0.);\n    vec2 stepY = vec2(0., uTexel.y);\n    float left = depthAt(uv - stepX);\n    float right = depthAt(uv + stepX);\n    float down = depthAt(uv - stepY);\n    float up = depthAt(uv + stepY);\n\n    // blendAxis leans toward the neighbor that stays on this surface rather than switching to it. A\n    // hard pick makes a face turned side on jump: both depth differences are large and nearly equal\n    // there, so a small camera rotation crosses the comparison and the normal jumps with it. The\n    // smoothstep over their difference crosses that middle continuously.\n    vec3 alongX = blendAxis(here - viewAt(uv - stepX, left), viewAt(uv + stepX, right) - here,\n                            abs(depth - left), abs(right - depth));\n    vec3 alongY = blendAxis(here - viewAt(uv - stepY, down), viewAt(uv + stepY, up) - here,\n                            abs(depth - down), abs(up - depth));\n\n    vec3 normal = normalize(cross(alongX, alongY));\n    // A surface the camera sees faces the camera, and view space looks down -z. The flip matters in\n    // external mode, where the host's projection can mirror an axis and turn the cross product with\n    // it. The wrong side samples the hemisphere behind the surface.\n    return normal.z < 0. ? -normal : normal;\n  }\n\n  float occlusionTap(vec3 here, vec3 at) {\n    vec4 clip = uProjection * vec4(at, 1.);\n    // At or behind the eye, where the perspective divide has no answer. Orthographic keeps w at 1,\n    // so this costs a comparison there and nothing else.\n    if (clip.w <= 0.) return 0.;\n    vec2 uv = clip.xy / clip.w * .5 + .5;\n    // Screen space sees only what is on screen. A tap off the edge has no depth of its own, and\n    // clamped sampling answers with the border texel's depth, so the tap contributes nothing.\n    if (uv.x < 0. || uv.x > 1. || uv.y < 0. || uv.y > 1.) return 0.;\n    float stored = depthAt(uv);\n    // The prepass clears to the far plane, so a tap over open background lands there. This rejects\n    // that tap rather than darkening an edge.\n    if (stored >= 1.) return 0.;\n    float storedZ = viewAt(uv, stored).z;\n    // Nothing in front of the tap: this surface is open in that direction.\n    if (storedZ < at.z + uRadius * AO_BIAS) return 0.;\n    return smoothstep(0., 1., uRadius / abs(here.z - storedZ));\n  }\n\n  void main() {\n    float depth = depthAt(vUv);\n    // Nothing here, or nothing to reach with. The prepass clears to the far plane. A radius of zero\n    // puts every tap on the fragment itself, where the divide by its distance has no answer.\n    if (depth >= 1. || uRadius <= 0.) {\n      gl_FragColor = vec4(0., 0., 0., 1.);\n      return;\n    }\n\n    vec3 here = viewAt(vUv, depth);\n    vec3 normal = normalAt(vUv, here, depth);\n\n    // The tile's own rotation, turned into a basis around the normal. One kernel becomes a\n    // different kernel per pixel, with no second kernel to upload.\n    vec3 rotation = vec3(texture2D(uNoise, vUv * uNoiseScale).xy, 0.);\n    vec3 tangent = cross(normal, rotation);\n    // Degenerate only where the rotation lies along the normal, which is a wall seen edge on. The\n    // fallback is degenerate only where the normal is the view axis, the case this one covers, so\n    // between them there is always a tangent.\n    if (dot(tangent, tangent) < 1e-6) tangent = cross(normal, vec3(0., 0., 1.));\n    tangent = normalize(tangent);\n    mat3 orient = mat3(tangent, cross(normal, tangent), normal);\n\n    float occluded = 0.;\n    for (int tap = 0; tap < 16; tap++) {\n      // GLSL ES 1.00 on the old Android WebViews this SDK reaches needs a constant loop bound, and\n      // the break is what skips the taps.\n      if (tap >= uTaps) break;\n      occluded += occlusionTap(here, here + orient * uKernel[tap] * uRadius);\n    }\n\n    // The average divides by what the loop walked, not by what the kernel holds. The floor stops a\n    // tap count of zero from dividing by nothing. No control offers zero, and a stale upload can\n    // still hold it.\n    float term = occluded / max(float(uTaps), 1.);\n\n    // The fade drops the term where the surface turns edge on to the camera, because the normal\n    // that oriented this kernel stops being reliable there. A face turned nearly side on gives\n    // normalAt two neighbors that disagree by almost the same amount. A small camera rotation then\n    // still moves the normal, and the term moves with it.\n    //\n    // The fragment sits in view space here, where the camera is the origin, so its own direction is\n    // the view vector. The dot of that against the normal says how square on the surface is: one\n    // face on, zero edge on. Taken as an absolute value, since a normal reconstructed at a depth\n    // discontinuity can come back pointing away.\n    //\n    // An ordinary wall under this plan's camera reads about 0.82 square on at a 55 degree pitch.\n    // That is well clear of the band, so walls keep their full term.\n    float facing = abs(dot(normal, normalize(here)));\n    gl_FragColor = vec4(term * smoothstep(AO_GRAZING_MIN, AO_GRAZING_MAX, facing), 0., 0., 1.);\n  }\n";
+//# sourceMappingURL=ambient-occlusion-pass.d.ts.map