@rapidmx/web-client 0.17.2 → 0.19.0

package/dist/apps/shared/components/admin/diagnostics/download.d.ts

@@ -0,0 +1,9 @@
+/** Saves `content` to the viewer's computer as a file called `filename`. What the download buttons call, so a test can swap it. */
+export type SaveFile = (filename: string, content: string, mimeType: string) => void;
+/**
+ * The browser way to save text it made itself: a Blob behind an object URL, opened by a temporary `<a download>`. The URL is
+ * revoked once the click has been handled (not in the same turn: some browsers start the download after it).
+ */
+export declare const saveTextFile: SaveFile;
+/** `rapidmx-server-logs-2026-09-26T10-30-00.000Z.log`: the name, then the time with the colons a file name cannot hold replaced. */
+export declare function timestampedFilename(name: string, extension: string, now?: Date): string;

package/dist/apps/shared/components/admin/diagnostics/download.js

@@ -0,0 +1,23 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The browser way to save text it made itself: a Blob behind an object URL, opened by a temporary `<a download>`. The URL is
+ * revoked once the click has been handled (not in the same turn: some browsers start the download after it).
+ */
+export const saveTextFile = (filename, content, mimeType) => {
+    const url = URL.createObjectURL(new Blob([content], { type: mimeType }));
+    const link = document.createElement("a");
+    link.href = url;
+    link.download = filename;
+    link.style.display = "none";
+    document.body.appendChild(link);
+    link.click();
+    link.remove();
+    setTimeout(() => URL.revokeObjectURL(url), 0);
+};
+/** `rapidmx-server-logs-2026-09-26T10-30-00.000Z.log`: the name, then the time with the colons a file name cannot hold replaced. */
+export function timestampedFilename(name, extension, now = new Date()) {
+    return `${name}-${now.toISOString().replace(/:/g, "-")}.${extension}`;
+}

package/dist/apps/shared/components/admin/diagnostics/format.d.ts

@@ -0,0 +1,24 @@
+/** What is shown where a number is missing or not a number. */
+export declare const NO_VALUE = "\u2014";
+/** `1536` as `1.5 KiB` (binary units, as Kubernetes reports them). */
+export declare function formatBytes(bytes: number | undefined): string;
+/** CPU as cores: `0.25 cores`, `1 core`, `4 cores`. */
+export declare function formatCores(cores: number | undefined): string;
+/** `42.34` as `42.3%`. */
+export declare function formatPercent(percent: number | undefined): string;
+/** `used` as a percentage of `capacity`, or `undefined` when either is missing or the capacity is not positive. */
+export declare function percentOf(used: number | undefined, capacity: number | undefined): number | undefined;
+/** Seconds as `3d 4h`, `4h 12m`, `12m 5s` or `5s`: the two largest units that are not zero. */
+export declare function formatUptime(seconds: number | undefined): string;
+/** A date as the viewer's local date and time, or a dash for a missing one (an unreadable one is shown as it came). */
+export declare function formatDateTime(value: string | undefined): string;
+/** `sha256:0123456789abcdef...` as `0123456789ab`. */
+export declare function shortDigest(digest: string | undefined): string;
+/** Shown when the server wants the administrator to have confirmed their identity recently (`api-104`). */
+export declare const ELEVATION_MESSAGE = "Diagnostics needs you to have recently confirmed your identity. Reload this page, or sign in again, then try once more.";
+/** Shown for a 403 that is not about elevation, or a 401. */
+export declare const NOT_AUTHORISED_MESSAGE = "You are not authorised to view diagnostics.";
+/** Whether the caller is not (or no longer) allowed: retrying the same request would fail the same way. */
+export declare function isPermissionError(err: unknown): boolean;
+/** Why a request failed, in words for the administrator. */
+export declare function describeError(err: unknown, fallback: string): string;

package/dist/apps/shared/components/admin/diagnostics/format.js

