@driftengine/native-host 4.0.0

package/dist/uiTouch.js

@@ -0,0 +1,75 @@
+/**
+ * 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 { UIEvent } from './uiEvents.js';
+export class Touch {
+    identifier;
+    target;
+    clientX;
+    clientY;
+    screenX;
+    screenY;
+    radiusX;
+    radiusY;
+    rotationAngle = 0;
+    force;
+    altitudeAngle = Math.PI / 2;
+    azimuthAngle = 0;
+    touchType = 'direct';
+    constructor(init) {
+        this.identifier = init.identifier;
+        this.target = init.target;
+        this.clientX = init.clientX ?? 0;
+        this.clientY = init.clientY ?? 0;
+        this.screenX = init.screenX ?? 0;
+        this.screenY = init.screenY ?? 0;
+        this.radiusX = init.radiusX ?? 0;
+        this.radiusY = init.radiusY ?? 0;
+        this.force = init.force ?? 0;
+    }
+    get pageX() {
+        return this.clientX;
+    }
+    get pageY() {
+        return this.clientY;
+    }
+}
+export class TouchList {
+    length;
+    constructor(touches = []) {
+        this.length = touches.length;
+        touches.forEach((touch, at) => {
+            this[at] = touch;
+        });
+    }
+    item(index) {
+        return this[index] ?? null;
+    }
+    *[Symbol.iterator]() {
+        for (let at = 0; at < this.length; at += 1)
+            yield this[at];
+    }
+}
+export class TouchEvent extends UIEvent {
+    touches;
+    targetTouches;
+    changedTouches;
+    ctrlKey;
+    shiftKey;
+    altKey;
+    metaKey;
+    constructor(type, init = {}) {
+        super(type, init);
+        this.touches = new TouchList(init.touches);
+        this.targetTouches = new TouchList(init.targetTouches);
+        this.changedTouches = new TouchList(init.changedTouches);
+        this.ctrlKey = init.ctrlKey === true;
+        this.shiftKey = init.shiftKey === true;
+        this.altKey = init.altKey === true;
+        this.metaKey = init.metaKey === true;
+    }
+}

package/dist/window.d.ts

@@ -0,0 +1,71 @@
+/**
+ * A window, the canvas the engine draws into, and the frame put on the screen.
+ *
+ * **SDL makes the window and Dawn draws into it**, through `@kmamal/sdl` and `@kmamal/gpu`: the
+ * composition chosen for this host on 2026-09-18, because Dawn is the WebGPU implementation inside
+ * Chrome and the host's gate is that the engine's frames match the browser's. SDL is also what the
+ * later tasks read input, audio and the clipboard from.
+ *
+ * **The window renderer is made from the engine's device, when the engine configures the canvas.**
+ * The engine asks `navigator.gpu` for its own adapter and device, as it does in a browser, so the
+ * host does not have one until the engine hands it over — which it does, in `configure`.
+ *
+ * **Teardown waits for the device.** Destroying the device, the instance or the window with work
+ * still in flight trips an assertion inside Dawn and takes the process with it (measured
+ * 2026-09-18); after `onSubmittedWorkDone` every order is clean.
+ */
+import type { NativeBridge } from './bridge.ts';
+import { NativeCanvas } from './canvas.ts';
+import type { NativeTextHost } from './textHost.ts';
+import { type WindowMode } from './windowMode.ts';
+import type { HostPage } from './page.ts';
+export interface HostWindowOptions {
+    readonly title: string;
+    readonly width: number;
+    readonly height: number;
+    /** A window that is never shown, for checks that should not flash on a desktop. */
+    readonly hidden?: boolean;
+    /** As a packaged game's manifest says; windowed and resizable when it says nothing. */
+    readonly mode?: WindowMode;
+    readonly resizable?: boolean;
+}
+export declare class HostWindow {
+    readonly canvas: NativeCanvas;
+    readonly gpu: GPU;
+    private readonly window;
+    private readonly instance;
+    private device;
+    private renderer;
+    private presenter;
+    private closed;
+    constructor(options: HostWindowOptions);
+    /**
+     * Put this window's canvas in `page`, and its keys, mouse, focus and size into `page`'s events.
+     * Hands back what disconnects them.
+     */
+    connectPage(page: HostPage): () => void;
+    /**
+     * The shell's bridge over this window, with its store at `storePath` (see `bridge.ts`). `quit` is
+     * how the host hears that the game, or the person closing the window, has ended the session.
+     */
+    createBridge(storePath: string, quit: () => void): NativeBridge;
+    /** The editor's text services over this window's typing and the desktop's clipboard. */
+    createTextHost(): NativeTextHost;
+    /** Whether the person closed it. */
+    /** A new title, made showable as the first one was (`windowTitle.ts`). */
+    setTitle(title: string): void;
+    /**
+     * Send `event` as SDL sends one, through the window's own emitter, for input a capture replays:
+     * it then takes the path a person's does, and counts as a gesture where theirs would.
+     */
+    replay(type: string, event: object): void;
+    get isClosed(): boolean;
+    /**
+     * Put the engine's last frame on the screen. Nothing happens before the engine has configured
+     * the canvas, or while the window is minimised to nothing.
+     */
+    present(): void;
+    /** Wait for the device, then let everything go in an order Dawn accepts. */
+    close(): Promise<void>;
+    private adopt;
+}

