@expofp/renderer 3.2.5 → 3.27.0

package/dist/core/lines/FrustumCulling.js

@@ -0,0 +1,85 @@
+import { Vector3, Vector4 } from 'three';
+import { FrustumCulling as InstancedFrustumCulling, } from '../instanced/FrustumCulling';
+/**
+ * Culling for a line batch: each member tested by where it is *drawn*, not where it runs.
+ *
+ * A member's bounds are its two endpoints, which is the segment. What covers pixels is the ribbon the
+ * shader expands around it — after projection, by a width counted in screen pixels — so a member with
+ * both ends off screen still shows if that ribbon crosses the edge, and culling on the ends alone
+ * pops it there.
+ *
+ * The margin is added here rather than to the bounds themselves because it is not a property of the
+ * member: it depends on the camera, and on how far *this* member is from it. Which is also why it is
+ * 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 {
+    instanceSphere(host, id, camera, target) {
+        const sphere = super.instanceSphere(host, id, camera, target);
+        sphere.radius += this.drawnMargin(host, id, camera, sphere);
+        return sphere;
+    }
+    /**
+     * How far past its endpoints one member draws, in the units its bounds are measured in.
+     *
+     * Measured at the far side of the member, since a screen-space width covers more of the plan the
+     * further away it is — the near side would under-pad the end that is further off.
+     * @param host - The batch being culled.
+     * @param id - The member.
+     * @param camera - The camera the width is measured from.
+     * @param sphere - What encloses it, in the batch's own space.
+     * @returns The margin.
+     */
+    drawnMargin(host, id, camera, sphere) {
+        const material = host.material;
+        const held = host.getWidthAt(id);
+        // A member that set no width of its own draws at the material's.
+        const width = held < 0 ? material.linewidth : held;
+        if (width <= 0)
+            return 0;
+        if (material.worldUnits)
+            return width / 2;
+        // Nothing to measure a screen-space width against until the batch has been sized to a viewport,
+        // which it does before this pass runs.
+        if (material.resolution.x === 0)
+            return 0;
+        // The distance is world-space and the radius it pads is the batch's own, which agree because a
+        // line batch is placed by translation — a layer moves one, nothing scales it.
+        _worldCenter.copy(sphere.center).applyMatrix4(host.matrixWorld);
+        const near = camera.near ?? 0;
+        const distance = _cameraPosition
+            .setFromMatrixPosition(camera.matrixWorld)
+            .distanceTo(_worldCenter);
+        return worldSpaceHalfWidth(camera, Math.max(near, distance + sphere.radius), width, material);
+    }
+}
+/**
+ * Half a screen-space width, in plan units, at a distance from the camera.
+ *
+ * Vendored from three's `LineSegments2`, where `getWorldSpaceHalfWidth` is module-private and takes
+ * its width off a module global. Worth vendoring rather than approximating: it is the same formula
+ * three expands a line's *pick* bounds by, so what a batch culls and what it can be picked by are
+ * decided the same way.
+ * @param camera - The camera in use.
+ * @param distance - How far from it the width is measured.
+ * @param width - The full width, in the pixels the material's resolution counts.
+ * @param material - The material, for the resolution those pixels are counted against.
+ * @returns Half the width, in plan units.
+ */
+function worldSpaceHalfWidth(camera, distance, width, material) {
+    // Transform into clip space, adjust the x and y values by the pixel width offset, then transform
+    // back into world space to get world offset. Note clip space is [-1, 1] so full width does not
+    // need to be halved.
+    const resolution = material.resolution;
+    _clipToWorld.set(0, 0, -distance, 1).applyMatrix4(camera.projectionMatrix);
+    _clipToWorld.multiplyScalar(1 / _clipToWorld.w);
+    _clipToWorld.x = width / resolution.width;
+    _clipToWorld.y = width / resolution.height;
+    _clipToWorld.applyMatrix4(camera.projectionMatrixInverse);
+    _clipToWorld.multiplyScalar(1 / _clipToWorld.w);
+    return Math.abs(Math.max(_clipToWorld.x, _clipToWorld.y));
+}
+// Scratch, each filled and consumed within one synchronous call.
+const _worldCenter = new Vector3();
+const _cameraPosition = new Vector3();
+const _clipToWorld = new Vector4();

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

