@driftengine/core 3.61.0

package/src/render/surfaceTexture.ts

@@ -0,0 +1,310 @@
+/** A GPU image the caller supplies, sampled by the flat shader as surface colour. */
+
+/**
+ * How a texture behaves past its edges and between its texels.
+ *
+ * Deliberately small. Every knob here is one a tiling world actually needs; anything
+ * beyond it — swizzles, borders, compressed formats — is a format decision that
+ * belongs to whoever is generating the pixels, not to the surface that shows them.
+ */
+/**
+ * Everything the flat pass needs to know about a surface, in one call.
+ *
+ * **Shaped for what comes after it.** ORM is the next map and emissive the one after; both are a
+ * field here rather than a fourth and fifth setter, which is the whole reason this replaced
+ * `setSurfaceTexture` rather than sitting beside it. A consumer setting four maps in four calls is
+ * four chances to forget one, and four resets `bindMeshPass` has to reason about.
+ *
+ * **Every field is independent.** A material with a `normal` and no `albedo` is a legitimate one —
+ * vertex colour with authored normals — and shades as such rather than as no material at all.
+ *
+ * **Generic over the texture, for the reason `SurfaceTextureHandle` exists.** The two backends have
+ * different texture classes and the public API speaks in an opaque handle; parameterising here lets
+ * each renderer take its own concrete type while a consumer sees one shape. Defaulted to the
+ * WebGL2 class so the common spelling stays `SurfaceMaterial`.
+ */
+export interface SurfaceMaterial<Texture = SurfaceTexture> {
+  albedo?: Texture | null;
+  /**
+   * Surface-space directions, turned into world space through the mesh's tangent frame.
+   *
+   * Read by the flat pass since 2026-08-22, from the attribute at location 10 where the mesh has
+   * one and from a per-fragment cotangent frame where it does not. `normalStrength` gates it.
+   * See `docs/RENDERING.md` for the normal-map path.
+   */
+  normal?: Texture | null;
+  /**
+   * Occlusion in R, roughness in G, metallic in B, in one image.
+   *
+   * glTF's packing, because that is what an import carries, and one unit for three channels rather
+   * than three units for three maps. Sampled linear and never sRGB: these numbers *are* the data.
+   */
+  orm?: Texture | null;
+  /**
+   * Where a surface glows, and in what colour.
+   *
+   * **It modulates the surface's own emission rather than creating it**, which is glTF's rule
+   * — emitted colour is `emissiveFactor * emissiveTexture` — and is the one thing about this map
+   * that surprises people. A mesh whose `emissive` attribute is 0 emits nothing however bright
+   * the image it binds, because there is nothing for the image to scale. An import carries the
+   * factor for you: `gltf.ts` puts `max(emissiveFactor)` in the attribute and the factor itself
+   * in `emissiveColor`. A procedurally built mesh has to say so the same way it says its colour,
+   * which is in vertex data, because that is what makes a whole world one draw call here.
+   *
+   * Sampled **sRGB**, unlike `normal` and `orm`: this one is a colour a person picked, where
+   * those two are numbers. glTF says the same.
+   */
+  emissive?: Texture | null;
+  /** Repeats across the mesh's own UV range, per axis. Applies to every map the material holds. */
+  uScale?: number;
+  vScale?: number;
+  /** Alpha below which a fragment is discarded. See `uAlbedoCutout`. */
+  cutout?: number;
+  /**
+   * How hard the normal map turns the shading normal.
+   *
+   * **Defaults to 1 when a `normal` is supplied and 0 when it is not**, because binding a map and
+   * saying nothing about strength means "use it" rather than "use it at nothing".
+   */
+  normalStrength?: number;
+  /**
+   * Scales the ORM map's G channel. glTF's `roughnessFactor`. Default 1.
+   *
+   * The map *replaces* the mesh's own roughness attribute rather than scaling it, and this is what
+   * gives back the scaling. Scaling the attribute was the alternative and it is wrong outside an
+   * import: `vertexDefaults.ts` hands an absent roughness **0.4277**, not 1, so every procedurally
+   * built mesh would read far glossier than the image it was handed, with nothing in the API to
+   * say it would.
+   */
+  roughnessScale?: number;
+  /** Scales the ORM map's B channel. glTF's `metallicFactor`. Default 1. */
+  metallicScale?: number;
+  /**
+   * How much of the ORM map's R channel to apply. glTF's `occlusionTexture.strength`. Default 1.
+   *
+   * **0 is no occlusion, not full occlusion.** glTF defines it as `1 + strength * (texel - 1)`, so
+   * the shader mixes from 1 rather than multiplying — a multiply at 0 would black the surface out,
+   * which is the opposite of what the caller asked for.
+   */
+  occlusionStrength?: number;
+  /**
+   * Scales the emissive map, per channel. Default 1.
+   *
+   * The counterpart of `roughnessScale` and `metallicScale`: a factor that multiplies a texture is
+   * not a value, and this is where the multiplier lives once an image supplies the shape. A
+   * consumer who wants a bound map twice as bright asks here rather than rebuilding the mesh.
+   */
+  emissiveScale?: readonly [number, number, number];
+}
+
+export interface SurfaceTextureOptions {
+  /**
+   * `repeat` tiles the image, `clamp` stretches its edge texels.
+   *
+   * Repeat is the default because the case this exists for is a wall: one small image
+   * covering a large surface, with `uvScale` deciding how often it lands. Clamp is for
+   * an image that is a *picture* — a portrait, a sign — where a second copy of it
+   * appearing past the edge is a bug rather than a pattern.
+   */
+  wrap?: 'repeat' | 'clamp';
+  /**
+   * How the image's values are encoded, so the shader can sample light rather than pixels.
+   *
+   * `linear` is the default and the old behaviour: the bytes are handed to the shader as
+   * they are. That is right for a mask, a height field, anything whose numbers *are* the
+   * data.
+   *
+   * `srgb` is right for anything that was authored to be looked at — a photo, a painted
+   * canvas, a biome tile. Those bytes are display values, and shading maths is linear, so
+   * multiplying a light into them without decoding first is a category error: mid-greys
+   * come out roughly twice as bright as they should, and the mistake is invisible until an
+   * output transform is applied and everything blows out at once. The GPU decodes
+   * `SRGB8_ALPHA8` in the sampler, so this costs nothing per fetch and, unlike decoding in
+   * the shader, it happens *before* filtering — which is the only place it is correct.
+   */
+  colorSpace?: 'linear' | 'srgb';
+  /**
+   * How a texel is chosen when the image is magnified: smoothed between texels, or taken whole.
+   *
+   * **`linear` is the default and is every surface that shipped before this**, which is right for
+   * anything photographic: a wall, a painted canvas, a biome tile, where the texel grid is an
+   * artefact of resolution rather than the subject.
+   *
+   * `nearest` is for an image whose *pixels are the subject* — pixel art, an icon atlas, a
+   * hand-authored tile. **Reported by a consumer whose block atlas is exactly that**: linear
+   * magnification turns an authored tile into a smear as the camera approaches, and there was no
+   * way to ask for anything else. They composed their atlas with `imageSmoothingEnabled = false`
+   * and kept tiles at twice the resolution they wanted, and neither touches magnification — the
+   * smoothing happens in the sampler, after everything a caller controls.
+   *
+   * **Minification still blends between mip levels**, and that is not the option being ignored. A
+   * tiled floor at a grazing angle minifies far past one texel per pixel, which is what mips exist
+   * for; taking the nearest *level* as well would trade a smear for a visible pop as the camera
+   * pulls back. So the choice applies where it was asked about, and within a level either way.
+   *
+   * `@driftengine/ui2d` takes the same option and defaults it the other way, because a sprite sheet
+   * is usually pixel art and a world surface usually is not.
+   */
+  filter?: 'linear' | 'nearest';
+  /**
+   * Build a mip chain. On by default, and it is not a quality preference.
+   *
+   * A tiled surface seen at a grazing angle — which is every floor and every corridor
+   * wall — minifies far past one texel per pixel, and without mips that undersampling
+   * is aliasing that *crawls* as the camera moves. It is the single most visible
+   * artefact a textured world can have. Off is for a texture drawn at roughly its own
+   * size, where the chain is memory spent on levels nothing will sample.
+   */
+  mipmap?: boolean;
+  /**
+   * Anisotropic samples, when the extension is present. 1 disables it.
+   *
+   * Mips fix the crawling and cost sharpness: a floor stretching to the horizon picks
+   * its mip from the *worse* of the two axes, so it blurs along the one that was still
+   * well sampled. Anisotropy is the standard repair, it is cheap at these sizes, and
+   * on a machine without the extension the clamp below silently leaves it at 1.
+   */
+  anisotropy?: number;
+}
+
+const DEFAULT_ANISOTROPY = 4;
+
+/**
+ * An image uploaded once and bound per draw.
+ *
+ * The engine ships no image assets and fetches nothing — that payload rule is intact
+ * and this does not weaken it. What it takes is a `TexImageSource` the *consumer*
+ * already has: a canvas it generated procedurally at runtime, an `ImageBitmap` it
+ * decoded, a video frame. The engine owns the GPU object and the sampler state; where
+ * the pixels came from is the caller's business and stays that way.
+ */
+export class SurfaceTexture {
+  private texture: WebGLTexture | null;
+  private readonly mipmapped: boolean;
+  /** Whether the sampler decodes sRGB on fetch. See `colorSpace`. */
+  private readonly srgb: boolean;
+
+  constructor(
+    gl: WebGL2RenderingContext,
+    source: TexImageSource,
+    options: SurfaceTextureOptions = {},
+  ) {
+    const texture = gl.createTexture();
+    if (texture === null) throw new Error('SurfaceTexture: createTexture failed');
+    this.texture = texture;
+    this.mipmapped = options.mipmap ?? true;
+    this.srgb = (options.colorSpace ?? 'linear') === 'srgb';
+
+    const wrap = (options.wrap ?? 'repeat') === 'repeat' ? gl.REPEAT : gl.CLAMP_TO_EDGE;
+
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    /*
+     * **Not flipped, and this used to be, which is the bug it is written down for.**
+     *
+     * The flip was here with a comment saying every source is a 2D drawing surface whose Y
+     * runs down from the top-left, so without it "every texture arrives mirrored". That is
+     * true of a canvas and **WebGL ignores `UNPACK_FLIP_Y_WEBGL` entirely for an
+     * `ImageBitmap`**, which carries its own orientation. So the two source types the same
+     * method accepts arrived the opposite way up from each other, and nothing caught it
+     * because every canvas-sourced texture in this repository was symmetric under a vertical
+     * flip: eroded noise, a radial halo, a sleeve blurred to 24 pixels and back. One consumer
+     * painted lettering to a canvas beside a sleeve decoded as a bitmap and the text was
+     * upside down.
+     *
+     * **Made to agree by dropping the flip rather than by extending it**, and the direction
+     * is a deliberate choice about blast radius rather than a coin toss: `drftLoader` builds
+     * every model texture from an `ImageBitmap`, so flipping bitmaps to match canvases would
+     * turn over every painted surface on every loaded model. Dropping it changes only
+     * canvas-sourced textures, and every one of those that exists today is symmetric.
+     *
+     * A caller that was mirroring its own canvas to cancel this must stop.
+     */
+    gl.texImage2D(
+      gl.TEXTURE_2D,
+      0,
+      this.srgb ? gl.SRGB8_ALPHA8 : gl.RGBA,
+      gl.RGBA,
+      gl.UNSIGNED_BYTE,
+      source,
+    );
+
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, wrap);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, wrap);
+    /* Nearest where the caller said their pixels are the subject; see `filter`. The mip chain is
+       still blended between levels, because that is minification and this option is about
+       magnification. */
+    const nearest = options.filter === 'nearest';
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, nearest ? gl.NEAREST : gl.LINEAR);
+    gl.texParameteri(
+      gl.TEXTURE_2D,
+      gl.TEXTURE_MIN_FILTER,
+      this.mipmapped
+        ? nearest
+          ? gl.NEAREST_MIPMAP_LINEAR
+          : gl.LINEAR_MIPMAP_LINEAR
+        : nearest
+          ? gl.NEAREST
+          : gl.LINEAR,
+    );
+
+    if (this.mipmapped) gl.generateMipmap(gl.TEXTURE_2D);
+    applyAnisotropy(gl, options.anisotropy ?? DEFAULT_ANISOTROPY);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+  }
+
+  /**
+   * Replace the pixels, keeping the GPU object and its sampler state.
+   *
+   * For a source that changes — a canvas being redrawn, a decoded frame. Re-uploading
+   * beats constructing a second texture because the binding the caller already handed
+   * to a draw stays valid, and because a texture created per frame is a leak in every
+   * case where the caller forgets the matching dispose.
+   *
+   * Not a hot path: it re-uploads the whole image and regenerates the chain. A caller
+   * doing this every frame at any size wants to know that it costs what it costs.
+   */
+  update(gl: WebGL2RenderingContext, source: TexImageSource): void {
+    if (this.texture === null) return;
+    gl.bindTexture(gl.TEXTURE_2D, this.texture);
+    /* Unflipped, matching the constructor. See it for why, and for what it cost. */
+    gl.texImage2D(
+      gl.TEXTURE_2D,
+      0,
+      this.srgb ? gl.SRGB8_ALPHA8 : gl.RGBA,
+      gl.RGBA,
+      gl.UNSIGNED_BYTE,
+      source,
+    );
+    if (this.mipmapped) gl.generateMipmap(gl.TEXTURE_2D);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+  }
+
+  /** Bind to a unit for sampling. Engine-internal: the renderer owns unit assignment. */
+  bind(gl: WebGL2RenderingContext, unit: number): void {
+    gl.activeTexture(gl.TEXTURE0 + unit);
+    gl.bindTexture(gl.TEXTURE_2D, this.texture);
+  }
+
+  dispose(gl: WebGL2RenderingContext): void {
+    if (this.texture === null) return;
+    gl.deleteTexture(this.texture);
+    this.texture = null;
+  }
+}
+
+/**
+ * Set anisotropic filtering when the driver offers it, and stay silent when it does not.
+ *
+ * Silent because the extension is an enhancement with an exact fallback — the same
+ * texture, filtered isotropically — so a machine without it renders a slightly softer
+ * floor rather than a broken one. Nothing here should fail init over that.
+ */
+function applyAnisotropy(gl: WebGL2RenderingContext, requested: number): void {
+  if (requested <= 1) return;
+  const ext =
+    gl.getExtension('EXT_texture_filter_anisotropic') ??
+    gl.getExtension('WEBKIT_EXT_texture_filter_anisotropic');
+  if (ext === null) return;
+  const max = gl.getParameter(ext.MAX_TEXTURE_MAX_ANISOTROPY_EXT) as number;
+  gl.texParameterf(gl.TEXTURE_2D, ext.TEXTURE_MAX_ANISOTROPY_EXT, Math.min(requested, max));
+}

