@driftengine/core 4.8.7 → 4.9.0

package/CHANGELOG.json

@@ -1,4 +1,65 @@
 [
+  {
+    "version": "4.9.0",
+    "date": "2026-10-07",
+    "entries": [
+      {
+        "kind": "added",
+        "short": "`screenSpaceReflections`: every opaque lit surface reflects the frame by its own material, the probe's share swapped for what a ray finds, softened by roughness and left to the probes past a ceiling.",
+        "text": "A renderer built with `screenSpaceReflections` reflects the frame in every opaque lit surface by that surface's own material, where `ReflectiveSurface` reflects it by a box's. The lit stage leaves, per pixel, how much of the environment it showed and the tint a reflection lands with; the screen-space trace gains a material mode that marches every such pixel against the frame's depth and swaps the probe's share for what it finds. The swap is exact because the lit stage's blend is a mix: the frame holds the environment times the tint times the weight, and a found reflection belongs there with the same tint and weight, so nothing else in the pixel moves. A rougher surface shows a softer reflection, blurred by its roughness, and past `maxRoughness` it keeps the probes' reflection alone. One floor mesh with one ORM map therefore mirrors the figures standing on its glossy panels and barely shows them on its matte ones. What a surface reflects is what the lit stage already reflected: a metal by its metalness, a dielectric where `setSurfaceReflectivity` or its material asks. `true` takes `DEFAULT_FRAME_REFLECTIONS`; a `FrameReflections` sets the ceiling, the march and the blur. WebGPU writes the two maps by replaying the opaque lit draws without their lamps, since a second attachment on the frame's pass would bind every pipeline in it; WebGL2 writes them beside the colour, enabled around the opaque lit draws alone and behind a lit switch, so a renderer without the option carries nothing for it. It needs `screenEffects`, `hdrScene` and one sample, and says so once where it has none. On `demo/dev/frameReflections.html` the trace moves 30,138 floor pixels and none above them, a ceiling below every stripe matches the frame without the trace to the pixel, and the two backends differ by 41 pixels."
+      },
+      {
+        "kind": "added",
+        "short": "`setSurfaceOverlay` lays a rim of light, a dissolve with a glowing edge and wrinkle normals by six region weights over a draw's materials, its images regions of one atlas.",
+        "text": "`renderer.setSurfaceOverlay(overlay)` lays something over the surfaces of the draws that follow, beyond their materials, so one character's whole set of materials changes together while another's does not; per draw, reset by `bindMeshPass`. A `rim` glows along the silhouette: an edge `(1 - N·V)^falloff` leaning toward normals that face up, raised to a contrast, times a noise laid in screen space and scrolled on the environment's `surfaceTime`, a slow pulse and a mask in the mesh's uv, added to emission and not gated on the night. A `dissolve` cuts the surface away where a noise in its uv falls under a threshold, with a glowing band at the edge and a colour laid through the same noise. A `wrinkle` blends a second normal map into the surface's by six region weights read through two masks. Every image is a region of one atlas (`OverlayRegion`), read in the slot the frame's refraction copy takes, which an opaque surface never reads; a draw that refracts keeps its refraction and reads none of the overlay's images, and says so once. A lit switch, off until an overlay is set. WebGL2 carries the overlay's fifteen uniform vectors where its device has room and refuses it in words where it does not, as on a 256-vector part at the eight-light budget, and reads a compressed atlas as none. On `demo/dev/surfaceOverlay.html` every control moves only the object it names, and the two backends agree to the pixel."
+      },
+      {
+        "kind": "added",
+        "short": "`outputTransform: 'filmic'` and `setFilmicCurve`: a film curve shaped by five numbers that holds mid grey at mid grey, applied by the composite.",
+        "text": "`outputTransform: 'filmic'` is a film curve in the ACEScg working space: a straight segment through mid grey meeting a soft toe below and a shoulder above, shaped by a slope, a toe, a shoulder and two clips, with the ACES reference's glow and red modifier around it. `setFilmicCurve` sets the numbers and a renderer starts with `DEFAULT_FILMIC_CURVE`; a curve that runs backwards or divides by zero is clamped and said once rather than refused. 0.18 of scene light comes out at 0.18, where `'aces'` gives about 0.11: 118 of 255 on both backends, and every one of sixteen grey and colour patches agrees with a consumer's own transcription of the reference. It is the composite's, so it needs `screenEffects` and `hdrScene`; without them every pass grades with `'aces'` and the renderer says so once. Bound to DriftScript as `drift/render.filmic`."
+      },
+      {
+        "kind": "added",
+        "short": "`highDynamicRange` draws to a display's own range on WebGPU, `displayRange` says which range the frame went out in, and `setDisplayLuminance` lets highlights reach the display's peak.",
+        "text": "`highDynamicRange: true` asks for a canvas whose highlights run past paper white as far as the display can show. It is had where the renderer is on WebGPU, the frame keeps its light past white (`screenEffects` and `hdrScene`) and the display reports a high range: the canvas is configured `rgba16float` with extended tone mapping and read back to confirm it. `renderer.displayRange` says which range the frame goes out in, `'high'` or `'standard'`, and `displayRangeReason` says why; WebGL2 draws into an eight-bit canvas and always answers `'standard'`. `setDisplayLuminance(paperWhite, peak)` gives the ratio highlights may reach: paper white stays where it was and so does everything below it, the filmic shoulder rolls off toward the peak, and a colour grade colours a highlight without clipping it back to white. On a standard display it changes nothing. A host without a browser display query answers it with `createRenderer`'s `highDynamicRangeDisplay`."
+      },
+      {
+        "kind": "added",
+        "short": "`setCameraMotionBlur(scale, maxShare)` blurs each drawn object by its own motion under DriftTR on WebGPU: a mover smears while the still stage behind it stays sharp.",
+        "text": "Camera motion blur now reads each pixel's motion from the reconstruction's motion target, so a mover with a previous placement or pose smears along its own path while the stage standing still behind it does not, and `setCameraMotionBlur` takes a maximum as a share of the frame. On `demo/dev/objectBlur.html` a box crossing a still camera's view smears 8 pixels, 1 with the blur off, 5 capped. It is WebGPU's under DriftTR alone, since that is where per-object motion is kept; WebGL2, and WebGPU without reconstruction, blur by the camera's motion alone and say so once when given a mover."
+      },
+      {
+        "kind": "added",
+        "short": "`setChromaticAberration(intensity, start)` pulls the colour channels apart toward the frame's edges past a start radius, at three wavelengths, on both backends.",
+        "text": "`setChromaticAberration(intensity, start)` is a lens fringe in the composite: the three channels sampled apart toward the frame's edges, scaled by their wavelengths, from a start radius outward, so the middle of the frame is untouched. Held until changed; 0 is none. On `demo/dev/toneCurve.html?fringe=` it moves 13,480 pixels, none inside the start, and the two backends agree. It needs `screenEffects`, and says so once."
+      },
+      {
+        "kind": "added",
+        "short": "`Atmosphere.fogStart` keeps the exponential fog's first metres clear, integrated along each ray's own path in the lit stage and the GPU-driven pipeline alike.",
+        "text": "`Atmosphere.fogStart` holds the exponential height fog off for its first metres: the medium begins where the ray has travelled that far, integrated along the ray's own path, so a stage reads clear up close and hazes with distance as a fog start does in a scene authored elsewhere. 0, or absent, is the fog as before. On `demo/dev/fogStart.html` the measured columns match values worked by hand on both backends, and the GPU-driven pipeline's fog takes it too."
+      },
+      {
+        "kind": "added",
+        "short": "A registered pass reads the frame: `reads: ['colorSnapshot']` hands it the colour drawn so far as `sceneColor`, beside the depth's `sceneDepth`, on both backends.",
+        "text": "A pass that declares `reads: ['depthSnapshot']` is handed the frame's depth as `sceneDepth` — in the `PrepareContext` on WebGPU, an `r32float` texture, and in the `PassContext` on WebGL2 — and one that declares `reads: ['colorSnapshot']` the colour with everything drawn before it as `sceneColor`, copied afresh at each such pass's draw. A distortion samples the scene behind it with it; a full-screen pass drawn last reads the whole frame and writes over it in scene light, before the tone curve. Under DriftTR the pass runs after the upscale over a copy of the reconstructed frame. On `demo/dev/framePass.html` a pass inverting the frame reads the same values on both backends, with multisampling too."
+      },
+      {
+        "kind": "changed",
+        "short": "The worker factories are at declared subpaths, `@driftengine/assets/bcWorkers` and `@driftengine/physics/workers`, where a bundler and Node can both find them.",
+        "text": "`spawnBcWorker` and the physics island pool's `createIslandPool` were reached by a path into a package's `src`, which a published package's `exports` does not have to allow and a strict resolver refuses. Each now has a subpath of its own in its package's `exports`, `@driftengine/assets/bcWorkers` and `@driftengine/physics/workers`, built to `dist` like the barrels, and the messages that name them say so. The barrels still do not reach them, which is what keeps a worker out of a game that never names one."
+      },
+      {
+        "kind": "fixed",
+        "short": "A scene capture or a probe bake inside a frame no longer turns that frame black on WebGPU, nor switches off its skin spread, nor steps the temporal jitter twice.",
+        "text": "Three defects at the boundary a capture or a probe bake opens in the middle of a frame. On WebGPU, `captureScene` and `bakeProbe` saved the open pass before flushing the frame graph, which opens the frame's pass, so a capture after any draw restored the wrong pass and the frame came out black. On both backends, the latch that spreads skin once a frame was set before the check that refuses a mirror, a probe or a capture, so a blended draw inside a capture switched the frame's skin spread off. And the temporal history stepped its jitter each time the camera was bound rather than once a frame, so a frame that bound it twice drew two frames' jitter. Each has a test, and `scripts/capture-check.mjs` captures at the start of a frame, among its draws and at its end, against controls taken the same way."
+      },
+      {
+        "kind": "fixed",
+        "short": "WebGPU asks a device for the textures and samplers the environment probe's widest lit variant really binds, sixteen and twelve, counted from the generated bindings.",
+        "text": "The check that decides whether a device can build the environment probe's permutation compared its limits against seven sampled textures and four samplers, typed when the probe was added. The widest lit variant had since grown to sixteen and twelve with the material maps, glass, the fixture atlas and DriftLight, so a device under those would have been admitted to a permutation it cannot bind. The counts now come from the generated bindings, a shared sampler counted once."
+      }
+    ]
+  },
   {
     "version": "4.8.7",
     "date": "2026-10-06",

package/README.md

@@ -6,7 +6,7 @@ carries the loop, the renderer, cameras, input, the scene graph, geometry, text
 and the whole of [`@driftengine/physics`](https://driftengine.dev/docs/simulation/rigid-bodies),
 which it re-exports. The rest of the engine is separate packages you add when you need them.
 
-**Cost: 828.1 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`,
+**Cost: 858.8 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`,
 which fails the build if the figure drifts by more than 3%.
 
 The manual is at **[driftengine.dev/docs](https://driftengine.dev/docs)**, with an example running

package/dist/index.d.ts

@@ -145,6 +145,8 @@ export { placeCascade } from './render/gi/globalField.ts';
 export type { ReflectionOptions, ReflectiveSample } from './render/gi/reflection.ts';
 export { GRADE_PLACEHOLDER_SIZE, MAX_GRADE_SIZE, identityGradeLut } from './render/colourGrade.ts';
 export type { ColourGradeLut } from './render/colourGrade.ts';
+export { DEFAULT_FILMIC_CURVE } from './render/filmicCurve.ts';
+export type { FilmicCurve } from './render/filmicCurve.ts';
 /**
  * How bloom answers past its threshold — a ramp in place of the subtraction, and a tint for each
  * of the pyramid's `BLOOM_LEVELS` octaves — the third argument of `setBloom`.
@@ -157,6 +159,9 @@ export type { BoltHandle, CausticsHandle, ClothBindingHandle, ClothParticlesHand
 export type { ClothBindingData } from './render/clothBindingData.ts';
 export { anisotropicModel, eyeModel, hairModel, lightmapModel, skinModel, } from './render/surfaceModel.ts';
 export type { AnisotropicModel, EyeModel, HairModel, LightmapModel, SkinModel, SurfaceModel, SurfaceModelKind, } from './render/surfaceModel.ts';
+export { DEFAULT_FRAME_REFLECTIONS } from './render/frameReflections.ts';
+export type { FrameReflections } from './render/frameReflections.ts';
+export type { OverlayRegion, SurfaceDissolve, SurfaceOverlay, SurfaceRim, SurfaceWrinkle, } from './render/surfaceOverlay.ts';
 export { WHOLE_PAGE } from './render/lightmap.ts';
 export type { LightmapPage, LightmapRegion } from './render/lightmap.ts';
 export { createSkinnedCloth } from './render/skinnedClothRun.ts';

package/dist/index.js

@@ -209,6 +209,7 @@ export { placeCascade } from './render/gi/globalField.js';
  * take the identity, bend it, hand it back — and because it is what the placeholder is.
  */
 export { GRADE_PLACEHOLDER_SIZE, MAX_GRADE_SIZE, identityGradeLut } from './render/colourGrade.js';
+export { DEFAULT_FILMIC_CURVE } from './render/filmicCurve.js';
 /**
  * How bloom answers past its threshold — a ramp in place of the subtraction, and a tint for each
  * of the pyramid's `BLOOM_LEVELS` octaves — the third argument of `setBloom`.
@@ -221,6 +222,12 @@ export { probeDevice } from './render/backend/probe.js';
  * its own, compiled the first time a draw asks.
  */
 export { anisotropicModel, eyeModel, hairModel, lightmapModel, skinModel, } from './render/surfaceModel.js';
+/*
+ * What a draw lays over its surface beyond its material — a rim of light, a dissolve, wrinkle
+ * normals by region — set per draw with `setSurfaceOverlay`, its images regions of one atlas.
+ */
+/* Every opaque lit surface reflecting the frame by its own material: `screenSpaceReflections`. */
+export { DEFAULT_FRAME_REFLECTIONS } from './render/frameReflections.js';
 /*
  * A baked lightmap: the page a consumer decoded, which `createLightmap` uploads as a lightmapped
  * material's `modelMap`, and the region of it a material or an instance reads.

package/dist/render/atmosphere.d.ts

@@ -45,6 +45,19 @@ export interface Atmosphere {
     /** Linear mode only: where haze begins, and where it is total. */
     fogNear?: number;
     fogFar?: number;
+    /**
+     * The medium only: how far along the view ray it begins, in metres. Absent or 0 is at the
+     * camera, as every world before it was drawn.
+     *
+     * The air nearer than this is perfectly clear, and what lies beyond is fogged by the air past
+     * this point alone — so a faint, bright haze can lie over a distant crowd while the figures a
+     * few metres from the camera stay sharp, which no density can do when the medium starts at the
+     * eye: there it veils the whole frame, lifting the shadows and draining the colour before it
+     * reaches anything far enough to want it. Unlike `linear`'s `fogNear`, nothing past it is a
+     * ramp: it is the same extinction, integrated from further out. **What it gives up** is the air
+     * between the camera and the start, which a real medium has; that is the point of it.
+     */
+    fogStart?: number;
     underwater: UnderwaterAtmosphere | null;
 }
 /**

package/dist/render/atmosphere.js

@@ -46,7 +46,15 @@ export function resolveAtmosphere(atmosphere, cameraY, underwaterEnabled, out) {
     out.fogHeightFalloff = atmosphere.fogHeightFalloff;
     out.fogEyeY = cameraY;
     out.fogMode = atmosphere.fogMode === 'linear' ? 1 : 0;
-    out.fogNear = atmosphere.fogNear ?? 0;
+    /*
+     * **One slot, two meanings, and never both**: the ramp's near distance in linear mode, and in
+     * the medium where it begins (`fogStart`), which the medium never read before — so a world that
+     * left a `fogNear` on an exponential fog starts nothing, and draws exactly as it did.
+     */
+    out.fogNear =
+        atmosphere.fogMode === 'linear'
+            ? (atmosphere.fogNear ?? 0)
+            : Math.max(0, Number.isFinite(atmosphere.fogStart) ? (atmosphere.fogStart ?? 0) : 0);
     out.fogFar = atmosphere.fogFar ?? 1;
     /*
      * The air medium stands in when nothing is submerged. The shaders multiply by the factor

package/dist/render/backend/api.d.ts

@@ -7,6 +7,7 @@ import type { ProbeBakeOptions } from '../reflectionProbe.ts';
 import type { Renderer, TranslucentMeshOptions } from './webgl2/renderer.ts';
 import type { InstancedOptions, MeshInstances } from '../instances.ts';
 import type { SurfaceMaterial } from '../surfaceTexture.ts';
+import type { SurfaceOverlay } from '../surfaceOverlay.ts';
 import type { SurfaceSource } from '../compressedSource.ts';
 import type { LightmapPage } from '../lightmap.ts';
 import type { DeviceParticles } from '../particlePool.ts';
@@ -189,7 +190,7 @@ export interface MeshOptions {
 }
 export type RendererApi = Omit<{
     [K in keyof Renderer]: Renderer[K];
-}, 'gpuTimer' | 'createMesh' | 'createMeshIncremental' | 'updateMesh' | 'drawMesh' | 'disposeMesh' | 'drawTranslucentMesh' | 'drawLightVolume' | 'drawFilm' | 'createScatter' | 'drawScatter' | 'uploadScatter' | 'disposeScatter' | 'createInstanced' | 'uploadInstanced' | 'drawInstanced' | 'drawTranslucentInstanced' | 'disposeInstanced' | 'createWater' | 'drawWater' | 'disposeWater' | 'createPlumes' | 'drawPlumes' | 'disposePlumes' | 'setPlumeScale' | 'createCaustics' | 'drawCaustics' | 'disposeCaustics' | 'createParticles' | 'drawParticles' | 'drawDeviceParticles' | 'disposeParticles' | 'createWindStreaks' | 'drawWindStreaks' | 'disposeWindStreaks' | 'createFlock' | 'drawFlock' | 'disposeFlock' | 'createBolts' | 'drawBolts' | 'disposeBolts' | 'createLines' | 'drawLines' | 'disposeLines' | 'createText' | 'setText' | 'setPlate' | 'drawText' | 'textWidth' | 'disposeText' | 'createSdfText' | 'setSdfText' | 'drawSdfText' | 'disposeSdfText' | 'createSurfaceTexture' | 'createSurfaceTextureArray' | 'createLightmap' | 'createSceneCapture' | 'captureScene' | 'updateSurfaceTexture' | 'disposeSurfaceTexture' | 'setSurfaceTexture' | 'setMaterial' | 'createClothBinding' | 'createClothParticles' | 'updateClothParticles' | 'setCloth' | 'disposeClothBinding' | 'disposeClothParticles'> & {
+}, 'gpuTimer' | 'createMesh' | 'createMeshIncremental' | 'updateMesh' | 'drawMesh' | 'disposeMesh' | 'drawTranslucentMesh' | 'drawLightVolume' | 'drawFilm' | 'createScatter' | 'drawScatter' | 'uploadScatter' | 'disposeScatter' | 'createInstanced' | 'uploadInstanced' | 'drawInstanced' | 'drawTranslucentInstanced' | 'disposeInstanced' | 'createWater' | 'drawWater' | 'disposeWater' | 'createPlumes' | 'drawPlumes' | 'disposePlumes' | 'setPlumeScale' | 'createCaustics' | 'drawCaustics' | 'disposeCaustics' | 'createParticles' | 'drawParticles' | 'drawDeviceParticles' | 'disposeParticles' | 'createWindStreaks' | 'drawWindStreaks' | 'disposeWindStreaks' | 'createFlock' | 'drawFlock' | 'disposeFlock' | 'createBolts' | 'drawBolts' | 'disposeBolts' | 'createLines' | 'drawLines' | 'disposeLines' | 'createText' | 'setText' | 'setPlate' | 'drawText' | 'textWidth' | 'disposeText' | 'createSdfText' | 'setSdfText' | 'drawSdfText' | 'disposeSdfText' | 'createSurfaceTexture' | 'createSurfaceTextureArray' | 'createLightmap' | 'createSceneCapture' | 'captureScene' | 'updateSurfaceTexture' | 'disposeSurfaceTexture' | 'setSurfaceTexture' | 'setMaterial' | 'setSurfaceOverlay' | 'createClothBinding' | 'createClothParticles' | 'updateClothParticles' | 'setCloth' | 'disposeClothBinding' | 'disposeClothParticles'> & {
     /**
      * A mesh's cloth binding: which simulation triangle each of its vertices follows, where on it and
      * by how much (`ClothBindingData`). The mesh must be skinned — a binding blends each vertex
@@ -213,6 +214,13 @@ export type RendererApi = Omit<{
     setCloth(binding: ClothBindingHandle | null, particles?: ClothParticlesHandle | null): void;
     disposeClothBinding(binding: ClothBindingHandle): void;
     disposeClothParticles(particles: ClothParticlesHandle): void;
+    /**
+     * What the following draws lay over their surfaces beyond their materials — a rim of light, a
+     * dissolve with a glowing edge, wrinkle normals by region — or null for none, which every pass
+     * starts with. Per draw, so one character's whole set of materials changes together. Its images
+     * are regions of one atlas (`SurfaceOverlay.maps`). See `surfaceOverlay.ts`.
+     */
+    setSurfaceOverlay(overlay: SurfaceOverlay | null): void;
     /**
      * Upload a caller's image, or a BC image's blocks with their stored chain where
      * `compressedFormats` has the format. See `SurfaceTextureHandle` for the boundary this guards.

package/dist/render/backend/createRenderer.d.ts

@@ -132,6 +132,12 @@ export interface CreateRendererOptions {
      * badge is looked at on a deployed build.
      */
     readonly splash?: boolean | SplashOptions;
+    /**
+     * Whether the display shows a high dynamic range, asked only where `highDynamicRange` was. The
+     * browser's `(dynamic-range: high)` query by default; a host with no DOM, or one that knows
+     * better about its own display, answers instead. See `displayRange.ts`.
+     */
+    readonly highDynamicRangeDisplay?: () => boolean;
 }
 /** What was built, and which path built it. */
 export interface CreatedRenderer {

package/dist/render/backend/createRenderer.js

@@ -4,6 +4,7 @@ import { BACKEND_TIMEOUT_MS, forcedBackend, selectBackend } from './select.js';
 import { TIMED_OUT, withDeadline } from './deadline.js';
 import { mountSplash } from '../../ui/splash.js';
 import { gpuDrivenRefusal, gpuDrivenSupported } from '../gpudriven/pipeline.js';
+import { browserHighDynamicRange, chooseDisplayRange } from '../displayRange.js';
 /**
  * What a caller who says nothing gets.
  *
@@ -177,7 +178,9 @@ export async function createRenderer(canvas, quality = {}, options = {}) {
                 const { createGpuSurface } = await import('./webgpu/device.js');
                 const { WebGPURenderer } = await import('./webgpu/renderer.js');
                 stage = 'creating the surface';
-                const surface = createGpuSurface(canvas, device);
+                const profile = resolveRenderQuality(qualityFor('webgpu'));
+                const surface = createGpuSurface(canvas, device, chooseDisplayRange(profile.highDynamicRange, profile.screenEffects && profile.hdrScene, profile.highDynamicRange &&
+                    (options.highDynamicRangeDisplay ?? browserHighDynamicRange)()));
                 stage = 'constructing the renderer';
                 return { surface, WebGPURenderer };
             })();

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

@@ -12,6 +12,7 @@ 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 SurfaceOverlay } from '../../surfaceOverlay.ts';
 import type { ColourGradeLut } from '../../colourGrade.ts';
 import { type BloomResponse } from '../../bloomChain.ts';
 import { LightField } from '../../driftLight/lightField.ts';
@@ -72,6 +73,8 @@ import { TextRenderer } from '../../textRenderer.ts';
 import { SdfTextRenderer } from '../../sdfTextRenderer.ts';
 import type { SdfFont } from '../../sdfFont.ts';
 import type { SdfTextStyle } from '../../sdfTextLayout.ts';
+import type { DisplayRange } from '../../displayRange.ts';
+import { type FilmicCurve } from '../../filmicCurve.ts';
 import type { RenderBackend } from '../api.ts';
 import type { TextStyle } from '../../textLayout.ts';
 import { WindStreakRenderer } from '../../windStreakRenderer.ts';
@@ -974,6 +977,10 @@ export declare class WebGL2Renderer implements RendererApi {
     private readonly reflectionQueue;
     /** Built on the first frame that submits a surface, and never for a scene with none. */
     private ssr;
+    /** The frame's materials' reflections, resolved; null where off. See `frameReflections.ts`. */
+    private readonly frameReflections;
+    /** Their two maps on the scene's framebuffer, null where they cannot be drawn. */
+    private readonly reflectionTargets;
     /** 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. */
@@ -1033,6 +1040,8 @@ export declare class WebGL2Renderer implements RendererApi {
      * exactly as it asked to be and nothing about it changes.
      */
     private exposure;
+    /** The `filmic` curve's eight constants, held until `setFilmicCurve` is called again. */
+    private readonly filmConstants;
     /**
      * This frame's veil colour, and how much of it to composite. See `setFrameVeil`.
      *
@@ -1234,6 +1243,15 @@ export declare class WebGL2Renderer implements RendererApi {
     private warnedNoPointShadowArray;
     /** Said once, for the retired ambient dial. */
     private warnedEnvironmentAmbient;
+    /** The overlay the draws wear, `uOverlay`: see `setSurfaceOverlay`. */
+    private readonly overlayFloats;
+    /** Its atlas, and the 2D copy of it bound where the refraction copy goes. */
+    private overlayMaps;
+    private overlayTexture;
+    /** Whether this device's lit stage has room for the overlay's vectors: asked once. */
+    private overlayRoom;
+    private warnedOverlayRoom;
+    private warnedOverlayBlocks;
     /** Whether a probe is being baked, so the passes that would recurse into one can tell. */
     private probePassActive;
     /**
@@ -1558,6 +1576,8 @@ export declare class WebGL2Renderer implements RendererApi {
      * 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.
      */
+    /** Each registered pass's declared reads, as a mask, resolved once at registration. */
+    private readonly passReads;
     registerPass(definition: PassDefinition): PassHandle;
     /**
      * How many registered passes declare `prepare`, so a frame with none walks nothing.
@@ -2015,6 +2035,27 @@ export declare class WebGL2Renderer implements RendererApi {
      * exactly as it did.
      */
     setSurfaceReflectivity(amount: number): void;
+    /**
+     * The overlay the following draws wear — a rim of light, a dissolve, wrinkles by region — or null
+     * for none. Pass state, as the material is: `bindMeshPass` puts it back to none. See
+     * `surfaceOverlay.ts` for what it lays and `shaders/flat/overlay.ts` for how.
+     *
+     * **Refused, said once, where the lit stage has no room for it.** Fifteen vectors more than the
+     * program this device fits: counted from the source as `fitFlatProgram` counts, and on a device
+     * whose limit is the 256 an Adreno 740 reports, the eight-light build at 254 has none. The draws
+     * then wear nothing, which is the picture a game without the feature draws. Its atlas is bound as
+     * a 2D copy of its first layer, in the refraction copy's unit (`SurfaceTexture.flatLayer`); a
+     * compressed atlas has no copy and is read as none, also said once.
+     */
+    setSurfaceOverlay(overlay: SurfaceOverlay | null): void;
+    /** The overlay's atlas into the refraction copy's unit, as a 2D copy, or the empty texture. */
+    private bindOverlayMaps;
+    /** The most fragment uniform vectors this GPU offers a stage. */
+    private fragmentVectorLimit;
+    /** What the lit shader at this renderer's budget leaves of the limit, with no overlay. */
+    private overlayRoomLeft;
+    /** Whether the lit shader with the overlay compiled in fits this GPU: counted once. */
+    private overlayFits;
     /**
      * How bright the environment the surfaces drawn next reflect is. 1 is the default and identity.
      *
@@ -3015,8 +3056,17 @@ export declare class WebGL2Renderer implements RendererApi {
      * 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.
+     *
+     * `maxShare` is the longest smear, as a share of the frame (0.03 unless given, at most half): a
+     * fast turn softens the frame rather than erasing it. **Each drawn object's own motion is
+     * followed only under a reconstruction on WebGPU**, which draws the motion target it reads; here,
+     * and on WebGPU without one, the camera's motion alone smears the frame, and a draw that names
+     * where it was last frame is told so once.
      */
-    setCameraMotionBlur(scale: number): void;
+    setCameraMotionBlur(scale: number, maxShare?: number): void;
+    /** The longest smear, as a share of the frame. See `setCameraMotionBlur`. */
+    private motionBlurMax;
+    private warnedObjectBlur;
     /**
      * The camera has cut: this frame is a new shot, not the next moment of the last one.
      *
@@ -3178,6 +3228,30 @@ export declare class WebGL2Renderer implements RendererApi {
      * black frame with a sign error in it.
      */
     setOutputExposure(exposure: number): void;
+    /**
+     * The `filmic` curve this and every later frame is graded through, until it is set again: a
+     * grading volume's five numbers, solved once here into the constants the resolve reads. Ignored
+     * unless `outputTransform` is `filmic`. A number out of range is clamped into it and said once,
+     * since a frame loop must not throw. See `filmicCurve.ts`.
+     */
+    setFilmicCurve(curve: FilmicCurve): void;
+    private warnedFilmClamped;
+    /**
+     * The range the frame goes out in: `'high'` where the profile asked for `highDynamicRange`, the
+     * frame holds light past white and the display shows it — on WebGPU — and `'standard'` otherwise.
+     * **Always standard here**: this backend draws into a canvas of eight bits a channel, which has
+     * nothing above white to show. Typed as the question rather than this backend's answer, because
+     * the shared surface is derived from this class.
+     */
+    readonly displayRange: DisplayRange;
+    /** Why it is that range, in words, for a game choosing its look and for a bug report. */
+    get displayRangeReason(): string;
+    /**
+     * How bright paper white and the display's peak are, in one unit, held until changed: their
+     * ratio is how far above white the highlights may run where `displayRange` is `'high'`, and
+     * nothing changes where it is standard, which is always here.
+     */
+    setDisplayLuminance(paperWhite: number, peak: number): void;
     /**
      * Composite a flat colour over the finished frame — for a cut dipping to white or to black.
      *
@@ -3242,6 +3316,14 @@ export declare class WebGL2Renderer implements RendererApi {
      * see `filmLook.ts`. Needs `screenEffects`, and says so once rather than doing nothing.
      */
     setVignette(strength: number): void;
+    /**
+     * The lens's colour fringe, held until changed: `intensity` is a percentage, 0 is none, and red
+     * and green are pulled toward the centre by their wavelength's distance from blue, growing from
+     * `start` — a share of the half-frame, 0 the centre — to the whole of it at the edge. Applied to
+     * scene light at the composite's first read. Needs `screenEffects`, and says so once rather than
+     * doing nothing. See `shaders/fringe.ts`.
+     */
+    setChromaticAberration(intensity: number, start?: number): void;
     /**
      * Film grain, held until changed: an amplitude in display values (0 is none, 0.03 is a fine
      * grain) and this frame's seed. **The seed is the caller's**, because the engine takes time from
@@ -3517,12 +3599,18 @@ export declare class WebGL2Renderer implements RendererApi {
      * here, so there is no motion target for this to be written into, and a mover passed here is
      * neither read nor advanced.
      */
-    _previousModel?: ReadonlyMat4 | Mover | null): void;
+    previousModel?: ReadonlyMat4 | Mover | null): void;
     /**
      * Whether a skin draw now draws its two halves: the profile asked, the frame has not spread its
      * skin yet, this is the frame's own picture — not a mirror's or a probe's, nor an overlay after
      * the frame — and the blur's target can be had.
      */
+    /**
+     * Whether a draw now is the frame's own, opaque and lit, and so writes the two maps beside its
+     * colour: not a mirror's, a probe's or a capture's, whose framebuffers have no maps, and not after
+     * the frame. See `reflectionSurfaceTargets.ts`.
+     */
+    private reflectionKeeps;
     private skinSplits;
     /**
      * Spread the frame's skin and add it back: once, at the first blended draw or at the frame's end.