@driftengine/native-host 4.0.0

package/dist/touchEvents.js

@@ -0,0 +1,210 @@
+/**
+ * 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 { MouseEvent, PointerEvent } from './uiEvents.js';
+import { Touch, TouchEvent } from './uiTouch.js';
+const SLOP_PX = 15;
+const DOUBLE_TAP_MS = 400;
+const DOUBLE_TAP_PX = 20;
+export class TouchModel {
+    window;
+    page;
+    canvas;
+    modifiers;
+    now;
+    fingers = new Map();
+    nextPointer = 2;
+    /** Whether this run of touches may still be a tap: one finger, nothing prevented. */
+    tappable = true;
+    lastTap = { liftedAt: Number.NEGATIVE_INFINITY, x: 0, y: 0, count: 0 };
+    /** Whether the mouse Chrome makes of taps is over the canvas yet. */
+    mouseOver = false;
+    constructor(window, page, canvas, modifiers, now) {
+        this.window = window;
+        this.page = page;
+        this.canvas = canvas;
+        this.modifiers = modifiers;
+        this.now = now;
+    }
+    down(event) {
+        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 = {
+            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) {
+        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) {
+        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 = { ...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. */
+    tap(finger) {
+        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 });
+    }
+    init(finger, button, buttons) {
+        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(),
+        };
+    }
+    pointer(type, init) {
+        this.page.capture.process(init.pointerId ?? 0, init);
+        this.canvas.dispatchEvent(new PointerEvent(type, { ...init, bubbles: true, cancelable: true }));
+    }
+    mouse(type, init) {
+        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. */
+    boundary(type, init, nodes) {
+        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. */
+    touch(type, finger) {
+        const touchOf = (f) => 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/dist/uiEvents.d.ts

@@ -0,0 +1,157 @@
+/**
+ * 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.
+ */
+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 declare class UIEvent extends Event {
+    readonly detail: number;
+    readonly view: unknown;
+    constructor(type: string, init?: UiInit);
+}
+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 declare 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;
+    constructor(type: string, init?: MouseInit);
+    get button(): number;
+    get which(): number;
+    get x(): number;
+    get y(): number;
+    get pageX(): number;
+    get pageY(): number;
+    get offsetX(): number;
+    get offsetY(): number;
+    getModifierState(key: string): boolean;
+}
+export interface WheelInit extends MouseInit {
+    readonly deltaX?: number;
+    readonly deltaY?: number;
+    readonly deltaZ?: number;
+    readonly deltaMode?: number;
+}
+export declare 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);
+}
+export interface PointerInit extends MouseInit {
+    readonly pointerId?: number;
+    readonly width?: number;
+    readonly height?: number;
+    readonly pressure?: number;
+    readonly pointerType?: string;
+    readonly isPrimary?: boolean;
+}
+export declare 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: number;
+    readonly azimuthAngle = 0;
+    readonly pointerType: string;
+    readonly isPrimary: boolean;
+    constructor(type: string, init?: PointerInit);
+    get button(): number;
+    /** A move stands for itself: this host coalesces nothing, so there is one event in it. */
+    getCoalescedEvents(): PointerEvent[];
+    getPredictedEvents(): PointerEvent[];
+}
+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 declare 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;
+    constructor(type: string, init?: KeyInit);
+    get which(): number;
+    getModifierState(key: string): boolean;
+}
+export declare class FocusEvent extends UIEvent {
+    readonly relatedTarget: EventTarget | null;
+    constructor(type: string, init?: UiInit & {
+        relatedTarget?: EventTarget | null;
+    });
+}
+export {};

package/dist/uiEvents.js