@@ -0,0 +1,44 @@
+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 {
+    /** The material, whose width a member with none of its own draws at. */
+    material: LineMaterial;
+    /**
+     * Reads a member's endpoints.
+     * @param id - The member.
+     * @param start - Receives the segment start.
+     * @param end - Receives the segment end.
+     */
+    getPointsAt(id: number, start: Vector3, end: Vector3): void;
+    /**
+     * A member's own width, or a negative value while it has none.
+     * @param id - The member.
+     * @returns The width.
+     */
+    getWidthAt(id: number): number;
+}
+/**
+ * Picking for a line batch: each member tested in screen space, at the width it actually draws at.
+ *
+ * A line is picked by where it is *drawn*, not merely where it runs — a 10px route has to answer
+ * anywhere on its ribbon, not only along its centerline — and that ribbon is expanded after
+ * projection, so the test needs the camera and the viewport. Three has the math, in
+ * `LineSegments2.raycast`, and this is how a batch reaches it: one scratch line, holding one
+ * segment, stood up per member.
+ *
+ * Only {@link prepareInstance} differs from the instanced sweep this inherits. The whole-batch
+ * early-out, the frustum-culled candidates, the visibility test and naming the member each hit
+ * belongs to are the same questions for a segment as for a quad — and answering them in world space
+ * is what lets this inherit them rather than restate them, since three's screen-space math projects
+ * the ray through the camera and needs it there.
+ *
+ * The width is the one thing three has nowhere to read per segment: it is material state. So the
+ * 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;
+}
+//# sourceMappingURL=Raycasting.d.ts.map

package/dist/core/lines/Raycasting.js

@@ -0,0 +1,91 @@
+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';
+/**
+ * Picking for a line batch: each member tested in screen space, at the width it actually draws at.
+ *
+ * A line is picked by where it is *drawn*, not merely where it runs — a 10px route has to answer
+ * anywhere on its ribbon, not only along its centerline — and that ribbon is expanded after
+ * projection, so the test needs the camera and the viewport. Three has the math, in
+ * `LineSegments2.raycast`, and this is how a batch reaches it: one scratch line, holding one
+ * segment, stood up per member.
+ *
+ * Only {@link prepareInstance} differs from the instanced sweep this inherits. The whole-batch
+ * early-out, the frustum-culled candidates, the visibility test and naming the member each hit
+ * belongs to are the same questions for a segment as for a quad — and answering them in world space
+ * is what lets this inherit them rather than restate them, since three's screen-space math projects
+ * the ray through the camera and needs it there.
+ *
+ * The width is the one thing three has nowhere to read per segment: it is material state. So the
+ * 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 {
+    prepareInstance(host, objectIndex) {
+        host.getPointsAt(objectIndex, _start, _end);
+        // Written straight into the interleaved buffer the geometry already owns. `setPositions` would
+        // allocate that buffer and both attribute views over it again, per member per pick.
+        _segment.set([_start.x, _start.y, _start.z, _end.x, _end.y, _end.z]);
+        encloseSegment();
+        const held = host.getWidthAt(objectIndex);
+        _material.linewidth = held < 0 ? host.material.linewidth : held;
+        _material.worldUnits = host.material.worldUnits;
+        _material.resolution.copy(host.material.resolution);
+        // The batch's own placement. A per-instance transform, if a line ever carries one, composes in
+        // here — which is why this hands back a placed object rather than a geometry.
+        _line.matrixWorld.copy(host.matrixWorld);
+        return _line;
+    }
+}
+/**
+ * Fills the scratch geometry's bounds from the segment just written into it.
+ *
+ * Written rather than invalidated: three computes them when it finds them null, and both its
+ * `LineSegmentsGeometry` implementations allocate as they do — where a segment's box and sphere are
+ * two lines of arithmetic over the endpoints already in hand.
+ */
+function encloseSegment() {
+    const geometry = _line.geometry;
+    const box = (geometry.boundingBox ??= new Box3()).makeEmpty();
+    box.expandByPoint(_start).expandByPoint(_end);
+    const sphere = (geometry.boundingSphere ??= new Sphere());
+    box.getCenter(sphere.center);
+    sphere.radius = _start.distanceTo(_end) / 2;
+}
+/**
+ * A geometry holding exactly one segment, whose endpoints are rewritten per test.
+ * @returns The geometry.
+ */
+function makeSegmentGeometry() {
+    const geometry = new LineSegmentsGeometry();
+    // The only way to get the interleaved buffer and its two attribute views built; what it is filled
+    // with here is irrelevant, since every test overwrites it.
+    geometry.setPositions(new Float32Array(FLOATS_PER_SEGMENT));
+    return geometry;
+}
+/**
+ * The buffer a segment geometry holds its endpoints in.
+ * @param geometry - The geometry to read.
+ * @returns The endpoints, interleaved as `xyz xyz`.
+ */
+function segmentArrayOf(geometry) {
+    const start = geometry.getAttribute('instanceStart');
+    return start.data.array;
+}
+/** Floats one segment occupies: `x, y, z` for each end. */
+const FLOATS_PER_SEGMENT = 6;
+/**
+ * The line every member is tested through.
+ *
+ * One object rather than one per member, for the reason the instanced sweep keeps a scratch mesh:
+ * what differs between members is the data, and three's raycast reads all of it off the object it is
+ * called on. Never rendered, so neither its geometry nor its material holds anything to free — and
+ * its material is its own, so a test writes no state the batch is drawing with.
+ */
+const _line = new LineSegments2(makeSegmentGeometry(), new LineMaterial());
+const _material = _line.material;
+const _segment = segmentArrayOf(_line.geometry);
+const _start = new Vector3();
+const _end = new Vector3();

