flexdesk 0.16.0 → 0.17.0

package/src/help/help_modal.js

@@ -2,14 +2,25 @@
  * HelpModal - Modal dialog for displaying help content
  *
  * Features:
- * - Markdown rendering with syntax highlighting
- * - Table of contents navigation
+ * - Topics as trusted HTML (`topic.html`) or as markdown (`topic.markdown`),
+ *   rendered safe by `renderMarkdown` with the provider's `markdownOptions`
+ *   (a highlighter, math, extension rules)
+ * - A table of contents for a topic with two or more headings, markdown or
+ *   html alike: its headings, listed and numbered, the one in view marked,
+ *   a click that scrolls to one (`createDocumentOutline`)
  * - Topic search
  * - Category browsing
  * - Keyboard navigation (Escape to close)
  */
 
 import { helpProvider, helpCategories, helpCopy } from './help_registry.js';
+import { renderMarkdown } from '../ui/utils/markdown.js';
+import { createDocumentOutline } from '../ui/components/document_outline.js';
+
+/** The headings a topic's table of contents lists. */
+const TOC_HEADINGS = 'h1, h2, h3, h4, h5, h6';
+/** Fewer headings than this, and a topic shows no table of contents. */
+const TOC_MIN_HEADINGS = 2;
 
 // ═══════════════════════════════════════════════════════════════════════════
 // HelpModal Class
@@ -33,14 +44,22 @@ export class HelpModal {
         this._modal = null;
         this._currentTopic = null;
         this._searchQuery = '';
+        this._fallback = null;
+        this._toc = null;
         this._boundKeyHandler = this._handleKeyDown.bind(this);
     }
 
     /**
      * Open the help modal.
      * @param {string} [topicId] - Initial topic to display
+     * @param {Object} [options]
+     * @param {{title: string, html: string}} [options.fallback] - Shown for
+     *   `topicId` when the provider has no such topic (its `loadTopic` answers
+     *   null). A library-owned topic, such as the palette's keyboard shortcuts,
+     *   uses it so that an application's own topic of that id still wins.
      */
