@driftengine/native-host 4.0.0

package/src/images.ts

@@ -0,0 +1,148 @@
+/**
+ * `createImageBitmap`, for a host with no browser to decode an image.
+ *
+ * **A scene's images reach the engine through it**: a model's textures are PNG and JPEG bytes the
+ * loader hands to `createImageBitmap`, and the bitmap it gets back goes to the device through
+ * `copyExternalImageToTexture`. Node has neither, so the host decodes, and its queue (see
+ * `device.ts`) writes a host bitmap's bytes where the browser would have copied an image.
+ *
+ * **The decoders are chosen to give Chrome's bytes.** PNG is lossless, so this repository's own
+ * decoder (`packages/core/scripts/png.mjs`) gives them by definition. JPEG goes through
+ * `@jsquash/jpeg`, MozJPEG compiled to WebAssembly — libjpeg-turbo, the decoder Chrome uses — which
+ * decodes the showroom car's five JPEG textures to Chrome's bytes exactly: 0 of 6.07 million pixels,
+ * measured 2026-09-19 against `createImageBitmap` in Chrome on the same bytes. A JavaScript JPEG
+ * decoder was the alternative and would have differed, because the inverse transform is not
+ * specified to the bit.
+ *
+ * What it gives up: WebP is not decoded (no scene the host runs needs it yet, and it is refused by
+ * name), and a resized decode is declined — see `hostCreateImageBitmap`.
+ */
+
+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';
+
+/** What a host hands back for an image: its size and four bytes a pixel, top row first. */
+export interface HostBitmap {
+  readonly width: number;
+  readonly height: number;
+  /** Straight alpha, as decoded. */
+  readonly data: Uint8ClampedArray;
+  /**
+   * Whether a browser would be holding this premultiplied, which it does unless asked not to
+   * (`premultiplyAlpha: 'none'`). The data stays straight; the queue does what Chrome's copy does
+   * with a premultiplied image (see `device.ts`), so a transparent texel's colour is lost where
+   * Chrome loses it.
+   */
+  readonly premultiplied: boolean;
+  close(): void;
+}
+
+const HOST_BITMAP = Symbol('driftengine host bitmap');
+
+export function isHostBitmap(value: unknown): value is HostBitmap {
+  return typeof value === 'object' && value !== null && HOST_BITMAP in value;
+}
+
+function bitmap(
+  width: number,
+  height: number,
+  data: Uint8ClampedArray,
+  premultiplied: boolean,
+): HostBitmap {
+  return {
+    width,
+    height,
+    data,
+    premultiplied,
+    close: () => undefined,
+    [HOST_BITMAP]: true,
+  } 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. */
+function readyJpeg(): Promise<void> {
+  if (jpegReady === null) {
+    const wasm = createRequire(import.meta.url).resolve('@jsquash/jpeg/codec/dec/mozjpeg_dec.wasm');
+    jpegReady = WebAssembly.compile(readFileSync(wasm)).then((module) => initJpeg(module));
+  }
+  return jpegReady;
+}
+
+/**
+ * Decode a blob or take `ImageData` as it is.
+ *
+ * **Decoded straight, with no colour conversion**, which is what the engine asks for where it asks
+ * (`premultiplyAlpha: 'none'`, `colorSpaceConversion: 'none'`). Where it does not ask, a browser
+ * holds the image premultiplied, and the bitmap says so for the copy to act on. **A resized decode is declined by name**: the model loader asks
+ * for a small preview before the sharp image and drops it if it fails, and a preview resampled by
+ * another filter than Chrome's would put a picture on the screen that no browser drew.
+ */
+export async function hostCreateImageBitmap(
+  source: Blob | ImageData,
+  options: ImageBitmapOptions = {},
+): Promise<HostBitmap> {
+  if (options.resizeWidth !== undefined || options.resizeHeight !== undefined) {
+    throw new Error('[driftengine] the native host does not resample while it decodes');
+  }
+  const premultiplied = options.premultiplyAlpha !== 'none';
+  if (!(source instanceof Blob)) {
+    return bitmap(source.width, source.height, new Uint8ClampedArray(source.data), premultiplied);
+  }
+  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);
+    return bitmap(png.width, png.height, pixels, premultiplied);
+  }
+  if (source.type === 'image/jpeg') {
+    await readyJpeg();
+    const image = await decodeJpeg(bytes.buffer);
+    return bitmap(image.width, image.height, new Uint8ClampedArray(image.data), premultiplied);
+  }
+  throw new Error(
+    `[driftengine] the native host cannot decode ${source.type || 'an untyped blob'}`,
+  );
+}
+
+/**
+ * The image globals a scene reads: `createImageBitmap`, and `ImageData`, which Node lacks and which
+ * both the model loader and MozJPEG's module construct.
+ */
+export function installImages(): void {
+  const scope = globalThis as Record<string, unknown>;
+  scope['createImageBitmap'] = hostCreateImageBitmap;
+  if (scope['ImageData'] === undefined) {
+    scope['ImageData'] = class {
+      readonly data: Uint8ClampedArray;
+      readonly width: number;
+      readonly height: number;
+      constructor(data: Uint8ClampedArray, width: number, height: number) {
+        this.data = data;
+        this.width = width;
+        this.height = height;
+      }
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * The engine on a native window and a native WebGPU device: Node, Dawn and SDL, with no browser
+ * between them.
+ *
+ * **Two calls are the whole surface.** `runGame` is what a packaged game's generated entry calls:
+ * it starts the host, mounts the game's native entry on the canvas, and draws until the window
+ * closes. `startHost` is the same start without a game, for a tool that drives its own frames —
+ * the engine repository's scene runner and editor runner are two.
+ *
+ * Everything a page reads around the canvas — events, pointer lock, fullscreen, gamepads, audio,
+ * storage — the host installs as a browser would have it, so the engine and the game run unchanged.
+ * The modules that do it are in `src/` and are private.
+ *
+ * **One capability a page has no equivalent of is offered as well**: `tileFiles`, the texture
+ * streamer's tiles read from a directory on disk, for a game's native entry to hand its streamer
+ * where a page would fetch them over HTTP.
+ */
+
+export { runGame } from './game.ts';
+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';

package/src/keyCodes.ts

@@ -0,0 +1,203 @@
+/**
+ * A key, named as a browser names it, from the scancode SDL reports.
+ *
+ * **`code` is the name that matters**: the engine binds by it and so does every game on it, because
+ * it names a key's position rather than what the layout prints on it. SDL's scancode is the USB
+ * keyboard usage for that position, and the W3C table of codes is written against the same usages,
+ * so the two meet by number. `key` is what the key types, which a text field wants and a game
+ * mostly does not.
+ *
+ * What it gives up: keys a game does not bind — media keys, the international keys beyond the ISO
+ * backslash, a keypad's rarer members — have no `code` here and arrive as `Unidentified` rather
+ * than as a guess. Usage 0x32, the ISO hash key most boards report as 0x31 anyway, is one of them.
+ */
+
+const CODES = new Map<number, string>();
+for (let at = 0; at < 26; at += 1) CODES.set(4 + at, `Key${String.fromCharCode(65 + at)}`);
+for (let at = 0; at < 9; at += 1) CODES.set(30 + at, `Digit${at + 1}`);
+CODES.set(39, 'Digit0');
+for (let at = 0; at < 12; at += 1) CODES.set(58 + at, `F${at + 1}`);
+for (let at = 0; at < 9; at += 1) CODES.set(89 + at, `Numpad${at + 1}`);
+for (const [usage, code] of [
+  [40, 'Enter'],
+  [41, 'Escape'],
+  [42, 'Backspace'],
+  [43, 'Tab'],
+  [44, 'Space'],
+  [45, 'Minus'],
+  [46, 'Equal'],
+  [47, 'BracketLeft'],
+  [48, 'BracketRight'],
+  [49, 'Backslash'],
+  [51, 'Semicolon'],
+  [52, 'Quote'],
+  [53, 'Backquote'],
+  [54, 'Comma'],
+  [55, 'Period'],
+  [56, 'Slash'],
+  [57, 'CapsLock'],
+  [70, 'PrintScreen'],
+  [71, 'ScrollLock'],
+  [72, 'Pause'],
+  [73, 'Insert'],
+  [74, 'Home'],
+  [75, 'PageUp'],
+  [76, 'Delete'],
+  [77, 'End'],
+  [78, 'PageDown'],
+  [79, 'ArrowRight'],
+  [80, 'ArrowLeft'],
+  [81, 'ArrowDown'],
+  [82, 'ArrowUp'],
+  [83, 'NumLock'],
+  [84, 'NumpadDivide'],
+  [85, 'NumpadMultiply'],
+  [86, 'NumpadSubtract'],
+  [87, 'NumpadAdd'],
+  [88, 'NumpadEnter'],
+  [98, 'Numpad0'],
+  [99, 'NumpadDecimal'],
+  [100, 'IntlBackslash'],
+  [101, 'ContextMenu'],
+  [103, 'NumpadEqual'],
+  [224, 'ControlLeft'],
+  [225, 'ShiftLeft'],
+  [226, 'AltLeft'],
+  [227, 'MetaLeft'],
+  [228, 'ControlRight'],
+  [229, 'ShiftRight'],
+  [230, 'AltRight'],
+  [231, 'MetaRight'],
+] as const) {
+  CODES.set(usage, code);
+}
+
+/** `KeyboardEvent.key` for the keys that type nothing, by position. */
+const NAMED = new Map<number, string>([
+  [40, 'Enter'],
+  [88, 'Enter'],
+  [41, 'Escape'],
+  [42, 'Backspace'],
+  [43, 'Tab'],
+  [44, ' '],
+  [57, 'CapsLock'],
+  [70, 'PrintScreen'],
+  [71, 'ScrollLock'],
+  [72, 'Pause'],
+  [73, 'Insert'],
+  [74, 'Home'],
+  [75, 'PageUp'],
+  [76, 'Delete'],
+  [77, 'End'],
+  [78, 'PageDown'],
+  [79, 'ArrowRight'],
+  [80, 'ArrowLeft'],
+  [81, 'ArrowDown'],
+  [82, 'ArrowUp'],
+  [83, 'NumLock'],
+  [101, 'ContextMenu'],
+  [224, 'Control'],
+  [228, 'Control'],
+  [225, 'Shift'],
+  [229, 'Shift'],
+  [226, 'Alt'],
+  [230, 'Alt'],
+  [227, 'Meta'],
+  [231, 'Meta'],
+]);
+for (let at = 0; at < 12; at += 1) NAMED.set(58 + at, `F${at + 1}`);
+
+/** The position's name, or null for one this table does not name. */
+export function codeOf(scancode: number): string | null {
+  return CODES.get(scancode) ?? null;
+}
+
+/**
+ * What the key types, from SDL's name for it: the character, shifted where it is a letter and
+ * shift is held, or the browser's name for a key that types nothing.
+ */
+export function keyOf(key: string | null, scancode: number, shifted: boolean): string {
+  if (key !== null && key.length === 1) {
+    return shifted && key >= 'a' && key <= 'z' ? key.toUpperCase() : key;
+  }
+  return NAMED.get(scancode) ?? 'Unidentified';
+}
+
+/**
+ * The legacy `keyCode` a browser still sends on `keydown` and `keyup`: the Windows virtual-key code
+ * for the position, which Chrome sends on every platform.
+ */
+const LEGACY = new Map<string, number>([
+  ['Backspace', 8],
+  ['Tab', 9],
+  ['Enter', 13],
+  ['NumpadEnter', 13],
+  ['ShiftLeft', 16],
+  ['ShiftRight', 16],
+  ['ControlLeft', 17],
+  ['ControlRight', 17],
+  ['AltLeft', 18],
+  ['AltRight', 18],
+  ['Pause', 19],
+  ['CapsLock', 20],
+  ['Escape', 27],
+  ['Space', 32],
+  ['PageUp', 33],
+  ['PageDown', 34],
+  ['End', 35],
+  ['Home', 36],
+  ['ArrowLeft', 37],
+  ['ArrowUp', 38],
+  ['ArrowRight', 39],
+  ['ArrowDown', 40],
+  ['PrintScreen', 44],
+  ['Insert', 45],
+  ['Delete', 46],
+  ['MetaLeft', 91],
+  ['MetaRight', 92],
+  ['ContextMenu', 93],
+  ['NumpadMultiply', 106],
+  ['NumpadAdd', 107],
+  ['NumpadSubtract', 109],
+  ['NumpadDecimal', 110],
+  ['NumpadDivide', 111],
+  ['NumLock', 144],
+  ['ScrollLock', 145],
+  ['Semicolon', 186],
+  ['Equal', 187],
+  ['Comma', 188],
+  ['Minus', 189],
+  ['Period', 190],
+  ['Slash', 191],
+  ['Backquote', 192],
+  ['BracketLeft', 219],
+  ['Backslash', 220],
+  ['BracketRight', 221],
+  ['Quote', 222],
+  ['IntlBackslash', 226],
+]);
+for (let at = 0; at < 10; at += 1) {
+  LEGACY.set(`Digit${at}`, 48 + at);
+  LEGACY.set(`Numpad${at}`, 96 + at);
+}
+for (let at = 0; at < 24; at += 1) LEGACY.set(`F${at + 1}`, 112 + at);
+
+/**
+ * `keyCode` for a key down or up. A letter key's is the letter the layout puts there, as Chrome's
+ * is — `KeyQ` on an AZERTY board types `a` and reports 65 — and every other key's is its position's.
+ */
+export function legacyKeyCode(code: string, key: string): number {
+  if (/^[a-z]$/i.test(key)) return key.toUpperCase().charCodeAt(0);
+  if (/^Key[A-Z]$/.test(code)) return code.charCodeAt(3);
+  return LEGACY.get(code) ?? 0;
+}
+
+/**
+ * Which of the four locations a key is in: 1 and 2 for a modifier's two sides, 3 for the keypad.
+ * Only the modifiers have sides — `BracketLeft` and `ArrowLeft` are standard keys.
+ */
+export function keyLocation(code: string): number {
+  const side = /^(?:Shift|Control|Alt|Meta)(Left|Right)$/.exec(code)?.[1];
+  if (side !== undefined) return side === 'Left' ? 1 : 2;
+  return code.startsWith('Numpad') ? 3 : 0;
+}

package/src/keyEvents.ts

@@ -0,0 +1,135 @@
+/**
+ * Keys, as a page hears them: `keydown`, `keypress` and `keyup`, each a `KeyboardEvent` carrying
+ * the `code`, the `key`, the location and the legacy codes Chrome sends.
+ *
+ * **A key down waits for its character.** SDL reports a key and the text it typed as two events,
+ * the key first, and the text is the layout's answer to what was typed: `!` for shift and 1 on a US
+ * board, `é` through a dead key. That is what a browser puts in `key`, and what a `keypress`
+ * carries. Both arrive in one drain of SDL's queue, so a key down is held until its text, the next
+ * event of any other kind, or the end of that drain, whichever is first — never across a frame.
+ *
+ * **A `keypress` is sent only for a key that typed something**, and for Enter, which SDL types
+ * nothing for and Chrome gives a carriage return; a key down a listener prevented sends none, as in
+ * Chrome. Ctrl with a letter types nothing in SDL either, which is Chrome's rule too.
+ *
+ * What it gives up: a key that composes, through an input method, reports what it composed to the
+ * text host alone (`textHost.ts`), and its key down names the key SDL saw; and with Ctrl held, a
+ * shifted symbol's `key` is the unshifted one, since no text says otherwise.
+ */
+
+import { codeOf, keyLocation, keyOf, legacyKeyCode } from './keyCodes.ts';
+import { KeyboardEvent, type ModifierInit } from './uiEvents.ts';
+
+export interface SdlKey {
+  readonly scancode: number;
+  readonly key: string | null;
+  /**
+   * Whether this key is an auto-repeat. **A number by SDL's declaration and not always by its
+   * behaviour**, so both shapes are accepted and `isRepeat` decides; see its note.
+   */
+  readonly repeat?: number | boolean;
+  readonly shift: number;
+  readonly ctrl: number;
+  readonly alt: number;
+  readonly super: number;
+  readonly altgr?: number;
+  readonly capslock?: number;
+  readonly numlock?: number;
+}
+
+/** The modifiers an SDL key event reports, as a browser's event carries them. */
+export function modifiersOf(event: SdlKey): ModifierInit {
+  return {
+    shiftKey: event.shift !== 0,
+    ctrlKey: event.ctrl !== 0,
+    altKey: event.alt !== 0,
+    metaKey: event.super !== 0,
+    modifierAltGraph: (event.altgr ?? 0) !== 0,
+    modifierCapsLock: (event.capslock ?? 0) !== 0,
+    modifierNumLock: (event.numlock ?? 0) !== 0,
+  };
+}
+
+export class KeyEvents {
+  private pending: { readonly event: SdlKey; text: string | null } | null = null;
+
+  /**
+   * `target` is where a key goes: the focused element, or the document with nothing focused.
+   * `activate` is told of each key down but Escape, a person's gesture as a browser counts one.
+   */
+  constructor(
+    private readonly target: () => EventTarget,
+    private readonly activate: () => void = () => undefined,
+  ) {}
+
+  down(event: SdlKey): void {
+    this.flush();
+    this.pending = { event, text: null };
+    queueMicrotask(() => this.flush());
+  }
+
+  /** A key's character, or a composition's, which is the text host's and not a key's. */
+  text(text: string): void {
+    const pending = this.pending;
+    if (pending === null) return;
+    if ([...text].length === 1) pending.text = text;
+    this.flush();
+  }
+
+  up(event: SdlKey): void {
+    this.flush();
+    const key = keyOf(event.key, event.scancode, event.shift !== 0);
+    this.send('keyup', event, key, 0);
+  }
+
+  /** Send the key down being held, and its `keypress` if it typed. */
+  flush(): void {
+    const pending = this.pending;
+    if (pending === null) return;
+    this.pending = null;
+    const { event, text } = pending;
+    const key = text ?? keyOf(event.key, event.scancode, event.shift !== 0);
+    if (key !== 'Escape') this.activate();
+    const down = this.send('keydown', event, key, 0);
+    if (down.defaultPrevented) return;
+    const typed = text ?? (key === 'Enter' ? '\r' : null);
+    if (typed !== null) this.send('keypress', event, key, typed.codePointAt(0) ?? 0);
+  }
+
+  private send(type: string, event: SdlKey, key: string, charCode: number): KeyboardEvent {
+    const code = codeOf(event.scancode) ?? '';
+    const sent = new KeyboardEvent(type, {
+      bubbles: true,
+      cancelable: true,
+      key,
+      code,
+      location: keyLocation(code),
+      repeat: isRepeat(event.repeat),
+      keyCode: charCode !== 0 ? charCode : legacyKeyCode(code, key),
+      charCode,
+      detail: 0,
+      ...modifiersOf(event),
+    });
+    this.target().dispatchEvent(sent);
+    return sent;
+  }
+}
+
+/**
+ * Whether the platform is calling this key a repeat, for either shape it might say it in.
+ *
+ * **`(repeat ?? 0) !== 0` was inverted for a boolean**, and that is the whole of a bug that made
+ * the engine deaf to held keys: `false !== 0` is `true`, so a platform answering `repeat: false`
+ * marked *every* press a repeat, and `InputSource` discards a repeat outright so that a held key
+ * cannot re-fire a press. Taps handled on the edge — a hotbar digit — kept working, which is what
+ * made it so hard to see: the keyboard was plainly delivering keys and the player would not walk.
+ *
+ * SDL's own types declare a number and this took the declaration at its word. **A number is what it
+ * promises and not what it was giving**, which is why this reads the value rather than its type:
+ * anything positive, or `true`, is a repeat, and everything else — `0`, `false`, absent — is a
+ * first press.
+ */
+function isRepeat(repeat: number | boolean | undefined): boolean {
+  if (typeof repeat === 'boolean') return repeat;
+  return typeof repeat === 'number' && repeat > 0;
+}

package/src/mediaQueries.ts

@@ -0,0 +1,173 @@
+/**
+ * `matchMedia`, answered from what this host knows: a desktop window's pointer, its size and
+ * shape, its pixel ratio, and whether it is fullscreen.
+ *
+ * **The engine asks `(pointer: coarse)`** to choose touch controls and to ask for fullscreen on a
+ * first gesture, and a window with no `matchMedia` at all read as a desktop only because the engine
+ * guards the call. A consumer may ask anything, so the common features are answered:
+ * - `pointer` and `hover` as a desktop's mouse, `fine` and `hover`. `any-pointer` adds `coarse`
+ *   once a finger has landed, because SDL cannot say whether a touch screen exists — on the machine
+ *   this was written on it listed X11's master pointer, "Virtual core pointer", as one.
+ * - `width`, `height` and `orientation` from the window, in either spelling of a range;
+ *   `resolution` from its pixel ratio.
+ * - `display-mode` as `fullscreen` or `standalone`, the display mode of an app's own window.
+ * - Preferences as a person who set none: `prefers-reduced-motion: no-preference`,
+ *   `prefers-color-scheme: light`, `prefers-contrast: no-preference`, `forced-colors: none`.
+ *
+ * A list is live, as a browser's is, and is sent `change` when its answer flips. **A feature this
+ * does not know answers false and is named once on the console**, rather than a guess at what a
+ * browser would have said.
+ *
+ * What it gives up: a desktop's colour scheme is not read, so a dark desktop still answers
+ * `light`; and a machine with only a touch screen answers as one with a mouse until told
+ * otherwise.
+ */
+
+import { HostNode } from './domTree.ts';
+
+export interface MediaFacts {
+  /** The viewport, in CSS pixels. */
+  readonly width: number;
+  readonly height: number;
+  readonly pixelRatio: number;
+  readonly fullscreen: boolean;
+  /** Whether a finger has landed, which is the one proof of a touch screen SDL gives. */
+  readonly touched: boolean;
+}
+
+type Feature = (value: string | null, facts: MediaFacts) => boolean;
+
+const is = (answer: string) => (value: string | null) => value === null || value === answer;
+const px = (value: string) => Number.parseFloat(value);
+const dppx = (value: string) =>
+  value.endsWith('dpi') ? Number.parseFloat(value) / 96 : Number.parseFloat(value);
+
+const FEATURES: Record<string, Feature> = {
+  pointer: is('fine'),
+  'any-pointer': (v, f) => v === null || v === 'fine' || (v === 'coarse' && f.touched),
+  hover: is('hover'),
+  'any-hover': is('hover'),
+  orientation: (v, f) => v === (f.height >= f.width ? 'portrait' : 'landscape'),
+  width: (v, f) => v === null || f.width === px(v),
+  'min-width': (v, f) => v !== null && f.width >= px(v),
+  'max-width': (v, f) => v !== null && f.width <= px(v),
+  height: (v, f) => v === null || f.height === px(v),
+  'min-height': (v, f) => v !== null && f.height >= px(v),
+  'max-height': (v, f) => v !== null && f.height <= px(v),
+  'min-resolution': (v, f) => v !== null && f.pixelRatio >= dppx(v),
+  'max-resolution': (v, f) => v !== null && f.pixelRatio <= dppx(v),
+  'display-mode': (v, f) => v === (f.fullscreen ? 'fullscreen' : 'standalone'),
+  'prefers-reduced-motion': (v) => v === 'no-preference',
+  'prefers-color-scheme': (v) => v === 'light',
+  'prefers-contrast': (v) => v === 'no-preference',
+  'forced-colors': (v) => v === 'none',
+  color: () => true,
+};
+
+/** `(width >= 600px)` and its kin, the range spelling, as the equivalent `min-` or `max-`. */
+function range(condition: string): [string, string] | null {
+  const match = /^(width|height)\s*(>=|<=|>|<)\s*(\S+)$/.exec(condition);
+  if (match === null) return null;
+  const [, name, op, value] = match as unknown as [string, string, string, string];
+  const nudge = op === '>' ? 0.001 : op === '<' ? -0.001 : 0;
+  const bound = `${px(value) + nudge}px`;
+  return [op.startsWith('>') ? `min-${name}` : `max-${name}`, bound];
+}
+
+/** `pointer: coarse` as its name and value; a bare `color` has no value. */
+function nameAndValue(condition: string): [string, string | null] {
+  const colon = condition.indexOf(':');
+  if (colon < 0) return [condition, null];
+  return [condition.slice(0, colon).trim(), condition.slice(colon + 1).trim()];
+}
+
+export class MediaQueryList extends HostNode {
+  private last: boolean;
+  constructor(
+    readonly media: string,
+    private readonly answer: () => boolean,
+  ) {
+    super();
+    this.last = answer();
+  }
+  get matches(): boolean {
+    return this.answer();
+  }
+  /** The legacy pair, still read. */
+  addListener(listener: (event: Event) => void): void {
+    this.addEventListener('change', listener);
+  }
+  removeListener(listener: (event: Event) => void): void {
+    this.removeEventListener('change', listener);
+  }
+  /** Tell the list's listeners if its answer has flipped since they were last told. */
+  recheck(): void {
+    const now = this.answer();
+    if (now === this.last) return;
+    this.last = now;
+    this.dispatchEvent(Object.assign(new Event('change'), { media: this.media, matches: now }));
+  }
+  static {
+    HostNode.handles(MediaQueryList.prototype, ['change']);
+  }
+}
+
+export interface MediaQueryList {
+  onchange: ((event: Event) => unknown) | null;
+}
+
+export class MediaQueries {
+  private readonly lists: MediaQueryList[] = [];
+  private readonly unknown = new Set<string>();
+
+  constructor(private readonly facts: () => MediaFacts) {}
+
+  match(query: string): MediaQueryList {
+    const list = new MediaQueryList(query.trim(), () => this.evaluate(query));
+    this.lists.push(list);
+    return list;
+  }
+
+  /** Something a query can read has changed: each list whose answer flipped is told. */
+  changed(): void {
+    for (const list of this.lists) list.recheck();
+  }
+
+  private evaluate(query: string): boolean {
+    const facts = this.facts();
+    return query.split(',').some((one) => this.single(one.trim().toLowerCase(), facts));
+  }
+
+  /** One query of a list: `not` or `only`, a media type, and conditions joined by `and`. */
+  private single(query: string, facts: MediaFacts): boolean {
+    let rest = query;
+    const negated = rest.startsWith('not ');
+    if (negated || rest.startsWith('only ')) rest = rest.slice(rest.indexOf(' ') + 1).trim();
+    const parts = rest.split(/\s+and\s+/);
+    let result = true;
+    for (const part of parts) {
+      if (part === 'all' || part === 'screen') continue;
+      if (!part.startsWith('(') || !part.endsWith(')')) {
+        result = false;
+        continue;
+      }
+      if (!this.condition(part.slice(1, -1).trim(), facts)) result = false;
+    }
+    return negated ? !result : result;
+  }
+
+  private condition(condition: string, facts: MediaFacts): boolean {
+    const [name, value] = range(condition) ?? nameAndValue(condition);
+    const feature = FEATURES[name];
+    if (feature === undefined) {
+      if (!this.unknown.has(name)) {
+        this.unknown.add(name);
+        console.warn(
+          `[driftengine] the native host does not answer the media feature \`${name}\`; it reads as false`,
+        );
+      }
+      return false;
+    }
+    return feature(value, facts);
+  }
+}