@driftengine/native-host 4.0.0

package/dist/canvas.d.ts

@@ -0,0 +1,97 @@
+/**
+ * A canvas with no page around it: a drawing buffer, a CSS box, and a WebGPU context.
+ *
+ * **What the engine asks of a canvas, and no more.** Its WebGPU backend takes a canvas, asks it
+ * for a `webgpu` context, configures that against its device, sets the drawing buffer's size, and
+ * each frame draws into `getCurrentTexture()`. The renderer's public measurements read the canvas's
+ * CSS box. That is the whole surface, so that is what this implements — and anything a scene reaches
+ * for beyond it is a gap the host names when it meets one, rather than a document this pretends to
+ * be.
+ *
+ * **The frame lands in a texture the host owns.** A browser presents the canvas itself at the end of
+ * a task; a host has to, so the texture carries two usages the engine never asks for — sampled, to be
+ * drawn into the window, and copyable, to be read back by the pixel gate.
+ */
+import { CanvasStyle } from './canvasStyle.ts';
+import { type Handlers, HostNode } from './domTree.ts';
+import { INPUT_TYPES, type PageDocument } from './page.ts';
+import { PointerCapture } from './pointerCapture.ts';
+export interface NativeCanvas extends Handlers<(typeof INPUT_TYPES)[number]> {
+}
+export declare class NativeCanvas extends HostNode {
+    /** The drawing buffer, in device pixels, which the engine sets. */
+    width: number;
+    height: number;
+    /** Device pixels per CSS pixel. */
+    readonly pixelRatio: number;
+    /** Whether there is a window to present to: false while it is minimised to nothing. */
+    visible: boolean;
+    private cssWidth;
+    private cssHeight;
+    private context;
+    /** Set by the page that holds this canvas (`page.ts`); a canvas outside one has no pointer to lock. */
+    lockPointer: (() => Promise<void>) | null;
+    /** Set by the page too, which is what holds the focus and the fullscreen. */
+    focuser: ((focus: boolean) => void) | null;
+    fullscreener: (() => Promise<void>) | null;
+    capture: PointerCapture | null;
+    /** Set by what drives the window's mouse, which is where a cursor is shown (`canvasStyle.ts`). */
+    cursorer: ((css: string) => void) | null;
+    readonly style: CanvasStyle;
+    /**
+     * A canvas is focusable only once it is given a `tabIndex`, as a browser's is: until then it
+     * reports −1 and `focus()` does nothing.
+     */
+    private focusIndex;
+    constructor(width: number, height: number, pixelRatio?: number);
+    /** The CSS box, which is what `cssWidth` and `aspect` are asked of. */
+    get clientWidth(): number;
+    get clientHeight(): number;
+    getBoundingClientRect(): DOMRect;
+    /**
+     * `webgpu`, and nothing else — which is what a browser's canvas answers once it has given one.
+     * The engine never asks for another here: the backend is chosen before a context is taken.
+     */
+    getContext(kind: string): GPUCanvasContext | null;
+    get tabIndex(): number;
+    set tabIndex(index: number);
+    /** Focus, through the page; nothing, as in a browser, for a canvas that is not focusable. */
+    focus(_options?: FocusOptions): void;
+    blur(): void;
+    /** Capture, through the page, which is what knows the pointers (`pointerCapture.ts`). */
+    setPointerCapture(pointerId: number): void;
+    releasePointerCapture(pointerId: number): void;
+    hasPointerCapture(pointerId: number): boolean;
+    /** The document this canvas is in, once a page holds it. */
+    get ownerDocument(): PageDocument;
+    /** Fullscreen, through the page, which is what holds the window. */
+    requestFullscreen(_options?: FullscreenOptions): Promise<void>;
+    /** A canvas no page holds knows no pointers, so every id is unknown to it. */
+    private pointers;
+    /** What a browser's canvas answers, through the page, which is what holds the lock. */
+    requestPointerLock(_options?: unknown): Promise<void>;
+    /**
+     * The window's size, in device pixels, as the host is told it.
+     *
+     * **A window minimised to nothing keeps the last size it had.** It reports zero by zero, and a
+     * texture of no size is a validation error that invalidates every command buffer that touches
+     * it; the engine sizes its targets from this canvas, so this canvas never goes to zero. `visible`
+     * says there is nowhere to present to, and the host skips presenting until there is.
+     */
+    resizeTo(width: number, height: number): void;
+}
+export declare class NativeCanvasContext {
+    readonly canvas: NativeCanvas;
+    private configuration;
+    private texture;
+    constructor(canvas: NativeCanvas);
+    configure(configuration: GPUCanvasConfiguration): void;
+    unconfigure(): void;
+    getConfiguration(): GPUCanvasConfiguration | null;
+    /**
+     * This frame's texture: the same one until the drawing buffer changes size, and a new one when it
+     * does, as a browser's is.
+     */
+    getCurrentTexture(): GPUTexture;
+    private dropTexture;
+}

