@x-tech-laboratories/x-libs 0.14.1 → 0.14.2

package/dist/server/events.js

@@ -0,0 +1,68 @@
+// Server-sent events: each open page keeps one stream and is told through it when the data changed, so it fetches at
+// once instead of polling. Every stream gets a client id, so the page that made a change is not told about its own.
+// ── Imports ──────────────────────────────────────────────────────────────────
+import { randomUUID } from "node:crypto";
+// ── Settings ─────────────────────────────────────────────────────────────────
+export const default_client_id_header = "x-client-id";
+// ── Stream ───────────────────────────────────────────────────────────────────
+export class EventStream {
+    heartbeat_ms;
+    retry_ms;
+    hello_event;
+    changed_event;
+    client_id_header;
+    streams = new Map();
+    constructor(options = {}) {
+        this.heartbeat_ms = options.heartbeat_ms ?? 25_000;
+        this.retry_ms = options.retry_ms ?? 3000;
+        this.hello_event = options.hello_event === undefined ? "hello" : options.hello_event;
+        this.changed_event = options.changed_event ?? "changed";
+        this.client_id_header = options.client_id_header ?? default_client_id_header;
+    }
+    get client_count() {
+        return this.streams.size;
+    }
+    // The client id a request carries, or "" for one that sent none.
+    client_id_of(request) {
+        return String(request.headers[this.client_id_header] ?? "");
+    }
+    send(data, options = {}) {
+        const lines = data.split("\n").map((line) => `data: ${line}`).join("\n");
+        const text = `${options.event === undefined ? "" : `event: ${options.event}\n`}${lines}\n\n`;
+        for (const { client, response } of this.streams.values()) {
+            if (client.id === options.except_client_id)
+                continue;
+            if (options.to !== undefined && !options.to(client))
+                continue;
+            response.write(text);
+        }
+    }
+    // The page that made a change already shows it, so only the others are told.
+    announce_change(except_client_id = "") {
+        this.send("", { event: this.changed_event, except_client_id });
+    }
+    // Serves the stream on the path, and ends every stream when the app closes, since one never ends by itself.
+    register(app, path = "/events") {
+        app.get(path, (request, reply) => {
+            reply.hijack();
+            const response = reply.raw;
+            const id = randomUUID();
+            response.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-store", connection: "keep-alive", "x-accel-buffering": "no" });
+            response.write(`retry: ${this.retry_ms}\n\n`);
+            if (this.hello_event !== null)
+                response.write(`event: ${this.hello_event}\ndata: ${id}\n\n`);
+            this.streams.set(id, { client: { id, request }, response });
+            const heartbeat = setInterval(() => response.write(": still here\n\n"), this.heartbeat_ms);
+            request.raw.on("close", () => {
+                clearInterval(heartbeat);
+                this.streams.delete(id);
+            });
+        });
+        app.addHook("onClose", async () => this.close());
+    }
+    close() {
+        for (const { response } of this.streams.values())
+            response.end();
+        this.streams.clear();
+    }
+}

package/dist/server/hash_password.d.ts

@@ -0,0 +1 @@
+export declare function hash_password_command(variable: string, argv?: string[]): Promise<void>;

package/dist/server/hash_password.js