package/src/render/temporalAa.ts

@@ -0,0 +1,221 @@
+import { mat4 } from 'gl-matrix';
+import type { ReadonlyMat4 } from 'gl-matrix';
+
+/**
+ * The sub-pixel sequence a temporal resolve samples along, and the state that says whether there
+ * is anything to resolve *against* yet.
+ *
+ * **Antialiasing by moving the camera rather than by taking more samples.** A frame is rasterised
+ * with the projection shifted a fraction of a pixel, so an edge that fell one side of a pixel
+ * centre falls the other side next frame, and blending the two puts the edge where it actually
+ * is. What MSAA buys per frame this buys across frames, at one extra texture and one extra pass
+ * instead of a multiplied fill rate — which is the trade a browser target wants.
+ *
+ * **This file holds only the parts that are arithmetic**, so they can be asserted without a
+ * device: where the next sample sits, what that does to a projection matrix, and whether the
+ * history is usable this frame. The resolve itself is a shader and belongs to each backend.
+ */
+
+/**
+ * How many frames the sequence takes to come back round.
+ *
+ * Eight rather than sixteen: the accumulation converges in eight frames instead of sixteen, and
+ * every frame of history is a frame of ghosting a moving object has to be clipped out of. The
+ * sequence is the deciding factor rather than the count — eight *distinct* low-discrepancy
+ * positions beat sixteen that clump.
+ */
+export const JITTER_PERIOD = 8;
+
+/**
+ * How much of the clipped history each resolved frame keeps.
+ *
+ * Nine parts history to one part this frame, which gives the accumulation an effective window of
+ * about ten frames — a little longer than the eight-frame period, so every offset in the sequence
+ * still contributes to what is on screen. Higher holds a ghost for longer wherever the
+ * neighbourhood clip does not catch it; lower stops converging before the period is out and leaves
+ * the crawl this exists to remove.
+ */
+export const TEMPORAL_HISTORY_BLEND = 0.9;
+
+/**
+ * The radical inverse of `index` in `base`, which is what makes a Halton sequence fill a gap
+ * before it fills a corner.
+ *
+ * Consecutive samples land as far from each other as the base allows, so eight of them cover the
+ * pixel evenly where eight random ones would leave holes and pairs.
+ */
+function halton(index: number, base: number): number {
+  let result = 0;
+  let fraction = 1;
+  let i = index;
+  while (i > 0) {
+    fraction /= base;
+    result += fraction * (i % base);
+    i = Math.floor(i / base);
+  }
+  return result;
+}
+
+/**
+ * The period's offsets, centred so they sum to zero.
+ *
+ * **Halton's own mean is not the middle of the pixel** — over eight samples base two averages
+ * 0.445 rather than 0.5 — and accumulating towards a mean that is off centre resolves to a picture
+ * displaced from the depth buffer it was tested against and from every pass that did not jitter.
+ * Subtracting the period's own mean costs nothing and makes the property exact rather than
+ * approximate, which is what lets the test assert it.
+ */
+const OFFSETS: readonly (readonly [number, number])[] = (() => {
+  const raw: [number, number][] = [];
+  for (let i = 1; i <= JITTER_PERIOD; i++) raw.push([halton(i, 2), halton(i, 3)]);
+  const meanX = raw.reduce((sum, o) => sum + o[0], 0) / JITTER_PERIOD;
+  const meanY = raw.reduce((sum, o) => sum + o[1], 0) / JITTER_PERIOD;
+  return raw.map(([x, y]) => [x - meanX, y - meanY] as const);
+})();
+
+/** Where in its pixel frame `frameIndex` samples, in pixels, centred on zero. */
+export function jitterOffset(frameIndex: number): readonly [number, number] {
+  const at = ((frameIndex % JITTER_PERIOD) + JITTER_PERIOD) % JITTER_PERIOD;
+  return OFFSETS[at] as readonly [number, number];
+}
+
+/**
+ * `source` shifted by `offsetX`, `offsetY` pixels on a `width` by `height` target.
+ *
+ * **A clip-space translation scaled by w, and not an edit to the projection's third column.** The
+ * usual trick adds the offset to the third column, where it is multiplied by view z and the
+ * perspective divide then cancels it — which is exact, and only for a bare perspective projection.
+ * This engine's single funnel for geometry is `viewProjFor`, which carries a *combined*
+ * view-projection: there the third column multiplies world z instead of view z, and the jitter
+ * would swim with the scene's own depth. An orthographic matrix breaks it too, its w being 1.
+ *
+ * Adding `offset * w` to clip x and y is what those two cases have in common. It survives the
+ * divide as a constant screen offset at every distance, whatever produced the clip position, so
+ * this may be handed a projection or a view-projection and is correct for both — which is the
+ * property the near-and-far test beside this pins.
+ *
+ * **A zero offset returns the matrix unchanged, bit for bit.** Every published capture is taken
+ * with this off, and a jitter of zero that still ran the arithmetic would move pixels by whatever
+ * it rounded to.
+ */
+export function jitterProjection(
+  out: mat4,
+  source: ReadonlyMat4,
+  offsetX: number,
+  offsetY: number,
+  width: number,
+  height: number,
+): mat4 {
+  mat4.copy(out, source);
+  if (offsetX === 0 && offsetY === 0) return out;
+  const ndcX = (2 * offsetX) / width;
+  const ndcY = (2 * offsetY) / height;
+  /* Row 0 gains `ndcX` times row 3, and row 1 `ndcY` times it, which is `T * source` for a T
+     translating in clip space — done in place because that product touches nothing else. */
+  for (let column = 0; column < 4; column++) {
+    const w = source[column * 4 + 3];
+    out[column * 4 + 0] += ndcX * w;
+    out[column * 4 + 1] += ndcY * w;
+  }
+  return out;
+}
+
+/** A colour the resolve is working on, as three numbers rather than a texture fetch. */
+export type Rgb = [number, number, number];
+
+/**
+ * `history` pulled into the box `min`..`max`, along the line towards the box's centre.
+ *
+ * **This is what separates a temporal resolve from a long exposure.** Reprojection finds where a
+ * pixel *was*; nothing in it knows whether what was there is what is there now. A character
+ * walking in front of a wall reprojects onto wall, and blending nine parts of that history is a
+ * smear that follows them about. The colours actually present around the pixel this frame bound
+ * what the history is allowed to be, and anything outside those bounds is a sample of something
+ * that has gone.
+ *
+ * **Clipped towards the centre rather than clamped per channel.** A clamp moves each channel
+ * independently, so a history that is merely brighter than its surroundings lands on a corner of
+ * the box and comes back a different hue, which reads as coloured fringing along every moving
+ * edge. Shortening the whole offset by one ratio keeps the direction and changes only the length.
+ *
+ * The same arithmetic is in `TEMPORAL_RESOLVE_FRAG`, and the shader test asserts the shader still
+ * spells it this way.
+ */
+export function clipToNeighbourhood(
+  out: Rgb,
+  history: readonly [number, number, number],
+  min: readonly [number, number, number],
+  max: readonly [number, number, number],
+): Rgb {
+  const centre: Rgb = [0, 0, 0];
+  const offset: Rgb = [0, 0, 0];
+  let ratio = 0;
+
+  for (let c = 0; c < 3; c++) {
+    centre[c] = (min[c] + max[c]) * 0.5;
+    offset[c] = history[c] - centre[c];
+    const extent = (max[c] - min[c]) * 0.5;
+    /*
+     * A channel with no extent cannot bound anything, so a history that differs from it at all is
+     * infinitely outside and collapses to the neighbourhood — which is the honest answer for a
+     * flat region, and the alternative is a division by zero.
+     */
+    if (extent > 1e-7) ratio = Math.max(ratio, Math.abs(offset[c]) / extent);
+    else if (Math.abs(offset[c]) > 1e-7) ratio = Number.POSITIVE_INFINITY;
+  }
+
+  if (!(ratio > 1)) {
+    out[0] = history[0];
+    out[1] = history[1];
+    out[2] = history[2];
+    return out;
+  }
+
+  const scale = Number.isFinite(ratio) ? 1 / ratio : 0;
+  out[0] = centre[0] + offset[0] * scale;
+  out[1] = centre[1] + offset[1] * scale;
+  out[2] = centre[2] + offset[2] * scale;
+  return out;
+}
+
+/**
+ * Whether the last frame left a picture this one may sample, and where the jitter has got to.
+ *
+ * **Two calls a frame, and the split is the point.** `openFrame` answers a question about the
+ * state *before* this frame writes anything, and the resolve needs that answer before it writes;
+ * `accumulated` reports that a picture now exists. One call cannot do both.
+ */
+export class TemporalHistory {
+  /** How many frames have been opened, which is what indexes the jitter. */
+  frameIndex = 0;
+
+  private picture = false;
+  private width = 0;
+  private height = 0;
+
+  /**
+   * Open a frame at this target size, and answer whether the history may be sampled.
+   *
+   * **The jitter advances whether or not it may be.** Holding the sequence still on the frames a
+   * resize or a cut discarded would sample the same position twice running, which is one sample
+   * and not two.
+   */
+  openFrame(width: number, height: number): boolean {
+    this.frameIndex++;
+    const usable = this.picture && width === this.width && height === this.height;
+    if (!usable) this.picture = false;
+    this.width = width;
+    this.height = height;
+    return usable;
+  }
+
+  /** A resolved picture is now in the history, at the size the frame was opened with. */
+  accumulated(): void {
+    this.picture = true;
+  }
+
+  /** Forget it — a cut, a teleport, or anything else that makes the last frame a different scene. */
+  invalidate(): void {
+    this.picture = false;
+  }
+}

