@driftengine/core 4.2.1 → 4.4.0

package/dist/render/shaders/prefilter.js

@@ -37,6 +37,12 @@ import { OCTAHEDRAL_GLSL } from './octahedral.js';
  */
 export const PREFILTER_FRAG = `#version 300 es
 precision highp float;
+/*
+ * highp int as well, because the radical inverse below is a 32-bit bit reversal and the fragment
+ * default for int and uint is mediump. A driver that computes mediump in sixteen bits returns 0
+ * for every sample, and every cosine sample of the diffuse level lands on its own normal.
+ */
+precision highp int;
 
 ${OCTAHEDRAL_GLSL}
 

package/dist/render/shaders/rush.js

@@ -21,8 +21,16 @@
 /* The vertex stage is `FULLSCREEN_VERT`, shared with the occlusion pass and its blur. */
 import { glslSceneDepthToNdc } from '../depthConvention.js';
 import { DEPTH_OF_FIELD_GLSL } from './depthOfField.js';
+import { AUTO_EXPOSURE_GLSL } from './exposure.js';
+import { LOCAL_EXPOSURE_GLSL } from './localExposure.js';
+import { FILM_LOOK_GLSL } from './filmLook.js';
 export const RUSH_FRAG = `#version 300 es
 precision highp float;
+/*
+ * highp int as well, for the film grain's hash, which multiplies and shifts uints. The fragment
+ * default is mediump, and a sixteen-bit driver would hand back a hash of sixteen bits.
+ */
+precision highp int;
 
 in vec2 vUv;
 
@@ -133,6 +141,11 @@ uniform float uBloomStrength;
  */
 uniform vec3 uVeilColor;
 uniform float uVeilAlpha;