package/dist/canvas.js

@@ -0,0 +1,197 @@
+/**
+ * A canvas with no page around it: a drawing buffer, a CSS box, and a WebGPU context.
+ *
+ * **What the engine asks of a canvas, and no more.** Its WebGPU backend takes a canvas, asks it
+ * for a `webgpu` context, configures that against its device, sets the drawing buffer's size, and
+ * each frame draws into `getCurrentTexture()`. The renderer's public measurements read the canvas's
+ * CSS box. That is the whole surface, so that is what this implements — and anything a scene reaches
+ * for beyond it is a gap the host names when it meets one, rather than a document this pretends to
+ * be.
+ *
+ * **The frame lands in a texture the host owns.** A browser presents the canvas itself at the end of
+ * a task; a host has to, so the texture carries two usages the engine never asks for — sampled, to be
+ * drawn into the window, and copyable, to be read back by the pixel gate.
+ */
+import { CanvasStyle } from './canvasStyle.js';
+import { HostNode } from './domTree.js';
+import { INPUT_TYPES } from './page.js';
+import { PointerCapture } from './pointerCapture.js';
+/* Texture usage flags, named here rather than read off a global a host may not have installed. */
+const COPY_SRC = 0x01;
+const TEXTURE_BINDING = 0x04;
+const RENDER_ATTACHMENT = 0x10;
+export class NativeCanvas extends HostNode {
+    /** The drawing buffer, in device pixels, which the engine sets. */
+    width;
+    height;
+    /** Device pixels per CSS pixel. */
+    pixelRatio;
+    /** Whether there is a window to present to: false while it is minimised to nothing. */
+    visible = true;
+    cssWidth;
+    cssHeight;
+    context = null;
+    /** Set by the page that holds this canvas (`page.ts`); a canvas outside one has no pointer to lock. */
+    lockPointer = null;
+    /** Set by the page too, which is what holds the focus and the fullscreen. */
+    focuser = null;
+    fullscreener = null;
+    capture = null;
+    /** Set by what drives the window's mouse, which is where a cursor is shown (`canvasStyle.ts`). */
+    cursorer = null;
+    style = new CanvasStyle((css) => this.cursorer?.(css));
+    /**
+     * A canvas is focusable only once it is given a `tabIndex`, as a browser's is: until then it
+     * reports −1 and `focus()` does nothing.
+     */
+    focusIndex = null;
+    static {
+        HostNode.handles(NativeCanvas.prototype, INPUT_TYPES);
+    }
+    constructor(width, height, pixelRatio = 1) {
+        super();
+        this.pixelRatio = pixelRatio;
+        this.width = width;
+        this.height = height;
+        this.cssWidth = width / pixelRatio;
+        this.cssHeight = height / pixelRatio;
+    }
+    /** The CSS box, which is what `cssWidth` and `aspect` are asked of. */
+    get clientWidth() {
+        return this.cssWidth;
+    }
+    get clientHeight() {
+        return this.cssHeight;
+    }
+    getBoundingClientRect() {
+        const width = this.cssWidth;
+        const height = this.cssHeight;
+        const rect = { x: 0, y: 0, left: 0, top: 0, right: width, bottom: height, width, height };
+        return { ...rect, toJSON: () => rect };
+    }
+    /**
+     * `webgpu`, and nothing else — which is what a browser's canvas answers once it has given one.
+     * The engine never asks for another here: the backend is chosen before a context is taken.
+     */
+    getContext(kind) {
+        if (kind !== 'webgpu')
+            return null;
+        if (this.context === null)
+            this.context = new NativeCanvasContext(this);
+        return this.context;
+    }
+    get tabIndex() {
+        return this.focusIndex ?? -1;
+    }
+    set tabIndex(index) {
+        this.focusIndex = Math.trunc(index);
+    }
+    /** Focus, through the page; nothing, as in a browser, for a canvas that is not focusable. */
+    focus(_options) {
+        if (this.focusIndex !== null)
+            this.focuser?.(true);
+    }
+    blur() {
+        this.focuser?.(false);
+    }
+    /** Capture, through the page, which is what knows the pointers (`pointerCapture.ts`). */
+    setPointerCapture(pointerId) {
+        this.pointers().set(this, pointerId);
+    }
+    releasePointerCapture(pointerId) {
+        this.pointers().release(this, pointerId);
+    }
+    hasPointerCapture(pointerId) {
+        return this.capture?.has(this, pointerId) ?? false;
+    }
+    /** The document this canvas is in, once a page holds it. */
+    get ownerDocument() {
+        if (this.parentNode === null) {
+            throw new Error('[driftengine] a canvas no page holds is in no document');
+        }
+        return this.parentNode;
+    }
+    /** Fullscreen, through the page, which is what holds the window. */
+    requestFullscreen(_options) {
+        if (this.fullscreener === null) {
+            return Promise.reject(new TypeError('[driftengine] a canvas with no window cannot fill it'));
+        }
+        return this.fullscreener();
+    }
+    /** A canvas no page holds knows no pointers, so every id is unknown to it. */
+    pointers() {
+        return this.capture ?? new PointerCapture();
+    }
+    /** What a browser's canvas answers, through the page, which is what holds the lock. */
+    requestPointerLock(_options) {
+        if (this.lockPointer === null) {
+            return Promise.reject(new Error('[driftengine] a canvas with no window has no pointer to lock'));
+        }
+        return this.lockPointer();
+    }
+    /**
+     * The window's size, in device pixels, as the host is told it.
+     *
+     * **A window minimised to nothing keeps the last size it had.** It reports zero by zero, and a
+     * texture of no size is a validation error that invalidates every command buffer that touches
+     * it; the engine sizes its targets from this canvas, so this canvas never goes to zero. `visible`
+     * says there is nowhere to present to, and the host skips presenting until there is.
+     */
+    resizeTo(width, height) {
+        if (width <= 0 || height <= 0) {
+            this.visible = false;
+            return;
+        }
+        this.visible = true;
+        this.width = width;
+        this.height = height;
+        this.cssWidth = width / this.pixelRatio;
+        this.cssHeight = height / this.pixelRatio;
+    }
+}
+export class NativeCanvasContext {
+    canvas;
+    configuration = null;
+    texture = null;
+    constructor(canvas) {
+        this.canvas = canvas;
+    }
+    configure(configuration) {
+        this.dropTexture();
+        const asked = configuration.usage ?? RENDER_ATTACHMENT;
+        this.configuration = { ...configuration, usage: asked | TEXTURE_BINDING | COPY_SRC };
+    }
+    unconfigure() {
+        this.dropTexture();
+        this.configuration = null;
+    }
+    getConfiguration() {
+        return this.configuration;
+    }
+    /**
+     * This frame's texture: the same one until the drawing buffer changes size, and a new one when it
+     * does, as a browser's is.
+     */
+    getCurrentTexture() {
+        const configuration = this.configuration;
+        if (configuration === null) {
+            throw new Error('[driftengine] this canvas is not configured, so it has no frame to give');
+        }
+        const { width, height } = this.canvas;
+        const current = this.texture;
+        if (current !== null && current.width === width && current.height === height)
+            return current;
+        this.dropTexture();
+        this.texture = configuration.device.createTexture({
+            label: 'native canvas',
+            size: { width, height },
+            format: configuration.format,
+            usage: configuration.usage ?? RENDER_ATTACHMENT,
+        });
+        return this.texture;
+    }
+    dropTexture() {
+        this.texture?.destroy();
+        this.texture = null;
+    }
+}

