@expofp/renderer 3.34.2 → 3.35.1

package/dist/objects/lighting/occlusion-targets.d.ts

@@ -0,0 +1,143 @@
+import { Vector2, type WebGLRenderer, WebGLRenderTarget } from 'three';
+/**
+ * The three render targets the occlusion passes draw into, over two color textures.
+ *
+ * | Target  | Color texture          | Depth attachment       | Written by | Read by         |
+ * | ------- | ---------------------- | ---------------------- | ---------- | --------------- |
+ * | `depth` | its own, never written | `DepthTexture`, 24-bit | prepass    | nothing         |
+ * | `ao`    | its own                | none                   | AO pass    | the blur pass   |
+ * | `blur`  | the `depth` target's   | none                   | blur pass  | the lit shaders |
+ *
+ * The sharing brings rules, and they live here because this class is the only place that can keep
+ * them.
+ *
+ * A target must not carry a texture that the pass drawing into it samples. WebGL2 calls that a
+ * rendering feedback loop, leaves the result undefined, and browsers refuse the draw. Both the AO
+ * pass and the blur pass sample the prepass depth, so neither one can bind a target that carries it.
+ * That is why two of these three targets carry no depth attachment.
+ *
+ * Three targets over two color textures. The prepass writes depth with `colorWrite` off, so nothing
+ * writes its color attachment and nothing reads it. The blur pass writes what the lit shaders read,
+ * so it takes that attachment. The handover costs one framebuffer and no GL texture at all. three's
+ * `setupRenderTarget` creates a texture only for a target that has none. `RenderTarget` has a
+ * `texture` setter, so this is supported API rather than a reach into internals.
+ *
+ * Two textures and not one, because the blur pass reads the AO pass's output while it writes its own.
+ * One texture for both is the feedback loop above.
+ *
+ * The set costs `1.5` bytes for each canvas pixel: `1.0` for 24-bit depth and `0.25` for each `R8`
+ * color texture, all at a quarter of the canvas area. A `2880 × 1800` canvas therefore holds about
+ * `7.8 MB` of them.
+ *
+ * Never call `setSize`. It calls `dispose()`, and three's deallocation deletes the GL texture of
+ * every entry in `renderTarget.textures`, a shared one included. A size change rebuilds all three
+ * instead.
+ *
+ * Dispose all three together, from here. The first disposal of a shared texture deletes it and
+ * removes its properties, and the second disposal then finds nothing to delete. No one of the three
+ * can outlive the others.
+ *
+ * The completeness check stays, because a required format is no promise that a particular driver
+ * reports the combination complete.
+ */
+export declare class OcclusionTargets {
+    /** The prepass's target, or `null` until this builds a complete set. */
+    private depthTarget;
+    /** The AO pass's target, over a color texture of its own, or `null` beside it. */
+    private aoTarget;
+    /** The blur pass's target, over the prepass's color texture, or `null` beside them. */
+    private blurTarget;
+    /** The set's pixel size, which is the canvas size at {@link CANVAS_FRACTION}. */
+    private readonly targetSize;
+    /** Whether this context cannot give a complete set. Once this turns true it stays true. */
+    private unavailable;
+    /** The prepass's target, or `null` until {@link OcclusionTargets.sync} returns `true`. */
+    get depth(): WebGLRenderTarget | null;
+    /** The AO pass's target, or `null` until {@link OcclusionTargets.sync} returns `true`. */
+    get ao(): WebGLRenderTarget | null;
+    /** The blur pass's target, or `null` until {@link OcclusionTargets.sync} returns `true`. */
+    get blur(): WebGLRenderTarget | null;
+    /** The set's pixel size. Read-only in spirit: the set owns it and rewrites it on a rebuild. */
+    get size(): Vector2;
+    /**
+     * Whether a set is allocated right now.
+     *
+     * A caller frees the set once when the debug GUI switches occlusion off, rather than on every frame
+     * after. This getter tells the caller which frame that is. A flag kept beside the set drifts the
+     * first time a sync fails or a rebuild releases the set on its own.
+     */
+    get held(): boolean;
+    /**
+     * Frees all three targets and the depth texture, and forgets their size.
+     *
+     * This takes no renderer. A `RenderTarget` disposal is an event three's own renderer listens for,
+     * so an unmount effect with nothing else in hand can call it.
+     */
+    dispose(): void;
+    /**
+     * Brings the set to the canvas's current size, and rebuilds it when that size moves.
+     * @param gl - The renderer, for the canvas size and for the completeness check.
+     * @returns Whether a complete set now exists to draw into.
+     */
+    sync(gl: WebGLRenderer): boolean;
+    /**
+     * Allocates the set at a size, at one of the two depth widths.
+     * @param width - The set's width in pixels.
+     * @param height - Its height.
+     * @param depthType - The depth texture's type, which decides its bit width.
+     */
+    private allocate;
+    /**
+     * Rebuilds the set, and falls back to 16-bit depth once before it gives up for good.
+     * @param gl - The renderer, for the completeness check.
+     * @param width - The set's width in pixels.
+     * @param height - Its height.
+     * @returns Whether a complete set now exists.
+     */
+    private build;
+    /**
+     * Frees whatever is allocated, together and in one place, and forgets its size.
+     */
+    private release;
+    /**
+     * Asks the driver whether the two framebuffer combinations this set uses came back complete, once
+     * per allocation.
+     *
+     * Binding each target through three is what builds its framebuffer, so the check runs against the
+     * real thing rather than against an intention. This puts the previously bound target back, which
+     * keeps a shared context unaware that the check ran. The MapLibre embed is that shared context.
+     *
+     * **Two checks cover three targets, because two of the targets are one combination.** The depth
+     * target is a color attachment beside a sampleable depth texture, at whichever of the two widths
+     * `build` is trying, and it is the only one of the three carrying depth at all. That is its own
+     * risk and it takes its own check. The blur target is a single `R8` color attachment over a
+     * texture the depth target already owns. The AO target is that same single `R8` attachment over a
+     * texture of its own, so the blur target covers the AO target's combination and adds the sharing,
+     * which is the part of this design a driver is most likely to refuse. A third bind would ask a
+     * question the second one already answers.
+     *
+     * **three's own renderer never calls `checkFramebufferStatus`**, so this is the only thing that
+     * detects a driver refusing either combination. What it buys is the 16-bit retry and, after that,
+     * occlusion switching itself off, rather than a plan drawing out of an incomplete framebuffer.
+     *
+     * A context that throws while three binds it answers the same question the status code answers, so
+     * this catches the throw. Occlusion switching itself off is the documented outcome. Taking the
+     * frame loop down with it is the worse one.
+     * @param gl - The renderer whose context answers.
+     * @returns Whether both combinations are complete.
+     */
+    private verify;
+}
+/**
+ * The share of the canvas size each axis of the set takes.
+ *
+ * Half, so each pass bills a quarter of the texels a full-size pass bills. Occlusion is a
+ * low-frequency signal. The lit read finds its own fragment by normalized coordinates, so the texel
+ * count behind that read changes nothing anyone can see.
+ *
+ * The canvas size and not the drawing buffer's, which is what `gl.getSize()` reports. A device pixel
+ * ratio of `2` squares into four times the texels, and both passes bill per texel. A set sized from
+ * the buffer therefore costs four times as much on a retina screen, for detail nothing asks of it.
+ */
+export declare const CANVAS_FRACTION = 0.5;
+//# sourceMappingURL=occlusion-targets.d.ts.map

