@driftengine/native-host 4.0.0

package/src/threads.ts

@@ -0,0 +1,66 @@
+/**
+ * Real threads, as a page's `Worker`, with none of a page's conditions on shared memory.
+ *
+ * **A browser gives a page `SharedArrayBuffer` only when it is cross-origin isolated**, served with
+ * `Cross-Origin-Opener-Policy` and `Cross-Origin-Embedder-Policy` headers: a condition on every
+ * consumer's deployment, which is why the engine's pools are switches rather than defaults. Node
+ * has shared memory unconditionally, so on this host they run on real threads with nothing asked.
+ *
+ * **The engine is not told.** Its pools build their workers the way a page does, `new Worker(url)`,
+ * and hear from them through `onmessage` and `error` events; this is that `Worker` over
+ * `node:worker_threads`, each thread starting in `workerScope.mjs`, which gives the module a
+ * browser worker's scope. The core count is Node's own `navigator.hardwareConcurrency`, which is
+ * what the physics pool bounds itself by.
+ *
+ * What it gives up: a classic, non-module worker script, which a Node thread cannot load; the
+ * `name` and `credentials` options, which mean nothing without a page.
+ */
+
+import { Worker as NodeWorker } from 'node:worker_threads';
+
+const SCOPE = new URL('./workerScope.mjs', import.meta.url);
+
+export class HostWorker extends EventTarget {
+  onmessage: ((event: MessageEvent) => void) | null = null;
+  onerror: ((event: ErrorEvent) => void) | null = null;
+  private readonly thread: NodeWorker;
+
+  constructor(url: string | URL, _options?: WorkerOptions) {
+    super();
+    this.thread = new NodeWorker(SCOPE, { workerData: { url: String(url) } });
+    this.thread.on('message', (data: unknown) => {
+      const event = Object.assign(new Event('message'), { data }) as MessageEvent;
+      this.onmessage?.(event);
+      this.dispatchEvent(event);
+    });
+    this.thread.on('error', (error: Error) => {
+      const event = Object.assign(new Event('error'), {
+        message: error.message,
+        error,
+      }) as ErrorEvent;
+      this.onerror?.(event);
+      this.dispatchEvent(event);
+    });
+  }
+
+  postMessage(value: unknown, transfer?: readonly Transferable[]): void {
+    this.thread.postMessage(value, transfer as never);
+  }
+
+  terminate(): void {
+    void this.thread.terminate();
+  }
+}
+
+/** Answer `new Worker(url)` with a real thread, and hand back what takes it away again. */
+export function installThreads(
+  scope: Record<string, unknown> = globalThis as Record<string, unknown>,
+): () => void {
+  const had = 'Worker' in scope;
+  const before = scope['Worker'];
+  scope['Worker'] = HostWorker;
+  return () => {
+    if (had) scope['Worker'] = before;
+    else delete scope['Worker'];
+  };
+}

package/src/tileFiles.ts

