@driftengine/native-host 4.0.0

package/src/dualRumble.ts

@@ -0,0 +1,58 @@
+/**
+ * A pad's `vibrationActuator`, the standard's `dual-rumble` effect, driven through SDL's rumble.
+ *
+ * The strong magnitude drives the low-frequency motor and the weak one the high-frequency motor,
+ * the pair every rumbling pad has. A later effect preempts the one playing, whose promise then
+ * settles `preempted`, as the standard describes; one that runs its course settles `complete`.
+ */
+
+/** What this drives of an SDL pad, a controller's or a joystick's. */
+export interface Rumbler {
+  rumble(low: number, high: number, durationMs: number): void;
+  stopRumble(): void;
+}
+
+export interface DualRumble {
+  readonly type: 'dual-rumble';
+  readonly effects: readonly string[];
+  playEffect(type: string, params: Readonly<Record<string, number>>): Promise<string>;
+  reset(): Promise<string>;
+}
+
+export function dualRumble(motors: Rumbler): DualRumble {
+  let settle: ((result: string) => void) | null = null;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const finish = (result: string): void => {
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+    const settling = settle;
+    settle = null;
+    settling?.(result);
+  };
+  return {
+    type: 'dual-rumble',
+    effects: ['dual-rumble'],
+    playEffect(type, params) {
+      if (type !== 'dual-rumble') {
+        return Promise.reject(new Error(`[driftengine] the native host plays no ${type} effect`));
+      }
+      finish('preempted');
+      const duration = params['duration'] ?? 0;
+      const delay = params['startDelay'] ?? 0;
+      return new Promise((resolve) => {
+        settle = resolve;
+        const start = () => {
+          motors.rumble(params['strongMagnitude'] ?? 0, params['weakMagnitude'] ?? 0, duration);
+          timer = setTimeout(() => finish('complete'), duration);
+        };
+        if (delay > 0) timer = setTimeout(start, delay);
+        else start();
+      });
+    },
+    reset() {
+      finish('preempted');
+      motors.stopRumble();
+      return Promise.resolve('complete');
+    },
+  };
+}

package/src/eventClasses.ts

@@ -0,0 +1,46 @@
+/**
+ * Put the browser's input event classes on the global a page reads them from, where the runtime
+ * has none, and hand back what takes them away again. Node has `Event` and none of these.
+ */
+
+import {
+  FocusEvent,
+  KeyboardEvent,
+  MouseEvent,
+  PointerEvent,
+  UIEvent,
+  WheelEvent,
+} from './uiEvents.ts';
+import { Touch, TouchEvent, TouchList } from './uiTouch.ts';
+
+/** A pad arriving or leaving, as `gamepadconnected` and `gamepaddisconnected` carry it. */
+export class GamepadEvent extends Event {
+  readonly gamepad: unknown;
+  constructor(type: string, init: EventInit & { gamepad: unknown }) {
+    super(type, init);
+    this.gamepad = init.gamepad;
+  }
+}
+
+const CLASSES = {
+  UIEvent,
+  FocusEvent,
+  MouseEvent,
+  WheelEvent,
+  PointerEvent,
+  KeyboardEvent,
+  Touch,
+  TouchList,
+  TouchEvent,
+  GamepadEvent,
+};
+
+export function installEventClasses(
+  scope: Record<string, unknown> = globalThis as Record<string, unknown>,
+): () => void {
+  const added = Object.entries(CLASSES).filter(([name]) => !(name in scope));
+  for (const [name, value] of added) scope[name] = value;
+  return () => {
+    for (const [name] of added) delete scope[name];
+  };
+}

package/src/files.ts

