ankka-console 0.10.0 → 0.11.0

package/dist/ui/tokens.js

@@ -0,0 +1,172 @@
+/**
+ * The console's look as values: the one source the stylesheet is generated from, the contrast test
+ * reads, and the documentation's table of properties is written from. Each becomes a `--ac-*`
+ * custom property a host may set; the names are a contract, the values are not.
+ *
+ * Text sits on translucent surfaces, so its contrast depends on what is behind it. The backdrop is
+ * brightest where the glow peaks, and every ink must keep 4.5:1 on every surface there, in both
+ * themes. The glow's alpha is therefore a limit: `test/contrast.test.ts` fails if it is raised past
+ * what the inks can stand.
+ */
+export const tokens = {
+    dark: {
+        mesh: {
+            base: "#111f26",
+            slate: "#1e2e3a",
+            glow: "rgba(212, 128, 88, 0.34)",
+            peach: "rgba(222, 170, 132, 0.16)",
+            dot: "rgba(255, 255, 255, 0.08)",
+        },
+        surface: {
+            glass: "rgba(255, 255, 255, 0.05)",
+            glassStrong: "rgba(255, 255, 255, 0.09)",
+            glassLine: "rgba(255, 255, 255, 0.2)",
+            tile: "rgba(255, 255, 255, 0.06)",
+            tileLine: "rgba(255, 255, 255, 0.14)",
+            node: "rgba(255, 255, 255, 0.1)",
+            nodeLine: "rgba(255, 255, 255, 0.38)",
+            inset: "rgba(0, 0, 0, 0.2)",
+            edge: "rgba(255, 255, 255, 0.7)",
+        },
+        ink: { ink: "#f5f8f7", ink2: "#dfe8e6", ink3: "#ccd9d6" },
+        accent: { amber: "#f0b83c", amberInk: "#13343b", green: "#8fe0ad", red: "#ffc4bc", redWash: "rgba(255, 138, 128, 0.16)" },
+        shadow: "0 18px 50px rgba(5, 15, 18, 0.28)",
+    },
+    light: {
+        mesh: {
+            base: "#e6eeee",
+            slate: "#cfe0dc",
+            glow: "rgba(224, 165, 38, 0.30)",
+            peach: "rgba(241, 213, 194, 0.80)",
+            dot: "rgba(19, 52, 59, 0.10)",
+        },
+        surface: {
+            glass: "rgba(255, 255, 255, 0.50)",
+            glassStrong: "rgba(255, 255, 255, 0.85)",
+            glassLine: "rgba(19, 52, 59, 0.14)",
+            tile: "rgba(255, 255, 255, 0.50)",
+            tileLine: "rgba(19, 52, 59, 0.10)",
+            node: "rgba(255, 255, 255, 0.62)",
+            nodeLine: "rgba(19, 52, 59, 0.22)",
+            inset: "rgba(19, 52, 59, 0.06)",
+            edge: "rgba(19, 52, 59, 0.55)",
+        },
+        ink: { ink: "#13343b", ink2: "#33504f", ink3: "#4a6465" },
+        accent: { amber: "#e0a526", amberInk: "#13343b", green: "#1f6b3a", red: "#a8231b", redWash: "#fbe9e7" },
+        shadow: "0 18px 50px rgba(19, 52, 59, 0.10)",
+    },
+    radius: { panel: "20px", card: "14px", control: "10px", node: "18px" },
+    font: {
+        sans: '"Inter Variable", system-ui, -apple-system, "Segoe UI", Roboto, sans-serif',
+        mono: 'ui-monospace, "SF Mono", Menlo, Consolas, monospace',
+    },
+    size: { rail: "56px", panel: "232px", inspector: "300px", bar: "64px" },
+};
+/** Every colour property of a theme, by its CSS name without the `--ac-` prefix. */
+export function colours(theme) {
+    return [
+        ["color-mesh-base", theme.mesh.base],
+        ["color-mesh-slate", theme.mesh.slate],
+        ["color-glow", theme.mesh.glow],
+        ["color-peach", theme.mesh.peach],
+        ["color-dot", theme.mesh.dot],
+        ["color-glass", theme.surface.glass],
+        ["color-glass-strong", theme.surface.glassStrong],
+        ["color-glass-line", theme.surface.glassLine],
+        ["color-tile", theme.surface.tile],
+        ["color-tile-line", theme.surface.tileLine],
+        ["color-node", theme.surface.node],
+        ["color-node-line", theme.surface.nodeLine],
+        ["color-inset", theme.surface.inset],
+        ["color-edge", theme.surface.edge],
+        ["color-ink", theme.ink.ink],
+        ["color-ink-2", theme.ink.ink2],
+        ["color-ink-3", theme.ink.ink3],
+        ["color-amber", theme.accent.amber],
+        ["color-amber-ink", theme.accent.amberInk],
+        ["color-green", theme.accent.green],
+        ["color-red", theme.accent.red],
+        ["color-red-wash", theme.accent.redWash],
+        ["shadow-part", theme.shadow],
+    ];
+}
+/** The properties that are the same in both themes. */
+export function constants(t) {
+    return [
+        ["radius-panel", t.radius.panel],
+        ["radius-card", t.radius.card],
+        ["radius-control", t.radius.control],
+        ["radius-node", t.radius.node],
+        ["font-sans", t.font.sans],
+        ["font-mono", t.font.mono],
+        ["size-rail", t.size.rail],
+        ["size-panel", t.size.panel],
+        ["size-inspector", t.size.inspector],
+        ["size-bar", t.size.bar],
+    ];
+}
+/**
+ * The stylesheet's theme. The console is dark; its values are the theme itself. Light redefines the
+ * same properties when a host chooses it, by putting `ac-light` on the shell. Browsers report a
+ * preference for light when nobody has stated one, so the browser's preference is not followed.
+ * Both sit on `:root` and inside the `theme` layer, so a host's own, unlayered declaration of any of
+ * them wins in either theme, on any element.
+ *
+ * Tailwind prefixes the `@theme` names (`--color-ink` becomes `--ac-color-ink`); the light block is
+ * plain CSS and names the prefixed property itself.
+ */
+export function toCss(t) {
+    const decl = (pairs, prefix) => pairs.map(([k, v]) => `  ${prefix}${k}: ${v};`).join("\n");
+    return [
+        "/* Generated from src/ui/tokens.ts by scripts/build.ts. Do not edit. */",
+        "@theme static {",
+        "  --*: initial;",
+        "  --spacing: 0.25rem;",
+        decl(colours(t.dark), "--"),
+        decl(constants(t), "--"),
+        "}",
+        "",
+        "@layer theme {",
+        "  :root:has(.ac-light) {",
+        decl(colours(t.light), "    --ac-"),
+        "  }",
+        "}",
+        "",
+    ].join("\n");
+}
+/** What each property is for, by its name without the `--ac-` prefix: the documentation's table. */
+export const roles = {
+    "color-mesh-base": "The backdrop's darker colour, and what a surface is drawn over where blur is unavailable.",
+    "color-mesh-slate": "The backdrop's lighter colour.",
+    "color-glow": "The glow at the centre of the screen. Its alpha is the brightest the backdrop gets: the limit.",
+    "color-peach": "The warmth in the lower corner.",
+    "color-dot": "The dot grid across the backdrop.",
+    "color-glass": "The rail, the bar, the listing and the inspector.",
+    "color-glass-strong": "A button, and the item being read in the listing.",
+    "color-glass-line": "The edge of the glass surfaces.",
+    "color-tile": "A card on the page, and an item in the listing.",
+    "color-tile-line": "A card's edge and the rules in its tables.",
+    "color-node": "A part of a service's shape and of its topology.",
+    "color-node-line": "A part's edge.",
+    "color-inset": "Fields, logs, the section links and a part's inset row.",
+    "color-edge": "The joins between parts.",
+    "color-ink": "Text.",
+    "color-ink-2": "Secondary text: labels, hints, counts.",
+    "color-ink-3": "Section titles and placeholders.",
+    "color-amber": "The accent: focus, the current area, toggles, the primary operation.",
+    "color-amber-ink": "Text on the accent.",
+    "color-green": "A ready lifecycle's mark.",
+    "color-red": "Failure: a failed lifecycle, a destructive button, a field's error.",
+    "color-red-wash": "Behind a refusal.",
+    "shadow-part": "The shadow under a part.",
+    "radius-panel": "The shell's surfaces.",
+    "radius-card": "Cards.",
+    "radius-control": "Fields and listing items.",
+    "radius-node": "A part of the shape.",
+    "font-sans": "The face; the package serves Inter itself.",
+    "font-mono": "Logs, descriptors and secrets.",
+    "size-rail": "The rail's width.",
+    "size-panel": "The listing's width.",
+    "size-inspector": "The inspector's width.",
+    "size-bar": "The bar's height.",
+};

