@driftengine/native-host 4.0.0

package/src/device.ts

@@ -0,0 +1,167 @@
+/**
+ * The device, made to say what it rejected, when its binding will not.
+ *
+ * **The engine hears one thing from its device**: `uncapturederror`, which its surface turns into a
+ * line naming what the GPU refused — the only warning a WebGPU frame gets that it drew nothing.
+ * `@kmamal/gpu` 0.2.0 refuses that listener ("no overload matched for addEventListener") and will not
+ * take an `onuncapturederror` either (measured 2026-09-18). Error scopes work, so the host opens one
+ * around each frame and hands whatever it caught to the listeners the engine registered: the same
+ * message, at the end of the frame that caused it, which is when a browser raises it too.
+ *
+ * **Detected, not assumed.** A device whose binding takes the listener is left exactly as it is, so a
+ * later binding that delivers its own events costs nothing here.
+ *
+ * What it gives up: an error from work outside a frame — a pipeline built at mount — is only caught
+ * if the host has a scope open at the time. Dawn still prints every validation error to the
+ * terminal itself, so none is silent.
+ */
+
+import { AlphaCopier } from './alphaCopy.ts';
+import type { AlphaStep } from './alphaCopy.ts';
+import { isHostBitmap } from './images.ts';
+
+export interface FrameErrors {
+  /** Before the frame: catch what it does. */
+  open(): void;
+  /** After it: hand anything caught to the engine's listeners. */
+  close(): void;
+}
+
+const adapted = new WeakMap<GPUDevice, FrameErrors>();
+
+/** The frame's error scopes for a device this host adapted, or `null` for one it left alone. */
+export function errorsOf(device: GPUDevice): FrameErrors | null {
+  return adapted.get(device) ?? null;
+}
+
+/** Skia's premultiply, the integer rounding Chrome's image decoders use. */
+export function premultiplied(straight: Uint8Array): Uint8Array {
+  const out = new Uint8Array(straight.length);
+  for (let at = 0; at < straight.length; at += 4) {
+    const alpha = straight[at + 3] as number;
+    out[at + 3] = alpha;
+    for (let channel = 0; channel < 3; channel += 1) {
+      out[at + channel] = (((straight[at + channel] as number) * alpha + 128) * 257) >> 16;
+    }
+  }
+  return out;
+}
+
+/**
+ * The step a copy takes between the alpha an image is held in and the alpha its texture wants, or
+ * null where the two agree and a browser copies the bytes as they are.
+ */
+export function alphaStepFor(held: boolean, wanted: boolean): AlphaStep | null {
+  if (held === wanted) return null;
+  return held ? 'unpremultiply' : 'premultiply';
+}
+
+/**
+ * The queue, taking an image the host decoded where a browser would take one it decoded.
+ *
+ * **The engine puts a decoded image on the device with `copyExternalImageToTexture`**, and a browser
+ * copies from its own image there. A host's image is a `HostBitmap` from `images.ts`, four bytes a
+ * pixel that Dawn's binding cannot read as an image, so it is copied the way Chrome copies one:
+ *
+ * - **held as the texture wants it**, the bytes go in with `writeTexture`. Straight or
+ *   premultiplied, into a plain or an sRGB texture, Chrome writes exactly these (measured);
+ * - **held one way and wanted the other**, `alphaCopy.ts` runs the step on the device.
+ *
+ * A browser holds a decoded image premultiplied unless told `premultiplyAlpha: 'none'`, with Skia's
+ * integer rounding, so that is how the bytes are held here. A browser flips rows only when asked,
+ * and so does this. Any other source goes to the binding.
+ */
+function adaptQueue(device: GPUDevice): void {
+  const queue = device.queue as GPUQueue | undefined;
+  if (queue === undefined) return;
+  const original = queue.copyExternalImageToTexture.bind(queue);
+  const copier = new AlphaCopier(device);
+  queue.copyExternalImageToTexture = (source, destination, copySize) => {
+    /* A size may be any iterable of numbers or a dictionary; one shape, for both uses below. */
+    const size: GPUExtent3D =
+      Symbol.iterator in Object(copySize)
+        ? Array.from(copySize as Iterable<number>)
+        : (copySize as GPUExtent3DDict);
+    const image: unknown = source.source;
+    if (!isHostBitmap(image)) {
+      original(source, destination, size);
+      return;
+    }
+    const from = source.origin as GPUOrigin2DDict | undefined;
+    if ((from?.x ?? 0) !== 0 || (from?.y ?? 0) !== 0) {
+      throw new Error(
+        '[driftengine] the native host copies a whole image, from its top-left corner',
+      );
+    }
+    const row = image.width * 4;
+    const straight = new Uint8Array(
+      image.data.buffer,
+      image.data.byteOffset,
+      image.data.byteLength,
+    );
+    let bytes = image.premultiplied ? premultiplied(straight) : straight;
+    if (source.flipY === true) {
+      const flipped = new Uint8Array(bytes.length);
+      for (let y = 0; y < image.height; y += 1) {
+        flipped.set(bytes.subarray(y * row, (y + 1) * row), (image.height - 1 - y) * row);
+      }
+      bytes = flipped;
+    }
+    const width = Array.isArray(size) ? (size[0] as number) : (size as GPUExtent3DDict).width;
+    const height = Array.isArray(size) ? (size[1] ?? 1) : ((size as GPUExtent3DDict).height ?? 1);
+    const step = alphaStepFor(image.premultiplied, destination.premultipliedAlpha === true);
+    if (step !== null) {
+      copier.copy(bytes, image.width, image.height, step, destination, width, height);
+      return;
+    }
+    queue.writeTexture(
+      {
+        texture: destination.texture,
+        mipLevel: destination.mipLevel ?? 0,
+        origin: destination.origin ?? { x: 0, y: 0, z: 0 },
+      },
+      bytes,
+      { offset: 0, bytesPerRow: row, rowsPerImage: image.height },
+      { width, height, depthOrArrayLayers: 1 },
+    );
+  };
+}
+
+export function adaptDevice(device: GPUDevice): GPUDevice {
+  adaptQueue(device);
+  const original = device.addEventListener.bind(device);
+  try {
+    original('uncapturederror', () => undefined);
+    return device;
+  } catch {
+    /* The binding refused it: this device needs the adapter. */
+  }
+
+  const listeners = new Set<EventListenerOrEventListenerObject>();
+  const deliver = (error: GPUError): void => {
+    const event = { type: 'uncapturederror', error } as unknown as GPUUncapturedErrorEvent;
+    for (const listener of listeners) {
+      if (typeof listener === 'function') listener(event);
+      else listener.handleEvent(event);
+    }
+  };
+  const scoped = device as unknown as {
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject): void;
+    removeEventListener(type: string, listener: EventListenerOrEventListenerObject): void;
+  };
+  scoped.addEventListener = (type, listener) => {
+    if (type === 'uncapturederror') listeners.add(listener);
+  };
+  scoped.removeEventListener = (type, listener) => {
+    if (type === 'uncapturederror') listeners.delete(listener);
+  };
+  adapted.set(device, {
+    open: () => device.pushErrorScope('validation'),
+    close: () => {
+      void device.popErrorScope().then((error) => {
+        if (error !== null) deliver(error);
+      });
+    },
+  });
+  return device;
+}

