@expofp/renderer 3.38.0 → 3.39.0

package/dist/controls/camera-api.d.ts

@@ -147,6 +147,14 @@ interface CameraContext {
     height: number;
     /** Device pixels per css pixel. */
     dpr: number;
+    /**
+     * Asks React Three Fiber to draw another frame.
+     *
+     * A command changes the controls directly. That change happens outside a React commit. React
+     * Three Fiber cannot see it on its own. Calling this schedules the frame that shows the change,
+     * under a demand frame loop that would otherwise never draw one.
+     */
+    invalidate: () => void;
 }
 /**
  * The camera commands, over whatever the scene currently holds.
@@ -181,6 +189,26 @@ export declare class CameraCommands implements CameraAPI {
     pitchBy(degrees: number, options?: TransitionOptions): Promise<void>;
     /** @inheritdoc */
     reset(axes?: CameraAxes, options?: TransitionOptions): Promise<void>;
+    /**
+     * Runs a move against the controls and asks for the frame that shows it.
+     *
+     * Every method above that takes {@link TransitionOptions} funnels its move through this one
+     * helper. A method that calls `controls` directly instead skips it, and looks obviously unlike
+     * its siblings.
+     *
+     * The invalidate happens before the move settles, not after, and every time, not only when the
+     * move is immediate. An eased move already triggers its own invalidate through `transitionstart`.
+     * An immediate move fires no event at all. `camera-controls` only applies an immediate move inside
+     * its own `update`, which runs from a frame that only an invalidate schedules. Invalidating after
+     * the move's promise settles would be too late to schedule that frame.
+     *
+     * A field and not a method, so it never lands on `CameraCommands.prototype`. The guard spec walks
+     * that prototype and calls everything it finds there, and an implementation detail would fail that
+     * walk for no reason.
+     * @param move - Issues the move against the controls and returns its promise.
+     * @returns The same promise `move` returned.
+     */
+    private withInvalidate;
 }
 /**
  * How far the plan is turned from north: clockwise, in radians, in `[0, 2π)`.

package/dist/controls/camera-api.js

@@ -35,17 +35,17 @@ export class CameraCommands {
         if (!fit)
             return;
         const transition = !options?.immediate;
-        await Promise.all([
+        await this.withInvalidate(() => Promise.all([
             controls.moveTo(fit.center.x, fit.center.y, 0, transition),
             controls.dollyTo(camera.zoomFactorToDistance(fit.zoom), transition),
-        ]);
+        ]));
     }
     /** @inheritdoc */
     zoomBy(factor, options) {
         const { controls, camera } = this.context;
         if (!controls || !camera)
             return RESOLVED;
-        return controls.dollyTo(camera.zoomFactorToDistance(camera.zoomFactor * factor), !options?.immediate);
+        return this.withInvalidate(() => controls.dollyTo(camera.zoomFactorToDistance(camera.zoomFactor * factor), !options?.immediate));
     }
     /** @inheritdoc */
     panTo(point, options) {
@@ -53,7 +53,7 @@ export class CameraCommands {
         if (!controls)
             return RESOLVED;
         const world = toWorld(space, point);
-        return controls.moveTo(world.x, world.y, world.z, !options?.immediate);
+        return this.withInvalidate(() => controls.moveTo(world.x, world.y, world.z, !options?.immediate));
     }
     /** @inheritdoc */
     panBy(offset, options) {
@@ -65,7 +65,7 @@ export class CameraCommands {
         const origin = toWorld(space, ORIGIN, _origin);
         const shifted = toWorld(space, offset);
         const current = controls.getTarget(_current);
-        return controls.moveTo(current.x + shifted.x - origin.x, current.y + shifted.y - origin.y, current.z + shifted.z - origin.z, !options?.immediate);
+        return this.withInvalidate(() => controls.moveTo(current.x + shifted.x - origin.x, current.y + shifted.y - origin.y, current.z + shifted.z - origin.z, !options?.immediate));
     }
     /** @inheritdoc */
     rollTo(degrees, options) {
@@ -75,14 +75,14 @@ export class CameraCommands {
         // Whichever way round is shorter, which is what keeps a turn from 350° to 10° going the long
         // way about.
         const delta = angleDiff(-degToRad(degrees), controls.azimuthAngle);
-        return controls.rotateAzimuthTo(controls.azimuthAngle + delta, !options?.immediate);
+        return this.withInvalidate(() => controls.rotateAzimuthTo(controls.azimuthAngle + delta, !options?.immediate));
     }
     /** @inheritdoc */
     rollBy(degrees, options) {
         const { controls } = this.context;
         if (!controls)
             return RESOLVED;
-        return controls.rotateAzimuthTo(controls.azimuthAngle - degToRad(degrees), !options?.immediate);
+        return this.withInvalidate(() => controls.rotateAzimuthTo(controls.azimuthAngle - degToRad(degrees), !options?.immediate));
     }
     /** @inheritdoc */
     pitchTo(degrees, options) {
@@ -90,14 +90,14 @@ export class CameraCommands {
         if (!controls)
             return RESOLVED;
         // Held inside the pitch limits by the controls themselves, which is where those limits live.
-        return controls.rotatePolarTo(degToRad(degrees), !options?.immediate);
+        return this.withInvalidate(() => controls.rotatePolarTo(degToRad(degrees), !options?.immediate));
     }
     /** @inheritdoc */
     pitchBy(degrees, options) {
         const { controls } = this.context;
         if (!controls)
             return RESOLVED;
-        return controls.rotatePolarTo(controls.polarAngle + degToRad(degrees), !options?.immediate);
+        return this.withInvalidate(() => controls.rotatePolarTo(controls.polarAngle + degToRad(degrees), !options?.immediate));
     }
     /** @inheritdoc */
     async reset(axes = ALL_AXES, options) {
@@ -119,8 +119,31 @@ export class CameraCommands {
             moves.push(controls.normalizeRotations().rotateAzimuthTo(0, transition));
         if (axes.pitch)
             moves.push(controls.rotatePolarTo(controls.minPolarAngle, transition));
-        await Promise.all(moves);
+        await this.withInvalidate(() => Promise.all(moves));
     }
+    /**
+     * Runs a move against the controls and asks for the frame that shows it.
+     *
+     * Every method above that takes {@link TransitionOptions} funnels its move through this one
+     * helper. A method that calls `controls` directly instead skips it, and looks obviously unlike
+     * its siblings.
+     *
+     * The invalidate happens before the move settles, not after, and every time, not only when the
+     * move is immediate. An eased move already triggers its own invalidate through `transitionstart`.
+     * An immediate move fires no event at all. `camera-controls` only applies an immediate move inside
+     * its own `update`, which runs from a frame that only an invalidate schedules. Invalidating after
+     * the move's promise settles would be too late to schedule that frame.
+     *
+     * A field and not a method, so it never lands on `CameraCommands.prototype`. The guard spec walks
+     * that prototype and calls everything it finds there, and an implementation detail would fail that
+     * walk for no reason.
+     * @param move - Issues the move against the controls and returns its promise.
+     * @returns The same promise `move` returned.
+     */
+    withInvalidate = (move) => {
+        this.context.invalidate();
+        return move();
+    };
 }
 /**
  * How far the plan is turned from north: clockwise, in radians, in `[0, 2π)`.

package/dist/controls/hooks.js

@@ -182,6 +182,7 @@ const _target = new Vector3();
  */
 export function useCameraAPI() {
     const get = useThree((state) => state.get);
+    const invalidate = useThree((state) => state.invalidate);
     const controls = useCameraControls();
     const camera = useCamera();
     const space = useSpace();
@@ -194,5 +195,6 @@ export function useCameraAPI() {
         width,
         height,
         dpr,
+        invalidate,
     });
 }

package/dist/core/InstanceUniforms.d.ts

@@ -29,6 +29,21 @@ export declare class InstanceUniforms {
     texture: SquareDataTexture | null;
     /** Everything declared so far, merged across calls, so a rebuild recomputes the whole layout. */
     private declared;
+    /** Backs {@link shaderKey}, rebuilt whenever {@link declared} changes. */
+    private key;
+    /**
+     * What the declared uniforms generate, as one string.
+     *
+     * A material that fetches per-instance uniforms compiles different GLSL for every schema, and
+     * three caches a compiled program under `customProgramCacheKey` alone, with no way to compare
+     * source. So every patcher that injects this store's prologue folds this into its own key.
+     * Without it, two meshes whose schemas differ share one program and the second silently draws
+     * against the first's layout.
+     *
+     * Empty while nothing is declared, which is itself a distinct key: that program has no prologue.
+     * @returns The key, stable for as long as the schema is.
+     */
+    get shaderKey(): string;
     /**
      * Declares uniforms, merging with any already declared and rebuilding the texture.
      *

package/dist/core/InstanceUniforms.js

@@ -21,6 +21,23 @@ export class InstanceUniforms {
     texture = null;
     /** Everything declared so far, merged across calls, so a rebuild recomputes the whole layout. */
     declared = {};
+    /** Backs {@link shaderKey}, rebuilt whenever {@link declared} changes. */
+    key = '';
+    /**
+     * What the declared uniforms generate, as one string.
+     *
+     * A material that fetches per-instance uniforms compiles different GLSL for every schema, and
+     * three caches a compiled program under `customProgramCacheKey` alone, with no way to compare
+     * source. So every patcher that injects this store's prologue folds this into its own key.
+     * Without it, two meshes whose schemas differ share one program and the second silently draws
+     * against the first's layout.
+     *
+     * Empty while nothing is declared, which is itself a distinct key: that program has no prologue.
+     * @returns The key, stable for as long as the schema is.
+     */
+    get shaderKey() {
+        return this.key;
+    }
     /**
      * Declares uniforms, merging with any already declared and rebuilding the texture.
      *
@@ -42,6 +59,7 @@ export class InstanceUniforms {
         }
         this.texture = texture;
         this.declared = { vertex, fragment };
+        this.key = schemaKey(this.declared);
     }
     /**
      * Reads one instance's uniform.
@@ -106,6 +124,7 @@ export class InstanceUniforms {
             vertex: { ...source.declared.vertex },
             fragment: { ...source.declared.fragment },
         };
+        this.key = source.key;
         this.texture = source.texture ? source.texture.clone() : null;
     }
     /** Frees the texture. */
@@ -210,6 +229,19 @@ function uniformSize(type) {
             throw new Error(`InstanceUniforms: invalid uniform type "${String(type)}".`);
     }
 }
+/**
+ * Builds the key that stands for the GLSL a schema generates. See {@link InstanceUniforms.shaderKey}.
+ *
+ * Names, types and the stage each is read in, because all three reach the generated source. Left in
+ * declaration order rather than sorted, since that is the order the layout packs them in, so two
+ * schemas that differ only in order still pack differently and have to compile apart.
+ * @param schema - The declared uniforms.
+ * @returns The key.
+ */
+function schemaKey(schema) {
+    const stage = (prefix, uniforms = {}) => Object.entries(uniforms).map(([name, type]) => `${prefix}${name}:${type}`);
+    return [...stage('v', schema.vertex), ...stage('f', schema.fragment)].join(',');
+}
 /**
  * Flattens a schema into the name-to-type pairs a rebuild has to carry across.
  * @param schema - The declared uniforms.

package/dist/core/batch/BatchedMesh.js

@@ -131,6 +131,12 @@ export class BatchedMeshImpl extends BatchedMeshBase {
         const batchIndexGlsl = /* glsl */ `float ${batchIndex} = getIndirectIndex( gl_DrawID ) + 0.5;`;
         this.patchedMaterial = material;
         const onBeforeCompileBase = material.onBeforeCompile.bind(material);
+        // three caches a compiled program under this key alone and compares no source. The prologue
+        // below changes the GLSL, and the schema decides how, so both have to reach the key. Without
+        // it, two batches whose schemas differ share one program and the second draws against the
+        // first's layout. Bound rather than saved raw, because this patch is one-shot and never undone.
+        const cacheKeyBase = material.customProgramCacheKey.bind(material);
+        material.customProgramCacheKey = () => `efpBatched_${this.uniforms.shaderKey}_${cacheKeyBase()}`;
         material.onBeforeCompile = (shader, renderer) => {
             if (this.uniforms.patchShader(shader, batchIndex)) {
                 // Declares the index the prologue just injected reads. Written after it precisely so it runs

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

@@ -154,7 +154,11 @@ export function patchInstancedMaterial(material, textures) {
     // before a texture was added, since each changes the generated GLSL. Every texture that can arrive
     // late is named: the matrices are allocated by the first transform written, and a program built
     // before that reads identity.
-    const key = () => `${!!textures.matricesTexture}_${!!textures.colorsTexture}_${!!textures.uniforms.texture}`;
+    //
+    // The uniforms contribute their whole schema and not just their presence. Two meshes that declare
+    // different uniforms generate different GLSL, so a key that recorded only "has uniforms" would let
+    // the second draw against the first's layout.
+    const key = () => `${!!textures.matricesTexture}_${!!textures.colorsTexture}_${textures.uniforms.shaderKey}`;
     material.customProgramCacheKey = () => `efp_${key()}_${baseCacheKey.call(material)}`;
     material.onBeforeCompile = (shader, renderer) => {
         // Instancing first, the material's own handler after — the same order the batched meshes use,

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

@@ -2,8 +2,8 @@ import { type Box3, type BufferGeometry, type Camera, type Group, type Material,
 import { LineMaterial } from 'three/addons/lines/LineMaterial.js';
 import { LineSegmentsGeometry } from 'three/addons/lines/LineSegmentsGeometry.js';
 import { InstancedMeshImpl, type InstancedMeshImplParams } from '../instanced/InstancedMesh';
-import { FrustumCulling } from './FrustumCulling';
-import { Raycasting } from './Raycasting';
+import { FrustumCullingLines } from './FrustumCullingLines';
+import { RaycastingLines } from './RaycastingLines';
 /**
  * An instanced mesh whose instances are placed by two endpoints instead of a matrix.
  *
@@ -21,7 +21,7 @@ import { Raycasting } from './Raycasting';
  *   names and needs no rewriting beyond dropping the declarations — see `objects/materials/LineMaterial`.
  * - **The bounds**, swept from the endpoints, because the template geometry's own are in the
  *   parametric space the shader expands from and mean nothing in the plan.
- * - **Picking**, which has to run in screen space at each member's own width — see {@link Raycasting}.
+ * - **Picking**, which has to run in screen space at each member's own width — see {@link RaycastingLines}.
  *
  * And what it stops needing by being one: the endpoints are addressed by id, so paint order is a
  * `customSort` over the draw list like every other batch's rather than a packing of the buffer;
@@ -32,6 +32,8 @@ import { Raycasting } from './Raycasting';
  * Render it with {@link BatchedLines}.
  */
 export declare class BatchedLinesImpl extends InstancedMeshImpl {
+    /** Marks this as a line batch. three's brand pattern, so a holder can tell the batch kinds apart. */
+    readonly isBatchedLines = true;
     /**
      * 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.
@@ -51,10 +53,10 @@ export declare class BatchedLinesImpl extends InstancedMeshImpl {
     material: LineMaterial;
     /** Draw order is paint order, which a container decides through `customSort` rather than depth. */
     sortObjects: boolean;
-    /** Screen space, at each member's own width — see {@link Raycasting}. */
-    protected raycasting: Raycasting;
-    /** By the ribbon each member draws rather than the segment it runs — see {@link FrustumCulling}. */
-    protected culling: FrustumCulling;
+    /** Screen space, at each member's own width — see {@link RaycastingLines}. */
+    protected raycasting: RaycastingLines;
+    /** By the ribbon each member draws rather than the segment it runs — see {@link FrustumCullingLines}. */
+    protected culling: FrustumCullingLines;
     /**
      * @param params - Instance capacity; the buffers grow past it on demand.
      */

package/dist/core/lines/BatchedLines.js

@@ -3,9 +3,9 @@ import { Vector3, Vector4, } from 'three';
 import { LineMaterial } from 'three/addons/lines/LineMaterial.js';
 import { LineSegmentsGeometry } from 'three/addons/lines/LineSegmentsGeometry.js';
 import { InstancedMeshImpl } from '../instanced/InstancedMesh';
-import { FrustumCulling } from './FrustumCulling';
+import { FrustumCullingLines } from './FrustumCullingLines';
 import { END_UNIFORM, patchLineMaterial, START_UNIFORM, WIDTH_UNIFORM } from './lines-material';
-import { Raycasting } from './Raycasting';
+import { RaycastingLines } from './RaycastingLines';
 /**
  * An instanced mesh whose instances are placed by two endpoints instead of a matrix.
  *
@@ -23,7 +23,7 @@ import { Raycasting } from './Raycasting';
  *   names and needs no rewriting beyond dropping the declarations — see `objects/materials/LineMaterial`.
  * - **The bounds**, swept from the endpoints, because the template geometry's own are in the
  *   parametric space the shader expands from and mean nothing in the plan.
- * - **Picking**, which has to run in screen space at each member's own width — see {@link Raycasting}.
+ * - **Picking**, which has to run in screen space at each member's own width — see {@link RaycastingLines}.
  *
  * And what it stops needing by being one: the endpoints are addressed by id, so paint order is a
  * `customSort` over the draw list like every other batch's rather than a packing of the buffer;
@@ -34,6 +34,8 @@ import { Raycasting } from './Raycasting';
  * Render it with {@link BatchedLines}.
  */
 export class BatchedLinesImpl extends InstancedMeshImpl {
+    /** Marks this as a line batch. three's brand pattern, so a holder can tell the batch kinds apart. */
+    isBatchedLines = true;
     /**
      * 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.
@@ -53,10 +55,10 @@ export class BatchedLinesImpl extends InstancedMeshImpl {
     material = new LineMaterial();
     /** Draw order is paint order, which a container decides through `customSort` rather than depth. */
     sortObjects = true;
-    /** Screen space, at each member's own width — see {@link Raycasting}. */
-    raycasting = new Raycasting();
-    /** By the ribbon each member draws rather than the segment it runs — see {@link FrustumCulling}. */
-    culling = new FrustumCulling();
+    /** Screen space, at each member's own width — see {@link RaycastingLines}. */
+    raycasting = new RaycastingLines();
+    /** By the ribbon each member draws rather than the segment it runs — see {@link FrustumCullingLines}. */
+    culling = new FrustumCullingLines();
     /**
      * @param params - Instance capacity; the buffers grow past it on demand.
      */

package/dist/core/lines/{FrustumCulling.d.ts → FrustumCullingLines.d.ts}

@@ -1,8 +1,8 @@
 import { type Camera, type Sphere } from 'three';
 import { type LineMaterial } from 'three/addons/lines/LineMaterial.js';
-import { type CullingHost as InstancedCullingHost, FrustumCulling as InstancedFrustumCulling } from '../instanced/FrustumCulling';
-/** What {@link FrustumCulling} reads off the batch it culls, beyond what every instanced mesh offers. */
-export interface CullingHost extends InstancedCullingHost {
+import { type CullingHost, FrustumCulling } from '../instanced/FrustumCulling';
+/** What {@link FrustumCullingLines} reads off the batch it culls, beyond what every instanced mesh offers. */
+interface CullingHostLines extends CullingHost {
     /** The material, whose width a member with none of its own draws at, and whose units they are in. */
     material: LineMaterial;
     /**
@@ -25,8 +25,8 @@ export interface CullingHost extends InstancedCullingHost {
  * per member rather than one figure for the batch — a member already knows its own width, and a batch
  * of hairlines beside one wide route would otherwise be padded by the widest of them.
  */
-export declare class FrustumCulling extends InstancedFrustumCulling {
-    protected instanceSphere(host: CullingHost, id: number, camera: Camera, target: Sphere): Sphere;
+export declare class FrustumCullingLines extends FrustumCulling {
+    protected instanceSphere(host: CullingHostLines, id: number, camera: Camera, target: Sphere): Sphere;
     /**
      * How far past its endpoints one member draws, in the units its bounds are measured in.
      *
@@ -40,4 +40,5 @@ export declare class FrustumCulling extends InstancedFrustumCulling {
      */
     private drawnMargin;
 }
-//# sourceMappingURL=FrustumCulling.d.ts.map
+export {};
+//# sourceMappingURL=FrustumCullingLines.d.ts.map

package/dist/core/lines/{FrustumCulling.js → FrustumCullingLines.js}

@@ -1,5 +1,5 @@
 import { Vector3, Vector4 } from 'three';
-import { FrustumCulling as InstancedFrustumCulling, } from '../instanced/FrustumCulling';
+import { FrustumCulling } from '../instanced/FrustumCulling';
 /**
  * Culling for a line batch: each member tested by where it is *drawn*, not where it runs.
  *
@@ -13,7 +13,7 @@ import { FrustumCulling as InstancedFrustumCulling, } from '../instanced/Frustum
  * per member rather than one figure for the batch — a member already knows its own width, and a batch
  * of hairlines beside one wide route would otherwise be padded by the widest of them.
  */
-export class FrustumCulling extends InstancedFrustumCulling {
+export class FrustumCullingLines extends FrustumCulling {
     instanceSphere(host, id, camera, target) {
         const sphere = super.instanceSphere(host, id, camera, target);
         sphere.radius += this.drawnMargin(host, id, camera, sphere);

package/dist/core/lines/{Raycasting.d.ts → RaycastingLines.d.ts}

@@ -1,8 +1,8 @@
 import { type Object3D, Vector3 } from 'three';
 import { LineMaterial } from 'three/addons/lines/LineMaterial.js';
-import { type RaycastHost as InstancedRaycastHost, Raycasting as InstancedRaycasting } from '../instanced/Raycasting';
-/** What {@link Raycasting} reads off the batch it tests, beyond what every instanced mesh offers. */
-export interface RaycastHost extends InstancedRaycastHost {
+import { type RaycastHost, Raycasting } from '../instanced/Raycasting';
+/** What {@link RaycastingLines} reads off the batch it tests, beyond what every instanced mesh offers. */
+interface RaycastHostLines extends RaycastHost {
     /** The material, whose width a member with none of its own draws at. */
     material: LineMaterial;
     /**
@@ -38,7 +38,8 @@ export interface RaycastHost extends InstancedRaycastHost {
  * scratch carries a material of its own, written per test, and nothing touches the batch's — which
  * is in use by the draw the pointer is moving over.
  */
-export declare class Raycasting extends InstancedRaycasting {
-    protected prepareInstance(host: RaycastHost, objectIndex: number): Object3D;
+export declare class RaycastingLines extends Raycasting {
+    protected prepareInstance(host: RaycastHostLines, objectIndex: number): Object3D;
 }
-//# sourceMappingURL=Raycasting.d.ts.map
+export {};
+//# sourceMappingURL=RaycastingLines.d.ts.map

package/dist/core/lines/{Raycasting.js → RaycastingLines.js}

@@ -2,7 +2,7 @@ import { Box3, Sphere, Vector3 } from 'three';
 import { LineMaterial } from 'three/addons/lines/LineMaterial.js';
 import { LineSegments2 } from 'three/addons/lines/LineSegments2.js';
 import { LineSegmentsGeometry } from 'three/addons/lines/LineSegmentsGeometry.js';
-import { Raycasting as InstancedRaycasting, } from '../instanced/Raycasting';
+import { Raycasting } from '../instanced/Raycasting';
 /**
  * Picking for a line batch: each member tested in screen space, at the width it actually draws at.
  *
@@ -22,7 +22,7 @@ import { Raycasting as InstancedRaycasting, } from '../instanced/Raycasting';
  * scratch carries a material of its own, written per test, and nothing touches the batch's — which
  * is in use by the draw the pointer is moving over.
  */
-export class Raycasting extends InstancedRaycasting {
+export class RaycastingLines extends Raycasting {
     prepareInstance(host, objectIndex) {
         host.getPointsAt(objectIndex, _start, _end);
         // Written straight into the interleaved buffer the geometry already owns. `setPositions` would

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

@@ -28,14 +28,23 @@ export function patchLineMaterial(material) {
     seedColorChunk(material);
     // Saved raw rather than bound, for the reason `patchInstancedMaterial` spells out: restoring a
     // bound copy would put a *different* function back, and the next draw would bind that one in turn.
-    /* eslint-disable-next-line @typescript-eslint/unbound-method -- restored verbatim; called with `.call`. */
+    /* eslint-disable @typescript-eslint/unbound-method -- restored verbatim; called with `.call`. */
     const baseOnBeforeCompile = material.onBeforeCompile;
+    const baseCacheKey = material.customProgramCacheKey;
+    /* eslint-enable @typescript-eslint/unbound-method */
+    // three caches a compiled program under this key alone. A patched line material compiles source a
+    // plain one does not, so it needs a key of its own. A constant suffix is enough, because what this
+    // patch injects is fixed. `seedColorChunk` happens to change the source three derives its own
+    // shader id from, which has masked the absence of this until now. That is incidental, and a
+    // material that stopped needing the seed would lose the protection with it.
+    material.customProgramCacheKey = () => `efpLine_${baseCacheKey.call(material)}`;
     material.onBeforeCompile = (shader, renderer) => {
         patchLineShader(shader);
         baseOnBeforeCompile.call(material, shader, renderer);
     };
     return () => {
         material.onBeforeCompile = baseOnBeforeCompile;
+        material.customProgramCacheKey = baseCacheKey;
     };
 }
 /**

package/dist/core/sprites/BatchedSprites.d.ts

@@ -0,0 +1,115 @@
+import { type BufferGeometry, type Camera, type Group, type Material, PlaneGeometry, type Scene, type Sphere, Vector2, type WebGLRenderer } from 'three';
+import { InstancedMeshImpl, type InstancedMeshImplParams } from '../instanced/InstancedMesh';
+import { RaycastingSprites } from './RaycastingSprites';
+/**
+ * Whether an instanced mesh is a sprite batch.
+ *
+ * three's own brand pattern, which `isLineMaterial` in `BatchedLines` already follows here. A holder
+ * that keeps one mesh field for several batch kinds narrows it with this, instead of keeping a
+ * second field that says which kind it stored.
+ * @param object - The instanced mesh to test.
+ * @returns Whether it is a sprite batch.
+ */
+export declare function isBatchedSprites(object: InstancedMeshImpl): object is BatchedSpritesImpl;
+/**
+ * An instanced mesh whose every member faces the camera.
+ *
+ * The name means what it says, which is why this is a class and not a flag. A batch of sprites is
+ * homogeneous. One atlas is then drawn by two meshes over two disjoint subsets of its images,
+ * instead of one mesh learning about orientation, and the packing never hears about the distinction.
+ *
+ * What facing the camera changes, and nothing else does:
+ *
+ * - The projection, in the shader. See `sprite-material.ts`. Everything else an instanced mesh
+ *   does applies unchanged: slots, visibility, growth, per-instance uniforms, the draw list that is
+ *   also the paint order, and the material wiring.
+ * - The anchor, as a per-instance uniform rather than a fold into the matrix. A sprite pivots
+ *   about its anchor, so the matrix translation has to be the anchor.
+ * - The bounds, which enclose the quad about that anchor. See `getBoundingSphereAt`.
+ * - Picking, which has to run three's own sprite algorithm through a scratch object. See
+ *   `RaycastingSprites`.
+ *
+ * Members are ids, not `Sprite` objects. `BatchedTextImpl` takes `TextImpl` members because troika's
+ * layout is object shaped and asynchronous, and the batch has to pack what those objects produce. A
+ * sprite carries none of that. It is a matrix, an anchor and a color, and every one of those
+ * already lives in a data texture this mesh owns. Reusing three's type as the member representation
+ * would reinstate the object-per-instance layer the port dropped, and would import `SpriteMaterial`
+ * semantics this package does not implement. Three's type is reused where it costs nothing, as
+ * picking scratch.
+ *
+ * This class knows nothing about textures. A uv region belongs to `TextureMaterial` and to the layer
+ * that packs an atlas. A batch drawn with a plain color material works exactly as well, and tints
+ * its members through `setColorAt` like any instanced mesh.
+ *
+ * Render it with `BatchedSprites`.
+ */
+export declare class BatchedSpritesImpl extends InstancedMeshImpl {
+    /** Marks this as a sprite batch. See `isBatchedSprites`. */
+    readonly isBatchedSprites = true;
+    /**
+     * The quad every member is drawn from, shared by every sprite batch in the process. That is
+     * three's own arrangement, which builds one module-level geometry and lets every `Sprite` share it.
+     *
+     * Seeded here rather than mounted as a child element, because it is not a choice the way an atlas's
+     * quad is. A sprite is a quad, any z is flattened by the projection, and every non-quad
+     * silhouette is a matter of texture alpha. `InstancedMeshImpl` already seeds a throwaway geometry
+     * expecting R3F to replace it, and not rendering a replacement is what makes this one stand.
+     *
+     * Two consequences. Nothing may dispose it, so this class does not override `dispose`. Nothing may
+     * write its bounding sphere, so `getBoundingSphereAt` computes rather than inflating.
+     */
+    geometry: PlaneGeometry;
+    /** Three's own sprite algorithm, reached through a scratch object. See `RaycastingSprites`. */
+    protected raycasting: RaycastingSprites;
+    /**
+     * @param params - Instance capacity. The buffers grow past it on demand.
+     */
+    constructor(params?: InstancedMeshImplParams);
+    /**
+     * A member's anchor. It is how far the pivot sits from the quad's middle, in unit-quad lengths, y
+     * down, and zero is the middle.
+     * @param id - The member to read.
+     * @param target - Receives the result.
+     * @returns The anchor.
+     */
+    getAnchorAt(id: number, target?: Vector2): Vector2;
+    /**
+     * Sets a member's anchor, and invalidates the bounds it decides.
+     * @param id - The member to write.
+     * @param x - How far right of the middle the pivot sits, in unit-quad lengths.
+     * @param y - How far below the middle the pivot sits, in unit-quad lengths.
+     */
+    setAnchorAt(id: number, x: number, y: number): void;
+    /**
+     * Encloses one member: the sphere about its anchor that reaches the quad's furthest corner.
+     *
+     * The anchor is not folded into the matrix, so the matrix translation already is the center and
+     * only the radius needs correcting. That is the exact enclosing sphere for a quad pivoting about
+     * its anchor, up to the max-axis approximation `Sphere.applyMatrix4` already makes on the flat
+     * path. It also holds at every camera angle, which is what a sprite's bounds have to do.
+     *
+     * Two alternatives were rejected. Inflating the shared quad's own bounding sphere replaces a
+     * minimal sphere with a non-minimal one, needs a per-instance factor on a per-geometry field, and
+     * would propagate through every sprite batch in the process. Reading the anchor inside
+     * `InstancedMeshImpl.getBoundingSphereAt` is quad math in a class whose instances are arbitrary
+     * geometry, where `ModelContainer` is a live counter-example.
+     * @param id - The member.
+     * @param target - Receives the result.
+     * @returns The bounds.
+     */
+    getBoundingSphereAt(id: number, target: Sphere): Sphere;
+    onBeforeRender(renderer: WebGLRenderer, scene: Scene, camera: Camera, geometry: BufferGeometry, material: Material, group: Group): void;
+    protected patchMaterial(material: Material): () => void;
+    /**
+     * Clears a member as it is handed out, so a reused slot keeps nothing of the one that held it. The
+     * anchor included, which a caller that writes only a matrix would otherwise inherit.
+     * @param id - The member being handed out.
+     */
+    protected resetInstance(id: number): void;
+}
+/**
+ * Registers the class as an R3F element, by value so the generated key cannot collide with the
+ * `Sprite` three puts in the catalog when the canvas mounts.
+ */
+export declare const BatchedSprites: 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<BatchedSpritesImpl, import("@react-three/fiber").MathProps<BatchedSpritesImpl> & import("@react-three/fiber").ReactProps<BatchedSpritesImpl> & Partial<import("@react-three/fiber").EventHandlers>>>, Omit<import("@react-three/fiber").InstanceProps<BatchedSpritesImpl, typeof BatchedSpritesImpl>, "object">>>>;
+//# sourceMappingURL=BatchedSprites.d.ts.map