@x-tech-laboratories/x-libs 0.9.0 → 0.11.1

package/README.md

@@ -10,11 +10,11 @@ Code the X-apps share, published as one npm package, `@x-tech-laboratories/x-lib
 | `log`                                    | Loggers by scope and level from a setting such as `"warn,play:debug"`; a malformed setting falls back instead of silencing logging, and a setting read through a function applies to loggers made before it arrived. |
 | `dates`                                  | Local dates as `"2026-06-10"` or `"2026-06-10T09:30"`: reading, writing, adding days and months, overdue, and Yesterday/Today/Tomorrow labels. |
 | `backups`                                | Named backups of an app's data in any store, newest first, with daily automatic ones kept to a set number. |
-| `electron/bridge`                        | `define_bridge`: one method table for the preload, the main process, and a web page's calls to its server; `with_cloneable_arguments` flattens what structured clone refuses, such as a Proxy. |
+| `electron/bridge`                        | `define_bridge`: one method table for the preload, the main process, and a web page's calls to its server; `handle` takes a `trusted` guard on the sender frame and answers in `envelopes`, which the client unwraps into Errors with the message alone, and a plain client strips Electron's remote-method prefix; `to_envelope`; `with_cloneable_arguments` flattens what structured clone refuses, such as a Proxy. |
 | `electron/events`                        | `define_events`: messages the main process pushes to its pages, such as progress, on one channel and subscribed to by name. |
 | `electron/app`                           | `hold_single_instance`, `bring_to_front`, and `first_argument` for a link handed over on the command line. |
 | `electron/window`                        | `create_window`: links and other sites open in the browser, the background follows the system theme, and the size and place are remembered, through the app's write guard if it has one; timers can keep running while hidden. |
-| `electron/fetch`                         | `create_main_fetch` and `create_page_fetch`: the page's requests sent from the main process past cross-origin rules, to an allow-list of hosts, with headers such as `Origin` pinned. |
+| `electron/fetch`                         | `create_main_fetch` and `create_page_fetch`: the page's requests sent from the main process past cross-origin rules, to an allow-list of hosts, with headers such as `Origin` pinned; `create_main_stream_fetch` and `create_page_stream_fetch` carry the body chunk by chunk over an events channel into a `ReadableStream` body, for a player that reads as it lands, cancelled by the request's signal. |
 | `agent/commands`                         | `run_command` and `stream_command`: one shell command, in its own process group. |
 | `agent/long_runs`                        | `LongRuns`: commands that outlive the agent, their output and exit code kept on disk. |
 | `agent/keys`                             | Reads and makes OpenSSH ed25519 agent keys; signs and checks the login challenge. |
@@ -26,30 +26,70 @@ Code the X-apps share, published as one npm package, `@x-tech-laboratories/x-lib
 | `server/passwords`                       | scrypt hashes and the `name:hash` accounts file.                              |
 | `server/hash_password`                   | The `hash-password` command.                                                  |
 | `server/backup_files`                    | `file_backup_store`: the `backups` store as files in a folder on disk.        |
-| `web/dom`, `web/format`, `web/router`, `web/theme` | The page's element builder, formatters (including `compact_count`, such as `"1.4M"`), hash router and theme choice, kept in this browser or the app's settings. |
-| `web/states`, `web/tables`, `web/menus`, `web/split` | `LoginNeeded`; sorting by several columns, trees and column order; menu items, placement and keys; pane sizing. |
+| `server/sign_in`, `server/login_page`    | `register_token_sign_in`: a server with one secret signs browsers in on its own login page, keeps them in by an HMAC-derived cookie, takes the secret as a bearer header, waits after a wrong try, and turns the rest away (401 in text or JSON under the API prefix, 303 to the login page elsewhere, with open paths); `register_sign_in_guard` is the turning-away alone, for an app with its own sessions. |
+| `server/events`                          | `EventStream`: server-sent events with a client id per page, a heartbeat, `announce_change(except_client_id)` so the page that made a change is not told, nameless or named events to all or chosen clients, and every stream ended with the app. |
+| `server/web_folder`                      | `register_web_folder`: the built page from a folder, tuned for the Nix store (no etag or date, hashed `/assets/` kept a year, the page fetched fresh), a warning, error or nothing when the folder is missing, and the page for unknown paths when it routes itself. |
+| `server/replies`                         | `register_error_replies`: errors and unknown paths answered in plain text or as `{ error }`; `register_lenient_json_body`: an empty body as no arguments and bad JSON as `BAD_JSON`, for the route to refuse in its own words; `send_text`. |
+| `server/config`                          | `read_server_config`: host, port, web folder and the app's options from flags, then the environment, then defaults, with usage text for `--help`, the secret from `<PREFIX>_TOKEN_FILE` or `<PREFIX>_TOKEN`, and no listening beyond this machine without one; `read_secret_file`. |
+| `server/cors`                            | `register_open_cors`: any origin may call the API, as a native or mobile shell does from a page of its own, with the client id header allowed. |
+| `web/dom`, `web/format`, `web/router`, `web/theme` | The page's element builder and `cx` class joiner, formatters (including `compact_count`, such as `"1.4M"`), hash router and theme choice, kept in this browser or the app's settings. |
+| `web/states`, `web/tables`, `web/menus`, `web/split`, `web/errors` | `LoginNeeded`; sorting by several columns, trees and column order; menu items, placement and keys; pane sizing; `describe_error` for anything thrown, such as shaka's coded objects. |
 | `web/tree`                               | Rows with `parent_id` and `position`: nesting, subtrees, tree order, paths, and where a dropped or keyed row lands, its siblings ordered by position or, with `by_list_order`, as the list gives them. |
