@expofp/renderer 3.34.2 → 3.35.1

package/dist/Renderer.d.ts

@@ -2,6 +2,7 @@ import { type Box } from '@expofp/geometry';
 import { type HTMLAttributes, type ReactNode, type Ref } from 'react';
 import { type ControlsConfig } from './controls';
 import { type ExternalCanvasProps } from './external/ExternalCanvas';
+import { type LightingProps } from './objects/lighting';
 import { type CameraProps } from './space/Camera';
 import { type SceneDef } from './types/defs';
 import { type PointerMissedEventData } from './types/events';
@@ -60,6 +61,19 @@ export interface RendererProps extends HTMLAttributes<HTMLDivElement>, CameraPro
      * without taking a gesture away.
      */
     controls?: ControlsConfig;
+    /**
+     * The scene's lighting, and the darkening that rides with it: the rig's contrast and three
+     * colors, and a `shadow` object holding the shade both darkening terms blend toward and each
+     * term's own numbers. See {@link LightingProps}.
+     *
+     * Every value is optional and every omitted one keeps the design's own default, so a caller sets
+     * the one number a plan needs and nothing else. Where the key light points is not here: that is
+     * the design's decision, and the debug GUI keeps it.
+     *
+     * Changing a value moves a mounted scene with no remount and no shader recompile. It lands on a
+     * uniform or on a field the frame reads, and asks for a redraw.
+     */
+    lighting?: LightingProps;
     /**
      * The part of the canvas the plan should be framed inside, in css pixels from its top-left
      * corner — for a host whose own header, sheet or panel covers the rest.

package/dist/Renderer.js

@@ -24,12 +24,12 @@ export function Renderer(props) {
     // attributes — which is what React warns about, and the reason every member of `CameraProps` has
     // to be named here as well as reassembled below. They are passed on untouched: what an omitted
     // one means is `Camera`'s to say, and it is the only place that says it.
-    const { debug, scene, memoryLimit, minZoom, maxZoom, minPitch, maxPitch, bounds, smoothTime, controls, visibleRect, onPointerMissed, gl, requestFrame, onFrame, children, ...canvasProps } = props;
+    const { debug, scene, memoryLimit, minZoom, maxZoom, minPitch, maxPitch, bounds, smoothTime, controls, lighting, visibleRect, onPointerMissed, gl, requestFrame, onFrame, children, ...canvasProps } = props;
     const cameraProps = { minZoom, maxZoom, minPitch, maxPitch, bounds, smoothTime };
     const external = gl !== undefined;
     // The one tree, whichever canvas it lands on. The mount decides nothing about it; the tree
     // leaves out what external mode has no object for — the controls here, the camera inside Scene.
-    const tree = (_jsx(DebugOverlay, { enabled: debug, children: _jsxs(Scene, { sceneDef: scene, external: external, memoryLimit: memoryLimit, visibleRect: visibleRect, ...cameraProps, children: [!external && _jsx(Controls, { config: controls }), _jsx(PointerMissed, { onPointerMissed: onPointerMissed }), children] }) }));
+    const tree = (_jsx(DebugOverlay, { enabled: debug, children: _jsxs(Scene, { sceneDef: scene, external: external, memoryLimit: memoryLimit, lighting: lighting, visibleRect: visibleRect, ...cameraProps, children: [!external && _jsx(Controls, { config: controls }), _jsx(PointerMissed, { onPointerMissed: onPointerMissed }), children] }) }));
     // The host's context arriving is what selects external mode. The mount swap is an element-type
     // change, so flipping modes at runtime remounts — like `debug`, both are fixed for a renderer's
     // lifetime in practice.
@@ -43,11 +43,23 @@ export function Renderer(props) {
         return (_jsx(ExternalCanvas, { gl: gl, requestFrame: requestFrame, onFrame: onFrame, children: tree }));
     }
     return (_jsx(StrictMode, { children: _jsx(Suspense, { fallback: null, children: _jsx(CanvasWithDebug, { ...canvasProps, debugEnabled: debug, 
-                // Tonemapping off: plan colors are authored values, not scene-referred light.
+                // R3F force-writes ACES filmic tone mapping onto a fresh renderer unless `flat` is set,
+                // which lands it on three's own default, `NoToneMapping`, instead. This renderer does not
+                // tone map: `Lighting` keeps the rig's light sum in range by construction, rather than
+                // compressing an unbounded one back into range afterward.
                 flat: true, 
                 // three leaves the stencil buffer off by default. Line layers need one: it is how they keep
                 // translucent lines from darkening where they overlap (see `LineMaterial`), and without the
                 // buffer the stencil settings silently do nothing. In the MapLibre embed the context is the
                 // map's own, which already has one.
-                gl: { stencil: true }, frameloop: debug ? 'always' : 'demand', resize: { debounce: 50 }, children: tree }) }) }));
+                gl: { stencil: true }, 
+                // three reads a program's info log straight after linking it, and that read blocks until
+                // the driver has finished linking. Left to itself the driver links in the background,
+                // because `KHR_parallel_shader_compile` is there, so the check is the whole of what makes
+                // a compile synchronous: 17 programs cost 64 ms of main thread on a large scene, in
+                // blocks of up to 12 ms, and they land in the frames where the layers are still mounting.
+                // Debug keeps the check, because a broken shader has to report itself somewhere.
+                onCreated: (state) => {
+                    state.gl.debug.checkShaderErrors = debug ?? false;
+                }, frameloop: debug ? 'always' : 'demand', resize: { debounce: 50 }, children: tree }) }) }));
 }

package/dist/core/SquareDataTexture.d.ts

@@ -91,8 +91,8 @@ export declare function getSquareTextureInfo(arrayType: TypedArrayConstructor, c
  * 2. **The index varying is always `float`**, so `getUniformsGLSL` no longer takes an index type.
  *    It follows from the first: GLSL ES 3.00 requires integer varyings to be `flat`, so an index
  *    that is not float could not have the qualifier removed. **Callers must therefore hand it a float
- *    index** — `BatchedMeshExt` does, from three's own `getIndirectIndex( gl_DrawID )`, and
- *    `InstancedMeshExt` does, from the float index texture that replaced upstream's `uint` attribute.
+ *    index** — `BatchedMeshImpl` does, from three's own `getIndirectIndex( gl_DrawID )`, and
+ *    `InstancedMeshImpl` does, from the float index texture that replaced upstream's `uint` attribute.
  * 3. **`clone` and `copy` produce an independent texture.** See each method.
  */
 export declare class SquareDataTexture extends DataTexture {

package/dist/core/SquareDataTexture.js

@@ -68,8 +68,8 @@ export function getSquareTextureInfo(arrayType, channels, pixelsPerInstance, cap
  * 2. **The index varying is always `float`**, so `getUniformsGLSL` no longer takes an index type.
  *    It follows from the first: GLSL ES 3.00 requires integer varyings to be `flat`, so an index
  *    that is not float could not have the qualifier removed. **Callers must therefore hand it a float
- *    index** — `BatchedMeshExt` does, from three's own `getIndirectIndex( gl_DrawID )`, and
- *    `InstancedMeshExt` does, from the float index texture that replaced upstream's `uint` attribute.
+ *    index** — `BatchedMeshImpl` does, from three's own `getIndirectIndex( gl_DrawID )`, and
+ *    `InstancedMeshImpl` does, from the float index texture that replaced upstream's `uint` attribute.
  * 3. **`clone` and `copy` produce an independent texture.** See each method.
  */
 export class SquareDataTexture extends DataTexture {

package/dist/core/batch/BatchedMesh.d.ts

@@ -19,8 +19,8 @@ import { type UniformValue, type UniformValueObj } from '../SquareDataTexture';
  * - **Bounds invalidate themselves.** Every mutation that can move the mesh's extents nulls the
  *   cached bounds, so callers cannot forget; three's frustum test recomputes a null one on demand.
  */
-export declare class BatchedMeshExt extends BatchedMeshBase {
-    /** Per-instance uniform store, shared with {@link InstancedMeshExt}. */
+export declare class BatchedMeshImpl extends BatchedMeshBase {
+    /** Per-instance uniform store, shared with {@link InstancedMeshImpl}. */
     private readonly uniforms;
     /** The material whose `onBeforeCompile` is already wrapped, so it is wrapped exactly once. */
     private patchedMaterial;
@@ -70,5 +70,5 @@ export declare class BatchedMeshExt extends BatchedMeshBase {
  * Registers the class as an R3F element, by value so the generated key cannot collide with the
  * `BatchedMesh` three already puts in the catalog when the canvas mounts.
  */
-export declare const BatchedMesh: import("react").ExoticComponent<import("@react-three/fiber/dist/declarations/src/core/utils").Mutable<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<Partial<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<BatchedMeshExt, import("@react-three/fiber").MathProps<BatchedMeshExt> & import("@react-three/fiber").ReactProps<BatchedMeshExt> & Partial<import("@react-three/fiber").EventHandlers>>>, Omit<import("@react-three/fiber").InstanceProps<BatchedMeshExt, typeof BatchedMeshExt>, "object">>>>;
+export declare const BatchedMesh: import("react").ExoticComponent<import("@react-three/fiber/dist/declarations/src/core/utils").Mutable<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<Partial<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<BatchedMeshImpl, import("@react-three/fiber").MathProps<BatchedMeshImpl> & import("@react-three/fiber").ReactProps<BatchedMeshImpl> & Partial<import("@react-three/fiber").EventHandlers>>>, Omit<import("@react-three/fiber").InstanceProps<BatchedMeshImpl, typeof BatchedMeshImpl>, "object">>>>;
 //# sourceMappingURL=BatchedMesh.d.ts.map

package/dist/core/batch/BatchedMesh.js

@@ -20,8 +20,8 @@ import { openMain } from '../shader-source';
  * - **Bounds invalidate themselves.** Every mutation that can move the mesh's extents nulls the
  *   cached bounds, so callers cannot forget; three's frustum test recomputes a null one on demand.
  */
-export class BatchedMeshExt extends BatchedMeshBase {
-    /** Per-instance uniform store, shared with {@link InstancedMeshExt}. */
+export class BatchedMeshImpl extends BatchedMeshBase {
+    /** Per-instance uniform store, shared with {@link InstancedMeshImpl}. */
     uniforms = new InstanceUniforms();
     /** The material whose `onBeforeCompile` is already wrapped, so it is wrapped exactly once. */
     patchedMaterial = null;
@@ -146,4 +146,4 @@ export class BatchedMeshExt extends BatchedMeshBase {
  * Registers the class as an R3F element, by value so the generated key cannot collide with the
  * `BatchedMesh` three already puts in the catalog when the canvas mounts.
  */
-export const BatchedMesh = extend(BatchedMeshExt);
+export const BatchedMesh = extend(BatchedMeshImpl);

package/dist/core/instanced/InstancedMesh.d.ts

@@ -3,8 +3,8 @@ import { type UniformSchemaShader } from '../InstanceUniforms';
 import { type UniformValue, type UniformValueObj } from '../SquareDataTexture';
 import { FrustumCulling } from './FrustumCulling';
 import { Raycasting } from './Raycasting';
-/** Constructor options for {@link InstancedMeshExt}. */
-export interface InstancedMeshExtParams {
+/** Constructor options for {@link InstancedMeshImpl}. */
+export interface InstancedMeshImplParams {
     /** Initial instance capacity; the buffers grow past it on demand. */
     capacity?: number;
 }
@@ -34,10 +34,10 @@ export type CustomSortFn = (list: InstancedRenderItem[]) => void;
  * - **Batched-style texture handling.** The data textures bind as ordinary shader uniforms and
  *   flush through {@link SquareDataTexture.update}, so there is no manual texture-unit binding,
  *   `updateTextures`/`bindTextures` split, or `PropertiesOverride` — the vendored texture already
- *   works this way for `BatchedMeshExt`.
+ *   works this way for `BatchedMeshImpl`.
  * - **The draw list is a texture, not a vertex attribute.** Upstream stamps a `uint` index attribute
  *   onto whatever geometry it is handed; this fetches the instance id by `gl_InstanceID` from a texture of
- *   its own, the way `BatchedMeshExt` resolves `gl_DrawID`. So the mesh never writes to a geometry it
+ *   its own, the way `BatchedMeshImpl` resolves `gl_DrawID`. So the mesh never writes to a geometry it
  *   does not own — several may draw one cached geometry — and the cull list flushes through
  *   {@link SquareDataTexture.update} in `onBeforeRender` like every other per-instance buffer, rather
  *   than needing an attribute that owns its GL buffer to beat three's upload in `projectObject`. It
@@ -53,7 +53,7 @@ export type CustomSortFn = (list: InstancedRenderItem[]) => void;
  *
  * Render it with {@link InstancedMesh}.
  */
-export declare class InstancedMeshExt extends Mesh<BufferGeometry, Material | Material[], Object3DEventMap & {
+export declare class InstancedMeshImpl extends Mesh<BufferGeometry, Material | Material[], Object3DEventMap & {
     dispose: object;
 }> {
     /**
@@ -110,7 +110,7 @@ export declare class InstancedMeshExt extends Mesh<BufferGeometry, Material | Ma
     private drawList;
     /** Puts back what {@link patchInstancedMaterial} wrapped; null between draws. */
     private _unpatchMaterial;
-    constructor(params?: InstancedMeshExtParams);
+    constructor(params?: InstancedMeshImplParams);
     /**
      * The instance capacity the textures currently hold.
      */
@@ -298,5 +298,5 @@ export declare class InstancedMeshExt extends Mesh<BufferGeometry, Material | Ma
  * Registers the class as an R3F element, by value so the generated key cannot collide with the
  * `InstancedMesh` three already puts in the catalog when the canvas mounts.
  */
-export declare const InstancedMesh: import("react").ExoticComponent<import("@react-three/fiber/dist/declarations/src/core/utils").Mutable<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<Partial<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<InstancedMeshExt, import("@react-three/fiber").MathProps<InstancedMeshExt> & import("@react-three/fiber").ReactProps<InstancedMeshExt> & Partial<import("@react-three/fiber").EventHandlers>>>, Omit<import("@react-three/fiber").InstanceProps<InstancedMeshExt, typeof InstancedMeshExt>, "object">>>>;
+export declare const InstancedMesh: import("react").ExoticComponent<import("@react-three/fiber/dist/declarations/src/core/utils").Mutable<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<Partial<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<InstancedMeshImpl, import("@react-three/fiber").MathProps<InstancedMeshImpl> & import("@react-three/fiber").ReactProps<InstancedMeshImpl> & Partial<import("@react-three/fiber").EventHandlers>>>, Omit<import("@react-three/fiber").InstanceProps<InstancedMeshImpl, typeof InstancedMeshImpl>, "object">>>>;
 //# sourceMappingURL=InstancedMesh.d.ts.map

package/dist/core/instanced/InstancedMesh.js

@@ -26,10 +26,10 @@ patchInstancedShaderChunks();
  * - **Batched-style texture handling.** The data textures bind as ordinary shader uniforms and
  *   flush through {@link SquareDataTexture.update}, so there is no manual texture-unit binding,
  *   `updateTextures`/`bindTextures` split, or `PropertiesOverride` — the vendored texture already
- *   works this way for `BatchedMeshExt`.
+ *   works this way for `BatchedMeshImpl`.
  * - **The draw list is a texture, not a vertex attribute.** Upstream stamps a `uint` index attribute
  *   onto whatever geometry it is handed; this fetches the instance id by `gl_InstanceID` from a texture of
- *   its own, the way `BatchedMeshExt` resolves `gl_DrawID`. So the mesh never writes to a geometry it
+ *   its own, the way `BatchedMeshImpl` resolves `gl_DrawID`. So the mesh never writes to a geometry it
  *   does not own — several may draw one cached geometry — and the cull list flushes through
  *   {@link SquareDataTexture.update} in `onBeforeRender` like every other per-instance buffer, rather
  *   than needing an attribute that owns its GL buffer to beat three's upload in `projectObject`. It
@@ -45,7 +45,7 @@ patchInstancedShaderChunks();
  *
  * Render it with {@link InstancedMesh}.
  */
-export class InstancedMeshExt extends Mesh {
+export class InstancedMeshImpl extends Mesh {
     /**
      * The number of instances rendered in the last frame.
      * @default 0
@@ -489,7 +489,7 @@ export class InstancedMeshExt extends Mesh {
  * Registers the class as an R3F element, by value so the generated key cannot collide with the
  * `InstancedMesh` three already puts in the catalog when the canvas mounts.
  */
-export const InstancedMesh = extend(InstancedMeshExt);
+export const InstancedMesh = extend(InstancedMeshImpl);
 const DEFAULT_CAPACITY = 1000;
 const _matrix = new Matrix4();
 const _color = new Color();

package/dist/core/instanced/instanced-material.js

@@ -55,7 +55,7 @@ const INSTANCED_DECLARATIONS = /* glsl */ `
  * The matrix is declared here rather than where the transform chunks use it, so it lands in `main`
  * whether or not the material includes those chunks. It shadows the `attribute mat4 instanceMatrix`
  * three declares for any `isInstancedMesh` object — which is what the placeholder attribute on
- * `InstancedMeshExt` exists to satisfy — and a material doing its own transform simply never reads
+ * `InstancedMeshImpl` exists to satisfy — and a material doing its own transform simply never reads
  * it.
  */
 const INSTANCED_RESOLVE = /* glsl */ `

package/dist/core/lines/BatchedLines.d.ts

@@ -1,7 +1,7 @@
 import { type Box3, type BufferGeometry, type Camera, type Group, type Material, type Scene, type Sphere, Vector3, type Vector3Like, type WebGLRenderer } from 'three';
 import { LineMaterial } from 'three/addons/lines/LineMaterial.js';
 import { LineSegmentsGeometry } from 'three/addons/lines/LineSegmentsGeometry.js';
-import { InstancedMeshExt, type InstancedMeshExtParams } from '../instanced/InstancedMesh';
+import { InstancedMeshImpl, type InstancedMeshImplParams } from '../instanced/InstancedMesh';
 import { FrustumCulling } from './FrustumCulling';
 import { Raycasting } from './Raycasting';
 /**
@@ -31,7 +31,7 @@ import { Raycasting } from './Raycasting';
  *
  * Render it with {@link BatchedLines}.
  */
-export declare class BatchedLinesExt extends InstancedMeshExt {
+export declare class BatchedLinesImpl extends InstancedMeshImpl {
     /**
      * The segment template every member is drawn from, and the whole of what the geometry carries: the
      * per-instance data three would put in instanced attributes is in the uniforms instead.
@@ -58,7 +58,7 @@ export declare class BatchedLinesExt extends InstancedMeshExt {
     /**
      * @param params - Instance capacity; the buffers grow past it on demand.
      */
-    constructor(params?: InstancedMeshExtParams);
+    constructor(params?: InstancedMeshImplParams);
     /**
      * Reads a member's endpoints.
      * @param id - The member to read.
@@ -131,5 +131,5 @@ export declare class BatchedLinesExt extends InstancedMeshExt {
  * Registers the class as an R3F element, by value so the generated key cannot collide with anything
  * three puts in the catalog when the canvas mounts.
  */
-export declare const BatchedLines: import("react").ExoticComponent<import("@react-three/fiber/dist/declarations/src/core/utils").Mutable<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<Partial<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<BatchedLinesExt, import("@react-three/fiber").MathProps<BatchedLinesExt> & import("@react-three/fiber").ReactProps<BatchedLinesExt> & Partial<import("@react-three/fiber").EventHandlers>>>, Omit<import("@react-three/fiber").InstanceProps<BatchedLinesExt, typeof BatchedLinesExt>, "object">>>>;
+export declare const BatchedLines: import("react").ExoticComponent<import("@react-three/fiber/dist/declarations/src/core/utils").Mutable<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<Partial<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<BatchedLinesImpl, import("@react-three/fiber").MathProps<BatchedLinesImpl> & import("@react-three/fiber").ReactProps<BatchedLinesImpl> & Partial<import("@react-three/fiber").EventHandlers>>>, Omit<import("@react-three/fiber").InstanceProps<BatchedLinesImpl, typeof BatchedLinesImpl>, "object">>>>;
 //# sourceMappingURL=BatchedLines.d.ts.map

package/dist/core/lines/BatchedLines.js

@@ -2,7 +2,7 @@ import { extend } from '@react-three/fiber';
 import { Vector3, Vector4, } from 'three';
 import { LineMaterial } from 'three/addons/lines/LineMaterial.js';
 import { LineSegmentsGeometry } from 'three/addons/lines/LineSegmentsGeometry.js';
-import { InstancedMeshExt } from '../instanced/InstancedMesh';
+import { InstancedMeshImpl } from '../instanced/InstancedMesh';
 import { FrustumCulling } from './FrustumCulling';
 import { END_UNIFORM, patchLineMaterial, START_UNIFORM, WIDTH_UNIFORM } from './lines-material';
 import { Raycasting } from './Raycasting';
@@ -33,7 +33,7 @@ import { Raycasting } from './Raycasting';
  *
  * Render it with {@link BatchedLines}.
  */
-export class BatchedLinesExt extends InstancedMeshExt {
+export class BatchedLinesImpl extends InstancedMeshImpl {
     /**
      * The segment template every member is drawn from, and the whole of what the geometry carries: the
      * per-instance data three would put in instanced attributes is in the uniforms instead.
@@ -188,7 +188,7 @@ export class BatchedLinesExt extends InstancedMeshExt {
  * Registers the class as an R3F element, by value so the generated key cannot collide with anything
  * three puts in the catalog when the canvas mounts.
  */
-export const BatchedLines = extend(BatchedLinesExt);
+export const BatchedLines = extend(BatchedLinesImpl);
 /**
  * Whether a material is one three's line shader compiles from.
  * @param material - The material three is about to draw with.
@@ -199,7 +199,7 @@ function isLineMaterial(material) {
 }
 /**
  * The width a member starts at: negative, which is how "none of its own" is marked, so it draws at
- * the material's. See {@link BatchedLinesExt.setWidthAt} for why the marker is a negative value and
+ * the material's. See {@link BatchedLinesImpl.setWidthAt} for why the marker is a negative value and
  * not zero.
  */
 const MATERIAL_WIDTH = -1;

package/dist/core/shader-source.d.ts

@@ -11,6 +11,9 @@
  * Both helpers throw when they cannot find it, for the same reason: what reaches the driver
  * otherwise is a compile error naming an undeclared identifier, a long way from the patch that
  * failed to declare it.
+ *
+ * {@link sceneColorAnchor} is not about `main`, but it answers the same kind of question: where in a
+ * shader's own text a patch belongs.
  */
 /**
  * Declares GLSL above `main`, where file-scope declarations belong — samplers, varyings, functions.
@@ -47,4 +50,21 @@ export declare function openMain(source: string, glsl: string): string;
  * @throws {Error} If the source does not contain the anchor.
  */
 export declare function replaceAnchor(source: string, anchor: string, glsl: string): string;
+/**
+ * Where the fragment's **scene** color is final: the line a patch that changes the scene must land
+ * in front of.
+ *
+ * `<opaque_fragment>` writes the scene color, and three's output chain follows it — tone mapping,
+ * the colorspace conversion, fog, dithering. This returns the first of those. A patch below any of
+ * them would edit a value the chain already transformed, so its strength would depend on how bright
+ * the pixel already was.
+ *
+ * Two spellings, because three resolves `#include` after every `onBeforeCompile` while troika
+ * resolves it earlier, in its own rebuild of `main`. The expanded spelling is the `#if` line rather
+ * than the tone-mapping line inside it: the renderer pins `NoToneMapping`, which leaves
+ * `TONE_MAPPING` undefined, and the preprocessor then strips that block and anything put in it.
+ * @param fragmentShader - The shader to search.
+ * @returns The anchor found, or `undefined` if the shader has no output chain.
+ */
+export declare function sceneColorAnchor(fragmentShader: string): string | undefined;
 //# sourceMappingURL=shader-source.d.ts.map

package/dist/core/shader-source.js

@@ -11,6 +11,9 @@
  * Both helpers throw when they cannot find it, for the same reason: what reaches the driver
  * otherwise is a compile error naming an undeclared identifier, a long way from the patch that
  * failed to declare it.
+ *
+ * {@link sceneColorAnchor} is not about `main`, but it answers the same kind of question: where in a
+ * shader's own text a patch belongs.
  */
 /**
  * Declares GLSL above `main`, where file-scope declarations belong — samplers, varyings, functions.
@@ -56,6 +59,29 @@ export function replaceAnchor(source, anchor, glsl) {
         throw new Error(`shader-source: the shader has no "${anchor}" to rewrite.`);
     return source.slice(0, at) + glsl + source.slice(at + anchor.length);
 }
+/**
+ * Where the fragment's **scene** color is final: the line a patch that changes the scene must land
+ * in front of.
+ *
+ * `<opaque_fragment>` writes the scene color, and three's output chain follows it — tone mapping,
+ * the colorspace conversion, fog, dithering. This returns the first of those. A patch below any of
+ * them would edit a value the chain already transformed, so its strength would depend on how bright
+ * the pixel already was.
+ *
+ * Two spellings, because three resolves `#include` after every `onBeforeCompile` while troika
+ * resolves it earlier, in its own rebuild of `main`. The expanded spelling is the `#if` line rather
+ * than the tone-mapping line inside it: the renderer pins `NoToneMapping`, which leaves
+ * `TONE_MAPPING` undefined, and the preprocessor then strips that block and anything put in it.
+ * @param fragmentShader - The shader to search.
+ * @returns The anchor found, or `undefined` if the shader has no output chain.
+ */
+export function sceneColorAnchor(fragmentShader) {
+    const include = /*glsl*/ `#include <tonemapping_fragment>`;
+    const expanded = /*glsl*/ `#if defined( TONE_MAPPING )`;
+    if (fragmentShader.includes(include))
+        return include;
+    return fragmentShader.includes(expanded) ? expanded : undefined;
+}
 /**
  * Rewrites the first opening of `main`, splicing rather than replacing — so a `$` in the injected
  * GLSL cannot be read as a replacement pattern.

package/dist/core/text/BatchedText.d.ts

@@ -2,7 +2,7 @@ import { type BufferGeometry, type Camera, type Intersection, type Material, typ
 import { BatchedText as TroikaBatchedText, type TextMaterial } from 'troika-three-text';
 import { type UniformSchemaShader } from '../InstanceUniforms';
 import { type UniformValue, type UniformValueObj } from '../SquareDataTexture';
-import { type TextExt } from './Text';
+import { type TextImpl } from './Text';
 /**
  * troika's `BatchedText` with stable member ids, explicit paint order, and per-instance uniforms.
  *
@@ -24,7 +24,7 @@ import { type TextExt } from './Text';
  * Other departures from upstream:
  *
  * - **Sync is flag-driven, not scanned.** Members report property writes through
- *   `TextExt._batchParent`, so an idle frame costs nothing instead of walking every member.
+ *   `TextImpl._batchParent`, so an idle frame costs nothing instead of walking every member.
  * - **Per-member frustum culling and visibility**, by zeroing a hidden member's matrix so its glyphs
  *   collapse to a degenerate triangle. See {@link MemberTexture}.
  * - **Bounds are cached**, recomputed only when {@link invalidateBounds} says they moved, where
@@ -34,7 +34,7 @@ import { type TextExt } from './Text';
  * - **The derived material inherits the base's `transparent`**, rather than troika forcing it true.
  *   See {@link configureDerivedMaterial}.
  *
- * **Not built on {@link InstancedMeshExt}'s machinery**, despite the family resemblance. That mesh
+ * **Not built on {@link InstancedMeshImpl}'s machinery**, despite the family resemblance. That mesh
  * draws one shared geometry through a per-frame list of instance ids, so it culls and sorts by
  * rewriting the list; here draw order *is* the order glyph runs sit in the attributes, so a reorder
  * costs a repack and culling collapses a matrix row instead. Its members are real objects carrying
@@ -42,14 +42,14 @@ import { type TextExt } from './Text';
  * per member rather than in bulk by count, and visibility rides on the member's own `visible`. What
  * the two genuinely share is {@link InstanceUniforms}.
  *
- * Members must be {@link TextExt}, and are assumed to agree on `orientation` and `sdfGlyphSize`:
+ * Members must be {@link TextImpl}, and are assumed to agree on `orientation` and `sdfGlyphSize`:
  * both feed uniforms that are batch-wide rather than per-member, so mixing them across a batch
  * leaves whichever member was written last in charge.
  *
  * Render it with {@link BatchedText}.
  */
-export declare class BatchedTextExt extends TroikaBatchedText {
-    /** Per-instance uniform store, shared with {@link BatchedMeshExt} and {@link InstancedMeshExt}. */
+export declare class BatchedTextImpl extends TroikaBatchedText {
+    /** Per-instance uniform store, shared with {@link BatchedMeshImpl} and {@link InstancedMeshImpl}. */
     private readonly uniforms;
     /** The per-member transform and style rows the batch's shader draws from. */
     private readonly memberTexture;
@@ -76,7 +76,7 @@ export declare class BatchedTextExt extends TroikaBatchedText {
      * hole.
      *
      * **A pure high-water mark: removing a member never pulls it back in**, unlike `Instances`, the
-     * equivalent for {@link InstancedMeshExt}, which shrinks past trailing dead ids. Converting either
+     * equivalent for {@link InstancedMeshImpl}, which shrinks past trailing dead ids. Converting either
      * to the other buys nothing. A dead row costs the sweeps here one array read and a `continue`; and
      * this same number also sizes both textures, where `Instances` has a separate `capacity` for that
      * — so shrinking it would reallocate the matrix and uniform textures every time the last member
@@ -85,10 +85,10 @@ export declare class BatchedTextExt extends TroikaBatchedText {
     get addedMembersCount(): number;
     /** The material whose `onBeforeCompile` is already wrapped, so it is wrapped exactly once. */
     private patchedMaterial;
-    /** Marks the batch as needing a sync pass. Members call this through `TextExt._batchParent`. */
+    /** Marks the batch as needing a sync pass. Members call this through `TextImpl._batchParent`. */
     requestSync(): void;
     /**
-     * Marks the batch's bounds as stale. Members call this through `TextExt._batchParent` whenever
+     * Marks the batch's bounds as stale. Members call this through `TextImpl._batchParent` whenever
      * their transform changes, so no caller has to remember to.
      */
     invalidateBounds(): void;
@@ -97,7 +97,7 @@ export declare class BatchedTextExt extends TroikaBatchedText {
      * @param memberId - The member to read.
      * @returns The member, or `undefined` when the id holds none.
      */
-    getText(memberId: number): TextExt | undefined;
+    getText(memberId: number): TextImpl | undefined;
     /**
      * Shows or hides a member. A hidden member keeps its id and its glyphs; it is collapsed at draw
      * time rather than repacked out, so hiding costs no repack.
@@ -119,7 +119,7 @@ export declare class BatchedTextExt extends TroikaBatchedText {
      * @param texts - Every member, in paint order. Members missing from it are not drawn, and anything
      *   that is not a member is dropped.
      */
-    setOrder(texts: readonly TextExt[]): void;
+    setOrder(texts: readonly TextImpl[]): void;
     /**
      * Declares per-instance uniforms, merging with any already declared and rebuilding the backing
      * texture (existing values carried across). See {@link InstanceUniforms.add}.
@@ -147,8 +147,8 @@ export declare class BatchedTextExt extends TroikaBatchedText {
      * @returns The member’s id — stable for as long as it stays in the batch, and the index every
      *   other method here takes.
      */
-    addText(text: TextExt): number;
-    removeText(text: TextExt): void;
+    addText(text: TextImpl): number;
+    removeText(text: TextImpl): void;
     /**
      * Copies the text-level properties, and deliberately not the membership.
      *
@@ -223,5 +223,5 @@ export declare class BatchedTextExt extends TroikaBatchedText {
  * Registers the class as an R3F element, by value so the generated key cannot collide with anything
  * three puts in the catalog when the canvas mounts.
  */
-export declare const BatchedText: import("react").ExoticComponent<import("@react-three/fiber/dist/declarations/src/core/utils").Mutable<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<Partial<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<BatchedTextExt, import("@react-three/fiber").MathProps<BatchedTextExt> & import("@react-three/fiber").ReactProps<BatchedTextExt> & Partial<import("@react-three/fiber").EventHandlers>>>, Omit<import("@react-three/fiber").InstanceProps<BatchedTextExt, typeof BatchedTextExt>, "object">>>>;
+export declare const BatchedText: import("react").ExoticComponent<import("@react-three/fiber/dist/declarations/src/core/utils").Mutable<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<Partial<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<BatchedTextImpl, import("@react-three/fiber").MathProps<BatchedTextImpl> & import("@react-three/fiber").ReactProps<BatchedTextImpl> & Partial<import("@react-three/fiber").EventHandlers>>>, Omit<import("@react-three/fiber").InstanceProps<BatchedTextImpl, typeof BatchedTextImpl>, "object">>>>;
 //# sourceMappingURL=BatchedText.d.ts.map

package/dist/core/text/BatchedText.js

@@ -26,7 +26,7 @@ import { MemberTexture } from './MemberTexture';
  * Other departures from upstream:
  *
  * - **Sync is flag-driven, not scanned.** Members report property writes through
- *   `TextExt._batchParent`, so an idle frame costs nothing instead of walking every member.
+ *   `TextImpl._batchParent`, so an idle frame costs nothing instead of walking every member.
  * - **Per-member frustum culling and visibility**, by zeroing a hidden member's matrix so its glyphs
  *   collapse to a degenerate triangle. See {@link MemberTexture}.
  * - **Bounds are cached**, recomputed only when {@link invalidateBounds} says they moved, where
@@ -36,7 +36,7 @@ import { MemberTexture } from './MemberTexture';
  * - **The derived material inherits the base's `transparent`**, rather than troika forcing it true.
  *   See {@link configureDerivedMaterial}.
  *
- * **Not built on {@link InstancedMeshExt}'s machinery**, despite the family resemblance. That mesh
+ * **Not built on {@link InstancedMeshImpl}'s machinery**, despite the family resemblance. That mesh
  * draws one shared geometry through a per-frame list of instance ids, so it culls and sorts by
  * rewriting the list; here draw order *is* the order glyph runs sit in the attributes, so a reorder
  * costs a repack and culling collapses a matrix row instead. Its members are real objects carrying
@@ -44,14 +44,14 @@ import { MemberTexture } from './MemberTexture';
  * per member rather than in bulk by count, and visibility rides on the member's own `visible`. What
  * the two genuinely share is {@link InstanceUniforms}.
  *
- * Members must be {@link TextExt}, and are assumed to agree on `orientation` and `sdfGlyphSize`:
+ * Members must be {@link TextImpl}, and are assumed to agree on `orientation` and `sdfGlyphSize`:
  * both feed uniforms that are batch-wide rather than per-member, so mixing them across a batch
  * leaves whichever member was written last in charge.
  *
  * Render it with {@link BatchedText}.
  */
-export class BatchedTextExt extends TroikaBatchedText {
-    /** Per-instance uniform store, shared with {@link BatchedMeshExt} and {@link InstancedMeshExt}. */
+export class BatchedTextImpl extends TroikaBatchedText {
+    /** Per-instance uniform store, shared with {@link BatchedMeshImpl} and {@link InstancedMeshImpl}. */
     uniforms = new InstanceUniforms();
     /** The per-member transform and style rows the batch's shader draws from. */
     memberTexture = new MemberTexture();
@@ -85,7 +85,7 @@ export class BatchedTextExt extends TroikaBatchedText {
      * hole.
      *
      * **A pure high-water mark: removing a member never pulls it back in**, unlike `Instances`, the
-     * equivalent for {@link InstancedMeshExt}, which shrinks past trailing dead ids. Converting either
+     * equivalent for {@link InstancedMeshImpl}, which shrinks past trailing dead ids. Converting either
      * to the other buys nothing. A dead row costs the sweeps here one array read and a `continue`; and
      * this same number also sizes both textures, where `Instances` has a separate `capacity` for that
      * — so shrinking it would reallocate the matrix and uniform textures every time the last member
@@ -96,12 +96,12 @@ export class BatchedTextExt extends TroikaBatchedText {
     }
     /** The material whose `onBeforeCompile` is already wrapped, so it is wrapped exactly once. */
     patchedMaterial = null;
-    /** Marks the batch as needing a sync pass. Members call this through `TextExt._batchParent`. */
+    /** Marks the batch as needing a sync pass. Members call this through `TextImpl._batchParent`. */
     requestSync() {
         this.batchNeedsSync = true;
     }
     /**
-     * Marks the batch's bounds as stale. Members call this through `TextExt._batchParent` whenever
+     * Marks the batch's bounds as stale. Members call this through `TextImpl._batchParent` whenever
      * their transform changes, so no caller has to remember to.
      */
     invalidateBounds() {
@@ -456,7 +456,7 @@ export class BatchedTextExt extends TroikaBatchedText {
  * Registers the class as an R3F element, by value so the generated key cannot collide with anything
  * three puts in the catalog when the canvas mounts.
  */
-export const BatchedText = extend(BatchedTextExt);
+export const BatchedText = extend(BatchedTextImpl);
 // Reused rather than built per dispatch: three's `dispatchEvent` stamps `target` on the object it
 // is handed, so these are one allocation for the batch's lifetime instead of one per event.
 const syncStartEvent = { type: 'syncstart' };

package/dist/core/text/MemberTexture.d.ts

@@ -1,6 +1,6 @@
 import { type Camera, type ColorRepresentation, Matrix4 } from 'three';
 import { type BatchTextMaterial } from 'troika-three-text';
-import { type TextExt } from './Text';
+import { type TextImpl } from './Text';
 /** What {@link MemberTexture} reads off the batch it fills for. */
 export interface MemberTextureHost {
     /**
@@ -18,7 +18,7 @@ export interface MemberTextureHost {
      * @param memberId - The member to read.
      * @returns The member, or `undefined` when the id holds none.
      */
-    getText(memberId: number): TextExt | undefined;
+    getText(memberId: number): TextImpl | undefined;
 }
 /**
  * The data texture a batch's shader reads each member's transform and style from: one 32-float row

package/dist/core/text/Text.d.ts

@@ -1,6 +1,6 @@
 import { Matrix4 } from 'three';
 import { Text as TroikaText, type TextMaterial } from 'troika-three-text';
-import { type BatchedTextExt } from './BatchedText';
+import { type BatchedTextImpl } from './BatchedText';
 /**
  * troika's `Text` with the deviations a batched, 2D-painter renderer needs.
  *
@@ -30,13 +30,13 @@ import { type BatchedTextExt } from './BatchedText';
  *
  * Render it with {@link Text}.
  */
-export declare class TextExt extends TroikaText {
+export declare class TextImpl extends TroikaText {
     /**
-     * The batch this text belongs to, set by {@link BatchedTextExt.addText}. It is how a member
+     * The batch this text belongs to, set by {@link BatchedTextImpl.addText}. It is how a member
      * reaches its batch without the batch scanning for changes: property writes invalidate the sync
      * through it, and transform writes invalidate the bounds.
      */
-    _batchParent: BatchedTextExt | undefined;
+    _batchParent: BatchedTextImpl | undefined;
     /**
      * Backing store for the `_needsSync` accessor installed on the prototype below.
      *
@@ -69,5 +69,5 @@ export declare class TextExt extends TroikaText {
  * Registers the class as an R3F element, by value so the generated key cannot collide with anything
  * three puts in the catalog when the canvas mounts.
  */
-export declare const Text: import("react").ExoticComponent<import("@react-three/fiber/dist/declarations/src/core/utils").Mutable<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<Partial<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<TextExt, import("@react-three/fiber").MathProps<TextExt> & import("@react-three/fiber").ReactProps<TextExt> & Partial<import("@react-three/fiber").EventHandlers>>>, Omit<import("@react-three/fiber").InstanceProps<TextExt, typeof TextExt>, "object">>>>;
+export declare const Text: import("react").ExoticComponent<import("@react-three/fiber/dist/declarations/src/core/utils").Mutable<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<Partial<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<TextImpl, import("@react-three/fiber").MathProps<TextImpl> & import("@react-three/fiber").ReactProps<TextImpl> & Partial<import("@react-three/fiber").EventHandlers>>>, Omit<import("@react-three/fiber").InstanceProps<TextImpl, typeof TextImpl>, "object">>>>;
 //# sourceMappingURL=Text.d.ts.map

package/dist/core/text/Text.js

@@ -30,9 +30,9 @@ import { Text as TroikaText } from 'troika-three-text';
  *
  * Render it with {@link Text}.
  */
-export class TextExt extends TroikaText {
+export class TextImpl extends TroikaText {
     /**
-     * The batch this text belongs to, set by {@link BatchedTextExt.addText}. It is how a member
+     * The batch this text belongs to, set by {@link BatchedTextImpl.addText}. It is how a member
      * reaches its batch without the batch scanning for changes: property writes invalidate the sync
      * through it, and transform writes invalidate the bounds.
      */
@@ -189,7 +189,7 @@ export class TextExt extends TroikaText {
  * Runs during `super()` — the base constructor seeds the syncable properties — at which point the
  * `_batchParent` field initializer has not run yet, so the optional call is doing real work.
  */
-Object.defineProperty(TextExt.prototype, '_needsSync', {
+Object.defineProperty(TextImpl.prototype, '_needsSync', {
     configurable: true,
     get() {
         return this._syncFlag;
@@ -206,7 +206,7 @@ Object.defineProperty(TextExt.prototype, '_needsSync', {
  * Registers the class as an R3F element, by value so the generated key cannot collide with anything
  * three puts in the catalog when the canvas mounts.
  */
-export const Text = extend(TextExt);
+export const Text = extend(TextImpl);
 // Scratch reused across calls, each filled and consumed within a single synchronous block.
 const _matrix = new Matrix4();
 const _horizontal = new Vector3();