@driftengine/core 4.11.1 → 4.12.0

package/dist/render/surfaceLayerLooks.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Which layer of a layered material's arrays each of its layers reads, and how each looks: the
+ * fifteen vectors `shaders/flat/layerLooks.ts` reads, packed from `SurfaceMaterial.layers`.
+ *
+ * **Why a material needs these at all.** Layers read from the material's own arrays in order, so
+ * a texture worn by fifty materials in fifty tints had to be baked fifty times, each with its tint,
+ * its roughness range and its normal strength in the pixels. Picked by index from arrays the
+ * materials share, and given their look as numbers, each texture is held once: a set of layered
+ * materials built from a few textures costs those textures rather than one copy per material.
+ *
+ * **What it gives up**: fifteen fragment uniform vectors, so it is a lit switch of its own,
+ * `LAYER_LOOKS`, which a device short of vectors refuses while still drawing the layers; a layer's
+ * look is a handful of numbers, not a graph; and every layer is still read wherever any shows, as
+ * `surfaceLayers.ts` says, now from arrays that may be large.
+ */
+import type { Vec3 } from '../math/color.ts';
+import type { SurfaceLayers } from './surfaceLayers.ts';
+/**
+ * One layer's own look, applied to what it reads before the layers are blended. Every field is the
+ * identity where it is absent, so a material names only what differs.
+ */
+export interface SurfaceLayerLook {
+    /** Multiplies the layer's colour, linear. Above 1 brightens it. Absent: `[1, 1, 1]`. */
+    readonly tint?: Vec3;
+    /** The roughness the ORM's green channel is spread over, from its 0 to its 1. Absent: `[0, 1]`. */
+    readonly roughness?: readonly [number, number];
+    /** The metalness the ORM's blue channel is spread over, the same way. Absent: `[0, 1]`. */
+    readonly metalness?: readonly [number, number];
+    /**
+     * How far the layer's normal map bends the surface: its tangent-space x and y times this, before
+     * the layers' normals are blended. 0 is flat, 1 the map as it is. Absent: 1.
+     */
+    readonly normalStrength?: number;
+    /**
+     * The layer's specular, in the units a mesh's vertices carry theirs: how strong a highlight is,
+     * and under `physicalSpecular` the reflectance head-on, `0.08 × specular`. Blended across the
+     * layers as their colours are. Absent: the surface's own, as its vertices give it.
+     */
+    readonly specular?: number;
+}
+/** What an occlusion read at the mesh's own coordinates darkens, and how far. */
+export interface SurfaceMeshOcclusion {
+    /** 0 to 1: the surface times `mix(1, occlusion, strength)`. Absent: 1. */
+    readonly strength?: number;
+    /**
+     * `'color'`, the default, darkens the blended colour, and so every light on it, the sun's too.
+     * `'ambient'` darkens the ambient light alone, sky, ground and probe, as an ambient occlusion
+     * does, leaving the sun, the lamps and the reflections as they were.
+     */
+    readonly into?: 'color' | 'ambient';
+    /** The range the occlusion's red is spread over, from its 0 to its 1. Absent: `[0, 1]`. */
+    readonly range?: readonly [number, number];
+}
+/** Floats `packLayerLooks` writes: fifteen vectors. */
+export declare const LOOK_FLOATS = 60;
+/**
+ * Whether a material asks for anything the `LAYER_LOOKS` switch carries: layers picked by index,
+ * extra maps placed somewhere other than just past the layers, a look, a repeat that is a pair, or
+ * a mesh occlusion.
+ */
+export declare function asksLayerLooks<Texture>(layers: SurfaceLayers<Texture> | null | undefined): boolean;
+/**
+ * `layers` into `out`, fifteen vectors, the identity wherever a material says nothing — which is
+ * also what a layered material that asks for none of this is drawn with once another has switched
+ * `LAYER_LOOKS` on, so it must draw exactly as it did before.
+ *
+ * - **0 to 7**: the array layer each layer reads, base first (layer `i` where not given); where the
+ *   maps beyond the layers start (the layer count where not given); the mesh occlusion's strength,
+ *   and what it darkens, 0 the colour and 1 the ambient light.
+ * - **8 to 47**: two vectors a layer, base first: its tint and its normal strength, then its
+ *   roughness range and its metalness range.
+ * - **48 to 59**: each layer's specular (−1 for the surface's own), each layer's repeat down (its
+ *   repeat across where it gave one number), and the range the occlusion is spread over.
+ *
+ * An array layer that is not a whole number at or above 0 reads layer `i`; a start that is not one
+ * is the count; a strength is held to 0..1; a tint channel, a normal strength or a specular that is
+ * not a number at or above 0 is the identity; a repeat down that is not a positive number is the
+ * repeat across; a range end that is not a number is the identity's end.
+ */
+export declare function packLayerLooks<Texture>(layers: SurfaceLayers<Texture> | null | undefined, out: Float32Array): void;

