@driftengine/native-host 4.0.0

package/src/audioParams.ts

@@ -0,0 +1,150 @@
+/**
+ * A defect in `node-web-audio-api` 2.2.0's automation, corrected for the engine's ramps until it is
+ * fixed upstream.
+ *
+ * **The defect, measured against Chrome on 2026-09-19.** A `setTargetAtTime` whose start is past
+ * the first render quantum, following an event that has *settled* — the value simply set, a
+ * `setValueAtTime`, the end of a linear or exponential ramp — renders garbage from the second
+ * quantum until it starts: 31.1 for a gain holding at 1, 10.5 for one a ramp left at 0.5, a
+ * low-pass at −839,731 Hz. From its start on it is Chrome's to four places, and following another
+ * `setTargetAtTime` it is right throughout. Every other shape the engine schedules was compared
+ * and agrees. The engine's every level and cutoff move is this shape (`mix/inserts.ts`, `ramp`), so
+ * the reference mix came out 28 dB hot in its second second.
+ *
+ * **The correction is what the specification says the value already is.** Before a target starts,
+ * a parameter holds the value its last settled event left; so a `setValueAtTime` of exactly that
+ * value is placed at the target's start, which changes nothing a browser computes and gives this
+ * engine the event it renders correctly. To know that value, each parameter's scheduled events are
+ * written down as they are made. Where that record cannot say — a curve spanning the start, a
+ * `cancelAndHoldAtTime`, a value set while events are pending — nothing is added, rather than a
+ * guess.
+ *
+ * Remove this with the dependency's fix: `audioParams.test.ts` is Chrome's numbers and will say.
+ */
+
+import { createRequire } from 'node:module';
+
+interface Scheduled {
+  /** When it takes hold: a ramp's end, a curve's end, a target's start. */
+  readonly time: number;
+  /** Whether the value from `time` on is `value`, or still moving toward it. */
+  readonly settled: boolean;
+  readonly value: number;
+}
+
+type ParamMethods = {
+  setValueAtTime(value: number, time: number): AudioParam;
+  linearRampToValueAtTime(value: number, time: number): AudioParam;
+  exponentialRampToValueAtTime(value: number, time: number): AudioParam;
+  setTargetAtTime(target: number, start: number, constant: number): AudioParam;
+  setValueCurveAtTime(values: ArrayLike<number>, start: number, duration: number): AudioParam;
+  cancelScheduledValues(time: number): AudioParam;
+  cancelAndHoldAtTime(time: number): AudioParam;
+};
+
+/** Each parameter's events, time-ordered, or `null` once the record cannot be trusted. */
+const records = new WeakMap<object, Scheduled[] | null>();
+
+function recordOf(param: object): Scheduled[] | null {
+  let record = records.get(param);
+  if (record === undefined) {
+    record = [];
+    records.set(param, record);
+  }
+  return record;
+}
+
+function add(param: object, event: Scheduled): void {
+  const record = recordOf(param);
+  if (record === null) return;
+  let at = record.length;
+  while (at > 0 && (record[at - 1] as Scheduled).time > event.time) at -= 1;
+  record.splice(at, 0, event);
+}
+
+let installed = false;
+
+/** Correct the Rust engine's parameters, once, for every context made after or before. */
+export function correctAutomation(): void {
+  if (installed) return;
+  installed = true;
+  const { AudioParam: Param } = createRequire(import.meta.url)('node-web-audio-api') as {
+    AudioParam: { prototype: ParamMethods & { value: number } };
+  };
+  const proto = Param.prototype;
+  const original = {
+    setValueAtTime: proto.setValueAtTime,
+    linearRampToValueAtTime: proto.linearRampToValueAtTime,
+    exponentialRampToValueAtTime: proto.exponentialRampToValueAtTime,
+    setTargetAtTime: proto.setTargetAtTime,
+    setValueCurveAtTime: proto.setValueCurveAtTime,
+    cancelScheduledValues: proto.cancelScheduledValues,
+    cancelAndHoldAtTime: proto.cancelAndHoldAtTime,
+  };
+  const value = Object.getOwnPropertyDescriptor(proto, 'value');
+
+  proto.setValueAtTime = function (this: AudioParam, next, time) {
+    add(this, { time, settled: true, value: next });
+    return original.setValueAtTime.call(this, next, time);
+  };
+  proto.linearRampToValueAtTime = function (this: AudioParam, next, time) {
+    add(this, { time, settled: true, value: next });
+    return original.linearRampToValueAtTime.call(this, next, time);
+  };
+  proto.exponentialRampToValueAtTime = function (this: AudioParam, next, time) {
+    add(this, { time, settled: true, value: next });
+    return original.exponentialRampToValueAtTime.call(this, next, time);
+  };
+  proto.setValueCurveAtTime = function (this: AudioParam, values, start, duration) {
+    add(this, { time: start + duration, settled: true, value: values[values.length - 1] ?? 0 });
+    /* A curve spans its duration, and a target starting inside it has no settled value to hold. */
+    add(this, { time: start, settled: false, value: Number.NaN });
+    return original.setValueCurveAtTime.call(this, values, start, duration);
+  };
+  proto.cancelScheduledValues = function (this: AudioParam, time) {
+    const record = recordOf(this);
+    if (record !== null) {
+      while (record.length > 0 && (record[record.length - 1] as Scheduled).time >= time)
+        record.pop();
+    }
+    return original.cancelScheduledValues.call(this, time);
+  };
+  proto.cancelAndHoldAtTime = function (this: AudioParam, time) {
+    records.set(this, null);
+    return original.cancelAndHoldAtTime.call(this, time);
+  };
+  proto.setTargetAtTime = function (this: AudioParam, target, start, constant) {
+    const record = recordOf(this);
+    if (record !== null) {
+      let last: Scheduled | undefined;
+      for (const event of record) if (event.time <= start) last = event;
+      /* Nothing before it: what it holds is the value the parameter was simply given. */
+      const held =
+        last === undefined
+          ? (this as unknown as { value: number }).value
+          : last.settled
+            ? last.value
+            : null;
+      if (held !== null && Number.isFinite(held)) {
+        add(this, { time: start, settled: true, value: held });
+        original.setValueAtTime.call(this, held, start);
+      }
+    }
+    add(this, { time: start, settled: false, value: target });
+    return original.setTargetAtTime.call(this, target, start, constant);
+  };
+  if (value?.set !== undefined && value.get !== undefined) {
+    const { get, set } = value;
+    Object.defineProperty(proto, 'value', {
+      configurable: true,
+      enumerable: value.enumerable ?? false,
+      get,
+      set(this: AudioParam, next: number) {
+        /* With events pending, a value set now is an event at a time this cannot see. */
+        const record = records.get(this);
+        if (record !== undefined && record !== null && record.length > 0) records.set(this, null);
+        set.call(this, next);
+      },
+    });
+  }
+}