package/dist/ui/topology/Graph.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A topology as a picture: a column per layer, declared connections solid, observed calls dashed and
+ * heavier the more they were made, a warning mark only for failed or unanswered calls. The picture
+ * says what it holds in its label; the same facts are in the table beside it.
+ */
+import { type View } from "./layout.ts";
+export declare function Graph({ shown, differs, selected, onSelect, }: {
+    shown: View;
+    /** Nodes not on every instance that answered. */
+    differs: Set<string>;
+    selected: string | null;
+    onSelect: (id: string) => void;
+}): import("react").JSX.Element;

package/dist/ui/topology/Graph.js

@@ -0,0 +1,56 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * A topology as a picture: a column per layer, declared connections solid, observed calls dashed and
+ * heavier the more they were made, a warning mark only for failed or unanswered calls. The picture
+ * says what it holds in its label; the same facts are in the table beside it.
+ */
+import { describe, edgeMark, weight } from "./layout.js";
+const GRID = { margin: 16, column: 210, row: 64, width: 170, height: 40 };
+function clip(text, length) {
+    return text.length > length ? text.slice(0, length - 1) + "…" : text;
+}
+function kindInWords(kind) {
+    return kind.replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase();
+}
+export function Graph({ shown, differs, selected, onSelect, }) {
+    const columns = Math.max(0, ...shown.nodes.map((n) => n.column)) + 1;
+    const rows = Math.max(0, ...shown.nodes.map((n) => n.row)) + 1;
+    const width = GRID.margin * 2 + (columns - 1) * GRID.column + GRID.width;
+    const height = GRID.margin * 2 + (rows - 1) * GRID.row + GRID.height;
+    const at = new Map(shown.nodes.map((n) => [n.id, { x: GRID.margin + n.column * GRID.column, y: GRID.margin + n.row * GRID.row }]));
+    const path = (from, to, below) => {
+        const a = at.get(from);
+        const b = at.get(to);
+        if (!a || !b || from === to)
+            return null;
+        const forwards = b.x >= a.x;
+        const x1 = forwards ? a.x + GRID.width : a.x;
+        const x2 = forwards ? b.x : b.x + GRID.width;
+        const y1 = a.y + GRID.height / 2 + below;
+        const y2 = b.y + GRID.height / 2 + below;
+        const bend = (x2 - x1) / 2;
+        return { d: `M ${x1} ${y1} C ${x1 + bend} ${y1}, ${x2 - bend} ${y2}, ${x2} ${y2}`, mx: (x1 + x2) / 2, my: (y1 + y2) / 2 };
+    };
+    const node = (n) => {
+        const { x, y } = at.get(n.id);
+        const outside = n.kind.startsWith("External") || n.kind === "UnknownCaller";
+        const classes = ["ac-topology-node", outside ? "ac-topology-outside" : "", n.platform ? "ac-topology-platform" : "", differs.has(n.id) ? "ac-topology-differs" : "", n.id === selected ? "ac-topology-selected" : ""]
+            .filter(Boolean)
+            .join(" ");
+        const kind = kindInWords(n.kind) + (n.platform ? ", platform" : "") + (differs.has(n.id) ? ", not on every instance" : "");
+        return (_jsxs("g", { className: classes, transform: `translate(${x} ${y})`, tabIndex: 0, role: "button", "aria-label": `${n.label}: ${kind}`, onClick: () => onSelect(n.id), onKeyDown: (e) => {
+                if (e.key === "Enter" || e.key === " ")
+                    onSelect(n.id);
+            }, children: [_jsx("rect", { width: GRID.width, height: GRID.height, rx: 12, filter: "url(#ac-topology-shadow)" }), _jsx("text", { x: 10, y: 16, className: "ac-topology-name", children: clip(n.label, 22) }), _jsx("text", { x: 10, y: 30, className: "ac-topology-kind", children: clip(kind, 28) })] }, n.id));
+    };
+    return (_jsxs("svg", { className: "ac-topology-graph", viewBox: `0 0 ${width} ${height}`, width: width, height: height, role: "group", "aria-label": describe(shown), children: [_jsx("defs", { children: _jsx("filter", { id: "ac-topology-shadow", x: "-20%", y: "-30%", width: "140%", height: "180%", children: _jsx("feDropShadow", { dx: "0", dy: "6", stdDeviation: "8", floodColor: "#05090b", floodOpacity: "0.28" }) }) }), shown.declared.map((e) => {
+                const p = path(e.from, e.to, 0);
+                return p ? (_jsx("path", { className: "ac-topology-declared", d: p.d, children: _jsx("title", { children: `${e.from} to ${e.to}: ${e.kind}` }) }, `d:${e.from}>${e.to}:${e.kind}`)) : null;
+            }), shown.calls.map((c) => {
+                const p = path(c.from, c.to, 7);
+                if (!p)
+                    return null;
+                const warning = edgeMark(c.pairs) === "warning";
+                return (_jsxs("g", { children: [_jsx("path", { className: `ac-topology-call${warning ? " ac-topology-warning" : ""}`, d: p.d, style: { strokeWidth: `${0.75 + weight(c.pairs) * 0.75}px` }, children: _jsx("title", { children: `${c.from} calls ${c.to}` }) }), warning ? (_jsx("text", { className: "ac-topology-mark", x: p.mx - 3, y: p.my - 4, children: "!" })) : null] }, `c:${c.from}>${c.to}`));
+            }), shown.nodes.map(node)] }));
+}