package/dist/core/lines/lines-material.d.ts

@@ -0,0 +1,47 @@
+import { type WebGLProgramParametersWithUniforms } from 'three';
+import { type LineMaterial } from 'three/addons/lines/LineMaterial.js';
+/**
+ * The material side of a line batch: what three's line shader has to become before it can draw
+ * members that differ in width and tint.
+ *
+ * Free functions holding no state, as `instanced-material.ts` is — {@link patchLineMaterial} hands
+ * back its own undo rather than parking it on the caller.
+ *
+ * It lives here rather than in the material component for the reason the instancing patch does: the
+ * material is three's, and a `<LineMaterial>` has no business knowing whether it is drawing a batch
+ * or a plain `LineSegments2`. What it must keep working with is either.
+ */
+/** The per-instance segment start, named for the attribute three's line shader reads. */
+export declare const START_UNIFORM = "instanceStart";
+/** The per-instance segment end, named for the attribute three's line shader reads. */
+export declare const END_UNIFORM = "instanceEnd";
+/** The per-instance width. Distinct from three's `linewidth`, which it falls back to. */
+export declare const WIDTH_UNIFORM = "lineWidth";
+/**
+ * Wraps a material so the programs it compiles read a batch's per-instance endpoints, width and tint.
+ *
+ * Installed *inside* the wrap an instanced draw puts on, so that by the time this runs the prologue
+ * it reads is already in the shader — which is why the batch installs this one first.
+ * @param material - The material the batch is about to draw with.
+ * @returns Restores the material exactly as it arrived. Call it once, after the draw.
+ */
+export declare function patchLineMaterial(material: LineMaterial): () => void;
+/**
+ * Points three's line shader at a batch's per-instance endpoints, width and tint.
+ *
+ * Deliberately small, and small in a particular way: the endpoints are *not* rewritten anywhere. The
+ * batch declares them under the names three's own shader already reads — `instanceStart` and
+ * `instanceEnd` — so the uniform prologue lands two locals of `main` that shadow the attributes, and
+ * every line of three's projection, near-plane trimming and cap math goes on reading what it always
+ * read. What is left is to drop the attribute declarations that no longer feed anything, resolve the
+ * width the shader expands by, and carry the instance color's alpha into an output that drops it.
+ *
+ * Does nothing until a batch's prologue is in the shader — the guard `applyDim` uses, and for the
+ * same reason: a material may be compiled for something that is not a batch at all, and the GLSL
+ * below reads names only the prologue brings into scope.
+ * @param shader - The program parameters to edit.
+ * @returns Whether the shader was patched.
+ * @throws {Error} If the prologue is present but the shader around it has moved what this anchors on.
+ */
+export declare function patchLineShader(shader: WebGLProgramParametersWithUniforms): boolean;
+//# sourceMappingURL=lines-material.d.ts.map

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