@@ -0,0 +1,91 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { isElevationRequired } from "../elevation.js";
+/** What is shown where a number is missing or not a number. */
+export const NO_VALUE = "—";
+const BYTE_UNITS = ["B", "KiB", "MiB", "GiB", "TiB", "PiB"];
+const isNumber = (value) => typeof value === "number" && Number.isFinite(value);
+/** `1536` as `1.5 KiB` (binary units, as Kubernetes reports them). */
+export function formatBytes(bytes) {
+    if (!isNumber(bytes)) {
+        return NO_VALUE;
+    }
+    let value = Math.abs(bytes);
+    let unit = 0;
+    while (value >= 1024 && unit < BYTE_UNITS.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    const text = unit === 0 || value >= 100 ? value.toFixed(0) : value.toFixed(1);
+    return `${bytes < 0 ? "-" : ""}${text} ${BYTE_UNITS[unit]}`;
+}
+/** CPU as cores: `0.25 cores`, `1 core`, `4 cores`. */
+export function formatCores(cores) {
+    if (!isNumber(cores)) {
+        return NO_VALUE;
+    }
+    const text = cores >= 10 ? cores.toFixed(0) : String(Number(cores.toFixed(2)));
+    return `${text} ${text === "1" ? "core" : "cores"}`;
+}
+/** `42.34` as `42.3%`. */
+export function formatPercent(percent) {
+    return isNumber(percent) ? `${percent.toFixed(1)}%` : NO_VALUE;
+}
+/** `used` as a percentage of `capacity`, or `undefined` when either is missing or the capacity is not positive. */
+export function percentOf(used, capacity) {
+    return isNumber(used) && isNumber(capacity) && capacity > 0 ? (used / capacity) * 100 : undefined;
+}
+/** Seconds as `3d 4h`, `4h 12m`, `12m 5s` or `5s`: the two largest units that are not zero. */
+export function formatUptime(seconds) {
+    if (!isNumber(seconds) || seconds < 0) {
+        return NO_VALUE;
+    }
+    const total = Math.floor(seconds);
+    const parts = [
+        [Math.floor(total / 86400), "d"],
+        [Math.floor((total % 86400) / 3600), "h"],
+        [Math.floor((total % 3600) / 60), "m"],
+        [total % 60, "s"],
+    ];
+    const start = parts.findIndex(([value]) => value > 0);
+    if (start === -1) {
+        return "0s";
+    }
+    return parts
+        .slice(start, start + 2)
+        .map(([value, unit]) => `${value}${unit}`)
+        .join(" ");
+}
+/** A date as the viewer's local date and time, or a dash for a missing one (an unreadable one is shown as it came). */
+export function formatDateTime(value) {
+    if (!value) {
+        return NO_VALUE;
+    }
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? value : date.toLocaleString();
+}
+/** `sha256:0123456789abcdef...` as `0123456789ab`. */
+export function shortDigest(digest) {
+    return digest ? digest.replace(/^[a-z0-9]+:/i, "").slice(0, 12) : NO_VALUE;
+}
+/** Shown when the server wants the administrator to have confirmed their identity recently (`api-104`). */
+export const ELEVATION_MESSAGE = "Diagnostics needs you to have recently confirmed your identity. Reload this page, or sign in again, then try once more.";
+/** Shown for a 403 that is not about elevation, or a 401. */
+export const NOT_AUTHORISED_MESSAGE = "You are not authorised to view diagnostics.";
+/** Whether the caller is not (or no longer) allowed: retrying the same request would fail the same way. */
+export function isPermissionError(err) {
+    return err instanceof ApiRequestError && (err.status === 403 || err.status === 401);
+}
+/** Why a request failed, in words for the administrator. */
+export function describeError(err, fallback) {
+    if (isElevationRequired(err)) {
+        return ELEVATION_MESSAGE;
+    }
+    if (isPermissionError(err)) {
+        return NOT_AUTHORISED_MESSAGE;
+    }
+    return err instanceof ApiRequestError ? err.message || fallback : fallback;
+}

package/dist/apps/shared/components/admin/diagnostics/logClient.d.ts

@@ -0,0 +1,85 @@
+import { LogEntry } from "./logLines.js";
+/**
+ * A client for the server's live log stream: the WebSocket of the `/admin` route's `logs` endpoint (`<origin>/api/admin/logs`).
+ * It follows the shape of `@rapidmx/react-shared`'s `PushClient`, and differs where the protocol does.
+ *
+ * - It authenticates from the `jwt` cookie the browser sends with the upgrade. The server closes the socket with code 1002 when
+ * the caller may not read the logs, or the stream is not set up on the server, with an error code as the close reason. That is
+ * final: retrying would be refused the same way, so the client stops with an error and does not reconnect.
+ * - The first frame is a control message, `{"id":0,"type":"SUBSCRIBED","success":true,"data":"<channel>"}`, which says the stream
+ * is live. It is not a log line. Every later frame is the JSON of one Winston `info` object (see `parseLogFrame()`).
+ * - Delivery is fire-and-forget: lines logged while the socket was down are not replayed.
+ * - Any other close is retried with exponential backoff and jitter until `stop()`.
+ */
+/** The subset of the browser's `WebSocket` this client uses - what a test's fake implements. */
+export interface LogSocket {
+    readyState: number;
+    close(code?: number, reason?: string): void;
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((event: {
+        code?: number;
+        reason?: string;
+    }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+}
+export type LogSocketFactory = (url: string) => LogSocket;
+/**
+ * `connecting`: opening the first connection. `live`: subscribed. `reconnecting`: the connection was lost, or a reconnect is
+ * being tried. `closed`: stopped (or never started). `error`: refused for good, with `error()` saying why.
+ */
+export type LogStreamStatus = "connecting" | "live" | "reconnecting" | "closed" | "error";
+/** The close code the server uses when it refuses the stream (a permission or configuration failure). */
+export declare const LOG_CLOSE_REFUSED = 1002;
+/** The first reconnect waits about this long, and each further failure doubles it ... */
+export declare const LOG_BACKOFF_BASE_MS = 1000;
+/** ... up to this. */
+export declare const LOG_BACKOFF_MAX_MS = 30000;
+/** The log stream's URL: `apiUrl("/admin/logs")` made absolute (a relative one takes this page's origin) on `ws:`/`wss:` to
+ * match. `undefined` where there is no origin to use (server-side rendering). */
+export declare function logsUrl(): string | undefined;
+/** What the error for a refused stream says: the server's reason is an error code, so it is shown as one. */
+export declare function refusedMessage(reason: string | undefined): string;
+export interface LogClientOptions {
+    /** The URL to connect to. Defaults to `logsUrl()`. */
+    url?: () => string | undefined;
+    /** Creates the socket. Defaults to the browser's `WebSocket`, if there is one. */
+    createSocket?: LogSocketFactory;
+    /** A `Math.random()` stand-in, for the backoff's jitter. */
+    random?: () => number;
+    /** A clock, for the time lines are received at. */
+    now?: () => number;
+}
+export declare class LogClient {
+    private readonly options;
+    private socket;
+    private running;
+    private attempt;
+    private timer;
+    private nextId;
+    private current;
+    private failure;
+    private readonly entryListeners;
+    private readonly statusListeners;
+    constructor(options?: LogClientOptions);
+    get status(): LogStreamStatus;
+    /** Why the stream is in the `error` state. */
+    get error(): string | undefined;
+    /** Connects, and keeps reconnecting until `stop()`, or until the server refuses the stream. A no-op while it already runs. */
+    start(): void;
+    /** Closes the socket and stops reconnecting. The client can be started again. */
+    stop(): void;
+    /** Calls `listener` with every log line; returns the function that stops it. */
+    onEntry(listener: (entry: LogEntry) => void): () => void;
+    /** Calls `listener` whenever the status changes; returns the function that stops it. */
+    onStatus(listener: (status: LogStreamStatus, error: string | undefined) => void): () => void;
+    private setStatus;
+    /** Lets go of the socket without hearing about it any more, and closes it. */
+    private detach;
+    private connect;
+    /** Waits out an exponentially growing, jittered delay ("equal jitter": half fixed, half random), then reconnects. */
+    private scheduleReconnect;
+    private handleFrame;
+}

package/dist/apps/shared/components/admin/diagnostics/logClient.js

@@ -0,0 +1,173 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { apiUrl } from "@rapidmx/react-shared/util/api.js";
+import { isControlFrame, parseLogFrame } from "./logLines.js";
+/** The close code the server uses when it refuses the stream (a permission or configuration failure). */
+export const LOG_CLOSE_REFUSED = 1002;
+/** The first reconnect waits about this long, and each further failure doubles it ... */
+export const LOG_BACKOFF_BASE_MS = 1000;
+/** ... up to this. */
+export const LOG_BACKOFF_MAX_MS = 30000;
+/** The log stream's URL: `apiUrl("/admin/logs")` made absolute (a relative one takes this page's origin) on `ws:`/`wss:` to
+ * match. `undefined` where there is no origin to use (server-side rendering). */
+export function logsUrl() {
+    const url = apiUrl("/admin/logs");
+    let absolute = url;
+    if (!/^https?:\/\//i.test(url)) {
+        absolute = typeof window === "undefined" ? undefined : `${window.location.origin}${url}`;
+    }
+    return absolute?.replace(/^http/i, "ws");
+}
+function defaultSocketFactory() {
+    return typeof WebSocket === "undefined" ? undefined : (url) => new WebSocket(url);
+}
+/** What the error for a refused stream says: the server's reason is an error code, so it is shown as one. */
+export function refusedMessage(reason) {
+    return reason
+        ? `The server refused the log stream (${reason}). Check that you are an administrator and that log streaming is enabled.`
+        : "The server refused the log stream. Check that you are an administrator and that log streaming is enabled.";
+}
+export class LogClient {
+    constructor(options = {}) {
+        this.options = options;
+        this.running = false;
+        this.attempt = 0;
+        this.nextId = 1;
+        this.current = "closed";
+        this.entryListeners = new Set();
+        this.statusListeners = new Set();
+    }
+    get status() {
+        return this.current;
+    }
+    /** Why the stream is in the `error` state. */
+    get error() {
+        return this.failure;
+    }
+    /** Connects, and keeps reconnecting until `stop()`, or until the server refuses the stream. A no-op while it already runs. */
+    start() {
+        if (this.running) {
+            return;
+        }
+        this.running = true;
+        this.attempt = 0;
+        this.connect();
+    }
+    /** Closes the socket and stops reconnecting. The client can be started again. */
+    stop() {
+        this.running = false;
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        this.detach();
+        this.setStatus("closed");
+    }
+    /** Calls `listener` with every log line; returns the function that stops it. */
+    onEntry(listener) {
+        this.entryListeners.add(listener);
+        return () => this.entryListeners.delete(listener);
+    }
+    /** Calls `listener` whenever the status changes; returns the function that stops it. */
+    onStatus(listener) {
+        this.statusListeners.add(listener);
+        return () => this.statusListeners.delete(listener);
+    }
+    setStatus(status, error) {
+        if (status === this.current && error === this.failure) {
+            return;
+        }
+        this.current = status;
+        this.failure = error;
+        for (const listener of [...this.statusListeners]) {
+            listener(status, error);
+        }
+    }
+    /** Lets go of the socket without hearing about it any more, and closes it. */
+    detach() {
+        const socket = this.socket;
+        this.socket = undefined;
+        if (socket) {
+            socket.onopen = socket.onmessage = socket.onclose = socket.onerror = null;
+            try {
+                socket.close(1000, "closing");
+            }
+            catch {
+                // Already gone.
+            }
+        }
+    }
+    connect() {
+        const url = (this.options.url ?? logsUrl)();
+        const createSocket = this.options.createSocket ?? defaultSocketFactory();
+        if (!url || !createSocket) {
+            this.running = false;
+            this.setStatus("error", "This browser cannot open a WebSocket to the server.");
+            return;
+        }
+        let socket;
+        try {
+            socket = createSocket(url);
+        }
+        catch {
+            this.scheduleReconnect();
+            return;
+        }
+        this.socket = socket;
+        this.setStatus(this.attempt === 0 ? "connecting" : "reconnecting");
+        socket.onmessage = (event) => this.handleFrame(event.data);
+        socket.onclose = (event) => {
+            if (this.socket !== socket) {
+                return;
+            }
+            this.socket = undefined;
+            if (event.code === LOG_CLOSE_REFUSED) {
+                this.running = false;
+                this.setStatus("error", refusedMessage(event.reason));
+                return;
+            }
+            this.scheduleReconnect();
+        };
+        // A failed connection is followed by a close, which is what triggers the retry.
+        socket.onerror = () => undefined;
+    }
+    /** Waits out an exponentially growing, jittered delay ("equal jitter": half fixed, half random), then reconnects. */
+    scheduleReconnect() {
+        const ceiling = Math.min(LOG_BACKOFF_MAX_MS, LOG_BACKOFF_BASE_MS * 2 ** Math.min(this.attempt, 30));
+        const delay = ceiling / 2 + ((this.options.random ?? Math.random)() * ceiling) / 2;
+        this.attempt += 1;
+        this.setStatus("reconnecting");
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            this.connect();
+        }, delay);
+    }
+    handleFrame(data) {
+        if (typeof data !== "string") {
+            return;
+        }
+        const frame = parseLogFrame(data, this.nextId, (this.options.now ?? Date.now)());
+        if (isControlFrame(frame)) {
+            if (frame.success) {
+                this.attempt = 0;
+                this.setStatus("live");
+            }
+            else {
+                // The server accepted the socket and refused the subscription: nothing will ever be sent.
+                this.running = false;
+                this.detach();
+                this.setStatus("error", refusedMessage(undefined));
+            }
+            return;
+        }
+        this.nextId += 1;
+        if (this.current !== "live") {
+            // A line before the greeting means the stream is flowing.
+            this.attempt = 0;
+            this.setStatus("live");
+        }
+        for (const listener of [...this.entryListeners]) {
+            listener(frame);
+        }
+    }
+}

package/dist/apps/shared/components/admin/diagnostics/logLines.d.ts

@@ -0,0 +1,47 @@
+/** The levels of the server's logger (Winston's npm levels), most severe first. */
+export declare const LOG_LEVELS: readonly ["error", "warn", "info", "http", "verbose", "debug", "silly"];
+export type LogLevel = (typeof LOG_LEVELS)[number];
+/** One line of the server's log stream. */
+export interface LogEntry {
+    /** Counts up from 1 in the order lines arrived; unique for the life of the stream. */
+    id: number;
+    /** When this page received it (`Date.now()`). */
+    receivedAt: number;
+    /** The level as the server wrote it (lower-cased, without colour codes); empty when it wrote none. */
+    level: string;
+    message: string;
+    /** As the server wrote it, when it did. */
+    timestamp?: string;
+    /** Every other field the server logged with the line (`label`, `service`, `stack`, ...). */
+    extra: Record<string, unknown>;
+    /** The frame as one line of JSON: what the `.ndjson` download holds. */
+    json: string;
+    /** Whether the frame was JSON. A frame that was not is shown as it came, with no level. */
+    structured: boolean;
+}
+/** What a frame is, when it is the server's own control message and not a log line. */
+export interface ControlFrame {
+    control: true;
+    success: boolean;
+    data: unknown;
+}
+export declare const stripAnsi: (text: string) => string;
+/**
+ * Reads one frame of the log stream. It is the control message (`{"id":0,"type":"SUBSCRIBED","success":true,...}`), a Winston
+ * `info` object (the JSON of `level`, `message` and whatever else was logged with them), or - since the server's logger can write
+ * anything - text that is not JSON at all. Whatever it is, the frame is never refused: a missing field is left empty.
+ */
+export declare function parseLogFrame(raw: string, id: number, receivedAt: number): LogEntry | ControlFrame;
+export declare const isControlFrame: (frame: LogEntry | ControlFrame) => frame is ControlFrame;
+/** When a line happened: what the server stamped it with, else when this page received it. */
+export declare function entryTime(entry: LogEntry): string;
+/** `<timestamp> <LEVEL> <message>`: the line of a `.log` download. A line with no level has none written. */
+export declare function formatLogLine(entry: LogEntry): string;
+/** The text of a `.log` download: one formatted line for each entry. */
+export declare function entriesToLog(entries: LogEntry[]): string;
+/** The text of an `.ndjson` download: each frame as one line of JSON. */
+export declare function entriesToNdjson(entries: LogEntry[]): string;
+/** Whether `entry` is one of `levels`. A line with no known level (text that was not JSON, an unusual level) is always kept. */
+export declare function levelVisible(entry: LogEntry, levels: ReadonlySet<string>): boolean;
+/** Whether `entry` contains `needle` (already lower-cased) in its time, level, message or other fields. */
+export declare function entryMatches(entry: LogEntry, needle: string): boolean;

package/dist/apps/shared/components/admin/diagnostics/logLines.js

@@ -0,0 +1,86 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** The levels of the server's logger (Winston's npm levels), most severe first. */
+export const LOG_LEVELS = ["error", "warn", "info", "http", "verbose", "debug", "silly"];
+/** Colour codes a logger writes around a level (`\u001b[32minfo\u001b[39m`). */
+// eslint-disable-next-line no-control-regex
+const ANSI_PATTERN = /\u001b\[[0-9;]*m/g;
+export const stripAnsi = (text) => text.replace(ANSI_PATTERN, "");
+/** A field's value as text: a string as it is, nothing as empty, anything else as JSON. */
+function textOf(value) {
+    if (typeof value === "string") {
+        return stripAnsi(value);
+    }
+    return value === undefined ? "" : JSON.stringify(value);
+}
+/**
+ * Reads one frame of the log stream. It is the control message (`{"id":0,"type":"SUBSCRIBED","success":true,...}`), a Winston
+ * `info` object (the JSON of `level`, `message` and whatever else was logged with them), or - since the server's logger can write
+ * anything - text that is not JSON at all. Whatever it is, the frame is never refused: a missing field is left empty.
+ */
+export function parseLogFrame(raw, id, receivedAt) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        parsed = undefined;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return {
+            id,
+            receivedAt,
+            level: "",
+            message: stripAnsi(raw),
+            extra: {},
+            json: JSON.stringify({ raw }),
+            structured: false,
+        };
+    }
+    const frame = parsed;
+    if (frame.type === "SUBSCRIBED" && frame.level === undefined) {
+        return { control: true, success: frame.success !== false, data: frame.data };
+    }
+    const { level, message, timestamp, ...extra } = frame;
+    return {
+        id,
+        receivedAt,
+        level: textOf(level).toLowerCase(),
+        message: textOf(message),
+        timestamp: typeof timestamp === "string" ? timestamp : undefined,
+        extra,
+        json: JSON.stringify(frame),
+        structured: true,
+    };
+}
+export const isControlFrame = (frame) => "control" in frame;
+/** When a line happened: what the server stamped it with, else when this page received it. */
+export function entryTime(entry) {
+    return entry.timestamp ?? new Date(entry.receivedAt).toISOString();
+}
+/** `<timestamp> <LEVEL> <message>`: the line of a `.log` download. A line with no level has none written. */
+export function formatLogLine(entry) {
+    return [entryTime(entry), entry.level.toUpperCase(), entry.message].filter((part) => part !== "").join(" ");
+}
+/** The text of a `.log` download: one formatted line for each entry. */
+export function entriesToLog(entries) {
+    return entries.map((entry) => formatLogLine(entry).replace(/\r?\n/g, " ↵ ")).join("\n") + "\n";
+}
+/** The text of an `.ndjson` download: each frame as one line of JSON. */
+export function entriesToNdjson(entries) {
+    return entries.map((entry) => entry.json).join("\n") + "\n";
+}
+/** Whether `entry` is one of `levels`. A line with no known level (text that was not JSON, an unusual level) is always kept. */
+export function levelVisible(entry, levels) {
+    return !LOG_LEVELS.includes(entry.level) || levels.has(entry.level);
+}
+/** Whether `entry` contains `needle` (already lower-cased) in its time, level, message or other fields. */
+export function entryMatches(entry, needle) {
+    if (needle === "") {
+        return true;
+    }
+    const extra = Object.keys(entry.extra).length > 0 ? JSON.stringify(entry.extra) : "";
+    return `${formatLogLine(entry)} ${extra}`.toLowerCase().includes(needle);
+}