package/src/dialogs.ts

@@ -0,0 +1,98 @@
+/**
+ * Open and save dialogs from the desktop, since SDL 2 gives a window none.
+ *
+ * **The desktop's own dialog program, asked and waited for**: zenity, which GNOME and the GTK
+ * desktops carry, and kdialog where zenity is not installed. What comes back is what the desktop
+ * shell hands a game (`main/ipc.ts`): a picked file's name and bytes, `null` for a cancelled pick,
+ * and `false` for a cancelled save — a cancellation being exit code 1 for both programs.
+ *
+ * **A filter is the extensions the game named**, `.json` becoming `*.json`; a MIME type has no
+ * pattern either program takes, so it is left out rather than guessed at.
+ *
+ * What it gives up: Windows and macOS, which carry neither program and are Task 7's; the desktop
+ * portal, which is what a sandboxed Linux build would need and answers over D-Bus signals rather
+ * than an exit code; and where neither program is installed, `desktopFiles` answers null and the
+ * bridge reports every pick cancelled.
+ */
+
+import { spawn } from 'node:child_process';
+import { accessSync, constants } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { basename, delimiter, join } from 'node:path';
+
+import type { NativeFiles } from './bridge.ts';
+
+/** Run a dialog program and hand back its exit code and what it printed. */
+export type DialogRunner = (
+  command: string,
+  args: readonly string[],
+) => Promise<{ code: number; stdout: string }>;
+
+const spawnRunner: DialogRunner = (command, args) =>
+  new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'ignore'] });
+    let stdout = '';
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk: string) => {
+      stdout += chunk;
+    });
+    child.once('error', reject);
+    child.once('close', (code) => resolve({ code: code ?? 1, stdout }));
+  });
+
+/** Whether `name` is an executable on the search path. */
+function onPath(name: string): boolean {
+  for (const directory of (process.env['PATH'] ?? '').split(delimiter)) {
+    try {
+      accessSync(join(directory, name), constants.X_OK);
+      return true;
+    } catch {
+      /* Not in this one. */
+    }
+  }
+  return false;
+}
+
+const patternsOf = (accept: readonly string[]) =>
+  accept.filter((entry) => entry.startsWith('.')).map((extension) => `*${extension}`);
+
+/** The chosen path, or null when the person cancelled; anything else is a fault and says so. */
+function chosen(command: string, answer: { code: number; stdout: string }): string | null {
+  if (answer.code === 0) return answer.stdout.replace(/\r?\n$/, '');
+  if (answer.code !== 1) console.warn(`[driftengine] ${command} ended with code ${answer.code}`);
+  return null;
+}
+
+export function desktopFiles(
+  available: (name: string) => boolean = onPath,
+  run: DialogRunner = spawnRunner,
+): NativeFiles | null {
+  const command = available('zenity') ? 'zenity' : available('kdialog') ? 'kdialog' : null;
+  if (command === null) return null;
+  const zenity = command === 'zenity';
+  return {
+    async openFile(accept) {
+      const patterns = patternsOf(accept);
+      const args = zenity
+        ? [
+            '--file-selection',
+            ...(patterns.length > 0
+              ? [`--file-filter=${patterns.join(' ')} | ${patterns.join(' ')}`]
+              : []),
+          ]
+        : ['--getopenfilename', '.', ...(patterns.length > 0 ? [patterns.join(' ')] : [])];
+      const path = chosen(command, await run(command, args));
+      if (path === null) return null;
+      return { name: basename(path), bytes: new Uint8Array(await readFile(path)) };
+    },
+    async saveFile(name, bytes) {
+      const args = zenity
+        ? ['--file-selection', '--save', `--filename=${name}`]
+        : ['--getsavefilename', name];
+      const path = chosen(command, await run(command, args));
+      if (path === null) return false;
+      await writeFile(path, bytes);
+      return true;
+    },
+  };
+}