@@ -0,0 +1,39 @@
+/**
+ * Texture tiles from a directory on disk: the texture streamer's `TileSource`, with no network.
+ *
+ * **A tile is a file named by its hash**, the 64-bit FNV-1a `hashTile` gives as sixteen hex
+ * characters, which is what the streamer asks for. A name that is anything else is answered
+ * `null` before the filesystem is touched, so a hash from a stale or hostile index cannot climb out
+ * of the directory.
+ *
+ * **A file that is not there is `null`, which the streamer remembers as missing** and stops asking
+ * for. One that is there and cannot be read is a deployment fault rather than an absence, so it is
+ * said, once a tile, and then counted as missing too: the streamer treats a refusal as an absence
+ * either way, and a world that never finishes loading with nothing said is what it exists to
+ * prevent.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import type { TileSource } from '@driftengine/texture';
+
+const TILE_NAME = /^[0-9a-f]{16}$/;
+
+export function tileFiles(directory: string): TileSource {
+  const said = new Set<string>();
+  return {
+    async fetch(hash: string): Promise<Uint8Array | null> {
+      if (!TILE_NAME.test(hash)) return null;
+      try {
+        return new Uint8Array(await readFile(join(directory, hash)));
+      } catch (cause) {
+        if ((cause as NodeJS.ErrnoException).code !== 'ENOENT' && !said.has(hash)) {
+          said.add(hash);
+          console.warn(`[driftengine] tile ${hash} is on disk and could not be read:`, cause);
+        }
+        return null;
+      }
+    },
+  };
+}

package/src/touchEvents.ts

@@ -0,0 +1,238 @@
+/**
+ * Fingers, as a page hears them from Chrome: pointer events of type `touch`, touch events, and the
+ * mouse events and click Chrome makes of a tap.
+ *
+ * **What Chrome sends, measured 2026-09-19 in Chrome 151 over the DevTools protocol** on a page
+ * whose canvas filled it, is what this sends:
+ * - A finger down is `pointerover`, `pointerenter` at the document and the canvas, `pointerdown`,
+ *   then `touchstart`. Fingers are pointers 2, 3 and on, never reused, the first down primary, and
+ *   a touch's `identifier` is the lowest one free.
+ * - A finger is captured by the canvas when it lands, so `gotpointercapture` comes before its next
+ *   event and `lostpointercapture` right after its `pointerup`, then `pointerout`, `pointerleave`
+ *   at the canvas and the document, and `touchend`.
+ * - A `touchmove` within 15 px of where the finger landed is not sent, unless the `touchstart` was
+ *   prevented; 13 px was held back and 17 px sent. A pointer move is always sent.
+ * - A tap — one finger, no further than 15 px, neither its `touchstart` nor its `touchend`
+ *   prevented — is then a mouse: `mouseover` and `mouseenter` the first time, `mousemove`,
+ *   `mousedown`, `mouseup`, and a `click` that is the finger's own pointer event. A second tap
+ *   landing within 400 ms of the first's lift and 20 px of it counts two, with a `dblclick`: 340 ms
+ *   counted and 380 did not, 20 px counted and 30 did not.
+ *
+ * **SDL makes a mouse of every finger**, and a finger of the mouse where asked; both are dropped,
+ * each already said by the other.
+ *
+ * What it gives up: SDL reports no contact size, so a finger is a pointer one pixel across; no
+ * `touchcancel`, which SDL never reports; and a `touchend` after a move is cancelable here, which
+ * Chrome's was not.
+ */
+
+import type { NativeCanvas } from './canvas.ts';
+import type { MouseWindow } from './mouseEvents.ts';
+import type { HostPage } from './page.ts';
+import { type ModifierInit, MouseEvent, type PointerInit, PointerEvent } from './uiEvents.ts';
+import { Touch, TouchEvent } from './uiTouch.ts';
+
+export interface SdlFinger {
+  readonly fingerId: number;
+  /** Across the window, from 0 to 1. */
+  readonly x: number;
+  readonly y: number;
+  readonly pressure: number;
+  /** A finger SDL made of the mouse. */
+  readonly mouse?: boolean;
+}
+
+interface Finger {
+  readonly identifier: number;
+  readonly pointerId: number;
+  readonly primary: boolean;
+  readonly landedAt: number;
+  readonly startX: number;
+  readonly startY: number;
+  x: number;
+  y: number;
+  pressure: number;
+  /** Past the slop: no longer a tap, and its moves are sent. */
+  travelled: boolean;
+}
+
+const SLOP_PX = 15;
+const DOUBLE_TAP_MS = 400;
+const DOUBLE_TAP_PX = 20;
+
+export class TouchModel {
+  private readonly fingers = new Map<number, Finger>();
+  private nextPointer = 2;
+  /** Whether this run of touches may still be a tap: one finger, nothing prevented. */
+  private tappable = true;
+  private lastTap = { liftedAt: Number.NEGATIVE_INFINITY, x: 0, y: 0, count: 0 };
+  /** Whether the mouse Chrome makes of taps is over the canvas yet. */
+  private mouseOver = false;
+
+  constructor(
+    private readonly window: MouseWindow,
+    private readonly page: HostPage,
+    private readonly canvas: NativeCanvas,
+    private readonly modifiers: () => ModifierInit,
+    private readonly now: () => number,
+  ) {}
+
+  down(event: SdlFinger): void {
+    if (event.mouse === true || this.fingers.has(event.fingerId)) return;
+    this.page.noteTouch();
+    const taken = new Set([...this.fingers.values()].map((f) => f.identifier));
+    let identifier = 0;
+    while (taken.has(identifier)) identifier += 1;
+    const primary = this.fingers.size === 0;
+    /* A second finger down makes the run a gesture of two, which is no tap. */
+    this.tappable = primary;
+    const x = event.x * this.window.width;
+    const y = event.y * this.window.height;
+    const finger: Finger = {
+      identifier,
+      pointerId: this.nextPointer,
+      primary,
+      landedAt: this.now(),
+      startX: x,
+      startY: y,
+      x,
+      y,
+      pressure: event.pressure,
+      travelled: false,
+    };
+    this.nextPointer += 1;
+    this.fingers.set(event.fingerId, finger);
+    const { capture, document } = this.page;
+    capture.add(finger.pointerId, () => this.fingers.get(event.fingerId) === finger);
+    const init = this.init(finger, 0, 1);
+    this.pointer('pointerover', init);
+    this.boundary('pointerenter', init, [document, this.canvas]);
+    this.pointer('pointerdown', init);
+    /* Held by the canvas it landed on, as a browser holds a finger, unless a listener chose. */
+    if (!capture.has(this.canvas, finger.pointerId)) capture.set(this.canvas, finger.pointerId);
+    if (!this.touch('touchstart', finger)) this.tappable = false;
+  }
+
+  move(event: SdlFinger): void {
+    const finger = this.fingers.get(event.fingerId);
+    if (event.mouse === true || finger === undefined) return;
+    finger.x = event.x * this.window.width;
+    finger.y = event.y * this.window.height;
+    finger.pressure = event.pressure;
+    if (Math.hypot(finger.x - finger.startX, finger.y - finger.startY) > SLOP_PX) {
+      finger.travelled = true;
+    }
+    this.pointer('pointermove', this.init(finger, -1, 1));
+    /* A move still inside the slop is held back, unless the page took the touch at its start. */
+    if (finger.travelled || !this.tappable) this.touch('touchmove', finger);
+  }
+
+  up(event: SdlFinger): void {
+    const finger = this.fingers.get(event.fingerId);
+    if (event.mouse === true || finger === undefined) return;
+    finger.x = event.x * this.window.width;
+    finger.y = event.y * this.window.height;
+    /* A finger lifted is a person's gesture, noted before its events so their listeners may use it. */
+    this.page.userActivation.notify();
+    /* The pointer's pressure is gone; the touch keeps the force it last had, as Chrome's did. */
+    const init: PointerInit = { ...this.init(finger, 0, 0), pressure: 0 };
+    this.pointer('pointerup', init);
+    this.page.capture.releaseImplicitly(finger.pointerId, init);
+    this.pointer('pointerout', init);
+    this.boundary('pointerleave', init, [this.canvas, this.page.document]);
+    this.fingers.delete(event.fingerId);
+    this.page.capture.remove(finger.pointerId);
+    const ended = this.touch('touchend', finger);
+    if (ended && this.tappable && !finger.travelled && this.fingers.size === 0) this.tap(finger);
+  }
+
+  /** The mouse Chrome makes of a tap, and its click. */
+  private tap(finger: Finger): void {
+    const last = this.lastTap;
+    const again =
+      finger.landedAt - last.liftedAt <= DOUBLE_TAP_MS &&
+      Math.hypot(finger.startX - last.x, finger.startY - last.y) <= DOUBLE_TAP_PX;
+    const count = again ? last.count + 1 : 1;
+    this.lastTap = { liftedAt: this.now(), x: finger.startX, y: finger.startY, count };
+    const at = { ...this.init(finger, -1, 0), clientX: finger.startX, clientY: finger.startY };
+    if (!this.mouseOver) {
+      this.mouseOver = true;
+      this.mouse('mouseover', at);
+      this.boundary('mouseenter', at, [this.page.document, this.canvas]);
+    }
+    this.mouse('mousemove', at);
+    const down = this.mouse('mousedown', { ...at, button: 0, buttons: 1, detail: count });
+    if (!down.defaultPrevented) this.canvas.focus();
+    this.mouse('mouseup', { ...at, button: 0, buttons: 0, detail: count });
+    this.canvas.dispatchEvent(
+      new PointerEvent('click', {
+        ...at,
+        button: 0,
+        buttons: 0,
+        detail: count,
+        isPrimary: false,
+        bubbles: true,
+        cancelable: true,
+      }),
+    );
+    if (count === 2) this.mouse('dblclick', { ...at, button: 0, buttons: 0, detail: count });
+  }
+
+  private init(finger: Finger, button: number, buttons: number): PointerInit {
+    return {
+      clientX: finger.x,
+      clientY: finger.y,
+      screenX: this.window.x + finger.x,
+      screenY: this.window.y + finger.y,
+      button,
+      buttons,
+      pressure: finger.pressure,
+      pointerId: finger.pointerId,
+      pointerType: 'touch',
+      isPrimary: finger.primary,
+      ...this.modifiers(),
+    };
+  }
+
+  private pointer(type: string, init: PointerInit): void {
+    this.page.capture.process(init.pointerId ?? 0, init);
+    this.canvas.dispatchEvent(new PointerEvent(type, { ...init, bubbles: true, cancelable: true }));
+  }
+
+  private mouse(type: string, init: PointerInit): MouseEvent {
+    const event = new MouseEvent(type, { ...init, bubbles: true, cancelable: true });
+    this.canvas.dispatchEvent(event);
+    return event;
+  }
+
+  /** An enter or a leave, which does not bubble: sent to each node it crosses, in turn. */
+  private boundary(type: string, init: PointerInit, nodes: readonly EventTarget[]): void {
+    const Kind = type.startsWith('pointer') ? PointerEvent : MouseEvent;
+    for (const node of nodes) node.dispatchEvent(new Kind(type, { ...init, bubbles: false }));
+  }
+
+  /** A touch event for `finger`, answering whether it went uncancelled. */
+  private touch(type: string, finger: Finger): boolean {
+    const touchOf = (f: Finger) =>
+      new Touch({
+        identifier: f.identifier,
+        target: this.canvas,
+        clientX: f.x,
+        clientY: f.y,
+        screenX: this.window.x + f.x,
+        screenY: this.window.y + f.y,
+        force: f.pressure,
+      });
+    const all = [...this.fingers.values()].map(touchOf);
+    const event = new TouchEvent(type, {
+      bubbles: true,
+      cancelable: true,
+      touches: all,
+      targetTouches: all,
+      changedTouches: [touchOf(finger)],
+      ...this.modifiers(),
+    });
+    this.canvas.dispatchEvent(event);
+    return !event.defaultPrevented;
+  }
+}

