@driftengine/core 3.61.0

package/dist/render/lightVolumeDraw.d.ts

@@ -0,0 +1,132 @@
+import type { ReadonlyMat4 } from 'gl-matrix';
+import type { Atmosphere } from './atmosphere.ts';
+/**
+ * Where the camera stands relative to a volume of light, decided once for both backends.
+ *
+ * **The interesting half of `drawLightVolume` is arithmetic, not binding.** The march runs
+ * entirely in the volume's own space, so the camera has to arrive there rather than the other
+ * way round — one inverse per draw against one transform per fragment — and whether it arrives
+ * *inside* the cone decides which half of the hull is kept.
+ *
+ * Both answers are a rule rather than a binding, which is why they are here and not in either
+ * renderer. A second copy of the inside test is a beam that vanishes when somebody walks into
+ * it on one backend and not the other, and nothing would raise: the frame is a plausible one
+ * either way. That is the 2026-08-13 rule in `AGENTS.md`, and `resolveAtmosphere`,
+ * `resolvePointLights` and `resolveWater` are the same split applied to their own passes.
+ */
+/**
+ * A stored depth in [0,1] back to the clip space `viewProjection` was built in, which is [-1,1].
+ *
+ * The march's scene-depth clamp feeds the shader `vec4(uv * 2 - 1, stored, 1)` and multiplies it
+ * by `inverse(viewProjection * model)`, which is built from the **raw** matrix on both backends.
+ * `uv` is `gl_FragCoord.xy * uInvViewport`, so what arrives is a screen position and a depth, and
+ * this is what turns the depth half of it into the NDC z that inverse expects.
+ *
+ * Here rather than in either renderer for the reason at the top of this file: it is a rule, and
+ * two copies of a rule is a beam that clamps differently depending on who drew it.
+ *
+ * Column major: (x, y, z, 1) -> (x, y, 2z - 1, 1) conventionally, and (x, y, 1 - 2z, 1) once
+ * depth is reversed, because a reversed buffer stores `0.5 - 0.5z` and this is its inverse.
+ *
+ * **This one is for a backend whose framebuffer Y runs up. See `DEPTH_01_TO_CLIP_Y_DOWN`, which
+ * is the same remap for one whose Y runs down, and read its derivation before touching either.**
+ */
+export declare const DEPTH_01_TO_CLIP: ReadonlyMat4;
+/**
+ * The same remap, **and a Y flip**, for a backend whose framebuffer Y runs down.
+ *
+ * **The two backends do not share one matrix here, and the argument that they could is the
+ * defect this constant exists to close.** It ran like this: WebGPU's framebuffer `v` is top-down
+ * so `2v - 1 = -ndc.y`, and the scene was drawn through a `CLIP_CORRECTION` that negates Y, so
+ * the two negations cancel and the raw view-projection's own NDC comes back out. Every step of
+ * that is true except the one it leaves out.
+ *
+ * **The generated shaders flip Y a second time.** `scripts/wgsl.ts` runs naga without
+ * `--keep-coordinate-space`, so every WGSL vertex entry point this engine ships ends with
+ * `gl_Position.y = -gl_Position.y` — check any file under `shaders/generated`, they all carry
+ * it. That is what makes the frame land the right way up *despite* `CLIP_CORRECTION`, and it is
+ * why `sky.ts` needs `INVERSE_CLIP_CORRECTION` to unproject the clip position it wrote itself.
+ * So the Y the rasteriser actually used is the raw matrix's Y, not its negation, and `2v - 1`
+ * is the negation of the value the clamp has to be handed.
+ *
+ * **What one missing negation does to a beam**: the depth fetched is the right pixel's, and the
+ * screen position it is unprojected through is that pixel mirrored about the middle of the frame.
+ * The reconstructed point sits at the true distance along the mirrored ray, so projecting it back
+ * onto the true one shortens it by `cos(2t)`, where `t` is the vertical angle the pixel sits at
+ * off the view axis. Exact along the frame's horizontal centre line, zero at 45 degrees off it,
+ * and negative past that — which discards the fragment outright.
+ *
+ * **Measured before it was believed**, by writing the reconstructed distance out as colour and
+ * photographing `demo/dev/volume.html` on both backends: against a scene the clamp could reach,
+ * the ratio of the two ran 0.927, 0.941, 0.964, 0.968, 0.986, 0.987 down the beam where
+ * `cos(2t)` is 0.911, 0.934, 0.954, 0.970, 0.983, 0.993. Five hypotheses formed by reading the
+ * shader were wrong before this one was formed by reading a photograph.
+ *
+ * A landscape frame at a 48-degree vertical field of view never gets far enough off axis for
+ * this to be more than a dim band on the floor, which is why the harness page agreed to within
+ * a few thousand pixels for four capture rounds. A portrait one, which is what one consumer
+ * composes, reaches the angles that take the top off a shaft.
+ *
+ * Column major: (x, y, z, 1) -> (x, -y, 2z - 1, 1).
+ */
+export declare const DEPTH_01_TO_CLIP_Y_DOWN: ReadonlyMat4;
+/** The two things a light-volume draw has to work out before it can bind anything. */
+export interface ResolvedLightVolume {
+    /** The camera in the volume's own space, which is the frame the whole march happens in. */
+    readonly cameraLocal: Float32Array;
+    /**
+     * Whether the camera is inside the cone.
+     *
+     * From outside, the hull's front faces are where a view ray enters it. From inside they are
+     * behind the viewer, so keeping them makes a beam disappear the moment somebody steps into
+     * it — which the pass this replaced avoided by culling nothing at all, an option a closed
+     * hull does not have: every pixel would then be marched twice and arrive at double
+     * brightness.
+     */
+    inside: boolean;
+}
+export declare function createResolvedLightVolume(): ResolvedLightVolume;
+/**
+ * Put the camera in the volume's space and decide which half of the hull survives.
+ *
+ * `length` and `spread` are the *draw call's* numbers rather than the geometry's, which is the
+ * same pair the shader fades against — so a hull built wider than the aperture it is drawn
+ * with is culled by the aperture, exactly as it is shaded by it.
+ *
+ * **A singular model matrix leaves the previous answer in place rather than raising.** That is
+ * `mat4.invert`'s own behaviour and it is kept: this runs in the frame loop, where `AGENTS.md`
+ * forbids throwing, and a degenerate transform means the caller has already collapsed the hull
+ * to nothing, so there are no pixels for a stale camera position to be wrong about.
+ */
+export declare function resolveLightVolume(model: ReadonlyMat4, cameraPosition: ArrayLike<number>, length: number, spread: number, out: ResolvedLightVolume): ResolvedLightVolume;
+/**
+ * How much of a beam the air is thick enough to show, from the medium it stands in.
+ *
+ * **The shader's own header says a beam is more visible in fog and nothing made it so.** Every
+ * term in that program is deliberately unlit, unfogged and unscaled by night, for reasons that
+ * file records at length and that are all correct: fog *dims* a surface, and dimming the thing
+ * that is being lit by ninety metres of medium is what made the first two attempts vanish. What
+ * was left out is the other direction. A headlight cone in clear air and the same cone in thick
+ * fog were the same picture, because `strength` is a number the caller authored once and nothing
+ * between it and the frame knew what the weather was.
+ *
+ * That was reported from outside as the largest gap in one of eight weather states, and the
+ * criterion it fails is worth quoting: fog should change how the road is *perceived* rather than
+ * filter the frame. At night in thick fog the beam **is** the road. Without it, driving in fog is
+ * driving in a grey box.
+ *
+ * **A multiplier on the CPU rather than a uniform**, which is the reason this is four lines: the
+ * shader clamps `uStrength` to 1, so a gain could only ever go downward anyway, and the whole
+ * effect is one number per draw rather than one per fragment. Nothing recompiles, nothing is
+ * bound, and both backends cannot disagree because there is only this function — which is what
+ * this file is for.
+ *
+ * **Density is taken where the volume is, not where the camera is.** `fogDensityAtEye` reads a
+ * height against the haze's own falloff, and a car in a valley of fog with the camera on the
+ * ridge above it is exactly the case that distinction exists for. The height comes from the model
+ * matrix's translation, so a beam attached to something moving carries its own weather.
+ *
+ * Returns 1 where the air is at least as thick as `fullAtDensity`, which keeps this incapable of
+ * brightening a beam past what its author asked for.
+ */
+export declare function volumeMediumGain(atmosphere: Atmosphere, model: ReadonlyMat4, fullAtDensity: number): number;