@@ -0,0 +1,115 @@
+import { openMain, replaceAnchor } from '../shader-source';
+/**
+ * The material side of a line batch: what three's line shader has to become before it can draw
+ * members that differ in width and tint.
+ *
+ * Free functions holding no state, as `instanced-material.ts` is — {@link patchLineMaterial} hands
+ * back its own undo rather than parking it on the caller.
+ *
+ * It lives here rather than in the material component for the reason the instancing patch does: the
+ * material is three's, and a `<LineMaterial>` has no business knowing whether it is drawing a batch
+ * or a plain `LineSegments2`. What it must keep working with is either.
+ */
+/** The per-instance segment start, named for the attribute three's line shader reads. */
+export const START_UNIFORM = 'instanceStart';
+/** The per-instance segment end, named for the attribute three's line shader reads. */
+export const END_UNIFORM = 'instanceEnd';
+/** The per-instance width. Distinct from three's `linewidth`, which it falls back to. */
+export const WIDTH_UNIFORM = 'lineWidth';
+/**
+ * Wraps a material so the programs it compiles read a batch's per-instance endpoints, width and tint.
+ *
+ * Installed *inside* the wrap an instanced draw puts on, so that by the time this runs the prologue
+ * it reads is already in the shader — which is why the batch installs this one first.
+ * @param material - The material the batch is about to draw with.
+ * @returns Restores the material exactly as it arrived. Call it once, after the draw.
+ */
+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`. */
+    const baseOnBeforeCompile = material.onBeforeCompile;
+    material.onBeforeCompile = (shader, renderer) => {
+        patchLineShader(shader);
+        baseOnBeforeCompile.call(material, shader, renderer);
+    };
+    return () => {
+        material.onBeforeCompile = baseOnBeforeCompile;
+    };
+}
+/**
+ * Puts the chunk three seeds `vColor` in into the material's own source, once.
+ *
+ * That chunk is the only place an instanced draw has to fold a per-instance color in, and the line
+ * shader is the one stock material that does not include it. It goes into the *source* rather than
+ * into a compiling shader because the instancing injection looks for it before the patch below runs,
+ * and finding it is what makes it bind the colors texture at all.
+ *
+ * Left in place afterwards rather than undone with the wrap: it expands to nothing without the color
+ * defines, which only an instanced draw sets — so the material still draws a plain `LineSegments2` —
+ * and putting it back would change the source three keys its program cache by, on every draw.
+ * @param material - The material to seed.
+ */
+function seedColorChunk(material) {
+    if (material.vertexShader.includes(COLOR_VERTEX_CHUNK))
+        return;
+    material.vertexShader = openMain(material.vertexShader, COLOR_VERTEX_CHUNK);
+}
+/**
+ * Points three's line shader at a batch's per-instance endpoints, width and tint.
+ *
+ * Deliberately small, and small in a particular way: the endpoints are *not* rewritten anywhere. The
+ * batch declares them under the names three's own shader already reads — `instanceStart` and
+ * `instanceEnd` — so the uniform prologue lands two locals of `main` that shadow the attributes, and
+ * every line of three's projection, near-plane trimming and cap math goes on reading what it always
+ * read. What is left is to drop the attribute declarations that no longer feed anything, resolve the
+ * width the shader expands by, and carry the instance color's alpha into an output that drops it.
+ *
+ * Does nothing until a batch's prologue is in the shader — the guard `applyDim` uses, and for the
+ * same reason: a material may be compiled for something that is not a batch at all, and the GLSL
+ * below reads names only the prologue brings into scope.
+ * @param shader - The program parameters to edit.
+ * @returns Whether the shader was patched.
+ * @throws {Error} If the prologue is present but the shader around it has moved what this anchors on.
+ */
+export function patchLineShader(shader) {
+    const vertex = shader.vertexShader;
+    if (!vertex.includes(WIDTH_UNIFORM))
+        return false;
+    // Two statements, in this order for a reason: the first reads the material uniform while it is
+    // still the only `linewidth` in scope, and the second declares the local that takes over from
+    // there on. Nothing downstream is rewritten, which is the point — three's own `offset *= linewidth`
+    // (screen space) and `float hw = linewidth * 0.5` (world units) both keep working, so flipping
+    // `material.worldUnits` needs no change here. The fallback triggers on a *negative* width, not on
+    // zero, so a member given zero expands to no area and draws nothing, which is what asking for a
+    // zero-width line means.
+    const resolveWidth = /* glsl */ `
+    float materialLineWidth = linewidth;
+    float linewidth = ${WIDTH_UNIFORM} < 0.0 ? materialLineWidth : ${WIDTH_UNIFORM};
+  `;
+    // The attributes stand unused once the prologue shadows them, so a compiler would drop them anyway
+    // — but an attribute that looks like the data source and is not would be read as one. Dropped with
+    // a plain replace, because a three that stopped declaring them is not a three this breaks on.
+    shader.vertexShader = replaceAnchor(vertex.replace(ATTRIBUTE_DECLARATIONS, ''), WIDTH_ANCHOR, `${resolveWidth}\n${WIDTH_ANCHOR}`);
+    // The instance color reaches `diffuseColor` through three's own `<color_fragment>`, which the line
+    // shader does include — but only its rgb survives, because the output discards the diffuse alpha
+    // and carries a coverage of its own. Folding the tint's alpha into that is all that is left.
+    shader.fragmentShader = replaceAnchor(shader.fragmentShader, FRAGMENT_OUTPUT, 
+    /* glsl */ `gl_FragColor = vec4( diffuseColor.rgb, alpha * vColor.a );`);
+    return true;
+}
+/**
+ * The attribute declarations the per-instance endpoints replace. Matched loosely, because their
+ * indentation is three's and not ours to depend on.
+ */
+const ATTRIBUTE_DECLARATIONS = new RegExp(`attribute\\s+vec3\\s+${START_UNIFORM}\\s*;\\s*attribute\\s+vec3\\s+${END_UNIFORM}\\s*;`);
+/**
+ * Where the width resolve goes: ahead of the first statement of three's own `main`, which puts it
+ * after the prologue that declares the per-instance width and before everything that expands by it.
+ */
+const WIDTH_ANCHOR = /*glsl*/ `float aspect = resolution.x / resolution.y;`;
+/** The line shader's output, which the instance color's alpha is folded into. */
+const FRAGMENT_OUTPUT = /*glsl*/ `gl_FragColor = vec4( diffuseColor.rgb, alpha );`;
+/** Three's per-vertex color chunk, which an instanced draw substitutes its own for. */
+const COLOR_VERTEX_CHUNK = /*glsl*/ `#include <color_vertex>`;

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