-| `web/watch`, `web/react/watch`           | `create_watch`: a change counter a store bumps; `use_watch` redraws only the components that read that store. |
+| `web/watch`, `web/react/watch`           | `create_watch`: a change counter a store bumps; `use_watch` redraws only the components that read that store; `coalesce_bumps` lands a bump at most once per interval, for streamed tokens. |
+| `web/store`, `web/react/store`           | `create_store`: a value with a watch, set or updated, redrawing at a steady pace when `coalesce_in_milliseconds` is given; `use_store` reads it. |
 | `web/prefs`, `web/react/prefs`           | Remembered view settings that read as their default when stored corrupt, stale or of the wrong shape; `use_pref` keeps one as component state. |
 | `web/selection`, `web/virtual`, `web/drag` | Picking rows with plain, Ctrl and Shift clicks from a fixed anchor, or as lists of ids with the anchor kept by id, the row an arrow or page key moves to; which rows of a long list a viewport needs; a badge such as "3 tasks" as the drag image. |
 | `web/react/shell`                        | `Shell`: top bar, section links or the app's own sidebar in a `.sidebar-content` box, resizable, theme button, a `status_bar` at the foot, toasts, dialogs and menus, with or without logins (no account UI without a `user`, `logged_out` hiding the sidebar and tools), its phone menu held by the Shell or the app; `use_route`. |
-| `web/react/layout`, `badges`, `states`   | `PageHeading` with a subtitle, icon, banner and actions; panels, facts, tiles, cards, tabs, crumbs, steppers, settings rows, `RowActions` and `moved` for ordered lists, `SelectionBar` for picked rows; badges and chips; `use_resource` with its `status` (idle until `enabled`, loading, loaded, failed), a `watch` that reloads it quietly, and its loading states, `Loaded` taking an `idle` slot. |
+| `web/react/layout`, `badges`, `states`   | `PageHeading` with a subtitle, icon, banner, actions and a `level` for inside dialogs and panels; panels, facts, tiles, cards, tabs, crumbs, steppers, settings rows, `RowActions` and `moved` for ordered lists, `SelectionBar` for picked rows; badges, chips and `StatusPill`, a state dot with text and an action; `use_resource` with its `status` (idle until `enabled`, loading, loaded, failed), a `watch` that reloads it quietly, and its loading states, `Loaded` going by the status so a null result shows its `empty` slot or the children. |
 | `web/react/time`                         | `Age`: a time as how long ago, with the full stamp on hover; `use_now`, the time read again each minute. |
 | `web/react/reveal`                       | `use_reveal`: a long list shown a page at a time, the next page added as its end scrolls into view, starting from the count shown before the page was left if given. |
 | `web/react/media`                        | `Avatar`, a round picture or the name's first letter; `MediaTile` and `MediaGrid`: videos, albums or playlists as tiles in a grid or as rows, with text over the picture's corner such as a length, lines under the title, a faded look, and buttons in the corner. |
 | `web/react/menu_button`                  | `MenuButton`: a ⋮ button that opens a menu under itself, even inside a link, saying through `aria-expanded` whether it is open. |
-| `web/react/test_stubs`                   | Stands in for `showPopover`, `hidePopover`, `showModal` and `close`, which jsdom lacks; an app's widget tests import it for its side effects. |
+| `web/react/test_stubs`                   | Stands in for `showPopover`, `hidePopover`, `showModal`, `close`, `matchMedia` and `scrollTo`, which jsdom lacks; an app's widget tests import it for its side effects, and a node test's shared setup may import it too. |
 | `web/react/list_picker`                  | `pick_list_dialog`: adds one thing to any of the app's lists, such as a video to playlists, ticking the lists that hold it and making a new one. |