package/dist/render/lightVolumeDraw.js

@@ -0,0 +1,181 @@
+import { REVERSED_DEPTH } from './depthConvention.js';
+import { mat4 } from 'gl-matrix';
+import { fogDensityAtEye } from './atmosphere.js';
+/**
+ * Where the camera stands relative to a volume of light, decided once for both backends.
+ *
+ * **The interesting half of `drawLightVolume` is arithmetic, not binding.** The march runs
+ * entirely in the volume's own space, so the camera has to arrive there rather than the other
+ * way round — one inverse per draw against one transform per fragment — and whether it arrives
+ * *inside* the cone decides which half of the hull is kept.
+ *
+ * Both answers are a rule rather than a binding, which is why they are here and not in either
+ * renderer. A second copy of the inside test is a beam that vanishes when somebody walks into
+ * it on one backend and not the other, and nothing would raise: the frame is a plausible one
+ * either way. That is the 2026-08-13 rule in `AGENTS.md`, and `resolveAtmosphere`,
+ * `resolvePointLights` and `resolveWater` are the same split applied to their own passes.
+ */
+/**
+ * A stored depth in [0,1] back to the clip space `viewProjection` was built in, which is [-1,1].
+ *
+ * The march's scene-depth clamp feeds the shader `vec4(uv * 2 - 1, stored, 1)` and multiplies it
+ * by `inverse(viewProjection * model)`, which is built from the **raw** matrix on both backends.
+ * `uv` is `gl_FragCoord.xy * uInvViewport`, so what arrives is a screen position and a depth, and
+ * this is what turns the depth half of it into the NDC z that inverse expects.
+ *
+ * Here rather than in either renderer for the reason at the top of this file: it is a rule, and
+ * two copies of a rule is a beam that clamps differently depending on who drew it.
+ *
+ * Column major: (x, y, z, 1) -> (x, y, 2z - 1, 1) conventionally, and (x, y, 1 - 2z, 1) once
+ * depth is reversed, because a reversed buffer stores `0.5 - 0.5z` and this is its inverse.
+ *
+ * **This one is for a backend whose framebuffer Y runs up. See `DEPTH_01_TO_CLIP_Y_DOWN`, which
+ * is the same remap for one whose Y runs down, and read its derivation before touching either.**
+ */
+export const DEPTH_01_TO_CLIP = new Float32Array([
+    1,
+    0,
+    0,
+    0,
+    0,
+    1,
+    0,
+    0,
+    0,
+    0,
+    REVERSED_DEPTH ? -2 : 2,
+    0,
+    0,
+    0,
+    REVERSED_DEPTH ? 1 : -1,
+    1,
+]);
+/**
+ * The same remap, **and a Y flip**, for a backend whose framebuffer Y runs down.
+ *
+ * **The two backends do not share one matrix here, and the argument that they could is the
+ * defect this constant exists to close.** It ran like this: WebGPU's framebuffer `v` is top-down
+ * so `2v - 1 = -ndc.y`, and the scene was drawn through a `CLIP_CORRECTION` that negates Y, so
+ * the two negations cancel and the raw view-projection's own NDC comes back out. Every step of
+ * that is true except the one it leaves out.
+ *
+ * **The generated shaders flip Y a second time.** `scripts/wgsl.ts` runs naga without
+ * `--keep-coordinate-space`, so every WGSL vertex entry point this engine ships ends with
+ * `gl_Position.y = -gl_Position.y` — check any file under `shaders/generated`, they all carry
+ * it. That is what makes the frame land the right way up *despite* `CLIP_CORRECTION`, and it is
+ * why `sky.ts` needs `INVERSE_CLIP_CORRECTION` to unproject the clip position it wrote itself.
+ * So the Y the rasteriser actually used is the raw matrix's Y, not its negation, and `2v - 1`
+ * is the negation of the value the clamp has to be handed.
+ *
+ * **What one missing negation does to a beam**: the depth fetched is the right pixel's, and the
+ * screen position it is unprojected through is that pixel mirrored about the middle of the frame.
+ * The reconstructed point sits at the true distance along the mirrored ray, so projecting it back
+ * onto the true one shortens it by `cos(2t)`, where `t` is the vertical angle the pixel sits at
+ * off the view axis. Exact along the frame's horizontal centre line, zero at 45 degrees off it,
+ * and negative past that — which discards the fragment outright.
+ *
+ * **Measured before it was believed**, by writing the reconstructed distance out as colour and
+ * photographing `demo/dev/volume.html` on both backends: against a scene the clamp could reach,
+ * the ratio of the two ran 0.927, 0.941, 0.964, 0.968, 0.986, 0.987 down the beam where
+ * `cos(2t)` is 0.911, 0.934, 0.954, 0.970, 0.983, 0.993. Five hypotheses formed by reading the
+ * shader were wrong before this one was formed by reading a photograph.
+ *
+ * A landscape frame at a 48-degree vertical field of view never gets far enough off axis for
+ * this to be more than a dim band on the floor, which is why the harness page agreed to within
+ * a few thousand pixels for four capture rounds. A portrait one, which is what one consumer
+ * composes, reaches the angles that take the top off a shaft.
+ *
+ * Column major: (x, y, z, 1) -> (x, -y, 2z - 1, 1).
+ */
+export const DEPTH_01_TO_CLIP_Y_DOWN = new Float32Array([
+    1,
+    0,
+    0,
+    0,
+    0,
+    -1,
+    0,
+    0,
+    0,
+    0,
+    REVERSED_DEPTH ? -2 : 2,
+    0,
+    0,
+    0,
+    REVERSED_DEPTH ? 1 : -1,
+    1,
+]);
+export function createResolvedLightVolume() {
+    return { cameraLocal: new Float32Array(3), inside: false };
+}
+/**
+ * Scratch for the inverse model matrix. Module scope because this is a per-frame path and
+ * `AGENTS.md` allows no allocation in one.
+ */
+const scratchInverse = mat4.create();
+/**
+ * Put the camera in the volume's space and decide which half of the hull survives.
+ *
+ * `length` and `spread` are the *draw call's* numbers rather than the geometry's, which is the
+ * same pair the shader fades against — so a hull built wider than the aperture it is drawn
+ * with is culled by the aperture, exactly as it is shaded by it.
+ *
+ * **A singular model matrix leaves the previous answer in place rather than raising.** That is
+ * `mat4.invert`'s own behaviour and it is kept: this runs in the frame loop, where `AGENTS.md`
+ * forbids throwing, and a degenerate transform means the caller has already collapsed the hull
+ * to nothing, so there are no pixels for a stale camera position to be wrong about.
+ */
+export function resolveLightVolume(model, cameraPosition, length, spread, out) {
+    mat4.invert(scratchInverse, model);
+    const m = scratchInverse;
+    const x = cameraPosition[0] ?? 0;
+    const y = cameraPosition[1] ?? 0;
+    const z = cameraPosition[2] ?? 0;
+    const local = out.cameraLocal;
+    local[0] = (m[0] ?? 0) * x + (m[4] ?? 0) * y + (m[8] ?? 0) * z + (m[12] ?? 0);
+    local[1] = (m[1] ?? 0) * x + (m[5] ?? 0) * y + (m[9] ?? 0) * z + (m[13] ?? 0);
+    local[2] = (m[2] ?? 0) * x + (m[6] ?? 0) * y + (m[10] ?? 0) * z + (m[14] ?? 0);
+    const axial = local[2] ?? 0;
+    const radial = Math.hypot(local[0] ?? 0, local[1] ?? 0);
+    out.inside = axial >= 0 && axial <= length && radial <= spread * axial;
+    return out;
+}
+/**
+ * How much of a beam the air is thick enough to show, from the medium it stands in.
+ *
+ * **The shader's own header says a beam is more visible in fog and nothing made it so.** Every
+ * term in that program is deliberately unlit, unfogged and unscaled by night, for reasons that
+ * file records at length and that are all correct: fog *dims* a surface, and dimming the thing
+ * that is being lit by ninety metres of medium is what made the first two attempts vanish. What
+ * was left out is the other direction. A headlight cone in clear air and the same cone in thick
+ * fog were the same picture, because `strength` is a number the caller authored once and nothing
+ * between it and the frame knew what the weather was.
+ *
+ * That was reported from outside as the largest gap in one of eight weather states, and the
+ * criterion it fails is worth quoting: fog should change how the road is *perceived* rather than
+ * filter the frame. At night in thick fog the beam **is** the road. Without it, driving in fog is
+ * driving in a grey box.
+ *
+ * **A multiplier on the CPU rather than a uniform**, which is the reason this is four lines: the
+ * shader clamps `uStrength` to 1, so a gain could only ever go downward anyway, and the whole
+ * effect is one number per draw rather than one per fragment. Nothing recompiles, nothing is
+ * bound, and both backends cannot disagree because there is only this function — which is what
+ * this file is for.
+ *
+ * **Density is taken where the volume is, not where the camera is.** `fogDensityAtEye` reads a
+ * height against the haze's own falloff, and a car in a valley of fog with the camera on the
+ * ridge above it is exactly the case that distinction exists for. The height comes from the model
+ * matrix's translation, so a beam attached to something moving carries its own weather.
+ *
+ * Returns 1 where the air is at least as thick as `fullAtDensity`, which keeps this incapable of
+ * brightening a beam past what its author asked for.
+ */
+export function volumeMediumGain(atmosphere, model, fullAtDensity) {
+    if (!(fullAtDensity > 0))
+        return 1;
+    const density = fogDensityAtEye(atmosphere, model[13] ?? 0);
+    if (!(density > 0))
+        return 0;
+    const gain = density / fullAtDensity;
+    return gain >= 1 ? 1 : gain;
+}

