@gjsify/adwaita-web 0.59.1 → 0.61.0

package/lib/types/template-classes.d.ts

@@ -7,5 +7,7 @@
  * as `Gtk.Builder` refuses a type registered twice.
  */
 export declare function registerTemplateClass(name: string, tag: string): void;
+/** Whether `tag` is an element an application class registered, whose properties are GObject properties. */
+export declare function isTemplateTag(tag: string): boolean;
 /** The tag `name` was registered under, or a refusal that names what is missing. */
 export declare function templateTagFor(name: string): string;

package/lib/types/widget-members.spec.d.ts

@@ -0,0 +1 @@
+export declare const WidgetMembersTest: () => Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-web",
-    "version": "0.59.1",
+    "version": "0.61.0",
     "description": "Adwaita/Libadwaita web components for browser targets",
     "type": "module",
     "main": "./src/index.ts",
@@ -34,7 +34,11 @@
         "scss",
         "dist",
         "lib",
-        "style.css.d.ts"
+        "style.css.d.ts",
+        "!src/**/*.spec.ts",
+        "!src/test.browser.mts",
+        "!dist/test.browser.mjs",
+        "!lib/types/**/*.spec.d.ts"
     ],
     "scripts": {
         "clear": "gjsify clear lib dist tsconfig.tsbuildinfo scss/_icons.generated.scss src/styles.generated.ts",
@@ -50,17 +54,26 @@
         "@codemirror/language": "^6.12.4",
         "@codemirror/state": "^6.7.0",
         "@codemirror/view": "^6.43.4",
-        "@gjsify/adwaita-core": "^0.59.1",
-        "@gjsify/adwaita-fonts": "^0.59.1",
-        "@gjsify/adwaita-icons": "^0.59.1",
-        "@gjsify/gtksource-core": "^0.59.1",
+        "@gjsify/adwaita-core": "^0.61.0",
+        "@gjsify/adwaita-fonts": "^0.61.0",
+        "@gjsify/adwaita-icons": "^0.61.0",
+        "@gjsify/gtksource-core": "^0.61.0",
         "@lezer/highlight": "^1.2.3"
     },
+    "peerDependencies": {
+        "@gjsify/app-settings": "^0.61.0"
+    },
+    "peerDependenciesMeta": {
+        "@gjsify/app-settings": {
+            "optional": true
+        }
+    },
     "devDependencies": {
-        "@gjsify/blueprint": "^0.59.1",
-        "@gjsify/cli": "^0.59.1",
-        "@gjsify/unit": "^0.59.1",
-        "@gjsify/vite-plugin-blueprint": "^0.59.1",
+        "@gjsify/app-settings": "^0.61.0",
+        "@gjsify/blueprint": "^0.61.0",
+        "@gjsify/cli": "^0.61.0",
+        "@gjsify/unit": "^0.61.0",
+        "@gjsify/vite-plugin-blueprint": "^0.61.0",
         "sass": "^1.101.0",
         "typescript": "^6.0.3"
     },

package/scss/_viewport.scss

@@ -47,4 +47,13 @@ gtk-viewport {
   > * {
     flex: none;
   }
+
+  // A `GtkScrollable` is the one child GTK does NOT put in a viewport: `gtk_scrolled_window_set_child`
+  // takes it as the window's own scrollable (gtkscrolledwindow.c:4362), so it is allocated the
+  // window's size and scrolls itself. The builder wraps every child, so the scrollable has to fill
+  // the viewport it lands in, in both axes.
+  > gtk-source-view {
+    flex: 1 1 auto;
+    align-self: stretch;
+  }
 }

package/src/capabilities.mjs