package/dist/window.js

@@ -0,0 +1,164 @@
+/**
+ * A window, the canvas the engine draws into, and the frame put on the screen.
+ *
+ * **SDL makes the window and Dawn draws into it**, through `@kmamal/sdl` and `@kmamal/gpu`: the
+ * composition chosen for this host on 2026-09-18, because Dawn is the WebGPU implementation inside
+ * Chrome and the host's gate is that the engine's frames match the browser's. SDL is also what the
+ * later tasks read input, audio and the clipboard from.
+ *
+ * **The window renderer is made from the engine's device, when the engine configures the canvas.**
+ * The engine asks `navigator.gpu` for its own adapter and device, as it does in a browser, so the
+ * host does not have one until the engine hands it over — which it does, in `configure`.
+ *
+ * **Teardown waits for the device.** Destroying the device, the instance or the window with work
+ * still in flight trips an assertion inside Dawn and takes the process with it (measured
+ * 2026-09-18); after `onSubmittedWorkDone` every order is clean.
+ */
+import gpuModule from '@kmamal/gpu';
+import sdl from '@kmamal/sdl';
+import { nativeBridge } from './bridge.js';
+import { NativeCanvas } from './canvas.js';
+import { desktopFiles } from './dialogs.js';
+import { createNativeTextHost } from './textHost.js';
+import { connectDomEvents } from './domEvents.js';
+import { sdlWindowFlags } from './windowMode.js';
+import { windowTitle } from './windowTitle.js';
+import { nativeGpu } from './gpu.js';
+import { Presenter } from './present.js';
+export class HostWindow {
+    canvas;
+    gpu;
+    window;
+    instance;
+    device = null;
+    renderer = null;
+    presenter = null;
+    closed = false;
+    constructor(options) {
+        this.window = sdl.video.createWindow({
+            title: windowTitle(options.title, sdl.info.drivers.video.current),
+            width: options.width,
+            height: options.height,
+            ...sdlWindowFlags(options.mode, options.resizable),
+            visible: options.hidden !== true,
+            webgpu: true,
+        });
+        this.canvas = new NativeCanvas(this.window.pixelWidth, this.window.pixelHeight);
+        this.instance = gpuModule.create([]);
+        this.gpu = nativeGpu(this.instance);
+        this.window.on('resize', ({ pixelWidth, pixelHeight }) => {
+            this.canvas.resizeTo(pixelWidth, pixelHeight);
+            this.renderer?.resize();
+        });
+        this.window.on('close', () => {
+            this.closed = true;
+        });
+        /*
+         * **A window nobody focused receives no keys, and SDL says so nowhere.**
+         *
+         * `@kmamal/sdl` routes a mouse event by which window is *hovered* and a key event by which one
+         * is *focused*, and it learns the second only from a `focus` event it may deliver before
+         * anything is listening — a window created and given focus by the desktop in the same breath
+         * leaves `Globals.windows.focused` null. The window then draws, answers the mouse, and is deaf:
+         * a maintainer reported exactly that on 2026-09-20, with clicks landing and the keyboard doing
+         * nothing.
+         *
+         * Asking for focus outright sets it, which is what an application does when it opens a window
+         * anyway. **Only a visible one**: a hidden window is for checks that must not take a desktop's
+         * focus away from whoever is using it.
+         */
+        if (options.hidden !== true)
+            this.window.focus();
+    }
+    /**
+     * Put this window's canvas in `page`, and its keys, mouse, focus and size into `page`'s events.
+     * Hands back what disconnects them.
+     */
+    connectPage(page) {
+        page.attach(this.canvas);
+        return connectDomEvents(this.window, sdl.mouse, page, this.canvas);
+    }
+    /**
+     * The shell's bridge over this window, with its store at `storePath` (see `bridge.ts`). `quit` is
+     * how the host hears that the game, or the person closing the window, has ended the session.
+     */
+    createBridge(storePath, quit) {
+        return nativeBridge({
+            window: this.window,
+            displays: () => sdl.video.displays,
+            storePath,
+            quit,
+            files: desktopFiles() ?? undefined,
+        });
+    }
+    /** The editor's text services over this window's typing and the desktop's clipboard. */
+    createTextHost() {
+        return createNativeTextHost(this.window, sdl.clipboard);
+    }
+    /** Whether the person closed it. */
+    /** A new title, made showable as the first one was (`windowTitle.ts`). */
+    setTitle(title) {
+        this.window.setTitle(windowTitle(title, sdl.info.drivers.video.current));
+    }
+    /**
+     * Send `event` as SDL sends one, through the window's own emitter, for input a capture replays:
+     * it then takes the path a person's does, and counts as a gesture where theirs would.
+     */
+    replay(type, event) {
+        this.window.emit(type, event);
+    }
+    get isClosed() {
+        return this.closed;
+    }
+    /**
+     * Put the engine's last frame on the screen. Nothing happens before the engine has configured
+     * the canvas, or while the window is minimised to nothing.
+     */
+    present() {
+        if (this.closed || !this.canvas.visible)
+            return;
+        const context = this.canvas.getContext('webgpu');
+        const configuration = context.getConfiguration();
+        if (configuration === null)
+            return;
+        if (this.device !== configuration.device)
+            this.adopt(configuration.device);
+        const renderer = this.renderer;
+        const presenter = this.presenter;
+        if (renderer === null || presenter === null)
+            return;
+        presenter.present(context.getCurrentTexture(), renderer.getCurrentTextureView());
+        renderer.swap();
+    }
+    /** Wait for the device, then let everything go in an order Dawn accepts. */
+    async close() {
+        await this.device?.queue.onSubmittedWorkDone();
+        this.closed = true;
+        /*
+         * **A window the person already closed is destroyed, and destroying it again throws.**
+         *
+         * SDL destroys a window when its close button is pressed, so a host that then shuts down in
+         * good order — which is the ordinary path, and the only one after a person closes a window —
+         * met `Error: window is destroyed` out of `sdl.video.window.destroy` and ended on a stack
+         * trace instead of a clean exit. Reported from a maintainer's own machine, 2026-09-20.
+         *
+         * **What it gives up:** a destroy that fails for some other reason is swallowed too. The
+         * instance below is released either way, which is the part that holds the process open.
+         */
+        try {
+            this.window.destroy();
+        }
+        catch {
+            /* Already gone, which is what closing a window does. */
+        }
+        gpuModule.destroy(this.instance);
+    }
+    adopt(device) {
+        this.device = device;
+        this.renderer = gpuModule.renderGPUDeviceToWindow({
+            device: device,
+            window: this.window,
+        });
+        this.presenter = new Presenter(device, this.renderer.getCurrentTexture().format);
+    }
+}

