@driftengine/native-host 4.0.0

package/dist/page.js

@@ -0,0 +1,302 @@
+/**
+ * The page a scene expects around its canvas, for a host that has none: `window`, `document`, and
+ * the animation frames a browser schedules.
+ *
+ * **What is here is what gets read**, listed from every listener and property the engine's packages
+ * and the published scenes reach: keys, pointers, the mouse, the wheel, focus, resizing and
+ * unloading on `window`; visibility, focus and pointer lock on `document`; `requestAnimationFrame`,
+ * which the engine's input polls from. The three are a tree (`domTree.ts`), so an event is
+ * captured and bubbles as it does in a browser, and each answers the `on…` attributes. Anything
+ * else a scene reaches for is a gap named when it is met — `createElement` refuses by name —
+ * rather than a DOM this pretends to be.
+ *
+ * **Focus is a browser's.** The window has it or not, as SDL says; within it the canvas is focused
+ * only once it is focusable, which a canvas is when it is given a `tabIndex`, and keys go to what
+ * is focused, or to the document when nothing is.
+ *
+ * **A `document` is what the engine's splash looks for**, and it mounts one unless the scene says
+ * `splash: false` or the page carries a shell's bridge (`__driftHost`). The published scenes all
+ * say so; a packaged game is given the bridge.
+ */
+import { UserActivation } from './activation.js';
+import { HostNode } from './domTree.js';
+import { installEventClasses } from './eventClasses.js';
+import { PageFullscreen } from './fullscreen.js';
+import { MediaQueries } from './mediaQueries.js';
+import { PointerCapture } from './pointerCapture.js';
+import { FocusEvent } from './uiEvents.js';
+/** Every input event a page can be told of, which each of the three nodes answers `on…` for. */
+export const INPUT_TYPES = [
+    ...['keydown', 'keypress', 'keyup', 'focus', 'blur', 'wheel', 'contextmenu'],
+    ...['click', 'dblclick', 'auxclick', 'mousedown', 'mouseup', 'mousemove'],
+    ...['mouseover', 'mouseout', 'mouseenter', 'mouseleave'],
+    ...['pointerdown', 'pointerup', 'pointermove', 'pointerover', 'pointerout'],
+    ...['pointerenter', 'pointerleave', 'pointercancel', 'gotpointercapture', 'lostpointercapture'],
+    ...['touchstart', 'touchmove', 'touchend', 'touchcancel', 'fullscreenchange', 'fullscreenerror'],
+];
+const WINDOW_TYPES = ['resize', 'beforeunload', 'gamepadconnected', 'gamepaddisconnected'];
+const DOCUMENT_TYPES = [
+    'visibilitychange',
+    'pointerlockchange',
+    'pointerlockerror',
+    'fullscreenchange',
+    'fullscreenerror',
+];
+export class PageWindow extends HostNode {
+    canvas = null;
+    /** Answered by the page, which knows what a query asks about (`mediaQueries.ts`). */
+    matchMedia = () => {
+        throw new Error('[driftengine] a window no page holds has no media to query');
+    };
+    get innerWidth() {
+        return this.canvas?.clientWidth ?? 0;
+    }
+    get innerHeight() {
+        return this.canvas?.clientHeight ?? 0;
+    }
+    get devicePixelRatio() {
+        return this.canvas?.pixelRatio ?? 1;
+    }
+    static {
+        HostNode.handles(PageWindow.prototype, [...INPUT_TYPES, ...WINDOW_TYPES]);
+    }
+}
+export class PageDocument extends HostNode {
+    visibilityState = 'visible';
+    pointerLockElement = null;
+    /** What is focused: the canvas, once it is focusable and asked, or nothing. */
+    activeElement = null;
+    /** Set by the page that owns this document, which is what holds the lock and the focus. */
+    release = null;
+    focused = true;
+    /** The page's fullscreen, which this document reports. */
+    fullscreenControl = null;
+    fullscreenEnabled = true;
+    get fullscreenElement() {
+        return this.fullscreenControl?.element ?? null;
+    }
+    /** The legacy flag, still read. */
+    get fullscreen() {
+        return this.fullscreenElement !== null;
+    }
+    exitFullscreen() {
+        return this.fullscreenControl?.exit() ?? Promise.resolve();
+    }
+    get hidden() {
+        return this.visibilityState !== 'visible';
+    }
+    hasFocus() {
+        return this.focused;
+    }
+    exitPointerLock() {
+        this.release?.();
+    }
+    createElement(tag) {
+        throw new Error(`[driftengine] the native host has no DOM to make a <${tag}> in`);
+    }
+    static {
+        HostNode.handles(PageDocument.prototype, [...INPUT_TYPES, ...DOCUMENT_TYPES]);
+    }
+}
+export class HostPage {
+    window = new PageWindow();
+    document = new PageDocument();
+    /** Whether a person has just done something (`activation.ts`), as `navigator.userActivation`. */
+    userActivation;
+    fullscreen;
+    /** Which pointers the page holds (`pointerCapture.ts`). */
+    capture = new PointerCapture();
+    media;
+    /** Whether a finger has landed: the one proof of a touch screen SDL gives. */
+    touched = false;
+    /* Two queues swapped each frame, so a frame allocates nothing and asks made during it wait. */
+    asked = new Map();
+    due = new Map();
+    nextId = 1;
+    lockListeners = [];
+    locker = null;
+    constructor(options = {}) {
+        this.userActivation = new UserActivation(options.now ?? (() => performance.now()));
+        this.fullscreen = new PageFullscreen(this.userActivation);
+        this.document.parentNode = this.window;
+        this.document.release = () => this.unlock();
+        this.document.fullscreenControl = this.fullscreen;
+        this.fullscreen.changed = () => this.media.changed();
+        this.media = new MediaQueries(() => ({
+            width: this.window.innerWidth,
+            height: this.window.innerHeight,
+            pixelRatio: this.window.devicePixelRatio,
+            fullscreen: this.document.fullscreenElement !== null,
+            touched: this.touched,
+        }));
+        this.window.matchMedia = (query) => this.media.match(query);
+    }
+    /** A finger landed, so this is a touch screen, whatever SDL listed. */
+    noteTouch() {
+        if (this.touched)
+            return;
+        this.touched = true;
+        this.media.changed();
+    }
+    requestAnimationFrame = (callback) => {
+        const id = this.nextId;
+        this.nextId += 1;
+        this.asked.set(id, callback);
+        return id;
+    };
+    cancelAnimationFrame = (id) => {
+        this.asked.delete(id);
+        this.due.delete(id);
+    };
+    /** One frame: the callbacks asked for before it began, in the order they were asked. */
+    runFrame(now) {
+        const due = this.asked;
+        this.asked = this.due;
+        this.due = due;
+        for (const [id, callback] of due) {
+            /* Looked up again, so a callback cancelled by an earlier one this frame does not run. */
+            if (!due.has(id))
+                continue;
+            due.delete(id);
+            callback(now);
+        }
+    }
+    /** Whether the window can be seen, as `document.visibilityState` reports it. */
+    setVisible(visible) {
+        const state = visible ? 'visible' : 'hidden';
+        if (this.document.visibilityState === state)
+            return;
+        this.document.visibilityState = state;
+        this.document.dispatchEvent(new Event('visibilitychange'));
+    }
+    /**
+     * The window gaining or losing the focus: the focused canvas is told first, as the element a
+     * browser blurs, and then the window.
+     */
+    setFocused(focused) {
+        if (this.document.focused === focused)
+            return;
+        this.document.focused = focused;
+        const canvas = this.document.activeElement;
+        if (canvas !== null)
+            focusEvents(canvas, focused);
+        this.window.dispatchEvent(new FocusEvent(focused ? 'focus' : 'blur'));
+    }
+    /** Where a key goes: the focused element, or the document when nothing is focused. */
+    keyTarget() {
+        return this.document.activeElement ?? this.document;
+    }
+    /** Hold `canvas` in this page: its parent, its pointer lock and its focus are the page's. */
+    attach(canvas) {
+        canvas.parentNode = this.document;
+        this.window.canvas = canvas;
+        canvas.lockPointer = () => {
+            if (!this.userActivation.isActive) {
+                this.document.dispatchEvent(new Event('pointerlockerror', { bubbles: true }));
+                return Promise.reject(refusal('NotAllowedError', 'A user gesture is required to request Pointer Lock.'));
+            }
+            return this.lock(canvas)
+                ? Promise.resolve()
+                : Promise.reject(refusal('NotAllowedError', '[driftengine] the window could not hold the pointer'));
+        };
+        canvas.fullscreener = () => this.fullscreen.request(canvas);
+        canvas.capture = this.capture;
+        canvas.focuser = (focus) => {
+            const now = this.document.activeElement;
+            if (focus === (now === canvas))
+                return;
+            this.document.activeElement = focus ? canvas : null;
+            if (this.document.focused)
+                focusEvents(canvas, focus);
+        };
+    }
+    /**
+     * The platform's half of the lock: hide the cursor and hold it, or let it go. Answers false when it
+     * cannot — a window without focus, as a hidden one is — and the lock is then refused, the way a
+     * browser refuses one: the promise rejects and `pointerlockerror` fires, and nothing is locked.
+     */
+    setPointerLocker(locker) {
+        this.locker = locker;
+    }
+    /** The platform's half of fullscreen: put the window in it or take it out, false when it cannot. */
+    setFullscreener(setter) {
+        this.fullscreen.setter = setter;
+    }
+    /** Told when the lock is taken or released. */
+    onPointerLock(listener) {
+        this.lockListeners.push(listener);
+    }
+    unlock() {
+        if (this.document.pointerLockElement === null)
+            return;
+        this.locker?.(false);
+        this.document.pointerLockElement = null;
+        this.changedLock(false);
+    }
+    /** Put the globals a page has on `scope`, and hand back what takes them off again. */
+    install(scope = globalThis) {
+        const names = [
+            'window',
+            'document',
+            'requestAnimationFrame',
+            'cancelAnimationFrame',
+            'devicePixelRatio',
+            'matchMedia',
+        ];
+        const held = names.map((name) => [name, Object.getOwnPropertyDescriptor(scope, name)]);
+        scope['window'] = this.window;
+        scope['document'] = this.document;
+        scope['requestAnimationFrame'] = this.requestAnimationFrame;
+        scope['cancelAnimationFrame'] = this.cancelAnimationFrame;
+        scope['matchMedia'] = this.window.matchMedia;
+        Object.defineProperty(scope, 'devicePixelRatio', {
+            get: () => this.window.devicePixelRatio,
+            configurable: true,
+        });
+        const classes = installEventClasses(scope);
+        /* Node has a `navigator` of its own, behind a getter, so it is added to rather than replaced. */
+        const navigator = scope['navigator'];
+        if (navigator !== undefined) {
+            Object.defineProperty(navigator, 'userActivation', {
+                value: this.userActivation,
+                configurable: true,
+            });
+        }
+        return () => {
+            classes();
+            if (navigator !== undefined)
+                delete navigator.userActivation;
+            for (const [name, descriptor] of held) {
+                if (descriptor === undefined)
+                    delete scope[name];
+                else
+                    Object.defineProperty(scope, name, descriptor);
+            }
+        };
+    }
+    lock(element) {
+        if (this.document.pointerLockElement === element)
+            return true;
+        if (this.locker !== null && !this.locker(true)) {
+            this.document.dispatchEvent(new Event('pointerlockerror', { bubbles: true }));
+            return false;
+        }
+        this.document.pointerLockElement = element;
+        this.changedLock(true);
+        return true;
+    }
+    changedLock(locked) {
+        this.document.dispatchEvent(new Event('pointerlockchange', { bubbles: true }));
+        for (const listener of this.lockListeners)
+            listener(locked);
+    }
+}
+/** `focus` and `focusin`, or `blur` and `focusout`: the first stays on the element, the second bubbles. */
+function focusEvents(canvas, focused) {
+    canvas.dispatchEvent(new FocusEvent(focused ? 'focus' : 'blur'));
+    canvas.dispatchEvent(new FocusEvent(focused ? 'focusin' : 'focusout', { bubbles: true }));
+}
+/** A `DOMException`-shaped refusal: a browser's error name, with its message. */
+function refusal(name, message) {
+    return Object.assign(new Error(message), { name });
+}