package/dist/ui/topology/Table.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The topology as text: every fact the picture shows, in tables a screen reader and a search can
+ * read. Handled and unanswered are separate columns, because they are separate facts.
+ */
+import type { Pair, View } from "./layout.ts";
+export declare function duration(pair: Pair): string;
+export declare function Table({ shown, differs }: {
+    shown: View;
+    differs: Map<string, string[]>;
+}): import("react").JSX.Element;

package/dist/ui/topology/Table.js

@@ -0,0 +1,14 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+function nameOf(shown, id) {
+    return shown.nodes.find((n) => n.id === id)?.label ?? id;
+}
+function kindInWords(kind) {
+    return kind.replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase();
+}
+export function duration(pair) {
+    const d = pair.durationMillis;
+    return d ? `~${d.p50} / ~${d.p99} / ~${d.max} ms` : "";
+}
+export function Table({ shown, differs }) {
+    return (_jsxs(_Fragment, { children: [_jsx("div", { className: "ac-table-wrap", children: _jsxs("table", { className: "ac-table", "aria-label": "Components", children: [_jsx("caption", { className: "ac-visually-hidden", children: "Components" }), _jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: "Name" }), _jsx("th", { scope: "col", children: "Kind" }), _jsx("th", { scope: "col", children: "Handlers" })] }) }), _jsx("tbody", { children: shown.nodes.map((n) => (_jsxs("tr", { "data-node": n.id, children: [_jsx("td", { children: n.label }), _jsxs("td", { children: [kindInWords(n.kind), n.platform ? ", platform" : "", differs.has(n.id) ? `, only on ${differs.get(n.id).join(", ")}` : ""] }), _jsx("td", { children: n.handlers.map((h) => h.name).join(", ") })] }, n.id))) })] }) }), shown.declared.length > 0 ? (_jsx("div", { className: "ac-table-wrap", children: _jsxs("table", { className: "ac-table", "aria-label": "Declared connections", children: [_jsx("caption", { className: "ac-visually-hidden", children: "Declared connections" }), _jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: "From" }), _jsx("th", { scope: "col", children: "To" }), _jsx("th", { scope: "col", children: "As" })] }) }), _jsx("tbody", { children: shown.declared.map((e) => (_jsxs("tr", { children: [_jsx("td", { children: nameOf(shown, e.from) }), _jsx("td", { children: nameOf(shown, e.to) }), _jsx("td", { children: e.kind })] }, `${e.from}>${e.to}:${e.kind}`))) })] }) })) : null, shown.calls.length > 0 ? (_jsx("div", { className: "ac-table-wrap", children: _jsxs("table", { className: "ac-table", "aria-label": "Observed calls", children: [_jsx("caption", { className: "ac-visually-hidden", children: "Observed calls" }), _jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: "From" }), _jsx("th", { scope: "col", children: "To" }), _jsx("th", { scope: "col", children: "Handler to handler" }), _jsx("th", { scope: "col", className: "ac-num", children: "Ok" }), _jsx("th", { scope: "col", className: "ac-num", children: "Refused" }), _jsx("th", { scope: "col", className: "ac-num", children: "Failed" }), _jsx("th", { scope: "col", className: "ac-num", children: "Timed out" }), _jsx("th", { scope: "col", className: "ac-num", children: "Undelivered" }), _jsx("th", { scope: "col", children: "p50 / p99 / max" })] }) }), _jsx("tbody", { children: shown.calls.flatMap((c) => c.pairs.map((p) => (_jsxs("tr", { "data-pair": `${p.caller} -> ${p.callee}`, children: [_jsx("td", { children: nameOf(shown, c.from) }), _jsx("td", { children: nameOf(shown, c.to) }), _jsxs("td", { children: [p.caller, " \u2192 ", p.callee, p.streaming ? " (stream)" : ""] }), _jsx("td", { className: "ac-num", children: p.handled?.ok ?? 0 }), _jsx("td", { className: "ac-num", children: p.handled?.refused ?? 0 }), _jsx("td", { className: "ac-num", children: p.handled?.failed ?? 0 }), _jsx("td", { className: "ac-num", children: p.unanswered?.timedOut ?? 0 }), _jsx("td", { className: "ac-num", children: p.unanswered?.undelivered ?? 0 }), _jsx("td", { children: duration(p) })] }, `${c.from}>${c.to}:${p.caller}>${p.callee}`)))) })] }) })) : null] }));
+}

