@x-tech-laboratories/x-libs 0.4.0 → 0.7.0

package/README.md

@@ -6,7 +6,15 @@ Code the X-apps share, published as one npm package, `@x-tech-laboratories/x-lib
 
 | Import                                   | What it holds                                                                 |
 | ---------------------------------------- | ----------------------------------------------------------------------------- |
-| `durations`                              | `parse_duration` for settings such as `"2h30m"`, `format_duration`, `format_age`. |
+| `durations`                              | `parse_duration` for settings such as `"2h30m"`, `format_duration` in months down to seconds, `format_age`, and `format_clock` for a playing time such as `"3:07"`. |
+| `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/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. |
 | `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. |
@@ -17,13 +25,21 @@ Code the X-apps share, published as one npm package, `@x-tech-laboratories/x-lib
 | `server/agents/connection`, `agent`, `local`, `route` | One connected agent, the `Agent` interface, `LocalAgent`, and the Fastify route. |
 | `server/passwords`                       | scrypt hashes and the `name:hash` accounts file.                              |
 | `server/hash_password`                   | The `hash-password` command.                                                  |
-| `web/dom`, `web/format`, `web/router`, `web/theme` | The page's element builder, formatters, hash router and theme choice. |
-| `web/states`, `web/tables`, `web/menus`, `web/split` | `LoginNeeded`; table sorting; menu items and on-screen placement; pane sizing. |
-| `web/preact/shell`                       | `Shell`: top bar, sidebar, theme button, toasts and dialogs; `use_route`.       |
-| `web/preact/layout`, `badges`, `states`  | Panels, facts, tiles, cards, tabs, crumbs, steppers, settings rows; badges and chips; `use_resource` and its loading states. |
-| `web/preact/time`                        | `Age`: a time as how long ago, with the full stamp on hover. |
-| `web/preact/controls`, `table`           | Segmented choices, button groups, switches, search boxes, selects; sortable tables that turn into cards on phones, and a pager. |
-| `web/preact/toasts`, `dialog`, `menus`, `split` | Toasts with a link or Undo; modal, confirm and text dialogs openable from anywhere; context menus and popovers; resize handles and splits. |
+| `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. |
+| `web/tree`                               | Rows with `parent_id` and `position`: nesting, subtrees, tree order, paths, and where a dropped or keyed row lands. |
+| `web/watch`, `web/react/watch`           | `create_watch`: a change counter a store bumps; `use_watch` redraws only the components that read that store. |
+| `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, resizable, theme button, toasts, dialogs and menus, with or without logins, its phone menu held by the Shell or the app; `use_route`. |
+| `web/react/layout`, `badges`, `states`   | Panels, facts, tiles, cards, tabs, crumbs, steppers, settings rows, `RowActions` and `moved` for ordered lists, `SelectionBar` for picked rows; badges and chips; `use_resource` and its loading states. |
+| `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. |
+| `web/react/controls`, `table`            | Segmented choices, button groups, switches, search boxes that can 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, 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, confirm and text dialogs openable from anywhere; context menus and popovers worked by keyboard, openable from anywhere; resize handles and splits. |
 
 ```ts
 import { AgentHub } from "@x-tech-laboratories/x-libs/server/agents/hub";
@@ -38,13 +54,73 @@ which an app imports once:
 ```ts
 import "@x-tech-laboratories/halon/halon-tokens.css";
 import "@x-tech-laboratories/halon/halon.css";
-import { DataTable } from "@x-tech-laboratories/x-libs/web/preact/table";
-import { toast } from "@x-tech-laboratories/x-libs/web/preact/toasts";
+import { DataTable } from "@x-tech-laboratories/x-libs/web/react/table";
+import { toast } from "@x-tech-laboratories/x-libs/web/react/toasts";
 ```
 