package/dist/apps/shared/components/admin/diagnostics/metricsHistory.d.ts

@@ -0,0 +1,9 @@
+import type { DiagnosticsMetrics } from "./diagnosticsApi.js";
+/** How often the System tab asks the server for a new sample. */
+export declare const METRICS_POLL_INTERVAL_MS = 5000;
+/** How many samples the System tab keeps: the last five minutes at `METRICS_POLL_INTERVAL_MS`. */
+export declare const METRICS_HISTORY_SIZE = 60;
+/** `history` with `sample` added, the oldest samples dropped beyond `METRICS_HISTORY_SIZE`. */
+export declare function appendSample(history: DiagnosticsMetrics[], sample: DiagnosticsMetrics): DiagnosticsMetrics[];
+/** The values `pick` finds in each sample, in order. A sample it finds nothing in (a node with no stats yet, say) is skipped. */
+export declare function seriesOf(history: DiagnosticsMetrics[], pick: (sample: DiagnosticsMetrics) => number | undefined): number[];

package/dist/apps/shared/components/admin/diagnostics/metricsHistory.js

@@ -0,0 +1,19 @@
+/** How often the System tab asks the server for a new sample. */
+export const METRICS_POLL_INTERVAL_MS = 5000;
+/** How many samples the System tab keeps: the last five minutes at `METRICS_POLL_INTERVAL_MS`. */
+export const METRICS_HISTORY_SIZE = 60;
+/** `history` with `sample` added, the oldest samples dropped beyond `METRICS_HISTORY_SIZE`. */
+export function appendSample(history, sample) {
+    return [...history, sample].slice(-METRICS_HISTORY_SIZE);
+}
+/** The values `pick` finds in each sample, in order. A sample it finds nothing in (a node with no stats yet, say) is skipped. */
+export function seriesOf(history, pick) {
+    const values = [];
+    for (const sample of history) {
+        const value = pick(sample);
+        if (typeof value === "number" && Number.isFinite(value)) {
+            values.push(value);
+        }
+    }
+    return values;
+}