package/dist/ui/topology/layout.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The rules for reading a topology: what is shown, what is left out, and where each thing goes.
+ *
+ * Pure functions, document in and plain data out. The local console applies the same rules
+ * (`cli/src/main/resources/console/topology.js`), and both are tested against every fixture in
+ * `console/package/fixtures/topology/`, so the two consoles cannot disagree about a rule without one
+ * suite failing. Browser-safe: nothing here imports a Node module or the server entry point.
+ */
+export interface Handled {
+    ok?: number;
+    refused?: number;
+    failed?: number;
+}
+export interface Unanswered {
+    timedOut?: number;
+    undelivered?: number;
+}
+export interface Pair {
+    caller: string;
+    callee: string;
+    handled?: Handled;
+    unanswered?: Unanswered;
+    durationMillis?: {
+        p50: number;
+        p99: number;
+        max: number;
+        bucketed?: boolean;
+    };
+    streaming?: boolean;
+}
+export interface Node {
+    id: string;
+    kind: string;
+    layer: number;
+    platform: boolean;
+    handlers: {
+        name: string;
+        type: string;
+        streaming?: boolean | null;
+    }[];
+}
+export interface Declared {
+    from: string;
+    to: string;
+    kind: string;
+}
+export interface Call {
+    from: string;
+    to: string;
+    pairs: Pair[];
+}
+export interface Window {
+    seconds: number;
+    since: string;
+}
+export interface Document {
+    nodes?: Node[];
+    declared?: Declared[];
+    calls?: Call[];
+    window?: Window;
+}
+export interface Through {
+    component: string;
+    relation: "reads" | "read-by" | "calls" | "called-by";
+    kind?: string;
+    handled?: number;
+    unanswered?: number;
+}
+export interface PlacedNode extends Node {
+    through: Through[];
+    column: number;
+    row: number;
+    label: string;
+}
+export interface View {
+    nodes: PlacedNode[];
+    declared: Declared[];
+    calls: Call[];
+    hiddenPlatform: number;
+}
+export interface Options {
+    showPlatform?: boolean;
+    kinds?: string[] | null;
+    focus?: string | null;
+}
+/** The handled and the unanswered calls, each added up: two numbers, never one. */
+export declare function totals(pairs: Pair[] | undefined): {
+    handled: number;
+    unanswered: number;
+};
+/** A failure or a call nothing answered marks a call; refusals alone never do. */
+export declare function edgeMark(pairs: Pair[] | undefined): "warning" | null;
+/** From 1 to 5: one step for each power of ten of the handled calls. */
+export declare function weight(pairs: Pair[] | undefined): number;
+/** The sentence wherever observed calls are shown: how far back they reach. */
+export declare function observedLine(window: Window | undefined, now: number, timeZone?: string): string;
+/** What a node is called on the page. */
+export declare function label(node: Pick<Node, "id" | "kind">): string;
+/**
+ * Which local service a node opens. In the installation's console no service is local, so `services`
+ * is empty and an external service is never a link; the rule is shared so the fixtures hold both.
+ */
+export declare function linkFor(node: Pick<Node, "id" | "kind">, services: string[]): {
+    service: string | null;
+    note: string | null;
+};
+/**
+ * What to draw, given what the reader asked to see: platform folding first, then kinds, then focus,
+ * so focusing never brings back what the reader left out.
+ */
+export declare function view(doc: Document, options?: Options): View;
+/** What a picture says, for a reader who cannot see it. */
+export declare function describe(shown: View): string;