package/dist/canvasStyle.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A canvas's `style`, which a page writes to as it would a browser's: the cursor is the window's,
+ * and anything else is kept and read back, meaning nothing without a layout.
+ *
+ * **A page sets a cursor on the canvas it draws in** — `grab` over a view it can drag, `pointer`
+ * over a button, `none` in a first-person game — and a canvas with no `style` answered each with a
+ * `TypeError` inside the page's handler. CSS names more cursors than SDL has, so each is the nearest
+ * of SDL's twelve: `grab` and `grabbing` are its hand, as is `pointer`, since SDL has no open palm.
+ * A cursor with fallbacks, `url(hand.png) 4 4, crosshair`, is its last keyword; an image cursor is
+ * not drawn.
+ */
+/** The SDL cursor a CSS `cursor` value asks for: null to hide it, the arrow for one SDL lacks. */
+export declare function sdlCursor(css: string): string | null;
+export declare class CanvasStyle {
+    #private;
+    [property: string]: unknown;
+    constructor(onCursor: (css: string) => void);
+    get cursor(): string;
+    set cursor(css: string);
+    setProperty(name: string, value: string): void;
+    getPropertyValue(name: string): string;
+    removeProperty(name: string): string;
+}

package/dist/canvasStyle.js

@@ -0,0 +1,79 @@
+/**
+ * A canvas's `style`, which a page writes to as it would a browser's: the cursor is the window's,
+ * and anything else is kept and read back, meaning nothing without a layout.
+ *
+ * **A page sets a cursor on the canvas it draws in** — `grab` over a view it can drag, `pointer`
+ * over a button, `none` in a first-person game — and a canvas with no `style` answered each with a
+ * `TypeError` inside the page's handler. CSS names more cursors than SDL has, so each is the nearest
+ * of SDL's twelve: `grab` and `grabbing` are its hand, as is `pointer`, since SDL has no open palm.
+ * A cursor with fallbacks, `url(hand.png) 4 4, crosshair`, is its last keyword; an image cursor is
+ * not drawn.
+ */
+/** SDL's system cursor for a CSS keyword, or null for `none`, which hides it. */
+const SDL_CURSOR = {
+    auto: 'arrow',
+    default: 'arrow',
+    pointer: 'hand',
+    grab: 'hand',
+    grabbing: 'hand',
+    text: 'ibeam',
+    'vertical-text': 'ibeam',
+    wait: 'wait',
+    progress: 'waitarrow',
+    crosshair: 'crosshair',
+    move: 'sizeall',
+    'all-scroll': 'sizeall',
+    'not-allowed': 'no',
+    'no-drop': 'no',
+    'ew-resize': 'sizewe',
+    'col-resize': 'sizewe',
+    'e-resize': 'sizewe',
+    'w-resize': 'sizewe',
+    'ns-resize': 'sizens',
+    'row-resize': 'sizens',
+    'n-resize': 'sizens',
+    's-resize': 'sizens',
+    'nwse-resize': 'sizenwse',
+    'nw-resize': 'sizenwse',
+    'se-resize': 'sizenwse',
+    'nesw-resize': 'sizenesw',
+    'ne-resize': 'sizenesw',
+    'sw-resize': 'sizenesw',
+    none: null,
+};
+/** The SDL cursor a CSS `cursor` value asks for: null to hide it, the arrow for one SDL lacks. */
+export function sdlCursor(css) {
+    const keyword = css.split(',').at(-1)?.trim().toLowerCase() ?? '';
+    const cursor = SDL_CURSOR[keyword];
+    return cursor === undefined ? 'arrow' : cursor;
+}
+const camel = (name) => name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+export class CanvasStyle {
+    #cursor = '';
+    #onCursor;
+    constructor(onCursor) {
+        this.#onCursor = onCursor;
+    }
+    get cursor() {
+        return this.#cursor;
+    }
+    set cursor(css) {
+        this.#cursor = css;
+        this.#onCursor(css);
+    }
+    setProperty(name, value) {
+        this[camel(name)] = value;
+    }
+    getPropertyValue(name) {
+        const value = this[camel(name)];
+        return typeof value === 'string' ? value : '';
+    }
+    removeProperty(name) {
+        const was = this.getPropertyValue(name);
+        if (camel(name) === 'cursor')
+            this.cursor = '';
+        else
+            delete this[camel(name)];
+        return was;
+    }
+}

