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

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/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/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

@@ -1,3 +1,5 @@
+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];

package/dist/web/dom.js

@@ -1,4 +1,8 @@
-// Builds elements without innerHTML, so names from hosts and logs are always shown as text.
+// 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)) {

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/react/badges.d.ts

@@ -24,3 +24,12 @@ export declare function Verdict({ ok, label }: {
     ok: boolean | null | undefined;
     label: string;
 }): import("react").JSX.Element;
+interface StatusPillProps {
+    tone?: Tone;
+    busy?: boolean;
+    label: ReactNode;
+    action?: ReactNode;
+    title?: string;
+}
+export declare function StatusPill({ tone, busy, label, action, title }: StatusPillProps): import("react").JSX.Element;
+export {};

package/dist/web/react/badges.js

@@ -26,3 +26,7 @@ export function Verdict({ ok, label }) {
     const known = ok !== null && ok !== undefined;
     return _jsxs("span", { className: `verdict tone-${known ? (ok ? "good" : "bad") : "none"}`, children: [label, ": ", known ? (ok ? "pass" : "fail") : "no verdict"] });
 }
+// A state dot and its text, such as "Idle" or "Researching", with an optional button, for a top bar.
+export function StatusPill({ tone = "none", busy = false, label, action, title }) {
+    return (_jsxs("span", { className: "status-pill", title: title, children: [_jsx("span", { className: busy ? `status-dot tone-${tone} busy` : `status-dot tone-${tone}`, "aria-hidden": "true" }), _jsx("span", { className: "status-text small", children: label }), action] }));
+}

package/dist/web/react/controls.d.ts

@@ -55,6 +55,16 @@ interface DateTimeFieldProps {
     allow_time?: boolean;
 }
 export declare function DateTimeField({ label, value, on_change, allow_time }: DateTimeFieldProps): import("react").JSX.Element;