package/dist/ui/topology/layout.js

@@ -0,0 +1,177 @@
+/**
+ * The rules for reading a topology: what is shown, what is left out, and where each thing goes.
+ *
+ * Pure functions, document in and plain data out. The local console applies the same rules
+ * (`cli/src/main/resources/console/topology.js`), and both are tested against every fixture in
+ * `console/package/fixtures/topology/`, so the two consoles cannot disagree about a rule without one
+ * suite failing. Browser-safe: nothing here imports a Node module or the server entry point.
+ */
+/** The handled and the unanswered calls, each added up: two numbers, never one. */
+export function totals(pairs) {
+    const sum = { handled: 0, unanswered: 0 };
+    for (const pair of pairs ?? []) {
+        const h = pair.handled ?? {};
+        const u = pair.unanswered ?? {};
+        sum.handled += (h.ok ?? 0) + (h.refused ?? 0) + (h.failed ?? 0);
+        sum.unanswered += (u.timedOut ?? 0) + (u.undelivered ?? 0);
+    }
+    return sum;
+}
+/** A failure or a call nothing answered marks a call; refusals alone never do. */
+export function edgeMark(pairs) {
+    for (const pair of pairs ?? []) {
+        const h = pair.handled ?? {};
+        const u = pair.unanswered ?? {};
+        if ((h.failed ?? 0) > 0)
+            return "warning";
+        if ((u.timedOut ?? 0) + (u.undelivered ?? 0) > 0)
+            return "warning";
+    }
+    return null;
+}
+/** From 1 to 5: one step for each power of ten of the handled calls. */
+export function weight(pairs) {
+    const handled = totals(pairs).handled;
+    return 1 + Math.min(4, Math.floor(Math.log10(Math.max(1, handled))));
+}
+/** The sentence wherever observed calls are shown: how far back they reach. */
+export function observedLine(window, now, timeZone) {
+    const seconds = window?.seconds ?? 0;
+    const since = window ? Date.parse(window.since) : NaN;
+    const sinceStart = Number.isFinite(since) && since > now - seconds * 1000;
+    const from = sinceStart ? ` (since ${clock(since, timeZone)} when the service started)` : "";
+    return `Calls observed in the last ${inWords(seconds)}${from}. Calls not made in that time are not shown.`;
+}
+function inWords(seconds) {
+    const count = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+    if (seconds >= 3600 && seconds % 3600 === 0)
+        return count(seconds / 3600, "hour", "hours");
+    if (seconds >= 60 && seconds % 60 === 0)
+        return count(seconds / 60, "minute", "minutes");
+    return count(seconds, "second", "seconds");
+}
+function clock(millis, timeZone) {
+    return new Intl.DateTimeFormat("en-GB", { hour: "2-digit", minute: "2-digit", hour12: false, timeZone }).format(new Date(millis));
+}
+/** What a node is called on the page. */
+export function label(node) {
+    if (node.kind === "UnknownCaller")
+        return "unknown caller";
+    if (node.id === "service:(other)")
+        return "other services";
+    if (node.kind === "ExternalService")
+        return node.id.slice("service:".length).split("/").pop() ?? node.id;
+    if (node.kind === "Topic")
+        return node.id.slice("topic:".length);
+    if (node.kind === "ExternalComponent")
+        return node.id.slice("external:".length);
+    if (node.kind === "Endpoint")
+        return node.id.slice("endpoint:".length);
+    return node.id;
+}
+/**
+ * Which local service a node opens. In the installation's console no service is local, so `services`
+ * is empty and an external service is never a link; the rule is shared so the fixtures hold both.
+ */
+export function linkFor(node, services) {
+    if (node.kind !== "ExternalService")
+        return { service: null, note: null };
+    if (node.id === "service:(other)")
+        return { service: null, note: "other services" };
+    const name = label(node);
+    const matches = services.filter((s) => s === name);
+    return matches.length === 1 ? { service: name, note: null } : { service: null, note: "not running here" };
+}
+function compare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function edgeOrder(a, b) {
+    return compare(a.from, b.from) || compare(a.to, b.to) || compare(a.kind ?? "", b.kind ?? "");
+}
+function throughOrder(a, b) {
+    return compare(a.component, b.component) || compare(a.relation, b.relation);
+}
+function fold(nodes, declared, calls) {
+    const hidden = new Set(nodes.filter((n) => n.platform).map((n) => n.id));
+    const through = new Map();
+    const note = (visible, entry) => {
+        if (!through.has(visible))
+            through.set(visible, []);
+        through.get(visible).push(entry);
+    };
+    for (const edge of declared) {
+        if (hidden.has(edge.from) && !hidden.has(edge.to))
+            note(edge.to, { component: edge.from, relation: "reads", kind: edge.kind });
+        else if (!hidden.has(edge.from) && hidden.has(edge.to))
+            note(edge.from, { component: edge.to, relation: "read-by", kind: edge.kind });
+    }
+    for (const call of calls) {
+        const counts = totals(call.pairs);
+        if (!hidden.has(call.from) && hidden.has(call.to))
+            note(call.from, { component: call.to, relation: "calls", ...counts });
+        else if (hidden.has(call.from) && !hidden.has(call.to))
+            note(call.to, { component: call.from, relation: "called-by", ...counts });
+    }
+    const visible = (e) => !hidden.has(e.from) && !hidden.has(e.to);
+    return {
+        nodes: nodes.filter((n) => !hidden.has(n.id)).map((n) => ({ ...n, through: [...(through.get(n.id) ?? [])].sort(throughOrder) })),
+        declared: declared.filter(visible),
+        calls: calls.filter(visible),
+        hidden: hidden.size,
+    };
+}
+function within(nodes, declared, calls) {
+    const ids = new Set(nodes.map((n) => n.id));
+    const both = (e) => ids.has(e.from) && ids.has(e.to);
+    return { nodes, declared: declared.filter(both), calls: calls.filter(both) };
+}
+function place(nodes) {
+    const layers = [...new Set(nodes.map((n) => n.layer))].sort((a, b) => a - b);
+    const rows = new Map();
+    return [...nodes]
+        .sort((a, b) => a.layer - b.layer || compare(a.id, b.id))
+        .map((node) => {
+        const column = layers.indexOf(node.layer);
+        const row = rows.get(column) ?? 0;
+        rows.set(column, row + 1);
+        return { ...node, column, row };
+    });
+}
+/**
+ * What to draw, given what the reader asked to see: platform folding first, then kinds, then focus,
+ * so focusing never brings back what the reader left out.
+ */
+export function view(doc, options) {
+    const asked = { showPlatform: false, kinds: null, focus: null, ...(options ?? {}) };
+    const all = (doc.nodes ?? []).map((n) => ({ ...n, through: [] }));
+    const folded = asked.showPlatform
+        ? { nodes: all, declared: doc.declared ?? [], calls: doc.calls ?? [], hidden: 0 }
+        : fold(all, doc.declared ?? [], doc.calls ?? []);
+    const kinds = asked.kinds ? within(folded.nodes.filter((n) => asked.kinds.includes(n.kind)), folded.declared, folded.calls) : folded;
+    let focused = kinds;
+    if (asked.focus && kinds.nodes.some((n) => n.id === asked.focus)) {
+        const near = new Set([asked.focus]);
+        for (const e of [...kinds.declared, ...kinds.calls]) {
+            if (e.from === asked.focus)
+                near.add(e.to);
+            if (e.to === asked.focus)
+                near.add(e.from);
+        }
+        focused = within(kinds.nodes.filter((n) => near.has(n.id)), kinds.declared, kinds.calls);
+    }
+    return {
+        nodes: place(focused.nodes).map((n) => ({ ...n, label: label(n) })),
+        declared: [...focused.declared].sort(edgeOrder),
+        calls: [...focused.calls].sort(edgeOrder),
+        hiddenPlatform: folded.hidden,
+    };
+}
+/** What a picture says, for a reader who cannot see it. */
+export function describe(shown) {
+    const count = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+    return [
+        count(shown.nodes.length, "component", "components"),
+        count(shown.declared.length, "declared connection", "declared connections"),
+        count(shown.calls.length, "observed call", "observed calls"),
+    ].join(", ");
+}