@@ -0,0 +1,61 @@
+/**
+ * The page's own files, answered from disk: the `fetch` a scene calls, under a host.
+ *
+ * **A published scene fetches by a path relative to its page**: the showroom's model, the voxel
+ * sandbox's tiles. A browser resolves that against the server that sent the page, and a host has no
+ * server — so it answers those paths from the directory the dev server serves (`demo/dev/public`),
+ * and a `file:` URL, which is what `new URL(path, import.meta.url)` makes, as the file it names.
+ * Anything carrying a scheme of its own is the network's, and goes to the platform's `fetch`.
+ *
+ * **A missing file is a 404, not a throw**, because that is what the scenes already handle: the
+ * sandbox paints a missing tile magenta, and the showroom asks with `HEAD` whether a model is there.
+ * A path that climbs out of the served directory is a 404 too, as it would be from a server.
+ */
+
+import { readFile, stat } from 'node:fs/promises';
+import { resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+type Fetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+const TYPES: Record<string, string> = {
+  png: 'image/png',
+  json: 'application/json',
+  drft: 'application/octet-stream',
+};
+
+function typeOf(path: string): string {
+  return TYPES[path.slice(path.lastIndexOf('.') + 1).toLowerCase()] ?? 'application/octet-stream';
+}
+
+/** The file a request names, or null where it is the network's or outside what is served. */
+function pathOf(root: string, url: string): string | null {
+  if (url.startsWith('file:')) return fileURLToPath(url);
+  if (/^[a-z][a-z0-9+.-]*:/i.test(url)) return null;
+  const clean = url.split(/[?#]/)[0] ?? '';
+  const path = resolve(root, `.${clean.startsWith('/') ? '' : '/'}${clean}`);
+  const inside = path === root || path.startsWith(root.endsWith(sep) ? root : root + sep);
+  return inside ? path : '';
+}
+
+export function hostFetch(root: string, network: Fetch): Fetch {
+  const served = resolve(root);
+  return async (input, init) => {
+    const url = input instanceof Request ? input.url : String(input);
+    const method = (
+      init?.method ?? (input instanceof Request ? input.method : 'GET')
+    ).toUpperCase();
+    const path = pathOf(served, url);
+    if (path === null) return network(input, init);
+    if (path === '') return new Response(null, { status: 404 });
+    try {
+      const found = await stat(path);
+      if (!found.isFile()) return new Response(null, { status: 404 });
+      const headers = { 'content-type': typeOf(path), 'content-length': String(found.size) };
+      if (method === 'HEAD') return new Response(null, { status: 200, headers });
+      return new Response(await readFile(path), { status: 200, headers });
+    } catch {
+      return new Response(null, { status: 404 });
+    }
+  };
+}

package/src/fullscreen.ts

@@ -0,0 +1,71 @@
+/**
+ * The Fullscreen API over the host's window: `requestFullscreen` on the canvas, `exitFullscreen`
+ * and `fullscreenElement` on the document, and `fullscreenchange` and `fullscreenerror` heard
+ * there, as a page expects them.
+ *
+ * **Chrome's refusals, word for word, measured 2026-09-19 in Chrome 151**: a request with no
+ * gesture is `TypeError: Permissions check failed`, and leaving when nothing is fullscreen is
+ * `TypeError: Failed to execute 'exitFullscreen' on 'Document': Document not active`. A granted
+ * request spends the gesture (`activation.ts`).
+ *
+ * **Element fullscreen is the window's fullscreen.** The canvas fills the window, so the window is
+ * what goes fullscreen, through SDL; and when anything else takes the window out — the shell's
+ * bridge, the window manager, Escape — the element leaves with it and the page is told.
+ *
+ * What it gives up: the change is heard as soon as SDL is asked, rather than on the frame after the
+ * window has been resized, which is when Chrome sends it.
+ */
+
+import type { UserActivation } from './activation.ts';
+import type { NativeCanvas } from './canvas.ts';
+
+export class PageFullscreen {
+  element: NativeCanvas | null = null;
+  /** The platform's half: put the window in fullscreen or take it out, false when it cannot. */
+  setter: ((on: boolean) => boolean) | null = null;
+  /** Told after each change, for what reads it: `(display-mode: fullscreen)`. */
+  changed: () => void = () => undefined;
+
+  constructor(private readonly activation: UserActivation) {}
+
+  request(canvas: NativeCanvas): Promise<void> {
+    if (!this.activation.isActive) {
+      return this.refuse(canvas, new TypeError('Permissions check failed'));
+    }
+    this.activation.consume();
+    if (this.element === canvas) return Promise.resolve();
+    if (this.setter === null || !this.setter(true)) {
+      return this.refuse(canvas, new TypeError('Fullscreen request denied'));
+    }
+    this.element = canvas;
+    canvas.dispatchEvent(new Event('fullscreenchange', { bubbles: true, composed: true }));
+    this.changed();
+    return Promise.resolve();
+  }
+
+  exit(): Promise<void> {
+    const element = this.element;
+    if (element === null) {
+      return Promise.reject(
+        new TypeError("Failed to execute 'exitFullscreen' on 'Document': Document not active"),
+      );
+    }
+    this.setter?.(false);
+    this.lost();
+    return Promise.resolve();
+  }
+
+  /** The window is no longer fullscreen, whoever took it out, so neither is the element. */
+  lost(): void {
+    const element = this.element;
+    if (element === null) return;
+    this.element = null;
+    element.dispatchEvent(new Event('fullscreenchange', { bubbles: true, composed: true }));
+    this.changed();
+  }
+
+  private refuse(canvas: NativeCanvas, error: TypeError): Promise<void> {
+    canvas.dispatchEvent(new Event('fullscreenerror', { bubbles: true, composed: true }));
+    return Promise.reject(error);
+  }
+}

package/src/game.ts

@@ -0,0 +1,53 @@
+/**
+ * A game on the host: the host started, the game's native entry mounted on its canvas, and frames
+ * drawn until the window closes or the game quits.
+ *
+ * **The contract is one export, `mount(canvas)`.** In a browser a game's page finds its canvas in
+ * its own markup; here there is no markup, so the host hands the canvas over. Everything after that
+ * is the game's as it is in a browser: it builds its renderer on the canvas and drives its own loop
+ * with `requestAnimationFrame`, which the host's page runs once a frame before it paints. A game
+ * that already mounts onto a canvas it is given — as the engine's own scenes do — needs a file of a
+ * few lines and nothing else.
+ *
+ * **`startupReport` prints when the first frame reached the screen**, in milliseconds since the
+ * process began, which is how the packaging target's cold start is measured.
+ */
+
+import { type HostOptions, startHost } from './runtime.ts';
+
+/** What a game's native entry exports. */
+export interface GameEntry {
+  mount(canvas: HTMLCanvasElement): unknown;
+}
+
+export interface GameOptions extends HostOptions {
+  /** The game's native entry, imported once the host has started. */
+  readonly load: () => Promise<Partial<GameEntry>>;
+  readonly startupReport?: boolean;
+}
+
+export async function runGame(options: GameOptions): Promise<void> {
+  const host = startHost(options);
+  const entry = await options.load();
+  if (typeof entry.mount !== 'function') {
+    const has = Object.keys(entry).join(', ') || 'nothing';
+    throw new Error(
+      `[driftengine] the game's native entry exports no \`mount(canvas)\`; it exports ${has}`,
+    );
+  }
+  await entry.mount(host.canvas as unknown as HTMLCanvasElement);
+  await host.run({
+    after: ({ drawn }) => {
+      if (options.startupReport === true && drawn === 0) {
+        console.log(`[driftengine] first frame after ${Math.round(performance.now())} ms`);
+      }
+    },
+  });
+  await host.close();
+  /*
+   * **Ended here rather than left to end by itself.** A natural exit runs Dawn's finalizers over
+   * objects the engine has already destroyed, and one of them trips a reference-count assertion
+   * that takes the process down with it (measured 2026-09-18). Nothing is left for them to release.
+   */
+  process.exit(0);
+}

package/src/gamepads.ts

@@ -0,0 +1,195 @@
+/**
+ * Pads, as `navigator.getGamepads()` answers them and as Chrome shows them to a page.
+ *
+ * **The engine polls pads through the browser's API and is not changed for this host.** A
+ * controller SDL knows is the W3C's standard gamepad (`standardPad.ts`); a joystick it has no
+ * mapping for is a pad with none (`rawPad.ts`), which the engine reads as `mapping: 'unknown'` and
+ * by index. Both share Chrome's four slots.
+ *
+ * **Chrome shows a page no pad until a person uses one, and neither does this.** Chromium's rule,
+ * from its source (`device/gamepad/gamepad_user_gesture.cc`) and not measured, since the machine
+ * this was written on has no pad and the DevTools protocol cannot fake one: a button pressed, or an
+ * axis past 0.5, on any pad. Every pad is then shown and announced on the window with
+ * `gamepadconnected`; one arriving later is announced as it arrives, and one leaving with
+ * `gamepaddisconnected` and `connected` false. Before that a page sees four empty slots, which is
+ * what a game saying "press any button" is waiting out.
+ *
+ * **Rumble is SDL's** (`dualRumble.ts`): the first thing this host does that a browser cannot be
+ * relied on for.
+ *
+ * What it gives up: SDL is read when the page asks and every sixtieth of a second otherwise, rather
+ * than on a thread of its own as Chrome reads it.
+ */
+
+import { GamepadEvent } from './eventClasses.ts';
+import { type JoystickDevice, type JoystickInstance, RawPad } from './rawPad.ts';
+import { type PadController, type PadDevice, StandardPad } from './standardPad.ts';
+
+export type { JoystickDevice, JoystickInstance } from './rawPad.ts';
+export type { PadController, PadDevice } from './standardPad.ts';
+
+interface DeviceModule<Device, Opened> {
+  readonly devices: readonly Device[];
+  openDevice(device: Device): Opened;
+  on(event: 'deviceAdd' | 'deviceRemove', listener: (event: { device: Device }) => void): unknown;
+}
+/** SDL's controller module, and its joystick module, as far as this reads them. */
+export type PadModule = DeviceModule<PadDevice, PadController>;
+export type JoystickModule = DeviceModule<JoystickDevice, JoystickInstance>;
+
+export interface GamepadOptions {
+  readonly joysticks?: JoystickModule;
+  /** Where `gamepadconnected` and `gamepaddisconnected` are told: the page's window. */
+  readonly events?: EventTarget;
+  readonly now?: () => number;
+}
+
+type Pad = StandardPad | RawPad;
+const SLOTS = 4;
+/** Chromium's `kAxisMoveAmountThreshold`: an axis past this is a person, not drift. */
+const AXIS_IS_A_PERSON = 0.5;
+const POLL_MS = 1000 / 60;
+
+export class HostGamepads {
+  private readonly slots: (Pad | null)[] = Array.from({ length: SLOTS }, () => null);
+  private readonly empty: null[] = Array.from({ length: SLOTS }, () => null);
+  private shown = false;
+
+  constructor(
+    private readonly controllers: PadModule,
+    private readonly options: GamepadOptions = {},
+  ) {
+    for (const device of controllers.devices) this.addController(device);
+    controllers.on('deviceAdd', ({ device }) => this.addController(device));
+    controllers.on('deviceRemove', ({ device }) => this.remove(device.id, StandardPad));
+    const joysticks = options.joysticks;
+    if (joysticks === undefined) return;
+    for (const device of joysticks.devices) this.addJoystick(joysticks, device);
+    joysticks.on('deviceAdd', ({ device }) => this.addJoystick(joysticks, device));
+    joysticks.on('deviceRemove', ({ device }) => this.remove(device.id, RawPad));
+  }
+
+  /** The four slots, each pad read afresh — or four empty ones, until a person has used a pad. */
+  readonly getGamepads = (): (Pad | null)[] => {
+    this.poll();
+    return this.shown ? this.slots : this.empty;
+  };
+
+  /** Read every pad, and show them all the first time one has been used. */
+  poll(): void {
+    const now = (this.options.now ?? (() => performance.now()))();
+    for (const pad of this.slots) pad?.read(now);
+    if (this.shown || !this.slots.some(used)) return;
+    this.shown = true;
+    for (const pad of this.slots) if (pad !== null) this.announce('gamepadconnected', pad);
+  }
+
+  /** Answer `navigator.getGamepads`, read pads while nothing asks, and hand back what stops both. */
+  install(scope: { navigator?: object } = globalThis as { navigator?: object }): () => void {
+    /* Node has a `navigator` of its own, behind a getter, so it is added to rather than replaced. */
+    if (scope.navigator === undefined) {
+      Object.defineProperty(scope, 'navigator', { value: {}, configurable: true });
+    }
+    const navigator = scope.navigator as object;
+    const had = Object.getOwnPropertyDescriptor(navigator, 'getGamepads');
+    Object.defineProperty(navigator, 'getGamepads', {
+      value: this.getGamepads,
+      configurable: true,
+      writable: true,
+    });
+    const reading = setInterval(() => this.poll(), POLL_MS);
+    reading.unref();
+    return () => {
+      clearInterval(reading);
+      if (had === undefined) delete (navigator as Record<string, unknown>)['getGamepads'];
+      else Object.defineProperty(navigator, 'getGamepads', had);
+    };
+  }
+
+  private addController(device: PadDevice): void {
+    if (this.slotOf(device.id, StandardPad) >= 0) return;
+    /* Listed first as a bare joystick, it is a controller now that SDL has its mapping. */
+    this.remove(device.id, RawPad, false);
+    this.place((at) => new StandardPad(at, this.controllers.openDevice(device)));
+  }
+
+  private addJoystick(joysticks: JoystickModule, device: JoystickDevice): void {
+    /* SDL lists every controller among its joysticks too; that one is shown as a controller. */
+    if (this.controllers.devices.some((controller) => controller.id === device.id)) return;
+    if (this.slotOf(device.id, RawPad) >= 0) return;
+    const source = joysticks.openDevice(device);
+    /*
+     * **A device with nothing to steer by is not a gamepad, whatever SDL lists it among.**
+     *
+     * A keyboard exposes a second HID endpoint for its power and media keys, and SDL enumerates
+     * that among the joysticks: a maintainer's arrived as *"Keychron K8 Pro System Control"*, took
+     * the first pad slot, and the engine warned it could not vouch for the layout while the real
+     * controller sat behind it. Chrome does not offer a keyboard as a gamepad.
+     *
+     * **The rule is what a pad can be steered with**, rather than a name or a vendor, which would
+     * be a list to maintain forever. No axes *and* no hats is nothing a game can read as a
+     * direction — a stick with only buttons still has a hat, which is why it is both and not
+     * either. **What would make this wrong** is a pad whose axes SDL reports as absent until it is
+     * first moved; none seen, and the tell would be a real controller that never appears.
+     */
+    if (source.axes.length === 0 && source.hats.length === 0) {
+      source.close();
+      return;
+    }
+    this.place((at) => new RawPad(at, source));
+  }
+
+  private place(make: (at: number) => Pad): void {
+    const at = this.slots.indexOf(null);
+    if (at < 0) return;
+    const pad = make(at);
+    this.slots[at] = pad;
+    if (this.shown) this.announce('gamepadconnected', pad);
+  }
+
+  private remove(id: number, kind: typeof StandardPad | typeof RawPad, announce = true): void {
+    const at = this.slotOf(id, kind);
+    const pad = this.slots[at];
+    if (pad === undefined || pad === null) return;
+    /*
+     * **A handle the platform has already taken away must not take the process with it.**
+     *
+     * SDL lists every controller among its joysticks too, so a pad arrives first as a bare
+     * joystick and again as a controller once SDL has a mapping for it — and the promotion closes
+     * the joystick handle that SDL has *already* invalidated. Its own `close` then throws
+     * `Cannot read properties of undefined (reading 'delete')` from inside `joystick-instance.js`,
+     * out of the poll callback, and the process ends: a maintainer turned a pad on and the scene
+     * died (`@kmamal/sdl` 0.11.13, Linux, 2026-09-20).
+     *
+     * **What it gives up:** a close that fails for some *other* reason is swallowed too, and a
+     * device handle may leak until the process ends. That is the right trade for a host — after
+     * boot the frame loop never throws — and the slot is freed either way, which is the part the
+     * engine can see.
+     */
+    try {
+      pad.source.close();
+    } catch {
+      /* Already gone. The slot below is what matters. */
+    }
+    pad.connected = false;
+    this.slots[at] = null;
+    if (this.shown && announce) this.announce('gamepaddisconnected', pad);
+  }
+
+  private slotOf(id: number, kind: typeof StandardPad | typeof RawPad): number {
+    return this.slots.findIndex((pad) => pad instanceof kind && pad.source.device.id === id);
+  }
+
+  private announce(type: string, pad: Pad): void {
+    this.options.events?.dispatchEvent(new GamepadEvent(type, { gamepad: pad }));
+  }
+}
+
+/** Whether a person is using `pad`: a button pressed, or an axis past drift. */
+function used(pad: Pad | null): boolean {
+  if (pad === null) return false;
+  return (
+    pad.buttons.some((button) => button.pressed) ||
+    pad.axes.some((axis) => Math.abs(axis) > AXIS_IS_A_PERSON)
+  );
+}

package/src/globals.ts

@@ -0,0 +1,39 @@
+/**
+ * The globals the engine reads, installed by the host before any engine code runs.
+ *
+ * **Every one is a place the engine reaches outside itself**, and the list is short on purpose:
+ * `AGENTS.md` forbids a direct platform call, `scripts/platform.test.mjs` holds that for the
+ * engine's packages, and what is left is the browser's own WebGPU entry point, which the backend
+ * reads as `navigator.gpu` because that is what WebGPU is in a page. A gap Task 3 finds is added
+ * here with the scene that found it, so this file is the host's list of what the engine assumed.
+ */
+
+/**
+ * `navigator.gpu`. Node has a `navigator` of its own (with `hardwareConcurrency`, which the engine's
+ * thread pools read), so the property goes onto it rather than replacing it.
+ */
+export function installGpu(gpu: GPU): void {
+  const scope = globalThis as { navigator?: object };
+  if (scope.navigator === undefined) {
+    Object.defineProperty(globalThis, 'navigator', { value: { gpu }, configurable: true });
+    return;
+  }
+  Object.defineProperty(scope.navigator, 'gpu', { value: gpu, configurable: true });
+}
+
+/**
+ * `location`, with only the query a scene reads its options from.
+ *
+ * **Demo code, not engine code, reads it**: the voxel sandbox, the showroom, the day clock and the
+ * city each take their options from the page's address (`?radius=`, `?exposure=`, `?at=`), which
+ * is how the dev harness and a capture hold a scene still. The engine's own read, in
+ * `createRenderer`, is already optional. A host passes the same query a browser capture would, so
+ * the two draw the same scene.
+ */
+export function installLocation(search: string): void {
+  const query = search === '' || search.startsWith('?') ? search : `?${search}`;
+  Object.defineProperty(globalThis, 'location', {
+    value: { search: query, href: `native://host/${query}`, pathname: '/' },
+    configurable: true,
+  });
+}

package/src/gpu.ts

@@ -0,0 +1,59 @@
+/**
+ * `navigator.gpu` for a host with no browser: Dawn's instance, answering as the browser does.
+ *
+ * **The engine is not told it is on a host.** Its WebGPU backend asks `navigator.gpu` for an
+ * adapter and for the format a canvas prefers, and nothing else; this answers both from Dawn, the
+ * implementation inside Chrome, so the device the engine gets is the one it would have been given
+ * in a browser on the same machine.
+ */
+
+import { adaptDevice } from './device.ts';
+
+/**
+ * The format a canvas prefers, answered as Chrome answers it on this machine.
+ *
+ * **The engine builds every pipeline that writes the frame against this answer**, and Dawn's own
+ * instance says `bgra8unorm` where Chrome says `rgba8unorm`. The host owns the texture the frame
+ * lands in, so it can answer either; it answers the browser's, and the two hosts build the same
+ * pipelines. What it gives up: on a machine where Chrome prefers `bgra8unorm` the two hosts
+ * differ in channel order, which is the same picture and a different pipeline key.
+ */
+export const PREFERRED_FORMAT: GPUTextureFormat = 'rgba8unorm';
+
+/** What this needs from Dawn's instance: the adapter request, and nothing it says about canvases. */
+export interface DawnInstance {
+  requestAdapter(options?: GPURequestAdapterOptions): Promise<GPUAdapter | null>;
+  getPreferredCanvasFormat?(): GPUTextureFormat;
+  readonly wgslLanguageFeatures?: WGSLLanguageFeatures;
+}
+
+/**
+ * The adapter the engine is handed, whose devices come out adapted: see `device.ts`. A proxy rather
+ * than a patch, because the adapter is the binding's object and its other members are read as they
+ * are.
+ */
+function hostAdapter(adapter: GPUAdapter): GPUAdapter {
+  return new Proxy(adapter, {
+    get(target, key) {
+      if (key === 'requestDevice') {
+        return async (descriptor?: GPUDeviceDescriptor) =>
+          adaptDevice(await target.requestDevice(descriptor));
+      }
+      const value: unknown = Reflect.get(target, key, target);
+      return typeof value === 'function' ? (value as () => unknown).bind(target) : value;
+    },
+  });
+}
+
+/** The object a host installs as `navigator.gpu`. */
+export function nativeGpu(instance: DawnInstance): GPU {
+  const gpu = {
+    requestAdapter: async (options?: GPURequestAdapterOptions) => {
+      const adapter = await instance.requestAdapter(options);
+      return adapter === null ? null : hostAdapter(adapter);
+    },
+    getPreferredCanvasFormat: (): GPUTextureFormat => PREFERRED_FORMAT,
+    wgslLanguageFeatures: instance.wgslLanguageFeatures ?? new Set<string>(),
+  };
+  return gpu as unknown as GPU;
+}