package/src/bridge.ts

@@ -0,0 +1,230 @@
+/**
+ * The shell's bridge, `globalThis.__driftHost`, answered by this host.
+ *
+ * **A packaged game reaches its platform through `createHost()`**, from `@driftengine/package`, which
+ * takes the shell's implementations whenever it finds this bridge — and the engine's splash stands
+ * aside for a shell. The desktop shell's preload puts one there over Electron's IPC; this host puts
+ * its own there over SDL and the filesystem, so a game packaged for one runs on the other with no
+ * change. Each member makes the decision the desktop shell's main process makes (`main/ipc.ts`), for
+ * the same reasons, written beside it.
+ *
+ * - **The store** is one file, read whole before the game boots and replaced whole a quarter of a
+ *   second after the last write — `storeFile.ts`, which the desktop shell uses too — and written at
+ *   once, synchronously, on the way out, because a debounce that loses its last write loses exactly
+ *   the setting somebody changed before quitting.
+ * - **Fullscreen** is read back after it is asked for, since a window manager may refuse, and a
+ *   size is refused while the window covers a display.
+ * - **Closing** asks a game that registered to be asked, and waits for it at most three seconds; a
+ *   game that did not is closed at once.
+ *
+ * What it gives up: SDL 2 reports no scale for a display, so a display the window is not on reads
+ * 1; the store has no cloud; and `platform` answers that no store's features are here.
+ */
+
+import type { DisplayInfo, WindowMode } from '@driftengine/core';
+
+import type { DriftHostBridge } from '@driftengine/package/bridge';
+import { readStoreFile, writeStoreFile, writeStoreFileSync } from '@driftengine/package/store';
+
+/** A display, as SDL reports one. */
+export interface BridgeDisplay {
+  readonly name: string | null;
+  readonly frequency: number;
+  readonly geometry: {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+  };
+}
+
+/** What the bridge reads and drives of the SDL window. */
+export interface BridgeWindow {
+  readonly width: number;
+  readonly height: number;
+  readonly pixelWidth: number;
+  readonly fullscreen: boolean;
+  readonly display: BridgeDisplay;
+  setFullscreen(on: boolean): void;
+  setSize(width: number, height: number): void;
+  on(
+    type: 'focus' | 'blur' | 'beforeClose',
+    listener: (event: { prevent?: () => void }) => void,
+  ): unknown;
+  off(
+    type: 'focus' | 'blur' | 'beforeClose',
+    listener: (event: { prevent?: () => void }) => void,
+  ): unknown;
+}
+
+export interface NativeFiles {
+  openFile(accept: readonly string[]): Promise<{ name: string; bytes: Uint8Array } | null>;
+  saveFile(name: string, bytes: Uint8Array): Promise<boolean>;
+}
+
+export interface NativeBridgeOptions {
+  readonly window: BridgeWindow;
+  readonly displays: () => readonly BridgeDisplay[];
+  readonly storePath: string;
+  /** End the session: the host stops drawing and closes the window. */
+  readonly quit: () => void;
+  readonly files?: NativeFiles;
+}
+
+/** The bridge, and what writes its store now. */
+export interface NativeBridge extends DriftHostBridge {
+  flushSync(): void;
+}
+
+/** The desktop shell's figures (`main/ipc.ts`), for the same reasons. */
+const WRITE_DEBOUNCE_MS = 250;
+const QUIT_GRACE_MS = 3000;
+
+const idOf = (display: BridgeDisplay) =>
+  `${display.name ?? ''}@${display.geometry.x},${display.geometry.y}`;
+
+/**
+ * No file dialog on this desktop: a cancelled pick and a refused save, which a game already handles,
+ * and one line saying why, so a player whose picker never opens is told what to install.
+ */
+function noFiles(): NativeFiles {
+  let said = false;
+  const say = (): void => {
+    if (said) return;
+    said = true;
+    console.warn(
+      '[driftengine] this desktop has no file dialog for the native host: install zenity',
+    );
+  };
+  return {
+    openFile: () => {
+      say();
+      return Promise.resolve(null);
+    },
+    saveFile: () => {
+      say();
+      return Promise.resolve(false);
+    },
+  };
+}
+
+export function nativeBridge(options: NativeBridgeOptions): NativeBridge {
+  const { window, storePath } = options;
+  const snapshot = readStoreFile(storePath);
+  const entries = new Map(Object.entries(snapshot));
+  let pending: ReturnType<typeof setTimeout> | null = null;
+  const flush = (): void => {
+    pending = null;
+    void writeStoreFile(storePath, entries).catch((cause: unknown) =>
+      console.error('[driftengine] could not write the store:', cause),
+    );
+  };
+  const schedule = (): void => {
+    if (pending === null) pending = setTimeout(flush, WRITE_DEBOUNCE_MS);
+  };
+  const flushSync = (): void => {
+    if (pending === null) return;
+    clearTimeout(pending);
+    pending = null;
+    try {
+      writeStoreFileSync(storePath, entries);
+    } catch (cause) {
+      console.error('[driftengine] could not write the store on the way out:', cause);
+    }
+  };
+
+  /* One decision for the two members that need it, as the desktop shell's `resizable` is. */
+  const resizable = (): boolean => !window.fullscreen;
+
+  const quitHandlers = new Set<() => void>();
+  let grace: ReturnType<typeof setTimeout> | null = null;
+  const quit = (): void => {
+    if (grace !== null) clearTimeout(grace);
+    grace = null;
+    flushSync();
+    options.quit();
+  };
+  window.on('beforeClose', (event) => {
+    if (quitHandlers.size === 0) {
+      quit();
+      return;
+    }
+    event.prevent?.();
+    for (const handler of quitHandlers) handler();
+    /* A ceiling, not a wait: a game that answers with `requestQuit` closes at once. */
+    grace ??= setTimeout(quit, QUIT_GRACE_MS);
+  });
+
+  const files = options.files ?? noFiles();
+  return {
+    storeSnapshot: snapshot,
+    writeKey(key, value) {
+      entries.set(key, value);
+      schedule();
+    },
+    removeKey(key) {
+      entries.delete(key);
+      schedule();
+    },
+    flushSync,
+    setFullscreen(on) {
+      window.setFullscreen(on);
+      return Promise.resolve();
+    },
+    isFullscreen: () => window.fullscreen,
+    refreshHz: () => (window.display.frequency > 0 ? window.display.frequency : null),
+    mode: (): WindowMode => (window.fullscreen ? 'fullscreen' : 'windowed'),
+    setMode(mode) {
+      window.setFullscreen(mode === 'fullscreen');
+      /* Read back rather than assumed: a window manager may refuse. */
+      return Promise.resolve(window.fullscreen === (mode === 'fullscreen'));
+    },
+    size: () => ({ width: window.width, height: window.height }),
+    canSetSize: resizable,
+    setSize(width, height) {
+      if (!resizable()) return Promise.resolve(false);
+      window.setSize(Math.round(width), Math.round(height));
+      return Promise.resolve(true);
+    },
+    displays(): readonly DisplayInfo[] {
+      const on = idOf(window.display);
+      return options.displays().map((display, at) => ({
+        id: idOf(display),
+        /* A size where there is no name, which is what somebody choosing a monitor recognises. */
+        label:
+          display.name !== null && display.name.length > 0
+            ? display.name
+            : `${display.geometry.width}x${display.geometry.height}`,
+        width: display.geometry.width,
+        height: display.geometry.height,
+        scale: idOf(display) === on ? window.pixelWidth / window.width : 1,
+        refreshHz: display.frequency > 0 ? display.frequency : null,
+        /* SDL lists the primary display first. */
+        primary: at === 0,
+      }));
+    },
+    onFocusChange(handler) {
+      const focus = () => handler(true);
+      const blur = () => handler(false);
+      window.on('focus', focus);
+      window.on('blur', blur);
+      return () => {
+        window.off('focus', focus);
+        window.off('blur', blur);
+      };
+    },
+    onQuitRequest(handler) {
+      quitHandlers.add(handler);
+      return () => quitHandlers.delete(handler);
+    },
+    canQuit: true,
+    requestQuit: quit,
+    openFile: (accept) => files.openFile(accept),
+    saveFile: (name, bytes) => files.saveFile(name, bytes),
+    platform: {
+      available: false,
+      unlockAchievement: () => undefined,
+      setRichPresence: () => undefined,
+    },
+  };
+}