+interface PathInputProps {
+    label: string;
+    value: string;
+    on_change: (value: string) => void;
+    pick: (current: string) => Promise<string | null>;
+    placeholder?: string;
+    disabled?: boolean;
+    browse_label?: string;
+}
+export declare function PathInput({ label, value, on_change, pick, placeholder, disabled, browse_label }: PathInputProps): import("react").JSX.Element;
 interface ColorPickerProps {
     label: string;
     value: string | null;

package/dist/web/react/controls.js

@@ -123,6 +123,22 @@ export function DateTimeField({ label, value, on_change, allow_time = true }) {
     const join = (next_day, next_time) => on_change(next_day ? (next_time && allow_time ? `${next_day}T${next_time}` : next_day) : null);
     return (_jsxs("div", { className: "field date-time-field", children: [_jsx("span", { className: "field-label", children: label }), _jsxs("div", { className: "date-time-inputs", children: [_jsx("input", { type: "date", "aria-label": `${label} date`, value: day, onChange: (event) => join(event.currentTarget.value, time) }), day && allow_time && _jsx("input", { type: "time", "aria-label": `${label} time`, value: time, onChange: (event) => join(day, event.currentTarget.value) }), day && _jsx("button", { type: "button", className: "icon", "aria-label": `Clear ${label.toLowerCase()} date`, onClick: () => on_change(null), children: "\u00D7" })] })] }));
 }
+// A path typed by hand or picked through a Browse button.
+export function PathInput({ label, value, on_change, pick, placeholder, disabled = false, browse_label = "Browse…" }) {
+    const [picking, set_picking] = useState(false);
+    async function browse() {
+        set_picking(true);
+        try {
+            const chosen = await pick(value);
+            if (chosen !== null)
+                on_change(chosen);
+        }
+        finally {
+            set_picking(false);
+        }
+    }
+    return (_jsxs("span", { className: "path-row", children: [_jsx("input", { type: "text", "aria-label": label, spellCheck: false, placeholder: placeholder, disabled: disabled, value: value, onChange: (event) => on_change(event.currentTarget.value) }), _jsx("button", { type: "button", disabled: disabled || picking, onClick: () => void browse(), children: browse_label })] }));
+}
 // Swatches, a None choice, and the system colour chooser for any other colour.
 export function ColorPicker({ label, value, swatches, on_change, allow_none = true }) {
     const is_swatch = value !== null && swatches.some((swatch) => swatch.toLowerCase() === value.toLowerCase());

package/dist/web/react/following.d.ts

@@ -0,0 +1,25 @@
+import { type ReactNode, type RefObject, type UIEvent } from "react";
+export declare const at_bottom: (element: HTMLElement) => boolean;
+export interface FollowTail<Element extends HTMLElement> {
+    ref: RefObject<Element | null>;
+    following: boolean;
+    set_following: (following: boolean) => void;
+    on_scroll: (event: UIEvent<Element>) => void;
+}
+export declare function use_follow_tail<Element extends HTMLElement>(dependency: unknown, active?: boolean): FollowTail<Element>;
+interface FollowToggleProps {
+    following: boolean;
+    on_change: (following: boolean) => void;
+    disabled?: boolean;
+    label?: string;
+}
+export declare function FollowToggle({ following, on_change, disabled, label }: FollowToggleProps): import("react").JSX.Element;
+interface FollowingOutputProps {
+    text: string;
+    active?: boolean;
+    toggle?: boolean;
+    class_name?: string;
+    tools?: ReactNode;
+}
+export declare function FollowingOutput({ text, active, toggle, class_name, tools }: FollowingOutputProps): import("react").JSX.Element;
+export {};

package/dist/web/react/following.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Output that keeps its newest lines in view as they arrive, unless the reader has scrolled up to read, with a Follow switch.
+import { useCallback, useLayoutEffect, useRef, useState } from "react";
+import { cx } from "../dom.js";
+// How far above the bottom still counts as at the bottom.
+const FOLLOW_SLACK_PIXELS = 8;
+export const at_bottom = (element) => element.scrollTop + element.clientHeight >= element.scrollHeight - FOLLOW_SLACK_PIXELS;
+// Scrolls the box to its end whenever the dependency changes while following; active false, such as once a run has ended, leaves the scroll alone.
+export function use_follow_tail(dependency, active = true) {
+    const ref = useRef(null);
+    const [following, set_following] = useState(true);
+    useLayoutEffect(() => {
+        const element = ref.current;
+        if (following && active && element)
+            element.scrollTop = element.scrollHeight;
+    }, [dependency, following, active]);
+    const on_scroll = useCallback((event) => {
+        if (!active)
+            return;
+        set_following(at_bottom(event.currentTarget));
+    }, [active]);
+    return { ref, following, set_following, on_scroll };
+}
+export function FollowToggle({ following, on_change, disabled = false, label = "Follow" }) {
+    return (_jsxs("label", { className: "follow-toggle", children: [_jsx("input", { type: "checkbox", checked: following, disabled: disabled, onChange: (event) => on_change(event.currentTarget.checked) }), " ", label] }));
+}
+// Streamed text in an output box that follows its tail.
+export function FollowingOutput({ text, active = true, toggle = false, class_name, tools }) {
+    const tail = use_follow_tail(text, active);
+    const output = _jsx("pre", { ref: tail.ref, className: cx("output", "following-output", class_name), onScroll: tail.on_scroll, children: text });
+    if (!toggle && tools === undefined)
+        return output;
+    return (_jsxs("div", { className: "following", children: [_jsxs("div", { className: "following-tools", children: [tools, toggle && _jsx(FollowToggle, { following: tail.following, on_change: tail.set_following, disabled: !active })] }), output] }));
+}

package/dist/web/react/layout.d.ts

@@ -8,9 +8,10 @@ interface PageHeadingProps {
     banner?: string | ReactNode;
     actions?: ReactNode;
     class_name?: string;
+    level?: 1 | 2 | 3;
     children?: ReactNode;
 }
-export declare function PageHeading({ title, subtitle, icon, banner, actions, class_name, children }: PageHeadingProps): import("react").JSX.Element;
+export declare function PageHeading({ title, subtitle, icon, banner, actions, class_name, level, children }: PageHeadingProps): import("react").JSX.Element;
 interface SectionProps {
     title: ReactNode;
     tools?: ReactNode;

package/dist/web/react/layout.js

@@ -3,8 +3,9 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { Fragment } from "react";
 export { moved } from "../tables.js";
 // A page's heading: an optional banner, the title with its icon and subtitle, and the page's buttons.
-export function PageHeading({ title, subtitle, icon, banner, actions, class_name, children }) {
-    return (_jsxs("header", { className: class_name ? `page-head ${class_name}` : "page-head", children: [typeof banner === "string" ? _jsx("img", { className: "page-banner", src: banner, alt: "", loading: "lazy" }) : banner, _jsxs("div", { className: "page-title spread", children: [_jsxs("div", { className: "page-identity", children: [icon, _jsxs("div", { children: [_jsx("h1", { children: title }), subtitle && _jsx("p", { className: "page-subtitle muted", children: subtitle })] })] }), actions && _jsx("div", { className: "head-actions", children: actions })] }), children] }));
+export function PageHeading({ title, subtitle, icon, banner, actions, class_name, level = 1, children }) {
+    const Title = `h${level}`;
+    return (_jsxs("header", { className: class_name ? `page-head ${class_name}` : "page-head", children: [typeof banner === "string" ? _jsx("img", { className: "page-banner", src: banner, alt: "", loading: "lazy" }) : banner, _jsxs("div", { className: "page-title spread", children: [_jsxs("div", { className: "page-identity", children: [icon, _jsxs("div", { children: [_jsx(Title, { children: title }), subtitle && _jsx("p", { className: "page-subtitle muted", children: subtitle })] })] }), actions && _jsx("div", { className: "head-actions", children: actions })] }), children] }));
 }
 export function Section({ title, tools, class_name, on_context_menu, children }) {
     return (_jsxs("section", { className: class_name ? `panel ${class_name}` : "panel", onContextMenu: on_context_menu, children: [_jsxs("div", { className: "panel-head", children: [_jsx("h2", { children: title }), tools && _jsx("div", { className: "panel-tools", children: tools })] }), children] }));

package/dist/web/react/markdown.d.ts

@@ -0,0 +1,8 @@
+export declare function render_markdown(text: string): string;
+interface MarkdownProps {
+    text: string;
+    class_name?: string;
+    follow?: boolean;
+}
+export declare function Markdown({ text, class_name, follow }: MarkdownProps): import("react").JSX.Element;
+export {};