package/dist/render/surfaceLayerLooks.js

@@ -0,0 +1,83 @@
+import { MAX_SURFACE_LAYERS, across } from './surfaceLayers.js';
+/** Floats `packLayerLooks` writes: fifteen vectors. */
+export const LOOK_FLOATS = 60;
+/** The specular a layer is packed with when it names none: the surface's own, as its vertices give it. */
+const OWN_SPECULAR = -1;
+/**
+ * Whether a material asks for anything the `LAYER_LOOKS` switch carries: layers picked by index,
+ * extra maps placed somewhere other than just past the layers, a look, a repeat that is a pair, or
+ * a mesh occlusion.
+ */
+export function asksLayerLooks(layers) {
+    if (layers === null || layers === undefined)
+        return false;
+    return (layers.arrayLayers !== undefined ||
+        layers.extrasAt !== undefined ||
+        layers.looks !== undefined ||
+        layers.repeats.some((repeat) => typeof repeat !== 'number') ||
+        occlusionOf(layers.meshOcclusion).strength > 0);
+}
+/**
+ * `layers` into `out`, fifteen vectors, the identity wherever a material says nothing — which is
+ * also what a layered material that asks for none of this is drawn with once another has switched
+ * `LAYER_LOOKS` on, so it must draw exactly as it did before.
+ *
+ * - **0 to 7**: the array layer each layer reads, base first (layer `i` where not given); where the
+ *   maps beyond the layers start (the layer count where not given); the mesh occlusion's strength,
+ *   and what it darkens, 0 the colour and 1 the ambient light.
+ * - **8 to 47**: two vectors a layer, base first: its tint and its normal strength, then its
+ *   roughness range and its metalness range.
+ * - **48 to 59**: each layer's specular (−1 for the surface's own), each layer's repeat down (its
+ *   repeat across where it gave one number), and the range the occlusion is spread over.
+ *
+ * An array layer that is not a whole number at or above 0 reads layer `i`; a start that is not one
+ * is the count; a strength is held to 0..1; a tint channel, a normal strength or a specular that is
+ * not a number at or above 0 is the identity; a repeat down that is not a positive number is the
+ * repeat across; a range end that is not a number is the identity's end.
+ */
+export function packLayerLooks(layers, out) {
+    const count = Math.min(layers?.repeats.length ?? 0, MAX_SURFACE_LAYERS);
+    const picks = layers?.arrayLayers;
+    for (let i = 0; i < MAX_SURFACE_LAYERS; i++)
+        out[i] = arrayLayer(picks?.[i], i);
+    out[5] = arrayLayer(layers?.extrasAt, count);
+    const occlusion = occlusionOf(layers?.meshOcclusion);
+    out[6] = occlusion.strength;
+    out[7] = occlusion.into === 'ambient' ? 1 : 0;
+    for (let i = 0; i < MAX_SURFACE_LAYERS; i++) {
+        const look = layers?.looks?.[i] ?? null;
+        const at = 8 + i * 8;
+        out[at] = atLeastZero(look?.tint?.[0], 1);
+        out[at + 1] = atLeastZero(look?.tint?.[1], 1);
+        out[at + 2] = atLeastZero(look?.tint?.[2], 1);
+        out[at + 3] = atLeastZero(look?.normalStrength, 1);
+        out[at + 4] = finiteOr(look?.roughness?.[0], 0);
+        out[at + 5] = finiteOr(look?.roughness?.[1], 1);
+        out[at + 6] = finiteOr(look?.metalness?.[0], 0);
+        out[at + 7] = finiteOr(look?.metalness?.[1], 1);
+        out[48 + i] = atLeastZero(look?.specular, OWN_SPECULAR);
+        const repeat = layers?.repeats[i];
+        const acrossIt = positiveOr(across(repeat), 1);
+        out[53 + i] = typeof repeat === 'object' ? positiveOr(repeat[1], acrossIt) : acrossIt;
+    }
+    out[58] = finiteOr(occlusion.range?.[0], 0);
+    out[59] = finiteOr(occlusion.range?.[1], 1);
+}
+/** The number form of `meshOcclusion` as the object form, the strength held to 0..1. */
+function occlusionOf(occlusion) {
+    const given = typeof occlusion === 'number' ? { strength: occlusion } : (occlusion ?? { strength: 0 });
+    const strength = given.strength ?? 1;
+    return { ...given, strength: Number.isFinite(strength) ? Math.min(Math.max(strength, 0), 1) : 0 };
+}
+function arrayLayer(value, otherwise) {
+    return value !== undefined && Number.isInteger(value) && value >= 0 ? value : otherwise;
+}
+function atLeastZero(value, otherwise) {
+    return value !== undefined && Number.isFinite(value) && value >= 0 ? value : otherwise;
+}
+function positiveOr(value, otherwise) {
+    return value !== undefined && Number.isFinite(value) && value > 0 ? value : otherwise;
+}
+function finiteOr(value, otherwise) {
+    return value !== undefined && Number.isFinite(value) ? value : otherwise;
+}