package/dist/pointerCapture.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Pointer capture: `setPointerCapture`, `releasePointerCapture` and `hasPointerCapture` on the
+ * canvas, and `gotpointercapture` and `lostpointercapture` when it changes.
+ *
+ * **As the Pointer Events specification processes it, and in the order Chrome sends it** — measured
+ * 2026-09-19 in Chrome 151 over the DevTools protocol. A capture asked for is pending, and
+ * `hasPointerCapture` already says so; it is taken, and `gotpointercapture` sent, just before that
+ * pointer's next event. A pointer's release lets it go at once, so `lostpointercapture` falls
+ * between the `mouseup` and the `click`. A mouse with no button down cannot be captured, and the
+ * request is dropped without a word; an id that is no pointer is refused as Chrome refuses it.
+ *
+ * **What capture moves here is when things are told, not where.** A browser retargets a captured
+ * pointer's events at the capturing element; this host has one element, which is every target
+ * already, and SDL keeps a pressed pointer to the window past its edge.
+ */
+import type { HostNode } from './domTree.ts';
+import { type PointerInit } from './uiEvents.ts';
+export declare class PointerCapture {
+    /** Each pointer a page can capture, and whether it is pressed — in contact, or a button down. */
+    private readonly pointers;
+    private readonly pending;
+    private readonly current;
+    add(pointerId: number, pressed: () => boolean): void;
+    remove(pointerId: number): void;
+    set(element: HostNode, pointerId: number): void;
+    release(element: HostNode, pointerId: number): void;
+    has(element: HostNode, pointerId: number): boolean;
+    /** Before a pointer's next event: a change of capture, told with that event's fields. */
+    process(pointerId: number, init: PointerInit): void;
+    /** After a pointer's up or cancel: its capture is let go, and told at once. */
+    releaseImplicitly(pointerId: number, init: PointerInit): void;
+}

