@driftengine/native-host 4.0.0

package/src/pointerCapture.ts

@@ -0,0 +1,73 @@
+/**
+ * Pointer capture: `setPointerCapture`, `releasePointerCapture` and `hasPointerCapture` on the
+ * canvas, and `gotpointercapture` and `lostpointercapture` when it changes.
+ *
+ * **As the Pointer Events specification processes it, and in the order Chrome sends it** — measured
+ * 2026-09-19 in Chrome 151 over the DevTools protocol. A capture asked for is pending, and
+ * `hasPointerCapture` already says so; it is taken, and `gotpointercapture` sent, just before that
+ * pointer's next event. A pointer's release lets it go at once, so `lostpointercapture` falls
+ * between the `mouseup` and the `click`. A mouse with no button down cannot be captured, and the
+ * request is dropped without a word; an id that is no pointer is refused as Chrome refuses it.
+ *
+ * **What capture moves here is when things are told, not where.** A browser retargets a captured
+ * pointer's events at the capturing element; this host has one element, which is every target
+ * already, and SDL keeps a pressed pointer to the window past its edge.
+ */
+
+import type { HostNode } from './domTree.ts';
+import { type PointerInit, PointerEvent } from './uiEvents.ts';
+
+export class PointerCapture {
+  /** Each pointer a page can capture, and whether it is pressed — in contact, or a button down. */
+  private readonly pointers = new Map<number, () => boolean>();
+  private readonly pending = new Map<number, HostNode>();
+  private readonly current = new Map<number, HostNode>();
+
+  add(pointerId: number, pressed: () => boolean): void {
+    this.pointers.set(pointerId, pressed);
+  }
+
+  remove(pointerId: number): void {
+    this.pointers.delete(pointerId);
+    this.pending.delete(pointerId);
+    this.current.delete(pointerId);
+  }
+
+  set(element: HostNode, pointerId: number): void {
+    const pressed = this.pointers.get(pointerId);
+    if (pressed === undefined) throw notFound('setPointerCapture');
+    if (pressed()) this.pending.set(pointerId, element);
+  }
+
+  release(element: HostNode, pointerId: number): void {
+    if (!this.pointers.has(pointerId)) throw notFound('releasePointerCapture');
+    if (this.pending.get(pointerId) === element) this.pending.delete(pointerId);
+  }
+
+  has(element: HostNode, pointerId: number): boolean {
+    return this.pending.get(pointerId) === element;
+  }
+
+  /** Before a pointer's next event: a change of capture, told with that event's fields. */
+  process(pointerId: number, init: PointerInit): void {
+    const was = this.current.get(pointerId);
+    const now = this.pending.get(pointerId);
+    if (was === now) return;
+    if (now === undefined) this.current.delete(pointerId);
+    else this.current.set(pointerId, now);
+    const told = { ...init, pointerId, bubbles: true, cancelable: false };
+    was?.dispatchEvent(new PointerEvent('lostpointercapture', told));
+    now?.dispatchEvent(new PointerEvent('gotpointercapture', told));
+  }
+
+  /** After a pointer's up or cancel: its capture is let go, and told at once. */
+  releaseImplicitly(pointerId: number, init: PointerInit): void {
+    this.pending.delete(pointerId);
+    this.process(pointerId, init);
+  }
+}
+
+function notFound(method: string): Error {
+  const message = `Failed to execute '${method}' on 'Element': No active pointer with the given id is found.`;
+  return Object.assign(new Error(message), { name: 'NotFoundError' });
+}

package/src/present.ts