package/dist/render/surfaceLayers.d.ts

@@ -2,14 +2,16 @@
  * A material blended from layers by a mask: `SurfaceMaterial.layers`, the four vectors
  * `shaders/flat/layered.ts` reads it from, and the decisions both backends take about it.
  */
+import type { SurfaceLayerLook, SurfaceMeshOcclusion } from './surfaceLayerLooks.ts';
 import type { SurfaceProjection } from './surfaceProjection.ts';
 /** The most layers a material blends: a base and one for each of the mask's four channels. */
 export declare const MAX_SURFACE_LAYERS = 5;
 /**
  * Up to five layers, each its own colour, normal and roughness at its own repeat, blended by a mask.
  *
- * **Layer `i` is layer `i` of the material's arrays**: `albedo`, `normal` and `orm` each an array
- * whose layers are the material's layers in order, read at the mesh's coordinates times
+ * **Layer `i` is layer `i` of the material's arrays**, unless `arrayLayers` picks another: `albedo`,
+ * `normal` and `orm` each an array whose layers are the material's layers, read at the mesh's
+ * coordinates times
  * `repeats[i]`, so rock can repeat forty times across a cliff while the moss on it repeats three.
  * Where the material has a `projection`, the layers are read at the world's horizontal position
  * instead, so a repeat is so many a metre (with the projection's own scale at 1). **The mask** is
@@ -21,8 +23,13 @@ export declare const MAX_SURFACE_LAYERS = 5;
  * **Maps beyond the layers ride the material's own arrays, after its layers**, so they take no
  * texture binding of their own — the lit stage has none to spare: a mask the ORM array carries
  * (`mask: 'orm'`) is the ORM array's layer just past the layers, an `addMask` the one after that,
- * and `meshNormal` the normal array's layer just past the layers. Each shares its array's size and
- * format, so a four-channel mask wants an array that stores four.
+ * a `meshOcclusion` the one after any of those, and `meshNormal` the normal array's layer just past
+ * the layers. `extrasAt` moves where "just past" is, for materials that share arrays. Each shares
+ * its array's size and format, so a four-channel mask wants an array that stores four.
+ *
+ * **Shared arrays and a look of each layer's own** — `arrayLayers`, `extrasAt`, `looks` and
+ * `meshOcclusion` — are a lit switch of their own, `LAYER_LOOKS`, and `surfaceLayerLooks.ts` says
+ * what they cost.
  *
  * **What it gives up**: every layer's maps are read wherever any shows, three reads a layer, so five
  * layers are fifteen reads where one material is three; layers share an array's size and format; a
@@ -38,8 +45,12 @@ export interface SurfaceLayers<Texture> {
      * vertex colour's red, green and blue, which then weights the layers instead of tinting them.
      */
     readonly mask: Texture | 'orm' | 'vertex';