package/dist/device.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The device, made to say what it rejected, when its binding will not.
+ *
+ * **The engine hears one thing from its device**: `uncapturederror`, which its surface turns into a
+ * line naming what the GPU refused — the only warning a WebGPU frame gets that it drew nothing.
+ * `@kmamal/gpu` 0.2.0 refuses that listener ("no overload matched for addEventListener") and will not
+ * take an `onuncapturederror` either (measured 2026-09-18). Error scopes work, so the host opens one
+ * around each frame and hands whatever it caught to the listeners the engine registered: the same
+ * message, at the end of the frame that caused it, which is when a browser raises it too.
+ *
+ * **Detected, not assumed.** A device whose binding takes the listener is left exactly as it is, so a
+ * later binding that delivers its own events costs nothing here.
+ *
+ * What it gives up: an error from work outside a frame — a pipeline built at mount — is only caught
+ * if the host has a scope open at the time. Dawn still prints every validation error to the
+ * terminal itself, so none is silent.
+ */
+import type { AlphaStep } from './alphaCopy.ts';
+export interface FrameErrors {
+    /** Before the frame: catch what it does. */
+    open(): void;
+    /** After it: hand anything caught to the engine's listeners. */
+    close(): void;
+}
+/** The frame's error scopes for a device this host adapted, or `null` for one it left alone. */
+export declare function errorsOf(device: GPUDevice): FrameErrors | null;
+/** Skia's premultiply, the integer rounding Chrome's image decoders use. */
+export declare function premultiplied(straight: Uint8Array): Uint8Array;
+/**
+ * The step a copy takes between the alpha an image is held in and the alpha its texture wants, or
+ * null where the two agree and a browser copies the bytes as they are.
+ */
+export declare function alphaStepFor(held: boolean, wanted: boolean): AlphaStep | null;
+export declare function adaptDevice(device: GPUDevice): GPUDevice;