package/dist/apps/shared/components/admin/diagnostics/useDiagnosticsResource.d.ts

@@ -0,0 +1,12 @@
+export interface DiagnosticsResource<T> {
+    /** What was last loaded. It stays while a reload is under way, and after a reload that failed. */
+    data: T | undefined;
+    /** Why the last load failed. */
+    error: string | undefined;
+    loading: boolean;
+}
+/**
+ * Loads `load()` when the component mounts and again whenever `reloadKey` changes (the Refresh button). It is never polled.
+ * The answer to a load that a newer one (or an unmount) has overtaken is dropped.
+ */
+export declare function useDiagnosticsResource<T>(load: () => Promise<T>, reloadKey: number, failure: string): DiagnosticsResource<T>;

package/dist/apps/shared/components/admin/diagnostics/useDiagnosticsResource.js

@@ -0,0 +1,30 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+import { describeError } from "./format.js";
+/**
+ * Loads `load()` when the component mounts and again whenever `reloadKey` changes (the Refresh button). It is never polled.
+ * The answer to a load that a newer one (or an unmount) has overtaken is dropped.
+ */
+export function useDiagnosticsResource(load, reloadKey, failure) {
+    const [state, setState] = useState({ data: undefined, error: undefined, loading: true });
+    useEffect(() => {
+        let cancelled = false;
+        setState((previous) => ({ ...previous, error: undefined, loading: true }));
+        load().then((data) => {
+            if (!cancelled) {
+                setState({ data, error: undefined, loading: false });
+            }
+        }, (err) => {
+            if (!cancelled) {
+                setState((previous) => ({ ...previous, error: describeError(err, failure), loading: false }));
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [reloadKey]);
+    return state;
+}