-    /** Each layer's repeats across the mesh's coordinates, base first: one to five of them. */
-    readonly repeats: readonly number[];
+    /**
+     * Each layer's repeats across the mesh's coordinates, base first: one to five of them. A pair is a
+     * repeat across and a repeat down apart, moss stretched along a trunk; a pair is drawn through the
+     * `LAYER_LOOKS` switch, which a single number does not need.
+     */
+    readonly repeats: readonly (number | readonly [number, number])[];
     /** The layer the emissive map glows on, 0 to 4. Absent: everywhere, as on any material. */
     readonly emissiveLayer?: number;
     /**
@@ -75,6 +86,34 @@ export interface SurfaceLayers<Texture> {
      * layer repeating forty times across it cannot carry.
      */
     readonly meshNormal?: boolean;
+    /**
+     * Which layer of the material's albedo, normal and ORM arrays each layer reads, base first, so
+     * many materials can share one array of each kind and hold every texture once. Absent, or past
+     * its end, layer `i` reads layer `i`. The same index reads all three arrays, so a texture's three
+     * maps sit at the same layer of each.
+     */
+    readonly arrayLayers?: readonly number[];
+    /**
+     * The layer of each array where the maps beyond the layers start: the ORM array's mask, added
+     * mask and mesh occlusion, in that order, and the normal array's mesh normal. Absent: just past
+     * the layers, at the layer count — which is no place for them once materials share arrays.
+     */
+    readonly extrasAt?: number;
+    /**
+     * Each layer's own look, base first: a tint, the ranges its ORM's roughness and metalness are
+     * spread over, and how far its normal map bends the surface. Absent or null for a layer: the map
+     * as it is.
+     */
+    readonly looks?: readonly (SurfaceLayerLook | null | undefined)[];
+    /**
+     * An occlusion read at the mesh's own coordinates — the red of the ORM array's layer after the
+     * layers and any mask or added mask the array carries — darkening the surface by a strength from 0
+     * to 1: the large shading of a cliff that layers repeating across it cannot carry, as
+     * `meshNormal` carries its shape. A number is that strength, darkening the blended colour; the
+     * object form also chooses what it darkens and the range its red is spread over. Absent or 0:
+     * none.
+     */
+    readonly meshOcclusion?: number | SurfaceMeshOcclusion;
 }
 /** Floats `packSurfaceLayers` writes: four vectors. */
 export declare const LAYER_FLOATS = 16;