package/dist/device.js

@@ -0,0 +1,144 @@
+/**
+ * The device, made to say what it rejected, when its binding will not.
+ *
+ * **The engine hears one thing from its device**: `uncapturederror`, which its surface turns into a
+ * line naming what the GPU refused — the only warning a WebGPU frame gets that it drew nothing.
+ * `@kmamal/gpu` 0.2.0 refuses that listener ("no overload matched for addEventListener") and will not
+ * take an `onuncapturederror` either (measured 2026-09-18). Error scopes work, so the host opens one
+ * around each frame and hands whatever it caught to the listeners the engine registered: the same
+ * message, at the end of the frame that caused it, which is when a browser raises it too.
+ *
+ * **Detected, not assumed.** A device whose binding takes the listener is left exactly as it is, so a
+ * later binding that delivers its own events costs nothing here.
+ *
+ * What it gives up: an error from work outside a frame — a pipeline built at mount — is only caught
+ * if the host has a scope open at the time. Dawn still prints every validation error to the
+ * terminal itself, so none is silent.
+ */
+import { AlphaCopier } from './alphaCopy.js';
+import { isHostBitmap } from './images.js';
+const adapted = new WeakMap();
+/** The frame's error scopes for a device this host adapted, or `null` for one it left alone. */
+export function errorsOf(device) {
+    return adapted.get(device) ?? null;
+}
+/** Skia's premultiply, the integer rounding Chrome's image decoders use. */
+export function premultiplied(straight) {
+    const out = new Uint8Array(straight.length);
+    for (let at = 0; at < straight.length; at += 4) {
+        const alpha = straight[at + 3];
+        out[at + 3] = alpha;
+        for (let channel = 0; channel < 3; channel += 1) {
+            out[at + channel] = ((straight[at + channel] * alpha + 128) * 257) >> 16;
+        }
+    }
+    return out;
+}
+/**
+ * The step a copy takes between the alpha an image is held in and the alpha its texture wants, or
+ * null where the two agree and a browser copies the bytes as they are.
+ */
+export function alphaStepFor(held, wanted) {
+    if (held === wanted)
+        return null;
+    return held ? 'unpremultiply' : 'premultiply';
+}
+/**
+ * The queue, taking an image the host decoded where a browser would take one it decoded.
+ *
+ * **The engine puts a decoded image on the device with `copyExternalImageToTexture`**, and a browser
+ * copies from its own image there. A host's image is a `HostBitmap` from `images.ts`, four bytes a
+ * pixel that Dawn's binding cannot read as an image, so it is copied the way Chrome copies one:
+ *
+ * - **held as the texture wants it**, the bytes go in with `writeTexture`. Straight or
+ *   premultiplied, into a plain or an sRGB texture, Chrome writes exactly these (measured);
+ * - **held one way and wanted the other**, `alphaCopy.ts` runs the step on the device.
+ *
+ * A browser holds a decoded image premultiplied unless told `premultiplyAlpha: 'none'`, with Skia's
+ * integer rounding, so that is how the bytes are held here. A browser flips rows only when asked,
+ * and so does this. Any other source goes to the binding.
+ */
+function adaptQueue(device) {
+    const queue = device.queue;
+    if (queue === undefined)
+        return;
+    const original = queue.copyExternalImageToTexture.bind(queue);
+    const copier = new AlphaCopier(device);
+    queue.copyExternalImageToTexture = (source, destination, copySize) => {
+        /* A size may be any iterable of numbers or a dictionary; one shape, for both uses below. */
+        const size = Symbol.iterator in Object(copySize)
+            ? Array.from(copySize)
+            : copySize;
+        const image = source.source;
+        if (!isHostBitmap(image)) {
+            original(source, destination, size);
+            return;
+        }
+        const from = source.origin;
+        if ((from?.x ?? 0) !== 0 || (from?.y ?? 0) !== 0) {
+            throw new Error('[driftengine] the native host copies a whole image, from its top-left corner');
+        }
+        const row = image.width * 4;
+        const straight = new Uint8Array(image.data.buffer, image.data.byteOffset, image.data.byteLength);
+        let bytes = image.premultiplied ? premultiplied(straight) : straight;
+        if (source.flipY === true) {
+            const flipped = new Uint8Array(bytes.length);
+            for (let y = 0; y < image.height; y += 1) {
+                flipped.set(bytes.subarray(y * row, (y + 1) * row), (image.height - 1 - y) * row);
+            }
+            bytes = flipped;
+        }
+        const width = Array.isArray(size) ? size[0] : size.width;
+        const height = Array.isArray(size) ? (size[1] ?? 1) : (size.height ?? 1);
+        const step = alphaStepFor(image.premultiplied, destination.premultipliedAlpha === true);
+        if (step !== null) {
+            copier.copy(bytes, image.width, image.height, step, destination, width, height);
+            return;
+        }
+        queue.writeTexture({
+            texture: destination.texture,
+            mipLevel: destination.mipLevel ?? 0,
+            origin: destination.origin ?? { x: 0, y: 0, z: 0 },
+        }, bytes, { offset: 0, bytesPerRow: row, rowsPerImage: image.height }, { width, height, depthOrArrayLayers: 1 });
+    };
+}
+export function adaptDevice(device) {
+    adaptQueue(device);
+    const original = device.addEventListener.bind(device);
+    try {
+        original('uncapturederror', () => undefined);
+        return device;
+    }
+    catch {
+        /* The binding refused it: this device needs the adapter. */
+    }
+    const listeners = new Set();
+    const deliver = (error) => {
+        const event = { type: 'uncapturederror', error };
+        for (const listener of listeners) {
+            if (typeof listener === 'function')
+                listener(event);
+            else
+                listener.handleEvent(event);
+        }
+    };
+    const scoped = device;
+    scoped.addEventListener = (type, listener) => {
+        if (type === 'uncapturederror')
+            listeners.add(listener);
+    };
+    scoped.removeEventListener = (type, listener) => {
+        if (type === 'uncapturederror')
+            listeners.delete(listener);
+    };
+    adapted.set(device, {
+        open: () => device.pushErrorScope('validation'),
+        close: () => {
+            void device.popErrorScope().then((error) => {
+                if (error !== null)
+                    deliver(error);
+            });
+        },
+    });
+    return device;
+}

