@driftengine/native-host 4.3.0 → 4.4.1

package/dist/frameLoop.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The host's frames, in the order a browser runs one: the page's animation frames, the frame
+ * itself, the task's microtask checkpoint, then the present.
+ *
+ * **The checkpoint before the present is the part that is easy to lose.** A browser puts the canvas
+ * on the screen when the task ends, after every microtask queued in it has run, and the WebGPU
+ * renderer relies on that: whatever is drawn after `endFrame` is submitted on a microtask, since
+ * there is no second `endFrame` to hang it on. A host that presents as soon as the frame returns
+ * blits the canvas before that submission, so the window never shows an overlay while the canvas
+ * texture, which a capture reads back, holds it — a loading screen seen by every capture and by
+ * nobody at the machine.
+ *
+ * Taken as steps rather than as a window, so the order can be held by a test without a display.
+ */
+/** One frame's call: the page's clock in milliseconds, and how many frames were drawn before it. */
+export interface FrameCall {
+    readonly now: number;
+    readonly drawn: number;
+}
+/** The device's error scope around a frame, where there is a device to scope. */
+export interface FrameErrors {
+    open(): void;
+    close(): void;
+}
+export interface FrameSteps {
+    /** Stop after this many; unbounded when absent. */
+    readonly frames?: number;
+    /** Whether to draw another: false once the window has closed or the game has asked to quit. */
+    readonly open: () => boolean;
+    /** The page's clock, read once a frame. */
+    readonly clock: () => number;
+    /** Where a held clock moves, before anything reads it. */
+    readonly before?: (drawn: number) => void;
+    /** The page's animation-frame callbacks, which a browser runs before it paints. */
+    readonly animationFrames: (now: number) => void;
+    /** The device's error scope for this frame, or null before the canvas has a device. */
+    readonly errors: () => FrameErrors | null;
+    /**
+     * Draw the frame, or answer with a promise when there is nothing to draw until it settles — a
+     * scene still mounting. The loop waits for it, presents nothing for that frame and does not count
+     * it, rather than spinning through empty frames: that burned a core between two scenes, and spent
+     * a run's frame budget before the next scene had drawn once.
+     */
+    readonly frame?: (call: FrameCall) => void | Promise<void>;
+    /** Put the canvas on the screen. */
+    readonly present: () => void;
+    readonly after?: (call: FrameCall) => void;
+}
+/** Draw until `open` says stop or `frames` are drawn, and answer how many were. */
+export declare function runFrames(steps: FrameSteps): Promise<number>;

package/dist/frameLoop.js

@@ -0,0 +1,46 @@
+/**
+ * The host's frames, in the order a browser runs one: the page's animation frames, the frame
+ * itself, the task's microtask checkpoint, then the present.
+ *
+ * **The checkpoint before the present is the part that is easy to lose.** A browser puts the canvas
+ * on the screen when the task ends, after every microtask queued in it has run, and the WebGPU
+ * renderer relies on that: whatever is drawn after `endFrame` is submitted on a microtask, since
+ * there is no second `endFrame` to hang it on. A host that presents as soon as the frame returns
+ * blits the canvas before that submission, so the window never shows an overlay while the canvas
+ * texture, which a capture reads back, holds it — a loading screen seen by every capture and by
+ * nobody at the machine.
+ *
+ * Taken as steps rather than as a window, so the order can be held by a test without a display.
+ */
+/** Draw until `open` says stop or `frames` are drawn, and answer how many were. */
+export async function runFrames(steps) {
+    const frames = steps.frames ?? Number.POSITIVE_INFINITY;
+    let drawn = 0;
+    while (steps.open() && drawn < frames) {
+        steps.before?.(drawn);
+        const now = steps.clock();
+        steps.animationFrames(now);
+        const errors = steps.errors();
+        errors?.open();
+        const waiting = steps.frame?.({ now, drawn });
+        if (waiting !== undefined) {
+            errors?.close();
+            await waiting;
+            continue;
+        }
+        /*
+         * The microtask checkpoint, then the present. A macrotask is the one boundary Node guarantees
+         * every microtask has run by, chained ones included. What it gives up: the device's and SDL's
+         * callbacks may take a turn between the frame and the present, where a browser runs nothing
+         * else. Both only queue work; neither draws.
+         */
+        await new Promise((resolve) => setImmediate(resolve));
+        steps.present();
+        errors?.close();
+        steps.after?.({ now, drawn });
+        drawn += 1;
+        /* A task between frames, so SDL's events and the device's callbacks get their turn. */
+        await new Promise((resolve) => setImmediate(resolve));
+    }
+    return drawn;
+}