@@ -0,0 +1,92 @@
+/**
+ * Putting the engine's frame in the window: one full-screen triangle, reading the canvas's texture.
+ *
+ * **A browser presents a canvas by itself and a host has to.** The engine draws into the canvas's
+ * current texture and stops; this copies that texture into the window's swap chain.
+ *
+ * **Decoded to linear on the way into an sRGB swap chain**, because Dawn's window renderer hands back
+ * `bgra8unorm-srgb`, and writing into one encodes. The engine has already graded and encoded its
+ * frame, so writing its bytes as they are would encode them a second time and every picture would
+ * come out paler. Decoding first puts the engine's own bytes on the screen, within a step of
+ * rounding. **The pixel gate reads the canvas texture, not the window**, so that rounding is on the
+ * screen and never in a comparison.
+ */
+
+const BLIT_WGSL = /* wgsl */ `
+@group(0) @binding(0) var frame: texture_2d<f32>;
+
+@vertex
+fn vertexMain(@builtin(vertex_index) index: u32) -> @builtin(position) vec4f {
+  let x = f32((index << 1u) & 2u);
+  let y = f32(index & 2u);
+  return vec4f(x * 2.0 - 1.0, 1.0 - y * 2.0, 0.0, 1.0);
+}
+
+fn toLinear(encoded: vec3f) -> vec3f {
+  let low = encoded / 12.92;
+  let high = pow((encoded + 0.055) / 1.055, vec3f(2.4));
+  return select(high, low, encoded <= vec3f(0.04045));
+}
+
+@fragment
+fn fragmentMain(@builtin(position) position: vec4f) -> @location(0) vec4f {
+  let size = vec2i(textureDimensions(frame)) - vec2i(1, 1);
+  let texel = textureLoad(frame, min(vec2i(position.xy), size), 0);
+  return vec4f(DECODE(texel.rgb), 1.0);
+}
+`;
+
+/** Whether writing into `format` encodes, so the blit has to decode first. */
+export function encodesOnWrite(format: GPUTextureFormat): boolean {
+  return format.endsWith('-srgb');
+}
+
+/** The blit's source, with the decode chosen for the swap chain it writes into. */
+export function blitSource(target: GPUTextureFormat): string {
+  return BLIT_WGSL.replace(
+    'DECODE(texel.rgb)',
+    encodesOnWrite(target) ? 'toLinear(texel.rgb)' : 'texel.rgb',
+  );
+}
+
+/** One pipeline, and one bind group a frame texture, made when they are first needed. */
+export class Presenter {
+  private readonly device: GPUDevice;
+  private readonly pipeline: GPURenderPipeline;
+  private source: GPUTexture | null = null;
+  private group: GPUBindGroup | null = null;
+
+  constructor(device: GPUDevice, target: GPUTextureFormat) {
+    this.device = device;
+    const module = device.createShaderModule({ label: 'native present', code: blitSource(target) });
+    this.pipeline = device.createRenderPipeline({
+      label: 'native present',
+      layout: 'auto',
+      vertex: { module, entryPoint: 'vertexMain' },
+      fragment: { module, entryPoint: 'fragmentMain', targets: [{ format: target }] },
+      primitive: { topology: 'triangle-list' },
+    });
+  }
+
+  /** Draw `frame` into `view`, and submit. */
+  present(frame: GPUTexture, view: GPUTextureView): void {
+    if (this.source !== frame) {
+      this.source = frame;
+      this.group = this.device.createBindGroup({
+        label: 'native present',
+        layout: this.pipeline.getBindGroupLayout(0),
+        entries: [{ binding: 0, resource: frame.createView() }],
+      });
+    }
+    const encoder = this.device.createCommandEncoder({ label: 'native present' });
+    const pass = encoder.beginRenderPass({
+      label: 'native present',
+      colorAttachments: [{ view, loadOp: 'clear', storeOp: 'store', clearValue: [0, 0, 0, 1] }],
+    });
+    pass.setPipeline(this.pipeline);
+    pass.setBindGroup(0, this.group);
+    pass.draw(3);
+    pass.end();
+    this.device.queue.submit([encoder.finish()]);
+  }
+}

package/src/rawPad.ts