-The widgets are Preact components, so a page renders with Preact; `Shell` holds the toasts and dialogs that `toast` and
-`confirm_dialog` open from anywhere. A request whose session has lapsed throws `LoginNeeded` from `web/states`, and
-`use_resource` passes it on as an unhandled rejection, which the page's login listens for.
+The widgets are React components, so a page renders with React through `createRoot` from `react-dom/client`; `Shell`
+holds the toasts, dialogs and menus that `toast`, `confirm_dialog` and `open_context_menu` open from anywhere. `DataTable`
+is drawn on `@tanstack/react-table` with Halon's markup; its sorting, column order, widths, hidden columns and open rows
+are props with change callbacks, so the app keeps them in its own settings, and a column's filter is the app's own
+content in a popover X-Libs opens from the column's funnel. A request whose session has lapsed
+throws `LoginNeeded` from `web/states`, and `use_resource` passes it on as an unhandled rejection, which the page's
+login listens for.
+
+## Shortcuts and trees
+
+```tsx
+import { use_shortcuts } from "@x-tech-laboratories/x-libs/web/react/shortcuts";
+import { Tree } from "@x-tech-laboratories/x-libs/web/react/tree";
+
+use_shortcuts([
+  { keys: "mod+z", run: undo },
+  { keys: "escape", run: clear_picks },
+]);
+
+<Tree items={tags} label="Tags" render_item={(tag) => tag.name} collapsed={collapsed} on_collapsed_change={set_collapsed}
+  on_move={(tag, { parent_id, position }) => move_tag(tag.id, parent_id, position)} />
+```
+
+A shortcut stays quiet in text fields unless it has `when: "always"`, and while a dialog or popover is open unless it
+has `over_overlays: true`. The tree builds Halon's `.tree` markup; a row dropped onto its top or bottom quarter lands
+beside it, and onto its middle inside it.
+
+## Electron apps
+
+The bridge and window helpers describe the few parts of Electron they use, so the app passes Electron's own objects in
+and X-Libs does not depend on Electron.
+
+```ts
+// shared
+export const notes_bridge = define_bridge<NotesApi>("x_notes", ["list_notes", "add_note"]);
+// preload
+notes_bridge.expose(contextBridge, ipcRenderer);
+// main
+notes_bridge.handle(ipcMain, { list_notes, add_note });
+create_window(BrowserWindow, {
+  title: "X-Notes", file: join(__dirname, "../renderer/index.html"), dev_url: process.env.ELECTRON_RENDERER_URL,
+  preload: join(__dirname, "../preload/index.mjs"), default_size: { width: 1100, height: 700 },
+  state_file: join(app.getPath("userData"), "window.json"), native_theme: nativeTheme, shell,
+});
+// web page
+window.x_notes = notes_bridge.web_rpc((method, args) => post_json(`api/${method}`, args));
+```
+
+A page that must reach another site, such as an API that sends no CORS headers, sends its requests through the main
+process with `electron/fetch`. The main process allows only the hosts it lists; the page gets a `fetch` to hand to a
+library.
+
+```ts
+// shared
+export const media_bridge = define_bridge<{ http_fetch: FetchMethod }>("x_media", ["http_fetch"]);
+// main
+media_bridge.handle(ipcMain, { http_fetch: create_main_fetch({ hosts: ["api.example.com", "*.cdn.example.com"] }) });
+// web page
+const page_fetch = create_page_fetch((request) => window.x_media.http_fetch(request), { pinned_headers: { Origin: "https://example.com" } });
+```
+
+`create_window` keeps the app's own pages in the window: a link or a navigation to another site opens in the browser,
+and only web and mail links leave the app.
 
 ## The app and its tasks
 

package/dist/backups.d.ts