@@ -105,3 +144,5 @@ export declare function layersFitBeside<Texture>(layers: SurfaceLayers<Texture>,
  * Anything else as it was. Whether to say so is the caller's.
  */
 export declare function layeredProjection<Texture>(projection: SurfaceProjection | null | undefined, layers: SurfaceLayers<Texture> | null | undefined): SurfaceProjection | null;
+/** A layer's repeat across: the number, or the first of a pair. The second is `LAYER_LOOKS`'. */
+export declare function across(repeat: number | readonly [number, number] | undefined): number | undefined;

package/dist/render/surfaceLayers.js

@@ -22,7 +22,7 @@ export function packSurfaceLayers(layers, out) {
         return;
     const count = Math.min(layers.repeats.length, MAX_SURFACE_LAYERS);
     for (let i = 0; i < MAX_SURFACE_LAYERS; i++)
-        out[i] = positive(i < count ? layers.repeats[i] : 1);
+        out[i] = positive(i < count ? across(layers.repeats[i]) : 1);
     out[5] = count;
     const glow = layers.emissiveLayer;
     out[6] = glow !== undefined && Number.isInteger(glow) && glow >= 0 && glow < count ? glow : -1;
@@ -70,6 +70,10 @@ export function layeredProjection(projection, layers) {
         return projection;
     return { kind: 'planar', scale: projection.scale };
 }
+/** A layer's repeat across: the number, or the first of a pair. The second is `LAYER_LOOKS`'. */
+export function across(repeat) {
+    return typeof repeat === 'number' || repeat === undefined ? repeat : repeat[0];
+}
 /** A layer an added mask or the facing may name: one a channel lays, 1 to `count − 1`, or −1. */
 function laidLayer(layer, count) {
     return layer !== undefined && Number.isInteger(layer) && layer >= 1 && layer < count ? layer : -1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/core",
-  "version": "4.11.1",
+  "version": "4.12.0",
   "description": "The runtime of DriftEngine, a WebGPU game engine with a WebGL2 fallback: renderer, loop, input, cameras, scene graph and physics",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,8 +29,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@driftengine/drft": "4.11.1",
-    "@driftengine/physics": "4.11.1",
+    "@driftengine/drft": "4.12.0",
+    "@driftengine/physics": "4.12.0",
     "gl-matrix": "^3.4.3"
   },
   "author": "Drift Technologies",
@@ -67,8 +67,8 @@
     "prepack": "node ../../scripts/build.mjs @driftengine/core"
   },
   "devDependencies": {
-    "@driftengine/nav": "4.11.1",
-    "@driftengine/network": "4.11.1",
-    "@driftengine/texture": "4.11.1"
+    "@driftengine/nav": "4.12.0",
+    "@driftengine/network": "4.12.0",
+    "@driftengine/texture": "4.12.0"
   }
 }

package/scripts/browser.d.mts

@@ -7,6 +7,11 @@ export interface LaunchedBrowser {
   close(): Promise<void>;
 }
 