package/dist/images.js

@@ -20,7 +20,7 @@
 import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import decodeJpeg, { init as initJpeg } from '@jsquash/jpeg/decode.js';
-import { decodePng } from '@driftengine/core/scripts/png.mjs';
+import { decodePng, rgbaOf } from '@driftengine/core/scripts/png.mjs';
 const HOST_BITMAP = Symbol('driftengine host bitmap');
 export function isHostBitmap(value) {
     return typeof value === 'object' && value !== null && HOST_BITMAP in value;
@@ -35,21 +35,6 @@ function bitmap(width, height, data, premultiplied) {
         [HOST_BITMAP]: true,
     };
 }
-/** Four bytes a pixel out of three or four. */
-function rgba(pixels, channels, count) {
-    const out = new Uint8ClampedArray(count * 4);
-    if (channels === 4) {
-        out.set(pixels.subarray(0, count * 4));
-        return out;
-    }
-    for (let at = 0; at < count; at += 1) {
-        out[at * 4] = pixels[at * channels];
-        out[at * 4 + 1] = pixels[at * channels + 1];
-        out[at * 4 + 2] = pixels[at * channels + 2];
-        out[at * 4 + 3] = 255;
-    }
-    return out;
-}
 let jpegReady = null;
 /** MozJPEG's module, compiled once from the file its package ships. */
 function readyJpeg() {
@@ -78,8 +63,8 @@ export async function hostCreateImageBitmap(source, options = {}) {
     }
     const bytes = new Uint8Array(await source.arrayBuffer());
     if (source.type === 'image/png') {
-        const png = decodePng(Buffer.from(bytes));
-        const pixels = rgba(png.pixels, png.channels, png.width * png.height);
+        const png = rgbaOf(decodePng(Buffer.from(bytes)));
+        const pixels = new Uint8ClampedArray(png.rgba.buffer, png.rgba.byteOffset, png.rgba.length);
         return bitmap(png.width, png.height, pixels, premultiplied);
     }
     if (source.type === 'image/jpeg') {

package/dist/index.d.ts

@@ -21,3 +21,4 @@ export type { GameEntry, GameOptions } from './game.ts';
 export { configDirectory, startHost } from './runtime.ts';
 export type { FrameCall, HostOptions, NativeHost, RunOptions } from './runtime.ts';
 export { tileFiles } from './tileFiles.ts';
+export type { PresentMode } from './window.ts';

package/dist/runtime.d.ts

@@ -16,8 +16,9 @@
 import { type AudioDefaults } from './audio.ts';
 import type { NativeBridge } from './bridge.ts';
 import type { NativeCanvas } from './canvas.ts';
+import { type FrameCall } from './frameLoop.ts';
 import { HostPage } from './page.ts';
-import { HostWindow } from './window.ts';
+import { HostWindow, type PresentMode } from './window.ts';
 import type { WindowMode } from './windowMode.ts';
 export interface HostOptions {
     readonly title: string;
@@ -37,17 +38,15 @@ export interface HostOptions {
     /** `location.search`, for a game that reads its address. */
     readonly query?: string;
     readonly audio?: AudioDefaults;
+    /** How frames reach the screen; `fifo` by default. See `HostWindowOptions.presentMode`. */
+    readonly presentMode?: PresentMode;
 }
-export interface FrameCall {
-    /** The page's clock for this frame, in milliseconds. */
-    readonly now: number;
-    /** Frames drawn before this one. */
-    readonly drawn: number;
-}
+export type { FrameCall } from './frameLoop.ts';
 export interface RunOptions {
     readonly frames?: number;
     readonly before?: (drawn: number) => void;
-    readonly frame?: (call: FrameCall) => void;
+    /** Draw, or answer with a promise to be waited for when there is nothing to draw: see `runFrames`. */
+    readonly frame?: (call: FrameCall) => void | Promise<void>;
     readonly after?: (call: FrameCall) => void;
 }
 export interface NativeHost {
@@ -58,7 +57,8 @@ export interface NativeHost {
     /**
      * Draw until the window closes, the game asks to quit, or `frames` have been drawn. Each frame
      * calls `before` (where a held clock moves), runs the page's animation frames, calls `frame`,
-     * puts the canvas on the screen and calls `after`. Answers how many were drawn.
+     * lets the microtasks it queued run, puts the canvas on the screen and calls `after`. Answers how
+     * many were drawn.
      */
     run(options?: RunOptions): Promise<number>;
     /** Flush the store and close the window. */

package/dist/runtime.js

@@ -20,6 +20,7 @@ import sdl from '@kmamal/sdl';
 import { BRIDGE_KEY } from '@driftengine/package/bridge';
 import { installAudio } from './audio.js';
 import { errorsOf } from './device.js';
+import { runFrames } from './frameLoop.js';
 import { hostFetch } from './files.js';
 import { HostGamepads } from './gamepads.js';
 import { installGpu, installLocation } from './globals.js';
@@ -46,6 +47,7 @@ export function startHost(options) {
         hidden: options.hidden === true,
         mode: options.mode,
         resizable: options.resizable,
+        presentMode: options.presentMode,
     });
     installGpu(window.gpu);
     installLocation(options.query ?? '');
@@ -73,27 +75,20 @@ export function startHost(options) {
         page,
         canvas: window.canvas,
         bridge,
-        async run(run = {}) {
-            const frames = run.frames ?? Number.POSITIVE_INFINITY;
-            let drawn = 0;
-            while (!window.isClosed && !quitting && drawn < frames) {
-                run.before?.(drawn);
-                const now = performance.now();
-                /* The page's animation frames first, as a browser runs them before it paints. */
-                page.runFrame(now);
-                const context = window.canvas.getContext('webgpu');
-                const configuration = context.getConfiguration();
-                const errors = configuration === null ? null : errorsOf(configuration.device);
-                errors?.open();
-                run.frame?.({ now, drawn });
-                window.present();
-                errors?.close();
-                run.after?.({ now, drawn });
-                drawn += 1;
-                /* A task between frames, so SDL's events and the device's callbacks get their turn. */
-                await new Promise((resolve) => setImmediate(resolve));
-            }
-            return drawn;
+        /* In a browser's order, the microtask checkpoint before the present included: see `frameLoop.ts`. */
+        run(run = {}) {
+            return runFrames({
+                ...run,
+                open: () => !window.isClosed && !quitting,
+                clock: () => performance.now(),
+                animationFrames: (now) => page.runFrame(now),
+                errors: () => {
+                    const context = window.canvas.getContext('webgpu');
+                    const configuration = context.getConfiguration();
+                    return configuration === null ? null : errorsOf(configuration.device);
+                },
+                present: () => window.present(),
+            });
         },
         async close() {
             bridge.flushSync();

package/dist/window.d.ts

@@ -28,7 +28,20 @@ export interface HostWindowOptions {
     /** As a packaged game's manifest says; windowed and resizable when it says nothing. */
     readonly mode?: WindowMode;
     readonly resizable?: boolean;
+    /**
+     * How a frame reaches the screen: `fifo`, the default, waits for the display's next refresh.
+     *
+     * **Named because the pacing is the compositor's, not the engine's.** The binding renders into
+     * X11 windows only, so a Wayland session runs this through XWayland, and what `fifo` waits for
+     * there differs by window: measured on one session, a hidden window held 58 fps where a visible
+     * one drew a light scene at 250. A caller measuring the engine wants the wait out of the way.
+     * `mailbox` never waits and the display takes the newest frame at its own rate, at the cost of
+     * drawing frames nobody sees; `immediate` also tears.
+     */
+    readonly presentMode?: PresentMode;
 }
+/** The binding's swap-chain modes, as `renderGPUDeviceToWindow` takes them. */
+export type PresentMode = 'fifo' | 'fifoRelaxed' | 'immediate' | 'mailbox';
 export declare class HostWindow {
     readonly canvas: NativeCanvas;
     readonly gpu: GPU;
@@ -37,6 +50,7 @@ export declare class HostWindow {
     private device;
     private renderer;
     private presenter;
+    private readonly presentMode;
     private closed;
     constructor(options: HostWindowOptions);
     /**

package/dist/window.js

@@ -33,6 +33,7 @@ export class HostWindow {
     device = null;
     renderer = null;
     presenter = null;
+    presentMode;
     closed = false;
     constructor(options) {
         this.window = sdl.video.createWindow({
@@ -43,6 +44,7 @@ export class HostWindow {
             visible: options.hidden !== true,
             webgpu: true,
         });
+        this.presentMode = options.presentMode ?? 'fifo';
         this.canvas = new NativeCanvas(this.window.pixelWidth, this.window.pixelHeight);
         this.instance = gpuModule.create([]);
         this.gpu = nativeGpu(this.instance);
@@ -158,6 +160,7 @@ export class HostWindow {
         this.renderer = gpuModule.renderGPUDeviceToWindow({
             device: device,
             window: this.window,
+            presentMode: this.presentMode,
         });
         this.presenter = new Presenter(device, this.renderer.getCurrentTexture().format);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/native-host",
-  "version": "4.3.0",
+  "version": "4.4.1",
   "description": "The engine on a native window and a native WebGPU device, with no browser between them",
   "license": "Apache-2.0",
   "type": "module",
@@ -37,13 +37,13 @@
     "node-web-audio-api": "2.2.0"
   },
   "devDependencies": {
-    "@driftengine/audio": "4.3.0"
+    "@driftengine/audio": "4.4.1"
   },
   "peerDependencies": {
-    "@driftengine/core": "4.3.0",
-    "@driftengine/package": "4.3.0",
-    "@driftengine/texture": "4.3.0",
-    "@driftengine/ui2d": "4.3.0"
+    "@driftengine/core": "4.4.1",
+    "@driftengine/package": "4.4.1",
+    "@driftengine/texture": "4.4.1",
+    "@driftengine/ui2d": "4.4.1"
   },
   "peerDependenciesMeta": {
     "@driftengine/texture": {

package/src/frameLoop.ts

@@ -0,0 +1,84 @@
+/**
+ * The host's frames, in the order a browser runs one: the page's animation frames, the frame
+ * itself, the task's microtask checkpoint, then the present.
+ *
+ * **The checkpoint before the present is the part that is easy to lose.** A browser puts the canvas
+ * on the screen when the task ends, after every microtask queued in it has run, and the WebGPU
+ * renderer relies on that: whatever is drawn after `endFrame` is submitted on a microtask, since
+ * there is no second `endFrame` to hang it on. A host that presents as soon as the frame returns
+ * blits the canvas before that submission, so the window never shows an overlay while the canvas
+ * texture, which a capture reads back, holds it — a loading screen seen by every capture and by
+ * nobody at the machine.
+ *
+ * Taken as steps rather than as a window, so the order can be held by a test without a display.
+ */
+
+/** One frame's call: the page's clock in milliseconds, and how many frames were drawn before it. */
+export interface FrameCall {
+  readonly now: number;
+  readonly drawn: number;
+}
+
+/** The device's error scope around a frame, where there is a device to scope. */
+export interface FrameErrors {
+  open(): void;
+  close(): void;
+}
+
+export interface FrameSteps {
+  /** Stop after this many; unbounded when absent. */
+  readonly frames?: number;
+  /** Whether to draw another: false once the window has closed or the game has asked to quit. */
+  readonly open: () => boolean;
+  /** The page's clock, read once a frame. */
+  readonly clock: () => number;
+  /** Where a held clock moves, before anything reads it. */
+  readonly before?: (drawn: number) => void;
+  /** The page's animation-frame callbacks, which a browser runs before it paints. */
+  readonly animationFrames: (now: number) => void;
+  /** The device's error scope for this frame, or null before the canvas has a device. */
+  readonly errors: () => FrameErrors | null;
+  /**
+   * Draw the frame, or answer with a promise when there is nothing to draw until it settles — a
+   * scene still mounting. The loop waits for it, presents nothing for that frame and does not count
+   * it, rather than spinning through empty frames: that burned a core between two scenes, and spent
+   * a run's frame budget before the next scene had drawn once.
+   */
+  readonly frame?: (call: FrameCall) => void | Promise<void>;
+  /** Put the canvas on the screen. */
+  readonly present: () => void;
+  readonly after?: (call: FrameCall) => void;
+}
+
+/** Draw until `open` says stop or `frames` are drawn, and answer how many were. */
+export async function runFrames(steps: FrameSteps): Promise<number> {
+  const frames = steps.frames ?? Number.POSITIVE_INFINITY;
+  let drawn = 0;
+  while (steps.open() && drawn < frames) {
+    steps.before?.(drawn);
+    const now = steps.clock();
+    steps.animationFrames(now);
+    const errors = steps.errors();
+    errors?.open();
+    const waiting = steps.frame?.({ now, drawn });
+    if (waiting !== undefined) {
+      errors?.close();
+      await waiting;
+      continue;
+    }
+    /*
+     * The microtask checkpoint, then the present. A macrotask is the one boundary Node guarantees
+     * every microtask has run by, chained ones included. What it gives up: the device's and SDL's
+     * callbacks may take a turn between the frame and the present, where a browser runs nothing
+     * else. Both only queue work; neither draws.
+     */
+    await new Promise((resolve) => setImmediate(resolve));
+    steps.present();
+    errors?.close();
+    steps.after?.({ now, drawn });
+    drawn += 1;
+    /* A task between frames, so SDL's events and the device's callbacks get their turn. */
+    await new Promise((resolve) => setImmediate(resolve));
+  }
+  return drawn;
+}

package/src/images.ts

@@ -23,7 +23,7 @@ import { createRequire } from 'node:module';
 
 import decodeJpeg, { init as initJpeg } from '@jsquash/jpeg/decode.js';
 
-import { decodePng } from '@driftengine/core/scripts/png.mjs';
+import { decodePng, rgbaOf } from '@driftengine/core/scripts/png.mjs';
 
 /** What a host hands back for an image: its size and four bytes a pixel, top row first. */
 export interface HostBitmap {
@@ -63,22 +63,6 @@ function bitmap(
   } as HostBitmap;
 }
 
-/** Four bytes a pixel out of three or four. */
-function rgba(pixels: Uint8Array, channels: number, count: number): Uint8ClampedArray {
-  const out = new Uint8ClampedArray(count * 4);
-  if (channels === 4) {
-    out.set(pixels.subarray(0, count * 4));
-    return out;
-  }
-  for (let at = 0; at < count; at += 1) {
-    out[at * 4] = pixels[at * channels] as number;
-    out[at * 4 + 1] = pixels[at * channels + 1] as number;
-    out[at * 4 + 2] = pixels[at * channels + 2] as number;
-    out[at * 4 + 3] = 255;
-  }
-  return out;
-}
-
 let jpegReady: Promise<void> | null = null;
 
 /** MozJPEG's module, compiled once from the file its package ships. */
@@ -112,8 +96,8 @@ export async function hostCreateImageBitmap(
   }
   const bytes = new Uint8Array(await source.arrayBuffer());
   if (source.type === 'image/png') {
-    const png = decodePng(Buffer.from(bytes));
-    const pixels = rgba(png.pixels, png.channels, png.width * png.height);
+    const png = rgbaOf(decodePng(Buffer.from(bytes)));
+    const pixels = new Uint8ClampedArray(png.rgba.buffer, png.rgba.byteOffset, png.rgba.length);
     return bitmap(png.width, png.height, pixels, premultiplied);
   }
   if (source.type === 'image/jpeg') {

package/src/index.ts

@@ -22,3 +22,4 @@ export type { GameEntry, GameOptions } from './game.ts';
 export { configDirectory, startHost } from './runtime.ts';
 export type { FrameCall, HostOptions, NativeHost, RunOptions } from './runtime.ts';
 export { tileFiles } from './tileFiles.ts';
+export type { PresentMode } from './window.ts';

package/src/runtime.ts

@@ -25,13 +25,14 @@ import { type AudioDefaults, installAudio } from './audio.ts';
 import type { NativeBridge } from './bridge.ts';
 import type { NativeCanvas } from './canvas.ts';
 import { errorsOf } from './device.ts';
+import { type FrameCall, runFrames } from './frameLoop.ts';
 import { hostFetch } from './files.ts';
 import { HostGamepads, type JoystickModule, type PadModule } from './gamepads.ts';
 import { installGpu, installLocation } from './globals.ts';
 import { installImages } from './images.ts';
 import { HostPage } from './page.ts';
 import { installThreads } from './threads.ts';
-import { HostWindow } from './window.ts';
+import { HostWindow, type PresentMode } from './window.ts';
 import type { WindowMode } from './windowMode.ts';
 
 export interface HostOptions {
@@ -52,19 +53,17 @@ export interface HostOptions {
   /** `location.search`, for a game that reads its address. */
   readonly query?: string;
   readonly audio?: AudioDefaults;
+  /** How frames reach the screen; `fifo` by default. See `HostWindowOptions.presentMode`. */
+  readonly presentMode?: PresentMode;
 }
 
-export interface FrameCall {
-  /** The page's clock for this frame, in milliseconds. */
-  readonly now: number;
-  /** Frames drawn before this one. */
-  readonly drawn: number;
-}
+export type { FrameCall } from './frameLoop.ts';
 
 export interface RunOptions {
   readonly frames?: number;
   readonly before?: (drawn: number) => void;
-  readonly frame?: (call: FrameCall) => void;
+  /** Draw, or answer with a promise to be waited for when there is nothing to draw: see `runFrames`. */
+  readonly frame?: (call: FrameCall) => void | Promise<void>;
   readonly after?: (call: FrameCall) => void;
 }
 
@@ -76,7 +75,8 @@ export interface NativeHost {
   /**
    * Draw until the window closes, the game asks to quit, or `frames` have been drawn. Each frame
    * calls `before` (where a held clock moves), runs the page's animation frames, calls `frame`,
-   * puts the canvas on the screen and calls `after`. Answers how many were drawn.
+   * lets the microtasks it queued run, puts the canvas on the screen and calls `after`. Answers how
+   * many were drawn.
    */
   run(options?: RunOptions): Promise<number>;
   /** Flush the store and close the window. */
@@ -102,6 +102,7 @@ export function startHost(options: HostOptions): NativeHost {
     hidden: options.hidden === true,
     mode: options.mode,
     resizable: options.resizable,
+    presentMode: options.presentMode,
   });
   installGpu(window.gpu);
   installLocation(options.query ?? '');
@@ -132,27 +133,20 @@ export function startHost(options: HostOptions): NativeHost {
     page,
     canvas: window.canvas,
     bridge,
-    async run(run = {}) {
-      const frames = run.frames ?? Number.POSITIVE_INFINITY;
-      let drawn = 0;
-      while (!window.isClosed && !quitting && drawn < frames) {
-        run.before?.(drawn);
-        const now = performance.now();
-        /* The page's animation frames first, as a browser runs them before it paints. */
-        page.runFrame(now);
-        const context = window.canvas.getContext('webgpu') as GPUCanvasContext;
-        const configuration = context.getConfiguration();
-        const errors = configuration === null ? null : errorsOf(configuration.device);
-        errors?.open();
-        run.frame?.({ now, drawn });
-        window.present();
-        errors?.close();
-        run.after?.({ now, drawn });
-        drawn += 1;
-        /* A task between frames, so SDL's events and the device's callbacks get their turn. */
-        await new Promise((resolve) => setImmediate(resolve));
-      }
-      return drawn;
+    /* In a browser's order, the microtask checkpoint before the present included: see `frameLoop.ts`. */
+    run(run = {}) {
+      return runFrames({
+        ...run,
+        open: () => !window.isClosed && !quitting,
+        clock: () => performance.now(),
+        animationFrames: (now) => page.runFrame(now),
+        errors: () => {
+          const context = window.canvas.getContext('webgpu') as GPUCanvasContext;
+          const configuration = context.getConfiguration();
+          return configuration === null ? null : errorsOf(configuration.device);
+        },
+        present: () => window.present(),
+      });
     },
     async close() {
       bridge.flushSync();

package/src/window.ts

@@ -47,8 +47,22 @@ export interface HostWindowOptions {
   /** As a packaged game's manifest says; windowed and resizable when it says nothing. */
   readonly mode?: WindowMode;
   readonly resizable?: boolean;
+  /**
+   * How a frame reaches the screen: `fifo`, the default, waits for the display's next refresh.
+   *
+   * **Named because the pacing is the compositor's, not the engine's.** The binding renders into
+   * X11 windows only, so a Wayland session runs this through XWayland, and what `fifo` waits for
+   * there differs by window: measured on one session, a hidden window held 58 fps where a visible
+   * one drew a light scene at 250. A caller measuring the engine wants the wait out of the way.
+   * `mailbox` never waits and the display takes the newest frame at its own rate, at the cost of
+   * drawing frames nobody sees; `immediate` also tears.
+   */
+  readonly presentMode?: PresentMode;
 }
 
+/** The binding's swap-chain modes, as `renderGPUDeviceToWindow` takes them. */
+export type PresentMode = 'fifo' | 'fifoRelaxed' | 'immediate' | 'mailbox';
+
 export class HostWindow {
   readonly canvas: NativeCanvas;
   readonly gpu: GPU;
@@ -57,6 +71,7 @@ export class HostWindow {
   private device: GPUDevice | null = null;
   private renderer: WindowRenderer | null = null;
   private presenter: Presenter | null = null;
+  private readonly presentMode: PresentMode;
   private closed = false;
 
   constructor(options: HostWindowOptions) {
@@ -68,6 +83,7 @@ export class HostWindow {
       visible: options.hidden !== true,
       webgpu: true,
     });
+    this.presentMode = options.presentMode ?? 'fifo';
     this.canvas = new NativeCanvas(this.window.pixelWidth, this.window.pixelHeight);
     this.instance = gpuModule.create([]);
     this.gpu = nativeGpu(this.instance as unknown as Parameters<typeof nativeGpu>[0]);
@@ -186,6 +202,7 @@ export class HostWindow {
     this.renderer = gpuModule.renderGPUDeviceToWindow({
       device: device as unknown as DawnDevice,
       window: this.window,
+      presentMode: this.presentMode,
     });
     this.presenter = new Presenter(device, this.renderer.getCurrentTexture().format);
   }