+${FILM_LOOK_GLSL}
+
+/* Eye adaptation's held brightness and the gain it asks for. See exposure.ts. */
+${AUTO_EXPOSURE_GLSL}
+${LOCAL_EXPOSURE_GLSL}
 
 /**
  * The colour grade: a lookup table over display values, sampled after the tone map.
@@ -291,6 +304,24 @@ vec3 cameraBlur(vec3 scene) {
   return sum / 9.0;
 }
 
+/**
+ * Everything after the light is complete, in the order the header of each step argues: the lens
+ * darkens its corners in scene light, the curve and the grade turn light into a picture, the veil
+ * fades it, and the print's grain sits on what is left. One function, so the two exits of \`main\`
+ * cannot finish a frame differently.
+ */
+vec3 finish(vec3 light) {
+  /*
+   * The eye's adaptation, in scene light and before the lens, as a camera's exposure would be; and
+   * each region's share of it, read from the light before either scales it, because that is the
+   * light the grid measured.
+   */
+  float local = localExposureGain(vUv, light);
+  light *= autoExposureGain() * local;
+  vec3 lensed = withVignette(light, vUv, vec2(textureSize(uScene, 0)));
+  return withGrain(withVeil(applyColourGrade(grade(lensed))), gl_FragCoord.xy);
+}
+
 void main() {
   vec3 scene = textureLod(uScene, vUv, 0.0).rgb;
   if (uMotionStrength > 0.0) scene = cameraBlur(scene);
@@ -328,7 +359,7 @@ void main() {
   float edge = smoothstep(inner, 1.0, radius);
   float amount = edge * uStrength;
   if (amount <= 0.0) {
-    fragColor = vec4(withVeil(applyColourGrade(grade(withBloom(scene * ao)))), 1.0);
+    fragColor = vec4(finish(withBloom(scene * ao)), 1.0);
     return;
   }
 
@@ -347,9 +378,6 @@ void main() {
   }
   vec3 blurred = sum / 7.0;
 
-  fragColor = vec4(
-    withVeil(applyColourGrade(grade(withBloom(mix(scene, blurred, amount) * ao)))),
-    1.0
-  );
+  fragColor = vec4(finish(withBloom(mix(scene, blurred, amount) * ao)), 1.0);
 }
 `;

package/dist/render/shaders/tangentFrame.d.ts

@@ -14,4 +14,4 @@
  * reason beside it; `AGENTS.md` 2026-08-07 is the rule, and WGSL refuses the module outright
  * rather than leaving a derivative in non-uniform control flow undefined.
  */
-export declare const TANGENT_FRAME_GLSL = "mat3 tangentFrame(vec3 n, vec3 worldPos, vec2 uv, vec4 tangent, int hasTangents) {\n  /*\n   * The derived frame: solve for the axis along u from how position and uv change together over\n   * the pixel. Exact where the surface is locally planar, approximate where it curves, which is\n   * the trade for working at all on geometry that carries no frame.\n   */\n  vec3 dp1 = dFdx(worldPos);\n  vec3 dp2 = dFdy(worldPos);\n  vec2 duv1 = dFdx(uv);\n  vec2 duv2 = dFdy(uv);\n  vec3 dp2perp = cross(dp2, n);\n  vec3 dp1perp = cross(n, dp1);\n  vec3 dt = dp2perp * duv1.x + dp1perp * duv2.x;\n  vec3 db = dp2perp * duv1.y + dp1perp * duv2.y;\n  /*\n   * **The determinant's sign, which magnitude-normalising throws away \u2014 and it is the difference\n   * between the two backends.**\n   *\n   * dFdy measures along *upward* window y in GLSL and along *downward* framebuffer y in WGSL, so\n   * dp2 and duv2 both arrive negated on WebGPU. The system this solves is invariant under that \u2014\n   * both sides of its second equation flip \u2014 but the closed form above is not: dt and db each come\n   * out negated, and dividing by their *length* keeps the negation instead of cancelling it. The\n   * frame then points the other way on one backend, which reads as a surface lit from the wrong\n   * side and nothing else.\n   *\n   * The UV determinant flips with them, so folding its sign back in restores the invariance the\n   * solve always had. Measured before and after on demo/dev/normal.html: the derived panel stood\n   * 86 of 255 rms from the attribute panel on WebGPU and 8.8 on WebGL2; with this they agree.\n   */\n  float det = duv1.x * duv2.y - duv2.x * duv1.y;\n  float handed = det < 0.0 ? -1.0 : 1.0;\n  /* One scale for both axes, so a stretched UV layout does not shear the frame it produces. */\n  float invmax = inversesqrt(max(max(dot(dt, dt), dot(db, db)), 1e-12)) * handed;\n  vec3 derivedT = dt * invmax;\n  vec3 derivedB = db * invmax;\n\n  /*\n   * The attribute frame, re-orthogonalised. Interpolating a tangent across a triangle leaves it\n   * no longer square to the interpolated normal, and Gram-Schmidt is what puts it back \u2014\n   * generateTangents does the same per vertex and says why: dropping it is a normal map that\n   * shears wherever the geometry curves.\n   */\n  vec3 attrT = normalize(tangent.xyz - n * dot(n, tangent.xyz));\n  /*\n   * The bitangent's sign, which is the whole reason w is stored. An artist mapping the left and\n   * right of a model onto one patch of texture gives one side a mirrored frame, and a bitangent\n   * computed without the sign lights that side inside out.\n   */\n  vec3 attrB = cross(n, attrT) * tangent.w;\n\n  vec3 t = hasTangents != 0 ? attrT : derivedT;\n  vec3 b = hasTangents != 0 ? attrB : derivedB;\n  return mat3(t, b, n);\n}";
+export declare const TANGENT_FRAME_GLSL = "mat3 tangentFrame(vec3 n, vec3 worldPos, vec2 uv, vec4 tangent, int hasTangents) {\n  /*\n   * The derived frame: solve for the axis along u from how position and uv change together over\n   * the pixel. Exact where the surface is locally planar, approximate where it curves, which is\n   * the trade for working at all on geometry that carries no frame.\n   */\n  vec3 dp1 = dFdx(worldPos);\n  vec3 dp2 = dFdy(worldPos);\n  vec2 duv1 = dFdx(uv);\n  vec2 duv2 = dFdy(uv);\n  vec3 dp2perp = cross(dp2, n);\n  vec3 dp1perp = cross(n, dp1);\n  vec3 dt = dp2perp * duv1.x + dp1perp * duv2.x;\n  vec3 db = dp2perp * duv1.y + dp1perp * duv2.y;\n  /*\n   * **The determinant's sign, which magnitude-normalising throws away \u2014 and it is the difference\n   * between the two backends.**\n   *\n   * dFdy measures along *upward* window y in GLSL and along *downward* framebuffer y in WGSL, so\n   * dp2 and duv2 both arrive negated on WebGPU. The system this solves is invariant under that \u2014\n   * both sides of its second equation flip \u2014 but the closed form above is not: dt and db each come\n   * out negated, and dividing by their *length* keeps the negation instead of cancelling it. The\n   * frame then points the other way on one backend, which reads as a surface lit from the wrong\n   * side and nothing else.\n   *\n   * The UV determinant flips with them, so folding its sign back in restores the invariance the\n   * solve always had. Measured before and after on demo/dev/normal.html: the derived panel stood\n   * 86 of 255 rms from the attribute panel on WebGPU and 8.8 on WebGL2; with this they agree.\n   */\n  float det = duv1.x * duv2.y - duv2.x * duv1.y;\n  float handed = det < 0.0 ? -1.0 : 1.0;\n  /* One scale for both axes, so a stretched UV layout does not shear the frame it produces. */\n  float invmax = inversesqrt(max(max(dot(dt, dt), dot(db, db)), 1e-12)) * handed;\n  vec3 derivedT = dt * invmax;\n  vec3 derivedB = db * invmax;\n\n  /*\n   * The attribute frame, re-orthogonalised. Interpolating a tangent across a triangle leaves it\n   * no longer square to the interpolated normal, and Gram-Schmidt is what puts it back \u2014\n   * generateTangents does the same per vertex and says why: dropping it is a normal map that\n   * shears wherever the geometry curves.\n   */\n  vec3 along = tangent.xyz - n * dot(n, tangent.xyz);\n  float alongSq = dot(along, along);\n  vec3 attrT = along * inversesqrt(max(alongSq, 1e-12));\n  /*\n   * The bitangent's sign, which is the whole reason w is stored. An artist mapping the left and\n   * right of a model onto one patch of texture gives one side a mirrored frame, and a bitangent\n   * computed without the sign lights that side inside out.\n   */\n  vec3 attrB = cross(n, attrT) * tangent.w;\n\n  /*\n   * **And only where there is a frame to keep.** A tangent parallel to its normal, or two that\n   * nearly cancel across one triangle at a mirrored seam, leaves nothing after the subtraction,\n   * and a normalised nothing is NaN. One such pixel in one probe face was a whole courtyard drawn\n   * black: a probe convolves its faces into every direction, and the bounce carries that into\n   * every other probe. So where nothing is left, the derived frame stands in. What it gives up is a\n   * direction on a pixel that had none; what would make it wrong is a threshold large enough to\n   * catch a frame that is merely short, and a unit tangent interpolated is nowhere near 1e-4.\n   */\n  bool framed = hasTangents != 0 && alongSq > 1e-8;\n  vec3 t = framed ? attrT : derivedT;\n  vec3 b = framed ? attrB : derivedB;\n  return mat3(t, b, n);\n}";

package/dist/render/shaders/tangentFrame.js

@@ -56,7 +56,9 @@ export const TANGENT_FRAME_GLSL = `mat3 tangentFrame(vec3 n, vec3 worldPos, vec2
    * generateTangents does the same per vertex and says why: dropping it is a normal map that
    * shears wherever the geometry curves.
    */
-  vec3 attrT = normalize(tangent.xyz - n * dot(n, tangent.xyz));
+  vec3 along = tangent.xyz - n * dot(n, tangent.xyz);
+  float alongSq = dot(along, along);
+  vec3 attrT = along * inversesqrt(max(alongSq, 1e-12));
   /*
    * The bitangent's sign, which is the whole reason w is stored. An artist mapping the left and
    * right of a model onto one patch of texture gives one side a mirrored frame, and a bitangent
@@ -64,7 +66,17 @@ export const TANGENT_FRAME_GLSL = `mat3 tangentFrame(vec3 n, vec3 worldPos, vec2
    */
   vec3 attrB = cross(n, attrT) * tangent.w;
 
-  vec3 t = hasTangents != 0 ? attrT : derivedT;
-  vec3 b = hasTangents != 0 ? attrB : derivedB;
+  /*
+   * **And only where there is a frame to keep.** A tangent parallel to its normal, or two that
+   * nearly cancel across one triangle at a mirrored seam, leaves nothing after the subtraction,
+   * and a normalised nothing is NaN. One such pixel in one probe face was a whole courtyard drawn
+   * black: a probe convolves its faces into every direction, and the bounce carries that into
+   * every other probe. So where nothing is left, the derived frame stands in. What it gives up is a
+   * direction on a pixel that had none; what would make it wrong is a threshold large enough to
+   * catch a frame that is merely short, and a unit tangent interpolated is nowhere near 1e-4.
+   */
+  bool framed = hasTangents != 0 && alongSq > 1e-8;
+  vec3 t = framed ? attrT : derivedT;
+  vec3 b = framed ? attrB : derivedB;
   return mat3(t, b, n);
 }`;

package/dist/render/shaders/temporalResolve.js

@@ -110,6 +110,44 @@ vec3 clipToNeighbourhood(vec3 history, vec3 lo, vec3 hi) {
   return centre + offset / ratio;
 }
 
+/*
+ * **The history read through a Catmull-Rom filter, not a bilinear one.**
+ *
+ * The reprojection lands between texels nearly everywhere, and a bilinear fetch there is a small blur;
+ * applied to a picture that is itself last frame's blend, it compounds every frame, so a still camera
+ * settled on a picture measurably softer than one frame of it. A courtyard's stone read as out of
+ * focus beside the same frame with the resolve off. Catmull-Rom passes a straight ramp through exactly
+ * and keeps the edge between two texels an edge, which is what the history is for.
+ *
+ * Five bilinear fetches rather than sixteen point ones: the middle two weights of each axis share a
+ * fetch placed between them, and the four corners, which carry a few hundredths, are left out and
+ * the rest renormalised. Its negative lobes can ring past what the frame holds, which the
+ * neighbourhood clip after it takes back, and the floor at zero keeps a float target out of the
+ * negatives meanwhile.
+ */
+vec3 historyCatmullRom(vec2 uv) {
+  vec2 size = 1.0 / uTexel;
+  vec2 at = uv * size;
+  vec2 base = floor(at - 0.5) + 0.5;
+  vec2 f = at - base;
+  vec2 w0 = f * (-0.5 + f * (1.0 - 0.5 * f));
+  vec2 w1 = 1.0 + f * f * (-2.5 + 1.5 * f);
+  vec2 w2 = f * (0.5 + f * (2.0 - 1.5 * f));
+  vec2 w3 = f * f * (-0.5 + 0.5 * f);
+  vec2 w12 = w1 + w2;
+  vec2 at0 = (base - 1.0) * uTexel;
+  vec2 at3 = (base + 2.0) * uTexel;
+  vec2 at12 = (base + w2 / w12) * uTexel;
+  vec3 sum =
+    textureLod(uHistory, vec2(at12.x, at0.y), 0.0).rgb * (w12.x * w0.y) +
+    textureLod(uHistory, vec2(at0.x, at12.y), 0.0).rgb * (w0.x * w12.y) +
+    textureLod(uHistory, at12, 0.0).rgb * (w12.x * w12.y) +
+    textureLod(uHistory, vec2(at3.x, at12.y), 0.0).rgb * (w3.x * w12.y) +
+    textureLod(uHistory, vec2(at12.x, at3.y), 0.0).rgb * (w12.x * w3.y);
+  float weight = w12.x * w0.y + w0.x * w12.y + w12.x * w12.y + w3.x * w12.y + w12.x * w3.y;
+  return max(sum / weight, vec3(0.0));
+}
+
 void main() {
   vec3 current = textureLod(uScene, vUv, 0.0).rgb;
 
@@ -142,7 +180,7 @@ void main() {
   vec3 lo;
   vec3 hi;
   neighbourhood(lo, hi);
-  vec3 history = textureLod(uHistory, wasUv, 0.0).rgb;
+  vec3 history = historyCatmullRom(wasUv);
   vec3 bounded = clipToNeighbourhood(history, lo, hi);
 
   fragColor = vec4(mix(current, bounded, uHistoryBlend), 1.0);

package/dist/render/shadowCasters.d.ts

@@ -26,9 +26,11 @@ import type { SurfaceTextureHandle } from './backend/api.ts';
  * enumeration serves the directional cascade and every point-light cubemap.
  *
  * **Every draw may also carry its material, which is what lets one enumeration serve a colour
- * pass as well as a depth one.** A depth pass ignores it, correctly: a material cannot change a
- * depth, which is why this interface was right to carry only a handle, a matrix and a palette for
- * as long as depth was the only thing replaying it. What that cost was measured from outside. A
+ * pass as well as a depth one.** A depth pass reads one thing from it, since 4.4.0: whether the
+ * caster is a cutout (`cutoutOf`), so a leaf card casts the leaf rather than the card. Everything
+ * else a material says cannot change a depth, which is why this interface carried only a handle, a
+ * matrix and a palette for as long as depth was the only thing replaying it — and why, until then,
+ * every alpha-cut surface cast its whole quad. What that cost was measured from outside. A
  * consumer wanting the scene from a second viewpoint — a mirror, a probe face — had one option,
  * which was to run its whole draw path again; the first attempt to avoid it replayed this sink
  * into the mirror and got **every car unpainted**, because the list carries no material. So the

package/dist/render/shadowMap.js

@@ -9,6 +9,7 @@
  * "zero textures" rule is about the art direction (no image assets in the
  * payload), and nothing here adds a byte to it.
  */
+import { SHADOW_DEPTH_CLEAR } from './depthConvention.js';
 import { DEFAULT_RENDER_QUALITY } from './renderQuality.js';
 export class ShadowMap {
     size;
@@ -48,6 +49,18 @@ export class ShadowMap {
                 return;
             throw new Error(`ShadowMap: framebuffer incomplete (0x${status.toString(16)})`);
         }
+        /*
+         * **Cleared once, here, to the far plane, because nothing else says what the texture holds.**
+         * WebGL zeroes it, and a zero compared with `LEQUAL` is an occluder at the light itself, so
+         * a layer no pass has drawn put the whole world in shade. ANGLE on Vulkan hands the same
+         * texture back reading 1, which is lit, and that is what every capture here ran on: a scene
+         * with a second depth layer it never peeled lost its sun only under ANGLE's GL backend, the
+         * one Chrome on Linux runs by default. The frame's clear value is borrowed and put back.
+         */
+        const frameClear = gl.getParameter(gl.DEPTH_CLEAR_VALUE);
+        gl.clearDepth(SHADOW_DEPTH_CLEAR);
+        gl.clear(gl.DEPTH_BUFFER_BIT);
+        gl.clearDepth(frameClear);
         gl.bindFramebuffer(gl.FRAMEBUFFER, null);
         gl.bindTexture(gl.TEXTURE_2D, null);
     }

package/dist/render/surfaceTexture.d.ts

@@ -59,6 +59,11 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
     vScale?: number;
     /** Alpha below which a fragment is discarded. See `uAlbedoCutout`. */
     cutout?: number;
+    /**
+     * Whether both faces are seen: glTF's `doubleSided`, what a curtain or a leaf card is. Drawn
+     * without culling, and a back face is lit as its front, with the normal turned to the viewer.
+     */
+    doubleSided?: boolean;
     /**
      * How hard the normal map turns the shading normal.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/core",
-  "version": "4.2.1",
+  "version": "4.4.0",
   "description": "DriftEngine reusable browser 3D runtime",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,8 +29,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@driftengine/drft": "4.2.1",
-    "@driftengine/physics": "4.2.1",
+    "@driftengine/drft": "4.4.0",
+    "@driftengine/physics": "4.4.0",
     "gl-matrix": "^3.4.3"
   },
   "author": "Drift Technologies",
@@ -63,8 +63,8 @@
     "prepack": "node ../../scripts/build.mjs @driftengine/core"
   },
   "devDependencies": {
-    "@driftengine/nav": "4.2.1",
-    "@driftengine/network": "4.2.1",
-    "@driftengine/texture": "4.2.1"
+    "@driftengine/nav": "4.4.0",
+    "@driftengine/network": "4.4.0",
+    "@driftengine/texture": "4.4.0"
   }
 }

package/scripts/gpuCompute.mjs

@@ -125,6 +125,22 @@ function dispatchScript(request) {
         });
         continue;
       }
+      if (spec.kind === 'emptyVolume') {
+        /* A new texture is zeros by the specification, so there is nothing to write. */
+        const texture = device.createTexture({
+          size: [1, 1, 1],
+          dimension: '3d',
+          format: spec.format,
+          usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+        });
+        entries.push({ binding: at, resource: texture.createView({ dimension: '3d' }) });
+        bindings.push({
+          binding: at,
+          visibility: GPUShaderStage.COMPUTE,
+          texture: { sampleType: spec.format === 'r32uint' ? 'uint' : 'float', viewDimension: '3d' },
+        });
+        continue;
+      }
       if (spec.kind === 'sampler') {
         const sampler = device.createSampler({
           magFilter: 'linear',
@@ -225,7 +241,7 @@ export async function openGpuCompute(options = {}) {
      * `features` are the device features the shader needs, `'shader-f16'` for a half-precision one;
      * an adapter without one of them is an error rather than a device created without it.
      *
-     * Each entry of `buffers` is bound at the binding its index names, as one of four kinds:
+     * Each entry of `buffers` is bound at the binding its index names, as one of six kinds:
      *
      * - `'storage'`, the default — `type`, `values` or `length`, `read`, `readOnly`. An `'f16'`
      *   buffer takes half-precision bits as its values, and is never read back.
@@ -242,14 +258,19 @@ export async function openGpuCompute(options = {}) {
      *   the device's sampler rounds to.
      * - `'sampler'` — `{ kind: 'sampler', address: 'clamp-to-edge' | 'repeat' }`, linear in
      *   magnification, minification and between levels.
+     * - `'emptyVolume'` — `{ kind: 'emptyVolume', format: 'r32uint' | 'rgba16float' }`: one texel
+     *   of zeros in a 3D texture, for a module that declares a volume the check leaves switched off
+     *   (the probe bake's DriftLight field).
      *
      * @param {{ wgsl: string, entryPoint?: string, workgroups?: number[], features?: string[],
-     *           buffers: { kind?: 'storage'|'uniform'|'texture2dArray'|'texture2d'|'sampler',
+     *           buffers: { kind?: 'storage'|'uniform'|'texture2dArray'|'texture2d'|'sampler'|
+     *                            'emptyVolume',
      *                      type?: 'f32'|'f16'|'u32'|'i32', values?: number[], length?: number,
      *                      read?: boolean, readOnly?: boolean, size?: number, layers?: number,
      *                      levels?: ArrayLike<number>[], address?: string,
      *                      width?: number, height?: number,
-     *                      format?: 'r32float'|'rgba32float' }[] }} request
+     *                      format?: 'r32float'|'rgba32float'|'r32uint'|'rgba16float' }[] }}
+     *        request
      */
     async run(request) {
       const prepared = {

package/scripts/png.mjs

@@ -2,9 +2,10 @@
  * Enough of a PNG reader to compare two frames, with no dependency.
  *
  * A screenshot arrives as 8-bit RGBA, filter method 0, not interlaced, which is what every
- * browser produces and is exactly what this handles. Anything else is refused by name rather
- * than guessed at, because a reader that quietly mis-decodes produces pixel differences that
- * look like a rendering change.
+ * browser produces. A bought model's maps also arrive as 8-bit grey, grey with alpha and RGB, and
+ * the baker and the native host read those through here too. Anything else — a palette, sixteen
+ * bits, interlacing — is refused by name rather than guessed at, because a reader that quietly
+ * mis-decodes produces pixel differences that look like a rendering change.
  *
  * `zlib` is Node's own, so this costs nothing to have.
  */
@@ -35,8 +36,15 @@ export function decodePng(bytes) {
       const interlace = body[12];
       if (depth !== 8) throw new Error(`bit depth ${depth}, only 8 is handled`);
       if (interlace !== 0) throw new Error('interlaced PNG, not handled');
-      channels = colorType === 6 ? 4 : colorType === 2 ? 3 : 0;
-      if (channels === 0) throw new Error(`colour type ${colorType}, only 2 and 6 are handled`);
+      /*
+       * Grey, grey with alpha, RGB and RGBA — every 8-bit type but a palette. A bought model's
+       * single-channel maps are greyscale, and refusing them left a baker's texture cap unable to
+       * shrink a third of one scene's maps. A palette needs `PLTE` read, and nothing has asked.
+       */
+      channels = { 0: 1, 4: 2, 2: 3, 6: 4 }[colorType] ?? 0;
+      if (channels === 0) {
+        throw new Error(`colour type ${colorType}, only 0, 2, 4 and 6 are handled`);
+      }
     } else if (type === 'IDAT') {
       parts.push(body);
     } else if (type === 'IEND') {
@@ -200,17 +208,20 @@ function chunk(type, body) {
   return out;
 }
 
-/** A decoded PNG as four bytes a pixel, whether it was written with three channels or four. */
+/** A decoded PNG as four bytes a pixel, whatever channels it was written with. The one widening. */
 export function rgbaOf(decoded) {
   const count = decoded.width * decoded.height;
-  if (decoded.channels === 4)
-    return { width: decoded.width, height: decoded.height, rgba: decoded.pixels };
+  const channels = decoded.channels;
+  if (channels === 4) return { width: decoded.width, height: decoded.height, rgba: decoded.pixels };
   const rgba = new Uint8Array(count * 4);
   for (let at = 0; at < count; at += 1) {
-    rgba[at * 4] = decoded.pixels[at * decoded.channels];
-    rgba[at * 4 + 1] = decoded.pixels[at * decoded.channels + 1];
-    rgba[at * 4 + 2] = decoded.pixels[at * decoded.channels + 2];
-    rgba[at * 4 + 3] = 255;
+    const from = at * channels;
+    /* Grey fills all three colour channels; RGB keeps its own. */
+    const grey = channels < 3;
+    rgba[at * 4] = decoded.pixels[from];
+    rgba[at * 4 + 1] = decoded.pixels[grey ? from : from + 1];
+    rgba[at * 4 + 2] = decoded.pixels[grey ? from : from + 2];
+    rgba[at * 4 + 3] = channels === 2 ? decoded.pixels[from + 1] : 255;
   }
   return { width: decoded.width, height: decoded.height, rgba };
 }

package/src/cinematic/cameraPath.ts

@@ -0,0 +1,178 @@
+/**
+ * A camera move through world space: an eye, a point it looks at and a field of view, keyed in time.
+ *
+ * **Not the cinematic player's shots, which frame a subject.** A shot there is placed relative to
+ * something that moves, and its keyframes are linear on purpose because a rig damps them. A walk
+ * through a building has no subject: it is a route and a gaze, both in world coordinates, and it
+ * has to arrive at each key without a kink or the motion reads as a hand-held stumble.
+ *
+ * **A cubic Hermite through every key, its tangent the key's neighbours' difference over their
+ * time apart**, which is Catmull-Rom with the keys' own times as knots. A key is passed exactly, the
+ * velocity through it is continuous, and an evenly timed straight run is exactly a constant
+ * velocity. What it gives up is continuity of acceleration — the curvature can jump at a key — and
+ * what would make that wrong is a move slow and wide enough for the jump to be seen as a change of
+ * pull. The answer then is keys further apart, not another curve.
+ *
+ * The eye and the target are interpolated separately, so a pan and a dolly are written as what they
+ * are. Allocation-free after construction: `sampleCameraPath` fills a caller-owned sample.
+ */
+import type { Vec3 } from '../math/color.ts';
+
+export interface CameraPathKey {
+  readonly atSec: number;
+  readonly eye: Readonly<Vec3>;
+  readonly target: Readonly<Vec3>;
+  readonly fovDeg: number;
+}
+
+export interface CameraPathOptions {
+  /**
+   * Whether the move wraps back through its first key. A looped path needs `periodSec`: when the
+   * first key comes round again, which must be later than the last key.
+   */
+  readonly loop: boolean;
+  readonly periodSec?: number;
+}
+
+/** Seven channels a key: eye, target, field of view. */
+const CHANNELS = 7;
+
+export interface CameraPath {
+  readonly loop: boolean;
+  /** For a loop, the period; for an open path, the time of the last key. */
+  readonly durationSec: number;
+  readonly count: number;
+  readonly times: Float64Array;
+  readonly values: Float64Array;
+  /** Per key and channel, units a second. */
+  readonly tangents: Float64Array;
+}
+
+export interface CameraPathSample {
+  eye: Vec3;
+  target: Vec3;
+  fovDeg: number;
+}
+
+export function createCameraPathSample(): CameraPathSample {
+  return { eye: [0, 0, 0], target: [0, 0, 0], fovDeg: 50 };
+}
+
+/** Check the keys and work out every tangent once. Throws at construction, never in a frame. */
+export function createCameraPath(
+  keys: readonly CameraPathKey[],
+  options: CameraPathOptions,
+): CameraPath {
+  const count = keys.length;
+  if (count < 2) throw new Error('a camera path needs at least two keys to move between');
+  const times = new Float64Array(count);
+  const values = new Float64Array(count * CHANNELS);
+  for (let i = 0; i < count; i++) {
+    const key = keys[i] as CameraPathKey;
+    if (i > 0 && !(key.atSec > (times[i - 1] as number))) {
+      throw new Error(`camera path key ${i} at ${key.atSec}s must be later than the one before`);
+    }
+    times[i] = key.atSec;
+    values.set([...key.eye, ...key.target, key.fovDeg], i * CHANNELS);
+  }
+  const first = times[0] as number;
+  const last = times[count - 1] as number;
+  let durationSec = last;
+  if (options.loop) {
+    const period = options.periodSec ?? 0;
+    if (!(first + period > last)) {
+      throw new Error(`a looped camera path's period ${period}s must end after its last key`);
+    }
+    durationSec = period;
+  }
+
+  const tangents = new Float64Array(count * CHANNELS);
+  for (let i = 0; i < count; i++) {
+    let before = i - 1;
+    let after = i + 1;
+    let tBefore = before >= 0 ? (times[before] as number) : 0;
+    let tAfter = after < count ? (times[after] as number) : 0;
+    if (options.loop) {
+      if (before < 0) {
+        before = count - 1;
+        tBefore = (times[before] as number) - durationSec;
+      }
+      if (after >= count) {
+        after = 0;
+        tAfter = (times[0] as number) + durationSec;
+      }
+    } else {
+      /* An open end has one neighbour, and its tangent is the straight line to it. */
+      if (before < 0) {
+        before = i;
+        tBefore = times[i] as number;
+      }
+      if (after >= count) {
+        after = i;
+        tAfter = times[i] as number;
+      }
+    }
+    const span = tAfter - tBefore;
+    for (let c = 0; c < CHANNELS; c++) {
+      const delta =
+        (values[after * CHANNELS + c] as number) - (values[before * CHANNELS + c] as number);
+      tangents[i * CHANNELS + c] = delta / span;
+    }
+  }
+  return { loop: options.loop, durationSec, count, times, values, tangents };
+}
+
+/** The camera at `timeSec`. An open path holds its ends; a looped one wraps. */
+export function sampleCameraPath(
+  path: CameraPath,
+  timeSec: number,
+  out: CameraPathSample,
+): CameraPathSample {
+  const { times, values, tangents, count } = path;
+  const first = times[0] as number;
+  let t = timeSec;
+  if (path.loop) {
+    t = first + ((((timeSec - first) % path.durationSec) + path.durationSec) % path.durationSec);
+  } else if (t <= first) {
+    return write(out, values, 0);
+  } else if (t >= (times[count - 1] as number)) {
+    return write(out, values, count - 1);
+  }
+
+  let i = 0;
+  while (i < count - 1 && (times[i + 1] as number) <= t) i++;
+  const next = i + 1 < count ? i + 1 : 0;
+  const t0 = times[i] as number;
+  const t1 = next === 0 ? first + path.durationSec : (times[next] as number);
+  const h = t1 - t0;
+  const u = (t - t0) / h;
+  const u2 = u * u;
+  const u3 = u2 * u;
+  const h00 = 2 * u3 - 3 * u2 + 1;
+  const h10 = u3 - 2 * u2 + u;
+  const h01 = -2 * u3 + 3 * u2;
+  const h11 = u3 - u2;
+  for (let c = 0; c < CHANNELS; c++) {
+    const v =
+      h00 * (values[i * CHANNELS + c] as number) +
+      h10 * h * (tangents[i * CHANNELS + c] as number) +
+      h01 * (values[next * CHANNELS + c] as number) +
+      h11 * h * (tangents[next * CHANNELS + c] as number);
+    if (c < 3) out.eye[c] = v;
+    else if (c < 6) out.target[c - 3] = v;
+    else out.fovDeg = v;
+  }
+  return out;
+}
+
+function write(out: CameraPathSample, values: Float64Array, key: number): CameraPathSample {
+  const at = key * CHANNELS;
+  out.eye[0] = values[at] as number;
+  out.eye[1] = values[at + 1] as number;
+  out.eye[2] = values[at + 2] as number;
+  out.target[0] = values[at + 3] as number;
+  out.target[1] = values[at + 4] as number;
+  out.target[2] = values[at + 5] as number;
+  out.fovDeg = values[at + 6] as number;
+  return out;
+}