+/** Where a Chromium-based browser lives on a platform, in the order `chromePath` tries them. */
+export function browserCandidates(
+  platform?: string,
+  env?: Readonly<Record<string, string | undefined>>,
+): string[];
 export function chromePath(): string;
 export function launch(options?: {
   flags?: readonly string[];

package/scripts/browser.mjs

@@ -27,22 +27,64 @@
  * it, and it is what turns "leaks accumulate forever" into "at most one leak per still-running
  * process."
  */
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { once } from 'node:events';
 import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { sleep } from './cdp.mjs';
 
-/** Where a Chrome or Chromium lives, in the order worth trying. `CHROME_PATH` wins. */
-const CANDIDATES = [
-  '/opt/google/chrome/chrome',
-  '/usr/bin/google-chrome',
-  '/usr/bin/google-chrome-stable',
-  '/usr/bin/chromium',
-  '/usr/bin/chromium-browser',
-  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
-];
+/**
+ * Where a Chromium-based browser lives on each platform, in the order worth trying.
+ *
+ * **Edge is last on every list and the only thing on Windows that is always there.** It is
+ * Chromium, it speaks the same DevTools protocol, and it ships with Windows 10 and 11, so a person
+ * who never installed Chrome still has a browser this module can drive. Chrome comes first where it
+ * exists because it is what the engine's captures are measured on.
+ *
+ * Windows paths are built from the environment rather than written out, because `Program Files`
+ * is wherever that machine put it and a per-user install sits under `LOCALAPPDATA`; a Mac's
+ * per-user install sits under `~/Applications`. Nothing here has been run on Windows or macOS by
+ * this repository yet; the lists are the browsers' documented install locations.
+ */
+export function browserCandidates(platform = process.platform, env = process.env) {
+  if (platform === 'win32') {
+    const roots = [env['PROGRAMFILES'], env['PROGRAMFILES(X86)'], env['LOCALAPPDATA']].filter(
+      (root) => typeof root === 'string' && root !== '',
+    );
+    return [
+      ...roots.map((root) =>
+        path.win32.join(root, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+      ),
+      ...roots.map((root) =>
+        path.win32.join(root, 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
+      ),
+    ];
+  }
+  if (platform === 'darwin') {
+    /* `/Applications` for an install by an administrator, `~/Applications` for one without. */
+    const roots = [
+      '/Applications',
+      typeof env['HOME'] === 'string' && env['HOME'] !== ''
+        ? path.posix.join(env['HOME'], 'Applications')
+        : null,
+    ].filter((root) => root !== null);
+    const apps = [
+      'Google Chrome.app/Contents/MacOS/Google Chrome',
+      'Chromium.app/Contents/MacOS/Chromium',
+      'Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+    ];
+    return apps.flatMap((app) => roots.map((root) => path.posix.join(root, app)));
+  }
+  return [
+    '/opt/google/chrome/chrome',
+    '/usr/bin/google-chrome',
+    '/usr/bin/google-chrome-stable',
+    '/usr/bin/chromium',
+    '/usr/bin/chromium-browser',
+    '/usr/bin/microsoft-edge',
+  ];
+}
 
 /**
  * What it takes to reach the real card from a headless process.
@@ -80,7 +122,7 @@ const PROFILE_PREFIX = 'driftengine-shots-';
 const OWNER_FILE = 'driftengine-owner.json';
 
 /**
- * Signal an entire process group, escalating if it does not go.
+ * Stop a browser and every process it started, escalating if it does not go.
  *
  * **Chrome is a tree, not a process.** It forks a zygote, a GPU process and one renderer per
  * page, and signalling the parent alone leaves the rest running with the port closed and the
@@ -89,9 +131,20 @@ const OWNER_FILE = 'driftengine-owner.json';
  *
  * SIGTERM first because a browser asked politely flushes and exits; SIGKILL after a grace period
  * because one that is wedged never will, and a wedged browser is exactly the case this exists for.
+ *
+ * **Windows has no process groups to signal**, so there `taskkill /T` walks the tree from the
+ * browser's own PID and `/F` ends it at once. Synchronous, because this also runs from an `exit`
+ * handler, where nothing asynchronous gets to finish.
  */
 function killTree(pid, graceMs = 2000) {
   if (!Number.isInteger(pid) || pid <= 0) return;
+  if (process.platform === 'win32') {
+    spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], {
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    return;
+  }
   try {
     process.kill(-pid, 'SIGTERM');
   } catch {
@@ -194,10 +247,11 @@ function defaultIsAlive(pid) {
 export function chromePath() {
   const asked = process.env['CHROME_PATH'];
   if (asked !== undefined && asked !== '') return asked;
-  const found = CANDIDATES.find((candidate) => existsSync(candidate));
+  const candidates = browserCandidates();
+  const found = candidates.find((candidate) => existsSync(candidate));
   if (found === undefined) {
     throw new Error(
-      `no Chrome or Chromium found. Tried:\n  ${CANDIDATES.join('\n  ')}\nSet CHROME_PATH to one.`,
+      `no Chrome, Chromium or Edge found. Tried:\n  ${candidates.join('\n  ')}\nSet CHROME_PATH to one.`,
     );
   }
   return found;
@@ -227,7 +281,7 @@ export async function launch({ flags = GPU_FLAGS, headless = true, timeoutMs = 2
      process and every renderer with one signal to the negative PID. `unref()` is deliberately
      not called: the parent must stay attached, or its own exit and signal handlers below never
      fire, and those are half of what closes the other three holes. */
-  const child = spawn(binary, args, { stdio: 'ignore', detached: true });
+  const child = spawn(binary, args, { stdio: 'ignore', detached: true, windowsHide: true });
   writeFileSync(
     path.join(profile, OWNER_FILE),
     JSON.stringify({ ownerPid: process.pid, chromePid: child.pid }),

package/scripts/look.d.mts

@@ -0,0 +1,81 @@
+import type { RgbaImage } from './png.d.mts';
+
+/** The backends `look` photographs by default, in the order a consumer runs them. */
+export const LOOK_BACKENDS: readonly ['webgpu', 'webgl2'];
+
+/** At or above this share of one colour, a canvas is called empty. */
+export const EMPTY_SHARE: number;
+
+/** What a frame is made of. */
+export interface FrameStats {
+  readonly width: number;
+  readonly height: number;
+  /** The most common colour, as `#rrggbb`. */
+  readonly dominant: string;
+  /** The share of the frame that colour covers, 0 to 1. */
+  readonly dominantShare: number;
+  /** Rec. 709 luminance averaged over the frame, 0 to 255. */
+  readonly meanLuminance: number;
+}
+
+/** One backend's photograph and everything the page said while it was taken. */
+export interface LookCapture {
+  readonly backend: string;
+  readonly url: string;
+  /** What a player sees, interface included. */
+  readonly file: string;
+  /**
+   * The backend that actually drew, read from the context the page's canvas asked for: `'webgpu'`,
+   * `'webgl2'`, or `null` when no canvas in the page asked for either.
+   */
+  readonly drawnWith: 'webgpu' | 'webgl2' | null;
+  /** Measured over the canvas alone; `null` when the page never booted. */
+  readonly stats: FrameStats | null;
+  /** The share of the canvas that changed between two frames; `null` when the page never booted. */
+  readonly moved: number | null;
+  readonly errors: readonly string[];
+  readonly warnings: readonly string[];
+  /** Every console line, `level: text`. */
+  readonly logs: readonly string[];
+  readonly problems: readonly string[];
+}
+
+export interface LookReport {
+  readonly url: string;
+  /** The renderer string of the GPU that drew, read from a WebGL2 context. */
+  readonly gpu: string;
+  readonly captures: readonly LookCapture[];
+  readonly problems: readonly string[];
+  /** True when no capture found a problem. */
+  readonly ok: boolean;
+}
+
+export interface LookOptions {
+  /** The address of the running game. */
+  readonly url: string;
+  readonly backends?: readonly string[];
+  /** Where the PNGs and `look.json` go. Defaults to `.driftengine/look`. */
+  readonly out?: string;
+  readonly width?: number;
+  readonly height?: number;
+  /** How long to wait for a canvas in the page to ask for a WebGPU or WebGL2 context. */
+  readonly bootMs?: number;
+  /** A pause after that for the first frames. */
+  readonly settleMs?: number;
+  /** How long to wait after that for the canvas to show more than one colour. */
+  readonly drawMs?: number;
+  /** The gap between the two frames compared to tell whether the game moves. */
+  readonly moveMs?: number;
+  /** Browser flags; defaults to `gpuFlagsFor()`. */
+  readonly flags?: readonly string[] | null;
+  /** `false` opens a real window, for a machine whose headless browser cannot reach its GPU. */
+  readonly headless?: boolean;
+}
+
+export function gpuFlagsFor(platform?: string): string[] | null;
+export function lookUrl(url: string, backend: string): string;
+export function frameStats(image: RgbaImage): FrameStats;
+export function changedShare(a: RgbaImage, b: RgbaImage, tolerance?: number): number;
+export function sortConsole(lines: readonly string[]): { errors: string[]; warnings: string[] };
+export function look(options: LookOptions): Promise<LookReport>;
+export function formatLook(report: LookReport): string;