package/dist/windowMode.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The window a packaged game asked for, in SDL's flags: the manifest's `window.mode` and
+ * `window.resizable`, which the desktop shell hands to Electron's `BrowserWindow`.
+ *
+ * **Fullscreen is the desktop's**: `@kmamal/sdl` opens it as `SDL_WINDOW_FULLSCREEN_DESKTOP`,
+ * covering the screen at the screen's own resolution, which is what Electron's `fullscreen: true`
+ * is. No mode is switched. **Borderless** is a window with no frame, which is Electron's
+ * `frame: false`.
+ *
+ * What it gives up: nothing chooses the display. SDL opens the window on its first display, as
+ * Electron does.
+ */
+export type WindowMode = 'windowed' | 'borderless' | 'fullscreen';
+export interface WindowFlags {
+    readonly fullscreen: boolean;
+    readonly borderless: boolean;
+    readonly resizable: boolean;
+}
+export declare function sdlWindowFlags(mode?: WindowMode, resizable?: boolean): WindowFlags;

package/dist/windowMode.js

@@ -0,0 +1,15 @@
+/**
+ * The window a packaged game asked for, in SDL's flags: the manifest's `window.mode` and
+ * `window.resizable`, which the desktop shell hands to Electron's `BrowserWindow`.
+ *
+ * **Fullscreen is the desktop's**: `@kmamal/sdl` opens it as `SDL_WINDOW_FULLSCREEN_DESKTOP`,
+ * covering the screen at the screen's own resolution, which is what Electron's `fullscreen: true`
+ * is. No mode is switched. **Borderless** is a window with no frame, which is Electron's
+ * `frame: false`.
+ *
+ * What it gives up: nothing chooses the display. SDL opens the window on its first display, as
+ * Electron does.
+ */
+export function sdlWindowFlags(mode = 'windowed', resizable = true) {
+    return { fullscreen: mode === 'fullscreen', borderless: mode === 'borderless', resizable };
+}