package/dist/render/lineBatch.d.ts

@@ -0,0 +1,60 @@
+import type { LineSegments } from './linePoints.ts';
+/**
+ * One draw call for a polyline with a real width — an audio waveform, a trail, a plotted
+ * curve, anything that is a stroke rather than a surface.
+ *
+ * Four vertices per segment rather than instancing, exactly as `BoltBatch` is: a segment's
+ * two endpoints *are* its geometry, so there is no repeated base shape to instance and an
+ * instanced version would upload the same two positions per vertex anyway. `SEGMENT_CORNERS`
+ * and the index list come from `segmentQuads.ts`, shared with the arc renderer so the two
+ * cannot drift into two different meshes for the same segment.
+ *
+ * **Alpha blended, depth tested, depth write off — not additive.** An arc is light arriving
+ * and adds to what is behind it; a line is a surface-ish thing that occludes in colour but
+ * must not cut a hole in the depth buffer from its own soft antialiased edge. That is the
+ * rule the SDF text renderer follows for the same reason, and `drawTo` leaves depth
+ * *testing* alone the way that renderer does, on the assumption that the mesh pass already
+ * has it enabled with `LEQUAL` — this is world geometry, not a screen overlay recovering
+ * state from whatever ran before it.
+ */
+export declare class LineBatch {
+    readonly program: WebGLProgram;
+    readonly uniforms: Record<string, WebGLUniformLocation>;
+    private readonly vao;
+    private readonly buffers;
+    private readonly fromBuffer;
+    private readonly toBuffer;
+    /** Scratch, expanded from the segment list's per-segment arrays to per-vertex ones. */
+    private readonly from;
+    private readonly to;
+    private readonly capacity;
+    constructor(gl: WebGL2RenderingContext, capacity: number, label: string);
+    /**
+     * Send this frame's polyline, expanding each segment to its four vertices.
+     *
+     * The expansion is written here rather than folded into `expandBoltSegments`: that
+     * function reads a `BoltSegments` — five arrays beyond `from`/`to` — and teaching it to
+     * read a `LineSegments` too would grow a union that couples two renderers sharing only a
+     * quad. This walk is the same shape with none of that: two positions in, copied to four
+     * vertices each.
+     */
+    upload(gl: WebGL2RenderingContext, data: LineSegments): number;
+    /**
+     * @param additive Whether this stroke is *light arriving* rather than a thing in the world.
+     *
+     * **It states what the stroke is; it does not turn a line into a bolt.** `AGENTS.md` forbids a
+     * mode flag on one verb to get the other, and this is not one: a bolt jitters along its own path
+     * because it is lightning, and that is a fact about its *geometry* which nothing here changes. A
+     * line asked to be additive still follows the path it was given, still has a clean edge, and is
+     * still fogged. What changes is that it adds to what is behind it instead of covering it.
+     *
+     * Reported by a consumer drawing a glowing block outline: the only additive stroke was
+     * `drawBolts`, which jitters, so they drew two alpha-blended passes at different softness and
+     * measured what it cost — against a bright surface it tints toward the glow colour instead of
+     * adding light to it, which is visible on sand at noon and indistinguishable in a cave.
+     */
+    drawTo(gl: WebGL2RenderingContext, segmentCount: number, additive?: boolean): void;
+    dispose(gl: WebGL2RenderingContext): void;
+    private dynamic;
+    private staticAttr;
+}