@@ -0,0 +1,46 @@
+// The `hash-password` command: adds a user to the accounts file, or changes their password. Asks for the password at a
+// terminal, or reads it from stdin, so it never lands in argv or shell history.
+// ── Imports ──────────────────────────────────────────────────────────────────
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { text } from "node:stream/consumers";
+import password from "@inquirer/password";
+import { account_name_pattern, hash_password, set_account } from "./passwords.js";
+// ── Asking ───────────────────────────────────────────────────────────────────
+// Asks twice at a terminal without echoing, on stderr so stdout stays clean; reads one line from a pipe.
+async function read_password() {
+    if (!process.stdin.isTTY)
+        return (await text(process.stdin)).replace(/\r?\n$/, "");
+    const ask = (message) => password({ message, mask: false }, { output: process.stderr });
+    try {
+        const first = await ask("Password:");
+        if (first !== (await ask("Again:"))) {
+            console.error("The passwords differ.");
+            process.exit(1);
+        }
+        return first;
+    }
+    catch (error) {
+        // Ctrl-C at the prompt ends the command as a shell would.
+        if (error.name === "ExitPromptError")
+            process.exit(130);
+        throw error;
+    }
+}
+// ── Command ──────────────────────────────────────────────────────────────────
+// Runs the command with `<name> [file]` from argv; `variable` is the environment variable the app reads the file from.
+export async function hash_password_command(variable, argv = process.argv.slice(2)) {
+    const name = argv[0] ?? "";
+    const file_path = argv[1] ?? "password.hash";
+    if (!account_name_pattern.test(name)) {
+        console.error("Usage: npm run hash-password -- <name> [file], the name of lowercase letters, digits, '.', '_' and '-'.");
+        process.exit(1);
+    }
+    const password = await read_password();
+    if (!password) {
+        console.error("The password is empty.");
+        process.exit(1);
+    }
+    const existing = existsSync(file_path) ? readFileSync(file_path, "utf8") : "";
+    writeFileSync(file_path, set_account(existing, name, hash_password(password)), { mode: 0o600 });
+    console.error(`Set ${name}'s password in ${file_path}; point ${variable} at it.`);
+}

package/dist/server/login_page.d.ts

@@ -0,0 +1,8 @@
+export interface LoginPageOptions {
+    title: string;
+    has_failed?: boolean;
+    action?: string;
+    prompt?: string;
+    failure_text?: string;
+}
+export declare function render_login_page(options: LoginPageOptions): string;

package/dist/server/login_page.js