-| `web/react/controls`, `table`            | Segmented choices, button groups, switches, search boxes that hand on typing as it pauses, submit on Enter or a button, clear on Escape, can take a paste whole, take focus and follow a value cleared from outside, selects, `CommitInput`, `DateTimeField`, `ColorPicker`, `TreeSelect`; `DataTable` on TanStack Table, sorting by several columns, with columns to move, resize, hide and filter, tree rows, groups under headings, rows the app drags and styles, rows that come sorted from a database, rows worked by keyboard, rows that draw again only when they change, `virtual` rows drawn only where they show, a last column that fills the room left, group headings that hide when the filter empties them, and cards on phones; a pager. |
+| `web/react/controls`, `table`            | Segmented choices, button groups, switches, search boxes that hand on typing as it pauses, submit on Enter or a button, clear on Escape, can take a paste whole, take focus and follow a value cleared from outside, selects, `CommitInput`, `DateTimeField`, `PathInput` with a Browse button on the app's picker, `ColorPicker`, `TreeSelect`; `DataTable` on TanStack Table, sorting by several columns, with columns to move, resize, hide and filter, tree rows, groups under headings, rows the app drags and styles, rows that come sorted from a database, rows worked by keyboard, rows that draw again only when they change, `virtual` rows drawn only where they show, a last column that fills the room left, group headings that hide when the filter empties them, a `wrap_class` for Halon's `scroll` and `sticky-head`, and cards on phones; a pager. |
 | `web/react/shortcuts`                    | `use_shortcuts` for keys such as `"mod+z"`, quiet while typing or while a dialog or popover is open; `describe_keys` for help text. |
 | `web/react/tree`                         | `Tree`: nested rows that fold, walk with the arrow keys, reorder by dragging or with Alt and the arrow keys, show several picked, and take drops from outside. |
 | `web/react/toasts`, `dialog`, `menus`, `split` | Toasts with a link or Undo that say how they closed, and `undoable` actions that commit or undo exactly once; modal dialogs with a subtitle, header actions, a full-window size and a `form` whose submit button sends it, and confirm and text dialogs, openable from anywhere; context menus and popovers worked by keyboard, openable from anywhere, their keep-open items ticking at once; resize handles and splits. |
+| `web/react/page_view`                    | `PageView`: a full-window page over the app on the Dialog, such as Settings or an item's properties, with a Close button, actions beside it and section tabs that stay put while the body scrolls. |
+| `web/react/progress`                     | `ProgressBar`: a bar with its value out of a max, busy while the amount of work is unknown, and words or the percentage beside it. |
+| `web/react/rating`                       | `Rating`: stars that show a rating or take one by click or keyboard, with unrated kept apart from none. |
+| `web/react/volume`                       | `VolumeButton`: a speaker button that opens a slider; scrolling over it adjusts the volume and a middle-click mutes. |
+| `web/react/following`                    | `use_follow_tail`, `FollowingOutput` and `FollowToggle`: output that keeps its newest lines in view as they arrive unless the reader scrolled up, with a Follow switch. |
+| `web/react/markdown`                     | `Markdown` and `render_markdown` on marked and DOMPurify, chosen because marked covers the hand-written parser feature for feature and adds tables and nested lists: raw HTML shows as text, only web links are clickable and open in a new tab, and `follow` keeps streamed text in view. |
+| `web/react/suggestions`                  | `Suggestions`: completions under any text field from a sync or async source; arrow keys choose, Tab or Enter take, Escape dismisses, other keys pass through. |
 
 ```ts
 import { AgentHub } from "@x-tech-laboratories/x-libs/server/agents/hub";
 import { parse_duration } from "@x-tech-laboratories/x-libs/durations";
 ```
 
+## A web app's server
+
+The server modules are small Fastify pieces an app registers one by one, so each app keeps only what it needs.
+
+```ts
+const config = read_server_config({
+  program: "x-tasks-server", summary: "Serves X-Tasks as a web app.", env_prefix: "X_TASKS", default_port: 3918,
+  web_folder_default: join(import.meta.dirname, "../web"),
+  options: { database: { variable: "X_TASKS_DB", help: "the task database; it is made if missing", placeholder: "<file>", required: true } },
+});
+const app = fastify({ forceCloseConnections: true });
+register_lenient_json_body(app);
+register_error_replies(app);
+await register_token_sign_in(app, { secret: config.secret, title: "X-Tasks" });
+const changes = new EventStream();
+await app.register(async (api) => {
+  await register_open_cors(api);
+  changes.register(api, "/events");
+  api.post("/add", async (request) => { ...; changes.announce_change(changes.client_id_of(request)); });
+}, { prefix: "/api" });
+await register_web_folder(app, { folder: config.web_folder });
+```
+
+An app with its own sessions, such as one logging in by name and password, uses `register_sign_in_guard` with its
+own `is_signed_in`, `login_path: null` so its page loads and logs in itself, and `refusal: "json"`.
+
 ## The page's widgets
 
 The widgets build Halon's markup, so their look comes from Halon's web stylesheets in `@x-tech-laboratories/halon`,