package/dist/render/lineBatch.js

@@ -0,0 +1,160 @@
+import { compileProgram, uniformLocations } from './shader.js';
+import { LINE_FRAG, LINE_VERT } from './shaders/line.js';
+import { buildSegmentQuads } from './segmentQuads.js';
+/**
+ * One draw call for a polyline with a real width — an audio waveform, a trail, a plotted
+ * curve, anything that is a stroke rather than a surface.
+ *
+ * Four vertices per segment rather than instancing, exactly as `BoltBatch` is: a segment's
+ * two endpoints *are* its geometry, so there is no repeated base shape to instance and an
+ * instanced version would upload the same two positions per vertex anyway. `SEGMENT_CORNERS`
+ * and the index list come from `segmentQuads.ts`, shared with the arc renderer so the two
+ * cannot drift into two different meshes for the same segment.
+ *
+ * **Alpha blended, depth tested, depth write off — not additive.** An arc is light arriving
+ * and adds to what is behind it; a line is a surface-ish thing that occludes in colour but
+ * must not cut a hole in the depth buffer from its own soft antialiased edge. That is the
+ * rule the SDF text renderer follows for the same reason, and `drawTo` leaves depth
+ * *testing* alone the way that renderer does, on the assumption that the mesh pass already
+ * has it enabled with `LEQUAL` — this is world geometry, not a screen overlay recovering
+ * state from whatever ran before it.
+ */
+export class LineBatch {
+    program;
+    uniforms;
+    vao;
+    buffers = [];
+    fromBuffer;
+    toBuffer;
+    /** Scratch, expanded from the segment list's per-segment arrays to per-vertex ones. */
+    from;
+    to;
+    capacity;
+    constructor(gl, capacity, label) {
+        this.program = compileProgram(gl, LINE_VERT, LINE_FRAG, label);
+        this.uniforms = uniformLocations(gl, this.program, 'lineBatch');
+        this.capacity = capacity;
+        const verts = capacity * 4;
+        this.from = new Float32Array(verts * 3);
+        this.to = new Float32Array(verts * 3);
+        /*
+         * The corner layout and the index list are the only static data: which end of the
+         * segment a vertex sits at, and which side of it. Everything else arrives per frame.
+         * Built in `segmentQuads.ts`, so both a bolt and a line draw the same quad.
+         */
+        const { corners, indices } = buildSegmentQuads(capacity);
+        const vao = gl.createVertexArray();
+        if (vao === null)
+            throw new Error(`${label}: createVertexArray failed`);
+        this.vao = vao;
+        gl.bindVertexArray(vao);
+        // Locations pinned to `line.ts`'s own `layout(location = ...)` qualifiers: 0 aFrom, 1
+        // aTo, 2 aCorner. There is no third dynamic attribute — a line has no envelope to carry.
+        this.fromBuffer = this.dynamic(gl, 0, verts * 3, 3, label);
+        this.toBuffer = this.dynamic(gl, 1, verts * 3, 3, label);
+        this.staticAttr(gl, 2, corners, 2, label);
+        const indexBuffer = gl.createBuffer();
+        if (indexBuffer === null)
+            throw new Error(`${label}: createBuffer failed`);
+        this.buffers.push(indexBuffer);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer);
+        gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, indices, gl.STATIC_DRAW);
+        gl.bindVertexArray(null);
+    }
+    /**
+     * Send this frame's polyline, expanding each segment to its four vertices.
+     *
+     * The expansion is written here rather than folded into `expandBoltSegments`: that
+     * function reads a `BoltSegments` — five arrays beyond `from`/`to` — and teaching it to
+     * read a `LineSegments` too would grow a union that couples two renderers sharing only a
+     * quad. This walk is the same shape with none of that: two positions in, copied to four
+     * vertices each.
+     */
+    upload(gl, data) {
+        const count = Math.min(data.count, this.capacity);
+        for (let s = 0; s < count; s++) {
+            const fx = data.from[s * 3];
+            const fy = data.from[s * 3 + 1];
+            const fz = data.from[s * 3 + 2];
+            const tx = data.to[s * 3];
+            const ty = data.to[s * 3 + 1];
+            const tz = data.to[s * 3 + 2];
+            for (let c = 0; c < 4; c++) {
+                const v = s * 4 + c;
+                this.from[v * 3] = fx;
+                this.from[v * 3 + 1] = fy;
+                this.from[v * 3 + 2] = fz;
+                this.to[v * 3] = tx;
+                this.to[v * 3 + 1] = ty;
+                this.to[v * 3 + 2] = tz;
+            }
+        }
+        if (count === 0)
+            return 0;
+        const verts = count * 4;
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.fromBuffer);
+        gl.bufferSubData(gl.ARRAY_BUFFER, 0, this.from, 0, verts * 3);
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.toBuffer);
+        gl.bufferSubData(gl.ARRAY_BUFFER, 0, this.to, 0, verts * 3);
+        return count;
+    }
+    /**
+     * @param additive Whether this stroke is *light arriving* rather than a thing in the world.
+     *
+     * **It states what the stroke is; it does not turn a line into a bolt.** `AGENTS.md` forbids a
+     * mode flag on one verb to get the other, and this is not one: a bolt jitters along its own path
+     * because it is lightning, and that is a fact about its *geometry* which nothing here changes. A
+     * line asked to be additive still follows the path it was given, still has a clean edge, and is
+     * still fogged. What changes is that it adds to what is behind it instead of covering it.
+     *
+     * Reported by a consumer drawing a glowing block outline: the only additive stroke was
+     * `drawBolts`, which jitters, so they drew two alpha-blended passes at different softness and
+     * measured what it cost — against a bright surface it tints toward the glow colour instead of
+     * adding light to it, which is visible on sand at noon and indistinguishable in a cave.
+     */
+    drawTo(gl, segmentCount, additive = false) {
+        if (segmentCount === 0)
+            return;
+        gl.enable(gl.BLEND);
+        gl.blendFunc(gl.SRC_ALPHA, additive ? gl.ONE : gl.ONE_MINUS_SRC_ALPHA);
+        gl.depthMask(false);
+        // The quad billboards toward the view direction the same way a bolt's does — see
+        // `line.ts`'s own `cross(dir, view)` — so its winding can flip with the camera exactly
+        // as a bolt's can, and culling it would drop the line from half the angles it is seen.
+        gl.disable(gl.CULL_FACE);
+        gl.bindVertexArray(this.vao);
+        gl.drawElements(gl.TRIANGLES, segmentCount * 6, gl.UNSIGNED_INT, 0);
+        gl.bindVertexArray(null);
+        gl.enable(gl.CULL_FACE);
+        gl.depthMask(true);
+        gl.disable(gl.BLEND);
+    }
+    dispose(gl) {
+        for (const buffer of this.buffers)
+            gl.deleteBuffer(buffer);
+        this.buffers.length = 0;
+        gl.deleteVertexArray(this.vao);
+        gl.deleteProgram(this.program);
+    }
+    dynamic(gl, location, floats, size, label) {
+        const buffer = gl.createBuffer();
+        if (buffer === null)
+            throw new Error(`${label}: createBuffer failed`);
+        this.buffers.push(buffer);
+        gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+        gl.bufferData(gl.ARRAY_BUFFER, floats * 4, gl.DYNAMIC_DRAW);
+        gl.enableVertexAttribArray(location);
+        gl.vertexAttribPointer(location, size, gl.FLOAT, false, 0, 0);
+        return buffer;
+    }
+    staticAttr(gl, location, data, size, label) {
+        const buffer = gl.createBuffer();
+        if (buffer === null)
+            throw new Error(`${label}: createBuffer failed`);
+        this.buffers.push(buffer);
+        gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+        gl.bufferData(gl.ARRAY_BUFFER, data, gl.STATIC_DRAW);
+        gl.enableVertexAttribArray(location);
+        gl.vertexAttribPointer(location, size, gl.FLOAT, false, 0, 0);
+    }
+}