package/dist/dialogs.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Open and save dialogs from the desktop, since SDL 2 gives a window none.
+ *
+ * **The desktop's own dialog program, asked and waited for**: zenity, which GNOME and the GTK
+ * desktops carry, and kdialog where zenity is not installed. What comes back is what the desktop
+ * shell hands a game (`main/ipc.ts`): a picked file's name and bytes, `null` for a cancelled pick,
+ * and `false` for a cancelled save — a cancellation being exit code 1 for both programs.
+ *
+ * **A filter is the extensions the game named**, `.json` becoming `*.json`; a MIME type has no
+ * pattern either program takes, so it is left out rather than guessed at.
+ *
+ * What it gives up: Windows and macOS, which carry neither program and are Task 7's; the desktop
+ * portal, which is what a sandboxed Linux build would need and answers over D-Bus signals rather
+ * than an exit code; and where neither program is installed, `desktopFiles` answers null and the
+ * bridge reports every pick cancelled.
+ */
+import type { NativeFiles } from './bridge.ts';
+/** Run a dialog program and hand back its exit code and what it printed. */
+export type DialogRunner = (command: string, args: readonly string[]) => Promise<{
+    code: number;
+    stdout: string;
+}>;
+export declare function desktopFiles(available?: (name: string) => boolean, run?: DialogRunner): NativeFiles | null;