@@ -4,10 +4,7 @@
 
 /** @type {import('./capabilities.d.mts').capabilities} */
 export const capabilities = {
-    layout: {
-        refused:
-            'an <adw-…> element is placed by DOM order and slot=, so a layout-manager placement has no door in the markup this package reads (ADR 0092)',
-    },
+    layout: 'implemented',
     strings: 'implemented',
     responses: 'implemented',
     page: 'implemented',

package/src/construct-vectors.spec.ts

@@ -23,10 +23,19 @@ customElements.define('corpus-extern', CorpusExtern);
 registerTemplateClass(EXTERN_VECTOR_CLASS, 'corpus-extern');
 
 function observe(vector: ConstructVector): unknown {
-    if (vector.kind === 'layout' || vector.kind === 'sibling-object') {
+    if (vector.kind === 'sibling-object') {
         buildSharedTree(vector.tree);
         return undefined;
     }
+    if (vector.kind === 'layout') {
+        // CSS Grid lines count from 1, GTK cells from 0: `2 / span 2` is column 1, columnSpan 2.
+        const start = (line: string) => Number(line.split(' / ')[0]) - 1;
+        const span = (line: string) => Number(line.split('span ')[1]);
+        return [...buildSharedTree(vector.tree).children].map((child) => {
+            const { gridRow, gridColumn } = (child as HTMLElement).style;
+            return { row: start(gridRow), column: start(gridColumn), columnSpan: span(gridColumn) };
+        });
+    }
     if (vector.kind === 'page') {
         const stack = buildSharedTree(vector.tree);
         return [{ name: stack.children[0]!.getAttribute('name'), title: stack.children[0]!.getAttribute('title') }];

package/src/elements/gtk-button.ts

@@ -50,6 +50,40 @@ export class GtkButton extends HTMLElement {
         ];
     }
 
+    /**
+     * `Gtk.Button:icon-name` and `Gtk.Widget:tooltip-text`, the GObject spellings: a class that
+     * holds a button as a template child writes `button.icon_name = …`, which must reach the DOM.
+     */
+    get icon_name(): string | null {
+        return this.getAttribute('icon-name');
+    }
+    set icon_name(value: string | null) {
+        this.reflect('icon-name', value);
+    }
+    get iconName(): string | null {
+        return this.icon_name;
+    }
+    set iconName(value: string | null) {
+        this.icon_name = value;
+    }
+    get tooltip_text(): string | null {
+        return this.getAttribute('tooltip-text');
+    }
+    set tooltip_text(value: string | null) {
+        this.reflect('tooltip-text', value);
+    }
+    get tooltipText(): string | null {
+        return this.tooltip_text;
+    }
+    set tooltipText(value: string | null) {
+        this.tooltip_text = value;
+    }
+
+    private reflect(attribute: string, value: string | null): void {
+        if (value === null || value === undefined) this.removeAttribute(attribute);
+        else this.setAttribute(attribute, value);
+    }
+
     /** The inner native button (for focus/imperative access). */
     get button(): HTMLButtonElement {
         return this._button;

package/src/elements/gtk-drop-down.ts

@@ -126,6 +126,16 @@ export class GtkDropDown extends HTMLElement {
         this._selectIndex(value);
     }
 
+    /** `gtk_drop_down_get_selected`. */
+    get_selected(): number {
+        return this.selected;
+    }
+
+    /** `gtk_drop_down_set_selected`; an out-of-range index is ignored, as the `selected` property does. */
+    set_selected(position: number): void {
+        this.selected = position;
+    }
+
     /** The selected option's value, or '' when empty (Gtk.DropDown:selected-item). */
     get selectedValue(): string {
         return this._state.selectedValue;

package/src/elements/gtk-label.ts

@@ -262,6 +262,16 @@ export class GtkLabel extends HTMLElement {
         this.toggleAttribute('selectable', !!value);
     }
 
+    /** `gtk_label_get_label`. */
+    get_label(): string {
+        return this.label;
+    }
+
+    /** `gtk_label_set_label`. */
+    set_label(str: string): void {
+        this.label = str;
+    }
+
     /** `gtk_label_get_text` — the text as SHOWN, markup reduced and the marker removed. */
     getText(): string {
         return labelDisplayText(this.label, this.useMarkup, this.useUnderline);

package/src/elements/gtk-text-view.ts

@@ -75,6 +75,14 @@ const WRAP_WHITE_SPACE: Record<TextViewWrapMode, string> = {
     char: 'pre-wrap',
 };
 
+/** The members of `Gtk.TextBuffer` this element has: text in and out, and the insertion cursor. */
+export interface GtkTextBufferSubset {
+    readonly cursor_position: number;
+    insert_at_cursor(text: string, len?: number): void;
+    set_text(text: string, len?: number): void;
+    get_text(): string;
+}
+
 export class GtkTextView extends HTMLElement {
     private _area!: HTMLTextAreaElement;
     private _initialized = false;
@@ -195,6 +203,38 @@ export class GtkTextView extends HTMLElement {
         this.setAttribute('right-margin', String(value));
     }
 
+    /**
+     * `gtk_text_view_get_buffer`: the part of `Gtk.TextBuffer` a program writes through. The text
+     * stays the element's own, so the buffer is a view onto it: the cursor is the textarea's caret,
+     * and a length of -1 means "the whole string", as in GTK.
+     */
+    get buffer(): GtkTextBufferSubset {
+        return {
+            cursor_position: this._area ? (this._area.selectionEnd ?? this._area.value.length) : this.text.length,
+            insert_at_cursor: (text: string, len = -1) => {
+                const piece = len < 0 ? text : text.slice(0, len);
+                const area = this._area;
+                if (!area) {
+                    this.text = this.text + piece;
+                    return;
+                }
+                const at = area.selectionEnd ?? area.value.length;
+                area.setRangeText(piece, at, at, 'end');
+                this._emitChanged();
+            },
+            set_text: (text: string, len = -1) => {
+                this.text = len < 0 ? text : text.slice(0, len);
+                if (this._area) this._emitChanged();
+            },
+            get_text: () => this.text,
+        } as GtkTextBufferSubset;
+    }
+
+    /** `gtk_text_view_get_buffer`. */
+    get_buffer(): GtkTextBufferSubset {
+        return this.buffer;
+    }
+
     /** The inner native textarea, for focus and selection. */
     get textarea(): HTMLTextAreaElement {
         return this._area;

package/src/file-chooser-host.ts

@@ -0,0 +1,421 @@
+// How the web door answers `Gtk.FileDialog` (ADR 0100 § 4, § 4a, § 5). The subset itself — argument
+// checks, the async/finish pairs, `Gio.File`, the stream — is `@gjsify/adwaita-core`'s; this file is
+// the driver below it.
+//
+// THE DOOR CHOOSES BY FEATURE, NEVER BY BROWSER. No line here reads the user agent:
+//   - `'showSaveFilePicker' in window`: the system pickers of File System Access, over the user's
+//     real files. The filters become `types[].accept`.
+//   - otherwise: the Origin Private File System, in a dialog drawn from Adwaita elements
+//     ({@link presentOpfsDialog}). A file picked through `<input type=file>` from that dialog is
+//     COPIED into OPFS, so the next save writes the copy and not a download.
+//   - `createWritable` on the handle: the write streams on the main thread; where it is missing
+//     (Safari before 26), a dedicated worker writes with `createSyncAccessHandle`.
+//
+// A download is never a stand-in for save; nothing here creates one.
+//
+// THE DRAWN DIALOG is a clean-room re-implementation: its STRUCTURE follows the current GNOME file
+// chooser (Nautilus' file-chooser mode — an OverlaySplitView with a places sidebar, the file list,
+// and a bottom bar with the filter drop-down, the name entry and the accept button), and no code,
+// template or string is taken from Nautilus (GPL-3.0-or-later). It shows only what OPFS has.
+
+import {
+    dialogFailedError,
+    dismissedError,
+    fileFilterAccepts,
+    registerFileChooserDriver,
+    type FileChooserDriver,
+    type FileChooserHandle,
+    type FileChooserRequest,
+    type FileChooserWriter,
+    type FileFilterSpec,
+} from '@gjsify/adwaita-core';
+
+import './elements/adw-dialog.js';
+import './elements/adw-overlay-split-view.js';
+import './elements/adw-toolbar-view.js';
+import './elements/gtk-button.js';
+import './elements/gtk-drop-down.js';
+import './elements/gtk-entry.js';
+import './elements/gtk-list-box.js';
+import './elements/gtk-list-box-row.js';
+import type { AdwDialog } from './elements/adw-dialog.js';
+import type { GtkDropDown } from './elements/gtk-drop-down.js';
+import type { GtkEntry } from './elements/gtk-entry.js';
+import type { GtkListBoxRow } from './elements/gtk-list-box-row.js';
+
+/** What the drawn dialog hands back: an OPFS entry by name, or a file the `<input>` picked. */
+export type OpfsChoice = { readonly name: string } | { readonly upload: File };
+
+/** File System Access `showOpenFilePicker`/`showSaveFilePicker` options, as far as the door fills them. */
+export interface FilePickerOptions {
+    types?: { description: string; accept: Record<string, string[]> }[];
+    excludeAcceptAllOption?: boolean;
+    suggestedName?: string;
+}
+
+/** The platform the driver reads. {@link browserFileChooserEnv} is the real one; a spec passes fakes. */
+export interface WebFileChooserEnv {
+    showOpenFilePicker?: (options: FilePickerOptions) => Promise<FileSystemFileHandle[]>;
+    showSaveFilePicker?: (options: FilePickerOptions) => Promise<FileSystemFileHandle>;
+    /** Transient user activation; an environment that cannot say answers `true`. */
+    isActive(): boolean;
+    opfsRoot(): Promise<FileSystemDirectoryHandle>;
+    /** The drawn dialog over `root`; `null` when the user closed it. */
+    choose(
+        kind: 'open' | 'save',
+        request: FileChooserRequest,
+        root: FileSystemDirectoryHandle,
+    ): Promise<OpfsChoice | null>;
+    /** Whether `handle` writes through `createWritable`; the worker writes otherwise. */
+    canStreamWrite(handle: FileSystemFileHandle): boolean;
+}
+
+// --- Filters ------------------------------------------------------------------------------------
+
+/** The extensions a filter names, with the dot, as `accept` and `types[].accept` take them. */
+function extensionsOf(spec: FileFilterSpec): string[] {
+    return [...spec.patterns, ...spec.suffixes].map((ext) => `.${ext}`);
+}
+
+/**
+ * The File System Access options for `request`. An extension-only filter needs a MIME key, and
+ * `application/octet-stream` is the one that claims nothing about the content. A filter that
+ * accepts everything is the picker's own accept-all option, so it is not a type.
+ */
+export function filePickerOptions(request: FileChooserRequest, kind: 'open' | 'save'): FilePickerOptions {
+    const types: NonNullable<FilePickerOptions['types']> = [];
+    for (const spec of request.filters) {
+        if (spec.acceptAll) continue;
+        const accept: Record<string, string[]> = {};
+        for (const mime of spec.mimeTypes) accept[mime] = [];
+        const extensions = extensionsOf(spec);
+        if (extensions.length > 0) accept[spec.mimeTypes[0] ?? 'application/octet-stream'] = extensions;
+        types.push({ description: spec.name ?? '', accept });
+    }
+    const options: FilePickerOptions = {};
+    if (types.length > 0) {
+        options.types = types;
+        options.excludeAcceptAllOption = !request.filters.some((spec) => spec.acceptAll);
+    }
+    if (kind === 'save' && request.initialName !== null) options.suggestedName = request.initialName;
+    return options;
+}
+
+/** `<input type=file accept>` for one filter: extensions and MIME types; `null` accepts every file. */
+export function inputAccept(spec: FileFilterSpec | null): string | null {
+    if (!spec || spec.acceptAll) return null;
+    const accept = [...extensionsOf(spec), ...spec.mimeTypes];
+    return accept.length > 0 ? accept.join(',') : null;
+}
+
+// --- Handles and writers ------------------------------------------------------------------------
+
+// Opens, truncates, writes and flushes in one message: `createSyncAccessHandle` exists in a
+// dedicated worker only, and only on OPFS files, which is exactly the handle this path gets.
+const WORKER_SOURCE = `onmessage = async (event) => {
+    const { handle, data } = event.data;
+    let access = null;
+    try {
+        access = await handle.createSyncAccessHandle();
+        access.truncate(0);
+        access.write(data, { at: 0 });
+        access.flush();
+        postMessage({ ok: true });
+    } catch (error) {
+        postMessage({ ok: false, message: String((error && error.name) || 'Error') + ': ' + String(error && error.message) });
+    } finally {
+        if (access) access.close();
+    }
+};`;
+
+function writeInWorker(handle: FileSystemFileHandle, data: Uint8Array): Promise<void> {
+    const url = URL.createObjectURL(new Blob([WORKER_SOURCE], { type: 'text/javascript' }));
+    const worker = new Worker(url);
+    return new Promise<void>((resolve, reject) => {
+        worker.onmessage = (event: MessageEvent<{ ok: boolean; message?: string }>) => {
+            if (event.data.ok) resolve();
+            else reject(new Error(event.data.message));
+        };
+        worker.onerror = (event) => reject(new Error(event.message || 'the write worker failed'));
+        worker.postMessage({ handle, data });
+    }).finally(() => {
+        worker.terminate();
+        URL.revokeObjectURL(url);
+    });
+}
+
+function concat(chunks: readonly Uint8Array[]): Uint8Array {
+    const out = new Uint8Array(chunks.reduce((n, c) => n + c.length, 0));
+    let at = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, at);
+        at += chunk.length;
+    }
+    return out;
+}
+
+async function openWriter(handle: FileSystemFileHandle, env: WebFileChooserEnv): Promise<FileChooserWriter> {
+    if (env.canStreamWrite(handle)) {
+        // `keepExistingData` defaults to false: the stream starts empty, and `close()` commits.
+        const stream = await handle.createWritable();
+        return { write: (chunk) => stream.write(chunk as Uint8Array<ArrayBuffer>), close: () => stream.close() };
+    }
+    const chunks: Uint8Array[] = [];
+    return {
+        write: async (chunk) => void chunks.push(chunk.slice()),
+        close: () => writeInWorker(handle, concat(chunks)),
+    };
+}
+
+function handleFor(handle: FileSystemFileHandle, env: WebFileChooserEnv): FileChooserHandle {
+    return {
+        basename: handle.name,
+        read: async () => new Uint8Array(await (await handle.getFile()).arrayBuffer()),
+        openWriter: () => openWriter(handle, env),
+    };
+}
+
+/** `name`, or `stem (2).ext`, `stem (3).ext` … — whichever `root` does not hold yet. */
+async function freeName(root: FileSystemDirectoryHandle, name: string): Promise<string> {
+    const dot = name.lastIndexOf('.');
+    const stem = dot > 0 ? name.slice(0, dot) : name;
+    const ext = dot > 0 ? name.slice(dot) : '';
+    for (let n = 1; ; n++) {
+        const candidate = n === 1 ? name : `${stem} (${n})${ext}`;
+        try {
+            await root.getFileHandle(candidate);
+        } catch {
+            return candidate;
+        }
+    }
+}
+
+/** Copies a picked `File` into OPFS: the copy is what a later save writes, never an existing file. */
+async function copyIntoOpfs(root: FileSystemDirectoryHandle, file: File, env: WebFileChooserEnv) {
+    const target = await root.getFileHandle(await freeName(root, file.name), { create: true });
+    const writer = await openWriter(target, env);
+    await writer.write(new Uint8Array(await file.arrayBuffer()));
+    await writer.close();
+    return target;
+}
+
+// --- The driver ---------------------------------------------------------------------------------
+
+function isAbort(error: unknown): boolean {
+    return (error as { name?: unknown } | null)?.name === 'AbortError';
+}
+
+/** The `Gtk.DialogError` a platform rejection becomes: `AbortError` is the user closing the picker. */
+function dialogRejection(error: unknown) {
+    if (isAbort(error)) return dismissedError();
+    const e = error as { name?: string; message?: string } | null;
+    if (e && typeof e.message === 'string') return dialogFailedError(`${e.name ?? 'Error'}: ${e.message}`);
+    return dialogFailedError(String(error));
+}
+
+export function createWebFileChooserDriver(env: WebFileChooserEnv): FileChooserDriver {
+    const run = async (kind: 'open' | 'save', request: FileChooserRequest): Promise<FileChooserHandle> => {
+        if (!env.isActive()) {
+            throw dialogFailedError(`Gtk.FileDialog.${kind}() needs a user activation (a click or a key press)`);
+        }
+        try {
+            if (env.showSaveFilePicker && env.showOpenFilePicker) {
+                const options = filePickerOptions(request, kind);
+                const handle =
+                    kind === 'open'
+                        ? (await env.showOpenFilePicker(options))[0]
+                        : await env.showSaveFilePicker(options);
+                if (!handle) throw dismissedError();
+                return handleFor(handle, env);
+            }
+            const root = await env.opfsRoot();
+            const choice = await env.choose(kind, request, root);
+            if (choice === null) throw dismissedError();
+            if ('upload' in choice) return handleFor(await copyIntoOpfs(root, choice.upload, env), env);
+            return handleFor(await root.getFileHandle(choice.name, { create: kind === 'save' }), env);
+        } catch (error) {
+            throw dialogRejection(error);
+        }
+    };
+    return { open: (request) => run('open', request), save: (request) => run('save', request) };
+}
+
+// --- The drawn dialog ---------------------------------------------------------------------------
+
+function el<K extends string>(tag: K, attrs: Record<string, string> = {}, text?: string): HTMLElement {
+    const node = document.createElement(tag);
+    for (const [name, value] of Object.entries(attrs)) node.setAttribute(name, value);
+    if (text !== undefined) node.textContent = text;
+    return node;
+}
+
+function sameFilter(a: FileFilterSpec, b: FileFilterSpec): boolean {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+
+/**
+ * Lets the user pick an OPFS file (`open`) or name one (`save`). Resolves the choice, or `null`
+ * when the dialog closes without one. On `open`, "Upload…" picks a file through `<input type=file>`;
+ * its `cancel` event dismisses the whole open, as ADR 0100 § 5 maps it.
+ *
+ * The dialog sets `data-ready` once the list is filled, which is what a spec waits for.
+ */
+export function presentOpfsDialog(
+    kind: 'open' | 'save',
+    request: FileChooserRequest,
+    root: FileSystemDirectoryHandle,
+): Promise<OpfsChoice | null> {
+    const filters = request.filters;
+    const initial = request.defaultFilter ? filters.findIndex((f) => sameFilter(f, request.defaultFilter!)) : 0;
+    let current: FileFilterSpec | null = filters[Math.max(initial, 0)] ?? request.defaultFilter;
+
+    const dialog = el('adw-dialog', {
+        title: request.title ?? (kind === 'open' ? 'Open File' : 'Save File'),
+        'content-width': '720',
+        'content-height': '480',
+    }) as AdwDialog;
+
+    const split = el('adw-overlay-split-view', { breakpoint: 'max-width: 560px' });
+    const sidebar = el('div', { slot: 'sidebar' });
+    const places = el('gtk-list-box', { class: 'navigation-sidebar', 'selection-mode': 'browse' });
+    places.append(el('gtk-list-box-row', {}, 'Origin Storage'));
+    sidebar.append(places);
+
+    const view = el('adw-toolbar-view');
+    const list = el('gtk-list-box', { 'selection-mode': 'single', 'activate-on-single-click': 'false' });
+    const empty = el('p', { class: 'dimmed', hidden: '' }, 'No files');
+    const bottom = el('div', { slot: 'bottom', class: 'toolbar' });
+
+    let dropDown: GtkDropDown | null = null;
+    if (filters.length > 0) {
+        dropDown = el('gtk-drop-down') as GtkDropDown;
+        dropDown.model = filters.map((f, i) => f.name ?? `Filter ${i + 1}`);
+        dropDown.selected = Math.max(initial, 0);
+        bottom.append(dropDown);
+    }
+    let entry: GtkEntry | null = null;
+    if (kind === 'save') {
+        entry = el('gtk-entry', { 'placeholder-text': 'Name' }) as GtkEntry;
+        entry.style.flex = '1';
+        entry.value = request.initialName ?? '';
+        bottom.append(entry);
+    }
+    let upload: HTMLElement | null = null;
+    if (kind === 'open') {
+        upload = el('gtk-button', { label: 'Upload…' });
+        bottom.append(upload);
+    }
+    const spacer = el('div');
+    spacer.style.flex = '1';
+    const accept = el('gtk-button', { label: kind === 'open' ? 'Open' : 'Save', suggested: '' });
+    bottom.append(spacer, accept);
+
+    view.append(list, empty, bottom);
+    split.append(sidebar, view);
+    dialog.append(split);
+
+    let selected: string | null = null;
+
+    const refill = async () => {
+        dialog.removeAttribute('data-ready');
+        const names: string[] = [];
+        for await (const [name, entryHandle] of root.entries()) {
+            if (entryHandle.kind === 'file' && (!current || fileFilterAccepts(current, name))) names.push(name);
+        }
+        names.sort((a, b) => a.localeCompare(b));
+        list.replaceChildren(
+            ...names.map((name) => {
+                const row = el('gtk-list-box-row', { 'data-name': name }, name);
+                return row;
+            }),
+        );
+        selected = null;
+        empty.hidden = names.length > 0;
+        dialog.setAttribute('data-ready', '');
+    };
+
+    return new Promise<OpfsChoice | null>((resolve) => {
+        let settled = false;
+        const finish = (choice: OpfsChoice | null) => {
+            if (settled) return;
+            settled = true;
+            resolve(choice);
+            dialog.forceClose();
+            dialog.remove();
+        };
+        const acceptCurrent = () => {
+            if (kind === 'open') {
+                if (selected !== null) finish({ name: selected });
+                return;
+            }
+            const name = entry!.value.trim();
+            if (name !== '' && !name.includes('/') && name !== '.' && name !== '..') finish({ name });
+        };
+
+        list.addEventListener('row-selected', (event) => {
+            const row = (event as CustomEvent<{ row: GtkListBoxRow | null }>).detail.row;
+            selected = row?.dataset.name ?? null;
+            if (entry && selected !== null) entry.value = selected;
+        });
+        list.addEventListener('row-activated', (event) => {
+            const row = (event as CustomEvent<{ row: GtkListBoxRow }>).detail.row;
+            selected = row.dataset.name ?? null;
+            if (entry && selected !== null) entry.value = selected;
+            acceptCurrent();
+        });
+        entry?.addEventListener('activate', acceptCurrent);
+        accept.addEventListener('click', acceptCurrent);
+        dropDown?.addEventListener('notify::selected', (event) => {
+            current = filters[(event as CustomEvent<{ selected: number }>).detail.selected] ?? null;
+            void refill();
+        });
+        upload?.addEventListener('click', () => {
+            const input = document.createElement('input');
+            input.type = 'file';
+            const acceptAttr = inputAccept(current);
+            if (acceptAttr !== null) input.accept = acceptAttr;
+            input.addEventListener('change', () => {
+                const file = input.files?.[0];
+                if (file) finish({ upload: file });
+            });
+            input.addEventListener('cancel', () => finish(null));
+            input.click();
+        });
+        dialog.addEventListener('closed', () => finish(null));
+
+        dialog.present();
+        void refill();
+    });
+}
+
+// --- The real environment -----------------------------------------------------------------------
+
+type PickerWindow = {
+    showOpenFilePicker?: (options: FilePickerOptions) => Promise<FileSystemFileHandle[]>;
+    showSaveFilePicker?: (options: FilePickerOptions) => Promise<FileSystemFileHandle>;
+};
+
+export function browserFileChooserEnv(): WebFileChooserEnv {
+    const win = (typeof window === 'undefined' ? {} : window) as PickerWindow;
+    const pickers = 'showSaveFilePicker' in win && 'showOpenFilePicker' in win;
+    return {
+        showOpenFilePicker: pickers ? (options) => win.showOpenFilePicker!(options) : undefined,
+        showSaveFilePicker: pickers ? (options) => win.showSaveFilePicker!(options) : undefined,
+        isActive: () =>
+            typeof navigator !== 'undefined' && navigator.userActivation ? navigator.userActivation.isActive : true,
+        opfsRoot: async () => {
+            if (typeof navigator === 'undefined' || typeof navigator.storage?.getDirectory !== 'function') {
+                throw new Error(
+                    'this browser has neither the File System Access pickers nor an Origin Private File System',
+                );
+            }
+            return navigator.storage.getDirectory();
+        },
+        choose: presentOpfsDialog,
+        canStreamWrite: (handle) => typeof (handle as { createWritable?: unknown }).createWritable === 'function',
+    };
+}
+
+export const webFileChooserDriver = createWebFileChooserDriver(browserFileChooserEnv());
+
+registerFileChooserDriver(webFileChooserDriver);