-    async open(topicId = null) {
+    async open(topicId = null, { fallback = null } = {}) {
+        this._fallback = topicId && fallback ? { id: topicId, topic: fallback } : null;
         // Close any existing modal
         if (_activeModal && _activeModal !== this) {
             _activeModal.close();
@@ -71,6 +90,7 @@ export class HelpModal {
      * Close the help modal.
      */
     close() {
+        this._disposeToc();
         if (this._overlay) {
             document.removeEventListener('keydown', this._boundKeyHandler);
             this._overlay.remove();
@@ -165,15 +185,15 @@ export class HelpModal {
             const icon = this._categories[category]?.icon || 'folder';
 
             return `
-                <div class="help-category" data-category="${category}">
+                <div class="help-category" data-category="${escapeHtml(category)}">
                     <div class="help-category__header">
-                        <span class="material-symbols-outlined">${icon}</span>
-                        <span>${label}</span>
+                        <span class="material-symbols-outlined">${escapeHtml(icon)}</span>
+                        <span>${escapeHtml(label)}</span>
                     </div>
                     <ul class="help-category__topics">
                         ${topics.map(topic => `
-                            <li class="help-topic-item" data-topic="${topic.id}">
-                                ${topic.title}
+                            <li class="help-topic-item" data-topic="${escapeHtml(topic.id)}">
+                                ${escapeHtml(topic.title)}
                             </li>
                         `).join('')}
                     </ul>
@@ -200,6 +220,7 @@ export class HelpModal {
      * @private
      */
     _showIndex() {
+        this._disposeToc();
         const content = this._modal.querySelector('.help-modal__content');
         const categories = this._service.getCategories();
 
@@ -222,15 +243,15 @@ export class HelpModal {
                         const icon = this._categories[category]?.icon || 'folder';
 
                         return `
-                            <div class="help-index__category" data-category="${category}">
+                            <div class="help-index__category" data-category="${escapeHtml(category)}">
                                 <div class="help-index__category-header">
-                                    <span class="material-symbols-outlined">${icon}</span>
-                                    <span>${label}</span>
+                                    <span class="material-symbols-outlined">${escapeHtml(icon)}</span>
+                                    <span>${escapeHtml(label)}</span>
                                 </div>
                                 <ul class="help-index__topics">
                                     ${topics.slice(0, 3).map(topic => `
-                                        <li class="help-index__topic" data-topic="${topic.id}">
-                                            ${topic.title}
+                                        <li class="help-index__topic" data-topic="${escapeHtml(topic.id)}">
+                                            ${escapeHtml(topic.title)}
                                         </li>
                                     `).join('')}
                                     ${topics.length > 3 ? `<li class="help-index__more">+${topics.length - 3} more</li>` : ''}
@@ -256,6 +277,7 @@ export class HelpModal {
      * @private
      */
     async _loadTopic(topicId) {
+        this._disposeToc();
         const content = this._modal.querySelector('.help-modal__content');
         content.innerHTML = '<div class="help-content__loading">Loading...</div>';
 
@@ -265,9 +287,23 @@ export class HelpModal {
         });
 
         try {
-            const topic = await this._service.loadTopic(topicId);
+            const topic = (await this._service.loadTopic(topicId))
+                ?? (this._fallback?.id === topicId ? this._fallback.topic : null);
+            // Closed (or closed and opened again) while the topic loaded.
+            if (!this._modal?.contains(content)) return;
             this._currentTopic = topicId;
 
+            if (!topic) {
+                // An id nobody provides is not a load failure: say so plainly.
+                content.innerHTML = `
+                    <div class="help-content__error help-content__error--not-found">
+                        <span class="material-symbols-outlined">search_off</span>
+                        <p>Help topic not found.</p>
+                    </div>
+                `;
+                return;
+            }
+
             content.innerHTML = `
                 <div class="help-content__article">
                     <div class="help-content__breadcrumb">
@@ -275,10 +311,11 @@ export class HelpModal {
                             <span class="material-symbols-outlined">home</span>
                         </a>
                         <span class="help-breadcrumb__separator">/</span>
-                        <span class="help-breadcrumb__title">${topic.title}</span>
+                        <span class="help-breadcrumb__title">${escapeHtml(topic.title)}</span>
                     </div>
+                    <div class="help-content__toc" hidden></div>
                     <article class="help-article">
-                        ${topic.html}
+                        ${this._articleHtml(topic)}
                     </article>
                 </div>
             `;
@@ -288,6 +325,8 @@ export class HelpModal {
                 e.preventDefault();
                 this._showIndex();
             });
+
+            this._buildToc(content);
         } catch (error) {
             content.innerHTML = `
                 <div class="help-content__error">
@@ -298,6 +337,54 @@ export class HelpModal {
         }
     }
 
+    /**
+     * The article body: a markdown topic rendered safe, else the provider's
+     * own HTML, which is trusted by contract.
+     * @private
+     */
+    _articleHtml(topic) {
+        if (typeof topic.markdown === 'string') {
+            return renderMarkdown(topic.markdown, this._service.markdownOptions ?? {});
+        }
+        return topic.html ?? '';
+    }
+
+    /**
+     * The topic's table of contents: one entry per heading in the article, in
+     * document order, its level the heading's. Built only when the article
+     * has `TOC_MIN_HEADINGS` or more; the outline resolves each entry to its
+     * heading ELEMENT, so the provider's markup needs no ids and the modal
+     * adds none.
+     * @param {HTMLElement} content - The scrolling content pane.
+     * @private
+     */
+    _buildToc(content) {
+        this._disposeToc();
+        const host = content.querySelector('.help-content__toc');
+        const headings = [...content.querySelectorAll(`.help-article :is(${TOC_HEADINGS})`)];
+        if (!host || headings.length < TOC_MIN_HEADINGS) return;
+        const byId = new Map(headings.map((heading, index) => [`heading-${index}`, heading]));
+        const entries = [...byId].map(([id, heading]) => ({
+            id,
+            level: Number(heading.tagName.slice(1)),
+            label: heading.textContent.trim(),
+        }));
+        host.hidden = false;
+        this._toc = createDocumentOutline(host, {
+            entries,
+            numbering: true,
+            scrollContainer: content,
+            resolveTarget: (entry) => byId.get(entry.id) ?? null,
+            label: 'Contents',
+        });
+    }
+
+    /** @private */
+    _disposeToc() {
+        this._toc?.dispose();
+        this._toc = null;
+    }
+
     /**
      * Handle search input.
      * @param {string} query - Search query
@@ -312,13 +399,14 @@ export class HelpModal {
             return;
         }
 
+        this._disposeToc();
         const results = this._service.searchTopics(query);
 
         if (results.length === 0) {
             content.innerHTML = `
                 <div class="help-search-results">
                     <h2>Search Results</h2>
-                    <p class="help-search-empty">No results found for "${query}"</p>
+                    <p class="help-search-empty">No results found for "${escapeHtml(query)}"</p>
                 </div>
             `;
             return;
@@ -327,12 +415,12 @@ export class HelpModal {
         content.innerHTML = `
             <div class="help-search-results">
                 <h2>Search Results</h2>
-                <p class="help-search-count">${results.length} result${results.length !== 1 ? 's' : ''} for "${query}"</p>
+                <p class="help-search-count">${results.length} result${results.length !== 1 ? 's' : ''} for "${escapeHtml(query)}"</p>
                 <ul class="help-search-list">
                     ${results.map(topic => `
-                        <li class="help-search-item" data-topic="${topic.id}">
-                            <span class="help-search-item__title">${topic.title}</span>
-                            <span class="help-search-item__category">${this._categories[topic.category]?.label || topic.category}</span>
+                        <li class="help-search-item" data-topic="${escapeHtml(topic.id)}">
+                            <span class="help-search-item__title">${escapeHtml(topic.title)}</span>
+                            <span class="help-search-item__category">${escapeHtml(this._categories[topic.category]?.label || topic.category)}</span>
                         </li>
                     `).join('')}
                 </ul>
@@ -361,14 +449,28 @@ export class HelpModal {
     /**
      * Static method to open help modal.
      * @param {string} [topicId] - Initial topic
+     * @param {Object} [options] - As for the instance `open`.
      * @returns {HelpModal}
      */
-    static open(topicId = null) {
+    static open(topicId = null, options = {}) {
         const modal = new HelpModal();
-        modal.open(topicId);
+        modal.open(topicId, options);
         return modal;
     }
 
+    /**
+     * Close the open help modal, or open the index when none is open — what
+     * the `?` shortcut does.
+     * @returns {HelpModal|null} the modal opened, or null when one was closed
+     */
+    static toggle() {
+        if (_activeModal) {
+            _activeModal.close();
+            return null;
+        }
+        return HelpModal.open();
+    }
+
     /**
      * Get the currently active modal.
      * @returns {HelpModal|null}
@@ -379,31 +481,55 @@ export class HelpModal {
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
-// Global Help Shortcut
+// Helpers
 // ═══════════════════════════════════════════════════════════════════════════
 
 /**
- * Open help modal with the `?` key. (F1 is reserved for top-nav Home.)
+ * Text for an innerHTML template. Everything the modal interpolates — the
+ * search query the user typed, and the topic ids, titles and categories the
+ * provider hands back — is TEXT; only `topic.html` is markup, by contract
+ * (and `topic.markdown` becomes markup through `renderMarkdown`).
+ * Quotes are escaped too, because ids and categories land in attributes.
  */
-function setupGlobalHelpShortcut() {
-    document.addEventListener('keydown', (event) => {
-        if (event.key !== '?') return;
-        // Don't hijack `?` typed into a field (search boxes, editors).
-        const t = event.target;
-        if (t?.closest?.(
-            'input, textarea, select, [contenteditable="true"]')) return;
-        event.preventDefault();
-        if (_activeModal) {
-            _activeModal.close();
-        } else {
-            HelpModal.open();
-        }
-    });
+function escapeHtml(value) {
+    if (value === null || value === undefined) return '';
+    return String(value)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
 }
 
-// Initialize global shortcut
-if (typeof document !== 'undefined') {
-    setupGlobalHelpShortcut();
+// ═══════════════════════════════════════════════════════════════════════════
+// The `?` shortcut — installed, never imported
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Bind `?` (outside editable fields) to `HelpModal.toggle()` on `target`, and
+ * return the disposer that takes it off again.
+ *
+ * Importing this module binds nothing. It used to add a `document` listener as
+ * a side effect of the import, which nobody could remove: a second shell in the
+ * same page, or an application with its own `?`, got two handlers. A
+ * `createShell()` shell binds `?` through its keymap (`installKeymap`), and
+ * `shell.dispose()` takes it off; this is for a page that uses the help modal
+ * without the shell.
+ *
+ * @param {object} [opts]
+ * @param {EventTarget} [opts.target=document]
+ * @returns {() => void}
+ */
+export function installHelpShortcut({ target = document } = {}) {
+    const onKeyDown = (event) => {
+        if (event.defaultPrevented || event.key !== '?') return;
+        // Don't hijack `?` typed into a field (search boxes, editors).
+        if (event.target?.closest?.('input, textarea, select, [contenteditable="true"]')) return;
+        event.preventDefault();
+        HelpModal.toggle();
+    };
+    target.addEventListener('keydown', onKeyDown);
+    return () => target.removeEventListener('keydown', onKeyDown);
 }
 
 export default HelpModal;

package/src/help/help_registry.js

@@ -13,8 +13,19 @@
  * @typedef {Object} HelpProvider
  * @property {() => string[]} getCategories
  * @property {(category: string) => Array<{id: string, title: string}>} getTopicsByCategory
- * @property {(id: string) => Promise<Object|null>} loadTopic
+ * @property {(id: string) => Promise<HelpTopic|null>} loadTopic
  * @property {(query: string) => Array<Object>} searchTopics
+ * @property {Object} [markdownOptions] What the modal passes to
+ *   `renderMarkdown` for a markdown topic: `highlight`, `math`, `allowHtml`,
+ *   `inlineRules`, `blockRules`.
+ *
+ * @typedef {Object} HelpTopic
+ * @property {string} title Text.
+ * @property {string} [markdown] The article as markdown, rendered safe by
+ *   `renderMarkdown`: raw HTML is escaped and only http(s), mailto and #anchor
+ *   links go anywhere. Used when present.
+ * @property {string} [html] The article as pre-rendered, TRUSTED HTML,
+ *   inserted verbatim. Never put unsanitised user content here.
  *
  * @typedef {Object.<string, {label: string, icon: string}>} HelpCategories
  *   Keyed by category id; ITERATION ORDER IS DISPLAY ORDER.

package/src/host/file_picker.js

@@ -0,0 +1,117 @@
+/**
+ * file_picker.js — let the user choose a file to open, and read it.
+ *
+ * A native window (pywebview, Photino) offers a real open dialog through the
+ * optional `host.dialogs.openFile` capability; a browser tab has none. pickFile()
+ * asks the host first and, when the host has no `openFile` or answers null
+ * ("no dialog behind it", per host.js), opens the browser's own file chooser
+ * through a transient `<input type="file">`. The caller gets ONE result shape
+ * either way:
+ *
+ *   {ok: true, name, path?, text}       encoding 'text' (the default)
+ *   {ok: true, name, path?, data}       encoding 'base64': the file's bytes, base64
+ *   {ok: false, cancelled: true}        the user closed the chooser: say nothing
+ *   {ok: false, error}                  show it to the user
+ *
+ * `path` comes only from a native host; a browser never reveals one.
+ */
+
+const ENCODINGS = new Set(['text', 'base64']);
+
+/**
+ * `accept` as a list of extensions or MIME types: an array is kept, a string
+ * is split on commas (the `<input accept>` form), each entry trimmed and the
+ * empty ones dropped. `'.json, .csv'` → `['.json', '.csv']`.
+ */
+function acceptList(accept) {
+    const parts = Array.isArray(accept) ? accept : (accept ? String(accept).split(',') : []);
+    return parts.map((a) => String(a).trim()).filter(Boolean);
+}
+
+/** `accept` as the `<input accept>` attribute wants it: comma-separated. */
+function acceptAttr(accept) {
+    return acceptList(accept).join(',');
+}
+
+/** Read `file` as text or as base64, with the FileReader of the file's own window. */
+function readFile(file, encoding, FileReaderCtor) {
+    return new Promise((resolve) => {
+        const reader = new FileReaderCtor();
+        reader.onload = () => {
+            const name = file.name;
+            if (encoding === 'base64') {
+                const url = String(reader.result ?? '');
+                resolve({ ok: true, name, data: url.slice(url.indexOf(',') + 1) });
+            } else {
+                resolve({ ok: true, name, text: String(reader.result ?? '') });
+            }
+        };
+        reader.onerror = () => resolve({ ok: false, error: String(reader.error?.message || reader.error || 'The file could not be read.') });
+        if (encoding === 'base64') reader.readAsDataURL(file);
+        else reader.readAsText(file);
+    });
+}
+
+/**
+ * The browser's file chooser: a hidden `<input type="file">`, clicked, removed
+ * again once it answers. Cancelling is the input's `cancel` event (every
+ * current engine fires it; an engine that does not leaves the promise pending
+ * until the user does choose a file).
+ */
+function browserChooser({ accept, encoding, doc }) {
+    const FileReaderCtor = doc?.defaultView?.FileReader ?? globalThis.FileReader;
+    if (!doc?.body || typeof FileReaderCtor !== 'function') {
+        return Promise.resolve({ ok: false, error: 'No file chooser is available here.' });
+    }
+    return new Promise((resolve) => {
+        const input = doc.createElement('input');
+        input.type = 'file';
+        const a = acceptAttr(accept);
+        if (a) input.accept = a;
+        input.style.display = 'none';
+        let done = false;
+        const finish = (result) => {
+            if (done) return;
+            done = true;
+            input.removeEventListener('change', onChange);
+            input.removeEventListener('cancel', onCancel);
+            input.remove();
+            resolve(result);
+        };
+        const onChange = () => {
+            const file = input.files && input.files[0];
+            if (!file) { finish({ ok: false, cancelled: true }); return; }
+            readFile(file, encoding, FileReaderCtor).then(finish);
+        };
+        const onCancel = () => finish({ ok: false, cancelled: true });
+        input.addEventListener('change', onChange);
+        input.addEventListener('cancel', onCancel);
+        doc.body.appendChild(input);
+        input.click();
+    });
+}
+
+/**
+ * Let the user choose one file and read it.
+ *
+ * @param {object} host  a Host; its optional `dialogs.openFile` is asked first
+ * @param {object} [opts]
+ * @param {string[]|string} [opts.accept]  extensions or MIME types, e.g. ['.json', '.csv'];
+ *                                         a string is comma-separated ('.json,.csv'). The
+ *                                         native host always receives the list.
+ * @param {string|null} [opts.kind]        a label for the native dialog's filter (e.g. 'json')
+ * @param {'text'|'base64'} [opts.encoding='text']  text, or the bytes as base64
+ * @param {Document} [opts.document]       where the browser chooser goes (default: the page's)
+ * @returns {Promise<{ok: true, name: string, path?: string, text?: string, data?: string}
+ *                   | {ok: false, cancelled: true} | {ok: false, error: string}>}
+ */
+export async function pickFile(host, { accept = [], kind = null, encoding = 'text', document: doc } = {}) {
+    if (!ENCODINGS.has(encoding)) throw new TypeError(`pickFile: unknown encoding '${encoding}' (use 'text' or 'base64')`);
+    if (typeof host?.dialogs?.openFile === 'function') {
+        let r = null;
+        try { r = await host.dialogs.openFile({ accept: acceptList(accept), kind, encoding }); }
+        catch { r = null; }                               // a failing host degrades like an absent one
+        if (r && typeof r === 'object') return r;
+    }
+    return browserChooser({ accept, encoding, doc: doc ?? (typeof document !== 'undefined' ? document : null) });
+}

package/src/host/host.js

@@ -22,11 +22,19 @@ export const HOST_CONTRACT = Object.freeze({
         // `chrome()` answers 'native' or 'custom', or a promise of one.
         optional: Object.freeze(['startNativeDrag', 'startNativeResize']),
     }),
-    dialogs: Object.freeze({ required: Object.freeze(['saveFile']), optional: Object.freeze([]) }),
+    // `openFile({accept, kind, encoding})` answers {ok: true, name, path?, text | data},
+    // {ok: false, cancelled: true}, {ok: false, error}, or null when there is
+    // no dialog behind it. Optional: pickFile() (file_picker.js) falls back to
+    // the browser's file chooser without it.
+    dialogs: Object.freeze({ required: Object.freeze(['saveFile']), optional: Object.freeze(['openFile']) }),
     state:   Object.freeze({ required: Object.freeze(['read', 'write']), optional: Object.freeze([]) }),
     // `openExternal(url)` hands a web address to the OS's default browser and
     // resolves true when it did. See external_links.js.
     shell:   Object.freeze({ required: Object.freeze(['openExternal']), optional: Object.freeze([]) }),
+    // `list(kind)` answers the starter entries `[{id, kind, label, description?,
+    // fields?}]` for one kind (every kind when `kind` is null), or a promise of
+    // them. Backs mountGalleryPicker() when it is given no `entries`.
+    gallery: Object.freeze({ required: Object.freeze(['list']), optional: Object.freeze([]) }),
 });
 
 /**
@@ -52,7 +60,7 @@ export function validateCapability(name, cap) {
  * Throws at boot on an incomplete capability — a half-wired host is a bug,
  * and a bug at boot beats a silent degrade at click time.
  *
- * @param {{ window?: object, dialogs?: object, state?: object, shell?: object }} caps
+ * @param {{ window?: object, dialogs?: object, state?: object, shell?: object, gallery?: object }} caps
  * @returns {Readonly<object>} the Host
  */
 export function createHost(caps = {}) {

package/src/host/photino_host.js

@@ -182,6 +182,15 @@ export function createPhotinoHost(opts = {}) {
                 catch (e) { warn('dialogs', 'saveFile', e); }
                 return r && typeof r === 'object' ? r : null;
             },
+            // `{ok: true, name, path?, text | data}` | `{ok: false, cancelled: true}` |
+            // `{ok: false, error}`, or null when the host refused: pickFile() then
+            // opens the browser's chooser. No timeout, for the same reason as saveFile.
+            async openFile({ accept = [], kind = null, encoding = 'text' } = {}) {
+                let r = null;
+                try { r = await request('dialogs', 'openFile', [{ accept, kind, encoding }], { wait: 0 }); }
+                catch (e) { warn('dialogs', 'openFile', e); }
+                return r && typeof r === 'object' ? r : null;
+            },
         },
         shell: {
             // True when the native side opened it in the system browser; false

package/src/host/photino_host.md

@@ -14,9 +14,10 @@ host → page   {"event": "window.maximizedChanged", "value": true}
 ```
 
 - Every request gets exactly one reply with the same `id`. A request that gets
-  none is given up after 10 s (`timeoutMs`). `dialogs.saveFile` is the
-  exception: the page waits for it without a timeout, because the dialog stays
-  open as long as the user takes. Always answer it.
+  none is given up after 10 s (`timeoutMs`). `dialogs.saveFile` and
+  `dialogs.openFile` are the exceptions: the page waits for them without a
+  timeout, because the dialog stays open as long as the user takes. Always
+  answer them.
 - `ok: false` means "I can't": the adapter logs it and degrades, exactly as it
   does with pywebview. Use it for unknown ops and for failures.
 - A message with no `id` and an `event` name is an event. The adapter hands it
@@ -40,6 +41,7 @@ host → page   {"event": "window.maximizedChanged", "value": true}
 | `window.startDrag` | `[]` | anything, **after mouse-up** | custom chrome only: the OS move loop (below) |
 | `window.startResize` | `[edge]`: `n` `s` `e` `w` `ne` `nw` `se` `sw` | anything, **after mouse-up** | custom chrome only: the OS size loop (below) |
 | `dialogs.saveFile` | `[{data, filename, kind}]` | see below | `ShowSaveFile(...)` + write |
+| `dialogs.openFile` | `[{accept, kind, encoding}]` | see below | `ShowOpenFile(...)` + read |
 | `shell.openExternal` | `[url]` | `true` when opened | the OS's default browser (below) |
 | `state.read` | `[key]` | the stored value, or `null` | a file per key |
 | `state.write` | `[key, value]` | `true` | a file per key |
@@ -113,6 +115,22 @@ as the reply's `value` (the envelope's own `ok` stays `true`). A reply with the
 envelope's `ok: false`, or none at all, makes `saveFile` resolve `null`, and the
 caller downloads the file the browser way instead.
 
+**`dialogs.openFile`** (0.17.0, optional). `accept` is a list of extensions or
+MIME types to filter by (`[".json"]`, may be empty), `kind` a label for the
+filter or `null`, and `encoding` `"text"` or `"base64"`. Show an open dialog,
+read the chosen file, and reply with one of:
+
+```
+{"ok": true,  "name": "model.json", "path": "C:\\Users\\me\\model.json", "text": "{...}"}   encoding "text": UTF-8
+{"ok": true,  "name": "pic.png",    "path": "C:\\Users\\me\\pic.png",    "data": "iVBO..."}  encoding "base64": the bytes
+{"ok": false, "cancelled": true}
+{"ok": false, "error": "The file is in use."}
+```
+
+as the reply's `value`. A reply with the envelope's `ok: false` (an older
+native side without the op) makes `openFile` resolve `null`, and `pickFile()`
+opens the browser's file chooser instead.
+
 **`state`.** `value` is any JSON value; store it and give it back unchanged. A
 string value that holds JSON is parsed on the way back, for hosts that store
 the text.

package/src/host/pywebview_host.js

@@ -115,6 +115,16 @@ export function createPywebviewHost({ bridgeRef = null, resolvePath = (k) => `${
             // Blob download, never report a failed save. Covered by
             // tests/ui/test_host_save_fallback.mjs.
             saveFile: ({ data, filename, kind }) => call('save_file_dialog', [data, filename, kind]),
+            // POSITIONAL on the wire like save_file_dialog: read_file_dialog(accept,
+            // kind, encoding), where `accept` is a list of extensions or MIME types
+            // (may be empty), `kind` a label for the filter or null, and `encoding`
+            // 'text' or 'base64'. The reply is openFile's result shape (host.js);
+            // null when the transport has no read_file_dialog, and pickFile() then
+            // opens the browser's file chooser instead. See the README host contract.
+            async openFile({ accept = [], kind = null, encoding = 'text' } = {}) {
+                const r = await call('read_file_dialog', [accept, kind, encoding]);
+                return r && typeof r === 'object' ? r : null;
+            },
         },
         state: {
             async read(key) {