package/dist/render/linePoints.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A polyline as the segments a renderer draws, rewritten in place.
+ *
+ * **No GL here**, for the reason `sdfTextLayout.ts` gives: which segments a point list
+ * produces is the same arithmetic on either backend, so it lives once and the two renderers
+ * own only their buffers. It is also the half worth testing, and testing it needs no context.
+ *
+ * A caller owns one of these for the life of its polyline and rewrites it per frame. That is
+ * the whole shape of the thing: an audio waveform, a moving trail and a plotted curve all
+ * have a fixed point count and moving points, and none of them should be allocating.
+ */
+export interface LineSegments {
+    /** `from` and `to` per segment, three floats each, live segments first. */
+    from: Float32Array;
+    to: Float32Array;
+    /** How many segments of the above are live. */
+    count: number;
+    readonly capacity: number;
+}
+/** Room for `capacity` segments, which is one fewer than the points that fill them. */
+export declare function createLineSegments(capacity: number): LineSegments;
+/**
+ * Rewrite a polyline from a flat point list, three floats a point.
+ *
+ * Returns how many segments were written, which is `pointCount - 1` clamped to capacity: a
+ * caller that overruns loses its tail rather than its frame, the same rule
+ * `expandBoltSegments` follows.
+ *
+ * A list of one point writes nothing rather than a zero-length segment. A degenerate segment
+ * is not harmless: its direction is undefined, so the shader falls back to an arbitrary
+ * perpendicular and draws a quad of full width pointing nowhere.
+ */
+export declare function setPolyline(out: LineSegments, points: ArrayLike<number>, pointCount: number): number;