package/dist/electron/bridge.d.ts

@@ -2,6 +2,11 @@ export interface IpcMainLike {
     handle(channel: string, listener: (event: unknown, ...args: unknown[]) => unknown): void;
     removeHandler(channel: string): void;
 }
+export interface IpcMainEventLike {
+    senderFrame?: {
+        url: string;
+    } | null;
+}
 export interface IpcRendererLike {
     invoke(channel: string, ...args: unknown[]): Promise<unknown>;
 }
@@ -16,17 +21,35 @@ export type Implementation<Methods extends Record<keyof Methods, AnyMethod>> = {
     [Name in keyof Methods]: (...args: Parameters<Methods[Name]>) => Awaited<ReturnType<Methods[Name]>> | Promise<Awaited<ReturnType<Methods[Name]>>>;
 };
 export type CallRemote = (method: string, args: unknown[]) => Promise<unknown>;
+export type Envelope<Result = unknown> = {
+    ok: true;
+    result: Result;
+} | {
+    ok: false;
+    error: string;
+};
+export interface HandleOptions {
+    trusted?: (event: IpcMainEventLike) => boolean;
+    envelopes?: boolean;
+}
+export interface ClientOptions {
+    envelopes?: boolean;
+}
 export interface Bridge<Methods extends Record<keyof Methods, AnyMethod>> {
     api_name: string;
     method_names: readonly (keyof Methods & string)[];
     channel: (method: keyof Methods & string) => string;
-    expose: (context_bridge: ContextBridgeLike, ipc_renderer: IpcRendererLike) => void;
-    ipc_client: (ipc_renderer: IpcRendererLike) => Client<Methods>;
-    handle: (ipc_main: IpcMainLike, implementation: Implementation<Methods>) => () => void;
+    expose: (context_bridge: ContextBridgeLike, ipc_renderer: IpcRendererLike, options?: ClientOptions) => void;
+    ipc_client: (ipc_renderer: IpcRendererLike, options?: ClientOptions) => Client<Methods>;
+    handle: (ipc_main: IpcMainLike, implementation: Implementation<Methods>, options?: HandleOptions) => () => void;
     web_rpc: (call_remote: CallRemote) => Client<Methods>;
     dispatch: (implementation: Implementation<Methods>, method: string, args: unknown[]) => Promise<unknown>;
 }
 export declare function define_bridge<Methods extends Record<keyof Methods, AnyMethod>>(api_name: string, method_names: readonly (keyof Methods & string)[]): Bridge<Methods>;
+export declare function to_envelope<Result>(work: () => Result | Promise<Result>): Promise<Envelope<Awaited<Result>>>;
+export declare function clean_error_message(message: string): string;
+export declare function clean_invoker(ipc_renderer: IpcRendererLike): IpcRendererLike;
+export declare function unwrapping_invoker(ipc_renderer: IpcRendererLike): IpcRendererLike;
 export declare function to_cloneable(value: unknown): unknown;
 export declare function with_cloneable_arguments<Methods extends Record<keyof Methods, AnyMethod>>(client: Client<Methods>): Client<Methods>;
 export {};

package/dist/electron/bridge.js

@@ -11,18 +11,29 @@ export function define_bridge(api_name, method_names) {
         const answer = implementation[method];
         return answer.apply(implementation, args);
     }
