@driftengine/native-host 4.0.0

package/dist/readback.js

@@ -0,0 +1,46 @@
+/**
+ * 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;
+/** Rows are copied at a stride of 256 bytes, which `copyTextureToBuffer` requires. */
+export function paddedRow(width) {
+    return 256 * Math.ceil((width * 4) / 256);
+}
+/** The padded rows, packed. */
+export function unpad(bytes, width, height) {
+    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) {
+    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/dist/runtime.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 { type AudioDefaults } from './audio.ts';
+import type { NativeBridge } from './bridge.ts';
+import type { NativeCanvas } from './canvas.ts';
+import { HostPage } from './page.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 declare function configDirectory(): string;
+export declare function startHost(options: HostOptions): NativeHost;

package/dist/runtime.js

@@ -0,0 +1,103 @@
+/**
+ * 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 { installAudio } from './audio.js';
+import { errorsOf } from './device.js';
+import { hostFetch } from './files.js';
+import { HostGamepads } from './gamepads.js';
+import { installGpu, installLocation } from './globals.js';
+import { installImages } from './images.js';
+import { HostPage } from './page.js';
+import { installThreads } from './threads.js';
+import { HostWindow } from './window.js';
+/** Where the desktop shell's Electron keeps application data on this platform. */
+export function configDirectory() {
+    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) {
+    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[BRIDGE_KEY] = bridge;
+    new HostGamepads(sdl.controller, {
+        joysticks: sdl.joystick,
+        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');
+                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/dist/standardPad.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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, type Rumbler } from './dualRumble.ts';
+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;
+}
+export declare const hex: (value: number | null) => string;
+export interface HostButton {
+    pressed: boolean;
+    touched: boolean;
+    value: number;
+}
+/** One controller in a slot, its state rewritten in place at every read. */
+export declare class StandardPad {
+    readonly index: number;
+    readonly source: PadController;
+    readonly id: string;
+    readonly mapping = "standard";
+    connected: boolean;
+    timestamp: number;
+    readonly buttons: HostButton[];
+    readonly axes: number[];
+    readonly vibrationActuator: DualRumble | null;
+    constructor(index: number, source: PadController);
+    read(now: number): void;
+}
+export {};

package/dist/standardPad.js

@@ -0,0 +1,80 @@
+/**
+ * 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 { dualRumble } from './dualRumble.js';
+/** The standard's buttons in its order, with the two triggers standing in at 6 and 7. */
+const STANDARD = [
+    'a',
+    'b',
+    'x',
+    'y',
+    'leftShoulder',
+    'rightShoulder',
+    'leftTrigger',
+    'rightTrigger',
+    'back',
+    'start',
+    'leftStick',
+    'rightStick',
+    'dpadUp',
+    'dpadDown',
+    'dpadLeft',
+    'dpadRight',
+    'guide',
+];
+const AXES = ['leftStickX', 'leftStickY', 'rightStickX', 'rightStickY'];
+/** Chrome's line for an analogue button, 30 of 255 (`kDefaultButtonPressedThreshold`). */
+const PRESSED_PAST = 30 / 255;
+export const hex = (value) => (value ?? 0).toString(16).padStart(4, '0');
+/** One controller in a slot, its state rewritten in place at every read. */
+export class StandardPad {
+    index;
+    source;
+    id;
+    mapping = 'standard';
+    connected = true;
+    timestamp = 0;
+    buttons = STANDARD.map(() => ({
+        pressed: false,
+        touched: false,
+        value: 0,
+    }));
+    axes = [0, 0, 0, 0];
+    vibrationActuator;
+    constructor(index, source) {
+        this.index = index;
+        this.source = source;
+        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) {
+        const { axes, buttons } = this.source;
+        for (let at = 0; at < STANDARD.length; at += 1) {
+            const name = STANDARD[at];
+            const button = this.buttons[at];
+            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]];
+        }
+        this.timestamp = now;
+    }
+}

package/dist/textHost.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 declare function createNativeTextHost(window: TextWindow, clipboard: TextClipboard): NativeTextHost;

package/dist/textHost.js

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+export function createNativeTextHost(window, clipboard) {
+    const pending = [];
+    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;
+        },
+    };
+}

package/dist/threads.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+export declare class HostWorker extends EventTarget {
+    onmessage: ((event: MessageEvent) => void) | null;
+    onerror: ((event: ErrorEvent) => void) | null;
+    private readonly thread;
+    constructor(url: string | URL, _options?: WorkerOptions);
+    postMessage(value: unknown, transfer?: readonly Transferable[]): void;
+    terminate(): void;
+}
+/** Answer `new Worker(url)` with a real thread, and hand back what takes it away again. */
+export declare function installThreads(scope?: Record<string, unknown>): () => void;

package/dist/threads.js

@@ -0,0 +1,59 @@
+/**
+ * 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 = null;
+    onerror = null;
+    thread;
+    constructor(url, _options) {
+        super();
+        this.thread = new NodeWorker(SCOPE, { workerData: { url: String(url) } });
+        this.thread.on('message', (data) => {
+            const event = Object.assign(new Event('message'), { data });
+            this.onmessage?.(event);
+            this.dispatchEvent(event);
+        });
+        this.thread.on('error', (error) => {
+            const event = Object.assign(new Event('error'), {
+                message: error.message,
+                error,
+            });
+            this.onerror?.(event);
+            this.dispatchEvent(event);
+        });
+    }
+    postMessage(value, transfer) {
+        this.thread.postMessage(value, transfer);
+    }
+    terminate() {
+        void this.thread.terminate();
+    }
+}
+/** Answer `new Worker(url)` with a real thread, and hand back what takes it away again. */
+export function installThreads(scope = globalThis) {
+    const had = 'Worker' in scope;
+    const before = scope['Worker'];
+    scope['Worker'] = HostWorker;
+    return () => {
+        if (had)
+            scope['Worker'] = before;
+        else
+            delete scope['Worker'];
+    };
+}

package/dist/tileFiles.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 type { TileSource } from '@driftengine/texture';
+export declare function tileFiles(directory: string): TileSource;

package/dist/tileFiles.js

@@ -0,0 +1,36 @@
+/**
+ * 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';
+const TILE_NAME = /^[0-9a-f]{16}$/;
+export function tileFiles(directory) {
+    const said = new Set();
+    return {
+        async fetch(hash) {
+            if (!TILE_NAME.test(hash))
+                return null;
+            try {
+                return new Uint8Array(await readFile(join(directory, hash)));
+            }
+            catch (cause) {
+                if (cause.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/dist/touchEvents.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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 } from './uiEvents.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;
+}
+export declare class TouchModel {
+    private readonly window;
+    private readonly page;
+    private readonly canvas;
+    private readonly modifiers;
+    private readonly now;
+    private readonly fingers;
+    private nextPointer;
+    /** Whether this run of touches may still be a tap: one finger, nothing prevented. */
+    private tappable;
+    private lastTap;
+    /** Whether the mouse Chrome makes of taps is over the canvas yet. */
+    private mouseOver;
+    constructor(window: MouseWindow, page: HostPage, canvas: NativeCanvas, modifiers: () => ModifierInit, now: () => number);
+    down(event: SdlFinger): void;
+    move(event: SdlFinger): void;
+    up(event: SdlFinger): void;
+    /** The mouse Chrome makes of a tap, and its click. */
+    private tap;
+    private init;
+    private pointer;
+    private mouse;
+    /** An enter or a leave, which does not bubble: sent to each node it crosses, in turn. */
+    private boundary;
+    /** A touch event for `finger`, answering whether it went uncancelled. */
+    private touch;
+}