@@ -0,0 +1,50 @@
+/**
+ * Editing a shader's source around the one construct it cannot be missing: the opening of `main`.
+ *
+ * Every injection here used to key on a chunk `#include` instead — the instancing declarations rode
+ * on `batching_pars_vertex`, which three includes in every mesh shader. That only holds for the
+ * materials three itself builds: a hand-written `ShaderMaterial` (three's `LineMaterial` among them)
+ * or a shader a glTF extension supplies may include no chunk at all, and a patch anchored on one that
+ * is not there silently does nothing — leaving a program that references identifiers nothing
+ * declared. `main` is the anchor that survives both.
+ *
+ * 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.
+ */
+/**
+ * Declares GLSL above `main`, where file-scope declarations belong — samplers, varyings, functions.
+ * @param source - The shader source.
+ * @param glsl - The declarations to add.
+ * @returns The source, with the declarations ahead of `main`.
+ * @throws {Error} If the source has no `main`.
+ */
+export declare function declareBeforeMain(source: string, glsl: string): string;
+/**
+ * Inserts GLSL as `main`'s first statements.
+ *
+ * Successive calls each insert at the top, so **the last caller runs first**. That is what lets a
+ * value be supplied to a prologue already injected: the instanced meshes fetch their per-instance
+ * uniforms by an index resolved from `gl_InstanceID`, and the resolve is written afterwards
+ * precisely so it lands ahead of the fetch that reads it.
+ * @param source - The shader source.
+ * @param glsl - The statements to run first.
+ * @returns The source, with the statements opening `main`.
+ * @throws {Error} If the source has no `main`.
+ */
+export declare function openMain(source: string, glsl: string): string;
+/**
+ * Rewrites the one place a shader spells `anchor`.
+ *
+ * For a patch that has to land somewhere a shader's *own* text decides — before the statement that
+ * reads a value, or over the line that outputs one. Throws for the same reason the two above do: an
+ * anchor that has moved leaves the shader compiling and drawing, just not the way the patch meant,
+ * and that is the failure worth being loud about.
+ * @param source - The shader source.
+ * @param anchor - The text to rewrite. Keep it in the replacement to insert around it.
+ * @param glsl - What takes its place.
+ * @returns The rewritten source.
+ * @throws {Error} If the source does not contain the anchor.
+ */
+export declare function replaceAnchor(source: string, anchor: string, glsl: string): string;
+//# sourceMappingURL=shader-source.d.ts.map

