@x-tech-laboratories/x-libs 0.6.0 → 0.8.0

package/README.md

@@ -6,10 +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` in months down to seconds, `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. |
-| `electron/bridge`                        | `define_bridge`: one method table for the preload, the main process, and a web page's calls to its server. |
-| `electron/window`                        | `create_window`: links open in the browser, the background follows the system theme, and the size and place are remembered. |
+| `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. |
@@ -20,16 +25,24 @@ 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, kept in this browser or the app's settings. |
+| `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, and where a dropped or keyed row lands. |
-| `web/react/shell`                        | `Shell`: top bar, section links or the app's own sidebar, resizable, theme button, toasts, dialogs and menus; `use_route`. |
-| `web/react/layout`, `badges`, `states`   | Panels, facts, tiles, cards, tabs, crumbs, steppers, settings 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. |
-| `web/react/controls`, `table`            | Segmented choices, button groups, switches, search boxes, selects; `DataTable` on TanStack Table, sorting by several columns, with columns to move, resize, hide and filter, tree rows, and cards on phones; a pager. |
+| `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/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`   | 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, 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. |
+| `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 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, 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/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, and reorder by dragging or with Alt and the arrow keys. |
-| `web/react/toasts`, `dialog`, `menus`, `split` | Toasts with a link or Undo that say how they closed; modal, confirm and text dialogs openable from anywhere; context menus and popovers worked by keyboard, openable from anywhere; resize handles and splits. |
+| `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. |
 
 ```ts
 import { AgentHub } from "@x-tech-laboratories/x-libs/server/agents/hub";
@@ -96,6 +109,22 @@ create_window(BrowserWindow, {
 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
 
 The server and every agent are given the same `AgentApp`: the app's name, its protocol version, 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/durations.d.ts

@@ -7,4 +7,5 @@ export interface DurationWording {
 export declare function parse_duration(value: unknown, key: string): number;
 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

@@ -37,3 +37,13 @@ export function format_duration(seconds, wording = {}) {
 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

@@ -13,7 +13,7 @@ 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]>) => ReturnType<Methods[Name]> | Promise<Awaited<ReturnType<Methods[Name]>>>;
+    [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>> {
@@ -27,4 +27,6 @@ export interface Bridge<Methods extends Record<keyof Methods, AnyMethod>> {
     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

@@ -30,3 +30,24 @@ export function define_bridge(api_name, method_names) {
         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);
+    };
+}

package/dist/electron/window.d.ts

@@ -15,13 +15,18 @@ export interface BrowserWindowOptionsLike {
     minHeight?: number;
     show: boolean;
     backgroundColor: string;
+    titleBarStyle?: "default" | "hidden" | "hiddenInset";
     webPreferences: {
         preload?: string;
         sandbox: boolean;
         contextIsolation: boolean;
         nodeIntegration: boolean;
+        backgroundThrottling: boolean;
     };
 }
+export interface NavigationEventLike {
+    preventDefault(): void;
+}
 export interface BrowserWindowLike {
     webContents: {
         setWindowOpenHandler(handler: (details: {
@@ -29,6 +34,7 @@ export interface BrowserWindowLike {
         }) => {
             action: "deny";
         }): void;
+        on(event: "will-navigate", listener: (event: NavigationEventLike, url: string) => void): unknown;
     };
     on(event: string, listener: () => void): unknown;
     once(event: string, listener: () => void): unknown;
@@ -74,6 +80,9 @@ export interface WindowOptions {
         dark: string;
     };
     sandbox?: boolean;
+    background_throttling?: boolean;
+    title_bar_style?: "default" | "hidden" | "hiddenInset";
+    before_write?: (path: string) => void;
     save_delay_ms?: number;
 }
 export interface WindowState {
@@ -82,4 +91,6 @@ export interface WindowState {
 }
 export declare function read_window_state(state_file: string): WindowState | null;
 export declare function write_window_state(state_file: string, state: WindowState): void;
+export declare function is_external_link(url: string): boolean;
+export declare function is_app_page(url: string, options: Pick<WindowOptions, "dev_url" | "file">): boolean;
 export declare function create_window<Window extends BrowserWindowLike>(BrowserWindow: new (options: BrowserWindowOptionsLike) => Window, options: WindowOptions): Window;

package/dist/electron/window.js

@@ -1,6 +1,7 @@
-// An Electron app's main window: links open in the browser, the background follows the system theme, and its size and place are remembered.
+// An Electron app's main window: links and pages of other sites open in the browser, the background follows the system theme, and its size and place are remembered.
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
+import { pathToFileURL } from "node:url";
 const DEFAULT_BACKGROUND = { light: "#f5f6f8", dark: "#0f1115" };
 const DEFAULT_SAVE_DELAY_MS = 500;
 // ── State file ───────────────────────────────────────────────────────────────
@@ -28,6 +29,34 @@ export function write_window_state(state_file, state) {
 function overlaps(first, second) {
     return first.x < second.x + second.width && second.x < first.x + first.width && first.y < second.y + second.height && second.y < first.y + first.height;
 }
+// ── Links ────────────────────────────────────────────────────────────────────
+const EXTERNAL_SCHEMES = new Set(["http:", "https:", "mailto:"]);
+// Only web and mail links reach the browser, never a file or another app's scheme.
+export function is_external_link(url) {
+    try {
+        return EXTERNAL_SCHEMES.has(new URL(url).protocol);
+    }
+    catch {
+        return false;
+    }
+}
+// True for the app's own pages: the dev server's origin, or files beside the built page.
+export function is_app_page(url, options) {
+    try {
+        const target = new URL(url);
+        if (options.dev_url)
+            return target.origin === new URL(options.dev_url).origin;
+        const page_folder = new URL(".", pathToFileURL(options.file)).href;
+        return target.protocol === "file:" && target.href.startsWith(page_folder);
+    }
+    catch {
+        return false;
+    }
+}
+function open_outside(shell, url) {
+    if (is_external_link(url))
+        void shell.openExternal(url);
+}
 // ── Window ───────────────────────────────────────────────────────────────────
 export function create_window(BrowserWindow, options) {
     const background = options.background ?? DEFAULT_BACKGROUND;
@@ -45,7 +74,8 @@ export function create_window(BrowserWindow, options) {
         minHeight: options.min_size?.height,
         show: false,
         backgroundColor: background_color(),
-        webPreferences: { preload: options.preload, sandbox: options.sandbox ?? false, contextIsolation: true, nodeIntegration: false },
+        ...(options.title_bar_style ? { titleBarStyle: options.title_bar_style } : {}),
+        webPreferences: { preload: options.preload, sandbox: options.sandbox ?? false, contextIsolation: true, nodeIntegration: false, backgroundThrottling: options.background_throttling ?? true },
     });
     window.once("ready-to-show", () => {
         if (saved?.is_maximized)
@@ -53,14 +83,21 @@ export function create_window(BrowserWindow, options) {
         window.show();
     });
     window.webContents.setWindowOpenHandler(({ url }) => {
-        void options.shell.openExternal(url);
+        open_outside(options.shell, url);
         return { action: "deny" };
     });
+    // A link that would load another site in the window opens in the browser instead.
+    window.webContents.on("will-navigate", (event, url) => {
+        if (is_app_page(url, options))
+            return;
+        event.preventDefault();
+        open_outside(options.shell, url);
+    });
     const follow_theme = () => window.setBackgroundColor(background_color());
     options.native_theme.on("updated", follow_theme);
     window.on("closed", () => options.native_theme.removeListener("updated", follow_theme));
     if (options.state_file)
-        remember_state(window, options.state_file, options.save_delay_ms ?? DEFAULT_SAVE_DELAY_MS);
+        remember_state(window, options.state_file, options.save_delay_ms ?? DEFAULT_SAVE_DELAY_MS, options.before_write);
     if (options.dev_url)
         void window.loadURL(options.dev_url);
     else
@@ -68,12 +105,18 @@ export function create_window(BrowserWindow, options) {
     return window;
 }
 // Saves a moment after the last move or resize, and at once when the window closes.
-function remember_state(window, state_file, save_delay_ms) {
+function remember_state(window, state_file, save_delay_ms, before_write) {
     let timer;
     const save_now = () => {
         clearTimeout(timer);
         timer = undefined;
-        write_window_state(state_file, { bounds: window.getNormalBounds(), is_maximized: window.isMaximized() });
+        try {
+            before_write?.(state_file);
+            write_window_state(state_file, { bounds: window.getNormalBounds(), is_maximized: window.isMaximized() });
+        }
+        catch {
+            // A refused or failed save keeps the last one, and the window carries on.
+        }
     };
     const save_soon = () => {
         clearTimeout(timer);

package/dist/log.d.ts

@@ -0,0 +1,30 @@
+export type Level = "critical" | "error" | "warn" | "info" | "debug";
+export declare const levels: Level[];
+export declare const default_level: Level;
+export interface LevelSpec {
+    default: Level;
+    scopes: Record<string, Level>;
+}
+export declare function parse_level_spec(spec: string | undefined, fallback?: Level): LevelSpec;
+export declare function level_for(spec: LevelSpec, scope: string): Level;
+export declare function is_enabled(spec: LevelSpec, scope: string, level: Level): boolean;
+export interface LogRecord {
+    at: number;
+    level: Level;
+    scope: string;
+    message: string;
+    data?: unknown;
+}
+export type LogSink = (record: LogRecord) => void;
+export declare function format_record(record: LogRecord): string;
+export interface Logger {
+    critical(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    debug(message: string, data?: unknown): void;
+    enabled(level: Level): boolean;
+    child(scope: string): Logger;
+}
+export type SpecSource = LevelSpec | (() => LevelSpec);
+export declare function create_logger(scope: string, spec: SpecSource, sink: LogSink): Logger;