package/dist/objects/lighting/occlusion-targets.js

@@ -0,0 +1,276 @@
+import { DepthTexture, NearestFilter, RedFormat, UnsignedByteType, UnsignedIntType, UnsignedShortType, Vector2, WebGLRenderTarget, } from 'three';
+import { createLogger } from '../../utils/logging';
+const logger = createLogger('occlusion');
+/**
+ * The three render targets the occlusion passes draw into, over two color textures.
+ *
+ * | Target  | Color texture          | Depth attachment       | Written by | Read by         |
+ * | ------- | ---------------------- | ---------------------- | ---------- | --------------- |
+ * | `depth` | its own, never written | `DepthTexture`, 24-bit | prepass    | nothing         |
+ * | `ao`    | its own                | none                   | AO pass    | the blur pass   |
+ * | `blur`  | the `depth` target's   | none                   | blur pass  | the lit shaders |
+ *
+ * The sharing brings rules, and they live here because this class is the only place that can keep
+ * them.
+ *
+ * A target must not carry a texture that the pass drawing into it samples. WebGL2 calls that a
+ * rendering feedback loop, leaves the result undefined, and browsers refuse the draw. Both the AO
+ * pass and the blur pass sample the prepass depth, so neither one can bind a target that carries it.
+ * That is why two of these three targets carry no depth attachment.
+ *
+ * Three targets over two color textures. The prepass writes depth with `colorWrite` off, so nothing
+ * writes its color attachment and nothing reads it. The blur pass writes what the lit shaders read,
+ * so it takes that attachment. The handover costs one framebuffer and no GL texture at all. three's
+ * `setupRenderTarget` creates a texture only for a target that has none. `RenderTarget` has a
+ * `texture` setter, so this is supported API rather than a reach into internals.
+ *
+ * Two textures and not one, because the blur pass reads the AO pass's output while it writes its own.
+ * One texture for both is the feedback loop above.
+ *
+ * The set costs `1.5` bytes for each canvas pixel: `1.0` for 24-bit depth and `0.25` for each `R8`
+ * color texture, all at a quarter of the canvas area. A `2880 × 1800` canvas therefore holds about
+ * `7.8 MB` of them.
+ *
+ * Never call `setSize`. It calls `dispose()`, and three's deallocation deletes the GL texture of
+ * every entry in `renderTarget.textures`, a shared one included. A size change rebuilds all three
+ * instead.
+ *
+ * Dispose all three together, from here. The first disposal of a shared texture deletes it and
+ * removes its properties, and the second disposal then finds nothing to delete. No one of the three
+ * can outlive the others.
+ *
+ * The completeness check stays, because a required format is no promise that a particular driver
+ * reports the combination complete.
+ */
+export class OcclusionTargets {
+    /** The prepass's target, or `null` until this builds a complete set. */
+    depthTarget = null;
+    /** The AO pass's target, over a color texture of its own, or `null` beside it. */
+    aoTarget = null;
+    /** The blur pass's target, over the prepass's color texture, or `null` beside them. */
+    blurTarget = null;
+    /** The set's pixel size, which is the canvas size at {@link CANVAS_FRACTION}. */
+    targetSize = new Vector2();
+    /** Whether this context cannot give a complete set. Once this turns true it stays true. */
+    unavailable = false;
+    /** The prepass's target, or `null` until {@link OcclusionTargets.sync} returns `true`. */
+    get depth() {
+        return this.depthTarget;
+    }
+    /** The AO pass's target, or `null` until {@link OcclusionTargets.sync} returns `true`. */
+    get ao() {
+        return this.aoTarget;
+    }
+    /** The blur pass's target, or `null` until {@link OcclusionTargets.sync} returns `true`. */
+    get blur() {
+        return this.blurTarget;
+    }
+    /** The set's pixel size. Read-only in spirit: the set owns it and rewrites it on a rebuild. */
+    get size() {
+        return this.targetSize;
+    }
+    /**
+     * Whether a set is allocated right now.
+     *
+     * A caller frees the set once when the debug GUI switches occlusion off, rather than on every frame
+     * after. This getter tells the caller which frame that is. A flag kept beside the set drifts the
+     * first time a sync fails or a rebuild releases the set on its own.
+     */
+    get held() {
+        return this.depthTarget !== null;
+    }
+    /**
+     * Frees all three targets and the depth texture, and forgets their size.
+     *
+     * This takes no renderer. A `RenderTarget` disposal is an event three's own renderer listens for,
+     * so an unmount effect with nothing else in hand can call it.
+     */
+    dispose() {
+        this.release();
+    }
+    /**
+     * Brings the set to the canvas's current size, and rebuilds it when that size moves.
+     * @param gl - The renderer, for the canvas size and for the completeness check.
+     * @returns Whether a complete set now exists to draw into.
+     */
+    sync(gl) {
+        if (this.unavailable)
+            return false;
+        const canvas = gl.getSize(_canvas);
+        const width = Math.floor(canvas.x * CANVAS_FRACTION);
+        const height = Math.floor(canvas.y * CANVAS_FRACTION);
+        // A canvas with no area yet, during a layout or before one. The next resize can undo that, so
+        // this is no reason to give up for good.
+        if (width < 1 || height < 1)
+            return false;
+        if (this.depthTarget && this.targetSize.x === width && this.targetSize.y === height) {
+            return true;
+        }
+        return this.build(gl, width, height);
+    }
+    /**
+     * Allocates the set at a size, at one of the two depth widths.
+     * @param width - The set's width in pixels.
+     * @param height - Its height.
+     * @param depthType - The depth texture's type, which decides its bit width.
+     */
+    allocate(width, height, depthType) {
+        this.depthTarget = new WebGLRenderTarget(width, height, {
+            ...SINGLE_CHANNEL_TEXTURE,
+            depthBuffer: true,
+            depthTexture: new DepthTexture(width, height, depthType),
+        });
+        this.aoTarget = new WebGLRenderTarget(width, height, {
+            ...SINGLE_CHANNEL_TEXTURE,
+            depthBuffer: false,
+        });
+        // No format of its own. The next line drops the texture this target is built with, so the
+        // missing depth attachment is the only option that outlives the constructor.
+        this.blurTarget = new WebGLRenderTarget(width, height, { depthBuffer: false });
+        // The sharing, in one line. `RenderTarget` has a `texture` setter, so this is supported API
+        // rather than a reach into internals. This drops the target's own fresh texture, which never
+        // uploaded. Nothing writes the prepass's color attachment and nothing reads it, so the blur pass
+        // can take it.
+        this.blurTarget.texture = this.depthTarget.texture;
+        this.targetSize.set(width, height);
+    }
+    /**
+     * Rebuilds the set, and falls back to 16-bit depth once before it gives up for good.
+     * @param gl - The renderer, for the completeness check.
+     * @param width - The set's width in pixels.
+     * @param height - Its height.
+     * @returns Whether a complete set now exists.
+     */
+    build(gl, width, height) {
+        this.release();
+        for (const depthType of DEPTH_TYPES) {
+            this.allocate(width, height, depthType);
+            if (this.verify(gl))
+                return true;
+            this.release();
+        }
+        // Off for good, and silent as far as a caller can tell. The SDK runs in old Android WebViews,
+        // and nobody can do anything about a driver that will not report these targets complete. The
+        // debug log is for whoever has to find out why a plan shipped without occlusion.
+        logger.debug('ambient occlusion off: this context gives no complete render targets');
+        this.unavailable = true;
+        return false;
+    }
+    /**
+     * Frees whatever is allocated, together and in one place, and forgets its size.
+     */
+    release() {
+        // The order does not matter. The first disposal of the shared texture deletes it and removes its
+        // properties, and the second one finds nothing left to delete. All three still have to happen.
+        // The AO target's own texture belongs to nobody else, so either order deletes it once.
+        this.depthTarget?.dispose();
+        this.aoTarget?.dispose();
+        this.blurTarget?.dispose();
+        this.depthTarget?.depthTexture?.dispose();
+        this.depthTarget = null;
+        this.aoTarget = null;
+        this.blurTarget = null;
+        this.targetSize.set(0, 0);
+    }
+    /**
+     * Asks the driver whether the two framebuffer combinations this set uses came back complete, once
+     * per allocation.
+     *
+     * Binding each target through three is what builds its framebuffer, so the check runs against the
+     * real thing rather than against an intention. This puts the previously bound target back, which
+     * keeps a shared context unaware that the check ran. The MapLibre embed is that shared context.
+     *
+     * **Two checks cover three targets, because two of the targets are one combination.** The depth
+     * target is a color attachment beside a sampleable depth texture, at whichever of the two widths
+     * `build` is trying, and it is the only one of the three carrying depth at all. That is its own
+     * risk and it takes its own check. The blur target is a single `R8` color attachment over a
+     * texture the depth target already owns. The AO target is that same single `R8` attachment over a
+     * texture of its own, so the blur target covers the AO target's combination and adds the sharing,
+     * which is the part of this design a driver is most likely to refuse. A third bind would ask a
+     * question the second one already answers.
+     *
+     * **three's own renderer never calls `checkFramebufferStatus`**, so this is the only thing that
+     * detects a driver refusing either combination. What it buys is the 16-bit retry and, after that,
+     * occlusion switching itself off, rather than a plan drawing out of an incomplete framebuffer.
+     *
+     * A context that throws while three binds it answers the same question the status code answers, so
+     * this catches the throw. Occlusion switching itself off is the documented outcome. Taking the
+     * frame loop down with it is the worse one.
+     * @param gl - The renderer whose context answers.
+     * @returns Whether both combinations are complete.
+     */
+    verify(gl) {
+        const context = webgl2(gl);
+        if (!context)
+            return false;
+        const previous = gl.getRenderTarget();
+        try {
+            let complete = true;
+            for (const target of [this.depthTarget, this.blurTarget]) {
+                gl.setRenderTarget(target);
+                if (context.checkFramebufferStatus(context.FRAMEBUFFER) !== context.FRAMEBUFFER_COMPLETE) {
+                    complete = false;
+                }
+            }
+            return complete;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            gl.setRenderTarget(previous);
+        }
+    }
+}
+/**
+ * The renderer's context, when it is one these targets can be built on.
+ *
+ * A runtime feature detection, and not a type narrowing a reader can drop. The SDK still runs in
+ * WebViews whose context can be neither WebGL2 nor able to carry a readable depth texture. The
+ * constructor itself can be missing, so this checks for it before it uses it.
+ * @param gl - The renderer to read.
+ * @returns The context, or `undefined` when the targets cannot be built on it.
+ */
+function webgl2(gl) {
+    const context = gl.getContext();
+    if (typeof WebGL2RenderingContext !== 'function')
+        return undefined;
+    return context instanceof WebGL2RenderingContext ? context : undefined;
+}
+/**
+ * The share of the canvas size each axis of the set takes.
+ *
+ * Half, so each pass bills a quarter of the texels a full-size pass bills. Occlusion is a
+ * low-frequency signal. The lit read finds its own fragment by normalized coordinates, so the texel
+ * count behind that read changes nothing anyone can see.
+ *
+ * The canvas size and not the drawing buffer's, which is what `gl.getSize()` reports. A device pixel
+ * ratio of `2` squares into four times the texels, and both passes bill per texel. A set sized from
+ * the buffer therefore costs four times as much on a retina screen, for detail nothing asks of it.
+ */
+export const CANVAS_FRACTION = 0.5;
+/**
+ * The depth widths this tries, in order.
+ *
+ * 24 bits first, because 16-bit depth at this size over a plan's range bands visibly in the
+ * occlusion. 16 bits is the one retry worth making before occlusion latches off for good. It saves
+ * memory rather than costing it, which makes it a fallback rather than a default.
+ */
+const DEPTH_TYPES = [UnsignedIntType, UnsignedShortType];
+/**
+ * The shared settings for the two color textures the occlusion passes draw into.
+ *
+ * `R8` holds one byte a texel. It is a color-renderable sized internal format in WebGL 2, so it is
+ * required to work rather than merely likely to.
+ *
+ * Both the blur pass and the lit read weight their samples by depth, so hardware filtering only
+ * smears occlusion across the edges those reads respect.
+ */
+const SINGLE_CHANNEL_TEXTURE = {
+    format: RedFormat,
+    type: UnsignedByteType,
+    minFilter: NearestFilter,
+    magFilter: NearestFilter,
+};
+/** Scratch for the canvas size, read once per sync. */
+const _canvas = new Vector2();

