@driftengine/core 4.4.1 → 4.4.2

package/CHANGELOG.json

@@ -1,4 +1,30 @@
 [
+ {
+  "version": "4.4.2",
+  "date": "2026-09-28",
+  "entries": [
+   {
+    "kind": "fixed",
+    "short": "A reconstructed frame no longer flickers or softens along the edges of still objects: the far side of every silhouette keeps its history.",
+    "text": "**The disocclusion test compared two different surfaces at every edge.** The reconstruction reprojects each output pixel by the nearest of its nine samples, the usual dilation, and then asked whether last frame held the same surface by reading last frame's depth under the output pixel rather than where the dilated sample had stood. At a silhouette those are the object and what is behind it, so the far side of every edge, every surface turned away from the eye and every part thinner than a sample dropped its history on a still frame: a paused picture flashed white along its outlines and read softer than a single frame of it.\n\nThe test now searches last frame's three by three around where the dilated sample stood, allows for how steeply the surface recedes, and weights the normal test by how planar the surface really is, so a thin rod no longer fails it. Measured on a consumer reconstructing at 1.5: a paused frame went from 3,269 flickering pixels to 338, and a still panel from up to 1,787 to 7, with no added ghosting in motion. The cost is 0.065 ms of GPU time at 2280 by 1291."
+   },
+   {
+    "kind": "fixed",
+    "short": "Temporal antialiasing no longer flashes on detail finer than a pixel while the camera is still: a paused grille, lace or crack of light holds steady.",
+    "text": "**A still pixel's neighbourhood now widens by its own proven flicker.** A thread finer than a pixel is caught by the jitter in some phases and missed in others, and in a phase that misses it the nine taps round the pixel miss it too: the box collapses onto the background, the settled history is clipped away, and a paused frame flashed at every fine edge. A still camera over a still scene samples every pixel the same way in every period of the jitter, so each pixel now keeps a small record of its own samples, and once two periods running have repeated, its box widens by the spread it has shown and it keeps more of its history. A surface that moves, a flame, or anything arriving breaks the repetition, and a sample beyond what the pixel has shown disqualifies the frame it lands in.\n\nMeasured on a scene of fine ironwork and fabric: a held frame went from 839 flickering pixels to 3 on WebGPU and from 1,802 to 14 on WebGL2, and the device check's edge figures are unchanged. It costs two half-float record targets beside the history. A moving camera is resolved exactly as before, and so is WebGL2 without float colour targets."
+   },
+   {
+    "kind": "fixed",
+    "short": "A point light's shadow no longer shows a straight-edged patch of wrong shadow while its map is redrawn: a map being sampled is re-baked whole or not at all.",
+    "text": "**A re-bake spread across frames was sampled half done.** Faces land in the layer the shader reads as they are drawn, and the origin they were drawn from is published only with the last one, so a map re-baked two faces a frame was read from its old origin with part of it drawn from the new one. A cube face is a 90 degree frustum, so the wrong part was a straight-edged quadrilateral of shadow on the ground under the lamp, and with the face budget spent elsewhere it could hold for over a second.\n\nA map that already holds an image is now re-baked whole or not at all, and a light being shaded may take one whole cube a frame outside `pointShadowFacesPerFrame`, the allowance a wandering light already had. A map with no image yet still fills a few faces a frame, since nothing samples it until it is complete. What it costs is six faces in the frame a shaded light goes stale, rather than two in each of three."
+   },
+   {
+    "kind": "fixed",
+    "short": "A flame's shadow no longer switches its own fixture in and out as the flame sways: the default near plane clears what the fire burns from at every point of the sway.",
+    "text": "**The near plane moved with the flame, and the fixture under it did not.** `createFlame` puts the light a third of the way up the flame, 0.83 of its width above what it burns from, with a near plane of one width, and sways it by 0.15 of a width on each axis. At the top of the sway the cut sat 7 mm under a 40 cm brazier's coals and at the bottom 13 cm, so the bowl beneath went in and out of the shadow map depending on where the flame stood when the map was last drawn, and the floor under the brazier took a dark disc on some re-bakes and none on others.\n\nThe default `shadowNear` now adds the sway, so it clears the same margin under the fire wherever the flame has wandered. A fixture reaching further below the flame than a sixth of its width sets its own `shadowNear` from its own depth."
+   }
+  ]
+ },
  {
   "version": "4.4.1",
   "date": "2026-09-28",

package/README.md

@@ -2,7 +2,7 @@
 
 The runtime everything needs: renderer, loop, camera, input, geometry. Collision and dynamics live in [`@driftengine/physics`](../physics/README.md), which this package depends on and re-exports whole, so reaching for them through this barrel works as it always did.
 
-**Cost: 789.9 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
+**Cost: 795.8 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
 3% — the number is a fact about the build rather than a claim in a document.
 
 Part of [DriftEngine](../../README.md). See [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md)

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

@@ -947,6 +947,9 @@ export declare class WebGL2Renderer implements RendererApi {
      * Scratch, filled in `endFrame`, which may not allocate.
      */
     private frameProjection;
+    /** The temporal resolve's depth-to-metres row, from the inverse of `frameProjection`. */
+    private readonly taaInvProjection;
+    private readonly taaDepthToViewZ;
     private readonly aoInvProjection;
     private readonly aoProjScale;
     /**

package/dist/render/backend/webgl2/renderer.js

@@ -626,6 +626,9 @@ export class WebGL2Renderer {
      * Scratch, filled in `endFrame`, which may not allocate.
      */
     frameProjection = null;
+    /** The temporal resolve's depth-to-metres row, from the inverse of `frameProjection`. */
+    taaInvProjection = mat4.create();
+    taaDepthToViewZ = Float32Array.of(0, 0, 0, 1);
     aoInvProjection = mat4.create();
     aoProjScale = new Float32Array(2);
     /**
@@ -4943,9 +4946,19 @@ export class WebGL2Renderer {
              * its early exit on it — so this is present every jittered frame rather than absent on some,
              * and the pass still runs and fills the history for the next one.
              */
+            /* The anti-flicker's same-surface test reads depths in metres, as the occlusion does. */
+            if (this.frameProjection !== null) {
+                mat4.invert(this.taaInvProjection, this.frameProjection);
+                this.taaDepthToViewZ[0] = this.taaInvProjection[10] ?? 0;
+                this.taaDepthToViewZ[1] = this.taaInvProjection[14] ?? 0;
+                this.taaDepthToViewZ[2] = this.taaInvProjection[11] ?? 0;
+                this.taaDepthToViewZ[3] = this.taaInvProjection[15] ?? 1;
+            }
             temporal = {
                 reprojection: this.reprojection,
                 blend: this.temporalHistoryUsable ? TEMPORAL_HISTORY_BLEND : 0,
+                periodStart: this.temporalHistory.periodStart,
+                depthToViewZ: this.taaDepthToViewZ,
             };
         }
         /*

package/dist/render/backend/webgpu/postPass.d.ts

@@ -174,14 +174,20 @@ export declare const ADDITIVE_BLEND: GPUBlendState;
 /** A fullscreen pass over one or more inputs, writing to one colour target. */
 export declare function postPipeline(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout, key: string, fragment: string, format: GPUTextureFormat, blend?: GPUBlendState): GPURenderPipeline;
 /**
- * The temporal resolve's block and its three inputs.
+ * The same over several colour targets, in the fragment's output order: the temporal resolve
+ * writes its picture and each pixel's flicker record in one pass. `targets` is the caller's, held
+ * rather than built per call, since this is asked for every frame.
+ */
+export declare function postPipelineTargets(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout, key: string, fragment: string, targets: GPUColorTargetState[]): GPURenderPipeline;
+/**
+ * The temporal resolve's block and its four inputs.
  *
  * Named like the occlusion's beside it, and for the same reason `BLOOM_DOWNSAMPLE_FIELDS` is: a
  * block read by assumption rather than by name is a uniform written to the wrong offset, which
  * draws a plausible picture.
  */
 export declare const TAA_FRAG_FIELDS: UniformFields;
-export declare const TAA_FRAG_SIZE: 80;
+export declare const TAA_FRAG_SIZE: 112;
 export declare const TAA_UNIFORMS: 1;
 export declare const TAA_TEXTURES: {
     readonly uScene: {
@@ -194,11 +200,21 @@ export declare const TAA_TEXTURES: {
         readonly sampler: 35;
         readonly type: "sampler2D";
     };
-    readonly uDepth: {
+    readonly uFlicker: {
         readonly texture: 36;
         readonly sampler: 37;
         readonly type: "sampler2D";
     };
+    readonly uFlickerMotion: {
+        readonly texture: 38;
+        readonly sampler: 39;
+        readonly type: "sampler2D";
+    };
+    readonly uDepth: {
+        readonly texture: 40;
+        readonly sampler: 41;
+        readonly type: "sampler2D";
+    };
 };
 /**
  * The order-independent resolve's inputs. It has no uniform block of its own — the whole pass is

package/dist/render/backend/webgpu/postPass.js

@@ -244,7 +244,20 @@ export const ADDITIVE_BLEND = {
 };
 /** A fullscreen pass over one or more inputs, writing to one colour target. */
 export function postPipeline(cache, device, layout, key, fragment, format, blend) {
-    return cache.get(key, () => ({
+    return cache.get(key, () => describePost(device, layout, key, fragment, [
+        blend === undefined ? { format } : { format, blend },
+    ]));
+}
+/**
+ * The same over several colour targets, in the fragment's output order: the temporal resolve
+ * writes its picture and each pixel's flicker record in one pass. `targets` is the caller's, held
+ * rather than built per call, since this is asked for every frame.
+ */
+export function postPipelineTargets(cache, device, layout, key, fragment, targets) {
+    return cache.get(key, () => describePost(device, layout, key, fragment, targets));
+}
+function describePost(device, layout, key, fragment, targets) {
+    return {
         label: key,
         layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
         vertex: {
@@ -254,7 +267,7 @@ export function postPipeline(cache, device, layout, key, fragment, format, blend
         fragment: {
             module: shaderModule(device, { label: key, code: fragment }),
             entryPoint: 'main',
-            targets: [blend === undefined ? { format } : { format, blend }],
+            targets,
         },
         /*
          * No depth at all, which is what makes this different from every other pipeline here: the
@@ -262,10 +275,10 @@ export function postPipeline(cache, device, layout, key, fragment, format, blend
          * disables the test, the write and culling by hand for the same draw.
          */
         primitive: { topology: 'triangle-list', cullMode: 'none' },
-    }));
+    };
 }
 /**
- * The temporal resolve's block and its three inputs.
+ * The temporal resolve's block and its four inputs.
  *
  * Named like the occlusion's beside it, and for the same reason `BLOOM_DOWNSAMPLE_FIELDS` is: a
  * block read by assumption rather than by name is a uniform written to the wrong offset, which

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

@@ -596,6 +596,16 @@ export declare class WebGPURenderer implements RendererApi {
     private taaUniforms;
     private taaTextures;
     private taaViews;
+    /** Each pixel's flicker record, paired with the history and swapped with it: see `temporalAa.ts`. */
+    private taaRecords;
+    private taaRecordViews;
+    /** The rest of each pixel's record — depth, pull and recent swing — beside the first. */
+    private taaMotions;
+    private taaMotionViews;
+    /** The resolve's depth-to-metres row, from the inverse of `frameProjection`. */
+    private readonly taaInvProjection;
+    /** The resolve's two targets, the picture and the record, held for the pipeline cache's sake. */
+    private taaTargets;
     /** Group `i` reads history `i` and the pass writes into the other one. */
     private taaBindGroups;
     private taaWrite;

package/dist/render/backend/webgpu/renderer.js

@@ -51,7 +51,7 @@ import { ExposurePass } from './exposurePass.js';
 import { AO_STORE } from '../../shaders/ambientOcclusion.js';
 import { clampAutoExposure } from '../../shaders/exposure.js';
 import { clampLocalExposure } from '../../shaders/localExposure.js';
-import { createDepthResolveLayout, createPostStageLayout, depthResolvePipeline, postPipeline, sceneColorFormat, AO_BLUR_FIELDS, AO_BLUR_FRAG_WGSL, AO_BLUR_SIZE, AO_BLUR_TEXTURES, AO_BLUR_UNIFORMS, AO_FRAG_FIELDS, AO_FRAG_SIZE, AO_FRAG_WGSL, AO_TEXTURES, AO_UNIFORMS, ADDITIVE_BLEND, BLOOM_DOWNSAMPLE_FIELDS, BLOOM_DOWNSAMPLE_FRAG_WGSL, BLOOM_PREFILTER_FIELDS, BLOOM_PREFILTER_FRAG_WGSL, BLOOM_STAGE_SIZE, BLOOM_TEXTURES, BLOOM_UNIFORMS, BLOOM_UPSAMPLE_FIELDS, BLOOM_UPSAMPLE_FRAG_WGSL, RESOLVED_DEPTH_FORMAT, RUSH_FRAG_FIELDS, RUSH_FRAG_SIZE, RUSH_FRAG_WGSL, RUSH_TEXTURES, RUSH_UNIFORMS, TAA_FRAG_FIELDS, TAA_FRAG_SIZE, TAA_TEXTURES, TAA_UNIFORMS, TEMPORAL_RESOLVE_FRAG_WGSL, MEDIUM_FRAG_FIELDS, MEDIUM_FRAG_SIZE, MEDIUM_FRAG_WGSL, MEDIUM_TEXTURES, MEDIUM_TRANSMIT_BLEND, MEDIUM_UNIFORMS, MEDIUM_UPSAMPLE_FIELDS, MEDIUM_UPSAMPLE_FRAG_WGSL, MEDIUM_UPSAMPLE_SIZE, MEDIUM_UPSAMPLE_TEXTURES, MEDIUM_UPSAMPLE_UNIFORMS, OIT_COMPOSITE_BLEND, OIT_RESOLVE_FRAG_WGSL, OIT_TEXTURES, DECAL_FRAG_FIELDS, DECAL_FRAG_SIZE, DECAL_MULTIPLY_BLEND, DECAL_PROJECT_FRAG_WGSL, DECAL_TEXTURES, DECAL_UNIFORMS, PREMULTIPLIED_OVER_BLEND, SSR_FRAG_FIELDS, SSR_FRAG_SIZE, SSR_RESOLVE_FRAG_WGSL, SSR_RESOLVE_TEXTURES, SSR_TEXTURES, SSR_TRACE_FRAG_WGSL, SSR_UNIFORMS, createOitResolveLayout, createSsrResolveLayout, } from './postPass.js';
+import { createDepthResolveLayout, createPostStageLayout, depthResolvePipeline, postPipeline, postPipelineTargets, sceneColorFormat, AO_BLUR_FIELDS, AO_BLUR_FRAG_WGSL, AO_BLUR_SIZE, AO_BLUR_TEXTURES, AO_BLUR_UNIFORMS, AO_FRAG_FIELDS, AO_FRAG_SIZE, AO_FRAG_WGSL, AO_TEXTURES, AO_UNIFORMS, ADDITIVE_BLEND, BLOOM_DOWNSAMPLE_FIELDS, BLOOM_DOWNSAMPLE_FRAG_WGSL, BLOOM_PREFILTER_FIELDS, BLOOM_PREFILTER_FRAG_WGSL, BLOOM_STAGE_SIZE, BLOOM_TEXTURES, BLOOM_UNIFORMS, BLOOM_UPSAMPLE_FIELDS, BLOOM_UPSAMPLE_FRAG_WGSL, RESOLVED_DEPTH_FORMAT, RUSH_FRAG_FIELDS, RUSH_FRAG_SIZE, RUSH_FRAG_WGSL, RUSH_TEXTURES, RUSH_UNIFORMS, TAA_FRAG_FIELDS, TAA_FRAG_SIZE, TAA_TEXTURES, TAA_UNIFORMS, TEMPORAL_RESOLVE_FRAG_WGSL, MEDIUM_FRAG_FIELDS, MEDIUM_FRAG_SIZE, MEDIUM_FRAG_WGSL, MEDIUM_TEXTURES, MEDIUM_TRANSMIT_BLEND, MEDIUM_UNIFORMS, MEDIUM_UPSAMPLE_FIELDS, MEDIUM_UPSAMPLE_FRAG_WGSL, MEDIUM_UPSAMPLE_SIZE, MEDIUM_UPSAMPLE_TEXTURES, MEDIUM_UPSAMPLE_UNIFORMS, OIT_COMPOSITE_BLEND, OIT_RESOLVE_FRAG_WGSL, OIT_TEXTURES, DECAL_FRAG_FIELDS, DECAL_FRAG_SIZE, DECAL_MULTIPLY_BLEND, DECAL_PROJECT_FRAG_WGSL, DECAL_TEXTURES, DECAL_UNIFORMS, PREMULTIPLIED_OVER_BLEND, SSR_FRAG_FIELDS, SSR_FRAG_SIZE, SSR_RESOLVE_FRAG_WGSL, SSR_RESOLVE_TEXTURES, SSR_TEXTURES, SSR_TRACE_FRAG_WGSL, SSR_UNIFORMS, createOitResolveLayout, createSsrResolveLayout, } from './postPass.js';
 import { GRADE_PLACEHOLDER_SIZE, identityGradeLut, validateGradeLut, } from '../../colourGrade.js';
 import { FILM_LOOK_WITHOUT_COMPOSITE, clampGrain, clampVignette, grainSeed, } from '../../shaders/filmLook.js';
 import { createProbeMipBindGroupLayout, createProbePrefilterBindGroupLayout, PREFILTER_UNIFORM_OFFSETS, probeLevels, probeMipPipeline, probePrefilterPipeline, PROBE_FACES, PROBE_FACE_BASIS, PROBE_FAR_M, PROBE_FOV_DEG, PROBE_MIP_UNIFORM_SIZE, PROBE_NEAR_M, } from './probePass.js';
@@ -1349,6 +1349,16 @@ export class WebGPURenderer {
     taaUniforms;
     taaTextures = [null, null];
     taaViews = [null, null];
+    /** Each pixel's flicker record, paired with the history and swapped with it: see `temporalAa.ts`. */
+    taaRecords = [null, null];
+    taaRecordViews = [null, null];
+    /** The rest of each pixel's record — depth, pull and recent swing — beside the first. */
+    taaMotions = [null, null];
+    taaMotionViews = [null, null];
+    /** The resolve's depth-to-metres row, from the inverse of `frameProjection`. */
+    taaInvProjection = new Float32Array(16);
+    /** The resolve's two targets, the picture and the record, held for the pipeline cache's sake. */
+    taaTargets = [];
     /** Group `i` reads history `i` and the pass writes into the other one. */
     taaBindGroups = [null, null];
     taaWrite = 0;
@@ -5230,6 +5240,8 @@ export class WebGPURenderer {
         this.taaLayout = createPostStageLayout(device, TAA_UNIFORMS, TAA_FRAG_SIZE, [
             { binding: TAA_TEXTURES.uScene },
             { binding: TAA_TEXTURES.uHistory },
+            { binding: TAA_TEXTURES.uFlicker },
+            { binding: TAA_TEXTURES.uFlickerMotion },
             { binding: TAA_TEXTURES.uDepth, filterable: false },
         ]);
         this.taaUniforms = device.createBuffer({
@@ -8647,8 +8659,10 @@ export class WebGPURenderer {
             return;
         const write = this.taaWrite;
         const target = this.taaViews[write];
+        const record = this.taaRecordViews[write];
+        const motion = this.taaMotionViews[write];
         const group = this.taaBindGroups[1 - write];
-        if (target === null || group === null)
+        if (target === null || record === null || motion === null || group === null)
             return;
         const { device } = this.surface;
         const f = this.taaFloats;
@@ -8657,15 +8671,34 @@ export class WebGPURenderer {
         f[at('uTexel')] = 1 / this.renderWidth;
         f[at('uTexel') + 1] = 1 / this.renderHeight;
         f[at('uHistoryBlend')] = this.temporalHistoryUsable ? TEMPORAL_HISTORY_BLEND : 0;
+        f[at('uPeriodStart')] = this.temporalHistory.periodStart ? 1 : 0;
+        /* The anti-flicker's same-surface test reads depths in metres, as the occlusion does. */
+        const depthRow = at('uDepthToViewZ');
+        if (this.frameProjection !== null) {
+            mat4.invert(this.taaInvProjection, this.frameProjection);
+            f[depthRow] = this.taaInvProjection[10] ?? 0;
+            f[depthRow + 1] = this.taaInvProjection[14] ?? 0;
+            f[depthRow + 2] = this.taaInvProjection[11] ?? 0;
+            f[depthRow + 3] = this.taaInvProjection[15] ?? 1;
+        }
+        else {
+            f[depthRow] = 0;
+            f[depthRow + 1] = 0;
+            f[depthRow + 2] = 0;
+            f[depthRow + 3] = 1;
+        }
+        f[at('uAntiFlicker')] = 1;
         device.queue.writeBuffer(this.taaUniforms, 0, this.taaStaging);
         const pass = encoder.beginRenderPass({
             label: 'post.taa',
             timestampWrites: this.gpuTimer.writesFor(),
             colorAttachments: [
                 { view: target, loadOp: 'clear', storeOp: 'store', clearValue: [0, 0, 0, 1] },
+                { view: record, loadOp: 'clear', storeOp: 'store', clearValue: [0, 0, 0, 0] },
+                { view: motion, loadOp: 'clear', storeOp: 'store', clearValue: [0, 0, 0, 0] },
             ],
         });
-        pass.setPipeline(postPipeline(this.pipelines, device, this.taaLayout, 'post.taa', TEMPORAL_RESOLVE_FRAG_WGSL, sceneColorFormat(this.quality.hdrScene)));
+        pass.setPipeline(postPipelineTargets(this.pipelines, device, this.taaLayout, 'post.taa', TEMPORAL_RESOLVE_FRAG_WGSL, this.taaTargets));
         pass.setBindGroup(0, group, [0]);
         pass.draw(3);
         pass.end();
@@ -12292,7 +12325,28 @@ export class WebGPURenderer {
             });
             this.taaTextures[i] = texture;
             this.taaViews[i] = texture.createView();
+            /* The records in half float, whatever the picture's format: one of them holds metres. */
+            this.taaRecords[i]?.destroy();
+            const record = device.createTexture({
+                label: `post.taaRecord${i}`,
+                size: [width, height],
+                format: 'rgba16float',
+                usage: USAGE,
+            });
+            this.taaRecords[i] = record;
+            this.taaRecordViews[i] = record.createView();
+            this.taaMotions[i]?.destroy();
+            /* Two numbers a pixel: the depth its sample stood at, in metres, and how far that swings. */
+            const motion = device.createTexture({
+                label: `post.taaMotion${i}`,
+                size: [width, height],
+                format: 'rg16float',
+                usage: USAGE,
+            });
+            this.taaMotions[i] = motion;
+            this.taaMotionViews[i] = motion.createView();
         }
+        this.taaTargets = [{ format }, { format: 'rgba16float' }, { format: 'rg16float' }];
         this.taaWrite = 0;
         /* A resized target is a new texture, so whatever the history held is gone. */
         this.temporalHistory.invalidate();
@@ -12478,8 +12532,15 @@ export class WebGPURenderer {
             const scene = this.sceneColorView;
             const history = this.taaViews[i];
             const resolved = this.taaViews[1 - i];
-            if (scene === null || history === null || resolved === null)
+            const record = this.taaRecordViews[i];
+            const motion = this.taaMotionViews[i];
+            if (scene === null ||
+                history === null ||
+                resolved === null ||
+                record === null ||
+                motion === null) {
                 continue;
+            }
             this.taaBindGroups[i] = device.createBindGroup({
                 label: `post.taaBindGroup${i}`,
                 layout: this.taaLayout,
@@ -12487,6 +12548,8 @@ export class WebGPURenderer {
                     { binding: TAA_UNIFORMS, resource: { buffer: this.taaUniforms, size: TAA_FRAG_SIZE } },
                     ...entry(TAA_TEXTURES.uScene, scene),
                     ...entry(TAA_TEXTURES.uHistory, history),
+                    ...entry(TAA_TEXTURES.uFlicker, record),
+                    ...entry(TAA_TEXTURES.uFlickerMotion, motion),
                     ...entry(TAA_TEXTURES.uDepth, this.resolvedDepthView, true),
                 ],
             });

package/dist/render/flameLight.js

@@ -11,6 +11,7 @@ export function flameFrequencyHz(diameterM) {
 export function createFlame(options) {
     const height = HEIGHT_PER_DIAMETER * options.diameterM;
     const centre = [options.x, options.y + height / 3, options.z];
+    const swayM = (options.sway ?? SWAY_PER_HEIGHT) * height;
     /* A seed spread over the whole turn, so seeds 1 and 2 are not neighbours in phase. */
     const phase = ((options.seed ?? 0) * 2.399963) % (Math.PI * 2);
     const light = {
@@ -23,7 +24,19 @@ export function createFlame(options) {
         radius: options.radius,
         /* Off, because this helper is the flicker; the selection's own would apply a second one. */
         flicker: 0,
-        shadowNear: Math.max(0.05, options.diameterM),
+        /*
+         * **Clear of what the fire burns from wherever the light has wandered**, which is the sway added
+         * to the near plane a still flame would want. The shadow map is baked from where the light
+         * stood, so the cut moves with it, and each axis moves by at most `swayM`: a near plane of D
+         * alone left a brazier's bowl 7 mm inside it at the top of the sway and 13 cm outside at the
+         * bottom, and the bowl's shadow on the floor under the brazier came and went with every
+         * re-bake — a dark disc on some, none on others.
+         *
+         * What it gives up is `swayM` of shadow nearest the light, which is inside the fixture. What
+         * would make it wrong is a fixture reaching further below the flame than D / 6: this clears
+         * that far and no further, so a deep bowl sets its own `shadowNear` from its own depth.
+         */
+        shadowNear: Math.max(0.05, options.diameterM) + swayM,
         sourceRadius: options.diameterM / 2,
         ...(options.castsShadow === false ? { castsShadow: false } : {}),
     };
@@ -41,7 +54,7 @@ export function createFlame(options) {
         color: [options.color[0], options.color[1], options.color[2]],
         flicker: options.flicker ?? 0.18,
         phase,
-        swayM: (options.sway ?? SWAY_PER_HEIGHT) * height,
+        swayM,
     };
 }
 /** Where the flame's light is and how bright, at `timeSeconds`. Writes `flame.light` in place. */

package/dist/render/pointShadowBudget.js

@@ -177,15 +177,15 @@ export function runPointShadowBakes(pool, lights, facesPerFrame, liveFacesPerFra
          * **The run decays rather than resetting, and it climbs past the threshold before it stops.**
          *
          * A light that wanders on a curve is not stale on *every* frame — near the turning points of
-         * its travel it moves less in a frame than the rebake tolerance, so a run that reset to zero
-         * lost the tracking allowance there and the map dropped back to two faces a frame. The shadow
-         * then travelled smoothly through the fast part of the wander and stepped through the slow
-         * part, which is not motion and not stillness: it reads as a vibration. Reported that way,
-         * against a brazier, once the tracking allowance was in.
+         * its travel it moves less in a frame than the rebake tolerance. When the run decided whether a
+         * wanderer got its whole cube, a run that reset to zero dropped it back to two faces a frame
+         * there, and the shadow stepped through the slow part of the wander: reported as a vibration
+         * against a brazier. Every image-holding map is re-baked whole now, so the run only orders the
+         * queue, and the hysteresis keeps a wanderer behind the lights that settle instead of letting
+         * it jump ahead at every turning point.
          *
-         * So the run is hysteresis. It climbs to twice the threshold, which buys a light that has
-         * earned the allowance three quiet frames before it loses it, and decays one frame at a time
-         * so a light that genuinely settles stops re-baking rather than holding a budget for ever.
+         * It climbs to twice the threshold, which keeps a light chronic for three quiet frames, and
+         * decays one frame at a time so a light that genuinely settles rejoins the ordinary order.
          */
         const previous = scratch.staleRun[slot] ?? 0;
         const run = stale
@@ -198,37 +198,40 @@ export function runPointShadowBakes(pool, lights, facesPerFrame, liveFacesPerFra
     let faces = facesPerFrame;
     let urgentSpent = false;
     /*
-     * **One wandering light finishes its cube in the frame it started it**, the same allowance a
-     * light with no image at all gets, and for a reason that turns out to be the same one: a map
-     * dribbled out at two faces a frame is a map nobody can sample correctly until it lands.
+     * **A map that holds an image is re-baked whole or not at all**, and one being shaded may take a
+     * whole cube a frame outside the budget to make that possible.
      *
-     * A cold light cannot be sampled *at all* until its six faces are in, so it takes the whole
-     * cube at once. A chronically stale one can be sampled throughout and is wrong in a quieter
-     * way: `planBake` pins the origin for the whole of a resumed bake, so six faces spread over
-     * three frames means the published origin steps once every third frame. The shader shoots from
-     * that origin, so the shadow it draws steps with it — reported on a brazier as motion that was
-     * "really fast, not smooth, snappy, and unrealistic", which is a 20 Hz sample of a flame that
-     * wanders about once a second.
+     * Faces land in the layer the shader samples as they are drawn, and `planBake` publishes the
+     * origin they were drawn from only with the last one. So a re-bake spread over frames is a cube
+     * the shader reads from the old origin with part of it drawn from the new one — and a face is a
+     * 90 degree frustum, so the part drawn from somewhere else is a straight-edged quadrilateral of
+     * wrong shadow on the ground under the lamp. With the budget spent elsewhere it could hold for a
+     * second and more. Reported under a brazier as a dark shape that came and went.
      *
-     * Given the cube in one frame the origin moves every frame and the shadow travels instead.
+     * A map with no image yet is not sampled until its sixth face lands (see
+     * `PointShadowSystem.bind`), so it still fills a few faces a frame, and a cold one being shaded
+     * still jumps the queue with all six.
      *
-     * **Bounded to one light, and it has to be.** Eight braziers each taking six passes is the 48
-     * passes and 89 ms `pointShadowFacesPerFrame` exists to prevent. One is the light being shaded
-     * that most recently went stale, which is the one somebody is standing next to; the rest keep
-     * dribbling under the ordinary budget, and their shadows step rather than travel. That is the
-     * right way round: a shadow you are looking at moves, and a shadow across the square does not
-     * cost the frame.
+     * The allowance used to be for a *chronically* stale light only — a wandering flame — whose
+     * dribbled cube published a new origin once every third frame, so its shadow stepped at 20 Hz
+     * where the flame wanders about once a second: reported as motion that was "really fast, not
+     * smooth, snappy, and unrealistic". Any shaded light is owed the same now, because a cube read
+     * part-way is wrong in the same place for the same reason whether or not it will be stale again.
      *
-     * It is spent *after* the cold and settling groups, because `planPointShadowBakes` orders the
-     * chronic ones last — so a light arriving in range still gets its first image ahead of a flame
-     * refining one it already has.
+     * **Bounded to one light, and it has to be.** Eight braziers each taking six passes is the 48
+     * passes and 89 ms `pointShadowFacesPerFrame` exists to prevent. The first in the plan's order
+     * takes it, and `planPointShadowBakes` puts the lights that settled ahead of the ones that never
+     * do, so a flame refining its image cannot hold a correction hostage. The rest keep sampling a
+     * complete image from a few centimetres away until their turn, which is the trade
+     * `pointShadowRebakeDistance` already makes. A warm map, held but not shaded, is re-baked when a
+     * whole cube fits the budget or once it is shaded, and not before.
      *
-     * **What would make it wrong** is a caster set heavy enough that six passes over it does not
-     * fit the frame. Measured against a game whose whole static world is about 8,500 triangles in
-     * a handful of draws; a world an order of magnitude heavier wants `pointShadowFacesPerFrame`
+     * **What would make it wrong** is a caster set heavy enough that six passes over it does not fit
+     * the frame. Measured against a game whose whole static world is about 8,500 triangles in a
+     * handful of draws; a world an order of magnitude heavier wants `pointShadowFacesPerFrame`
      * raised or this given up, and `gpuTiming` is how to tell which.
      */
-    let trackingSpent = false;
+    let refreshSpent = false;
     for (let i = 0; i < planned && faces > 0; i++) {
         const slot = scratch.order[i] ?? -1;
         /*
@@ -241,15 +244,22 @@ export function runPointShadowBakes(pool, lights, facesPerFrame, liveFacesPerFra
         if (light === undefined || map === undefined)
             continue;
         const sampled = slot < pool.sampledCount;
-        const cold = sampled && scratch.ready[slot] === 0;
-        const urgent = cold && !urgentSpent;
-        /* A light being shaded whose map will be stale again next frame however it is served. */
-        const tracking = !cold && sampled && scratch.chronic[slot] === 1 && !trackingSpent;
-        if (urgent)
-            urgentSpent = true;
-        if (tracking)
-            trackingSpent = true;
-        faces -= bake(map, light, staticCasters, urgent || tracking ? faceCount : faces);
+        if (scratch.ready[slot] !== 1) {
+            /* No image to spoil: a few faces a frame, or all six at once for one being shaded. */
+            const urgent = sampled && !urgentSpent;
+            if (urgent)
+                urgentSpent = true;
+            faces -= bake(map, light, staticCasters, urgent ? faceCount : faces);
+            continue;
+        }
+        if (faces >= faceCount) {
+            faces -= bake(map, light, staticCasters, faceCount);
+            continue;
+        }
+        if (!sampled || refreshSpent)
+            continue;
+        refreshSpent = true;
+        faces -= bake(map, light, staticCasters, faceCount);
     }
     /*
      * Live maps contain movers only and are composed with the static maps in the shader. A second

package/dist/render/recon/disocclusion.d.ts

@@ -12,10 +12,15 @@
  * a different part of a texel than the one it stands for, which at a grazing angle is a different
  * depth; the tolerance grows with the motion's length.
  *
+ * **And in proportion to the surface's own slope.** A new jitter samples a surface somewhere else, so
+ * on one turned from the eye two frames' samples of it differ by up to a texel's worth of its depth
+ * with nothing moved. `surfaceSlope` measures that step on the surface's own side of any silhouette.
+ *
  * **Normals, for the case depth cannot see.** A leaf's two sides are at one depth, and the history of
  * the front is not the back. The forward frame has no normal buffer, so both normals come from their
  * frame's depth — `worldPositionFromDepth` and `normalFromPositions` — in world space, where the two
- * frames agree.
+ * frames agree. **A normal differenced across an edge is not a normal**, so the caller weighs each by
+ * `planarity`: at an edge, a sliver, or anything finer than a texel the depth test decides alone.
  *
  * **Continuous in every input**, because a step is a line on screen along which the history is kept on
  * one frame and dropped on the next: every threshold is a smoothstep, never a comparison.
@@ -38,14 +43,42 @@ export interface DisocclusionParams {
  * normals trusted fully within sixty degrees and not at all past ninety.
  */
 export declare const DEFAULT_DISOCCLUSION: DisocclusionParams;
+/**
+ * The band over which three texels stop being one plane: how far their two steps in inverse depth
+ * fail to cancel, as a share of the two together. None of it is a plane at any angle; all of it is an
+ * edge — one side steps, the other does not — or a sliver, both stepping the same way.
+ *
+ * **A share and not a size**, which is the lesson of the rods in `resolve.test.ts`: a part a
+ * hundredth of the depth in front of a wall passes the depth test, and a normal differenced across it
+ * still leans by its height over a texel's width — nearly edge-on where texels are small. What would
+ * make this wrong is a curved surface judged at its apex, where both steps lean one way and the
+ * normal is sound; there it only gives the normals less say, which the depth test does not need.
+ */
+export declare const PLANAR_FROM = 0.25;
+export declare const PLANAR_TO = 0.5;
+/**
+ * How sure it is that `centre` and its neighbours either side along one axis lie on one plane, one to
+ * zero. Inverse depth is affine across a plane on screen, so a plane's two steps cancel whatever its
+ * angle. One where a neighbour is missing — zero, off the picture or undrawn — or where there is no
+ * step to compare: nothing to judge by, so a normal keeps the say it always had.
+ */
+export declare function planarity(before: number, centre: number, after: number): number;
+/**
+ * How far a surface's depth moves across one texel along an axis, relative to the depth: the smaller
+ * of the steps to its two neighbours, because beside a silhouette one of them is the surface behind.
+ * Zero at a sliver — nearer or farther than both, so each step is to another surface — and one
+ * neighbour's step where only one is there.
+ */
+export declare function surfaceSlope(before: number, centre: number, after: number): number;
 /**
  * One where the history is trustworthy, zero where it is not, and continuous between.
  *
  * `currDepth` is the view depth this surface should have had last frame; `histDepth` the view depth
  * last frame held where it lands, or zero where it landed off the screen; `motionLength` the motion's
- * length in uv; `normalDot` the cosine between the two frames' world normals there.
+ * length in uv; `normalDot` the cosine between the two frames' world normals there; `slope` the
+ * surface's `surfaceSlope`, which widens the tolerance one for one.
  */
-export declare function disocclusionWeight(currDepth: number, histDepth: number, motionLength: number, normalDot: number, params: DisocclusionParams): number;
+export declare function disocclusionWeight(currDepth: number, histDepth: number, motionLength: number, normalDot: number, params: DisocclusionParams, slope?: number): number;
 /**
  * The world position a depth stands for: `(u, v, clipDepth)` through the inverse view-projection,
  * in whatever depth convention that matrix was built for. Returns false where the matrix has no