@@ -0,0 +1,85 @@
+/**
+ * A joystick SDL has no controller mapping for — a flight stick, a wheel, an arcade panel, a pad
+ * too new or too rare — as Chrome shows a page one it cannot map: `mapping` empty, the device's own
+ * axes and buttons in the device's own order, and a name without "STANDARD GAMEPAD".
+ *
+ * **A hat is two axes**, as a browser on Linux reads one: the device reports it as a pair of
+ * absolute axes that are −1, 0 or 1, and SDL folds the pair into a direction, which is unfolded
+ * here — left and up negative. They follow the joystick's own axes, which is where their codes put
+ * them on a typical device.
+ *
+ * What it gives up: a device whose other axes sort after its hat in the kernel's numbering has
+ * them in a different order than Chrome gives; nothing here has been checked against a device, as
+ * there was none to hand.
+ */
+
+import { type DualRumble, dualRumble, type Rumbler } from './dualRumble.ts';
+import { type HostButton, hex } from './standardPad.ts';
+
+export interface JoystickDevice {
+  readonly id: number;
+  readonly name: string | null;
+  readonly vendor: number | null;
+  readonly product: number | null;
+}
+
+/** What this reads and drives of one of SDL's open joysticks. */
+export interface JoystickInstance extends Rumbler {
+  readonly device: JoystickDevice;
+  readonly axes: readonly number[];
+  readonly hats: readonly string[];
+  readonly buttons: readonly boolean[];
+  readonly hasRumble: boolean;
+  close(): void;
+}
+
+/** A hat's direction as the two axes it came from: x, then y, left and up negative. */
+const HAT: Readonly<Record<string, readonly [number, number]>> = {
+  centered: [0, 0],
+  up: [0, -1],
+  down: [0, 1],
+  left: [-1, 0],
+  right: [1, 0],
+  leftup: [-1, -1],
+  rightup: [1, -1],
+  leftdown: [-1, 1],
+  rightdown: [1, 1],
+};
+
+export class RawPad {
+  readonly id: string;
+  readonly mapping = '';
+  connected = true;
+  timestamp = 0;
+  readonly buttons: HostButton[];
+  readonly axes: number[];
+  readonly vibrationActuator: DualRumble | null;
+
+  constructor(
+    readonly index: number,
+    readonly source: JoystickInstance,
+  ) {
+    const { name, vendor, product } = source.device;
+    this.id = `${name ?? 'Joystick'} (Vendor: ${hex(vendor)} Product: ${hex(product)})`;
+    this.buttons = source.buttons.map(() => ({ pressed: false, touched: false, value: 0 }));
+    this.axes = Array.from({ length: source.axes.length + source.hats.length * 2 }, () => 0);
+    this.vibrationActuator = source.hasRumble ? dualRumble(source) : null;
+  }
+
+  read(now: number): void {
+    const { axes, hats, buttons } = this.source;
+    for (let at = 0; at < axes.length; at += 1) this.axes[at] = axes[at] as number;
+    for (let at = 0; at < hats.length; at += 1) {
+      const [x, y] = HAT[hats[at] as string] ?? [0, 0];
+      this.axes[axes.length + at * 2] = x;
+      this.axes[axes.length + at * 2 + 1] = y;
+    }
+    for (let at = 0; at < buttons.length; at += 1) {
+      const button = this.buttons[at] as HostButton;
+      button.pressed = buttons[at] === true;
+      button.touched = button.pressed;
+      button.value = button.pressed ? 1 : 0;
+    }
+    this.timestamp = now;
+  }
+}

package/src/readback.ts

@@ -0,0 +1,61 @@
+/**
+ * The frame as the engine left it in the canvas, read back to the CPU for the pixel gate.
+ *
+ * **The canvas texture, not the window**: the window is Dawn's `bgra8unorm-srgb` swap chain, which
+ * the present decodes into, and a comparison against it would compare that round trip. The canvas
+ * texture carries `COPY_SRC` for exactly this (see `canvas.ts`).
+ */
+
+const COPY_DST = 0x08;
+const MAP_READ = 0x01;
+
+export interface Frame {
+  readonly width: number;
+  readonly height: number;
+  /** Top row first, four bytes a pixel, in the canvas's own channel order. */
+  readonly rgba: Uint8Array;
+}
+
+/** Rows are copied at a stride of 256 bytes, which `copyTextureToBuffer` requires. */
+export function paddedRow(width: number): number {
+  return 256 * Math.ceil((width * 4) / 256);
+}
+
+/** The padded rows, packed. */
+export function unpad(bytes: Uint8Array, width: number, height: number): Uint8Array {
+  const row = paddedRow(width);
+  const out = new Uint8Array(width * height * 4);
+  for (let y = 0; y < height; y += 1) {
+    out.set(bytes.subarray(y * row, y * row + width * 4), y * width * 4);
+  }
+  return out;
+}
+
+export async function readFrame(context: GPUCanvasContext): Promise<Frame> {
+  const configuration = context.getConfiguration();
+  if (configuration === null)
+    throw new Error('[driftengine] there is no frame: the canvas was never configured');
+  const { device, format } = configuration;
+  if (format !== 'rgba8unorm') {
+    throw new Error(`[driftengine] the gate reads rgba8unorm frames, and this one is ${format}`);
+  }
+  const texture = context.getCurrentTexture();
+  const { width, height } = texture;
+  const buffer = device.createBuffer({
+    label: 'native readback',
+    size: paddedRow(width) * height,
+    usage: COPY_DST | MAP_READ,
+  });
+  const encoder = device.createCommandEncoder({ label: 'native readback' });
+  encoder.copyTextureToBuffer(
+    { texture },
+    { buffer, bytesPerRow: paddedRow(width) },
+    { width, height },
+  );
+  device.queue.submit([encoder.finish()]);
+  await buffer.mapAsync(MAP_READ);
+  const rgba = unpad(new Uint8Array(buffer.getMappedRange()), width, height);
+  buffer.unmap();
+  buffer.destroy();
+  return { width, height, rgba };
+}