package/dist/objects/lines/Lines.js

@@ -17,6 +17,8 @@ import { LineInstance } from './LineInstance';
  */
 export function Lines(props) {
     const { defs } = props;
+    // Only the instances are staged; the container is sized and ordered from the whole membership.
+    const mounted = props.mounted ?? defs.length;
     // Sized from the first render's defs; membership changes grow the batch in place, never rebuild
     // it. The container is bookkeeping only, so the copy StrictMode's double-invoked initializer
     // discards is plain garbage.
@@ -25,5 +27,5 @@ export function Lines(props) {
     // claimed slot — it is a frozen snapshot, so that never happens. The `ref` arrow is
     // deliberate: `ref={container.bind}` would make the React Compiler infer `container` itself as a
     // ref and reject its render-time reads.
-    return (_jsxs(_Fragment, { children: [_jsx(BatchedLines, { args: container.args, ref: (mesh) => container.bind(mesh), customSort: container.customSort, children: _jsx(LineMaterial, {}) }), defs.map((def) => (_jsx(LineInstance, { def: def, container: container }, defKey(def))))] }));
+    return (_jsxs(_Fragment, { children: [_jsx(BatchedLines, { args: container.args, ref: (mesh) => container.bind(mesh), customSort: container.customSort, children: _jsx(LineMaterial, {}) }), defs.slice(0, mounted).map((def) => (_jsx(LineInstance, { def: def, container: container }, defKey(def))))] }));
 }

package/dist/objects/lines/line-container.d.ts

@@ -1,5 +1,5 @@
-import { type InstancedMeshExtParams } from '../../core/instanced/InstancedMesh';
-import { type BatchedLinesExt } from '../../core/lines/BatchedLines';
+import { type InstancedMeshImplParams } from '../../core/instanced/InstancedMesh';
+import { type BatchedLinesImpl } from '../../core/lines/BatchedLines';
 import { type LineDef } from '../../types/defs';
 import { SlotContainer } from '../containers';
 /**
@@ -10,7 +10,7 @@ import { SlotContainer } from '../containers';
  * Only the options: the batch builds its own segment template and takes its material from the
  * `<LineMaterial>` child R3F mounts under it.
  */
-export type LineMeshArgs = [params: InstancedMeshExtParams];
+export type LineMeshArgs = [params: InstancedMeshImplParams];
 /**
  * One line layer's bookkeeping.
  *
@@ -19,7 +19,7 @@ export type LineMeshArgs = [params: InstancedMeshExtParams];
  * endpoints. That is why the resource type is `null` here: nothing about a `LineDef` can force a
  * re-claim, so a def keeps its slot for as long as it is mounted, `points` included.
  */
-export declare class LineContainer extends SlotContainer<null, BatchedLinesExt, LineDef> {
+export declare class LineContainer extends SlotContainer<null, BatchedLinesImpl, LineDef> {
     /** The constructor args R3F builds the batch from; a frozen snapshot, never mutated. */
     readonly args: LineMeshArgs;
     /**

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

@@ -4,80 +4,87 @@ export interface ColorMaterialProps {
     /** Base color. Defaults to white, which is what a per-instance tint multiplies against. */
     color?: ColorRepresentation;
     /**
-     * Whether this batch draws **volumes** — meshes carrying real z, which need shading to read as
-     * solid and depth testing to occlude themselves and each other. Defaults to `false`, the flat
-     * content that is every 2D primitive in a plan.
+     * Whether this batch draws volumes, which are the meshes carrying real z. A volume needs shading
+     * to read as solid, and depth testing to occlude itself and its neighbors. Defaults to `false`,
+     * which is the flat content every 2D primitive in a plan draws as.
      */
     solid?: boolean;
     /**
-     * Whether those volumes are translucent, which moves them into three's transparent pass. Only
-     * meaningful together with {@link solid}; flat content never uses it (see the note below on why 2D
-     * stays in the opaque list).
+     * Whether those volumes are translucent, which moves them into three's transparent pass.
+     *
+     * This means something only together with {@link solid}. Flat content never uses it, for the reason
+     * the note below gives.
      */
     translucent?: boolean;
     /**
-     * Runs on the shader before the dim patch does — the slot for a caller's own shader surgery,
-     * like the background quad's clip-space projection and its dim-uniform stand-in. Captured at
-     * first render and fixed for the material's lifetime, like every other axis of this component:
-     * a changing handler identity would risk a recompile per render.
+     * Runs on the shader before the dim patch runs. This is the slot for a caller's own shader surgery,
+     * such as the background quad's clip-space projection and its dim-uniform stand-in.
+     *
+     * This component captures the handler at the first render and keeps it for the material's lifetime,
+     * the way it keeps every other axis. A handler identity that changes risks a recompile per render.
      */
     onBeforeCompile?: (parameters: WebGLProgramParametersWithUniforms) => void;
 }
 /**
- * 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.
  */