@@ -0,0 +1,31 @@
+export interface Backup {
+    name: string;
+    taken_at: string;
+    is_automatic: boolean;
+    size_bytes: number;
+}
+export interface BackupNaming {
+    pattern: RegExp;
+    name_for: (taken_at: Date, is_automatic: boolean) => string;
+    describe: (name: string, size_bytes: number) => Backup;
+}
+export declare function backup_naming(prefix: string, extension: string): BackupNaming;
+export interface BackupStore {
+    list: () => Promise<{
+        name: string;
+        size_bytes: number;
+    }[]> | {
+        name: string;
+        size_bytes: number;
+    }[];
+    take: (name: string) => Promise<number> | number;
+    remove: (name: string) => Promise<void> | void;
+}
+export interface Backups {
+    naming: BackupNaming;
+    list: () => Promise<Backup[]>;
+    create: (is_automatic?: boolean) => Promise<Backup>;
+    remove: (name: string) => Promise<void>;
+    keep_automatic: (to_keep: number, interval_in_milliseconds?: number, now?: Date) => Promise<void>;
+}
+export declare function backups(naming: BackupNaming, store: BackupStore): Backups;

package/dist/backups.js

@@ -0,0 +1,43 @@
+// Named backups of an app's data: the name says when each was taken and whether it was automatic, and daily ones keep a set number.
+const escaped = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+// Names such as tasks-2026-06-10T09-30-00Z-auto.db for the prefix "tasks" and the extension ".db".
+export function backup_naming(prefix, extension) {
+    const pattern = new RegExp(`^${escaped(prefix)}-(\\d{4}-\\d{2}-\\d{2})T(\\d{2})-(\\d{2})-(\\d{2})Z(-auto)?${escaped(extension)}$`);
+    return {
+        pattern,
+        name_for: (taken_at, is_automatic) => `${prefix}-${taken_at.toISOString().slice(0, 19).replaceAll(":", "-")}Z${is_automatic ? "-auto" : ""}${extension}`,
+        describe: (name, size_bytes) => {
+            const match = pattern.exec(name);
+            if (!match)
+                throw new Error(`not a backup name: ${name}`);
+            const [, date, hours, minutes, seconds, automatic] = match;
+            return { name, taken_at: `${date}T${hours}:${minutes}:${seconds}Z`, is_automatic: automatic !== undefined, size_bytes };
+        },
+    };
+}
+const day_in_milliseconds = 24 * 60 * 60 * 1000;
+export function backups(naming, store) {
+    const list = async () => (await store.list())
+        .filter((file) => naming.pattern.test(file.name))
+        .map((file) => naming.describe(file.name, file.size_bytes))
+        .sort((first, second) => second.taken_at.localeCompare(first.taken_at));
+    const remove = async (name) => {
+        if (!naming.pattern.test(name))
+            throw new Error(`not a backup name: ${name}`);
+        await store.remove(name);
+    };
+    const create = async (is_automatic = false, now = new Date()) => {
+        const name = naming.name_for(now, is_automatic);
+        const existing = (await list()).find((backup) => backup.name === name);
+        return existing ?? naming.describe(name, await store.take(name));
+    };
+    const keep_automatic = async (to_keep, interval_in_milliseconds = day_in_milliseconds, now = new Date()) => {
+        const newest = (await list()).find((backup) => backup.is_automatic);
+        if (!newest || now.getTime() - Date.parse(newest.taken_at) >= interval_in_milliseconds)
+            await create(true, now);
+        const automatic = (await list()).filter((backup) => backup.is_automatic);
+        for (const backup of automatic.slice(Math.max(0, to_keep)))
+            await remove(backup.name);
+    };
+    return { naming, list, create: (is_automatic) => create(is_automatic), remove, keep_automatic };
+}

package/dist/dates.d.ts

@@ -0,0 +1,9 @@
+export declare function has_time(local_date: string): boolean;
+export declare function parse_local(local_date: string): Date;
+export declare function format_local(date: Date, with_time: boolean): string;
+export declare function start_of_day(date: Date): Date;
+export declare function days_between(first: Date, second: Date): number;
+export declare function add_days(date: Date, days: number): Date;
+export declare function add_months(date: Date, months: number): Date;
+export declare function is_overdue(local_date: string, now?: Date): boolean;
+export declare function relative_day_label(local_date: string, now?: Date, locale?: string): string;

package/dist/dates.js