package/dist/pointerCapture.js

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

package/dist/present.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Putting the engine's frame in the window: one full-screen triangle, reading the canvas's texture.
+ *
+ * **A browser presents a canvas by itself and a host has to.** The engine draws into the canvas's
+ * current texture and stops; this copies that texture into the window's swap chain.
+ *
+ * **Decoded to linear on the way into an sRGB swap chain**, because Dawn's window renderer hands back
+ * `bgra8unorm-srgb`, and writing into one encodes. The engine has already graded and encoded its
+ * frame, so writing its bytes as they are would encode them a second time and every picture would
+ * come out paler. Decoding first puts the engine's own bytes on the screen, within a step of
+ * rounding. **The pixel gate reads the canvas texture, not the window**, so that rounding is on the
+ * screen and never in a comparison.
+ */
+/** Whether writing into `format` encodes, so the blit has to decode first. */
+export declare function encodesOnWrite(format: GPUTextureFormat): boolean;
+/** The blit's source, with the decode chosen for the swap chain it writes into. */
+export declare function blitSource(target: GPUTextureFormat): string;
+/** One pipeline, and one bind group a frame texture, made when they are first needed. */
+export declare class Presenter {
+    private readonly device;
+    private readonly pipeline;
+    private source;
+    private group;
+    constructor(device: GPUDevice, target: GPUTextureFormat);
+    /** Draw `frame` into `view`, and submit. */
+    present(frame: GPUTexture, view: GPUTextureView): void;
+}

package/dist/present.js

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

package/dist/rawPad.d.ts

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

package/dist/rawPad.js

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

package/dist/readback.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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`).
+ */
+export interface Frame {
+    readonly width: number;
+    readonly height: number;
+    /** Top row first, four bytes a pixel, in the canvas's own channel order. */
+    readonly rgba: Uint8Array;
+}
+/** Rows are copied at a stride of 256 bytes, which `copyTextureToBuffer` requires. */
+export declare function paddedRow(width: number): number;
+/** The padded rows, packed. */
+export declare function unpad(bytes: Uint8Array, width: number, height: number): Uint8Array;
+export declare function readFrame(context: GPUCanvasContext): Promise<Frame>;