package/src/runtime.ts

@@ -0,0 +1,162 @@
+/**
+ * The host, started: a window with a WebGPU device, and around its canvas every global a page
+ * expects, installed in the order a page has them.
+ *
+ * **One start for everything that runs on the host** — a packaged game (`game.ts`) and the engine
+ * repository's scene runner and editor runner — so the three cannot come to disagree about what a
+ * page has, which is the drift two copies of one setup would be.
+ *
+ * The order is the part worth reading. **Threads first**, before a game's modules are imported,
+ * because the engine's pools decide whether they have a default worker when they load; a page's
+ * `Worker` likewise exists before its scripts run. Audio next, then the window and its device, the
+ * page, the shell's bridge (`__driftHost`), controllers, and `fetch` for the game's own files.
+ *
+ * What it gives up: one window per process, which is what a game on a desktop is.
+ */
+
+import { mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import sdl from '@kmamal/sdl';
+import { BRIDGE_KEY } from '@driftengine/package/bridge';
+
+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 { 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 type { WindowMode } from './windowMode.ts';
+
+export interface HostOptions {
+  readonly title: string;
+  /** The canvas, in pixels. */
+  readonly width: number;
+  readonly height: number;
+  /** A window that is never shown, for checks that should not flash on a desktop. */
+  readonly hidden?: boolean;
+  /** Windowed, borderless or fullscreen, as a packaged game's manifest says; windowed by default. */
+  readonly mode?: WindowMode;
+  /** Whether a person can resize the window; true by default, as the manifest's default is. */
+  readonly resizable?: boolean;
+  /** Where the shell's store lives; by default where the desktop shell keeps its own. */
+  readonly storePath?: string;
+  /** The game's own files, which `fetch` of a relative address reads. */
+  readonly publicDir?: string;
+  /** `location.search`, for a game that reads its address. */
+  readonly query?: string;
+  readonly audio?: AudioDefaults;
+}
+
+export interface FrameCall {
+  /** The page's clock for this frame, in milliseconds. */
+  readonly now: number;
+  /** Frames drawn before this one. */
+  readonly drawn: number;
+}
+
+export interface RunOptions {
+  readonly frames?: number;
+  readonly before?: (drawn: number) => void;
+  readonly frame?: (call: FrameCall) => void;
+  readonly after?: (call: FrameCall) => void;
+}
+
+export interface NativeHost {
+  readonly window: HostWindow;
+  readonly page: HostPage;
+  readonly canvas: NativeCanvas;
+  readonly bridge: NativeBridge;
+  /**
+   * 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.
+   */
+  run(options?: RunOptions): Promise<number>;
+  /** Flush the store and close the window. */
+  close(): Promise<void>;
+}
+
+/** Where the desktop shell's Electron keeps application data on this platform. */
+export function configDirectory(): string {
+  if (process.platform === 'win32') {
+    return process.env['APPDATA'] ?? join(homedir(), 'AppData', 'Roaming');
+  }
+  if (process.platform === 'darwin') return join(homedir(), 'Library', 'Application Support');
+  return process.env['XDG_CONFIG_HOME'] ?? join(homedir(), '.config');
+}
+
+export function startHost(options: HostOptions): NativeHost {
+  installThreads();
+  installAudio(options.audio ?? {});
+  const window = new HostWindow({
+    title: options.title,
+    width: options.width,
+    height: options.height,
+    hidden: options.hidden === true,
+    mode: options.mode,
+    resizable: options.resizable,
+  });
+  installGpu(window.gpu);
+  installLocation(options.query ?? '');
+  installImages();
+  const page = new HostPage();
+  page.install();
+  window.connectPage(page);
+
+  let quitting = false;
+  const storePath =
+    options.storePath ?? join(configDirectory(), 'driftengine-native-host', 'store.json');
+  mkdirSync(dirname(storePath), { recursive: true });
+  const bridge = window.createBridge(storePath, () => {
+    quitting = true;
+  });
+  (globalThis as Record<string, unknown>)[BRIDGE_KEY] = bridge;
+  new HostGamepads(sdl.controller as unknown as PadModule, {
+    joysticks: sdl.joystick as unknown as JoystickModule,
+    events: page.window,
+  }).install();
+  if (options.publicDir !== undefined) {
+    globalThis.fetch = hostFetch(options.publicDir, globalThis.fetch.bind(globalThis));
+  }
+  window.canvas.resizeTo(options.width, options.height);
+
+  return {
+    window,
+    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;
+    },
+    async close() {
+      bridge.flushSync();
+      await window.close();
+    },
+  };
+}

package/src/standardPad.ts

@@ -0,0 +1,126 @@
+/**
+ * A controller SDL knows, as the W3C's standard gamepad: SDL's game-controller layer reports a
+ * controller's buttons and axes by name, in the layout the standard describes by index, so each
+ * crosses by name into its index. `a` is button 0, the left stick is axes 0 and 1 with down
+ * positive, a trigger is an axis SDL reports from 0 to 1 and a button the standard reports as
+ * pressed past Chrome's threshold. A pad is named the way Chrome names one on Linux,
+ * `… (STANDARD GAMEPAD Vendor: 045e Product: 0b12)`, which is where the engine reads what kind of
+ * pad it is.
+ *
+ * What it gives up: trigger rumble, which the engine does not reach; and `touched`, which reads as
+ * `pressed` because SDL reports no touch.
+ */
+
+import { type DualRumble, dualRumble, type Rumbler } from './dualRumble.ts';
+
+type SdlButton =
+  | 'a'
+  | 'b'
+  | 'x'
+  | 'y'
+  | 'leftShoulder'
+  | 'rightShoulder'
+  | 'back'
+  | 'start'
+  | 'leftStick'
+  | 'rightStick'
+  | 'dpadUp'
+  | 'dpadDown'
+  | 'dpadLeft'
+  | 'dpadRight'
+  | 'guide';
+
+type SdlAxis =
+  'leftStickX' | 'leftStickY' | 'rightStickX' | 'rightStickY' | 'leftTrigger' | 'rightTrigger';
+
+export interface PadDevice {
+  readonly id: number;
+  readonly name: string;
+  readonly vendor: number | null;
+  readonly product: number | null;
+}
+
+/** What this reads and drives of one of SDL's open controllers. */
+export interface PadController extends Rumbler {
+  readonly device: PadDevice;
+  readonly axes: Readonly<Record<SdlAxis, number>>;
+  readonly buttons: Readonly<Record<string, boolean>>;
+  readonly hasRumble: boolean;
+  close(): void;
+}
+
+/** The standard's buttons in its order, with the two triggers standing in at 6 and 7. */
+const STANDARD: readonly (SdlButton | 'leftTrigger' | 'rightTrigger')[] = [
+  'a',
+  'b',
+  'x',
+  'y',
+  'leftShoulder',
+  'rightShoulder',
+  'leftTrigger',
+  'rightTrigger',
+  'back',
+  'start',
+  'leftStick',
+  'rightStick',
+  'dpadUp',
+  'dpadDown',
+  'dpadLeft',
+  'dpadRight',
+  'guide',
+];
+const AXES: readonly SdlAxis[] = ['leftStickX', 'leftStickY', 'rightStickX', 'rightStickY'];
+/** Chrome's line for an analogue button, 30 of 255 (`kDefaultButtonPressedThreshold`). */
+const PRESSED_PAST = 30 / 255;
+
+export const hex = (value: number | null) => (value ?? 0).toString(16).padStart(4, '0');
+
+export interface HostButton {
+  pressed: boolean;
+  touched: boolean;
+  value: number;
+}
+
+/** One controller in a slot, its state rewritten in place at every read. */
+export class StandardPad {
+  readonly id: string;
+  readonly mapping = 'standard';
+  connected = true;
+  timestamp = 0;
+  readonly buttons: HostButton[] = STANDARD.map(() => ({
+    pressed: false,
+    touched: false,
+    value: 0,
+  }));
+  readonly axes = [0, 0, 0, 0];
+  readonly vibrationActuator: DualRumble | null;
+
+  constructor(
+    readonly index: number,
+    readonly source: PadController,
+  ) {
+    const { name, vendor, product } = source.device;
+    this.id = `${name} (STANDARD GAMEPAD Vendor: ${hex(vendor)} Product: ${hex(product)})`;
+    this.vibrationActuator = source.hasRumble ? dualRumble(source) : null;
+  }
+
+  read(now: number): void {
+    const { axes, buttons } = this.source;
+    for (let at = 0; at < STANDARD.length; at += 1) {
+      const name = STANDARD[at] as SdlButton | 'leftTrigger' | 'rightTrigger';
+      const button = this.buttons[at] as HostButton;
+      if (name === 'leftTrigger' || name === 'rightTrigger') {
+        button.value = axes[name];
+        button.pressed = button.value > PRESSED_PAST;
+      } else {
+        button.pressed = buttons[name] === true;
+        button.value = button.pressed ? 1 : 0;
+      }
+      button.touched = button.pressed;
+    }
+    for (let at = 0; at < AXES.length; at += 1) {
+      this.axes[at] = axes[AXES[at] as SdlAxis];
+    }
+    this.timestamp = now;
+  }
+}

package/src/textHost.ts

@@ -0,0 +1,66 @@
+/**
+ * The editor's text services on this host: `@driftengine/ui2d`'s `TextHost`, over SDL.
+ *
+ * **Committed text, as a finished composition.** SDL delivers `textInput` — a key's character, or
+ * what an input method finished composing — and each one reaches the editor through the same
+ * `applyComposition` the browser host feeds, marked done. Queued, not applied, because it arrives on
+ * SDL's schedule and the editor applies text on its own frame, as the browser host's queue does
+ * (`editor/src/host/browser/textHost.ts`). Text arriving with no field focused is not the editor's.
+ *
+ * **The clipboard is SDL's**, which is the desktop's.
+ *
+ * What it gives up, both of them `@kmamal/sdl` 0.11's: it reports no composition in progress
+ * (`textEditing`), so an input method shows its unfinished text in its own window rather than in
+ * the field; and it cannot place that window, so `focusField`'s rectangle is kept and not used.
+ */
+
+import type { TextHost } from '@driftengine/ui2d';
+
+/** One update, in the shape `applyComposition` takes. */
+export interface CompositionUpdate {
+  text: string;
+  done: boolean;
+}
+
+/** What this reads of the SDL window. */
+export interface TextWindow {
+  on(type: 'textInput', listener: (event: { text: string }) => void): unknown;
+}
+
+/** SDL's clipboard. */
+export interface TextClipboard {
+  readonly text: string;
+  setText(text: string): void;
+}
+
+export interface NativeTextHost extends TextHost {
+  /** Take the text that has arrived, oldest first, and clear the queue. */
+  drainCompositions(out: CompositionUpdate[]): number;
+}
+
+export function createNativeTextHost(window: TextWindow, clipboard: TextClipboard): NativeTextHost {
+  const pending: CompositionUpdate[] = [];
+  let focused = false;
+  window.on('textInput', ({ text }) => {
+    if (focused) pending.push({ text, done: true });
+  });
+  return {
+    focusField() {
+      focused = true;
+    },
+    blurField() {
+      focused = false;
+    },
+    readClipboard: () => Promise.resolve(clipboard.text),
+    writeClipboard(text) {
+      clipboard.setText(text);
+      return Promise.resolve();
+    },
+    drainCompositions(out) {
+      out.length = 0;
+      for (const update of pending) out.push(update);
+      pending.length = 0;
+      return out.length;
+    },
+  };
+}