package/src/uiEvents.ts

@@ -0,0 +1,268 @@
+/**
+ * The browser's input events, for a runtime that has only `Event`: keys, the mouse, pointers, the
+ * wheel, touches, focus and pads, as classes with the members a browser's carry.
+ *
+ * **A page reads more of an event than the engine does.** The engine's input reads a key's `code`
+ * and a pointer's movement; a consumer's own code reads `getModifierState`, `detail` for a double
+ * click, the legacy `keyCode`, `pressure`, `offsetX`, or asks `instanceof PointerEvent`. An event
+ * assembled from a bare `Event` answers none of those, and the failure is a `TypeError` inside the
+ * consumer's handler or an `undefined` in its arithmetic. So each is its class, installed as the
+ * global a browser has, defaulting every member as the UI Events and Pointer Events specifications
+ * do.
+ *
+ * **Two of Chrome's own answers are kept where they differ from a first reading of those
+ * specifications**, both measured in Chrome 151 on 2026-09-19: a `MouseEvent` whose button did not
+ * change reports `button` 0 where a `PointerEvent` reports −1, and `which` is that raw button plus
+ * one, so 0 for a move either way.
+ *
+ * What it gives up: coordinates are the window's, which is the canvas's here, so `pageX` is
+ * `clientX` (nothing scrolls) and `offsetX` is measured from the target's box when it has one.
+ */
+
+type Modifier = 'AltGraph' | 'CapsLock' | 'NumLock';
+
+export interface ModifierInit {
+  readonly ctrlKey?: boolean;
+  readonly shiftKey?: boolean;
+  readonly altKey?: boolean;
+  readonly metaKey?: boolean;
+  readonly modifierAltGraph?: boolean;
+  readonly modifierCapsLock?: boolean;
+  readonly modifierNumLock?: boolean;
+}
+
+interface UiInit extends EventInit {
+  readonly detail?: number;
+  readonly view?: unknown;
+}
+
+export class UIEvent extends Event {
+  readonly detail: number;
+  readonly view: unknown;
+  constructor(type: string, init: UiInit = {}) {
+    super(type, init);
+    this.detail = init.detail ?? 0;
+    this.view = init.view ?? null;
+  }
+}
+
+/** `getModifierState`, which every event carrying modifiers answers the same way. */
+function modifierState(init: ModifierInit, key: string): boolean {
+  if (key === 'Shift') return init.shiftKey === true;
+  if (key === 'Control') return init.ctrlKey === true;
+  if (key === 'Alt') return init.altKey === true;
+  if (key === 'Meta') return init.metaKey === true;
+  const locked: Record<Modifier, boolean | undefined> = {
+    AltGraph: init.modifierAltGraph,
+    CapsLock: init.modifierCapsLock,
+    NumLock: init.modifierNumLock,
+  };
+  return locked[key as Modifier] === true;
+}
+
+export interface MouseInit extends UiInit, ModifierInit {
+  readonly screenX?: number;
+  readonly screenY?: number;
+  readonly clientX?: number;
+  readonly clientY?: number;
+  readonly movementX?: number;
+  readonly movementY?: number;
+  /** −1 where no button changed: a move, an enter, a leave. */
+  readonly button?: number;
+  readonly buttons?: number;
+  readonly relatedTarget?: EventTarget | null;
+}
+
+export class MouseEvent extends UIEvent {
+  readonly screenX: number;
+  readonly screenY: number;
+  readonly clientX: number;
+  readonly clientY: number;
+  readonly movementX: number;
+  readonly movementY: number;
+  readonly ctrlKey: boolean;
+  readonly shiftKey: boolean;
+  readonly altKey: boolean;
+  readonly metaKey: boolean;
+  readonly buttons: number;
+  readonly relatedTarget: EventTarget | null;
+  protected readonly rawButton: number;
+  private readonly modifiers: ModifierInit;
+
+  constructor(type: string, init: MouseInit = {}) {
+    super(type, init);
+    this.screenX = init.screenX ?? 0;
+    this.screenY = init.screenY ?? 0;
+    this.clientX = init.clientX ?? 0;
+    this.clientY = init.clientY ?? 0;
+    this.movementX = init.movementX ?? 0;
+    this.movementY = init.movementY ?? 0;
+    this.ctrlKey = init.ctrlKey === true;
+    this.shiftKey = init.shiftKey === true;
+    this.altKey = init.altKey === true;
+    this.metaKey = init.metaKey === true;
+    this.rawButton = init.button ?? 0;
+    this.buttons = init.buttons ?? 0;
+    this.relatedTarget = init.relatedTarget ?? null;
+    this.modifiers = init;
+  }
+
+  get button(): number {
+    return Math.max(this.rawButton, 0);
+  }
+  get which(): number {
+    return this.rawButton + 1;
+  }
+  get x(): number {
+    return this.clientX;
+  }
+  get y(): number {
+    return this.clientY;
+  }
+  get pageX(): number {
+    return this.clientX;
+  }
+  get pageY(): number {
+    return this.clientY;
+  }
+  get offsetX(): number {
+    return this.clientX - boxOf(this.target).left;
+  }
+  get offsetY(): number {
+    return this.clientY - boxOf(this.target).top;
+  }
+  getModifierState(key: string): boolean {
+    return modifierState(this.modifiers, key);
+  }
+}
+
+function boxOf(target: EventTarget | null): { left: number; top: number } {
+  const box = (target as { getBoundingClientRect?: () => DOMRect } | null)?.getBoundingClientRect;
+  return typeof box === 'function' ? box.call(target) : { left: 0, top: 0 };
+}
+
+export interface WheelInit extends MouseInit {
+  readonly deltaX?: number;
+  readonly deltaY?: number;
+  readonly deltaZ?: number;
+  readonly deltaMode?: number;
+}
+
+export class WheelEvent extends MouseEvent {
+  static readonly DOM_DELTA_PIXEL = 0;
+  static readonly DOM_DELTA_LINE = 1;
+  static readonly DOM_DELTA_PAGE = 2;
+  readonly deltaX: number;
+  readonly deltaY: number;
+  readonly deltaZ: number;
+  readonly deltaMode: number;
+  constructor(type: string, init: WheelInit = {}) {
+    super(type, init);
+    this.deltaX = init.deltaX ?? 0;
+    this.deltaY = init.deltaY ?? 0;
+    this.deltaZ = init.deltaZ ?? 0;
+    this.deltaMode = init.deltaMode ?? 0;
+  }
+}
+
+export interface PointerInit extends MouseInit {
+  readonly pointerId?: number;
+  readonly width?: number;
+  readonly height?: number;
+  readonly pressure?: number;
+  readonly pointerType?: string;
+  readonly isPrimary?: boolean;
+}
+
+export class PointerEvent extends MouseEvent {
+  readonly pointerId: number;
+  readonly width: number;
+  readonly height: number;
+  readonly pressure: number;
+  readonly tangentialPressure = 0;
+  readonly tiltX = 0;
+  readonly tiltY = 0;
+  readonly twist = 0;
+  readonly altitudeAngle = Math.PI / 2;
+  readonly azimuthAngle = 0;
+  readonly pointerType: string;
+  readonly isPrimary: boolean;
+  constructor(type: string, init: PointerInit = {}) {
+    super(type, init);
+    this.pointerId = init.pointerId ?? 0;
+    this.width = init.width ?? 1;
+    this.height = init.height ?? 1;
+    this.pressure = init.pressure ?? 0;
+    this.pointerType = init.pointerType ?? '';
+    this.isPrimary = init.isPrimary === true;
+  }
+  override get button(): number {
+    return this.rawButton;
+  }
+  /** A move stands for itself: this host coalesces nothing, so there is one event in it. */
+  getCoalescedEvents(): PointerEvent[] {
+    return this.type === 'pointermove' ? [this] : [];
+  }
+  getPredictedEvents(): PointerEvent[] {
+    return [];
+  }
+}
+
+export interface KeyInit extends UiInit, ModifierInit {
+  readonly key?: string;
+  readonly code?: string;
+  readonly location?: number;
+  readonly repeat?: boolean;
+  readonly isComposing?: boolean;
+  readonly keyCode?: number;
+  readonly charCode?: number;
+}
+
+export class KeyboardEvent extends UIEvent {
+  static readonly DOM_KEY_LOCATION_STANDARD = 0;
+  static readonly DOM_KEY_LOCATION_LEFT = 1;
+  static readonly DOM_KEY_LOCATION_RIGHT = 2;
+  static readonly DOM_KEY_LOCATION_NUMPAD = 3;
+  readonly key: string;
+  readonly code: string;
+  readonly location: number;
+  readonly repeat: boolean;
+  readonly isComposing: boolean;
+  readonly ctrlKey: boolean;
+  readonly shiftKey: boolean;
+  readonly altKey: boolean;
+  readonly metaKey: boolean;
+  /** The legacy pair: a key's code on `keydown` and `keyup`, a character's on `keypress`. */
+  readonly keyCode: number;
+  readonly charCode: number;
+  private readonly modifiers: ModifierInit;
+  constructor(type: string, init: KeyInit = {}) {
+    super(type, init);
+    this.key = init.key ?? '';
+    this.code = init.code ?? '';
+    this.location = init.location ?? 0;
+    this.repeat = init.repeat === true;
+    this.isComposing = init.isComposing === true;
+    this.ctrlKey = init.ctrlKey === true;
+    this.shiftKey = init.shiftKey === true;
+    this.altKey = init.altKey === true;
+    this.metaKey = init.metaKey === true;
+    this.keyCode = init.keyCode ?? 0;
+    this.charCode = init.charCode ?? 0;
+    this.modifiers = init;
+  }
+  get which(): number {
+    return this.keyCode;
+  }
+  getModifierState(key: string): boolean {
+    return modifierState(this.modifiers, key);
+  }
+}
+
+export class FocusEvent extends UIEvent {
+  readonly relatedTarget: EventTarget | null;
+  constructor(type: string, init: UiInit & { relatedTarget?: EventTarget | null } = {}) {
+    super(type, init);
+    this.relatedTarget = init.relatedTarget ?? null;
+  }
+}