package/dist/windowTitle.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A window's title as this SDL can show it.
+ *
+ * **Under X11 the title SDL writes is in the process's locale, and Node leaves that at C.** SDL
+ * 2.32's X11 driver sets `WM_NAME` through `XmbTextListToTextProperty`, so a UTF-8 title's bytes
+ * go in as Latin-1, and the `_NET_WM_NAME` it should add in UTF-8 — the one a window manager prefers —
+ * is not on the window at all. Read back with `xprop` on 2026-09-19: `WM_NAME(STRING) = "Showroom
+ * â\302\200\302\224 DriftEngine"` and no `_NET_WM_NAME`, which the desktop drew as `Showroom —
+ * DriftEngine`; reported by the maintainer. So under X11 a title is made ASCII before SDL sees it:
+ * accents dropped, dashes and quotes in their ASCII forms, and anything else one `?` rather than
+ * three characters of noise.
+ *
+ * What would make it wrong: an SDL that sets `_NET_WM_NAME`, which `xprop -id <window>
+ * _NET_WM_NAME` shows, and this then drops letters for nothing. Wayland's title is UTF-8 and is
+ * left alone.
+ */
+/** `title` as `driver` can show it: unchanged, or in ASCII under X11. */
+export declare function windowTitle(title: string, driver: string): string;

package/dist/windowTitle.js

@@ -0,0 +1,33 @@
+/**
+ * A window's title as this SDL can show it.
+ *
+ * **Under X11 the title SDL writes is in the process's locale, and Node leaves that at C.** SDL
+ * 2.32's X11 driver sets `WM_NAME` through `XmbTextListToTextProperty`, so a UTF-8 title's bytes
+ * go in as Latin-1, and the `_NET_WM_NAME` it should add in UTF-8 — the one a window manager prefers —
+ * is not on the window at all. Read back with `xprop` on 2026-09-19: `WM_NAME(STRING) = "Showroom
+ * â\302\200\302\224 DriftEngine"` and no `_NET_WM_NAME`, which the desktop drew as `Showroom —
+ * DriftEngine`; reported by the maintainer. So under X11 a title is made ASCII before SDL sees it:
+ * accents dropped, dashes and quotes in their ASCII forms, and anything else one `?` rather than
+ * three characters of noise.
+ *
+ * What would make it wrong: an SDL that sets `_NET_WM_NAME`, which `xprop -id <window>
+ * _NET_WM_NAME` shows, and this then drops letters for nothing. Wayland's title is UTF-8 and is
+ * left alone.
+ */
+const PLAIN = new Map([
+    ['–', '-'],
+    ['—', '-'],
+    ['‘', "'"],
+    ['’', "'"],
+    ['“', '"'],
+    ['”', '"'],
+    ['…', '...'],
+]);
+/** `title` as `driver` can show it: unchanged, or in ASCII under X11. */
+export function windowTitle(title, driver) {
+    if (driver !== 'x11')
+        return title;
+    return [...title.normalize('NFKD').replace(/\p{M}/gu, '')]
+        .map((character) => character.charCodeAt(0) < 0x80 ? character : (PLAIN.get(character) ?? '?'))
+        .join('');
+}

package/dist/workerScope.mjs

@@ -0,0 +1,48 @@
+/**
+ * The start of every thread the native host makes: a browser worker's scope over `worker_threads`,
+ * and then the module the page asked for.
+ *
+ * **A worker module written for a page reads `self`, `onmessage`, `addEventListener` and a global
+ * `postMessage`**, none of which a Node thread has; they are made here over `parentPort`, and a
+ * message is handed on with its value as `data`, as a `MessageEvent` carries it.
+ *
+ * **Messages wait until the module has run**, as a browser holds them until a worker's script has
+ * been evaluated: a page usually posts its first message the moment it constructs the worker, and a
+ * module that sets `onmessage` after an `await` would otherwise never see it.
+ *
+ * Plain JavaScript, so that it loads before any loader a host registers has anything to do.
+ */
+import { parentPort, workerData } from 'node:worker_threads';
+
+const scope = globalThis;
+const listeners = new Set();
+let ready = false;
+const held = [];
+
+function deliver(data) {
+  const event = { type: 'message', data, target: scope, currentTarget: scope };
+  if (typeof scope.onmessage === 'function') scope.onmessage(event);
+  for (const listener of listeners) {
+    if (typeof listener === 'function') listener(event);
+    else listener.handleEvent(event);
+  }
+}
+
+scope.self = scope;
+scope.onmessage = null;
+scope.postMessage = (value, transfer) => parentPort.postMessage(value, transfer);
+scope.addEventListener = (type, listener) => {
+  if (type === 'message') listeners.add(listener);
+};
+scope.removeEventListener = (type, listener) => {
+  if (type === 'message') listeners.delete(listener);
+};
+scope.close = () => process.exit(0);
+parentPort.on('message', (data) => {
+  if (ready) deliver(data);
+  else held.push(data);
+});
+
+await import(workerData.url);
+ready = true;
+for (const data of held.splice(0)) deliver(data);