package/src/domEvents.ts

@@ -0,0 +1,170 @@
+/**
+ * What SDL tells a window, as the events a page hears: keys, the mouse, the wheel, focus,
+ * visibility, resizing and closing.
+ *
+ * **The engine's input is not changed for this host.** `InputSource` listens on `window`,
+ * `document` and its canvas for the events a browser sends, and so do the scenes, so they are sent
+ * here in that shape: each the browser's class (`uiEvents.ts`), a key by its `code` and with the
+ * character the layout typed (`keyEvents.ts`), a button in the browser's numbering, the wheel in
+ * the browser's direction. Each is dispatched at the canvas, or at what has the focus, and the tree
+ * (`domTree.ts`) captures and bubbles it as a browser's does.
+ *
+ * The mouse is `mouseEvents.ts`, which says what Chrome sends for it; keys are `keyEvents.ts`.
+ *
+ * Fingers are `touchEvents.ts`.
+ */
+
+import type { NativeCanvas } from './canvas.ts';
+import { KeyEvents, type SdlKey } from './keyEvents.ts';
+import { type EventMouse, MouseModel, type SdlPointer } from './mouseEvents.ts';
+import { type SdlFinger, TouchModel } from './touchEvents.ts';
+import type { HostPage } from './page.ts';
+
+export type { EventMouse } from './mouseEvents.ts';
+
+/** What this reads of an SDL window: its events, where it is on the screen, and its size. */
+export interface EventWindow {
+  on(type: string, listener: (event: never) => void): unknown;
+  off(type: string, listener: (event: never) => void): unknown;
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  /** Whether SDL has the window fullscreen, and the way to ask; a window without them has none. */
+  readonly fullscreen?: boolean;
+  setFullscreen?(on: boolean): void;
+}
+
+export interface EventOptions {
+  /** The clock clicks are counted against, in milliseconds. */
+  readonly now?: () => number;
+}
+
+const ESCAPE = 41;
+/** The modifier keys by scancode, both sides of each, as the bits `modifiers` keeps. */
+const MODIFIER = new Map([
+  [224, 1],
+  [228, 1],
+  [225, 2],
+  [229, 2],
+  [226, 4],
+  [230, 4],
+  [227, 8],
+  [231, 8],
+]);
+
+/** Connect `window`'s events to `page` and `canvas`, and hand back what disconnects them. */
+export function connectDomEvents(
+  window: EventWindow,
+  mouse: EventMouse,
+  page: HostPage,
+  canvas: NativeCanvas,
+  options: EventOptions = {},
+): () => void {
+  const keys = new KeyEvents(
+    () => page.keyTarget(),
+    () => page.userActivation.notify(),
+  );
+  /*
+   * **Leaving puts the window back as it was**, not into a window: one already fullscreen before the
+   * page asked — a game packaged fullscreen, or put there by the shell's bridge — stays so, as a
+   * browser under F11 stays fullscreen when a page's element leaves.
+   */
+  let before = false;
+  page.setFullscreener((on) => {
+    if (window.setFullscreen === undefined) return false;
+    try {
+      if (on) before = window.fullscreen === true;
+      window.setFullscreen(on || before);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+  /* Which modifiers are down, so a pointer event can say, as a browser's does. */
+  let modifiers = 0;
+  const held = () => ({
+    ctrlKey: (modifiers & 1) !== 0,
+    shiftKey: (modifiers & 2) !== 0,
+    altKey: (modifiers & 4) !== 0,
+    metaKey: (modifiers & 8) !== 0,
+  });
+  const now = options.now ?? (() => performance.now());
+  const pointer = new MouseModel(window, mouse, page, canvas, held, now);
+  const fingers = new TouchModel(window, page, canvas, held, now);
+  canvas.cursorer = (css) => pointer.cursor(css);
+  /* SDL makes a mouse of every finger, which the finger's own events have already said. */
+  const mouseOnly = (handle: (event: SdlPointer) => void) => (event: SdlPointer) => {
+    if (event.touch !== true) handle(event);
+  };
+
+  const listeners: [string, (event: never) => void][] = [
+    [
+      'keyDown',
+      (event: SdlKey) => {
+        /* Escape is the browser's before it is the page's: it lets go of the lock and fullscreen. */
+        if (event.scancode === ESCAPE && pointer.isLocked) page.unlock();
+        if (event.scancode === ESCAPE) void page.document.exitFullscreen().catch(() => undefined);
+        modifiers |= MODIFIER.get(event.scancode) ?? 0;
+        keys.down(event);
+      },
+    ],
+    ['textInput', ({ text }: { text: string }) => keys.text(text)],
+    [
+      'keyUp',
+      (event: SdlKey) => {
+        modifiers &= ~(MODIFIER.get(event.scancode) ?? 0);
+        keys.up(event);
+      },
+    ],
+    ['mouseMove', mouseOnly((event) => pointer.move(event))],
+    ['mouseButtonDown', mouseOnly((event) => pointer.down(event))],
+    ['mouseButtonUp', mouseOnly((event) => pointer.up(event))],
+    ['mouseWheel', mouseOnly((event) => pointer.wheel(event))],
+    ['fingerDown', (event: SdlFinger) => fingers.down(event)],
+    ['fingerMove', (event: SdlFinger) => fingers.move(event)],
+    ['fingerUp', (event: SdlFinger) => fingers.up(event)],
+    ['hover', () => pointer.hover()],
+    ['leave', () => pointer.leave()],
+    ['focus', () => page.setFocused(true)],
+    [
+      'blur',
+      () => {
+        page.unlock();
+        /* A key released in another window is never heard here. */
+        modifiers = 0;
+        page.setFocused(false);
+      },
+    ],
+    ['minimize', () => page.setVisible(false)],
+    ['hide', () => page.setVisible(false)],
+    ['restore', () => page.setVisible(true)],
+    ['show', () => page.setVisible(true)],
+    ['maximize', () => page.setVisible(true)],
+    /* After the host's own listener has resized the canvas, which it registered first. */
+    [
+      'resize',
+      () => {
+        /* Taken out of fullscreen by something other than the page: the element leaves with it. */
+        if (window.fullscreen === false) page.fullscreen.lost();
+        page.window.dispatchEvent(new Event('resize'));
+        /* A query about the window's size or shape may now answer otherwise. */
+        page.media.changed();
+      },
+    ],
+    ['beforeClose', () => page.window.dispatchEvent(new Event('beforeunload'))],
+  ];
+  /* A key held for its text is sent before anything that happened after it. */
+  for (const entry of listeners) {
+    const [type, listener] = entry;
+    if (type === 'keyDown' || type === 'textInput') continue;
+    entry[1] = (event: never) => {
+      keys.flush();
+      listener(event);
+    };
+  }
+  for (const [type, listener] of listeners) window.on(type, listener);
+  return () => {
+    for (const [type, listener] of listeners) window.off(type, listener);
+  };
+}

package/src/domTree.ts

@@ -0,0 +1,215 @@
+/**
+ * The three nodes a host's page has — window, document and canvas, each the parent of the next —
+ * and a browser's dispatch across them: capture from the window down, the target, then bubbling
+ * back up.
+ *
+ * **Node's `EventTarget` has no tree**, so an event sent to each node in turn reaches a window's
+ * capture listener last rather than first, tells a listener on the window that the window was its
+ * target, and lets a passive listener cancel it. Each of those is a page behaving differently here
+ * than in Chrome — the engine's own `requestFullscreenOnGesture` listens on the window in the
+ * capture phase — so dispatch is the DOM's, for the one shape of tree this host has.
+ *
+ * **Event handler attributes are listeners**, as the HTML specification makes them: `onclick`
+ * assigned is added to the list at that moment, keeps its place when reassigned, and a handler
+ * returning `false` cancels the event. A page reached for them — `canvas.ondblclick` — and on a
+ * bare `EventTarget` an assignment is a property nothing reads.
+ *
+ * What it gives up: no shadow roots, no `composed`, and no retargeting, none of which a canvas
+ * with nothing inside it can need.
+ */
+
+/** The `on…` attributes for `Types`, as a class declares them for the checker. */
+export type Handlers<Types extends string> = {
+  [Type in Types as `on${Type}`]: ((event: Event) => unknown) | null;
+};
+
+interface Listener {
+  readonly callback: EventListenerOrEventListenerObject;
+  readonly capture: boolean;
+  readonly once: boolean;
+  readonly passive: boolean;
+  removed: boolean;
+}
+
+const CAPTURING = 1;
+const AT_TARGET = 2;
+const BUBBLING = 3;
+
+/** Set on an event while it is dispatched here, read back by the accessors defined on it. */
+interface Dispatch {
+  target: HostNode;
+  current: HostNode | null;
+  phase: number;
+  path: HostNode[];
+  stopped: boolean;
+  stoppedNow: boolean;
+}
+const dispatches = new WeakMap<Event, Dispatch>();
+
+function optionsOf(options: boolean | AddEventListenerOptions | undefined) {
+  if (typeof options === 'boolean') return { capture: options, once: false, passive: false };
+  return {
+    capture: options?.capture === true,
+    once: options?.once === true,
+    passive: options?.passive === true,
+    signal: options?.signal,
+  };
+}
+
+/** Give `event` the accessors a dispatch answers, once; Node's own are read-only slots. */
+function adopt(event: Event, dispatch: Dispatch): void {
+  const known = dispatches.has(event);
+  dispatches.set(event, dispatch);
+  if (known) return;
+  const own = (name: string, get: () => unknown) =>
+    Object.defineProperty(event, name, { get, configurable: true });
+  const now = () => dispatches.get(event) as Dispatch;
+  own('target', () => now().target);
+  own('srcElement', () => now().target);
+  own('currentTarget', () => now().current);
+  own('eventPhase', () => now().phase);
+  Object.defineProperty(event, 'composedPath', {
+    value: () => (now().current === null ? [] : [...now().path]),
+    configurable: true,
+  });
+  const stop = event.stopPropagation.bind(event);
+  const stopNow = event.stopImmediatePropagation.bind(event);
+  Object.defineProperty(event, 'stopPropagation', {
+    value: () => {
+      now().stopped = true;
+      stop();
+    },
+    configurable: true,
+  });
+  Object.defineProperty(event, 'stopImmediatePropagation', {
+    value: () => {
+      now().stopped = true;
+      now().stoppedNow = true;
+      stopNow();
+    },
+    configurable: true,
+  });
+}
+
+export class HostNode implements EventTarget {
+  parentNode: HostNode | null = null;
+  private readonly listeners = new Map<string, Listener[]>();
+  private readonly handlers = new Map<string, { value: unknown; listener: EventListener }>();
+
+  addEventListener(
+    type: string,
+    callback: EventListenerOrEventListenerObject | null,
+    options?: boolean | AddEventListenerOptions,
+  ): void {
+    if (callback === null) return;
+    const { capture, once, passive, signal } = optionsOf(options);
+    if (signal?.aborted === true) return;
+    const list = this.listeners.get(type) ?? [];
+    if (list.some((l) => l.callback === callback && l.capture === capture)) return;
+    list.push({ callback, capture, once, passive, removed: false });
+    this.listeners.set(type, list);
+    signal?.addEventListener('abort', () => this.removeEventListener(type, callback, capture));
+  }
+
+  removeEventListener(
+    type: string,
+    callback: EventListenerOrEventListenerObject | null,
+    options?: boolean | EventListenerOptions,
+  ): void {
+    const capture = typeof options === 'boolean' ? options : options?.capture === true;
+    const list = this.listeners.get(type);
+    const at = list?.findIndex((l) => l.callback === callback && l.capture === capture) ?? -1;
+    if (list === undefined || at < 0) return;
+    (list[at] as Listener).removed = true;
+    list.splice(at, 1);
+  }
+
+  dispatchEvent(event: Event): boolean {
+    const path: HostNode[] = [];
+    for (let node: HostNode | null = this; node !== null; node = node.parentNode) path.push(node);
+    const dispatch: Dispatch = {
+      target: this,
+      current: null,
+      phase: 0,
+      path,
+      stopped: false,
+      stoppedNow: false,
+    };
+    adopt(event, dispatch);
+    for (let at = path.length - 1; at > 0 && !dispatch.stopped; at -= 1) {
+      (path[at] as HostNode).invoke(event, dispatch, CAPTURING, true);
+    }
+    if (!dispatch.stopped) this.invoke(event, dispatch, AT_TARGET, true);
+    if (!dispatch.stopped) this.invoke(event, dispatch, AT_TARGET, false);
+    for (let at = 1; at < path.length && event.bubbles && !dispatch.stopped; at += 1) {
+      (path[at] as HostNode).invoke(event, dispatch, BUBBLING, false);
+    }
+    dispatch.current = null;
+    dispatch.phase = 0;
+    return !event.defaultPrevented;
+  }
+
+  /** `on<type>`, for each type given: a listener held in place, replaced by assignment. */
+  protected static handles(prototype: object, types: readonly string[]): void {
+    for (const type of types) {
+      Object.defineProperty(prototype, `on${type}`, {
+        configurable: true,
+        get(this: HostNode) {
+          return this.handlers.get(type)?.value ?? null;
+        },
+        set(this: HostNode, value: unknown) {
+          const held = this.handlers.get(type);
+          if (typeof value !== 'function') {
+            if (held !== undefined) this.removeEventListener(type, held.listener);
+            this.handlers.delete(type);
+            return;
+          }
+          if (held !== undefined) {
+            held.value = value;
+            return;
+          }
+          const slot = {
+            value,
+            listener: (event: Event) => {
+              const result = (slot.value as (e: Event) => unknown).call(this, event);
+              if (result === false) event.preventDefault();
+            },
+          };
+          this.handlers.set(type, slot);
+          this.addEventListener(type, slot.listener);
+        },
+      });
+    }
+  }
+
+  private invoke(event: Event, dispatch: Dispatch, phase: number, capture: boolean): void {
+    const list = this.listeners.get(event.type);
+    if (list === undefined) return;
+    dispatch.current = this;
+    dispatch.phase = phase;
+    for (const listener of [...list]) {
+      if (listener.removed || listener.capture !== capture) continue;
+      if (listener.once) this.removeEventListener(event.type, listener.callback, capture);
+      const passive = listener.passive;
+      if (passive)
+        Object.defineProperty(event, 'preventDefault', {
+          value: () => undefined,
+          configurable: true,
+        });
+      try {
+        const { callback } = listener;
+        if (typeof callback === 'function') callback.call(this, event);
+        else callback.handleEvent(event);
+      } catch (error) {
+        /*
+         * Reported, and the rest still run: a browser logs an uncaught error in a listener and
+         * carries on dispatching, where a rethrow here would end the host's process.
+         */
+        console.error(error);
+      } finally {
+        if (passive) delete (event as { preventDefault?: unknown }).preventDefault;
+      }
+      if (dispatch.stoppedNow) return;
+    }
+  }
+}

package/src/drs.d.ts

@@ -0,0 +1,9 @@
+/// <reference types="driftscript/drs" />
+
+/*
+ * What TypeScript knows about a `.drs` module, for the host's own compilation.
+ *
+ * The host mounts the published scenes, and the voxel sandbox imports two DriftScript modules; the
+ * demos carry this same line in `demo/voxelSandbox/drs.d.ts`, which is in the engine's compilation
+ * and not in this one. `preload.mjs` is what compiles them at run time.
+ */