@@ -0,0 +1,79 @@
+// The page a browser signs in on with the server's access token: a page of its own, so signing in needs nothing from
+// the app's built files, with colours that follow the light and dark themes.
+function escape_html(text) {
+    return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
+}
+export function render_login_page(options) {
+    const title = escape_html(options.title);
+    const action = escape_html(options.action ?? "login");
+    const prompt = escape_html(options.prompt ?? "Enter the access token this server was set up with.");
+    const failure_text = escape_html(options.failure_text ?? "That token is not right.");
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${title}</title>
+    <style>
+      :root {
+        color-scheme: light dark;
+        --surface-root: #f1f5f9;
+        --surface-default: #ffffff;
+        --text-heading: #0f172a;
+        --text-secondary: #475569;
+        --border-control: #8792a3;
+        --accent: #2563eb;
+        --text-on-fill: #fff;
+        --status-danger: #dc2626;
+      }
+      @media (prefers-color-scheme: dark) {
+        :root {
+          --surface-root: #060b14;
+          --surface-default: #16213a;
+          --text-heading: #f8fafc;
+          --text-secondary: #cbd5e1;
+          --border-control: #64748b;
+          --accent: #60a5fa;
+          --text-on-fill: #0b1220;
+          --status-danger: #f87171;
+        }
+      }
+      body {
+        margin: 0;
+        min-height: 100vh;
+        display: grid;
+        place-items: center;
+        padding: 0 16px;
+        background: var(--surface-root);
+        color: var(--text-heading);
+        font: 15px system-ui, sans-serif;
+      }
+      form {
+        width: min(340px, 100%);
+        display: grid;
+        gap: 12px;
+        padding: 24px;
+        border-radius: 12px;
+        background: var(--surface-default);
+        box-shadow: 0 1px 3px rgba(15, 23, 42, 0.12);
+      }
+      h1 { margin: 0; font-size: 20px; }
+      p { margin: 0; color: var(--text-secondary); }
+      .error { color: var(--status-danger); }
+      input, button { font: inherit; padding: 8px 10px; border-radius: 8px; }
+      input { border: 1px solid var(--border-control); background: transparent; color: inherit; }
+      button { border: 0; background: var(--accent); color: var(--text-on-fill); cursor: pointer; }
+    </style>
+  </head>
+  <body>
+    <form method="post" action="${action}">
+      <h1>${title}</h1>
+      <p>${prompt}</p>
+      ${options.has_failed ? `<p class="error">${failure_text}</p>` : ""}
+      <input type="password" name="token" autocomplete="current-password" aria-label="Access token" autofocus required />
+      <button type="submit">Sign in</button>
+    </form>
+  </body>
+</html>
+`;
+}

package/dist/server/passwords.d.ts

@@ -0,0 +1,8 @@
+export type Accounts = Map<string, string>;
+export declare const account_name_pattern: RegExp;
+export declare const default_account_name = "admin";
+export declare function hash_password(password: string): string;
+export declare function verify_password(password: string, stored: string): boolean;
+export declare function parse_accounts(text: string, source?: string): Accounts;
+export declare function load_accounts(variable: string, file_path?: string | undefined): Accounts;
+export declare function set_account(text: string, name: string, stored: string): string;

package/dist/server/passwords.js

@@ -0,0 +1,59 @@
+// Password hashes: scrypt with a random salt, and the accounts file an app logs in with, one `name:hash` line per user.
+import { randomBytes, scryptSync, timingSafeEqual } from "node:crypto";
+import { readFileSync } from "node:fs";
+const key_length = 64;
+export const account_name_pattern = /^[a-z0-9][a-z0-9_.-]{0,63}$/;
+// A line holding only a hash logs in as this user.
+export const default_account_name = "admin";
+// Stored as `scrypt$<salt hex>$<hash hex>`.
+export function hash_password(password) {
+    const salt = randomBytes(16);
+    return `scrypt$${salt.toString("hex")}$${scryptSync(password, salt, key_length).toString("hex")}`;
+}
+export function verify_password(password, stored) {
+    const [scheme, salt_hex, hash_hex] = stored.trim().split("$");
+    if (scheme !== "scrypt" || !salt_hex || !hash_hex)
+        return false;
+    const expected = Buffer.from(hash_hex, "hex");
+    const actual = scryptSync(password, Buffer.from(salt_hex, "hex"), expected.length);
+    return timingSafeEqual(actual, expected);
+}
+// Reads `name:hash` lines, skipping blank lines and `#` comments.
+export function parse_accounts(text, source = "the accounts file") {
+    const accounts = new Map();
+    for (const [index, raw_line] of text.split("\n").entries()) {
+        const line = raw_line.trim();
+        if (line === "" || line.startsWith("#"))
+            continue;
+        const separator = line.indexOf(":");
+        const name = separator === -1 ? default_account_name : line.slice(0, separator);
+        const stored = separator === -1 ? line : line.slice(separator + 1);
+        const where = `${source} line ${index + 1}`;
+        if (!account_name_pattern.test(name))
+            throw new Error(`${where}: '${name}' is not a user name of lowercase letters, digits, '.', '_' and '-'.`);
+        if (!stored.startsWith("scrypt$"))
+            throw new Error(`${where} does not hold a hash from \`npm run hash-password\`.`);
+        if (accounts.has(name))
+            throw new Error(`${where} names '${name}' a second time.`);
+        accounts.set(name, stored);
+    }
+    return accounts;
+}
+// The accounts in the file the environment variable names, such as X_NIX_PASSWORD_HASH_FILE.
+export function load_accounts(variable, file_path = process.env[variable]) {
+    if (!file_path)
+        throw new Error(`${variable} is not set; create one with \`npm run hash-password -- <name> <file>\`.`);
+    const accounts = parse_accounts(readFileSync(file_path, "utf8"), file_path);
+    if (accounts.size === 0)
+        throw new Error(`${file_path} holds no users; add one with \`npm run hash-password -- <name> ${file_path}\`.`);
+    return accounts;
+}
+// Sets one user's line in the accounts file's text, replacing their old one, whether it names them or holds only a hash.
+export function set_account(text, name, stored) {
+    const names_user = (line) => {
+        const trimmed = line.trim();
+        return trimmed.startsWith(`${name}:`) || (name === default_account_name && trimmed.startsWith("scrypt$"));
+    };
+    const kept = text.split("\n").filter((line) => line.trim() !== "" && !names_user(line));
+    return [...kept, `${name}:${stored}`].join("\n") + "\n";
+}

package/dist/server/replies.d.ts

@@ -0,0 +1,12 @@
+import type { FastifyInstance, FastifyReply } from "fastify";
+export interface ErrorRepliesOptions {
+    format?: "text" | "json";
+    not_found_text?: string;
+    not_found?: boolean;
+    log_failure?: (message: string, error: Error) => void;
+}
+export declare const BAD_JSON: unique symbol;
+export declare function send_text(reply: FastifyReply, status: number, text: string): FastifyReply;
+export declare function send_error(reply: FastifyReply, status: number, text: string, format?: "text" | "json"): FastifyReply;
+export declare function register_error_replies(app: FastifyInstance, options?: ErrorRepliesOptions): void;
+export declare function register_lenient_json_body(app: FastifyInstance): void;

package/dist/server/replies.js

@@ -0,0 +1,41 @@
+// How a server answers what it could not do: every refusal in plain words, or as JSON { error }, and a JSON body
+// parser that hands the route an empty body as no arguments and a bad one as a marker, so the route answers in its
+// own words instead of Fastify's.
+// What the JSON parser hands a route when the body was not JSON.
+export const BAD_JSON = Symbol("bad json");
+// ── Replies ──────────────────────────────────────────────────────────────────
+export function send_text(reply, status, text) {
+    return reply.code(status).type("text/plain; charset=utf-8").send(text);
+}
+export function send_error(reply, status, text, format = "text") {
+    if (format === "json")
+        return reply.code(status).send({ error: text });
+    return send_text(reply, status, text);
+}
+// ── Registration ─────────────────────────────────────────────────────────────
+// Errors answer with their own status and message, and unknown paths with 404, all in the one format.
+export function register_error_replies(app, options = {}) {
+    const { format = "text", not_found_text = "not found", not_found = true } = options;
+    const log_failure = options.log_failure ?? ((message, error) => console.error(message, error));
+    app.setErrorHandler((error, request, reply) => {
+        const status = error.statusCode ?? 500;
+        if (status >= 500)
+            log_failure(`${request.method} ${request.url} failed:`, error);
+        return send_error(reply, status, error.message, format);
+    });
+    if (not_found)
+        app.setNotFoundHandler(async (_request, reply) => send_error(reply, 404, not_found_text, format));
+}
+// An empty body parses as undefined and a body that is not JSON as BAD_JSON, for the route to refuse in its own words.
+export function register_lenient_json_body(app) {
+    app.addContentTypeParser("application/json", { parseAs: "string" }, (_request, body, done) => {
+        if (body === "")
+            return done(null, undefined);
+        try {
+            done(null, JSON.parse(body));
+        }
+        catch {
+            done(null, BAD_JSON);
+        }
+    });
+}

package/dist/server/sign_in.d.ts

@@ -0,0 +1,27 @@
+import type { FastifyInstance, FastifyRequest } from "fastify";
+export interface SignInGuardOptions {
+    is_signed_in: (request: FastifyRequest) => boolean;
+    api_prefix?: string;
+    open_paths?: Iterable<string>;
+    login_path?: string | null;
+    refusal?: "text" | "json";
+    refusal_text?: string;
+}
+export interface TokenSignInOptions extends Omit<SignInGuardOptions, "is_signed_in"> {
+    secret: string;
+    title: string;
+    cookie_name?: string;
+    session_seconds?: number;
+    failed_login_delay_ms?: number;
+    login_path?: string;
+    logout_path?: string;
+    home_path?: string;
+    render_login_page?: (has_failed: boolean) => string;
+}
+export declare function same_secret(first: string, second: string): boolean;
+export declare function session_value(secret: string, cookie_name: string): string;
+export declare function cookie_name_for(title: string): string;
+export declare function is_token_signed_in(request: FastifyRequest, secret: string, cookie_name: string): boolean;
+export declare function path_of(request: FastifyRequest): string;
+export declare function register_sign_in_guard(app: FastifyInstance, options: SignInGuardOptions): void;
+export declare function register_token_sign_in(app: FastifyInstance, options: TokenSignInOptions): Promise<void>;

package/dist/server/sign_in.js

@@ -0,0 +1,95 @@
+// Signing in to a server that has one secret: a browser posts it on the login page and keeps a cookie derived from it,
+// other programs send it as a bearer header, and the guard turns away every request that carries neither. The guard
+// alone also serves servers with their own sessions, which hand it the check.
+// ── Imports ──────────────────────────────────────────────────────────────────
+import { createHmac, timingSafeEqual } from "node:crypto";
+import fastify_cookie from "@fastify/cookie";
+import fastify_formbody from "@fastify/formbody";
+import { render_login_page } from "./login_page.js";
+// ── Settings ─────────────────────────────────────────────────────────────────
+const default_session_seconds = 90 * 24 * 60 * 60;
+const default_failed_login_delay_ms = 1000;
+// ── Secrets ──────────────────────────────────────────────────────────────────
+export function same_secret(first, second) {
+    const first_bytes = Buffer.from(first);
+    const second_bytes = Buffer.from(second);
+    return first_bytes.length === second_bytes.length && timingSafeEqual(first_bytes, second_bytes);
+}
+// The cookie holds a value derived from the secret, so changing the secret signs every browser out.
+export function session_value(secret, cookie_name) {
+    return createHmac("sha256", secret).update(cookie_name).digest("hex");
+}
+export function cookie_name_for(title) {
+    return `${title.toLowerCase().replaceAll(/[^a-z0-9]+/g, "_").replaceAll(/^_|_$/g, "")}_session`;
+}
+// A browser signs in with its cookie; other programs can send the secret as a bearer header instead.
+export function is_token_signed_in(request, secret, cookie_name) {
+    if (secret === "")
+        return true;
+    const bearer = /^Bearer (.+)$/.exec(request.headers.authorization ?? "")?.[1];
+    if (bearer !== undefined)
+        return same_secret(bearer, secret);
+    return same_secret(request.cookies[cookie_name] ?? "", session_value(secret, cookie_name));
+}
+// A proxy that ends TLS says so in a header, and the cookie is then kept to secure connections.
+function is_secure(request) {
+    return request.headers["x-forwarded-proto"] === "https" || "encrypted" in request.raw.socket;
+}
+function set_session_cookie(request, reply, cookie_name, value, max_age_seconds) {
+    void reply.setCookie(cookie_name, value, { path: "/", httpOnly: true, sameSite: "strict", maxAge: max_age_seconds, secure: is_secure(request) });
+}
+// ── Guard ────────────────────────────────────────────────────────────────────
+export function path_of(request) {
+    return request.url.split("?")[0] ?? "";
+}
+// Turns away every request that is not signed in: a page load goes to the login page, while a call gets a refusal it can act on.
+export function register_sign_in_guard(app, options) {
+    const { is_signed_in, api_prefix = "/api/", login_path = "/login", refusal = "text", refusal_text = "sign in first" } = options;
+    const open_paths = new Set(options.open_paths ?? []);
+    app.addHook("onRequest", async (request, reply) => {
+        const path = path_of(request);
+        // Preflight checks carry no credentials, and the sign-in routes are open by nature.
+        if (request.method === "OPTIONS" || open_paths.has(path))
+            return;
+        if (is_signed_in(request))
+            return;
+        if (!path.startsWith(api_prefix)) {
+            if (login_path === null)
+                return;
+            return reply.redirect(login_path, 303);
+        }
+        void reply.code(401).header("cache-control", "no-store");
+        if (refusal === "json")
+            return reply.send({ error: refusal_text });
+        return reply.type("text/plain; charset=utf-8").send(refusal_text);
+    });
+}
+// ── Token sign-in ────────────────────────────────────────────────────────────
+// Signs browsers in and out with the server's one secret, and guards everything else.
+export async function register_token_sign_in(app, options) {
+    const { secret, title, login_path = "/login", logout_path = "/logout", home_path = "/", session_seconds = default_session_seconds, failed_login_delay_ms = default_failed_login_delay_ms, } = options;
+    const cookie_name = options.cookie_name ?? cookie_name_for(title);
+    const render = options.render_login_page ?? ((has_failed) => render_login_page({ title, has_failed, action: login_path }));
+    await app.register(fastify_cookie);
+    await app.register(fastify_formbody);
+    register_sign_in_guard(app, {
+        ...options,
+        login_path,
+        open_paths: [login_path, logout_path, ...(options.open_paths ?? [])],
+        is_signed_in: (request) => is_token_signed_in(request, secret, cookie_name),
+    });
+    app.get(login_path, async (_request, reply) => reply.type("text/html; charset=utf-8").send(render(false)));
+    app.post(login_path, async (request, reply) => {
+        const token = request.body?.token ?? "";
+        if (secret === "" || same_secret(token, secret)) {
+            set_session_cookie(request, reply, cookie_name, session_value(secret, cookie_name), session_seconds);
+            return reply.redirect(home_path, 303);
+        }
+        await new Promise((wait) => setTimeout(wait, failed_login_delay_ms));
+        return reply.code(401).type("text/html; charset=utf-8").send(render(true));
+    });
+    app.get(logout_path, async (request, reply) => {
+        set_session_cookie(request, reply, cookie_name, "", 0);
+        return reply.redirect(login_path, 303);
+    });
+}

package/dist/server/web_folder.d.ts

@@ -0,0 +1,11 @@
+import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+export interface WebFolderOptions {
+    folder: string;
+    immutable_path?: string;
+    page_cache_control?: string;
+    when_missing?: "warn" | "throw" | "skip";
+    page_fallback?: boolean;
+    api_prefix?: string;
+    api_not_found?: (request: FastifyRequest, reply: FastifyReply) => unknown;
+}
+export declare function register_web_folder(app: FastifyInstance, options: WebFolderOptions): Promise<boolean>;

package/dist/server/web_folder.js

@@ -0,0 +1,40 @@
+// The built web page served from a folder, tuned for files from the Nix store: those are all dated 1970 and a rebuilt
+// page keeps its size, so the size-and-date ETag is off and the page is fetched whole each time, while the bundles
+// carry a content hash in their name and are kept for a year.
+// ── Imports ──────────────────────────────────────────────────────────────────
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import fastify_static from "@fastify/static";
+// ── Registration ─────────────────────────────────────────────────────────────
+// Whether the folder was found and is being served.
+export async function register_web_folder(app, options) {
+    const { immutable_path = "/assets/", page_cache_control = "no-cache", when_missing = "warn", api_prefix = "/api/" } = options;
+    const folder = resolve(options.folder);
+    if (!existsSync(folder)) {
+        if (when_missing === "throw")
+            throw new Error(`The web page is not built; nothing is at ${folder}`);
+        if (when_missing === "warn")
+            console.warn(`no web page found at ${folder}; only the API is served`);
+        return false;
+    }
+    await app.register(fastify_static, {
+        root: folder,
+        etag: false,
+        lastModified: false,
+        cacheControl: false,
+        setHeaders: (reply, path) => {
+            const immutable = path.includes(immutable_path);
+            void reply.header("cache-control", immutable ? "public, max-age=31536000, immutable" : page_cache_control);
+        },
+    });
+    if (options.page_fallback) {
+        const api_not_found = options.api_not_found ?? ((_request, reply) => reply.code(404).type("text/plain; charset=utf-8").send("not found"));
+        app.setNotFoundHandler((request, reply) => {
+            const path = request.url.split("?")[0] ?? "";
+            if (path.startsWith(api_prefix) || (request.method !== "GET" && request.method !== "HEAD"))
+                return api_not_found(request, reply);
+            return reply.header("cache-control", page_cache_control).sendFile("index.html");
+        });
+    }
+    return true;
+}

package/dist/web/dom.d.ts

@@ -0,0 +1,7 @@
+export type ClassValue = string | false | null | undefined;
+export declare function cx(...names: ClassValue[]): string;
+export type Child = Node | string | number | null | undefined | false | Child[];
+type Attributes = Record<string, string | number | boolean | EventListener | null | undefined>;
+export declare function h<Tag extends keyof HTMLElementTagNameMap>(tag: Tag, attributes?: Attributes, ...children: Child[]): HTMLElementTagNameMap[Tag];
+export declare function nodes(children: Child): (Node | string)[];
+export {};

package/dist/web/dom.js

@@ -0,0 +1,32 @@
+// Builds elements without innerHTML, so names from hosts and logs are always shown as text, and joins class names.
+// Joins the class names that are set, so conditional classes read as one expression.
+export function cx(...names) {
+    return names.filter(Boolean).join(" ");
+}
+export function h(tag, attributes = {}, ...children) {
+    const element = document.createElement(tag);
+    for (const [name, value] of Object.entries(attributes)) {
+        if (value === null || value === undefined || value === false)
+            continue;
+        if (typeof value === "function")
+            element.addEventListener(name.replace(/^on/, ""), value);
+        else if (value === true)
+            element.setAttribute(name, "");
+        else
+            element.setAttribute(name, String(value));
+    }
+    element.append(...nodes(children));
+    return element;
+}
+// The nodes a child stands for, with lists flattened and the empty values dropped.
+export function nodes(children) {
+    if (!Array.isArray(children))
+        children = [children];
+    return children.flatMap((child) => {
+        if (Array.isArray(child))
+            return nodes(child);
+        if (child === null || child === undefined || child === false)
+            return [];
+        return [child instanceof Node ? child : String(child)];
+    });
+}

package/dist/web/drag.d.ts

@@ -0,0 +1,3 @@
+export declare function set_drag_badge(event: {
+    dataTransfer: DataTransfer | null;
+}, label: string, class_name?: string): void;

package/dist/web/drag.js

@@ -0,0 +1,13 @@
+// What a drag shows under the pointer.
+// Shows a small badge such as "3 tasks" under the pointer as the drag image, in place of a picture of the grabbed row.
+export function set_drag_badge(event, label, class_name = "drag-badge") {
+    if (!event.dataTransfer)
+        return;
+    const badge = document.createElement("div");
+    badge.className = class_name;
+    badge.textContent = label;
+    document.body.append(badge);
+    event.dataTransfer.setDragImage(badge, -12, -12);
+    // The browser takes its picture of the badge during this event, so it can go once the event is over.
+    setTimeout(() => badge.remove(), 0);
+}

package/dist/web/errors.d.ts

@@ -0,0 +1 @@
+export declare function describe_error(error: unknown): string;

package/dist/web/errors.js

@@ -0,0 +1,27 @@
+// Words for anything thrown, since libraries throw plain objects and strings as well as Errors.
+// An Error's message, a shaka-style object's category and code, a string as it is, and anything else as JSON.
+export function describe_error(error) {
+    if (error instanceof Error)
+        return error.message || error.name;
+    if (typeof error === "string")
+        return error;
+    if (error === null || error === undefined)
+        return "Unknown error";
+    if (typeof error !== "object")
+        return String(error);
+    const coded = error;
+    if (typeof coded.code === "number") {
+        const name = typeof coded.category === "number" ? `${coded.category}.${coded.code}` : String(coded.code);
+        const text = typeof coded.message === "string" && coded.message ? coded.message : undefined;
+        const detail = text ?? (Array.isArray(coded.data) ? coded.data.find((item) => typeof item === "string") : undefined);
+        return detail ? `Error ${name}: ${detail}` : `Error ${name}`;
+    }
+    if (typeof coded.message === "string" && coded.message)
+        return coded.message;
+    try {
+        return JSON.stringify(error);
+    }
+    catch {
+        return String(error);
+    }
+}

package/dist/web/format.d.ts

@@ -0,0 +1,11 @@
+export declare function now_seconds(): number;
+export declare function age(epoch: number | null | undefined): string;
+export declare function until(epoch: number | null): string;
+export declare function duration(seconds: number | null): string;
+export declare function stamp(epoch: number): string;
+export declare function bytes(count: number): string;
+export declare function size(count: number | null | undefined): string;
+export declare function size_change(count: number | null | undefined): string;
+export declare function count_change(value: number | null | undefined): string;
+export declare function plural(count: number, word: string): string;
+export declare function compact_count(count: number): string;