package/dist/render/linePoints.js

@@ -0,0 +1,46 @@
+/**
+ * A polyline as the segments a renderer draws, rewritten in place.
+ *
+ * **No GL here**, for the reason `sdfTextLayout.ts` gives: which segments a point list
+ * produces is the same arithmetic on either backend, so it lives once and the two renderers
+ * own only their buffers. It is also the half worth testing, and testing it needs no context.
+ *
+ * A caller owns one of these for the life of its polyline and rewrites it per frame. That is
+ * the whole shape of the thing: an audio waveform, a moving trail and a plotted curve all
+ * have a fixed point count and moving points, and none of them should be allocating.
+ */
+/** Room for `capacity` segments, which is one fewer than the points that fill them. */
+export function createLineSegments(capacity) {
+    return {
+        from: new Float32Array(capacity * 3),
+        to: new Float32Array(capacity * 3),
+        count: 0,
+        capacity,
+    };
+}
+/**
+ * Rewrite a polyline from a flat point list, three floats a point.
+ *
+ * Returns how many segments were written, which is `pointCount - 1` clamped to capacity: a
+ * caller that overruns loses its tail rather than its frame, the same rule
+ * `expandBoltSegments` follows.
+ *
+ * A list of one point writes nothing rather than a zero-length segment. A degenerate segment
+ * is not harmless: its direction is undefined, so the shader falls back to an arbitrary
+ * perpendicular and draws a quad of full width pointing nowhere.
+ */
+export function setPolyline(out, points, pointCount) {
+    const count = Math.max(0, Math.min(pointCount - 1, out.capacity));
+    for (let s = 0; s < count; s++) {
+        const a = s * 3;
+        const b = a + 3;
+        out.from[a] = points[a];
+        out.from[a + 1] = points[a + 1];
+        out.from[a + 2] = points[a + 2];
+        out.to[a] = points[b];
+        out.to[a + 1] = points[b + 1];
+        out.to[a + 2] = points[b + 2];
+    }
+    out.count = count;
+    return count;
+}