+    const ipc_client = (ipc_renderer, options = {}) => {
+        const invoke = options.envelopes ? unwrapping_invoker(ipc_renderer) : clean_invoker(ipc_renderer);
+        return client_through((method, args) => invoke.invoke(channel(method), ...args));
+    };
     return {
         api_name,
         method_names,
         channel,
         dispatch,
-        ipc_client: (ipc_renderer) => client_through((method, args) => ipc_renderer.invoke(channel(method), ...args)),
-        expose: (context_bridge, ipc_renderer) => {
-            context_bridge.exposeInMainWorld(api_name, client_through((method, args) => ipc_renderer.invoke(channel(method), ...args)));
+        ipc_client,
+        expose: (context_bridge, ipc_renderer, options) => {
+            context_bridge.exposeInMainWorld(api_name, ipc_client(ipc_renderer, options));
         },
-        handle: (ipc_main, implementation) => {
+        handle: (ipc_main, implementation, options = {}) => {
             for (const method of method_names) {
-                ipc_main.handle(channel(method), (_event, ...args) => dispatch(implementation, method, args));
+                ipc_main.handle(channel(method), (event, ...args) => {
+                    const answer = () => {
+                        if (options.trusted && !options.trusted((event ?? {})))
+                            throw new Error("Untrusted sender.");
+                        return dispatch(implementation, method, args);
+                    };
+                    return options.envelopes ? to_envelope(answer) : answer();
+                });
             }
             return () => { for (const method of method_names)
                 ipc_main.removeHandler(channel(method)); };
@@ -30,6 +41,47 @@ export function define_bridge(api_name, method_names) {
         web_rpc: client_through,
     };
 }
+// ── Envelopes and errors ─────────────────────────────────────────────────────
+// Runs the work and puts its result or its failure's words in an envelope.
+export async function to_envelope(work) {
+    try {
+        return { ok: true, result: await work() };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+const REMOTE_ERROR_PREFIX = /^Error invoking remote method '[^']*': (?:\w*Error: )?/;
+// Electron reports a rejected handler as "Error invoking remote method 'x': Error: words", which the page shows as the words alone.
+export function clean_error_message(message) {
+    return message.replace(REMOTE_ERROR_PREFIX, "");
+}
+// An ipcRenderer whose rejections carry clean messages.
+export function clean_invoker(ipc_renderer) {
+    return {
+        invoke: async (channel, ...args) => {
+            try {
+                return await ipc_renderer.invoke(channel, ...args);
+            }
+            catch (error) {
+                if (error instanceof Error)
+                    throw new Error(clean_error_message(error.message));
+                throw error;
+            }
+        },
+    };
+}
+// An ipcRenderer that opens envelope replies, throwing a failure as an Error with its message.
+export function unwrapping_invoker(ipc_renderer) {
+    return {
+        invoke: async (channel, ...args) => {
+            const envelope = (await ipc_renderer.invoke(channel, ...args));
+            if (!envelope.ok)
+                throw new Error(envelope.error);
+            return envelope.result;
+        },
+    };
+}
 // ── Cloning ──────────────────────────────────────────────────────────────────
 // A value that survives structured clone passes as it is, and anything else, such as a Proxy, crosses as plain JSON.
 export function to_cloneable(value) {

package/dist/electron/fetch.d.ts

@@ -12,14 +12,41 @@ export interface FetchAnswer {
     body: Uint8Array<ArrayBuffer> | null;
 }
 export type FetchMethod = (request: FetchRequest) => FetchAnswer;
+export interface StreamRequest extends FetchRequest {
+    stream_id: string;
+}
+export type StreamHead = Omit<FetchAnswer, "body">;
+export type StreamChunk = {
+    stream_id: string;
+    bytes: Uint8Array<ArrayBuffer>;
+} | {
+    stream_id: string;
+    done: true;
+} | {
+    stream_id: string;
+    error: string;
+};
+export type StreamStartMethod = (request: StreamRequest) => StreamHead;
+export type StreamCancelMethod = (stream_id: string) => void;
 export interface FetchPolicy {
     hosts: readonly string[];
     allow_http?: boolean;
 }
 export declare function is_allowed_url(url: string, policy: FetchPolicy): boolean;
 export declare function create_main_fetch(policy: FetchPolicy, send?: typeof fetch): (request: FetchRequest) => Promise<FetchAnswer>;
+export interface MainStreamFetch {
+    start: (request: StreamRequest) => Promise<StreamHead>;
+    cancel: (stream_id: string) => void;
+}
+export declare function create_main_stream_fetch(policy: FetchPolicy, emit: (chunk: StreamChunk) => void, send?: typeof fetch): MainStreamFetch;
 export interface PageFetchOptions {
     pinned_headers?: Record<string, string>;
 }
 export declare function to_response(answer: FetchAnswer): Response;
 export declare function create_page_fetch(send: (request: FetchRequest) => Promise<FetchAnswer>, options?: PageFetchOptions): (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export interface PageStreamBridge {
+    start: (request: StreamRequest) => Promise<StreamHead>;
+    cancel?: (stream_id: string) => Promise<void> | void;
+    on_chunk: (handler: (chunk: StreamChunk) => void) => () => void;
+}
+export declare function create_page_stream_fetch(bridge: PageStreamBridge, options?: PageFetchOptions): (input: string | URL | Request, init?: RequestInit) => Promise<Response>;

package/dist/electron/fetch.js

@@ -1,4 +1,4 @@
-// Fetching from Electron's main process for a page whose own requests the browser's cross-origin rules would block.
+// Fetching from Electron's main process for a page whose own requests the browser's cross-origin rules would block, with the body whole or streamed in chunks.
 const NULL_BODY_STATUSES = new Set([101, 204, 205, 304]);
 export function is_allowed_url(url, policy) {
     let parsed;
@@ -34,6 +34,56 @@ export function create_main_fetch(policy, send = fetch) {
         };
     };
 }
+// The main process's half of a streamed fetch: answers with the head and sends each chunk of the body through emit as it arrives.
+export function create_main_stream_fetch(policy, emit, send = fetch) {
+    const open = new Map();
+    async function pump(stream_id, body, controller) {
+        const reader = body.getReader();
+        try {
+            while (!controller.signal.aborted) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                emit({ stream_id, bytes: new Uint8Array(value) });
+            }
+            if (!controller.signal.aborted)
+                emit({ stream_id, done: true });
+        }
+        catch (error) {
+            if (!controller.signal.aborted)
+                emit({ stream_id, error: error instanceof Error ? error.message : String(error) });
+        }
+        finally {
+            open.delete(stream_id);
+        }
+    }
+    return {
+        start: async (request) => {
+            if (!is_allowed_url(request.url, policy))
+                throw new Error(`fetching ${request.url} is not allowed`);
+            const controller = new AbortController();
+            open.set(request.stream_id, controller);
+            const response = await send(request.url, { method: request.method, headers: request.headers, body: request.body, signal: controller.signal });
+            const headers = [];
+            response.headers.forEach((value, name) => {
+                if (!DROPPED_ANSWER_HEADERS.has(name))
+                    headers.push([name, value]);
+            });
+            const has_body = response.body !== null && !NULL_BODY_STATUSES.has(response.status) && request.method !== "HEAD";
+            if (has_body)
+                void pump(request.stream_id, response.body, controller);
+            else {
+                open.delete(request.stream_id);
+                emit({ stream_id: request.stream_id, done: true });
+            }
+            return { status: response.status, status_text: response.statusText, headers };
+        },
+        cancel: (stream_id) => {
+            open.get(stream_id)?.abort();
+            open.delete(stream_id);
+        },
+    };
+}
 function abort_error() {
     return new DOMException("The request was aborted", "AbortError");
 }
@@ -65,3 +115,61 @@ export function create_page_fetch(send, options = {}) {
         return to_response(answer);
     };
 }
+let next_stream_number = 0;
+const new_stream_id = () => `${Date.now().toString(36)}-${(next_stream_number++).toString(36)}`;
+// The page's half of a streamed fetch: a fetch whose Response body is a ReadableStream fed by the chunks, so a player reads them as they land.
+export function create_page_stream_fetch(bridge, options = {}) {
+    return async (input, init) => {
+        const request = new Request(input, init);
+        const signal = init?.signal ?? request.signal;
+        const stream_id = new_stream_id();
+        const headers = new Headers(request.headers);
+        for (const [name, value] of Object.entries(options.pinned_headers ?? {}))
+            headers.set(name, value);
+        const body = request.method === "GET" || request.method === "HEAD" ? undefined : new Uint8Array(await request.arrayBuffer());
+        // Chunks may land before the head answers, so the listener is in place first and the stream holds them.
+        let stop_listening = () => { };
+        const stream = new ReadableStream({
+            start(controller) {
+                const finish = () => { stop_listening(); signal?.removeEventListener("abort", on_abort); };
+                const on_abort = () => {
+                    finish();
+                    void bridge.cancel?.(stream_id);
+                    try {
+                        controller.error(abort_error());
+                    }
+                    catch { /* already closed */ }
+                };
+                stop_listening = bridge.on_chunk((chunk) => {
+                    if (chunk.stream_id !== stream_id)
+                        return;
+                    if ("bytes" in chunk)
+                        controller.enqueue(chunk.bytes);
+                    else {
+                        finish();
+                        if ("error" in chunk)
+                            controller.error(new TypeError(chunk.error));
+                        else
+                            controller.close();
+                    }
+                });
+                signal?.addEventListener("abort", on_abort, { once: true });
+            },
+            cancel() {
+                stop_listening();
+                void bridge.cancel?.(stream_id);
+            },
+        });
+        try {
+            const head = await until_aborted(bridge.start({ stream_id, url: request.url, method: request.method, headers: [...headers.entries()], body }), signal);
+            const streams = !NULL_BODY_STATUSES.has(head.status) && request.method !== "HEAD";
+            if (!streams)
+                void stream.cancel();
+            return new Response(streams ? stream : null, { status: head.status, statusText: head.status_text, headers: head.headers });
+        }
+        catch (error) {
+            stop_listening();
+            throw error;
+        }
+    };
+}

package/dist/server/config.d.ts

@@ -0,0 +1,39 @@
+export interface ConfigOption {
+    variable?: string;
+    flag?: string;
+    help: string;
+    placeholder?: string;
+    default?: string;
+    required?: boolean;
+}
+export interface ServerConfigSpec<Name extends string = never> {
+    program: string;
+    summary: string;
+    env_prefix: string;
+    default_port: number;
+    options?: Record<Name, ConfigOption>;
+    built_in?: Partial<Record<BuiltInName, Partial<ConfigOption>>>;
+    web_folder_default?: string;
+    secret?: string | false;
+    argv?: string[];
+    env?: Record<string, string | undefined>;
+    exit_on_help?: boolean;
+}
+export interface ServerConfig<Name extends string = never> {
+    host: string;
+    port: number;
+    web_folder: string;
+    secret: string;
+    values: Record<Name, string | undefined>;
+    usage: string;
+}
+type BuiltInName = "host" | "port" | "web_folder";
+export declare class HelpRequested extends Error {
+    readonly usage: string;
+    constructor(usage: string);
+}
+export declare const loopback_hosts: string[];
+export declare function is_loopback(host: string): boolean;
+export declare function read_secret_file(path: string): string;
+export declare function read_server_config<Name extends string = never>(spec: ServerConfigSpec<Name>): ServerConfig<Name>;
+export {};

package/dist/server/config.js

@@ -0,0 +1,109 @@
+// A server's settings from the command line and the environment: the address and port, the web folder, the app's own
+// options, and the secret browsers sign in with, read from a file or a variable. Without a secret the server may only
+// listen on this machine.
+// ── Imports ──────────────────────────────────────────────────────────────────
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+export class HelpRequested extends Error {
+    usage;
+    constructor(usage) {
+        super(usage);
+        this.usage = usage;
+    }
+}
+// ── Settings ─────────────────────────────────────────────────────────────────
+export const loopback_hosts = ["127.0.0.1", "::1", "localhost"];
+export function is_loopback(host) {
+    return loopback_hosts.includes(host);
+}
+// ── Secrets ──────────────────────────────────────────────────────────────────
+// The file's text without its final newline; an unreadable or empty file is an error.
+export function read_secret_file(path) {
+    let secret;
+    try {
+        secret = readFileSync(path, "utf8").replace(/\r?\n$/, "");
+    }
+    catch (error) {
+        throw new Error(`Could not read the secret at ${path}: ${error.message}`);
+    }
+    if (secret.trim() === "")
+        throw new Error(`The secret at ${path} is empty`);
+    return secret.trim();
+}
+// ── Reading ──────────────────────────────────────────────────────────────────
+function capitals(name) {
+    return name.replaceAll("-", "_").toUpperCase();
+}
+function usage_text(program, summary, options, secret_note) {
+    const entries = Object.values(options);
+    const synopsis = entries
+        .map((option) => (option.required ? `--${option.flag} ${option.placeholder}` : `[--${option.flag} ${option.placeholder}]`))
+        .join(" ");
+    const flag_width = Math.max(...entries.map((option) => option.flag.length)) + 2;
+    const variable_width = Math.max(...entries.map((option) => option.variable.length));
+    const rows = entries.map((option) => {
+        const suffix = option.default === undefined ? "" : ` (default ${option.default})`;
+        return `  ${`--${option.flag}`.padEnd(flag_width)}  ${option.variable.padEnd(variable_width)}  ${option.help}${suffix}`;
+    });
+    return `Usage: ${program} ${synopsis}\n\n${summary} Every option can also be set in the environment:\n${rows.join("\n")}${secret_note}`;
+}
+export function read_server_config(spec) {
+    const { env_prefix, argv = process.argv.slice(2), env = process.env, exit_on_help = true } = spec;
+    const secret_name = spec.secret === undefined ? "token" : spec.secret;
+    const own = (spec.options ?? {});
+    const changes = spec.built_in ?? {};
+    const built_in = {
+        host: { help: "the address to listen on", placeholder: "<address>", default: "127.0.0.1", ...changes.host },
+        port: { help: "the port to listen on", placeholder: "<number>", default: String(spec.default_port), ...changes.port },
+    };
+    if (spec.web_folder_default !== undefined) {
+        built_in.web_folder = { help: "the built web page", placeholder: "<folder>", default: spec.web_folder_default, ...changes.web_folder };
+    }
+    const options = Object.fromEntries(Object.entries({ ...own, ...built_in }).map(([name, option]) => [name, {
+            ...option,
+            variable: option.variable ?? `${env_prefix}_${capitals(name)}`,
+            flag: option.flag ?? name.replaceAll("_", "-"),
+            placeholder: option.placeholder ?? "<value>",
+        }]));
+    const secret_note = secret_name === false ? "" : `\n\nThe ${secret_name} browsers sign in with is read from the file named by ${env_prefix}_${capitals(secret_name)}_FILE,\nor from ${env_prefix}_${capitals(secret_name)}. Without one the server only listens on this machine.`;
+    const usage = usage_text(spec.program, spec.summary, options, secret_note);
+    const { values: flags } = parseArgs({
+        args: argv,
+        options: { ...Object.fromEntries(Object.values(options).map((option) => [option.flag, { type: "string" }])), help: { type: "boolean" } },
+    });
+    if (flags.help) {
+        if (!exit_on_help)
+            throw new HelpRequested(usage);
+        console.log(usage);
+        process.exit(0);
+    }
+    const value_of = (name) => {
+        const option = options[name];
+        return flags[option.flag] ?? env[option.variable] ?? option.default;
+    };
+    for (const [name, option] of Object.entries(options)) {
+        if (option.required && value_of(name) === undefined)
+            throw new Error(`no ${option.flag} given\n\n${usage}`);
+    }
+    const port_text = value_of("port");
+    const port = Number(port_text);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new Error(`not a port: ${port_text}`);
+    let secret = "";
+    if (secret_name !== false) {
+        const secret_file = env[`${env_prefix}_${capitals(secret_name)}_FILE`];
+        secret = secret_file ? read_secret_file(secret_file) : (env[`${env_prefix}_${capitals(secret_name)}`] ?? "").trim();
+    }
+    const host = value_of("host");
+    if (secret_name !== false && secret === "" && !is_loopback(host)) {
+        throw new Error(`listening on ${host} needs a ${secret_name}; set ${env_prefix}_${capitals(secret_name)}_FILE or ${env_prefix}_${capitals(secret_name)}`);
+    }
+    return {
+        host,
+        port,
+        web_folder: "web_folder" in options ? value_of("web_folder") : "",
+        secret,
+        values: Object.fromEntries(Object.keys(own).map((name) => [name, value_of(name)])),
+        usage,
+    };
+}

package/dist/server/cors.d.ts

@@ -0,0 +1,8 @@
+import type { FastifyInstance } from "fastify";
+export interface OpenCorsOptions {
+    methods?: string[];
+    allowed_headers?: string[];
+    client_id_header?: string;
+    max_age_seconds?: number;
+}
+export declare function register_open_cors(app: FastifyInstance, options?: OpenCorsOptions): Promise<void>;

package/dist/server/cors.js

@@ -0,0 +1,13 @@
+// Cross-origin access for an API that a native or mobile shell calls from a page of its own: any origin may, since a
+// browser sends no cookies with such a call and the server's secret is still needed.
+import fastify_cors from "@fastify/cors";
+import { default_client_id_header } from "./events.js";
+export async function register_open_cors(app, options = {}) {
+    const { methods = ["GET", "POST"], allowed_headers = [], client_id_header = default_client_id_header, max_age_seconds = 86_400 } = options;
+    await app.register(fastify_cors, {
+        origin: "*",
+        methods,
+        allowedHeaders: ["authorization", "content-type", client_id_header, ...allowed_headers],
+        maxAge: max_age_seconds,
+    });
+}

package/dist/server/events.d.ts

@@ -0,0 +1,33 @@
+import type { FastifyInstance, FastifyRequest } from "fastify";
+export interface EventStreamOptions {
+    heartbeat_ms?: number;
+    retry_ms?: number;
+    hello_event?: string | null;
+    changed_event?: string;
+    client_id_header?: string;
+}
+export interface StreamClient {
+    id: string;
+    request: FastifyRequest;
+}
+export interface SendOptions {
+    event?: string;
+    except_client_id?: string;
+    to?: (client: StreamClient) => boolean;
+}
+export declare const default_client_id_header = "x-client-id";
+export declare class EventStream {
+    readonly heartbeat_ms: number;
+    readonly retry_ms: number;
+    readonly hello_event: string | null;
+    readonly changed_event: string;
+    readonly client_id_header: string;
+    private readonly streams;
+    constructor(options?: EventStreamOptions);
+    get client_count(): number;
+    client_id_of(request: FastifyRequest): string;
+    send(data: string, options?: SendOptions): void;
+    announce_change(except_client_id?: string): void;
+    register(app: FastifyInstance, path?: string): void;
+    close(): void;
+}