@@ -0,0 +1,206 @@
+/**
+ * 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.
+ */
+export class UIEvent extends Event {
+    detail;
+    view;
+    constructor(type, init = {}) {
+        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, key) {
+    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 = {
+        AltGraph: init.modifierAltGraph,
+        CapsLock: init.modifierCapsLock,
+        NumLock: init.modifierNumLock,
+    };
+    return locked[key] === true;
+}
+export class MouseEvent extends UIEvent {
+    screenX;
+    screenY;
+    clientX;
+    clientY;
+    movementX;
+    movementY;
+    ctrlKey;
+    shiftKey;
+    altKey;
+    metaKey;
+    buttons;
+    relatedTarget;
+    rawButton;
+    modifiers;
+    constructor(type, init = {}) {
+        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() {
+        return Math.max(this.rawButton, 0);
+    }
+    get which() {
+        return this.rawButton + 1;
+    }
+    get x() {
+        return this.clientX;
+    }
+    get y() {
+        return this.clientY;
+    }
+    get pageX() {
+        return this.clientX;
+    }
+    get pageY() {
+        return this.clientY;
+    }
+    get offsetX() {
+        return this.clientX - boxOf(this.target).left;
+    }
+    get offsetY() {
+        return this.clientY - boxOf(this.target).top;
+    }
+    getModifierState(key) {
+        return modifierState(this.modifiers, key);
+    }
+}
+function boxOf(target) {
+    const box = target?.getBoundingClientRect;
+    return typeof box === 'function' ? box.call(target) : { left: 0, top: 0 };
+}
+export class WheelEvent extends MouseEvent {
+    static DOM_DELTA_PIXEL = 0;
+    static DOM_DELTA_LINE = 1;
+    static DOM_DELTA_PAGE = 2;
+    deltaX;
+    deltaY;
+    deltaZ;
+    deltaMode;
+    constructor(type, init = {}) {
+        super(type, init);
+        this.deltaX = init.deltaX ?? 0;
+        this.deltaY = init.deltaY ?? 0;
+        this.deltaZ = init.deltaZ ?? 0;
+        this.deltaMode = init.deltaMode ?? 0;
+    }
+}
+export class PointerEvent extends MouseEvent {
+    pointerId;
+    width;
+    height;
+    pressure;
+    tangentialPressure = 0;
+    tiltX = 0;
+    tiltY = 0;
+    twist = 0;
+    altitudeAngle = Math.PI / 2;
+    azimuthAngle = 0;
+    pointerType;
+    isPrimary;
+    constructor(type, init = {}) {
+        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;
+    }
+    get button() {
+        return this.rawButton;
+    }
+    /** A move stands for itself: this host coalesces nothing, so there is one event in it. */
+    getCoalescedEvents() {
+        return this.type === 'pointermove' ? [this] : [];
+    }
+    getPredictedEvents() {
+        return [];
+    }
+}
+export class KeyboardEvent extends UIEvent {
+    static DOM_KEY_LOCATION_STANDARD = 0;
+    static DOM_KEY_LOCATION_LEFT = 1;
+    static DOM_KEY_LOCATION_RIGHT = 2;
+    static DOM_KEY_LOCATION_NUMPAD = 3;
+    key;
+    code;
+    location;
+    repeat;
+    isComposing;
+    ctrlKey;
+    shiftKey;
+    altKey;
+    metaKey;
+    /** The legacy pair: a key's code on `keydown` and `keyup`, a character's on `keypress`. */
+    keyCode;
+    charCode;
+    modifiers;
+    constructor(type, init = {}) {
+        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() {
+        return this.keyCode;
+    }
+    getModifierState(key) {
+        return modifierState(this.modifiers, key);
+    }
+}
+export class FocusEvent extends UIEvent {
+    relatedTarget;
+    constructor(type, init = {}) {
+        super(type, init);
+        this.relatedTarget = init.relatedTarget ?? null;
+    }
+}

package/dist/uiTouch.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Touches, as a browser's page reads them: `Touch`, the `TouchList` three of which a `TouchEvent`
+ * carries, and the event. The sibling of `uiEvents.ts`, split out only so each stays one screenful.
+ *
+ * A `TouchList` indexes, iterates and answers `item`, the three ways a page reads one; the engine's
+ * input reads `changedTouches[i]`.
+ */
+import { type ModifierInit, UIEvent } from './uiEvents.ts';
+export interface TouchInit {
+    readonly identifier: number;
+    readonly target: EventTarget;
+    readonly clientX?: number;
+    readonly clientY?: number;
+    readonly screenX?: number;
+    readonly screenY?: number;
+    readonly radiusX?: number;
+    readonly radiusY?: number;
+    readonly force?: number;
+}
+export declare class Touch {
+    readonly identifier: number;
+    readonly target: EventTarget;
+    readonly clientX: number;
+    readonly clientY: number;
+    readonly screenX: number;
+    readonly screenY: number;
+    readonly radiusX: number;
+    readonly radiusY: number;
+    readonly rotationAngle = 0;
+    readonly force: number;
+    readonly altitudeAngle: number;
+    readonly azimuthAngle = 0;
+    readonly touchType = "direct";
+    constructor(init: TouchInit);
+    get pageX(): number;
+    get pageY(): number;
+}
+export declare class TouchList {
+    readonly length: number;
+    [index: number]: Touch;
+    constructor(touches?: readonly Touch[]);
+    item(index: number): Touch | null;
+    [Symbol.iterator](): IterableIterator<Touch>;
+}
+export interface TouchEventInit extends EventInit, ModifierInit {
+    readonly touches?: readonly Touch[];
+    readonly targetTouches?: readonly Touch[];
+    readonly changedTouches?: readonly Touch[];
+}
+export declare class TouchEvent extends UIEvent {
+    readonly touches: TouchList;
+    readonly targetTouches: TouchList;
+    readonly changedTouches: TouchList;
+    readonly ctrlKey: boolean;
+    readonly shiftKey: boolean;
+    readonly altKey: boolean;
+    readonly metaKey: boolean;
+    constructor(type: string, init?: TouchEventInit);
+}