package/src/canvas.ts

@@ -0,0 +1,227 @@
+/**
+ * A canvas with no page around it: a drawing buffer, a CSS box, and a WebGPU context.
+ *
+ * **What the engine asks of a canvas, and no more.** Its WebGPU backend takes a canvas, asks it
+ * for a `webgpu` context, configures that against its device, sets the drawing buffer's size, and
+ * each frame draws into `getCurrentTexture()`. The renderer's public measurements read the canvas's
+ * CSS box. That is the whole surface, so that is what this implements — and anything a scene reaches
+ * for beyond it is a gap the host names when it meets one, rather than a document this pretends to
+ * be.
+ *
+ * **The frame lands in a texture the host owns.** A browser presents the canvas itself at the end of
+ * a task; a host has to, so the texture carries two usages the engine never asks for — sampled, to be
+ * drawn into the window, and copyable, to be read back by the pixel gate.
+ */
+
+import { CanvasStyle } from './canvasStyle.ts';
+import { type Handlers, HostNode } from './domTree.ts';
+import { INPUT_TYPES, type PageDocument } from './page.ts';
+import { PointerCapture } from './pointerCapture.ts';
+
+/* Texture usage flags, named here rather than read off a global a host may not have installed. */
+const COPY_SRC = 0x01;
+const TEXTURE_BINDING = 0x04;
+const RENDER_ATTACHMENT = 0x10;
+
+/* The attributes `HostNode.handles` defines below, declared for the checker. */
+export interface NativeCanvas extends Handlers<(typeof INPUT_TYPES)[number]> {}
+
+export class NativeCanvas extends HostNode {
+  /** The drawing buffer, in device pixels, which the engine sets. */
+  width: number;
+  height: number;
+  /** Device pixels per CSS pixel. */
+  readonly pixelRatio: number;
+  /** Whether there is a window to present to: false while it is minimised to nothing. */
+  visible = true;
+
+  private cssWidth: number;
+  private cssHeight: number;
+  private context: NativeCanvasContext | null = null;
+  /** Set by the page that holds this canvas (`page.ts`); a canvas outside one has no pointer to lock. */
+  lockPointer: (() => Promise<void>) | null = null;
+  /** Set by the page too, which is what holds the focus and the fullscreen. */
+  focuser: ((focus: boolean) => void) | null = null;
+  fullscreener: (() => Promise<void>) | null = null;
+  capture: PointerCapture | null = null;
+  /** Set by what drives the window's mouse, which is where a cursor is shown (`canvasStyle.ts`). */
+  cursorer: ((css: string) => void) | null = null;
+  readonly style = new CanvasStyle((css) => this.cursorer?.(css));
+  /**
+   * A canvas is focusable only once it is given a `tabIndex`, as a browser's is: until then it
+   * reports −1 and `focus()` does nothing.
+   */
+  private focusIndex: number | null = null;
+
+  static {
+    HostNode.handles(NativeCanvas.prototype, INPUT_TYPES);
+  }
+
+  constructor(width: number, height: number, pixelRatio = 1) {
+    super();
+    this.pixelRatio = pixelRatio;
+    this.width = width;
+    this.height = height;
+    this.cssWidth = width / pixelRatio;
+    this.cssHeight = height / pixelRatio;
+  }
+
+  /** The CSS box, which is what `cssWidth` and `aspect` are asked of. */
+  get clientWidth(): number {
+    return this.cssWidth;
+  }
+
+  get clientHeight(): number {
+    return this.cssHeight;
+  }
+
+  getBoundingClientRect(): DOMRect {
+    const width = this.cssWidth;
+    const height = this.cssHeight;
+    const rect = { x: 0, y: 0, left: 0, top: 0, right: width, bottom: height, width, height };
+    return { ...rect, toJSON: () => rect } as DOMRect;
+  }
+
+  /**
+   * `webgpu`, and nothing else — which is what a browser's canvas answers once it has given one.
+   * The engine never asks for another here: the backend is chosen before a context is taken.
+   */
+  getContext(kind: string): GPUCanvasContext | null {
+    if (kind !== 'webgpu') return null;
+    if (this.context === null) this.context = new NativeCanvasContext(this);
+    return this.context as unknown as GPUCanvasContext;
+  }
+
+  get tabIndex(): number {
+    return this.focusIndex ?? -1;
+  }
+
+  set tabIndex(index: number) {
+    this.focusIndex = Math.trunc(index);
+  }
+
+  /** Focus, through the page; nothing, as in a browser, for a canvas that is not focusable. */
+  focus(_options?: FocusOptions): void {
+    if (this.focusIndex !== null) this.focuser?.(true);
+  }
+
+  blur(): void {
+    this.focuser?.(false);
+  }
+
+  /** Capture, through the page, which is what knows the pointers (`pointerCapture.ts`). */
+  setPointerCapture(pointerId: number): void {
+    this.pointers().set(this, pointerId);
+  }
+
+  releasePointerCapture(pointerId: number): void {
+    this.pointers().release(this, pointerId);
+  }
+
+  hasPointerCapture(pointerId: number): boolean {
+    return this.capture?.has(this, pointerId) ?? false;
+  }
+
+  /** The document this canvas is in, once a page holds it. */
+  get ownerDocument(): PageDocument {
+    if (this.parentNode === null) {
+      throw new Error('[driftengine] a canvas no page holds is in no document');
+    }
+    return this.parentNode as PageDocument;
+  }
+
+  /** Fullscreen, through the page, which is what holds the window. */
+  requestFullscreen(_options?: FullscreenOptions): Promise<void> {
+    if (this.fullscreener === null) {
+      return Promise.reject(new TypeError('[driftengine] a canvas with no window cannot fill it'));
+    }
+    return this.fullscreener();
+  }
+
+  /** A canvas no page holds knows no pointers, so every id is unknown to it. */
+  private pointers(): PointerCapture {
+    return this.capture ?? new PointerCapture();
+  }
+
+  /** What a browser's canvas answers, through the page, which is what holds the lock. */
+  requestPointerLock(_options?: unknown): Promise<void> {
+    if (this.lockPointer === null) {
+      return Promise.reject(
+        new Error('[driftengine] a canvas with no window has no pointer to lock'),
+      );
+    }
+    return this.lockPointer();
+  }
+
+  /**
+   * The window's size, in device pixels, as the host is told it.
+   *
+   * **A window minimised to nothing keeps the last size it had.** It reports zero by zero, and a
+   * texture of no size is a validation error that invalidates every command buffer that touches
+   * it; the engine sizes its targets from this canvas, so this canvas never goes to zero. `visible`
+   * says there is nowhere to present to, and the host skips presenting until there is.
+   */
+  resizeTo(width: number, height: number): void {
+    if (width <= 0 || height <= 0) {
+      this.visible = false;
+      return;
+    }
+    this.visible = true;
+    this.width = width;
+    this.height = height;
+    this.cssWidth = width / this.pixelRatio;
+    this.cssHeight = height / this.pixelRatio;
+  }
+}
+
+export class NativeCanvasContext {
+  readonly canvas: NativeCanvas;
+  private configuration: GPUCanvasConfiguration | null = null;
+  private texture: GPUTexture | null = null;
+
+  constructor(canvas: NativeCanvas) {
+    this.canvas = canvas;
+  }
+
+  configure(configuration: GPUCanvasConfiguration): void {
+    this.dropTexture();
+    const asked = configuration.usage ?? RENDER_ATTACHMENT;
+    this.configuration = { ...configuration, usage: asked | TEXTURE_BINDING | COPY_SRC };
+  }
+
+  unconfigure(): void {
+    this.dropTexture();
+    this.configuration = null;
+  }
+
+  getConfiguration(): GPUCanvasConfiguration | null {
+    return this.configuration;
+  }
+
+  /**
+   * This frame's texture: the same one until the drawing buffer changes size, and a new one when it
+   * does, as a browser's is.
+   */
+  getCurrentTexture(): GPUTexture {
+    const configuration = this.configuration;
+    if (configuration === null) {
+      throw new Error('[driftengine] this canvas is not configured, so it has no frame to give');
+    }
+    const { width, height } = this.canvas;
+    const current = this.texture;
+    if (current !== null && current.width === width && current.height === height) return current;
+    this.dropTexture();
+    this.texture = configuration.device.createTexture({
+      label: 'native canvas',
+      size: { width, height },
+      format: configuration.format,
+      usage: configuration.usage ?? RENDER_ATTACHMENT,
+    });
+    return this.texture;
+  }
+
+  private dropTexture(): void {
+    this.texture?.destroy();
+    this.texture = null;
+  }
+}