package/src/render/temporalPass.ts

@@ -0,0 +1,153 @@
+import { compileProgram, uniformLocations } from './shader.ts';
+import { FULLSCREEN_VERT } from './shaders/fullscreen.ts';
+import { TEMPORAL_RESOLVE_FRAG } from './shaders/temporalResolve.ts';
+
+/**
+ * The temporal resolve on WebGL2: this frame blended into where the last one was.
+ *
+ * **Two targets and a swap, because a pass cannot read the texture it is writing.** The history is
+ * sampled at a reprojected coordinate, which is somewhere else in the same image, so reading and
+ * writing one texture is a feedback loop — undefined in WebGL2 and in practice whatever the driver
+ * left in the cache. So the resolve writes into the one it did not read and the pair swaps, which
+ * costs one more full-size texture and nothing per pixel.
+ *
+ * **What it returns is what the composite must then treat as the scene.** Bloom, occlusion and the
+ * grade all read the scene texture, and reading the unresolved one would grade a stable picture
+ * from an unstable source and put the crawl back on screen through the bloom.
+ */
+export class TemporalPass {
+  private readonly program: WebGLProgram;
+  private readonly uniforms: Record<string, WebGLUniformLocation | null>;
+  private readonly vao: WebGLVertexArrayObject;
+
+  /** The pair, and which of them the next resolve writes into. */
+  private textures: (WebGLTexture | null)[] = [null, null];
+  private framebuffers: (WebGLFramebuffer | null)[] = [null, null];
+  private write = 0;
+
+  private width = 0;
+  private height = 0;
+
+  constructor(
+    private readonly gl: WebGL2RenderingContext,
+    /**
+     * Matched to the scene target's own format, and it has to be.
+     *
+     * A half-float scene resolved into an eight-bit history is squashed into 0 to 1 on its way in
+     * and read back squashed, so the accumulation would pull every value above white *down* over
+     * eight frames — a bloom threshold that stopped meaning brightness, and a sunset that faded
+     * while the camera held still.
+     */
+    private readonly floatColor: boolean,
+  ) {
+    this.program = compileProgram(gl, FULLSCREEN_VERT, TEMPORAL_RESOLVE_FRAG, 'temporalResolve');
+    this.uniforms = uniformLocations(gl, this.program, 'temporalPass');
+    const vao = gl.createVertexArray();
+    if (vao === null) throw new Error('TemporalPass: createVertexArray failed');
+    this.vao = vao;
+  }
+
+  private ensureSize(width: number, height: number): void {
+    if (this.width === width && this.height === height && this.textures[0] !== null) return;
+    const { gl } = this;
+    this.width = width;
+    this.height = height;
+
+    for (let i = 0; i < 2; i++) {
+      if (this.textures[i] === null) this.textures[i] = gl.createTexture();
+      gl.bindTexture(gl.TEXTURE_2D, this.textures[i]);
+      if (this.floatColor) {
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA16F, width, height, 0, gl.RGBA, gl.HALF_FLOAT, null);
+      } else {
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, width, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+      }
+      /* Linear, because the history is sampled between texels wherever the reprojection lands;
+         clamped, because a sample that wrapped would pull the far edge of the screen into the
+         corner — and the shader rejects an off-screen reprojection before it can anyway. */
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+
+      if (this.framebuffers[i] === null) this.framebuffers[i] = gl.createFramebuffer();
+      gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffers[i]);
+      gl.framebufferTexture2D(
+        gl.FRAMEBUFFER,
+        gl.COLOR_ATTACHMENT0,
+        gl.TEXTURE_2D,
+        this.textures[i],
+        0,
+      );
+    }
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+  }
+
+  /**
+   * Resolve `scene` against the history and return the texture now holding the resolved frame.
+   *
+   * `blend` is how much of the clipped history to keep, and **zero is the whole switch**: the
+   * first frame, the frame after a resize and the frame after a cut pass zero, and the shader
+   * then returns this frame before it touches depth or history at all.
+   */
+  temporalResolve(
+    scene: WebGLTexture,
+    depth: WebGLTexture,
+    reprojection: Float32Array,
+    width: number,
+    height: number,
+    blend: number,
+  ): WebGLTexture {
+    const { gl } = this;
+    this.ensureSize(width, height);
+
+    const target = this.write;
+    const history = 1 - this.write;
+
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffers[target]);
+    gl.viewport(0, 0, width, height);
+    gl.disable(gl.DEPTH_TEST);
+    gl.disable(gl.BLEND);
+    gl.disable(gl.CULL_FACE);
+    gl.depthMask(false);
+
+    gl.useProgram(this.program);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, scene);
+    gl.uniform1i(this.uniforms['uScene'] ?? null, 0);
+    gl.activeTexture(gl.TEXTURE1);
+    gl.bindTexture(gl.TEXTURE_2D, this.textures[history]);
+    gl.uniform1i(this.uniforms['uHistory'] ?? null, 1);
+    gl.activeTexture(gl.TEXTURE2);
+    gl.bindTexture(gl.TEXTURE_2D, depth);
+    gl.uniform1i(this.uniforms['uDepth'] ?? null, 2);
+
+    gl.uniformMatrix4fv(this.uniforms['uReprojection'] ?? null, false, reprojection);
+    gl.uniform2f(this.uniforms['uTexel'] ?? null, 1 / width, 1 / height);
+    gl.uniform1f(this.uniforms['uHistoryBlend'] ?? null, blend);
+
+    gl.bindVertexArray(this.vao);
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+    gl.bindVertexArray(null);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+
+    this.write = history;
+    const resolved = this.textures[target];
+    if (resolved === null) throw new Error('TemporalPass: resolve target missing');
+    return resolved;
+  }
+
+  dispose(): void {
+    const { gl } = this;
+    for (let i = 0; i < 2; i++) {
+      if (this.textures[i] !== null) gl.deleteTexture(this.textures[i]);
+      if (this.framebuffers[i] !== null) gl.deleteFramebuffer(this.framebuffers[i]);
+      this.textures[i] = null;
+      this.framebuffers[i] = null;
+    }
+    gl.deleteProgram(this.program);
+    gl.deleteVertexArray(this.vao);
+    this.width = 0;
+    this.height = 0;
+  }
+}