@@ -0,0 +1,60 @@
+// Local calendar dates written as "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM", read and written in the device's own time zone.
+const DAY_IN_MILLISECONDS = 24 * 60 * 60 * 1000;
+// ── Text and dates ───────────────────────────────────────────────────────────
+export function has_time(local_date) {
+    return local_date.includes("T");
+}
+// A date without a time stands for midnight at the start of its day.
+export function parse_local(local_date) {
+    const [day = "", time = "00:00"] = local_date.split("T");
+    const [year = 0, month = 1, day_of_month = 1] = day.split("-").map(Number);
+    const [hours = 0, minutes = 0] = time.split(":").map(Number);
+    return new Date(year, month - 1, day_of_month, hours, minutes);
+}
+export function format_local(date, with_time) {
+    const pad = (number) => String(number).padStart(2, "0");
+    const day = `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+    return with_time ? `${day}T${pad(date.getHours())}:${pad(date.getMinutes())}` : day;
+}
+// ── Arithmetic ───────────────────────────────────────────────────────────────
+export function start_of_day(date) {
+    return new Date(date.getFullYear(), date.getMonth(), date.getDate());
+}
+// Whole calendar days from the first date to the second, so a clock change in between still counts as one day.
+export function days_between(first, second) {
+    return Math.round((start_of_day(second).getTime() - start_of_day(first).getTime()) / DAY_IN_MILLISECONDS);
+}
+export function add_days(date, days) {
+    const moved = new Date(date);
+    moved.setDate(moved.getDate() + days);
+    return moved;
+}
+// A day past the end of the target month falls back to its last day, so Jan 31 plus a month is Feb 28.
+export function add_months(date, months) {
+    const last_day = new Date(date.getFullYear(), date.getMonth() + months + 1, 0).getDate();
+    return new Date(date.getFullYear(), date.getMonth() + months, Math.min(date.getDate(), last_day), date.getHours(), date.getMinutes(), date.getSeconds(), date.getMilliseconds());
+}
+// ── Labels ───────────────────────────────────────────────────────────────────
+// A date without a time is overdue only once its day has passed.
+export function is_overdue(local_date, now = new Date()) {
+    const date = parse_local(local_date);
+    return has_time(local_date) ? date < now : date < start_of_day(now);
+}
+// Yesterday, Today or Tomorrow in the reader's language, else a short date with the year only when it is not this year, then the time if there is one.
+export function relative_day_label(local_date, now = new Date(), locale) {
+    const date = parse_local(local_date);
+    const day_offset = days_between(now, date);
+    const day_label = Math.abs(day_offset) <= 1
+        ? capitalised(new Intl.RelativeTimeFormat(locale, { numeric: "auto" }).format(day_offset, "day"), locale)
+        : date.toLocaleDateString(locale, {
+            month: "short",
+            day: "numeric",
+            year: date.getFullYear() === now.getFullYear() ? undefined : "numeric",
+        });
+    if (!has_time(local_date))
+        return day_label;
+    return `${day_label} ${date.toLocaleTimeString(locale, { hour: "numeric", minute: "2-digit" })}`;
+}
+function capitalised(text, locale) {
+    return text.charAt(0).toLocaleUpperCase(locale) + text.slice(1);
+}

package/dist/durations.d.ts

@@ -1,3 +1,11 @@
+declare const unit_names: readonly [readonly ["months", 2592000], readonly ["weeks", 604800], readonly ["days", 86400], readonly ["hours", 3600], readonly ["minutes", 60], readonly ["seconds", 1]];
+export type DurationUnit = (typeof unit_names)[number][0];
+export interface DurationWording {
+    separator?: string;
+    largest_unit?: DurationUnit;
+}
 export declare function parse_duration(value: unknown, key: string): number;
-export declare function format_duration(seconds: number): string;
+export declare function format_duration(seconds: number, wording?: DurationWording): string;
 export declare function format_age(seconds: number): string;
+export declare function format_clock(milliseconds: number | null | undefined, empty?: string): string;
+export {};

package/dist/durations.js

@@ -1,6 +1,7 @@
 // Reads durations such as "2h30m" from settings and writes them back in words, for the server and the agent alike.
 import parse from "parse-duration";
-const unit_names = [["weeks", 604800], ["days", 86400], ["hours", 3600], ["minutes", 60], ["seconds", 1]];
+// A month counts as 30 days.
+const unit_names = [["months", 2592000], ["weeks", 604800], ["days", 86400], ["hours", 3600], ["minutes", 60], ["seconds", 1]];
 const words = new Intl.DurationFormat("en", { style: "long" });
 // A duration in whole seconds; `key` names the setting in the error.
 export function parse_duration(value, key) {
@@ -14,13 +15,14 @@ export function parse_duration(value, key) {
     }
     return Math.floor(seconds);
 }
-// The two largest whole units, such as "1 day, 2 hours".
-export function format_duration(seconds) {
+// The two largest whole units, such as "1 day, 2 hours" or, with a space between, "1 week 2 days".
+export function format_duration(seconds, wording = {}) {
     if (seconds < 1)
         return "0 seconds";
+    const first_unit = unit_names.findIndex(([name]) => name === (wording.largest_unit ?? "months"));
     const parts = {};
     let remaining = Math.floor(seconds);
-    for (const [name, size] of unit_names) {
+    for (const [name, size] of unit_names.slice(first_unit)) {
         if (Object.keys(parts).length === 2)
             break;
         if (remaining < size)
@@ -28,8 +30,20 @@ export function format_duration(seconds) {
         parts[name] = Math.floor(remaining / size);
         remaining %= size;
     }
-    return words.format(parts);
+    if (wording.separator === undefined)
+        return words.format(parts);
+    return Object.entries(parts).map(([name, count]) => words.format({ [name]: count })).join(wording.separator);
 }
 export function format_age(seconds) {
     return seconds < 0 ? "never" : `${format_duration(seconds)} ago`;
 }
+// A playing time as a clock, such as "3:07", or "1:02:03" from an hour.
+export function format_clock(milliseconds, empty = "0:00") {
+    if (milliseconds === null || milliseconds === undefined || !Number.isFinite(milliseconds))
+        return empty;
+    const total = Math.max(0, Math.round(milliseconds / 1000));
+    const hours = Math.floor(total / 3600);
+    const minutes = Math.floor((total % 3600) / 60);
+    const seconds = String(total % 60).padStart(2, "0");
+    return hours > 0 ? `${hours}:${String(minutes).padStart(2, "0")}:${seconds}` : `${minutes}:${seconds}`;
+}

package/dist/electron/app.d.ts

@@ -0,0 +1,13 @@
+export interface AppLike {
+    requestSingleInstanceLock(): boolean;
+    quit(): void;
+    on(event: "second-instance", listener: (event: unknown, argv: string[]) => void): unknown;
+}
+export interface FocusableWindowLike {
+    isMinimized(): boolean;
+    restore(): void;
+    focus(): void;
+}
+export declare function hold_single_instance(app: AppLike, on_second_launch: (argv: string[]) => void): boolean;
+export declare function bring_to_front(window: FocusableWindowLike): void;
+export declare function first_argument<Value>(argv: readonly string[], parse: (argument: string) => Value | null): Value | null;

package/dist/electron/app.js

@@ -0,0 +1,27 @@
+// The app's place on the desktop: one copy running at a time, its window brought forward, and links handed over on the command line.
+// ── One copy ─────────────────────────────────────────────────────────────────
+// Keeps one copy running: a second launch hands its command line to the first and quits; returns false in the copy that must quit.
+export function hold_single_instance(app, on_second_launch) {
+    if (!app.requestSingleInstanceLock()) {
+        app.quit();
+        return false;
+    }
+    app.on("second-instance", (_event, argv) => on_second_launch(argv));
+    return true;
+}
+// Brings a window forward, restoring it first when minimised.
+export function bring_to_front(window) {
+    if (window.isMinimized())
+        window.restore();
+    window.focus();
+}
+// ── Command line ─────────────────────────────────────────────────────────────
+// The first command-line argument a parser accepts, such as a task link, or null.
+export function first_argument(argv, parse) {
+    for (const argument of argv) {
+        const value = parse(argument);
+        if (value !== null)
+            return value;
+    }
+    return null;
+}

package/dist/electron/bridge.d.ts

@@ -0,0 +1,32 @@
+export interface IpcMainLike {
+    handle(channel: string, listener: (event: unknown, ...args: unknown[]) => unknown): void;
+    removeHandler(channel: string): void;
+}
+export interface IpcRendererLike {
+    invoke(channel: string, ...args: unknown[]): Promise<unknown>;
+}
+export interface ContextBridgeLike {
+    exposeInMainWorld(api_key: string, api: unknown): void;
+}
+type AnyMethod = (...args: never[]) => unknown;
+export type Client<Methods extends Record<keyof Methods, AnyMethod>> = {
+    [Name in keyof Methods]: (...args: Parameters<Methods[Name]>) => Promise<Awaited<ReturnType<Methods[Name]>>>;
+};
+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 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;
+    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_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

@@ -0,0 +1,53 @@
+// One table of method names serves the Electron preload, the main process and a web page's calls to its server alike.
+export function define_bridge(api_name, method_names) {
+    const channel = (method) => `${api_name}:${method}`;
+    const is_method = (method) => method_names.includes(method);
+    function client_through(call) {
+        return Object.fromEntries(method_names.map((method) => [method, (...args) => call(method, args)]));
+    }
+    async function dispatch(implementation, method, args) {
+        if (!is_method(method))
+            throw new Error(`${api_name} has no method ${method}`);
+        const answer = implementation[method];
+        return answer.apply(implementation, 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)));
+        },
+        handle: (ipc_main, implementation) => {
+            for (const method of method_names) {
+                ipc_main.handle(channel(method), (_event, ...args) => dispatch(implementation, method, args));
+            }
+            return () => { for (const method of method_names)
+                ipc_main.removeHandler(channel(method)); };
+        },
+        web_rpc: client_through,
+    };
+}
+// ── 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) {
+    if (value === null || typeof value !== "object")
+        return value;
+    try {
+        structuredClone(value);
+        return value;
+    }
+    catch {
+        return JSON.parse(JSON.stringify(value));
+    }
+}
+// The same client with every argument made cloneable first, since Electron clones arguments before the preload sees them.
+export function with_cloneable_arguments(client) {
+    const wrapped = {};
+    for (const [name, method] of Object.entries(client)) {
+        wrapped[name] = (...args) => method(...args.map(to_cloneable));
+    }
+    return wrapped;
+}

package/dist/electron/events.d.ts

@@ -0,0 +1,21 @@
+import type { ContextBridgeLike } from "./bridge.ts";
+export interface IpcRendererEventsLike {
+    on(channel: string, listener: (event: unknown, message: unknown) => void): unknown;
+    removeListener(channel: string, listener: (event: unknown, message: unknown) => void): unknown;
+}
+export interface WindowLike {
+    webContents: {
+        send(channel: string, message: unknown): void;
+    };
+}
+export interface EventsClient<Events extends Record<string, unknown>> {
+    on<Name extends keyof Events & string>(name: Name, handler: (payload: Events[Name]) => void): () => void;
+}
+export interface EventsBridge<Events extends Record<string, unknown>> {
+    api_name: string;
+    channel: string;
+    ipc_client: (ipc_renderer: IpcRendererEventsLike) => EventsClient<Events>;
+    expose: (context_bridge: ContextBridgeLike, ipc_renderer: IpcRendererEventsLike) => void;
+    emit: <Name extends keyof Events & string>(windows: Iterable<WindowLike>, name: Name, payload: Events[Name]) => void;
+}
+export declare function define_events<Events extends Record<string, unknown>>(api_name: string): EventsBridge<Events>;

package/dist/electron/events.js

@@ -0,0 +1,25 @@
+// Messages the main process pushes to its pages, such as progress, on one channel and subscribed to by name.
+export function define_events(api_name) {
+    const channel = `${api_name}:event`;
+    const ipc_client = (ipc_renderer) => ({
+        on: (name, handler) => {
+            const listener = (_event, message) => {
+                const { name: sent_name, payload } = message;
+                if (sent_name === name)
+                    handler(payload);
+            };
+            ipc_renderer.on(channel, listener);
+            return () => void ipc_renderer.removeListener(channel, listener);
+        },
+    });
+    return {
+        api_name,
+        channel,
+        ipc_client,
+        expose: (context_bridge, ipc_renderer) => context_bridge.exposeInMainWorld(api_name, ipc_client(ipc_renderer)),
+        emit: (windows, name, payload) => {
+            for (const window of windows)
+                window.webContents.send(channel, { name, payload });
+        },
+    };
+}

package/dist/electron/fetch.d.ts

@@ -0,0 +1,25 @@
+export type HeaderList = [string, string][];
+export interface FetchRequest {
+    url: string;
+    method: string;
+    headers: HeaderList;
+    body?: Uint8Array<ArrayBuffer>;
+}
+export interface FetchAnswer {
+    status: number;
+    status_text: string;
+    headers: HeaderList;
+    body: Uint8Array<ArrayBuffer> | null;
+}
+export type FetchMethod = (request: FetchRequest) => FetchAnswer;
+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 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>;

package/dist/electron/fetch.js

@@ -0,0 +1,67 @@
+// Fetching from Electron's main process for a page whose own requests the browser's cross-origin rules would block.
+const NULL_BODY_STATUSES = new Set([101, 204, 205, 304]);
+export function is_allowed_url(url, policy) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol !== "https:" && !(policy.allow_http && parsed.protocol === "http:"))
+        return false;
+    return policy.hosts.some((host) => host.startsWith("*.") ? parsed.hostname.endsWith(host.slice(1)) : parsed.host === host || parsed.hostname === host);
+}
+// The body arrives already unpacked, so the headers describing the packed body are dropped.
+const DROPPED_ANSWER_HEADERS = new Set(["content-encoding", "content-length"]);
+// The main process's half: sends the page's request with Node's fetch, refusing any URL outside the policy.
+export function create_main_fetch(policy, send = fetch) {
+    return async (request) => {
+        if (!is_allowed_url(request.url, policy))
+            throw new Error(`fetching ${request.url} is not allowed`);
+        const response = await send(request.url, { method: request.method, headers: request.headers, body: request.body });
+        const headers = [];
+        response.headers.forEach((value, name) => {
+            if (!DROPPED_ANSWER_HEADERS.has(name))
+                headers.push([name, value]);
+        });
+        const has_body = !NULL_BODY_STATUSES.has(response.status) && request.method !== "HEAD";
+        return {
+            status: response.status,
+            status_text: response.statusText,
+            headers,
+            body: has_body ? new Uint8Array(await response.arrayBuffer()) : null,
+        };
+    };
+}
+function abort_error() {
+    return new DOMException("The request was aborted", "AbortError");
+}
+// Rejects once the signal aborts, though the main process still finishes the request.
+function until_aborted(promise, signal) {
+    if (!signal)
+        return promise;
+    if (signal.aborted)
+        return Promise.reject(abort_error());
+    return new Promise((resolve, reject) => {
+        signal.addEventListener("abort", () => reject(abort_error()), { once: true });
+        promise.then(resolve, reject);
+    });
+}
+export function to_response(answer) {
+    const body = NULL_BODY_STATUSES.has(answer.status) ? null : answer.body;
+    return new Response(body, { status: answer.status, statusText: answer.status_text, headers: answer.headers });
+}
+// The page's half: a fetch that sends each request through the bridge method, for libraries that take a fetch.
+export function create_page_fetch(send, options = {}) {
+    return async (input, init) => {
+        const request = new Request(input, init);
+        // A plain Headers keeps names a Request would drop, such as Origin and Referer.
+        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());
+        const answer = await until_aborted(send({ url: request.url, method: request.method, headers: [...headers.entries()], body }), init?.signal ?? request.signal);
+        return to_response(answer);
+    };
+}