package/src/canvasStyle.ts

@@ -0,0 +1,89 @@
+/**
+ * A canvas's `style`, which a page writes to as it would a browser's: the cursor is the window's,
+ * and anything else is kept and read back, meaning nothing without a layout.
+ *
+ * **A page sets a cursor on the canvas it draws in** — `grab` over a view it can drag, `pointer`
+ * over a button, `none` in a first-person game — and a canvas with no `style` answered each with a
+ * `TypeError` inside the page's handler. CSS names more cursors than SDL has, so each is the nearest
+ * of SDL's twelve: `grab` and `grabbing` are its hand, as is `pointer`, since SDL has no open palm.
+ * A cursor with fallbacks, `url(hand.png) 4 4, crosshair`, is its last keyword; an image cursor is
+ * not drawn.
+ */
+
+/** SDL's system cursor for a CSS keyword, or null for `none`, which hides it. */
+const SDL_CURSOR: Readonly<Record<string, string | null>> = {
+  auto: 'arrow',
+  default: 'arrow',
+  pointer: 'hand',
+  grab: 'hand',
+  grabbing: 'hand',
+  text: 'ibeam',
+  'vertical-text': 'ibeam',
+  wait: 'wait',
+  progress: 'waitarrow',
+  crosshair: 'crosshair',
+  move: 'sizeall',
+  'all-scroll': 'sizeall',
+  'not-allowed': 'no',
+  'no-drop': 'no',
+  'ew-resize': 'sizewe',
+  'col-resize': 'sizewe',
+  'e-resize': 'sizewe',
+  'w-resize': 'sizewe',
+  'ns-resize': 'sizens',
+  'row-resize': 'sizens',
+  'n-resize': 'sizens',
+  's-resize': 'sizens',
+  'nwse-resize': 'sizenwse',
+  'nw-resize': 'sizenwse',
+  'se-resize': 'sizenwse',
+  'nesw-resize': 'sizenesw',
+  'ne-resize': 'sizenesw',
+  'sw-resize': 'sizenesw',
+  none: null,
+};
+
+/** The SDL cursor a CSS `cursor` value asks for: null to hide it, the arrow for one SDL lacks. */
+export function sdlCursor(css: string): string | null {
+  const keyword = css.split(',').at(-1)?.trim().toLowerCase() ?? '';
+  const cursor = SDL_CURSOR[keyword];
+  return cursor === undefined ? 'arrow' : cursor;
+}
+
+const camel = (name: string) =>
+  name.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+
+export class CanvasStyle {
+  [property: string]: unknown;
+  #cursor = '';
+  readonly #onCursor: (css: string) => void;
+
+  constructor(onCursor: (css: string) => void) {
+    this.#onCursor = onCursor;
+  }
+
+  get cursor(): string {
+    return this.#cursor;
+  }
+
+  set cursor(css: string) {
+    this.#cursor = css;
+    this.#onCursor(css);
+  }
+
+  setProperty(name: string, value: string): void {
+    this[camel(name)] = value;
+  }
+
+  getPropertyValue(name: string): string {
+    const value = this[camel(name)];
+    return typeof value === 'string' ? value : '';
+  }
+
+  removeProperty(name: string): string {
+    const was = this.getPropertyValue(name);
+    if (camel(name) === 'cursor') this.cursor = '';
+    else delete this[camel(name)];
+    return was;
+  }
+}