@driftengine/core 3.61.0

package/dist/render/backend/webgl2/renderer.d.ts

@@ -0,0 +1,3027 @@
+import { FrameBudget } from '../budget.ts';
+import type { ReadonlyMat4 } from 'gl-matrix';
+import type { Camera } from '../../camera.ts';
+import type { PickHit, PickableSource } from '../../pickable.ts';
+import type { ReflectiveSurface } from '../../screenSpaceReflection.ts';
+import type { DecalProjector } from '../../decalProjector.ts';
+import type { Bounds } from '../../../math/bounds.ts';
+import type { ComputeDefinition, ComputeHandle } from '../../compute.ts';
+import type { PassDefinition, PassHandle } from '../../pass.ts';
+import type { Vec3 } from '../../../math/color.ts';
+import { GpuTimer } from '../../gpuTimer.ts';
+import type { ColourGradeLut } from '../../colourGrade.ts';
+/**
+ * How far the rush's outermost tap reaches at full strength, in UV.
+ *
+ * In UV rather than pixels so the smear is the same fraction of the screen at any
+ * resolution — a blur measured in pixels is twice as strong on a phone at DPR 2, which is
+ * exactly backwards from where the budget is.
+ */
+/**
+ * How far a camera-blur smear may reach, in UV.
+ *
+ * A ceiling rather than a scale: a fast turn can reproject a pixel most of the way across
+ * the screen, and sampling that far turns a frame into streaks rather than into motion.
+ * Beyond this the velocity is shortened and the direction kept.
+ */
+import type { RendererApi } from '../api.ts';
+import type { ProbeBakeOptions } from '../../reflectionProbe.ts';
+import type { ProbeGridOptions } from '../../probeGrid.ts';
+import type { AreaLightBuffer, AreaLightSource } from '../../areaLights.ts';
+import type { PhotometricProfile } from '../../iesProfile.ts';
+import type { ShadowLight } from '../../pointShadowSystem.ts';
+import type { ShadowCasters } from '../../shadowCasters.ts';
+import type { RenderQuality, RenderQualityOptions } from '../../renderQuality.ts';
+import { Mesh } from '../../mesh.ts';
+import type { IncrementalMesh } from '../../mesh.ts';
+import type { MeshData } from '../../mesh.ts';
+import type { MeshOptions } from '../api.ts';
+import { SurfaceTexture } from '../../surfaceTexture.ts';
+import type { SurfaceMaterial, SurfaceTextureOptions } from '../../surfaceTexture.ts';
+import { PlumeRenderer } from '../../plumeRenderer.ts';
+import type { PlumeOptions, PlumePlacement } from '../../plumeRenderer.ts';
+import { WaterRenderer } from '../../waterRenderer.ts';
+import type { WaterBody } from '../../waterRenderer.ts';
+import { CausticsRenderer } from '../../causticsRenderer.ts';
+import type { CausticSheet } from '../../causticsRenderer.ts';
+import type { Atmosphere } from '../../atmosphere.ts';
+import { InstancedMesh } from '../../instancedMesh.ts';
+import { ParticleBatch } from '../../particleBatch.ts';
+import type { ParticleBatchOptions } from '../../particleBatch.ts';
+import type { ParticleInstances } from '../../particlePool.ts';
+import { BoltBatch } from '../../boltBatch.ts';
+import type { BoltSegments } from '../../boltPool.ts';
+import { LineBatch } from '../../lineBatch.ts';
+import type { LineSegments } from '../../linePoints.ts';
+import type { InstanceData } from '../../instancedMesh.ts';
+import { FlockRenderer } from '../../flockRenderer.ts';
+import { TextRenderer } from '../../textRenderer.ts';
+import { SdfTextRenderer } from '../../sdfTextRenderer.ts';
+import type { SdfFont } from '../../sdfFont.ts';
+import type { SdfTextStyle } from '../../sdfTextLayout.ts';
+import type { RenderBackend } from '../api.ts';
+import type { TextStyle } from '../../textLayout.ts';
+import { WindStreakRenderer } from '../../windStreakRenderer.ts';
+import type { WindStreakOptions } from '../../windStreakRenderer.ts';
+import type { WindField } from '../../windField.ts';
+import type { FlockParams } from '../../flockRenderer.ts';
+import { InstancedBatch } from './instanced.ts';
+import type { MeshInstances } from '../../instances.ts';
+/** Reused each frame: which shader light slot each bound cubemap serves. */
+export type { ShadowCasterSink, ShadowCasters } from '../../shadowCasters.ts';
+/** Lighting and atmosphere for a frame. The game decides what goes in it. */
+export interface Environment extends Atmosphere {
+    /** Dominant outdoor directional source: sun by day, moon by night. */
+    directionalDir: Vec3;
+    directionalColor: Vec3;
+    ambient: Vec3;
+    /**
+     * Ambient arriving from below. Omitted, it matches `ambient` and the fill is uniform.
+     *
+     * A hemispheric fill is the difference between a room whose floor and ceiling are made
+     * of different things and one where they are the same colour at different brightness.
+     */
+    ambientGround?: Vec3;
+    /** Strength of self-illuminated geometry, once `nightFactor` lets it through. */
+    emissiveGain: number;
+    /**
+     * **Whether self-illuminated geometry emits at all. Despite the name, this is not a clock.**
+     *
+     * It reads as a time of day and it is the emissive master switch: `flat.ts` multiplies every
+     * emissive term by it, so at 0 nothing in the world glows, whatever `emissiveGain` says and
+     * whatever a mesh declared. The name is accurate for the case it was written for, an outdoor
+     * world whose lamps come on at dusk, and it is a trap for every other one.
+     *
+     * **A daylit scene containing a lit thing must set this to 1 and live with the name.** A
+     * studio with softboxes, a shop sign, a screen wall, a subway platform, a lava field: each is
+     * self-illuminated at noon. Reported from outside after an evening lost to a white cyclorama
+     * that shipped with four grey plastic rectangles where its lights should have been, because
+     * the field describing the time of day had been set correctly.
+     *
+     * It is not renamed because it is on the public surface and a second name for one field is
+     * worse than an inaccurate one. Read it as "does emissive emit", and use `emissiveGain` for
+     * how strongly.
+     */
+    nightFactor: number;
+    /**
+     * Emission that only shows where the dominant light does not reach, 0 and off by default.
+     *
+     * **The case it exists for is a lamp field on something that turns.** City lights are a
+     * property of the ground, so they are authored into the surface where the ground is. Whether
+     * they should be *visible* is a property of where the sun is, which the ground turns past, and
+     * nothing could say the second thing: `emissive` is per vertex and the light direction is per
+     * frame, and no term multiplied them.
+     *
+     * Reported from outside with the arithmetic, on a rotating planet whose night lights were
+     * built, photographed and then deleted because they could not be made to work. With an ambient
+     * of 0.07 and a directional of 1.15, a patch bright enough to read on the night side arrived at
+     * sixteen times that on the day side, as an orange blot on a continent. The ratio is fixed by
+     * the lighting, so no choice of value separates the two.
+     *
+     * Added to the ordinary emissive rather than replacing it, and weighted by how far the surface
+     * faces away from `directionalDir`, so the same mesh can carry day-side paint and night-side
+     * lamps. It is deliberately a hard cut at the terminator: softening it is what puts the lights
+     * back on the day side, which is the defect.
+     *
+     * Independent of `nightFactor`, which is a fact about the world's clock. This is a fact about
+     * where a surface is pointing, and a planet has a night side at any hour.
+     */
+    nightEmissive?: number;
+    /** World → light clip space, from `computeLightMatrix`. */
+    lightViewProj: ReadonlyMat4;
+    /** 0 disables shadow sampling — set to 0 whenever the map is not refreshed. */
+    shadowStrength: number;
+    /** Linear depth span returned by `computeLightMatrix`, in metres. */
+    shadowDepthSpan: number;
+    /** World-space box lit independently of the clock; 0 gain disables it. */
+    highlightMin: Vec3;
+    highlightMax: Vec3;
+    highlightGain: number;
+    /** Active point lights: 3 floats each for position/colour, 1 for radius. */
+    lightCount: number;
+    lightPositions: Float32Array;
+    lightColors: Float32Array;
+    lightRadii: Float32Array;
+    /** Each shaded light's emitter radius in metres. See `PointLightBuffer.sourceRadii`. */
+    lightSourceRadii: Float32Array;
+    /**
+     * How present each active light is, 0 to 1, from `selectPointLights`.
+     *
+     * Shorter than `MAX_POINT_LIGHTS` means a consumer that packs lights itself and has
+     * nothing to say about presence; those lights are taken as fully present, which is
+     * what every consumer got before this existed.
+     */
+    lightWeights: Float32Array;
+    /**
+     * Three per active light: where a spot points, normalised. Zeroes make a light a point light.
+     *
+     * Optional in spirit and required in the type, like every other member of this family: a short
+     * or absent array falls back in `resolvePointLights` to a direction of nothing and a cone that
+     * admits everything, which is the arithmetic every scene had before spot lights existed.
+     */
+    lightDirections: Float32Array;
+    /** Two per active light: the cosine of the inner cone angle, then of the outer. */
+    lightConeCos: Float32Array;
+    /** One per active light: a row of the photometric atlas, or −1 for none. */
+    lightIesProfiles: Float32Array;
+    /**
+     * Three per active light: where an asymmetric profile's azimuth zero points, in world space.
+     *
+     * Zeroes leave a profile on its first plane, which is what every axially symmetric fixture does
+     * anyway — so a scene that has never heard of this shades exactly as it did. See
+     * `PointLightSet.lightIesAxes` for why it cannot be derived from the light's direction.
+     */
+    lightIesAxes: Float32Array;
+    /** One per active light: a tile of the cookie atlas, or −1 for none. */
+    lightCookies: Float32Array;
+    /**
+     * The rectangular emitters this frame, or null for none.
+     *
+     * A buffer rather than loose arrays, unlike the point lights: those grew their arrays one at a
+     * time over years and the family is now seven wide, which is exactly the shape `bindPointLights`
+     * exists to stop anybody forgetting a member of. One object cannot be half-passed.
+     */
+    areaLights: AreaLightBuffer | null;
+    /**
+     * For each active light slot, which world light it holds. The shadow system
+     * needs this to translate a world light into the shader slot the fragment
+     * loop is iterating.
+     */
+    activeLightWorldIndices: Int32Array;
+}
+/**
+ * A complete `Environment`, with every field at a value that means "nothing special".
+ *
+ * The engine had no way to *make* one of these, so every caller assembled the whole
+ * interface by hand — and the first caller that wanted a small, self-contained lit scene
+ * (a character portrait in a box on a menu) wrote a partial literal, cast it to
+ * `Environment` to satisfy the compiler, and put `undefined` into `uniformMatrix4fv`. The
+ * type had been describing the contract all along; nothing was helping anyone meet it.
+ *
+ * So: a factory with a neutral baseline — no shadows, no point lights, an identity light
+ * matrix, no fog — and shallow overrides on top. A caller that forgets a field now gets
+ * the harmless value rather than a WebGL error, and a caller that needs the day's sky
+ * still assembles exactly what it did before.
+ *
+ * Fresh arrays every call. Sharing one `lightPositions` between two environments is the
+ * kind of aliasing that shows up as one scene's lamps appearing in another's.
+ */
+export declare function createEnvironment(overrides?: Partial<Environment>): Environment;
+/** A rectangle of the canvas, in CSS pixels from its top-left corner — i.e. a `DOMRect`. */
+export interface InsetRect {
+    readonly left: number;
+    readonly top: number;
+    readonly width: number;
+    readonly height: number;
+}
+export interface SkyColors {
+    top: Vec3;
+    horizon: Vec3;
+    deep: Vec3;
+    sunDir: Vec3;
+    sunColor: Vec3;
+    /** Apparent angular radius in radians; independent from emitted light. */
+    sunAngularRadius: number;
+    moonDir: Vec3;
+    moonColor: Vec3;
+    /** Apparent angular radius in radians; independent from emitted light. */
+    moonAngularRadius: number;
+    /** 0..1 across the lunar cycle. */
+    moonPhase: number;
+    nightFactor: number;
+    /** Accumulated cloud drift, metres of texture travel on each axis. */
+    cloudOffsetX: number;
+    cloudOffsetZ: number;
+}
+/**
+ * The whole WebGL2 surface of the engine. No raw `gl` calls may exist outside
+ * this directory (AGENTS.md): a shadow pass, a flat-shaded mesh pass, a sky
+ * pass, and any number of plume batches.
+ */
+/**
+ * How far a press reaches into the foliage, metres, and how much of a plant it takes.
+ *
+ * A little wider than a body, so a character leaves a path rather than a line of holes;
+ * 80% of the height, because grass that flattens completely reads as grass that has
+ * been deleted. Passing through foliage has to move it, so that it reads as being
+ * pressed down toward the ground rather than as vanishing.
+ */
+/**
+ * How far an overlay mesh is pulled toward the camera — see `drawMesh`.
+ *
+ * Both terms are in the units `glPolygonOffset` takes: the slope factor multiplies
+ * the polygon's own depth gradient, and the constant is in smallest-resolvable-depth
+ * units. Negative pulls toward the viewer.
+ *
+ * Deliberately small. It has to beat rounding at a coincident surface, which is one
+ * or two units, and it must not be large enough to pull a kerb out through a wall it
+ * genuinely stands behind — two units is a fraction of a millimetre at the distances
+ * a kerb is read at, and grows with distance exactly as the ambiguity does.
+ */
+/**
+ * Depth offset applied per layer — see `drawMesh`.
+ *
+ * **The slope term does not scale with the layer, and that is the whole point of
+ * splitting these two.** It multiplies the polygon's own depth gradient, which at a
+ * grazing angle is enormous: one pixel of a deck seen almost edge-on spans a large
+ * depth range, so a slope factor that is safe head-on can drag a flush marking metres
+ * toward the camera and out in front of geometry that genuinely stands over it. Scaled
+ * by the layer as well, it did exactly that: on a terrace, elements *underneath* the
+ * main platform showed through it at certain camera angles, as if trying to emerge
+ * from beneath something standing over them.
+ *
+ * So the slope term is **zero**, and the constant term carries the whole ordering.
+ *
+ * Zero rather than one, in the end, because the slope factor is the only part of this
+ * that depends on where the camera is — it multiplies the polygon's own depth gradient —
+ * and "certain camera angles" was the one constant in every report. A constant offset
+ * biases a layer by the same amount from every direction, so it can order two surfaces
+ * without ever being able to drag one out through the other as the view swings round.
+ *
+ * Kept as a named constant at zero rather than deleted: the next person to see a flush
+ * marking lose to its floor at a grazing angle will reach for a slope factor, and this is
+ * where the reason not to is written down.
+ */
+/**
+ * Re-exported from the depth convention, which is where the ceiling and the offset it scales now
+ * live together — one decision, read by this backend around a draw and by the other one inside a
+ * pipeline. Kept exported from here because the barrel has always named it from this module.
+ */
+export { MAX_DEPTH_LAYER } from '../../depthConvention.ts';
+/**
+ * What a film should do beyond shimmering, which until now was nothing.
+ *
+ * **A wet street at night is defined by everything above it appearing twice**, and `sheen`
+ * cannot supply that: it is an interference pattern, so raising it makes a road oilier rather
+ * than wetter. This is the other half, kept a separate number for exactly that reason.
+ *
+ * Requires a planar reflection to have been rendered this frame for the plane the film lies on,
+ * which needs `RenderQuality.planarReflections` where the scene has no water to allocate one.
+ * Absent or zero means the pass behaves as it always did, so nothing that predates it moves.
+ *
+ * **New, and honestly reported: the plumbing is proven and the look is not.** Measured on
+ * `demo/nightStreet.ts` held at frame 900, turning it from 0 to 1 changes 46,129 pixels and the
+ * largest change to any channel is **12 of 255**, so it is present and it does not yet read as a
+ * mirror. The reason is believed to be the film's own coverage alpha, which scales the mirrored
+ * term along with everything else, and a camera angle that keeps the grazing weight small. That
+ * is a weighting to tune rather than a mechanism to find, and the rig is where to tune it:
+ * `?scene=7&model=car&hold=900&wet=1` against `&wet=0`. Do not assume it looks right because it
+ * compiles.
+ */
+export interface FilmOptions {
+    /**
+     * How much of the mirrored scene shows through, 0 to 1.
+     *
+     * Weighted by the viewing angle on top of this, because that is what a reflection does: a wet
+     * surface underfoot shows almost nothing and the same surface down the street shows everything.
+     */
+    readonly reflectionStrength?: number;
+    /**
+     * The plane the film lies on, defaulting to 0.
+     *
+     * Only used to check it against the plane the reflection was rendered for, so a film on a
+     * different plane gets no mirror rather than somebody else's. A patch lifted a centimetre clear
+     * of the road still names the road's own height: the lift is to stop it fighting for the depth
+     * buffer, not a different plane to mirror across.
+     */
+    readonly reflectionPlaneY?: number;
+    /**
+     * How rough the film's own surface is, 0 to 1. Zero is a mirror, which is what this pass was.
+     *
+     * A film had one finish before this and it was the wrong one for the commonest use: a wet road
+     * is water lying *in* aggregate, so the stone under it scatters the reflection into a smear.
+     * Without this, a patch of film over a textured surface met it at a hard rim with mirror on one
+     * side and stone on the other — and softening the patch's coverage does not touch it, because
+     * the alpha was never what the eye was reading there.
+     *
+     * Displaces the reflection rather than blurring it. A rough surface scatters what it reflects
+     * rather than softening it, so a lamp becomes a streak and not a soft disc; it is also the only
+     * affordable choice, since the mirror has no mip chain and an honest blur costs taps.
+     */
+    readonly roughness?: number;
+    /**
+     * How coarse that roughness is, in bumps per metre. Defaults to 60.
+     *
+     * The same quantity `setSurfaceRelief` takes, and **matching the two is the point**: given the
+     * same field at the same scale, the water is broken up by the aggregate the dry surface beside
+     * it is already showing, and the wet and the dry stop reading as two materials. Ignored when
+     * `roughness` is zero.
+     */
+    readonly roughnessCyclesPerMetre?: number;
+}
+/**
+ * The two things a volume of light can have beyond its shape. See `drawLightVolume`.
+ *
+ * Both default to nothing, and that is not only compatibility: a torch beam is a smooth cone
+ * and should stay one. These are what turn a beam into a shaft of daylight, which is a
+ * different phenomenon that happens to be drawn by the same pass.
+ */
+export interface LightVolumeDrawOptions {
+    /**
+     * How much structure the air in the beam has, 0 to 1. Zero computes nothing.
+     *
+     * A shaft of sun through a window is not smooth: what is lit is the dust in it, and the dust
+     * is uneven. Useful values are low, around 0.2 to 0.5; past that the beam reads as smoke.
+     */
+    readonly dust?: number;
+    /** Metres per cell of the dust field. Around a metre for motes, several for weather. */
+    readonly dustScaleM?: number;
+    /**
+     * Where the dust field has drifted to, in metres. Defaults to standing still.
+     *
+     * A position rather than a rate, so this pass never reads a clock and a caller asking for
+     * the same instant twice gets the same frame. Air moves with the scene's wind, so the drift
+     * to hand it is the one `WindField` has already accumulated — the same value the smoke and
+     * the grass are answering to, which is what stops a shaft of dust drifting one way while the
+     * smoke beside it goes another.
+     */
+    readonly driftM?: Vec3;
+    /**
+     * How much the sun's own shadow map cuts the volume, 0 to 1. Zero samples nothing.
+     *
+     * **The directional light, which is to say the sun.** A shaft through a window carries the
+     * bars of that window because the light did; without this the floor under a mullioned window
+     * is barred and the shaft above it is smooth, and one frame disagreeing with itself about
+     * where the light went is most of what reads as fake. A beam from a lamp is not sunlight and
+     * wants this left at 0, which is why it is a per-draw amount and not a renderer setting.
+     *
+     * Needs `env`, and needs the renderer built with `directionalShadows`. Without either it is
+     * ignored rather than throwing, because this is a frame-loop call.
+     *
+     * The occlusion is evaluated at every step of the march, so this is a shadow carried through
+     * the air rather than stamped on a surface. What it still does not do is let one volume
+     * shadow another behind it: each is integrated on its own.
+     */
+    readonly sunShadow?: number;
+    /** Where the sun's shadow map is. Required by `sunShadow` and unused without it. */
+    readonly env?: Environment;
+    /**
+     * The air this volume stands in, and the density at which it reads at full strength.
+     *
+     * **A beam is only as visible as the medium it is lighting**, and until 2026-08-28 nothing
+     * here knew what the weather was: the same headlight cone was drawn in clear air and in thick
+     * fog, because `strength` is a number a caller authored once. Given this, the cone fades out
+     * as the air clears and blooms as it thickens, which is what turns fog from a filter over the
+     * frame into something that changes how the road is read.
+     *
+     * `fullAtDensity` is in the units of `Atmosphere.fogDensity` and is the density at which the
+     * beam is drawn exactly as authored; below it the beam is proportionally dimmer, above it
+     * nothing further happens. Absent means the beam ignores the weather, which is every volume
+     * drawn before this existed and every torch beam indoors.
+     *
+     * Density is read at the *volume's* own height rather than the camera's, so a car in a valley
+     * of fog seen from the ridge above carries its own weather.
+     */
+    readonly medium?: {
+        readonly atmosphere: Atmosphere;
+        readonly fullAtDensity: number;
+    };
+    /**
+     * Where the drawn volume starts along its own +Z, matching the `nearM` its hull was built
+     * with. Defaults to the apex.
+     *
+     * The march is clipped to the same slab the hull covers, so a shaft that is a slice taken
+     * far down a very wide cone has to say where its slice begins or the walk starts at an apex
+     * above the roof and integrates air that was never drawn.
+     */
+    readonly nearM?: number;
+}
+/**
+ * The two things a translucent draw can turn off. See `Renderer.drawTranslucentMesh`.
+ *
+ * Both default to `true`, which is the world exactly as it drew before this existed: lit,
+ * fogged, shaded like everything else. An options object rather than a positional boolean —
+ * `drawTranslucentMesh(mesh, model, opacity, false)` reads as a flag on the call rather than
+ * as a description of what got drawn, which `AGENTS.md` rules out for the same reason a bare
+ * boolean is refused everywhere else in this file.
+ */
+export interface TranslucentMeshOptions {
+    /**
+     * `false` draws the mesh exactly its own vertex colour times its own texture, with no
+     * ambient, sun, point lights, specular, reflectivity, grain or emissive touching it —
+     * three.js calls this `meshBasicMaterial`. For a glow shell, a flat backdrop plate or
+     * anything else whose art direction says "this colour, unconditionally."
+     */
+    readonly lit?: boolean;
+    /**
+     * `false` keeps this draw out of the atmospheric haze and the underwater tint, both —
+     * see the shader's own comment on `uFogEnabled` for why the two travel together and what
+     * a draw that opts out of both gives up.
+     *
+     * Independent of `lit`: an unlit marker at the edge of view range can still want to fade
+     * into the haze, so the two are separate switches rather than one covering both.
+     */
+    readonly fog?: boolean;
+    /**
+     * `false` skips the *tone curve* for this draw, keeping the colour-space conversion — which
+     * is exactly what three.js's `toneMapped: false` does and what it is for.
+     *
+     * **A meter is not a surface.** ACES is a photographic response: it compresses highlights and
+     * desaturates as it goes, which is right for a world made of light and wrong for a swatch
+     * whose colour *is* the reading. A spectrum bar authored at `#00d84a` renders through the
+     * curve as `(106, 213, 102)` — a pale sage where the author wrote a pure green — and the
+     * error cannot be dialled out of the source colour either: the AP1 matrix mixes channels, so
+     * that stop's red is pinned at 113 of 255 even with the input's red at zero. There is no
+     * value a caller can author that comes out right, which is why this is a switch rather than a
+     * tuning problem.
+     *
+     * **Honoured where this pass grades itself, which is a renderer with no composite.** With one,
+     * the frame is graded as a whole after every pass has written into it, and no per-draw flag
+     * can reach back through that; the draw is graded like everything else. That is a real limit
+     * of grading once at the end rather than per material, stated rather than hidden: three.js
+     * can honour it always because it tone maps inside every material's own fragment stage.
+     */
+    readonly toneMapped?: boolean;
+    /**
+     * How far this surface bends what is behind it, in screen UV at the frame's own resolution.
+     *
+     * **0 is off and is the default, which is what every call that predates this means**, so no
+     * existing draw and no published scene moves by a bit.
+     *
+     * Translucent only, and that is a statement about what the branch reads rather than a
+     * restriction: it samples the colour drawn *before* this surface, and an opaque draw has
+     * already occluded it.
+     *
+     * **What it costs is one copy of the frame's colour**, taken at the first refracting draw of a
+     * frame and reused by every later one. So glass does not refract other glass — which is right,
+     * a pane behind a pane should show the room — and opaque geometry drawn *after* the first pane
+     * is missing from what that pane shows. Draw the world, then the glass.
+     */
+    readonly refraction?: number;
+    /**
+     * What survives one metre of this medium, per channel. White is clear glass and is the default.
+     *
+     * **Beer-Lambert, stated in the units a caller thinks in.** The transmitted colour is
+     * `pow(tint, pathLength)`, which is `exp(-absorption * d)` with `absorption = -log(tint)`. What
+     * it costs is that a caller holding absorption coefficients from a reference converts them
+     * once; what it buys is that clear glass is `(1, 1, 1)` with no special case, and that there is
+     * no `log(0)` at the API to trap on.
+     *
+     * **Named apart from `tint` below, which is a different quantity on the same object.** That one
+     * multiplies the surface's own colour; this one absorbs what passes *through* it. A draw wanting
+     * a coloured pane that does not bend already has the first, and one name for both would be a
+     * noun lying about what it does.
+     *
+     * Does nothing without `refraction`, deliberately.
+     */
+    readonly refractTint?: Vec3;
+    /**
+     * Metres of medium at `dot(N, V) = 1`, multiplied by the per-vertex channel's `.w` lane.
+     *
+     * The lane is optional and absent means 1.0, so a mesh carrying no channel refracts at exactly
+     * this thickness. **An instanced draw cannot carry the lane at all** — location 13 is the
+     * instance matrix, and `InstancedMesh` refuses a channelled mesh at construction — so an
+     * instanced refracting draw is uniform in thickness rather than wrong.
+     *
+     * The path a ray takes is this divided by `dot(N, V)`, so a pane seen edge-on absorbs more than
+     * the same pane seen face-on. That is what makes a glass edge go green while its middle stays
+     * clear, and it is the whole difference between this and a flat tint.
+     */
+    readonly thicknessM?: number;
+    /**
+     * Whether this draw writes depth. `true`, which is what it has always done, unless a caller
+     * says otherwise.
+     *
+     * **Writing depth is right for a piece and wrong for a set of them.** A sign hung in the air
+     * has to occupy the depth buffer or the sky, drawn last over everything the world left
+     * untouched, paints straight over it — that is why this pass writes depth at all, and the
+     * reason is in `drawTranslucentMesh`'s own docstring. But depth written by a blended surface
+     * *rejects* the blended surfaces behind it, so a model whose interior is blended draws the
+     * first of each overlapping pair and discards the rest, and which one is first is the order
+     * the caller happened to submit in.
+     *
+     * So `false` is the tool for the second case: a set of blended surfaces that belong to one
+     * object and have to blend through each other. Measured on an imported vehicle, a quarter of
+     * whose materials declare a blend: 96 interior surfaces drawn against the shell they sit
+     * inside.
+     *
+     * **What it costs, and it is the whole reason this is not the default.** Nothing in the depth
+     * buffer means nothing to sort by, so the caller owns the order — draw back to front, or accept
+     * that two surfaces overlapping in view blend in submission order. And a surface that writes no
+     * depth cannot occlude the sky. A caller wanting both wants the pieces sorted and this left
+     * alone.
+     */
+    readonly depthWrite?: boolean;
+    /**
+     * Orders geometry that occupies the same surface as other geometry, exactly as `drawMesh`'s
+     * parameter of the same name and with the same ceiling.
+     *
+     * A decal lying on the surface it decorates is coplanar with it, and coplanar surfaces do not
+     * merely tie: their interpolated depths are equal in exact arithmetic, so which one survives is
+     * decided per pixel by which way the rounding fell. `drawMesh` has had the answer since the
+     * defect turned up in six places in one session, and this call did not — so the same marking
+     * declared over the same slab was ordered when it was opaque and a coin toss when it blended.
+     *
+     * A higher layer wins wherever two surfaces coincide. 0, the default, is the base world and
+     * takes no offset at all.
+     */
+    readonly depthLayer?: number;
+    /**
+     * A per-draw colour multiplier, exactly as `drawMesh`'s fourth argument.
+     *
+     * **Here rather than as a fifth positional parameter**, because it belongs to the same set of
+     * per-draw decisions the rest of this interface holds and a fifth argument after an options bag
+     * reads as an afterthought.
+     *
+     * It exists because the opaque and blended paths were not interchangeable for a caller that
+     * tints: a consumer fading a coloured model in — every surface translucent for the length of the
+     * fade — lost its colour for exactly as long as the fade ran and then snapped to it. Reported
+     * from a game whose cars arrive that way.
+     */
+    readonly tint?: Vec3 | null;
+}
+export declare class WebGL2Renderer implements RendererApi {
+    /**
+     * Private on purpose. The GL context never leaves this directory, so a
+     * second backend (WebGPU) stays a contained
+     * addition rather than a rewrite of every caller. Resources are created
+     * through the factories below.
+     *
+     * **`registerPass` is the one exception, and it is a deliberate one.** A package that draws
+     * cannot be given a lowest common denominator of two APIs without inventing a second renderer,
+     * so `PassContext` hands over this context by name and the WebGPU encoder by another. The
+     * reason above is unharmed: what kept the second backend a contained addition was that no
+     * *caller* holds a GL type, and a contributor that asks for one branches on the backend it
+     * asked for.
+     */
+    private readonly gl;
+    private readonly canvas;
+    private readonly contextLostListeners;
+    private readonly contextRestoredListeners;
+    /** Removes the canvas listeners `attachContextLoss` installed. See `dispose`. */
+    private readonly detachContextLoss;
+    private disposed;
+    /**
+     * Whether the drawing context is currently gone.
+     *
+     * Every GL entry point below returns early while this is true, and that is a
+     * reliability fix rather than an optimisation. A lost context does not stop the
+     * caller's frame loop — `requestAnimationFrame` keeps firing, the game keeps calling
+     * `beginFrame`, and every object this renderer holds now belongs to a context that no
+     * longer exists. The browser answers each call with INVALID_OPERATION, so a single
+     * loss becomes an unbounded flood of "object does not belong to this context" at sixty
+     * frames a second, which buries the one message that mattered and makes the console
+     * useless for finding the cause.
+     *
+     * It was reported as a wall of console errors after the picture stopped, with the
+     * trace running through the frame loop — the renderer drawing long after there was
+     * anything to draw to.
+     *
+     * Public so a consumer can skip its own per-frame work too; the guard here only makes
+     * the engine's half harmless.
+     *
+     * **Asks the context, not only the event.** `webglcontextlost` is dispatched
+     * asynchronously, so there is a window — however many calls the caller makes before
+     * the task queue drains — in which the context is already dead and the flag is still
+     * false. Every guard built on the flag alone fails open in that window, which is how a
+     * `resize` reached `PlanarReflection.ensureSize` and threw FRAMEBUFFER_UNSUPPORTED
+     * (0x8CDD) against a context that no longer existed.
+     *
+     * `isContextLost()` is the authority and is cheap. The flag is kept because it is what
+     * `onContextLost` listeners fire from, and it holds across the gap until
+     * `webglcontextrestored` clears it.
+     */
+    get contextLost(): boolean;
+    private contextLostFlag;
+    /**
+     * The material texture `setSurfaceTexture` last bound, or `null` when albedo is off.
+     *
+     * A boolean alone used to be enough, because nothing between two `drawMesh` calls
+     * ever touched `SURFACE_TEXTURE_UNIT`'s actual GL binding. `drawSdfText` does: the atlas
+     * borrows that same unit for the length of one draw (see `SDF_TEXT_TEXTURE_UNIT`), so
+     * after it returns the unit no longer necessarily holds what this flat-program state
+     * still says it holds. This is what lets `drawSdfText` put the *right* texture back
+     * rather than just a flag saying one should be there.
+     */
+    private currentSurfaceTexture;
+    /**
+     * GPU time for the frame's three parts, when the driver will report it.
+     *
+     * Public because the consumer is a diagnostic, not the renderer: the game brackets
+     * its own frame with `beginFrame`/`endFrame` and reads samples with `poll`.
+     */
+    readonly gpuTimer: GpuTimer;
+    /**
+     * The drawing-buffer density ceiling, in effect right now.
+     *
+     * Not `readonly`: `applyResolutionScale` moves it, which is what lets a governor hold a
+     * frame budget without rebuilding anything. It starts at the resolved quality's own
+     * `maxDevicePixelRatio` and is re-read by every `resize()`.
+     */
+    private maxDpr;
+    /** Area cap in pixels, 0 for uncapped. Mutable: see `setMaxDrawingBufferPixels`. */
+    private maxDrawingBufferPixels;
+    /** Reused by `resize`, which runs every frame and may not allocate. */
+    private readonly budgeted;
+    /** Per-frame bake planning scratch, sized once. See `pointShadowBudget.ts`. */
+    /**
+     * How many frames running each slot has been stale, which light that was, and whether
+     * that run is long enough to call the map chronically stale.
+     *
+     * A light that moves, or animates its radius, is owed a bake again the frame after it
+     * gets one. Counting the run is what separates it from a static light that drifted once
+     * and would then hold its image indefinitely, so the budget can serve the bake that
+     * will *stick* first. The owner is tracked because pool slots change hands: a new light
+     * in an old slot starts at zero rather than inheriting the last tenant's record.
+     */
+    /** The shaded lights that also cast, which is not the same list. See `updatePointShadows`. */
+    private readonly castingWorldIndices;
+    /** Per-slot scratch for the bake round; see `runPointShadowBakes`. */
+    private readonly bakeScratch;
+    /** Resolved once; a size/profile change recreates the renderer's resources. */
+    readonly quality: Readonly<RenderQuality>;
+    /**
+     * What `UNMASKED_RENDERER_WEBGL` calls this part, or `''` when the browser withholds it.
+     *
+     * Public because a bug report is worth more with it than without: every performance
+     * report this project has acted on was read GPU-string first.
+     */
+    readonly rendererName: string;
+    /**
+     * Which backend is drawing, from the renderer rather than from the address bar.
+     *
+     * **`createRenderer` returns this too and says to report it and never infer it** — the
+     * inference being a query string, which says what was *asked for* and is wrong in exactly
+     * the case that matters, a silent fallback. A consumer holding only a renderer could not
+     * ask before this existed, so it inferred or it said nothing.
+     *
+     * Not the same question as `rendererName`, which is the GPU's own string and identifies the
+     * part rather than the API.
+     */
+    readonly backend: RenderBackend;
+    /**
+     * Whether this part was recognised as one that cannot hold the profile it asked for, and
+     * had its pixel terms clamped at construction. Carried into bug snapshots, so a report
+     * says whether the clamp fired rather than leaving it to be inferred.
+     */
+    readonly capabilityClamped: boolean;
+    /**
+     * How many frames this renderer has actually presented, monotonic for its whole lifetime.
+     *
+     * **Incremented where `endFrame` reaches its end, not where it is called.** WebGL2 has no
+     * swap chain to acquire the way WebGPU's `getCurrentTexture` gives one — the canvas *is*
+     * the default framebuffer, and `beginFrame` clears it directly, so there is no separate
+     * "taken" instant to hang this on. `endFrame`'s only early return is a lost context, so its
+     * far end, right beside `framePresented`, is this backend's honest equivalent: the one
+     * point every call is guaranteed to reach if and only if the frame it opened is what the
+     * browser is about to show. A consumer compositing an offline export reads this after
+     * `endFrame` and compares it with what it read last, which is how it tells a frame that
+     * drew something from one that repeated the canvas it already had — see `ExportTarget`.
+     */
+    get presentedFrames(): number;
+    private presentedFrameCount;
+    private readonly flatProgram;
+    private readonly flatUniforms;
+    /**
+     * The lit fragment source every flat program is built from, and the budget it was built at.
+     *
+     * **One string for all four variants, built once.** The four flags `flatFrag` permutes on are
+     * fixed by the time the first program is compiled — three are resolved quality and the fourth is
+     * a `readonly` field — so the skinned, morphed and instanced programs differ only in their
+     * *vertex* stage. Building it three more times cost 0.84 ms each, measured, and made it possible
+     * for a lazily compiled variant to end up at a different light budget from the one the renderer
+     * uploads for, which is a picture nobody could explain.
+     */
+    private readonly flatFragSource;
+    /**
+     * How many lights this renderer's shader has room for, after the device had its say.
+     *
+     * `FULL_LIGHT_BUDGET` on anything with room, which is every desktop part and most phones. See
+     * `uniformVectorBudget.ts`, and `shadedLights` for what a consumer should do about it.
+     */
+    private readonly lightBudget;
+    /**
+     * The skinned twin of `flatProgram`, compiled the first time a rigged mesh is built.
+     *
+     * **Lazy, and at `createMesh` rather than at construction or in the frame loop.** At
+     * construction it would cost a compile to every game for a feature most never use; in the frame
+     * loop it could throw, and the rule is that initialisation fails loudly so a running frame never
+     * has to. `createMesh` is construction, it is off the frame, and it is where joints first exist.
+     */
+    private flatSkinnedProgram;
+    private flatSkinnedUniforms;
+    /**
+     * The vertex stage's other two variants, compiled on the first mesh that needs each.
+     *
+     * Four programs where the shader has four variants, and each is compiled only if a mesh actually
+     * asks for it — a game with characters and no morph targets pays for two, and one with neither
+     * pays for one. `bindMeshPass` feeds every program that exists, so the frame state cannot go
+     * missing from one of them.
+     */
+    private flatMorphedProgram;
+    private flatMorphedUniforms;
+    private flatBothProgram;
+    private flatBothUniforms;
+    /** The morph weights the following draws use, or null for none. */
+    private morphWeights;
+    /**
+     * Every flat program with the frame state it needs, preallocated so the loop allocates nothing.
+     *
+     * One entry until a rigged mesh is built, two after. `bindMeshPass` walks it.
+     */
+    private readonly flatTargets;
+    /**
+     * The last camera and environment `bindMeshPass` was given.
+     *
+     * Held so a program compiled *after* this frame's pass was bound can be fed at once rather than
+     * drawing one frame with every uniform at zero. Two references rather than copies, so this
+     * costs no allocation.
+     */
+    private lastPassCamera;
+    private lastPassEnv;
+    /** Light in the air, which is not a material. See `shaders/lightVolume.ts`. */
+    private readonly lightVolumeProgram;
+    private readonly lightVolumeUniforms;
+    /** Two triangles in screen space, for `fillPanel`. Built once. */
+    private readonly panelProgram;
+    private readonly panelUniforms;
+    private readonly panelVao;
+    private readonly filmProgram;
+    /**
+     * The off-screen colour target, when screen effects are on. Null is not a failure —
+     * it is the low-end path, and the scene goes straight to the canvas exactly as it did
+     * before this existed.
+     */
+    private readonly sceneTarget;
+    /** So the refusal below is once per renderer rather than once per frame. See `setColourGrade`. */
+    private warnedGradeWithoutComposite;
+    /** Scratch for a volume's `uDepthToLocal`. Built per draw and never allocated in the loop. */
+    private readonly volumeDepthToLocal;
+    private readonly volumeDepthScratch;
+    /**
+     * What a declared-but-unused sampler slot reads, instead of nothing.
+     *
+     * A profile with shadows off still compiles the samplers that would sample them, and a
+     * unit bound to `null` is an *incomplete* texture whose descriptor a driver may fetch
+     * before it evaluates the runtime branch that would have skipped the read. See
+     * `emptyTexture.ts`: on RDNA4 that fetch page-faults and resets the GPU.
+     */
+    /**
+     * The joint palette the next skinned `drawMesh` reads, or empty until one is set.
+     *
+     * Held rather than passed, like every other per-draw state on this renderer: `setSkinPalette`
+     * chooses and the following draws use it, which is the shape `setMaterial` already has.
+     */
+    private readonly skinPalette;
+    /** Whether a palette is currently chosen. Distinct from whether one was ever uploaded. */
+    private skinPaletteSet;
+    private readonly emptyTexture2D;
+    private readonly emptyTexture2DArray;
+    private readonly emptyTextureCube;
+    /** How hard the rush blurs this frame, and how far its outermost tap reaches. */
+    private rushStrength;
+    /** How much of the motion-blur ceiling this frame takes. See `setCameraMotionBlur`. */
+    /**
+     * Order-independent transparency: the frame's translucent draws, and the pass that resolves them.
+     *
+     * **Recorded rather than drawn**, because the accumulation and the revealage are two blend states
+     * over the same geometry and this renderer otherwise draws immediately. See `TranslucentQueue`
+     * for why every field is copied.
+     */
+    private readonly translucentQueue;
+    private oit;
+    /**
+     * The frame's drawn decals, and the pass that marks the scene with them.
+     *
+     * Recorded rather than drawn where the call is made, because a projected mark is decided
+     * from the depth the frame has drawn and therefore cannot run until the opaque world is
+     * finished. See `DecalQueue`.
+     */
+    private readonly decalQueue;
+    /** Built on the first frame that submits a mark, and never for a scene with none. */
+    private decals;
+    /** Said once where a mark cannot be drawn at all, rather than dropped in silence. */
+    private decalsRefused;
+    /**
+     * The frame's reflective surfaces, and the pass that marches them.
+     *
+     * Recorded rather than traced where the call is made, because the march reads the *finished*
+     * picture: what a ray finds is a pixel of the scene the frame has already drawn.
+     */
+    private readonly reflectionQueue;
+    /** Built on the first frame that submits a surface, and never for a scene with none. */
+    private ssr;
+    /** Said once where a reflection cannot be traced at all. */
+    private reflectionsRefused;
+    /** Where the frame's camera stands, which is what gives a reconstructed normal its sign. */
+    private readonly frameEye;
+    /** Whether this frame is recording translucent draws instead of blending them as they arrive. */
+    private oitActive;
+    /** True while the queue is being replayed, so a replayed draw does not record itself again. */
+    private oitReplaying;
+    /** Said once, not per frame, where the context cannot give the float target the sum needs. */
+    private oitRefused;
+    /** Said once for the whole renderer. See `refuseOitMultisampled`. */
+    private oitMultisampleRefused;
+    /**
+     * The options object the replay hands back to `drawTranslucentMesh`, reused.
+     *
+     * Mutable where `TranslucentMeshOptions` is readonly, and built once: a fresh literal per draw
+     * would allocate once per translucent surface per pass per frame, which is what `AGENTS.md`
+     * forbids in the frame loop.
+     */
+    private readonly oitReplayOptions;
+    private motionBlurScale;
+    /** How much of the bloom ceiling this frame takes. See `setBloom`. */
+    private bloomScale;
+    /**
+     * This frame's exposure into the tone curve. See `setOutputExposure`.
+     *
+     * Starts at the construction-time grade, so a world that never calls the setter is exposed
+     * exactly as it asked to be and nothing about it changes.
+     */
+    private exposure;
+    /**
+     * This frame's veil colour, and how much of it to composite. See `setFrameVeil`.
+     *
+     * A mutable tuple rather than a fresh array per call, so a transition calling this every
+     * frame costs no allocation to hold it. `veilAlpha` is reset to zero at the end of every
+     * `endFrame` — unlike `rushStrength` and the two scales above, which are held until a caller
+     * changes them — because a forgotten veil is a stuck white or black frame, and that failure
+     * is worse than one that has to ask again. See `setFrameVeil` for the ordering ruling.
+     */
+    private readonly veilColor;
+    private veilAlpha;
+    /**
+     * The view-projection the *previous* frame was drawn with, and the reprojection built
+     * from it. Held here because camera motion blur is the only thing that wants it and it
+     * costs one matrix either way.
+     *
+     * Scratch, allocated once: `endFrame` runs every frame and may not allocate.
+     */
+    private readonly previousViewProj;
+    private readonly reprojection;
+    /**
+     * Temporal antialiasing: the history's state, this frame's sub-pixel offset, and the jittered
+     * matrix geometry is actually drawn with.
+     *
+     * **`frameViewProj` stays unjittered and that is the whole design.** The reprojection above is
+     * built from it, and the history holds a resolved picture standing for the *unjittered* scene —
+     * so reprojecting through a jittered matrix would look every sample up half a pixel from where
+     * it is and cancel the accumulation it is trying to build. Only `viewProjFor` jitters, and only
+     * for the frame's own camera.
+     */
+    private readonly temporalHistory;
+    private readonly jitteredViewProj;
+    private temporalJitterX;
+    private temporalJitterY;
+    /** Whether this frame's geometry uploads are jittered. False for a mirror, a probe and when off. */
+    private temporalJittering;
+    /** Whether the resolve may sample what the last frame left. False on frame one, a resize, a cut. */
+    private temporalHistoryUsable;
+    private hasPreviousView;
+    /** The camera the frame was actually drawn with, captured by `bindMeshPass`. */
+    private frameViewProj;
+    /**
+     * That camera's projection, and its inverse, for ambient occlusion.
+     *
+     * The projection alone rather than the whole view-projection, because occlusion is measured
+     * in *view* space: distances there are metres from the eye, so a radius means the same
+     * thing wherever the camera is standing, and the numbers stay small enough that a depth
+     * reconstruction keeps its precision. A world-space reconstruction of the same points would
+     * be the camera's position plus a small offset, which is where a float loses the offset.
+     *
+     * Scratch, filled in `endFrame`, which may not allocate.
+     */
+    private frameProjection;
+    private readonly aoInvProjection;
+    private readonly aoProjScale;
+    /**
+     * Whether this frame has already been resolved to the canvas.
+     *
+     * Anything drawn *after* `endFrame` — a UI inset, a portrait box — belongs on the
+     * presented image, not in a target that has already been sampled. So once the frame is
+     * presented, "back to the whole frame" means the canvas again.
+     */
+    private framePresented;
+    /**
+     * A fence placed behind the first presented frame, and whether it has cleared.
+     *
+     * `endFrame` returning is not the frame being finished — it is the frame being
+     * *asked for*. The driver pays for every pipeline the first time it is used, and
+     * on a built game that bill is 150 ms of a saturated GPU process arriving after
+     * the renderer's own callbacks are back down to a millisecond each (traced
+     * 2026-08-07). A consumer covering the load with a plate has no way to see that
+     * from the main thread, so it uncovers the screen exactly in time for the player
+     * to watch it happen.
+     *
+     * The fence is the only thing that knows. `waited` bounds it: a driver that never
+     * signals must not be able to hold a plate up for ever, and two seconds of frames
+     * is far longer than any first frame and far shorter than a player waiting.
+     */
+    private firstFrameFence;
+    private firstFrameCleared;
+    private firstFrameWaits;
+    private readonly filmUniforms;
+    private readonly skyProgram;
+    private readonly skyUniforms;
+    private readonly skyVao;
+    private readonly scatterProgram;
+    private readonly scatterUniforms;
+    private readonly depthProgram;
+    /**
+     * The depth program that reads a joint palette.
+     *
+     * A second program rather than a uniform gate on the first, which is the decision
+     * `skinning.ts` measured for the flat shader and which is cheaper here: this vertex stage is a
+     * fifth the size, so the second copy dedupes almost entirely.
+     */
+    private readonly depthSkinnedProgram;
+    private readonly depthSkinnedUniforms;
+    private readonly depthUniforms;
+    private readonly depthInstancedProgram;
+    private readonly depthInstancedUniforms;
+    private readonly scatterDepthProgram;
+    private readonly scatterDepthUniforms;
+    private readonly shadowMap;
+    private readonly peeledShadowMap;
+    private readonly dynamicShadowMap;
+    private readonly pointShadows;
+    /**
+     * The layers a world's casting rectangles hold, above the point pool in the same array.
+     *
+     * Null exactly when `pointShadows` is, because an area shadow is read out of that array and
+     * WebGL2 has no seventeenth texture unit to put a second one in. See `areaShadowSet.ts`.
+     */
+    private readonly areaShadows;
+    /** What the lit pass is told about each rectangle. Refilled per frame, never allocated. */
+    private readonly resolvedAreaShadows;
+    /** Per-slot scratch for the area bake round; caller-owned, because that runs every frame. */
+    private readonly areaBakeScratch;
+    /** Said once per renderer, naming the field a rectangle left out. */
+    private warnedAreaShadowRange;
+    /** Said once per renderer, naming the quality flag an area shadow rides. */
+    private warnedAreaShadowsOff;
+    private warnedAreaShadowLayers;
+    /**
+     * How many point lights the array was last sized for.
+     *
+     * Kept because `firstAreaShadowLayer` needs it and the pool does not publish it: the area layers
+     * begin where the pool's end, and re-deriving that from anything else is the one number that must
+     * not be guessed — a rectangle told the wrong first layer samples a lamp's map.
+     */
+    private preparedPointLightCount;
+    /**
+     * Every point light's octahedral map, in one array texture, or null until a world says how
+     * many lights it has.
+     *
+     * Not built in the constructor, because `texStorage3D` is immutable and the size depends on the
+     * world. See `prepareStaticPointShadows`.
+     */
+    private pointShadowArray;
+    /** The photometric atlas, allocated on first use. See `setIesProfiles`. */
+    private iesTexture;
+    /** Rows in that atlas. One until a consumer loads a profile, which is the row of ones. */
+    private iesRows;
+    private cookieTexture;
+    /** Tiles in the cookie atlas. 0 is the white placeholder and the whole off path. */
+    private cookieTiles;
+    /** Horizontal planes each profile occupies. 1 unless something asymmetric was loaded. */
+    private iesPlanes;
+    private readonly planarReflection;
+    /**
+     * The cube six faces are drawn into, and the only one there is however many probes a grid holds.
+     *
+     * **Scratch, and reused by every probe.** A face is consumed the moment the convolution reads
+     * it, so a grid of thirty-two probes needs one capture rather than thirty-two — the same economy
+     * `pointShadowArray.ts` makes with its own single scratch, arrived at the same way.
+     */
+    private readonly probeCapture;
+    /** Every probe of the grid, as one array texture. Allocated when a grid is declared. */
+    private probeArray;
+    /**
+     * Where those probes stand. A single baked probe is a grid of one at that probe's own origin.
+     *
+     * Null until a caller bakes or declares one, because a grid's layer count is what the array is
+     * sized from and `texStorage3D` is immutable.
+     */
+    private probes;
+    /** Whether the grid supplies the scene's ambient. `ProbeBakeOptions.irradiance`, at grid scope. */
+    private probeAmbient;
+    /** Where the probe being baked stands. Reused, so a bake allocates nothing. */
+    private readonly probeOrigin;
+    /**
+     * The convolution that fills the probe's prefiltered cube. Null exactly when the probe is.
+     *
+     * Built beside the probe rather than on first bake, because a program compile in the frame a
+     * caller happens to bake in is a stall in the middle of play — the argument `planarReflection.ts`
+     * makes about its own target, and the same cost.
+     */
+    private readonly environmentPrefilter;
+    /** Said once per renderer; see `updatePointShadows`. */
+    private warnedNoPointShadowArray;
+    /** Said once, for the retired ambient dial. */
+    private warnedEnvironmentAmbient;
+    /** Whether a probe is being baked, so the passes that would recurse into one can tell. */
+    private probePassActive;
+    /** The clip-control extension, or null where this context does not offer it. */
+    private clipControl;
+    /**
+     * Whether this context really is drawing reversed. See `RendererApi.reversedDepth`.
+     *
+     * Separate from `REVERSED_DEPTH`, which is what the engine wants: this is what it got. Every
+     * depth decision below reads this one, so a context without `EXT_clip_control` behaves exactly
+     * as it did before rather than half-reversed — and it is public because a consumer choosing a
+     * near plane needs the granted answer and not the wished-for one.
+     */
+    reversedDepth: boolean;
+    /** `GL_DEPTH_REMAP * camera.viewProjection`, rebuilt once a frame. */
+    private readonly sceneViewProj;
+    /**
+     * One buffer per shadow matrix that outlives a call, and that is not fussiness.
+     *
+     * A single scratch was enough while only the directional pass used it; two passes share the
+     * correction now — the directional pass holds its result for the length of the pass and a point
+     * shadow face holds it for the face — and one buffer means whichever ran last silently rewrites
+     * the other. That is the same aliasing that sent a whole scene through the wrong projection when
+     * the frame projection was cached.
+     */
+    private readonly shadowViewProj;
+    private readonly faceViewProjStore;
+    /** The shim `frameViewFor` hands out. One object, never two live at once. */
+    private readonly correctedView;
+    /**
+     * The scene's view-projection in the space this context's depth buffer expects.
+     *
+     * **The camera's own matrix stays OpenGL-convention and that is deliberate.** `frustum.ts`
+     * extracts its planes on that assumption and says so, and the WebGPU backend corrects at the
+     * last moment for the same reason — so the correction lives here, in the one place that uploads
+     * it, and culling is untouched by any of this. Where the context is not reversed this hands back
+     * the camera's matrix unchanged and multiplies nothing.
+     */
+    private viewProjFor;
+    /**
+     * The same remap for a caller holding a matrix instead of a camera.
+     *
+     * **Only geometry wants this.** A matrix whose depth row never reaches a depth test must stay
+     * raw: `uReflectionViewProj` is read as `.xy / .w` and nothing else, and the motion blur builds
+     * its reprojection from `frameViewProj` and inverts it against a clip z the shader recovered in
+     * OpenGL's sense — remapping either would be correcting something that was never wrong.
+     */
+    /**
+     * The camera as the frame's drawing paths should see it: corrected once, here.
+     *
+     * **This is the seam this backend did not have.** WebGPU applies `CLIP_CORRECTION` in one place
+     * at the last moment; every path here read `camera.viewProjection` for itself, in this file and
+     * in five renderers beside it, so reversing depth meant finding and remapping each one. The
+     * frame now owns one corrected view and hands it over, which is why `FrameView` exists.
+     *
+     * Rebuilt per call rather than cached per frame: `sceneMatrix` writes into one buffer, so a
+     * caller holding this across a second call would see it move. Every consumer uses it and drops
+     * it within the same draw.
+     */
+    private frameViewFor;
+    /** The shadow passes' range correction, which changes the range and not the sense. */
+    private shadowMatrix;
+    private sceneMatrix;
+    private shadowPassActive;
+    /** Non-zero while the drawing buffer is pinned; see `lockDrawingBuffer`. */
+    private lockedWidth;
+    private lockedHeight;
+    private activeShadowMap;
+    private reflectionPassActive;
+    private reflectionReadyThisFrame;
+    private reflectionAtmosphereY;
+    /** Callback state for allocation-free point-shadow depth passes. */
+    private pointShadowCasters;
+    /**
+     * What the depth programs are currently configured to project by, and whether the
+     * pass is peeling.
+     *
+     * Two programs record depth now — rigid meshes and instanced scatter — and only
+     * one can be bound at a time. Rebinding one means re-uploading its matrix, so the
+     * pass records what that matrix is instead of each draw guessing.
+     */
+    private activeDepthViewProj;
+    private activeDepthPeel;
+    /**
+     * Whether the depth pass this scatter draw interrupts wants back-face culling.
+     *
+     * Foliage is two-sided, so a scatter batch must be rasterised with culling off or
+     * a blade facing away from the light casts nothing. The *directional* pass culls;
+     * `PointShadowMap.bake` deliberately culls nothing for all six faces. Blindly
+     * re-enabling after the draw would therefore start culling halfway through a
+     * cubemap — so the pass states what it wants and this restores that.
+     */
+    private depthPassCullsFaces;
+    /**
+     * The one sink handed to every caster enumeration.
+     *
+     * Built once at construction, arrow properties closing over `this`: a sink created
+     * per pass would allocate six objects per light per frame.
+     */
+    private readonly casterSink;
+    private readonly drawPointShadowFace;
+    /**
+     * Viewport in CSS pixels rather than device pixels.
+     *
+     * What screen-space overlays lay out against: sizing text in the drawing
+     * buffer makes it a third the size on a high-DPI phone, which is exactly the
+     * screen where it is hardest to read.
+     */
+    get cssWidth(): number;
+    get cssHeight(): number;
+    /**
+     * Told when the drawing context is lost. See `attachContextLoss`.
+     *
+     * A lost context is a black screen the game does not otherwise notice: nothing
+     * throws, the loop keeps running, and every draw call quietly does nothing.
+     */
+    onContextLost(listener: () => void): void;
+    /**
+     * Told when the drawing context comes back. See `attachContextLoss`.
+     *
+     * **This does not rebuild anything, and cannot:** every resource field on this class is
+     * `readonly` and set in the constructor, which is the same reason a quality change is
+     * construction-time. A listener that wants to draw again has to take the page through a
+     * reload. It is here so the moment is visible in a trace rather than silent, and so the
+     * promise `preventDefault` makes has somebody on the other end of it.
+     */
+    onContextRestored(listener: () => void): void;
+    /** Rebuilt once per `bindMeshPass`, never per draw. */
+    private readonly frustum;
+    /**
+     * Whether a mesh placed by this matrix is anywhere in the frame.
+     *
+     * Valid between `bindMeshPass` and `endFrame`, because that is when a camera has been given.
+     * **A consumer is better placed to use this than `cullDraws` is**: it can skip the model
+     * matrix, the animation update and the material switch as well, none of which the renderer can
+     * avoid once `drawMesh` has been called.
+     */
+    visible(bounds: Bounds, model: ReadonlyMat4): boolean;
+    /**
+     * The occlusion buffer, or null where the profile did not ask for one.
+     *
+     * **Built at the first `bindMeshPass` rather than at construction**, because a field initialiser
+     * runs before the constructor body and `quality` is not resolved yet there. Resized when the
+     * drawing buffer's aspect changes and cleared at every pass — which is also where the
+     * view-projection it projects through comes from.
+     */
+    private occlusion;
+    /**
+     * Declare a box that things behind it may safely be hidden by.
+     *
+     * **Between `bindMeshPass` and the first `drawMesh`**, because the pass is what supplies the
+     * camera and the first test is what freezes the pyramid. A no-op when the profile asked for no
+     * occlusion buffer, so a consumer may call it unconditionally.
+     *
+     * The box is in the model matrix's own space, and it is the box you may be *hidden by* rather
+     * than the one you occupy — an occluder larger than the solid it stands for culls things that are
+     * visible, which is a hole in the world. `OcclusionBuffer` carries the rest of the reasoning.
+     */
+    addOccluder(min: ArrayLike<number>, max: ArrayLike<number>, model: ReadonlyMat4): void;
+    /**
+     * Whether a mesh is entirely behind the occluders declared this frame.
+     *
+     * **False whenever anything is uncertain**, including when no occluders were declared and when
+     * the profile asked for no buffer — so a consumer may call it unconditionally and a scene that
+     * declares nothing behaves exactly as it did before. Read it beside `visible`, which answers the
+     * other half of the same question.
+     */
+    occluded(bounds: Bounds, model: ReadonlyMat4): boolean;
+    private readonly passes;
+    /** Built once so invoking somebody else's pass allocates nothing. See `PassDefinition.draw`. */
+    /**
+     * Built once and mutated, because `drawPass` is a per-frame path and the house rule about
+     * allocation binds it. The grade is written each call, since it depends on the frame.
+     */
+    private passContext;
+    private passDevice;
+    /**
+     * Let something outside this file draw into the frame.
+     *
+     * **The one thing that makes a rendering package possible.** The verb surface here is fixed and
+     * a package cannot add to it, so `splats`, `ui2d` and `xr` had nowhere at all to put a draw
+     * call. `init` runs now rather than at the first frame, because building a pipeline in the
+     * frame loop is the allocation the house rules are about.
+     */
+    registerPass(definition: PassDefinition): PassHandle;
+    /**
+     * How many registered passes declare `prepare`, so a frame with none walks nothing.
+     *
+     * The registry is a slot table and enumerating it every frame to discover that nobody wants a
+     * step is exactly the per-frame work the house rules are about. A counter is one integer and
+     * two increments over the life of a pass.
+     */
+    private preparingPasses;
+    /** Mutated in place, because `beginFrame` is a per-frame path. See `PassDefinition.prepare`. */
+    private prepareContext;
+    /**
+     * Give every pass that owns a target its chance to fill it, before the frame's own is bound.
+     *
+     * **The default framebuffer is bound here and must still be bound when this returns** — the
+     * contract `PrepareContext` writes out. Nothing verifies it, which is the honest state of this
+     * backend: there is no verb-level graph to schedule against, so ordering is the caller's
+     * politeness rather than a property of an encoder. What would make that wrong is two
+     * target-owning passes and one of them misbehaving, and the answer then is a debug build that
+     * reads the binding back after each `prepare` and names the pass that lost it.
+     */
+    private runPreparePasses;
+    /**
+     * Run one, here, now.
+     *
+     * **Immediate, because this backend draws immediately**: the framebuffer the frame is going
+     * into is already bound and a callback *is* a pass. The WebGPU side records it instead and
+     * runs it at the flush, and the difference is invisible to the caller — which is the point of
+     * both. The caller's position in its own draw order is the only thing that decides where this
+     * geometry lands, exactly as it is for every built-in verb.
+     */
+    drawPass(handle: PassHandle): void;
+    /** Let go of a pass. A handle kept past this draws nothing; see `PassHandle`. */
+    unregisterPass(handle: PassHandle): void;
+    /**
+     * Whether this backend can run a compute definition at all. It cannot.
+     *
+     * **A value-typed member answered honestly**, which the 2026-08-13 rule requires of every
+     * backend: a missing method names itself and a missing property is `undefined`, which in
+     * arithmetic is a picture rather than an error. `FrameTimer.available` is the same shape, and
+     * its comment names the alternative as the worst number available to invent.
+     *
+     * What it gives up: a consumer must branch, and a package that wants a GPU sort has to carry a
+     * second implementation. What would make it wrong: nothing short of WebGL2 gaining compute
+     * shaders, which it will not — the specification has none and is closed.
+     */
+    readonly computeSupported: boolean;
+    /** Labels already refused, so a refusal is once a definition rather than once a frame. */
+    private readonly refusedComputes;
+    /**
+     * The table the lit pass fetches, and the scratch the binner fills.
+     *
+     * **Allocated whether or not clustering is on**, because the sampler is declared
+     * unconditionally and a declared sampler needs a complete texture bound to it — an incomplete
+     * one is undefined behaviour a driver may read before it evaluates the branch that would have
+     * skipped it, which is the argument `emptyTexture.ts` already makes. With clustering off this is
+     * one texel rather than 292 KB.
+     */
+    private clusterTexture;
+    private clusterTable;
+    /** Refilled per frame; holds references and allocates nothing. See `resolvePointLights`. */
+    private readonly clusterLights;
+    /** near, far, tan(fovY/2), aspect — written per frame, uploaded as one vec4. */
+    private readonly clusterFrustum;
+    /**
+     * Bind the froxel table and the four numbers that address it.
+     *
+     * **Always, even with clustering off.** `uClustered` is what decides whether the shader reads
+     * any of it, and the binding has to be valid either way; see `clusterTexture`.
+     */
+    /**
+     * Upload the photometric profiles a consumer loaded, and bind the atlas.
+     *
+     * **Called once per set rather than per frame**, because a profile is an asset: a fixture's
+     * distribution does not change while the game runs, and re-uploading it every frame would be a
+     * texture upload per frame for data that is constant.
+     *
+     * Passing an empty list is how a consumer clears them, and it leaves the single row of ones the
+     * atlas falls back to — which is the multiplicative identity rather than darkness, so a scene
+     * that drops its profiles goes back to plain lights rather than going black.
+     */
+    /**
+     * Upload the cookies a consumer loaded, and bind the atlas.
+     *
+     * **One row of square tiles**, `COOKIE_TILE` a side, each image scaled into its tile by the
+     * driver. Called once per set rather than per frame, because a cookie is an asset: a fixture's
+     * mask does not change while the game runs.
+     *
+     * Passing an empty list clears them and leaves the single white texel the atlas falls back to,
+     * which is the multiplicative identity — a scene that drops its cookies goes back to plain
+     * lights rather than going black.
+     *
+     * **The engine ships no cookie and never will**, which is the same line the glyph keys draw:
+     * what a fixture throws is a consumer's art. `zero texture files` in `AGENTS.md` is a rule about
+     * what the *engine* carries, and a consumer's own image has always been allowed — it is what
+     * `createSurfaceTexture` and the material maps take.
+     */
+    setSpotCookies(images: readonly TexImageSource[]): void;
+    setIesProfiles(profiles: readonly PhotometricProfile[]): void;
+    /** Bind the atlas and say how many rows it has. Always, for the reason `bindClusters` gives. */
+    private bindIesAtlas;
+    private bindClusters;
+    /**
+     * Refuse, in words, and hand back the handle that names nothing.
+     *
+     * **This is the defined-state half of the 2026-08-13 rule**, whose other half forbids a silent
+     * no-op. There is nothing to degrade *to* here — a pass this backend cannot run can at least be
+     * an empty method that leaves a visible hole in the picture, and a compute stage has no picture
+     * to leave a hole in. So the degraded state is the refusal itself, spoken at the one moment a
+     * consumer can still act on it: registration, which is init time, where the house rule puts
+     * failures and never the frame loop, where it forbids them.
+     *
+     * **Zero rather than a live handle**, because `definitionAt` already reads zero as naming
+     * nothing — handles start at 1 for exactly this reason — so the `dispatchCompute` that follows
+     * is a no-op which has already announced itself rather than one that never speaks.
+     *
+     * `console.error` rather than a throw, for the reason `createGpuSurface` gives about the same
+     * choice: a consumer registering during boot should get a diagnostic it can act on, not an
+     * exception that takes the page down over a capability it can live without.
+     */
+    registerCompute(definition: ComputeDefinition): ComputeHandle;
+    /** Nothing was registered, so there is nothing to dispatch. See `registerCompute`. */
+    dispatchCompute(_handle: ComputeHandle): void;
+    /** Nothing was registered, so there is nothing to release. See `registerCompute`. */
+    unregisterCompute(_handle: ComputeHandle): void;
+    /** Side length of the depth map, so callers can size the light frustum. */
+    get shadowMapSize(): number;
+    private readonly pickables;
+    private readonly pickOrigin;
+    private readonly pickDirection;
+    /**
+     * Construct the WebGL2 renderer directly.
+     *
+     * @deprecated Use `createRenderer(canvas, quality)`. This constructor can only ever give
+     * you WebGL2, so a consumer that calls it opts out of WebGPU permanently and silently.
+     * `createRenderer` returns the best backend the browser will give, falls back to this one
+     * on its own, and tells you which it built.
+     *
+     * **It keeps working and it is not going away.** Three applications construct one today
+     * and none of them is being made to move on a schedule that is not theirs; the deprecation
+     * is how a *new* consumer is pointed at the right door, not a removal notice. The engine's
+     * own factory calls it, which is the point: this is the implementation of the WebGL2
+     * branch rather than a path being retired.
+     */
+    constructor(canvas: HTMLCanvasElement, qualityOptions?: RenderQualityOptions);
+    /**
+     * Release the drawing context and everything this renderer created on it.
+     *
+     * Needed by any consumer whose renderer does not live as long as its page. A game that
+     * *is* the page builds its renderer once and never tears it down, and for a long time
+     * nothing here noticed the other shape existed: a game embedded in a website is mounted
+     * when the player enters it and unmounted when they leave.
+     *
+     * Without this, each mount leaks a WebGL context. Browsers cap how many a process may
+     * hold — Chrome at around sixteen — and past the cap `getContext` starts returning
+     * null, so the failure is not a slow leak but a game that abruptly refuses to start
+     * with "WebGL2 is not available" on a machine that plainly has it. Entering and
+     * leaving a level a dozen times is enough.
+     *
+     * **The context is not dropped by default, and that is the hard-won part.** The obvious
+     * implementation ends with `WEBGL_lose_context.loseContext()`, since the context is the
+     * capped resource and deleting objects does not hand it back. But the context belongs
+     * to the *canvas*, and the canvas belongs to the consumer — and a canvas whose context
+     * has been lost this way is dead until something calls `restoreContext` on it.
+     *
+     * A React consumer keeps the same `<canvas>` element across an effect re-run, so a
+     * default `loseContext` poisons the element the next renderer is about to be built on:
+     * it reports success, then every call fails with "object does not belong to this
+     * context" and the screen is black. Measured exactly that way while porting an
+     * embedded scene, where a hot reload made it look like the renderer had broken itself.
+     *
+     * So the default frees what this class allocated and leaves the canvas usable. A
+     * consumer that is *discarding* the canvas — the normal unmount — can pass
+     * `releaseContext` to hand the context back immediately rather than waiting for the
+     * element to be collected, which is worth doing because browsers cap contexts per
+     * process (Chrome at about sixteen) and past the cap `getContext` returns null.
+     *
+     * Idempotent, because a teardown path that can run twice — a React effect cleanup
+     * racing an unmount — must not throw on the second call.
+     */
+    /**
+     * Resolve once every pipeline this renderer holds is ready to draw with.
+     *
+     * **Immediate on this backend, and that is the point of it being here.** WebGL2 links a
+     * program synchronously inside `compileProgram`, so nothing is ever outstanding by the time
+     * a caller holds a renderer. WebGPU is the opposite: `createRenderPipeline` returns before
+     * the driver has compiled anything and leaves the shader to the first draw that needs it,
+     * which puts the cost inside a frame with the queue stalled behind it. A consumer awaiting
+     * this before its first frame gets the right behaviour on both without asking which backend
+     * it has, which is the contract `RendererApi` exists to keep.
+     */
+    ready(): Promise<void>;
+    dispose(options?: {
+        releaseContext?: boolean;
+    }): void;
+    createMesh(data: MeshData, options?: MeshOptions): Mesh;
+    /**
+     * Geometry in, handle out — but the geometry lands over as many frames as the caller gives it.
+     *
+     * See `RendererApi.createMeshIncremental` for what this is for and what a caller may do with a
+     * mesh that has not finished arriving. The iterator here adds the one thing `mesh.ts` cannot
+     * know about: **a lost context ends the upload**, because an upload that spans frames can
+     * straddle one and every buffer it was filling is gone. Done with `complete` still false is
+     * the signal that it was abandoned.
+     */
+    createMeshIncremental(data: MeshData, options?: MeshOptions): IncrementalMesh;
+    /**
+     * Compile every flat variant this mesh can be drawn with.
+     *
+     * Shared by the two `createMesh` entry points: which variants a mesh needs is decided by the
+     * data, not by whether the geometry lands in one call or over six frames.
+     */
+    private warmVariants;
+    /**
+     * Rewrite a mesh's positions, and its normals where the caller has them.
+     *
+     * The VAO is left alone: an attribute pointer describes where a buffer's data *is*, and the
+     * buffer is the same buffer. Rebinding here would cost a state change for nothing.
+     */
+    updateMesh(mesh: Mesh, positions: Float32Array, normals?: Float32Array): void;
+    /**
+     * Compile the skinned flat program, once, on the first rigged mesh.
+     *
+     * The four quality flags are construction-time and give this renderer one flat program.
+     * Skinning is not: one scene holds rigged characters and static walls, and both draw through
+     * the lit pass — so it is a second program rather than a fifth flag, selected per draw.
+     *
+     * **It is fed immediately if a pass is already bound.** A program compiled after this frame's
+     * `bindMeshPass` would otherwise carry every uniform at zero, and zero is a real value for most
+     * of them — the failure this file records for `uGrain` and `uAmbientGround`. `createMesh` is
+     * construction rather than a frame path, so the extra write costs nothing anyone measures.
+     *
+     * What it costs is a second compile and a program switch between skinned and unskinned batches,
+     * which a caller controls by drawing its characters together. What would make it wrong is a
+     * fifth quality flag arriving that skinning should have been: it should not, because a quality
+     * flag is chosen once for a renderer and this is chosen per mesh.
+     */
+    private ensureSkinnedProgram;
+    /**
+     * Compile one flat variant, once, and feed it this frame's state.
+     *
+     * Lazy and at `createMesh` for the reason the skinned one was: at construction it costs every
+     * game a compile for a feature most never use, and in the frame loop it could throw where the
+     * rule is that initialisation fails loudly so a running frame never has to.
+     *
+     * **Fed immediately if a pass is already bound.** A program compiled after this frame's
+     * `bindMeshPass` would otherwise carry every uniform at zero, and zero is a real value for most
+     * of them — the failure this file records for `uGrain` and `uAmbientGround`.
+     */
+    private ensureVariant;
+    /**
+     * Upload an image the caller already has, for use as surface colour.
+     *
+     * Takes a `TexImageSource` rather than a URL, and that is the whole boundary: the
+     * engine ships no image assets and fetches nothing, so where the pixels came from —
+     * a canvas drawn procedurally at runtime, a decoded bitmap, a video frame — stays
+     * the consumer's decision. What it gains is a GPU object with sane sampler state.
+     */
+    createSurfaceTexture(source: TexImageSource, options?: SurfaceTextureOptions): SurfaceTexture;
+    /**
+     * Replace a surface texture's pixels, keeping the GPU object and its sampler state.
+     *
+     * Goes through the renderer because the GL context does not leave this directory, and
+     * `SurfaceTexture.update` needs one — without this a consumer could create a texture
+     * and dispose it but never change it, which is exactly the case an image that decodes
+     * *after* the world is built runs into. Re-uploading beats constructing a second
+     * texture: the binding a draw loop already holds stays valid, so the swap is a swap
+     * rather than a rebuild.
+     *
+     * Not a hot path — it re-uploads the whole image and regenerates the mip chain.
+     */
+    updateSurfaceTexture(texture: SurfaceTexture, source: TexImageSource): void;
+    disposeSurfaceTexture(texture: SurfaceTexture): void;
+    /**
+     * Choose the surface texture the following `drawMesh` calls sample, or `null` for none.
+     *
+     * State rather than an argument to `drawMesh`, for two reasons. A texture belongs to a
+     * *material*, and a material covers many draws — a biome's walls are one image and
+     * twenty meshes — so setting it per draw would re-bind the same texture twenty times
+     * to say the same thing. And `drawMesh` already carries a model, a layer and a tint;
+     * a fifth and sixth positional argument is where a signature stops being readable.
+     *
+     * `bindMeshPass` resets this to none, so a pass cannot inherit a material from the
+     * one before it and every caller starts from the same known state.
+     *
+     * `uScale`/`vScale` are repeats across the mesh's own UV range: geometry authored in
+     * metres is textured at whatever density the material wants without rebuilding it.
+     */
+    /**
+     * Choose the joint palette the following `drawMesh` calls skin by, or null for none.
+     *
+     * Null is what an unskinned draw needs and is the default, so a game that never animates never
+     * allocates a palette texture and never leaves one bound.
+     *
+     * The palette is sixteen floats a joint, column-major, exactly as `Skeleton.palette` produces —
+     * this renderer never learns where it came from, which is the boundary that keeps the animation
+     * runtime out of core.
+     */
+    setSkinPalette(palette: Float32Array | null): void;
+    /**
+     * Choose the morph weights the following `drawMesh` calls deform by, or null for none.
+     *
+     * One weight per target the mesh carries. **The weights are per draw and the deltas are per
+     * mesh**, which is the split that matters: two characters sharing one head mesh wear different
+     * expressions without a second copy of the geometry.
+     */
+    setMorphWeights(weights: Float32Array | null): void;
+    setMaterial(material: SurfaceMaterial | null): void;
+    /**
+     * One flat program's view of the current material.
+     *
+     * **The `albedoEnabled` cache that used to guard the last two writes is gone.** It skipped a
+     * `uniform1i` when the flag had not changed, which was correct for one program and is a wrong
+     * answer for two: the second would keep whatever it was left with. One uniform write per
+     * material change is not a cost worth a cache that can be wrong.
+     */
+    private writeMaterialState;
+    /**
+     * @deprecated Use `setMaterial`.
+     *
+     * Kept because it has 56 call sites across four repositories, three of which deploy on push;
+     * removing it is a major version taken deliberately rather than a side effect of adding a map.
+     * `material.test.ts` asserts the two make the same calls, which is the only thing that makes a
+     * wrapper safe to leave standing.
+     */
+    setSurfaceTexture(texture: SurfaceTexture | null, uScale?: number, vScale?: number, cutout?: number): void;
+    /**
+     * Rebind `SURFACE_TEXTURE_UNIT` to whatever `setSurfaceTexture` last put there.
+     *
+     * Only `drawSdfText` calls this, after the atlas has finished borrowing the same unit.
+     * No uniform is written here — the flat program's `uAlbedo`/`uAlbedoEnabled` were never
+     * touched by the text draw and are still correct, since that draw runs its own separate
+     * program. What moved is unit 15's actual `WebGLTexture` binding, which is GL state, not
+     * program state, and this puts it back to what `currentSurfaceTexture` says it should be.
+     */
+    private restoreSurfaceTextureUnit;
+    /**
+     * A pass-level scale over the grain the geometry itself declared, 0 to 1.
+     *
+     * Which surfaces are mineral is now `MeshData.grain`, stated per vertex through
+     * `MeshBuilder.setGrain` — because it is a property of a material, and absent means none.
+     * This stays as the override for the case that has no answer to state: an imported model
+     * arrives with no grain information at all, and a caller drawing one decides for it.
+     *
+     * Pass state, like `setSurfaceTexture`, because a material covers many draws. The default
+     * is 1 and `bindMeshPass` restores it, so it scales geometry that declared grain and
+     * leaves geometry that did not exactly as it is.
+     */
+    /**
+     * How much of the environment the following draws mirror, 0 to 1.
+     *
+     * Pass state beside the grain, and the counterpart to it: grain is a surface being uneven,
+     * this is a surface being smooth enough to carry an image. Polished paint, glass, chrome
+     * and still water want it; plaster and stone want none.
+     *
+     * Defaults to zero and bindMeshPass restores it, so a scene that never calls this looks
+     * exactly as it did.
+     */
+    setSurfaceReflectivity(amount: number): void;
+    /**
+     * How bright the environment the surfaces drawn next reflect is. 1 is the default and identity.
+     *
+     * See `uEnvironmentGain` in the preamble for the whole argument. In one line: a metal's Fresnel
+     * base is its own albedo, so it takes no ambient and no direct diffuse and *is* its reflection,
+     * and when the only environment is a cube of nearby geometry that leaves it as dark as the room
+     * happens to be. This is the stand-in for the image-based lighting that would carry the sky and
+     * the sources instead, and it goes away when there is one.
+     *
+     * Not clamped above: the case it exists for is a room that is too dim, and a value below 1 is as
+     * legitimate as one above. Held non-negative, because a negative environment is not a darker one.
+     */
+    setEnvironmentGain(gain: number): void;
+    /**
+     * Kept as a no-op that says so once, because it was a stand-in for a term that now exists.
+     *
+     * It mixed the ambient toward a box-filtered level of the probe, three below the coarsest,
+     * lifted by a `max` so a partial probe could not darken a subject. Irradiance is nine projected
+     * spherical-harmonic coefficients now, evaluated per fragment against the normal, and it is on
+     * whenever a probe has been baked — with nothing to tune, because an approximation needed a dial
+     * for the ways it was wrong and a cosine integral does not have them.
+     *
+     * **Deprecated rather than removed, and that is a compatibility decision rather than a
+     * preference.** It is on the public surface and consumers call it; deleting it today would be a
+     * breaking change across four repositories to save one method. It goes at the next major, where
+     * a coordinated release is happening anyway.
+     */
+    setEnvironmentAmbient(_amount: number): void;
+    setSurfaceGrain(amount: number): void;
+    /**
+     * How strong the microscopic relief on the surfaces drawn next is, and how coarse.
+     *
+     * **The material half of `MeshData.relief`.** The geometry says which surfaces have texture;
+     * this says what texture, because the same amount over a different scale is a different
+     * material entirely. Asphalt is coarse and deep, roughly 60 bumps to the metre at full
+     * strength; cast concrete is finer; orange peel on paint is finer again and shallow. The
+     * geometry carrying all three is identical, which is exactly why the two halves are separate.
+     *
+     * `amount` scales whatever each vertex declared, so 0 switches it off for a pass without
+     * rebuilding a mesh, the same way `setSurfaceGrain` does. `cyclesPerMetre` is how many bumps
+     * fit in a metre of world.
+     *
+     * **The roughness of a surface grows with its relief**, automatically and not optionally: a
+     * normal that wanders cannot hold a highlight narrower than the wander, and a narrow one on a
+     * fast-varying normal is the sub-pixel sparkle 0.20.0 was spent removing. The amount is known
+     * here rather than measured off the screen, which is what makes it safe; see the specular
+     * speckle entry in docs/IMPROVEMENTS.md for the version that measured it instead and made
+     * things three times worse.
+     *
+     * Defaults to off and `bindMeshPass` restores that, so a scene that never calls this is
+     * unchanged.
+     */
+    setSurfaceRelief(amount: number, cyclesPerMetre?: number): void;
+    /**
+     * How hard the bound surface texture's own luminance turns the shading normal, 0 for not at all.
+     *
+     * **Relief a photograph can give, where `setSurfaceRelief` invents it.** Noise is the right
+     * answer for asphalt and cast concrete, whose structure has no particular arrangement. A rock,
+     * a bark, a hammered plate has one: the bumps are where the picture says they are, and no noise
+     * function can know where that is. This reads the height off the image `setSurfaceTexture`
+     * already bound as colour, so a surface lights as the thing the photograph is of.
+     *
+     * **One image in both roles rather than a second sampler**, which is a decision with a cost
+     * behind it: the fragment shader's widest permutation already declares more samplers than this
+     * project's adapter offers and is legal only because several of them are marked as shared. It
+     * is also the ordinary case rather than an unusual one, since a scene handing one image to
+     * three.js's `map` and `bumpMap` together is exactly what this replaces.
+     *
+     * Scaled as three.js's `bumpScale` is, so a scene porting one carries the number over rather
+     * than refitting it by eye, and a negative value inverts the relief there and here alike.
+     * Deliberately not clamped to 0..1 the way `setSurfaceRelief` and `setSurfaceGrain` are: those
+     * scale something the geometry declared, and this is an amplitude against a luminance gradient
+     * with no natural ceiling.
+     *
+     * Nothing happens without a texture bound, because the shader gates on the same flag
+     * `setSurfaceTexture(null)` clears. Defaults to off and `bindMeshPass` restores that, so a
+     * scene that never calls this is unchanged.
+     */
+    setSurfaceTextureRelief(scale: number): void;
+    /**
+     * Release a mesh's GPU buffers.
+     *
+     * Needed by anything that rebuilds geometry at runtime — a character
+     * customiser recolouring an avatar, a level editor, a streamed chunk. Without
+     * it every rebuild leaks a VAO and its buffers, which is invisible until a
+     * player has spent a minute on one screen.
+     */
+    /**
+     * Scale the emissive of the following draws, or reset to what the environment says.
+     *
+     * Pass state, like `setSurfaceTexture`, and for the same reason: emissive strength
+     * belongs to a *material* and a material covers many draws. `bindMeshPass` sets it from
+     * `env.emissiveGain` and this overrides it between draws.
+     *
+     * It exists because emissive is per-vertex data, so anything that *pulses* — a threshold
+     * breathing, a ceiling answering a kick drum — could not be expressed at all without
+     * rebuilding geometry every frame. The light around such a thing could pulse and the
+     * glowing surface itself could not, which reads as a lamp brightening while its own bulb
+     * stays flat.
+     */
+    setEmissiveGain(gain: number): void;
+    /** The instanced program, compiled on first use. See `ensureInstancedProgram`. */
+    private flatInstancedProgram;
+    private flatInstancedUniforms;
+    /**
+     * Compile the instanced variant, once, and feed it this frame's pass state.
+     *
+     * The same shape as `ensureVariant` and for the same reason: a program compiled after this
+     * frame's `bindMeshPass` would otherwise carry every uniform at zero, and zero is a real value
+     * for most of them — `uGrain` unwritten switches grain off across every surface rather than
+     * weakening it.
+     */
+    private ensureInstancedProgram;
+    /**
+     * Attach per-instance placement to a mesh already on the device.
+     *
+     * One batch per mesh: the attributes bind to the mesh's own vertex array, of which a mesh has
+     * one. `Mesh.attachInstances` is what refuses a second, and says why.
+     */
+    createInstanced(mesh: Mesh, capacity: number): InstancedBatch;
+    /** Push placement and colour. Only the live prefix. */
+    uploadInstanced(batch: InstancedBatch, data: MeshInstances): void;
+    /** Draw every live instance, opaque. */
+    drawInstanced(batch: InstancedBatch, data: MeshInstances): void;
+    /** Draw every live instance, blended. See `drawTranslucentMesh` for what the options mean. */
+    drawTranslucentInstanced(batch: InstancedBatch, data: MeshInstances, opacity: number, options?: TranslucentMeshOptions): void;
+    /** Release the placement. The mesh is the caller's and is not released. */
+    disposeInstanced(batch: InstancedBatch): void;
+    /**
+     * One draw and one material, however many instances.
+     *
+     * **No `uModel` and no `uTint` written**, because the instanced program declares neither — its
+     * placement and colour arrive as attributes. Writing them would be a `uniform*` call against
+     * location `null`, which GL ignores, so this would look like it worked; it is left out because
+     * saying it is the point of the variant.
+     *
+     * **No frustum cull**, unlike `drawMesh`. A batch's bounds are the union of its instances and
+     * the mesh's own bounds describe one of them at the origin, so testing that box would cull a
+     * street of cars whenever the copy at the origin left the view. Culling a batch is the
+     * consumer's, which is also where the placements are.
+     */
+    private submitInstanced;
+    disposeMesh(mesh: Mesh): void;
+    /**
+     * Release a resource this renderer created, for every kind that needs the context back.
+     *
+     * **Reported from outside, and it was a real leak.** `disposeMesh` and
+     * `disposeSurfaceTexture` existed and nothing else did, so eight other kinds of resource
+     * were handed out with no way to release them: each one's own `dispose` takes the
+     * `WebGL2RenderingContext`, which this package deliberately never exposes. The engine's own
+     * demos could call them because they hold their own `gl` from creating the canvas; nobody
+     * outside could. It costs nothing when a consumer tears the whole renderer down, since
+     * releasing the context takes the programs and buffers with it, and it costs a program per
+     * rebuild for anyone who swaps weather or scenery without rebuilding the renderer. That is
+     * the ordinary case for a scene that changes, and the consumer who reported it was leaking
+     * one per scenario switch and living with it.
+     *
+     * Each guards on a lost context for the same reason `disposeMesh` does: the old context took
+     * its objects with it, and asking the new one to delete them is an INVALID_OPERATION apiece,
+     * which buries whatever caused the loss under a page of noise.
+     */
+    disposePlumes(plumes: PlumeRenderer): void;
+    /** Release a wind streak lattice. See `disposePlumes`. */
+    disposeWindStreaks(streaks: WindStreakRenderer): void;
+    /** Release a flock. See `disposePlumes`. */
+    disposeFlock(flock: FlockRenderer): void;
+    /** Release an instanced batch made by `createScatter`. See `disposePlumes`. */
+    disposeScatter(scatter: InstancedMesh): void;
+    /** Release a particle batch. See `disposePlumes`. */
+    disposeParticles(particles: ParticleBatch): void;
+    /** Release a bolt batch. See `disposePlumes`. */
+    disposeBolts(bolts: BoltBatch): void;
+    /** Release a line batch. See `disposePlumes`. */
+    disposeLines(lines: LineBatch): void;
+    /** Release a water renderer. See `disposePlumes`. */
+    disposeWater(water: WaterRenderer): void;
+    /** Release a caustics renderer. See `disposePlumes`. */
+    disposeCaustics(caustics: CausticsRenderer): void;
+    createPlumes(plumes: readonly PlumePlacement[], options: PlumeOptions): PlumeRenderer;
+    createWindStreaks(options?: WindStreakOptions): WindStreakRenderer;
+    /** Draw after the opaque scene: streaks are blended and write no depth. */
+    drawWindStreaks(streaks: WindStreakRenderer, camera: Camera, wind: WindField, timeSeconds: number, tint: Vec3, env: Environment): void;
+    /**
+     * A 3D text object: one string, drawn as instanced glyph cubes over the
+     * scene. Create one per message slot and reuse it — `setText` is a no-op when
+     * the string has not changed.
+     */
+    createText(): TextRenderer;
+    /** Lay a string out. A no-op when it is the string already laid out. */
+    setText(text: TextRenderer, content: string): void;
+    /** A solid rectangle of cells, for a keycap or a backing plate. See `TextLayout.setPlate`. */
+    setPlate(text: TextRenderer, widthCells: number, heightCells: number, bottomCell: number): void;
+    /**
+     * Draw a laid-out string over the scene.
+     *
+     * The viewport is the caller's rather than this renderer's: an overlay is positioned in
+     * whatever box the caller lays out in, and the game's own card is not always the canvas.
+     */
+    drawText(text: TextRenderer, viewportWidth: number, viewportHeight: number, originX: number, originY: number, style: TextStyle, timeSec: number): void;
+    /** Width of the string this handle currently holds, in pixels at a given cell size. */
+    textWidth(text: TextRenderer, cellSize: number): number;
+    disposeText(text: TextRenderer): void;
+    /**
+     * A text label from an SDF font. Opt-in: a consumer that never calls this pays nothing,
+     * which is what keeps `pixelFont.ts`'s no-asset promise true for everybody else.
+     */
+    createSdfText(): SdfTextRenderer;
+    /**
+     * Lay a string out against a font, and retain the atlas `drawSdfText` will sample.
+     *
+     * The engine fetches nothing: `font` was parsed from a metrics document the caller already
+     * had, and `atlas` is a `SurfaceTexture` the caller already uploaded. A no-op, and no
+     * re-upload, when neither the text nor the style moved since the last call.
+     */
+    setSdfText(handle: SdfTextRenderer, font: SdfFont, atlas: SurfaceTexture, content: string, style: SdfTextStyle): void;
+    /**
+     * Draw a laid-out SDF string into the scene, at `model`.
+     *
+     * Takes no camera: it draws against the view-projection `bindMeshPass` captured for the
+     * frame, the same one `drawMesh` uses, so a caller positions text with a model matrix
+     * alone — `billboardMatrixY` for a label that faces the camera, a surface's own matrix for
+     * one painted flush against it. A no-op before the first `bindMeshPass` of a session, same
+     * as every other pass that reads `frameViewProj`.
+     *
+     * **Puts `SURFACE_TEXTURE_UNIT` back the way it found it.** The atlas binds through
+     * `SDF_TEXT_TEXTURE_UNIT`, which is that same unit — see the constant's own comment for
+     * why that is safe — so once the glyphs are drawn this rebinds whatever `drawMesh`'s
+     * material state currently says should be there. Without it, a `drawMesh` call *after*
+     * this one would go on sampling unit 15 as its albedo and find the glyph atlas sitting on
+     * it instead of its own texture. Skipped when nothing was actually drawn, since only a
+     * real draw call touches the unit in the first place.
+     */
+    /**
+     * The output transform a forward pass should apply, and the exposure it should apply it at.
+     *
+     * **Only where that pass is genuinely the last one to touch the frame.** With a scene target
+     * the resolve grades, so a pass that graded as well would be applying a curve to its own
+     * output, and grading early throws away the range a float target exists to keep. With
+     * `screenEffects` off there is no resolve at all and every pass writes straight to the canvas,
+     * so each one has to grade itself or the frame comes out half converted: linear values in an
+     * eight-bit buffer read as display values, which is a saturated, clipped version of the colour
+     * the caller asked for rather than a slightly different one.
+     *
+     * One pair of accessors rather than the expression written out at each site, because that is
+     * how the mesh pass and the particle pass came to disagree in the first place: the mesh pass
+     * gated, and the particle pass uploaded the transform unconditionally to a stage that did not
+     * yet declare it.
+     */
+    private gradeCode;
+    private gradeExposure;
+    drawSdfText(handle: SdfTextRenderer, model: Float32Array, color: Vec3, opacity: number): void;
+    /** Release an SDF text label. Takes no context; see `disposeText`. */
+    disposeSdfText(handle: SdfTextRenderer): void;
+    createFlock(count: number): FlockRenderer;
+    drawFlock(flock: FlockRenderer, camera: Camera, timeSeconds: number, params: FlockParams, tint: Vec3, windX?: number, windZ?: number): void;
+    /**
+     * Build a scatter batch and fill it. Takes the data rather than handing back
+     * something the caller has to upload, because uploading needs the GL context
+     * and that never leaves this directory (AGENTS.md).
+     */
+    createScatter(base: MeshData, data: InstanceData): InstancedMesh;
+    /**
+     * Push changed instances to the GPU.
+     *
+     * Only for batches that *move*. Foliage is placed once at generation and never
+     * touched again, so `createScatter` uploads it and `drawScatter` deliberately does
+     * not — a per-frame upload of every blade of grass in the world would be pure waste.
+     *
+     * A live particle system is the other case, and it was silently broken: the drift
+     * plume's grains were drawn from the positions they happened to hold at boot, because
+     * nothing ever re-uploaded them. Only the *count* animated, so a drift threw a
+     * growing pile of stationary grit instead of a spray. Explicit rather than automatic,
+     * so the cost stays visible at the call site that needs it.
+     */
+    uploadScatter(scatter: InstancedMesh, data: InstanceData): void;
+    /**
+     * Build a particle material: one program, one VAO, one draw call per pool.
+     *
+     * A material rather than a renderer, and the distinction is the reason this
+     * exists at all. Particles used to be drawn through `drawScatter` — the foliage
+     * material — which is opaque, lit like a leaf and has no opacity channel, so
+     * every effect in the game that emitted particles rendered as small solid cubes
+     * that turned black instead of fading. The fix is not a tuning pass on the
+     * emitters; it is a material that knows what a particle is.
+     */
+    createParticles(capacity: number, options: ParticleBatchOptions): ParticleBatch;
+    /**
+     * Draw a live particle pool.
+     *
+     * Uploads and draws together, unlike the scatter path where the two are
+     * deliberately separate: a particle pool's data changes *every* frame without
+     * exception, so leaving the upload to the caller only creates the opportunity to
+     * forget it — which is exactly what happened to the skate sparks, drawn for a
+     * whole milestone from a buffer nothing had ever written.
+     */
+    drawParticles(batch: ParticleBatch, data: ParticleInstances, camera: Camera, env: Environment, timeSeconds: number): void;
+    /** Build a batch for electrical arcs. `capacity` is in segments, not arcs. */
+    createBolts(segmentCapacity: number, label?: string): BoltBatch;
+    /**
+     * Draw a pool of arcs.
+     *
+     * `widthM` is the filament's own half-width and `minWidthPerMetre` the floor that
+     * keeps a distant arc above a pixel — under one, a bright thin line does not fade,
+     * it strobes as the rasteriser catches it on some frames and not others.
+     */
+    drawBolts(batch: BoltBatch, data: BoltSegments, camera: Camera, env: Environment, timeSeconds: number, core: Vec3, edge: Vec3, widthM: number, coreGain: number, minWidthPerMetre?: number): void;
+    /**
+     * A polyline with a real width, for anything that is a stroke rather than a surface.
+     *
+     * Separate from `drawBolts` rather than a flag on it. The two share a vertex expansion
+     * and nothing else: an arc is additive, unlit, unfogged and jittered along its own path,
+     * a line is a flat fogged colour with a clean edge. A `jitter: 0` argument meaning
+     * "actually draw a line" would be a noun lying about what it draws, which `AGENTS.md`
+     * rules out for good reasons.
+     *
+     * There is no portable alternative. WebGL2 clamps `lineWidth` to one pixel on nearly
+     * every driver and WebGPU has no line width at all, so a wide line is a triangle
+     * everywhere or it is nowhere.
+     *
+     * **A handle holds one polyline's geometry for the frame it is drawn in.** Drawing it more
+     * than once in a frame is fine — three widths of one shape is exactly that, and costs nothing
+     * beyond the re-upload — because the data underneath does not change between those calls.
+     * *Changing* what it holds and drawing it more than once in the same frame is not fine: on
+     * WebGPU, `queue.writeBuffer` does not interleave with a pass's already-recorded draw
+     * commands, so every draw against this handle in a frame reads whichever write landed last by
+     * the time the frame submits, not the content that was current when each call was made.
+     * WebGL2 draws immediately on each call and happens to give the answer a caller expects, so
+     * the two backends disagree silently rather than loudly. A caller drawing several polylines
+     * whose geometry differs within one frame needs one handle each, not one handle reused.
+     */
+    createLines(segmentCapacity: number, label?: string): LineBatch;
+    /**
+     * Draw a polyline.
+     *
+     * `widthM` is the stroke's own half-width and `minWidthPerMetre` the floor that keeps a
+     * distant line above a pixel — under one, a thin line does not fade, it strobes as the
+     * rasteriser catches it on some frames and not others. `softness` widens the antialiased
+     * edge inward, as a fraction of the half-width; zero is a clean edge.
+     */
+    drawLines(lines: LineBatch, data: LineSegments, model: ReadonlyMat4, camera: Camera, env: Environment, color: Vec3, widthM: number, opacity: number, softness?: number, minWidthPerMetre?: number, additive?: boolean): void;
+    /**
+     * Draw a scatter batch. Wind arrives as a value rather than being sampled
+     * here: every system in the world must answer to the same gust, and a
+     * renderer that sampled its own would be a second wind by definition.
+     *
+     * **It binds no point lights, and that is a rule about what may be instanced rather than a
+     * performance note.** A field of grass shaded by ten lamps is a cost nobody wanted, so this
+     * material answers to the sun and the ambient alone. The consequence is invisible from the
+     * call site and a consumer has to know it: anything a lamp in the scene is meant to reach has
+     * to be merged into a mesh instead. Choosing wrongly is not slow, it is unlit. Reported from
+     * outside, where it had become a rule written on a consumer's own wrapper.
+     */
+    drawScatter(scatter: InstancedMesh, data: InstanceData, camera: Camera, env: Environment, windX: number, windZ: number, windGust: number, timeSeconds: number, 
+    /**
+     * Recent presses, from a `TrampleField`, or null for foliage nothing walks
+     * through. Four floats per slot: world position and how pressed.
+     */
+    trample?: Float32Array | null): void;
+    /**
+     * Upload the instance transform's inputs — the shared half of the scatter material.
+     *
+     * One function for both scatter programs, so the picture and its shadow are bent
+     * and pressed by identical numbers. Splitting these into two call sites is how the
+     * two poses drift apart by a tuning constant nobody remembers changing twice.
+     */
+    private bindScatterDeform;
+    /** Refilled per call rather than allocated; see `createScatterDeform`. */
+    private readonly deform;
+    /**
+     * The frame's wind, as the mesh and depth programs read it.
+     *
+     * **A second target from `deform` above, and one conversion between them.** The scatter batch
+     * takes its wind as arguments to its own draw call, which predates this, so the two cannot share
+     * a target without changing that signature. What they do share is `resolveScatterDeform`, which
+     * is where every number that matters is decided — a normalised direction, metres of bend from a
+     * speed, a gust amplitude and a scaled clock. `scatterDeform.ts` says why that has to be one
+     * function: a copy of any of those conversions drifts, and a field of grass then leans
+     * differently from the canopy above it.
+     *
+     * **What this does not defend against** is a consumer calling `setWind` with one gust and
+     * `drawScatter` with another. That is the same hazard `drawFlock` already carries, and the
+     * answer is the one AGENTS.md gives: sample the field once a frame and pass it down.
+     */
+    private readonly frameWind;
+    /**
+     * The five wind uniforms, uploaded through one function wherever they are read.
+     *
+     * Separate from the trample array beside it because the mesh programs want the wind and have no
+     * concept of something having walked through them.
+     */
+    private uploadWind;
+    /**
+     * The frame's wind, sampled once by the caller and handed down.
+     *
+     * Every mesh carrying a per-vertex channel bends to this, in the colour pass and in the depth
+     * pass, so a canopy and its own shadow move together. A caller that never calls it gets a still
+     * world, which is exactly what every scene drew before the channel existed.
+     */
+    setWind(windX: number, windZ: number, windGust: number, timeSeconds: number): void;
+    /** The point-shadow set, chosen by the pool and bound below. Refilled, never allocated. */
+    private readonly resolvedPointShadows;
+    /**
+     * Put the resolved point-shadow set on the GL program: one array texture and five arrays.
+     *
+     * **It was twelve cubemaps on twelve units.** They are one `TEXTURE_2D_ARRAY` now, a layer per
+     * light, which is where eleven of WebGL2's sixteen guaranteed units came back from.
+     *
+     * **The thin half of a split, and the arrays are why it is worth splitting.** Everything
+     * about *which* map a light samples and how present it is comes out of the pool, which both
+     * backends share; this turns that into a texture unit and `uniform*v` calls, which is the only
+     * part WebGL2 does differently.
+     *
+     * The array uniforms are addressed as `name[0]`, and that is not decoration. GLSL ES exposes
+     * an array uniform under the name of its first element; `name[1]` returns nothing from the
+     * cached table, so uploading element by element left slots 1–7 at zero and made their shadows
+     * vanish.
+     */
+    private bindPointShadows;
+    /** The same, for a light volume's local-space camera; see `createResolvedLightVolume`. */
+    private readonly volume;
+    createWater(resolution?: number, nearExtent?: number, farHalfExtent?: number): WaterRenderer;
+    /**
+     * Surfaces lit from below by the water under them.
+     *
+     * Null when the profile has water off or there is nothing to light, so a world
+     * with no covered water pays no program compile, no buffer and no draw. The
+     * matching draw accepts null for the same reason: a caller should not need a
+     * branch to express "this world has none".
+     */
+    createCaustics(sheets: readonly CausticSheet[]): CausticsRenderer | null;
+    drawPlumes(plumes: PlumeRenderer, camera: Camera, timeSeconds: number, env: Environment, windX?: number, windZ?: number, originX?: number, originY?: number, originZ?: number): void;
+    drawWater(water: WaterRenderer, camera: Camera, timeSeconds: number, settings: WaterBody, env: Environment, windX?: number, windZ?: number): void;
+    /**
+     * Draw after the opaque scene: this is light added to surfaces already shaded,
+     * from the water under them.
+     */
+    drawCaustics(caustics: CausticsRenderer | null, camera: Camera, timeSeconds: number, env: Environment, windX?: number, windZ?: number, strength?: number): void;
+    /**
+     * Begin a scene render mirrored across a horizontal plane. Draw ordinary
+     * mesh, sky and plume passes with the returned camera, then call
+     * `endPlanarReflection`; the next water draw samples the completed target.
+     */
+    /**
+     * **This is a water feature, not a renderer one, and the name hides that.**
+     *
+     * The target is allocated only when `water` *and* `waterReflections` are both on, and the
+     * only thing that samples it is `WaterRenderer`. So a scenario whose ground is a mesh slab
+     * with `drawFilm` patches over it, which is what a wet street is, cannot mirror the scene
+     * into it however it calls this. Reported from outside after being attempted, which is the
+     * cost of a name that promises more than the wiring does.
+     *
+     * What is available to a surface that is not water: `bakeReflectionProbe`, which is a room
+     * rather than a mirror, and `drawFilm`'s sheen, which is iridescence rather than reflection.
+     * Neither is a substitute for a mirrored pass and this comment is not pretending otherwise.
+     */
+    beginPlanarReflection(source: Camera, planeY: number, clearColor: Vec3): Camera | null;
+    endPlanarReflection(): void;
+    get aspect(): number;
+    /**
+     * Point rendering back at the frame's own target, whole.
+     *
+     * Every pass that borrows the viewport — the shadow maps, the reflection, the export
+     * target, an inset — has to hand it back, and each of them was spelling the same three
+     * arguments out. Five copies of "what does the full frame mean" is five chances to drift
+     * from the drawing buffer's real size after a resize.
+     *
+     * It restores the **framebuffer** as well, and that is not tidiness. A borrowing pass
+     * releases by binding `null`, which is the canvas — correct when the canvas was where the
+     * frame was going, and wrong the moment a scene target exists: everything drawn after a
+     * reflection would land on the canvas and then be overwritten by the resolve of a target
+     * missing half its content. This is the one place that knows where a frame is going, so
+     * it is the one place that can say so.
+     */
+    private restoreViewport;
+    /**
+     * Match the drawing buffer to CSS size × clamped DPR, under the pixel budget.
+     * Cheap when unchanged.
+     *
+     * The budget is deliberately not applied to a locked buffer: a lock is a caller naming
+     * an exact size for a reason no quality setting knows about — a clip is 1080x1920
+     * whatever anybody's frame rate is — and silently handing back a different one would
+     * write a file that is not the size it claims.
+     */
+    resize(): void;
+    /**
+     * Move the drawing-buffer area cap, in pixels. Zero is uncapped.
+     *
+     * Live, unlike every other quality lever, and that is the feature rather than an
+     * inconsistency. The rest size an allocation at construction — shadow maps, reflection
+     * targets, the wave surface — so moving one means rebuilding every GPU resource the
+     * world hangs off. This one only changes how many pixels the next frame covers, and
+     * everything sized from the drawing buffer already re-fits itself when it changes. A
+     * player hunting their own frame rate can therefore move this and see the answer, which
+     * is the only way anybody finds out that pixels were what it cost them.
+     */
+    setMaxDrawingBufferPixels(pixels: number): void;
+    /**
+     * Move the drawing-buffer density cap at runtime, without rebuilding anything.
+     *
+     * Live for the same reason `setMaxDrawingBufferPixels` is, and it is the other half of
+     * the same idea: `resize()` re-reads this cap, and the scene target and the planar
+     * reflection are both sized *from* the drawing buffer, so nothing here owns an
+     * allocation that a new density invalidates.
+     *
+     * This is the one quality lever a governor can drive, which is exactly why the governor
+     * drives this and not the preset. A preset means shadow maps and wave surfaces sized at
+     * construction; changing one of those mid-session means rebuilding every GPU resource the
+     * world hangs off, and that is what a reload is for.
+     *
+     * Cheap to call every few hundred frames and pointless to call every frame: it forces a
+     * `resize()`, which reallocates the scene target when the size actually changes.
+     */
+    applyResolutionScale(scale: number): void;
+    /**
+     * The density actually in force, which is where a governor has to start from.
+     *
+     * `applyResolutionScale` could always be *written* and never read, and that was enough for
+     * the consumer that drives it from a stored preset. It is not enough for one that drives it
+     * from measurement: `ResolutionGovernor` is constructed around a starting scale and moves
+     * relative to it, so a caller with no way to ask has to guess.
+     *
+     * **The effective density and not `maxDpr`, and the difference is not academic.** `maxDpr` is
+     * a *ceiling*: `resize` takes `min(devicePixelRatio, maxDpr)`, so on an ordinary 1x display a
+     * ceiling of 2 is already doing nothing. A governor seeded from the ceiling there spends its
+     * first four decisions walking 2 down to 1 while the drawing buffer does not change by a
+     * single pixel, which is a machine stuttering for several seconds through a fix that is
+     * being applied to a number nobody is reading. Found exactly that way, at 20x throttle: three
+     * decisions, no change in buffer size.
+     *
+     * `capabilityClamp` is the other half of the same point, and it argues the same direction:
+     * `maxDevicePixelRatio` is a request the clamp is entitled to have already lowered.
+     */
+    get resolutionScale(): number;
+    /**
+     * Pin the drawing buffer to an exact pixel size, ignoring CSS and DPR.
+     *
+     * For recording a frame at a size that has nothing to do with the window: a
+     * clip is 1080x1920 whatever shape the browser is, and `aspect` follows the
+     * lock, so a camera given `renderer.aspect` composes for the *export* rather
+     * than for the screen. That is the difference between rendering at an aspect
+     * and cropping to one, and cropping throws away the half of the frame the shot
+     * was built around.
+     *
+     * Not a quality option, deliberately. `RenderQualityOptions` describes how good
+     * the picture is for the whole session and is resolved before any GPU resource
+     * exists; this is a temporary, caller-driven override that must be released.
+     * The CSS box is untouched — a page that wants the preview letterboxed is
+     * styling, not rendering.
+     */
+    lockDrawingBuffer(width: number, height: number): void;
+    /** Back to following the CSS box. The next `resize` restores it. */
+    unlockDrawingBuffer(): void;
+    /**
+     * Render one directional shadow layer. Bracket `drawShadowCasters` calls
+     * between this and `endShadowPass`. Static and dynamic layers are sampled
+     * together; pass `shadowStrength: 0` whenever the dominant source is not
+     * emitting, because a stale map must never be sampled.
+     */
+    beginShadowPass(lightViewProj: ReadonlyMat4, layer?: 'static' | 'static-peel' | 'dynamic'): void;
+    /**
+     * Submit everything that casts into the layer `beginShadowPass` opened.
+     *
+     * The same `ShadowCasters` closure the point-light bakes are given, so a world has
+     * exactly one answer to "what occludes light" and the sun and the lamps cannot
+     * disagree about it. A no-op when the profile has directional shadows off.
+     */
+    /**
+     * The same enumeration, replayed into the colour pass that is open.
+     *
+     * See `SceneCasters` in `shadowCasters.ts` for why this exists and why scatter is declined. The
+     * sink is built once and held, because a caster enumeration runs per pass and a sink allocated
+     * per call would allocate per pass.
+     */
+    private readonly sceneCasterSink;
+    /**
+     * The material the open replay has bound, or `undefined` before its first entry.
+     *
+     * The twin of the WebGPU field, which carries the whole argument: a sink's material is optional
+     * and omitting it means *no material* rather than *unchanged*, so a run of entries sharing one
+     * material had no shorter spelling and bound once per entry. What it costs here is not a ring
+     * that runs out but `setMaterial`'s own body — a `useProgram` and a full `writeMaterialState`
+     * for **every** flat program, texture binds included, per entry rather than per surface.
+     *
+     * Reference identity, and `undefined` rather than `null` for "nothing bound yet", both for the
+     * reasons given there.
+     */
+    private sceneCasterMaterial;
+    /** Bind one replay entry's material, unless it is the one already standing. */
+    private bindSceneCasterMaterial;
+    /**
+     * Draw everything a caster enumeration contains into the open colour pass, with its materials.
+     *
+     * The colour counterpart of `drawShadowCasters`, so one closure answers "what is in this frame"
+     * for the shadow cascade, every cubemap face, and a second viewpoint such as a mirror or a probe
+     * face. What it replaces is a consumer re-entering its whole draw path with a second camera.
+     */
+    drawSceneCasters(casters: ShadowCasters): void;
+    drawShadowCasters(casters: ShadowCasters): void;
+    endShadowPass(): void;
+    /**
+     * The lit program, built at the largest light budget this device will actually link.
+     *
+     * **Why the engine fits the shader to the part rather than leaving it to a consumer.** `flat`
+     * at the full budget declares **440** rows of the fragment uniform grid — twenty arrays sized by
+     * `MAX_LIGHTS` and fourteen by `MAX_AREA_LIGHTS`, and GLSL ES gives an array a whole row per
+     * element whatever its base type. An Adreno 740 offers **256**. So the program does not link,
+     * `compileProgram` throws out of this constructor, and a game that awaited `createRenderer` gets
+     * no renderer, no reason and no frame — the page's background colour for as long as the player
+     * is willing to look at it, with the splash covering the first second of it. Reported from
+     * outside exactly that way.
+     *
+     * The only lever a consumer had was `pointShadows: false`, and it is not enough to be a fix: it
+     * pays a whole feature on every part under 440, and the lit path *without* point shadows is
+     * still 248, so it cannot reach a conforming device at all — WebGL2 guarantees 224. Sizing the
+     * arrays reaches it with everything compiled in: 8 lights and 2 rectangles is 252 rows **with**
+     * point shadows, and 4 and 1 is 158.
+     *
+     * **Counted first, then linked, and both are load-bearing.** The count is an upper bound over
+     * the source (see `countUniformVectors`), which is what lets the first attempt be the right one
+     * on a part that is short; the link is the driver's own answer, and a refusal steps down a rung
+     * rather than propagating. Only a shader that will not link at *any* budget throws, and it
+     * throws a sentence with the device's numbers in it rather than a bare driver string.
+     */
+    private fitFlatProgram;
+    /**
+     * How many point lights this renderer's shader shades at once.
+     *
+     * **Read it when sizing a `PointLightBuffer`.** `selectPointLights` fills a buffer to the
+     * buffer's own capacity and evicts the weakest when it is full, so the winners are the nearest
+     * ones but they are not in any order — which means a buffer wider than this leaves the shader
+     * shading an arbitrary subset rather than the nearest N. Sizing the buffer from this number is
+     * what makes a clamped budget a smaller scene instead of a flickering one. A wider upload is
+     * otherwise harmless: GL ignores array elements past the end of a uniform, measured on ANGLE.
+     */
+    get shadedLights(): number;
+    /** How many rectangular emitters this renderer's shader shades at once. */
+    get shadedAreaLights(): number;
+    /** How many point-light shadows the shader samples at once. */
+    get sampledShadowLights(): number;
+    /**
+     * Size the point-shadow pool for a world's lights. Call at load.
+     *
+     * It used to bake a map for every light here and keep them all forever, which is
+     * why it was called `bakeStaticPointShadows`. That allocated one cubemap per
+     * lamp — about 327 MB for 50 of them — so that the eight the shader can bind
+     * could be read. See `POINT_SHADOW_POOL`.
+     *
+     * Nothing is baked now. Maps are borrowed from the pool and baked by
+     * `updatePointShadows` the first time a light is actually sampled, which is the
+     * only moment the result can be seen. Load is correspondingly faster: it no
+     * longer renders six passes over the static world for every lamp in the day,
+     * most of which were never looked at.
+     */
+    prepareStaticPointShadows(lights: readonly ShadowLight[], 
+    /**
+     * The rectangles this world will shade, so the ones that cast get layers of the same array.
+     *
+     * **A second parameter on this call rather than a call of its own, because there is one array
+     * and `texStorage3D` sizes it once.** A separate `prepareAreaShadows` would either rebuild the
+     * array — throwing away every baked lamp — or depend on being called first, and a consumer
+     * getting that order wrong would see the rectangles cast and the lamps stop. Optional, so
+     * every existing caller is unchanged and allocates exactly what it did before.
+     *
+     * The name says point and this takes area lights too. It stays, because what it prepares is
+     * *the* shadow array and both kinds of light are layers in it — the alternative was a second
+     * name for one thing.
+     */
+    areaLights?: readonly AreaLightSource[]): void;
+    /**
+     * Say once that a rectangle asked to cast and named no range, naming the field.
+     *
+     * **A warning rather than a throw, because this is reachable from a frame.** `AGENTS.md` says
+     * fail fast at init and never throw in the frame loop, and a consumer may re-prepare when its
+     * world changes. What it must not be is silent: the picture of a rectangle that declined to cast
+     * and one whose range was forgotten is the same picture, and the second is a typo.
+     */
+    private warnAreaShadowRange;
+    /**
+     * Say once that a rectangle wants layers the array was not sized for.
+     *
+     * **This is the area-light shape of the failure `updatePointShadows` warns about above**, and it
+     * is just as quiet: `prepareStaticPointShadows` sizes the array — `texStorage3D` and
+     * `createTexture` are both immutable — so a consumer that passes its rectangles here and not
+     * there gets an array with no room above the pool. Every declaration is then honoured except the
+     * storage, the set holds no maps, every layer publishes -1, and the frame is indistinguishable
+     * from one whose rectangles declined to cast.
+     */
+    private warnAreaShadowLayers;
+    /** Say once that a rectangle asked to cast while the array it would read is switched off. */
+    private warnAreaShadowsOff;
+    /**
+     * Per frame: bind the shading pass's exact light set, refresh any sampled map
+     * whose source moved, and rebuild the live-caster map nearest the supplied
+     * focus. A second live map exists only during its ownership crossfade.
+     * Fixed-light world maps remain untouched.
+     */
+    updatePointShadows(lights: readonly ShadowLight[], activeWorldIndices: Int32Array, activeCount: number, liveX: number, liveY: number, liveZ: number, frameDt: number, staticCasters: ShadowCasters, dynamicCasters: ShadowCasters, warmWorldIndices?: Int32Array, warmCount?: number, 
+    /**
+     * The rectangles this frame shades, in the order `selectAreaLights` was given them.
+     *
+     * **The same list and the same order, which is what makes a slot mean one thing.** The lit
+     * pass reads `uAreaShadow*[a]` at the slot it is shading, and those arrays are filled from this
+     * list's position — so handing a different order here than to `selectAreaLights` puts one
+     * fixture's shadow under another. Optional, so an existing caller is unchanged.
+     *
+     * Their bakes ride this call rather than one of their own because the budget, the casters and,
+     * on the other backend, the encoder are all already here. See `AreaShadowSet.update`.
+     */
+    areaLights?: readonly AreaLightSource[]): void;
+    /**
+     * The rectangles' own round: their static layers under the same face budget, then their movers.
+     *
+     * **A separate allocation of the same two numbers rather than what the pool left over**, and the
+     * reason is which failure each choice produces. Sharing one budget means a courtyard full of lamps
+     * can starve a rectangle indefinitely, and a shadow that never arrives is worse than a shadow
+     * that arrives late — the pool's own ordering rule says so. Allocating separately doubles the
+     * worst case, and that worst case is bounded: `MAX_AREA_LIGHTS` is four against a pool of twenty,
+     * and a fixture's static layer is baked once because a fixture does not move.
+     *
+     * Which leaves the recurring cost as the live layers alone: `liveShadowFacesPerFrame` shared
+     * round-robin across the casting rectangles, of a handful of moving meshes each.
+     */
+    private updateAreaShadows;
+    /**
+     * Every point-shadow bake, under the one set of conventions all of them need.
+     *
+     * **It exists because the bracket was written on one of the two bake paths and not the other.**
+     * A point-shadow face is rendered from a light matrix `depthConvention.ts` deliberately leaves
+     * conventional, so the pass has to compare and clear conventionally too. `bakeAreaOne` did that;
+     * `bakeOne` — the ordinary lamp, which is nearly every point shadow a scene has — ran under the
+     * frame's own `GEQUAL` against a scratch cleared to 0, so every fragment won or lost the wrong
+     * comparison. That does not look broken. It looks *shaded*, which is why it outlived nine
+     * attempts at reversed depth and was only named by neutralising the term and watching the
+     * backends agree.
+     *
+     * Both callers go through here now, and the state is set unconditionally: conventional depth is
+     * already in this configuration, so there is no branch to forget.
+     */
+    private bakePointShadow;
+    /** Spend up to `maxFaces` on one rectangle's layer, from its centre. */
+    private bakeAreaOne;
+    /** Spend up to `maxFaces` on this map, returning how many it used. */
+    private bakeOne;
+    /**
+     * Draw into a rectangle of the canvas, on its own terms.
+     *
+     * For a *portrait*: a character preview standing in a box on a menu, lit and framed by
+     * whatever the caller wants, with nothing of the world in it. The scissor is what makes
+     * that true — the clear only touches the box, so the frame already drawn survives around
+     * it, and only the meshes the caller issues appear inside.
+     *
+     * Kept as a pair of calls rather than a callback so the caller's draw sequence reads the
+     * same inside a box as outside one: `beginInset`, bind a pass, draw meshes, `endInset`.
+     * It returns the **aspect** of the rectangle it set up, for the camera that will fill it.
+     *
+     * The rectangle is in **CSS pixels with the DOM's top-left origin** — a `DOMRect`, in
+     * other words, which is what a caller actually has. The first version took GL's own
+     * convention and left the caller to scale by the device pixel ratio and flip the y axis;
+     * that is arithmetic about *this* object's canvas, so it belongs here. A caller doing it
+     * has two chances to be wrong about somebody else's state, and on a high-DPI screen the
+     * mistake is a box in the wrong place at the wrong size.
+     *
+     * **`clearColor: null` keeps the picture and clears only depth**, which is the
+     * difference between an object *in* the frame and an object in a box cut out of it.
+     * A backdrop is right for a preview inside a panel, where the box is furniture and a
+     * dark case is what makes a small object read. It is wrong the moment the same inset
+     * is used over a live frame: the caller gets a filled rectangle pasted onto the
+     * picture, whatever colour it picks, because any colour that is not the scene is a
+     * rectangle. Depth alone still puts the meshes in front of everything already drawn
+     * inside the box, which is what a caller compositing over its own frame wants.
+     */
+    beginInset(rect: InsetRect, clearColor: Vec3 | null): number;
+    /**
+     * Hand a rectangle of the frame to a 2D canvas, at its own pixel size.
+     *
+     * For content that has to appear *in front of* the page rather than behind it. The
+     * menu's panels carry `backdrop-filter: blur(6px)`, so anything drawn into the canvas
+     * underneath a panel — including an inset in a hole cut through one — is shown blurred,
+     * by design: the world behind a menu is meant to be out of focus. A character preview
+     * shown through that hole inherits the blur along with everything else.
+     *
+     * A copy is what escapes it. The pixels become an ordinary image inside a DOM element,
+     * so the blur has nothing to do with them. It is one `drawImage` of a few tens of
+     * thousands of pixels, GPU-side, which is cheaper than any of the alternatives — a second
+     * WebGL context, or a mask cut out of the blurring layer and kept in step with the
+     * element it is hiding.
+     *
+     * **Must be called in the same task as the draw.** A WebGL drawing buffer is only
+     * guaranteed readable until the page composites; afterwards this copies black. That is
+     * the same rule the still export learned the hard way.
+     */
+    copyRegionTo(rect: InsetRect, target: HTMLCanvasElement): void;
+    /**
+     * Fill a rectangle of the frame with one flat colour, blended.
+     *
+     * The plain surface an overlay is read against. Neither of the two things that
+     * could nearly do this actually can: `beginInset` *clears*, so it is opaque by
+     * definition, and `TextRenderer.setPlate` builds its rectangle from one lit cube
+     * per cell — correct for a keycap and a grid of seams at panel size.
+     *
+     * `rect` is in CSS pixels from the top-left of the **canvas** — `cssWidth` and
+     * `cssHeight`'s space, which is what an overlay laying itself out already has.
+     * Deliberately *not* `beginInset`'s viewport-relative `DOMRect`: that one takes
+     * what its callers hold, which is a measured DOM element, and this one takes what
+     * its callers hold, which is a rectangle they computed against the frame. The two
+     * spaces differ exactly when the canvas does not fill the window — a letterboxed
+     * export — so a single convention would be silently wrong on one side or the
+     * other in the case that matters most.
+     *
+     * Depth-test off and depth writes off: this is furniture drawn over a finished
+     * frame, and it must neither be occluded by the scene nor occlude what is drawn
+     * after it.
+     */
+    fillPanel(rect: InsetRect, color: Vec3, alpha: number): void;
+    /** Give the whole canvas back. Safe to call without a matching `beginInset`. */
+    endInset(): void;
+    /**
+     * How much speed blur the frame about to be drawn should resolve with, 0 to 1.
+     *
+     * Set before `beginFrame`, held until changed, and ignored entirely when screen effects
+     * are off. A *renderer* parameter rather than a scene one: it describes how the finished
+     * image is presented, not anything in the world, which is why nothing about the world has
+     * to know it exists.
+     */
+    setSpeedRush(strength: number): void;
+    /**
+     * How much of the frame's camera motion blur to apply, 0 to 1. Scales `cameraMotionBlur`.
+     *
+     * **A ceiling and a dial, rather than one number.** `cameraMotionBlur` is
+     * construction-time because it decides whether the pass exists at all; this decides how
+     * much of it a given frame wants, and a frame is exactly the granularity that matters.
+     * Blur that is always on is not a speed cue, it is a filter: a viewer stops reading it
+     * within seconds, and it costs eight taps on every moving pixel while doing so. Reported
+     * from play, twice, by two different people, one of whom turned the setting off inside a
+     * minute.
+     *
+     * So a caller ramps it with whatever "fast" means in its world. 1 keeps what a scene
+     * written before this got, so nothing changes for anyone who does not call it.
+     *
+     * Set before `beginFrame` and held until changed, like `setSpeedRush`, which it sits
+     * beside for the same reason: both describe how the finished image is presented rather
+     * than anything in the world.
+     */
+    setCameraMotionBlur(scale: number): void;
+    /**
+     * Where this frame's lens is focused, how deep the sharp zone is, and how much of the ceiling
+     * to take.
+     *
+     * **The ceiling-and-dial split `setCameraMotionBlur` argues for, with a third number that is
+     * neither.** `depthOfField` is construction-time and decides how far a defocused point may
+     * spread, which is what the effect *costs*; `scale` decides how much of that this frame wants,
+     * so 0 turns it off for a moment without paying for it. `distance` and `range` are not a
+     * fraction of anything — they are where the camera is looking, in metres, and a caller changes
+     * them when the subject moves.
+     *
+     * **Racking focus is the caller's, and that is the same boundary `setOutputExposure` draws.** A
+     * game knows what its camera is looking at; the renderer could only find out by reading a depth
+     * sample back a frame late. Easing `distance` toward a target is two lines wherever that state
+     * already lives, and the clock belongs to the caller in this engine.
+     *
+     * `range` is clamped above zero because it is the divisor of the ramp: at zero, every pixel not
+     * exactly on the plane would be at full blur, which is a different effect and not one anybody
+     * asked for.
+     *
+     * Set before `beginFrame` and held until changed, like `setSpeedRush` and
+     * `setCameraMotionBlur` beside it. Ignored entirely when `depthOfField` is 0.
+     */
+    setDepthOfField(distance: number, range: number, scale?: number): void;
+    /** Where the lens is focused and how deep the sharp zone is, in metres. See `setDepthOfField`. */
+    private focusDistance;
+    private focusRange;
+    /** How much of `depthOfField` this frame takes. See `setDepthOfField`. */
+    private dofScale;
+    /** The inverse projection, and the four elements of it a depth-to-distance needs. */
+    private readonly dofInvProjection;
+    private readonly dofDepthToView;
+    /**
+     * How much of the frame's bloom to apply, 0 to 1. **Scales** `bloom`, like
+     * `setCameraMotionBlur` scales `cameraMotionBlur`.
+     *
+     * A scale rather than a replacement, and the distinction is worth being explicit about
+     * because the setter beside this one — `setOutputExposure` — is the other kind. A grade has
+     * no natural full value to take a fraction of, so exposure replaces. A strength does: how
+     * much a world blooms is that world's look, decided once, and what a frame gets to say is
+     * how much of it this moment wants. So `bloom: 0.4` with `setBloom(0.5)` is 0.2, and a
+     * caller that never calls this keeps exactly what it asked for at construction.
+     *
+     * That is also what keeps a quality profile meaningful: a part that cannot afford the effect
+     * has it capped in one place rather than in every frame that sets a dial.
+     *
+     * Set before `beginFrame` and held until changed. Ignored entirely when `bloom` is 0, since
+     * the chain is never built.
+     */
+    setBloom(scale: number): void;
+    /**
+     * How thick the air is, this frame: a global participating medium filling the whole frustum.
+     *
+     * **The dial beside `globalMediumSteps`' ceiling**, on the split every other effect here uses.
+     * The profile says what a march may cost, and this says what the weather is doing — so a game
+     * can walk into a fog bank without the settings screen changing under it, and a device that
+     * cannot afford a medium never draws one however thick the game says the air is.
+     *
+     * `density` is extinction per metre and **0 is a real off**: no target is allocated, no march
+     * runs and no composite is drawn, so a frame at 0 is identical to a build with the feature
+     * absent rather than merely close to it. Everything else is optional and holds until changed:
+     * `albedo` is how much of what the air takes out comes back as light, `anisotropy` is the
+     * Henyey-Greenstein g that makes haze glow toward a low sun, and `maxDistance` is where the
+     * search for light to scatter stops — not where the fog stops, which is what extinction says.
+     *
+     * This is the air, not a beam. `drawLightVolume` is a shaft somebody placed inside a hull;
+     * this is everything between the camera and whatever the frame already drew, and it is the one
+     * of the two that can put the shape of a doorway on a floor.
+     */
+    setGlobalMedium(density: number, albedo?: number, anisotropy?: number, maxDistance?: number): void;
+    /** This frame's medium. Off until a caller says otherwise. See `setGlobalMedium`. */
+    private mediumOptions;
+    /** Built on the first frame that asks for a medium, and never on one that does not. */
+    private medium;
+    /**
+     * How far this frame's scene is scaled into the tone curve. Replaces `outputExposure`.
+     *
+     * **The same ceiling-and-dial split as `setCameraMotionBlur`, for the same reason.**
+     * `outputExposure` is construction-time and is a *grade*: it says how this world's light
+     * levels are meant to sit in the curve. What it cannot express is that one scene has both a
+     * lit showroom and a dark interior in it, which is where a single exposure is wrong twice —
+     * blown out in the room and unreadable inside. So a frame gets to say what it wants, and a
+     * caller that never says anything keeps the grade it asked for at construction.
+     *
+     * **Adaptation is the caller's, and that is a deliberate boundary rather than a shortcut.**
+     * A game knows it walked into a cave; the renderer can only find out by measuring pixels a
+     * frame late. Easing toward a target is two lines wherever the state already lives, and the
+     * clock belongs to the caller in this engine — see the determinism rules. What the engine
+     * *could* add on top, and has not, is the measurement half: a mip of the scene target read as
+     * an average luminance and smoothed in a 1x1 ping-pong, so a scene that cannot say what it is
+     * looking at gets a number anyway. RENDERING.md §4 has that written down as what is left.
+     *
+     * Ignored unless `outputTransform` is `aces`, because there is no curve to be exposed into
+     * otherwise. Clamped above zero: a zero exposure is a black frame, and a negative one is a
+     * black frame with a sign error in it.
+     */
+    setOutputExposure(exposure: number): void;
+    /**
+     * Composite a flat colour over the finished frame — for a cut dipping to white or to black.
+     *
+     * `alpha` 0 leaves the picture untouched and is the default; 1 replaces it outright. Nothing
+     * else on this renderer can reach either end: `setOutputExposure`'s own guard clamps above
+     * zero, so black is unreachable by design, and white is not an exposure at all under `aces`,
+     * which is built to roll off rather than clip — driving exposure up gives a bloomed, tinted,
+     * still-legible frame, which is a different effect and a nice one. A veil is the operation
+     * that gap was missing, not a knob left unturned on an existing one.
+     *
+     * **Composited after the tone map, before grain and vignette. That is a ruling, not a
+     * measurement, and it is written out here because a caller reading this is exactly who needs
+     * it.**
+     *
+     * After the tone map, because a transition has to hit exact black and exact white
+     * deterministically: `setFrameVeil(0, 0, 0, 1)` must be pure black and
+     * `setFrameVeil(1, 1, 1, 1)` pure white. Compositing before a curve built to roll off makes
+     * "full white" an asymptote no caller could solve for — the same trap `setOutputExposure` is
+     * already in, and this must not be that.
+     *
+     * Before grain and vignette, because that is the complaint this replaces: painted on top of
+     * an already-finished frame, a dip to black flattens grain and a vignette instead of taking
+     * them down with it, which reads as a sheet laid over the picture rather than the picture
+     * going dark. Composited here, ahead of anything that still runs after the grade, a dip fades
+     * the whole image together.
+     *
+     * This also answers the bloom question by construction rather than by choice: bloom is
+     * resolved upstream of this pass, from the pre-tonemap scene — see `SceneTarget.resolve` —
+     * so a veil composited here never feeds it. That is the right side of its own framing: a dip
+     * is a cut rather than a light, and a veil that bloomed would mean dipping to white lit the
+     * whole frame instead of covering it.
+     *
+     * **Cleared with the frame, unlike `setSpeedRush` and `setCameraMotionBlur` beside it: one
+     * call per frame, and a frame that does not call it draws with no veil at all**, rather than
+     * inheriting whatever the last cut left behind. A transition that forgets to turn itself off
+     * is a worse failure than one that forgets to turn on, which is why this resets in `endFrame`
+     * where those two are held until changed.
+     *
+     * Costs nothing at zero: the shader's `withVeil` is a single comparison that hands the pixel
+     * back unmixed, and nothing extra is allocated on the CPU side to reach it.
+     */
+    setFrameVeil(r: number, g: number, b: number, alpha: number): void;
+    /**
+     * The colour grade this and every later frame applies, until it is set again.
+     *
+     * A lookup table over **display** values, applied after the tone curve and before the veil —
+     * `colourGrade.ts` argues both placements and `uGradeLut`'s own comment in `rush.ts` states
+     * them. Held rather than per-frame, so a consumer sets it once; the table is uploaded only
+     * when the object it was given changes, which makes calling this from a frame loop free.
+     *
+     * **It needs `screenEffects`, and says so rather than doing nothing.** Without a composite
+     * every forward pass is the last thing to touch the frame and grades itself, so there is no
+     * single place a look could be applied — the same rule and the same words `hdrScene` already
+     * carries. A silent no-op here would be a consumer wondering why their grade does not apply,
+     * which is precisely the failure this engine's rules exist to prevent. Once per renderer,
+     * because a consumer setting a grade every frame would otherwise flood a console.
+     */
+    setColourGrade(lut: ColourGradeLut | null, strength?: number): void;
+    /**
+     * What this frame asked for. **Every ceiling here is `null`, and that is the finding.**
+     *
+     * This backend imposes no per-frame limit on anything: it sets uniforms per draw and has no
+     * ring to run out of, so it draws whatever it is handed. WebGPU holds thirteen ceilings and
+     * skips the work past any of them. The same scene therefore renders differently on the two
+     * backends with nothing failing anywhere, and a developer working here — which is where most
+     * development happens, because it is the fallback that runs everywhere — cannot see a WebGPU
+     * ceiling approaching.
+     *
+     * Reporting the count with an honest `null` is what makes that visible: a consumer reads the
+     * same line name on both, compares its own number against the ceiling the other backend
+     * publishes, and finds out before a player does rather than after.
+     */
+    private readonly budget;
+    private readonly drawBudget;
+    /**
+     * Declared here and never asked, because this backend builds none.
+     *
+     * A bind group is a WebGPU object; the equivalent here is loose uniform and sampler calls, which
+     * are not a thing that is created and cached and so not a thing that can leak. Reporting a
+     * standing zero rather than omitting the line is the same argument the `draws` line above makes
+     * in the other direction: a consumer comparing the two backends reads one name on both, and a
+     * line that is absent on one is a line no cross-backend check can compare. The number it is
+     * being compared against should also be zero once the other backend's cache is warm.
+     */
+    private readonly bindGroupBudget;
+    /** What the frame just drawn asked for. See `budget.ts`, and the note on `budget` above. */
+    get frameBudget(): FrameBudget;
+    /**
+     * Mark whatever the depth buffer holds inside a projector's box.
+     *
+     * **The drawn half of decals, and `projectDecal` is the other.** That one clips the receiving
+     * surface's triangles once and hands back a mesh, which is cheaper every frame and exact — and
+     * which cannot follow a surface that deforms or streams in afterwards. This decides the mark
+     * from the frame's own depth instead, so the receiver may be a skinned mesh, a heightfield being
+     * rewritten, an instanced crowd, or geometry that arrived after the mark was placed.
+     *
+     * **The mark multiplies.** A forward renderer has no G-buffer, so the pixel is already lit by
+     * the time this runs: multiplying takes the receiver's lighting exactly, at the cost that a mark
+     * can darken and tint and never brighten. `decalProjector.ts` argues that at length.
+     *
+     * Recorded here and drawn in `endFrame`, before the frame is composited, so the post chain sees
+     * the mark. Silently nothing where the profile has no screen effects, since there is then no
+     * depth to read: the same rule `hdrScene` and `orderIndependent` carry.
+     */
+    drawDecal(projector: DecalProjector): void;
+    /**
+     * Reflect what the frame drew, in the surfaces inside a box.
+     *
+     * **What a planar reflection cannot reach.** `beginPlanarReflection` re-renders the world from a
+     * mirrored camera for one horizontal plane at one height, which is exactly right for a lake and
+     * gives nothing for a floor that undulates, a bonnet or a tilted pane — and it costs a second
+     * pass over the scene. This costs one scissored fullscreen pass per surface, follows the surface
+     * per pixel whatever shape it is, and is exact where an object meets the floor.
+     *
+     * **It can only reflect what is on screen.** Anything behind the camera or hidden behind the
+     * reflecting surface is not in the colour buffer and cannot be recovered from it; the fades in
+     * `screenSpaceReflection.ts` are what keep that from being an obvious limit rather than a
+     * pretence that it is not one.
+     *
+     * Recorded here and traced in `endFrame`, after the decals so a mark appears in the reflection
+     * and before the translucent resolve so a pane of glass is drawn over it. Needs `screenEffects`,
+     * and says so once where there is none.
+     */
+    drawReflection(surface: ReflectiveSurface): void;
+    /** Said once, not per frame, where this renderer cannot read the picture a march samples. */
+    private refuseReflections;
+    /** Said once, not per frame, where a medium was asked for and there is no depth to march against. */
+    private refuseMedium;
+    private mediumRefused;
+    /** Said once, not per frame, where this renderer cannot read the depth a mark is decided from. */
+    private refuseDecals;
+    /**
+     * Said once, not per frame, where multisampling excludes the effect a profile asked for.
+     *
+     * **A refusal rather than a silent sort, and the reason is who is on the other side of it.** The
+     * two are both switches on a graphics screen, so a player turning antialiasing on turns this off
+     * — and a quality setting that is enabled and does nothing is the fault `capabilityClamp` and
+     * the bloom warning in the constructor exist to prevent. The other backend refuses the same
+     * profile from the same constant, which is what stops the two compositing different pictures
+     * from one `RenderQuality` — see `OIT_MULTISAMPLE_REFUSAL` for why it is a constant and not two
+     * literals kept in step by hand.
+     */
+    private refuseOitMultisampled;
+    beginFrame(clearColor: Vec3): void;
+    /**
+     * Present the frame.
+     *
+     * Called at the very end of a render pass, and **always resolves to the canvas** — a
+     * frame recorder reads the canvas to build a clip and a still is a canvas copy, so a
+     * scene left in a framebuffer would export black while the screen looked right. A no-op
+     * when screen effects are off, so a caller may call it unconditionally.
+     */
+    endFrame(): void;
+    /**
+     * Whether the driver has finished the first frame, not merely been asked for it.
+     *
+     * For whatever is covering the load: a plate lifted on the frame being submitted
+     * uncovers the screen while the GPU process is still paying that frame's
+     * first-use bill, and the player watches the last of the load rather than being
+     * spared it. Poll it once a frame; it never goes back to false.
+     *
+     * Non-blocking by construction — a zero timeout asks the driver what it has
+     * finished and takes the answer, rather than waiting for the one it wants.
+     */
+    get firstFrameSettled(): boolean;
+    /**
+     * Make the flat program current, before anything writes one of its uniforms.
+     *
+     * **A uniform location belongs to a program, and writing it while a different program
+     * is bound is an `INVALID_OPERATION` that uploads nothing.** Every method here that
+     * writes `flatUniforms` calls this first, and that is a rule about this class rather
+     * than a suggestion: the flat pass is bound once by `bindMeshPass` and then *interrupted*
+     * by every other pass there is — water, particles, plumes, flock, bolts, streaks, film,
+     * sky — each of which binds a program of its own. Any flat-pass call made after one of
+     * those was writing to a program that had not been current since.
+     *
+     * Measured, on the demos, before this existed: `drawTranslucentMesh` in the chamber
+     * scene wrote `uModel` and `uOpacity` to the flat program while the particle program was
+     * bound, and `drawMesh` in the sea scene wrote `uModel` while the flock program was. Both
+     * raised `INVALID_OPERATION` every frame, and both then drew the mesh through whichever
+     * shader *was* bound, since a draw call takes the program it finds.
+     *
+     * That error mattered beyond the geometry it spoiled. A pending GL error is not attached
+     * to the call that raised it — the next `getError` anywhere reads it and concludes
+     * whatever it was checking has failed. The depth-blit guard in `sceneTarget.ts` did
+     * exactly that: it read this error as a driver refusing a depth resolve and switched
+     * camera motion blur off for the session.
+     *
+     * The other repair — having each interrupting pass hand the flat program back — was
+     * rejected. It puts the obligation on every pass that will ever be added rather than on
+     * the six places that write these uniforms, and a pass that forgets reintroduces exactly
+     * this, silently.
+     *
+     * Not filtered for redundancy. A cache of "what is bound" would have to be invalidated
+     * by every call that delegates to a pass module, which is the same forgettable
+     * obligation in a new shape, and the wrong answer is a silent no-op rather than a
+     * redundant bind. The engine's draw budget is under 100 calls a frame; measured on the
+     * chamber and sea scenes, GPU time did not move.
+     */
+    private useFlatProgram;
+    /** Bind the flat pass once per frame; then issue any number of drawMesh calls. */
+    bindMeshPass(camera: Camera, env: Environment): void;
+    /**
+     * Everything one flat program needs to know about this frame.
+     *
+     * Split out of `bindMeshPass` so it can be run against each program rather than only the one
+     * that happened to be bound. Takes its uniform table as a parameter for exactly that reason: a
+     * method reaching for `this.flatUniforms` would silently write the plain program's locations
+     * whichever program is current, which is an `INVALID_OPERATION` that uploads nothing.
+     */
+    private writeMeshPassState;
+    /**
+     * Draw world geometry.
+     *
+     * `depthLayer` orders geometry that **occupies the same surface** as other geometry
+     * — a deck crossing another deck, a kerb fused into the slab it trims, a marking
+     * inlaid in a floor. A higher layer wins the depth test wherever two surfaces
+     * coincide. 0, the default, is the base world and takes no offset at all.
+     *
+     * The engine cannot guess which of two fused surfaces should win, so it does not
+     * try: the consumer declares the order once, and the engine's promise is that the
+     * answer is then the *same from every angle*. That is the whole defect — not that
+     * the wrong surface wins, but that which one wins is not decided anywhere.
+     *
+     * Without it, two coplanar surfaces are a coin toss taken per pixel. Their
+     * interpolated depths are equal in exact arithmetic, so the comparison is decided
+     * by which way the rounding fell in each triangle's interpolators, and that
+     * pattern changes with the view: a kerb reads as a full band from one angle and a
+     * hairline from another, and the seam between two fused slabs crawls with a hatch.
+     *
+     * It turned up in six places in a single session, and the right call was to refuse
+     * the workaround: this belongs at engine level, and level design should not be bent
+     * around an engine bug. The workaround is real — consumers had been lifting markings
+     * a centimetre or two off the surfaces they belong to, one hand-tuned constant at a
+     * time, to dodge this.
+     *
+     * Two measurements narrowed it to exactly this and are worth keeping, because both
+     * eliminate a plausible cure:
+     *
+     * - **Not depth precision.** With the near plane at 2.0 the buffer resolves seven
+     *   microns at the distances involved and the artefact was unchanged. So the
+     *   surfaces are not nearly-coincident, they are *coincident* — and no depth
+     *   format separates equal depths. That is what took a reversed-Z conversion off
+     *   the table.
+     * - **Not the shadow pass.** With `?shadows=0`, unchanged.
+     *
+     * `POLYGON_OFFSET_FILL` is the feature built for this. The slope term matters as
+     * much as the constant one: a band seen at a grazing angle covers many depth units
+     * across one pixel, and a fixed nudge that suffices head-on vanishes there.
+     */
+    drawMesh(mesh: Mesh, model: ReadonlyMat4, depthLayer?: number, 
+    /**
+     * Optional per-draw colour multiplier, or null for the mesh's own colours.
+     *
+     * For anything that has to take on a colour decided at runtime — a part matching the
+     * surface underneath it, a highlight, a team tint — where the alternative is
+     * rebuilding vertex data every frame. Reset to white after the call, so a caller that
+     * passes one cannot leak it into the next draw.
+     */
+    tint?: Vec3 | null): void;
+    /**
+     * Draw a mesh you can see through, in the same material as everything else by default.
+     *
+     * For geometry that is *present* without being solid — a sign hung in the air, a
+     * hologram, a marker over a course. Lit, fogged and shaded exactly as the world
+     * is, because it belongs to the world; the only difference is that the world
+     * carries on behind it.
+     *
+     * **`options` turns either of those off, and it is the same draw doing it rather than a
+     * second one.** Geometry, blend state and depth behaviour are unchanged either way; only
+     * whether the fragment stage runs lighting and fog differs. See `TranslucentMeshOptions`
+     * for what each half means and why they are independent. A glow shell or a flat backdrop
+     * plate that needs to read exactly its own colour — three.js's `meshBasicMaterial` — is
+     * `{ lit: false, fog: false }`; everything that called this before keeps drawing lit and
+     * fogged, since both default to `true`.
+     *
+     * **It writes depth**, unlike every other blended pass here, and that is not an
+     * oversight. The sky is drawn last, as a full-screen triangle that fills every
+     * pixel the world left untouched — so anything translucent that declined to
+     * write depth is simply painted over wherever it stood against open air.
+     * The first version showed it plainly: a gate came out half visible, clipped away
+     * except for the part that overlapped the deck behind it. A sign hung in the
+     * air is exactly the case that stands against the sky.
+     *
+     * The cost is the usual one: two translucent surfaces in this pass sort by depth instead of
+     * blending through each other, and which of an overlapping pair survives is the order they
+     * were submitted in. **`{ depthWrite: false }` is the tool for a caller with overlapping
+     * glass**, and it was missing for as long as this paragraph named it without providing it —
+     * a consumer importing vehicles found it on a model whose interior is 96 blended surfaces
+     * inside a shell. `{ depthLayer }` is the other half, for a blended surface *coplanar* with
+     * what it decorates, which no ordering can separate. What it buys is that the piece
+     * exists in the depth buffer like everything else in the world.
+     *
+     * Back faces stay culled, so a closed shape blends once rather than twice, and
+     * a marker seen from below reads the same weight as one seen from above.
+     *
+     * Call inside the flat pass, after the opaque draws. Everything it changes is
+     * handed straight back.
+     */
+    drawTranslucentMesh(mesh: Mesh, model: ReadonlyMat4, opacity: number, options?: TranslucentMeshOptions): void;
+    /**
+     * Capture the room into a cubemap, once, so reflective surfaces can mirror it.
+     *
+     * `drawFace` is handed a camera already aimed and submits the scene exactly as it would to
+     * the screen: a `bindMeshPass`, the world's draws, the sky. It is called six times, and the
+     * whole thing is one bake rather than anything per frame — six submissions at the moment a
+     * caller says the room is finished, then a cubemap fetch per reflective pixel for ever after.
+     *
+     * **Called once the world exists and not before.** A probe baked in a constructor captures a
+     * room that has not been built yet, which is a reflection of nothing that looks exactly like
+     * a reflection of something.
+     *
+     * A no-op without `reflectionProbeSize`, and a no-op on a device with no spare texture unit,
+     * so a caller may issue it unconditionally. Returns whether the room was captured, for a
+     * caller that wants to say so.
+     *
+     * What it must not contain: the passes that bind framebuffers of their own. A shadow bake or
+     * a planar reflection inside `drawFace` would unbind the probe's target halfway through a
+     * face. Shadow maps baked *before* the probe are fine and are the normal arrangement, since
+     * what the probe wants is the lit room.
+     */
+    bakeReflectionProbe(origin: Vec3, clearColor: Vec3, drawFace: (camera: Camera) => void, options?: ProbeBakeOptions): boolean;
+    /**
+     * Declare where a grid's probes stand, and allocate the layers for them.
+     *
+     * **`texStorage3D` is immutable, so the layer count is fixed here and not grown later.** A grid
+     * that already matches is left alone, which is what makes `bakeReflectionProbe` cheap to call
+     * every time a scene rebakes its one probe.
+     *
+     * Answers false when no probe was allowed at all — no `reflectionProbeSize`, or a device with no
+     * spare texture unit — so a caller may issue it unconditionally.
+     */
+    setProbeGrid(options: ProbeGridOptions): boolean;
+    /**
+     * Bake one probe of the declared grid: six faces into the scratch cube, then one convolution.
+     *
+     * **One probe per call, and that is the budget question a grid actually raises.** A bake is six
+     * passes plus a convolution per level, which `prefilterEnvMap.ts` says is affordable only because
+     * it happens once per scene; a grid multiplies it by the probe count. A consumer spreading
+     * thirty-two probes over thirty-two frames is doing what the point-shadow pool already does.
+     *
+     * The grid is not sampled until every layer has been filled, so a scene paced this way keeps the
+     * gradient it had until the last probe lands rather than showing half a grid.
+     */
+    bakeProbe(layer: number, clearColor: Vec3, drawFace: (camera: Camera) => void, options?: ProbeBakeOptions): boolean;
+    /**
+     * Bake every probe of the declared grid, in one call.
+     *
+     * The whole grid at once, for a scene that can afford a stall at load. `bakeProbe` is the same
+     * work paced by the caller, and a grid of any size is worth pacing.
+     */
+    bakeProbeGrid(clearColor: Vec3, drawFace: (camera: Camera) => void, options?: ProbeBakeOptions): boolean;
+    /**
+     * Light the scene from an environment it did not photograph.
+     *
+     * **Downstream of the capture this is exactly a bake**, which is the whole design: the faces are
+     * uploaded into the same cube a bake fills and the same convolution runs over them. A loaded sky
+     * is therefore not a second lighting path that can be wrong on its own.
+     *
+     * A loaded environment is a grid of one, at the origin, because it is the same everywhere.
+     */
+    setEnvironmentImage(image: {
+        readonly width: number;
+        readonly height: number;
+        readonly data: Float32Array;
+    }, options?: ProbeBakeOptions): boolean;
+    /**
+     * Draw a volume of light: a beam from a lamp, a shaft through a window, the cone under a
+     * street light.
+     *
+     * **Not a material, and that is the whole point of it being a separate call.** Everything
+     * `drawMesh` does to a surface is wrong for light: it lights it, fogs it toward the medium's
+     * colour, and scales its emissive by how dark the world is. Light is what the fog is *made
+     * of*; a beam is more visible in mist, not less. This pass adds, and does nothing else.
+     *
+     * Two attempts to express a beam as geometry in the flat pass failed, in opposite
+     * directions, and both are worth knowing before reaching for a material again. Alpha blended
+     * it *subtracted*: blending moves the background toward the surface's own colour, so an unlit
+     * wedge darker than the dusk behind it swept a solid dark shape across the frame, which was
+     * reported five times as a bird. Made additive but still fogged, ninety metres of it
+     * multiplied down to nothing at twenty times the emissive.
+     *
+     * **What the caller supplies is a closed hull, and the pass walks the view ray inside it.**
+     * The geometry decides which pixels run and nothing else: every one of them integrates the
+     * air along its own line of sight, so the path length that makes a volume read as a volume
+     * comes out of the walk rather than being modelled.
+     *
+     * It used to rasterise a few flat panes through the axis and weight each fragment by how far
+     * from face-on its pane was turned, which stands in for that path length and works from the
+     * side. It cannot work down the barrel: every pane contains the axis, so a view lying near
+     * that axis lies nearly within all of them at once, each collapses to a narrow bright wedge,
+     * and their union reads as a six-armed asterisk instead of a disc. Reported twice from
+     * outside — as a beam whose shape never changed however it was tuned, and as raw lines in the
+     * opening of a room — and no correction to the weight could have fixed either, because the
+     * fault was that a handful of flat sheets is not a volume.
+     *
+     * Culling is off, because a volume seen from inside is still lit. Depth *testing* stays on,
+     * so a beam passes behind whatever stands in front of it; depth *writing* is off, because a
+     * volume of light occludes nothing.
+     *
+     * **The volume opens from its own origin along its local +Z**, and `length` and `spread` say
+     * how far and how wide: `spread` is half-width over distance, so the tangent of the
+     * half-angle. The shader fades the light to nothing at that length and at that aperture,
+     * which is what lets a beam dissolve into the air rather than stop at a bright square, and
+     * it is why the hull can be a coarse frustum rather than anything shaped like light.
+     * Building the gradient into the geometry instead is a staircase, because `MeshBuilder`
+     * states one emissive per quad.
+     *
+     * **All three numbers describe geometry this call cannot see, and each one fails silently
+     * when it disagrees with the mesh.** `buildLightVolume` in `src/geometry/` builds the hull
+     * from the same `length` and `spread` passed here, which is the way to have none of this
+     * apply; the following is what a caller building its own has to get right, and every one of
+     * them has been paid for from outside this repository.
+     *
+     * - **`length` is measured in the geometry's own units, not in world metres**, because the
+     *   shader compares it against the untransformed vertex position. A beam authored as a unit
+     *   wedge and placed with an orthonormal basis is *one unit long* whatever `length` says, so
+     *   a length of 7.4 puts the whole mesh inside the first 13% of its own falloff and the beam
+     *   is invisible. Either the model matrix carries the scale, or the hull is built at world
+     *   size. There is no error and no warning: the draw succeeds and nothing appears.
+     * - **`spread` has to be at or under the geometry's own flare**, since the across-axis fade
+     *   reaches zero at this aperture and clamps there. Wider than the hull and the fade is still
+     *   climbing where the hull ends, which cuts the volume instead of dissolving it. Narrower is
+     *   safe and merely reads as a beam thinner than its own silhouette.
+     * - **`strength` is clamped to 1.** Raising it is the natural response to a beam that looks
+     *   faint, and above 1 it does nothing at all — so a faint beam is one of the two faults
+     *   above, or a colour and emissive that are too low in the mesh itself.
+     *
+     * `strength` fades the whole thing, for a lamp coming up at dusk or dimming at dawn. At 0 it
+     * draws nothing at all rather than adding black, so a caller may keep the call in the frame.
+     */
+    drawLightVolume(mesh: Mesh, model: ReadonlyMat4, camera: Camera, strength: number, length: number, spread: number, options?: LightVolumeDrawOptions): void;
+    /**
+     * Draw a thin wet film — an oil slick, a puddle, a wet patch — over the world.
+     *
+     * Its own pass because it is its own material: view-dependent iridescence and a
+     * dissolving edge, neither of which the flat shader can express. It runs *after*
+     * the world with depth writes off and blending on, so a slick lies on the
+     * surface it was built against instead of fighting it for the depth buffer.
+     *
+     * The caller never sees a GL call: it hands over a mesh, the camera, the clock
+     * and how strong the sheen should be.
+     *
+     * **`sheen` is iridescence, not wetness, and the two are not the same dial.** Raising it to
+     * make a road look wetter makes it look oilier: the surface bands green to magenta like fuel
+     * on water, because that is what the term models. A consumer found the usable range for wet
+     * tarmac at night by bisection twice, at 0.7 and again at 0.24, and landed on **0.15 to
+     * 0.18**. Start there rather than repeating the search.
+     *
+     * There is no mirror term here to raise instead. A surface that should reflect the scene
+     * rather than shimmer needs a planar pass, and `beginPlanarReflection` is water-only; see the
+     * comment on it. Splitting the two is an open request from outside and is not built.
+     */
+    drawFilm(mesh: Mesh, camera: Camera, timeSeconds: number, env: Environment, sheen: number, options?: FilmOptions): void;
+    /**
+     * Scale one plume in a batch, 0 to hide it.
+     *
+     * For a fire that is not always burning — an oil slick on its ignition cycle. The caller owns
+     * *when*; nothing here knows what a slick is.
+     */
+    setPlumeScale(plumes: PlumeRenderer, index: number, scale: number): void;
+    /** Draw last: the sky only fills pixels the world left untouched. */
+    drawSky(camera: Camera, sky: SkyColors, env: Environment): void;
+    /**
+     * What is under a pixel, for a consumer that has to answer a click.
+     *
+     * The engine says *what*, and nothing else: enter, leave, capture, bubbling and the
+     * difference between a click and a drag are the consumer's, which already has that
+     * logic for anything with a drag in it. An event system here would be a second one,
+     * disagreeing with the first.
+     */
+    registerPickable(source: PickableSource, model: Float32Array): number;
+    updatePickable(handle: number, model: Float32Array): void;
+    unregisterPickable(handle: number): void;
+    pickAt(camera: Camera, cssX: number, cssY: number): PickHit | null;
+}
+/**
+ * The name this class had until 2026-08-24, kept because it is on the public barrel.
+ *
+ * **An alias rather than a rename with a migration**, because nothing measured needs one: no
+ * consumer in this repository binds either renderer class. Every one of them reaches the engine
+ * through `createRenderer` and holds the result as `RendererApi`, which is the surface both
+ * backends implement — so the concrete class is an implementation detail everywhere but here.
+ *
+ * **What it costs**: two names for one class, and a reader who meets `Renderer` has to learn it
+ * means the WebGL2 one. **What would make it wrong**: a consumer starting to bind it, which would
+ * turn a free alias into a migration owed. Nothing does today, and `docs/PORTING.md` says which
+ * name to prefer. It goes when something else forces a major, and not before.
+ */
+export { WebGL2Renderer as Renderer };