package/dist/core/shader-source.js

@@ -0,0 +1,84 @@
+/**
+ * Editing a shader's source around the one construct it cannot be missing: the opening of `main`.
+ *
+ * Every injection here used to key on a chunk `#include` instead — the instancing declarations rode
+ * on `batching_pars_vertex`, which three includes in every mesh shader. That only holds for the
+ * materials three itself builds: a hand-written `ShaderMaterial` (three's `LineMaterial` among them)
+ * or a shader a glTF extension supplies may include no chunk at all, and a patch anchored on one that
+ * is not there silently does nothing — leaving a program that references identifiers nothing
+ * declared. `main` is the anchor that survives both.
+ *
+ * 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.
+ */
+/**
+ * Declares GLSL above `main`, where file-scope declarations belong — samplers, varyings, functions.
+ * @param source - The shader source.
+ * @param glsl - The declarations to add.
+ * @returns The source, with the declarations ahead of `main`.
+ * @throws {Error} If the source has no `main`.
+ */
+export function declareBeforeMain(source, glsl) {
+    return rewriteMain(source, (main) => `${glsl}\n${main}`);
+}
+/**
+ * Inserts GLSL as `main`'s first statements.
+ *
+ * Successive calls each insert at the top, so **the last caller runs first**. That is what lets a
+ * value be supplied to a prologue already injected: the instanced meshes fetch their per-instance
+ * uniforms by an index resolved from `gl_InstanceID`, and the resolve is written afterwards
+ * precisely so it lands ahead of the fetch that reads it.
+ * @param source - The shader source.
+ * @param glsl - The statements to run first.
+ * @returns The source, with the statements opening `main`.
+ * @throws {Error} If the source has no `main`.
+ */
+export function openMain(source, glsl) {
+    return rewriteMain(source, (main) => `${main}\n${glsl}`);
+}
+/**
+ * Rewrites the one place a shader spells `anchor`.
+ *
+ * For a patch that has to land somewhere a shader's *own* text decides — before the statement that
+ * reads a value, or over the line that outputs one. Throws for the same reason the two above do: an
+ * anchor that has moved leaves the shader compiling and drawing, just not the way the patch meant,
+ * and that is the failure worth being loud about.
+ * @param source - The shader source.
+ * @param anchor - The text to rewrite. Keep it in the replacement to insert around it.
+ * @param glsl - What takes its place.
+ * @returns The rewritten source.
+ * @throws {Error} If the source does not contain the anchor.
+ */
+export function replaceAnchor(source, anchor, glsl) {
+    const at = source.indexOf(anchor);
+    if (at < 0)
+        throw new Error(`shader-source: the shader has no "${anchor}" to rewrite.`);
+    return source.slice(0, at) + glsl + source.slice(at + anchor.length);
+}
+/**
+ * Rewrites the first opening of `main`, splicing rather than replacing — so a `$` in the injected
+ * GLSL cannot be read as a replacement pattern.
+ * @param source - The shader source.
+ * @param rewrite - Receives the matched opening verbatim, whatever way it was spelled; returns what
+ *   takes its place.
+ * @returns The rewritten source.
+ * @throws {Error} If the source has no `main`.
+ */
+function rewriteMain(source, rewrite) {
+    const found = MAIN.exec(source);
+    if (!found) {
+        throw new Error('shader-source: the shader has no "void main()" to inject into.');
+    }
+    const main = found[0];
+    return source.slice(0, found.index) + rewrite(main) + source.slice(found.index + main.length);
+}
+/**
+ * The opening of `main`, spelled every way GLSL allows it: with or without the redundant `void`
+ * parameter, and with whitespace — a newline included — wherever it is legal.
+ *
+ * Neither anchored nor global, so it finds the first one, which is the one to patch: troika renames
+ * the shader's original `main` to `troikaOrigMain` and writes a new one, and a patch belongs in the
+ * new one. The rename also puts `main` where no whitespace precedes it, so this does not match it.
+ */
+const MAIN = /void\s+main\s*\(\s*(?:void)?\s*\)\s*\{/;