@vincentt-xr/cli 0.1.5 → 0.2.0

package/dist/preview/api.d.ts

@@ -0,0 +1,84 @@
+import type { ResolvedConfig } from "../shared/config.js";
+import { BackendError } from "../lib/backend.js";
+/** The mint response. Its key set is the cross-repo pin (contract table 2.11). */
+export interface MintedPreview {
+    sessionId: string;
+    /** Full `https://<label>.<apex>` — SERVER-COMPUTED, never assembled here. */
+    url: string;
+    /** `wss://…/tunnel` — server-computed for the same reason. */
+    edgeUrl: string;
+    /** An opaque JWS. Never parsed, never printed. */
+    grant: string;
+    heartbeatSec: number;
+    /** ISO8601, the hard max. */
+    expiresAt: string;
+}
+export interface HeartbeatResult {
+    state: string;
+    viewerCount: number;
+    expiresAt: string;
+}
+/** The mint rate limit (§2.16). `retryAfterSec` comes from the header, never the body. */
+export declare class PreviewRateLimitedError extends BackendError {
+    readonly retryAfterSec: number;
+    constructor(retryAfterSec: number);
+}
+/** A preview already exists for this working tree and the mint lost the race. */
+export declare class PreviewConflictError extends BackendError {
+    constructor(message: string);
+}
+/**
+ * The session is gone — `preview_session_ended`, the CLI's terminal branch.
+ *
+ * `endReason` is the DISCRIMINATOR the five ending screens need, and it is
+ * `undefined` against the API as built: every terminal cause answers this route
+ * with a byte-identical body (`{"code":"preview_session_ended","message":"this
+ * preview has ended"}`), verified against the running stack with an `abandoned`
+ * row and an `expired` row. QA-F3-09 names that exact condition — "if the wire
+ * carried one undifferentiated 'ended', the designer's spec would be unbuildable
+ * and that is a fork, not a test failure".
+ *
+ * It is read here anyway so the client half is complete and the seam is one
+ * field: the day the API adds `endReason` to the 410 body, the abandoned and
+ * hard-max screens separate with no further client change.
+ */
+export declare class PreviewEndedError extends BackendError {
+    readonly endReason?: string | undefined;
+    constructor(message: string, endReason?: string | undefined);
+}
+/**
+ * workingTreeKey is sha256 of the REALPATH of the project root, and the raw path
+ * NEVER leaves the machine: it is a filesystem-layout disclosure with zero
+ * platform value, and the one legitimate use (the one-session-per-tree supersede
+ * rule) only needs a stable opaque key.
+ *
+ * realpath, not the literal argument, so `.`, a relative path and a symlink into
+ * the same tree all produce ONE key — otherwise "one preview per working tree"
+ * would be one preview per spelling of the path.
+ */
+export declare function workingTreeKey(projectRoot: string): Promise<string>;
+/**
+ * parseRetryAfter reads the 429's header. The BODY carries no discriminator for
+ * which of the two mint limits fired — the header answers "how long", never
+ * "which" — so a missing or unparseable value falls back to a minute rather than
+ * inventing a number the copy would then state as fact.
+ */
+export declare function parseRetryAfter(raw: string | null): number;
+/** POST /projects/{id}/preview-sessions — mint. */
+export declare function mintPreviewSession(cfg: ResolvedConfig, projectId: string, key: string, fetchImpl?: typeof fetch): Promise<MintedPreview>;
+/**
+ * parseMint refuses a response missing any field the CLI depends on rather than
+ * defaulting one. A defaulted `url` is a blank line where the creator expects the
+ * link; a defaulted `edgeUrl` is a tunnel dialed at the wrong host. f2's
+ * `parseProjectView` dropped its legacy tolerance for the same reason.
+ */
+export declare function parseMint(raw: unknown): MintedPreview;
+/** POST /preview-sessions/{id}/heartbeat — keepalive AND re-authorization. */
+export declare function heartbeatPreviewSession(cfg: ResolvedConfig, sessionId: string, fetchImpl?: typeof fetch): Promise<HeartbeatResult>;
+/**
+ * DELETE /preview-sessions/{id} — end. Best-effort and never throws: the creator
+ * has already pressed Ctrl-C, and the session's own expiry reaps it regardless.
+ * Surfacing a teardown failure would turn a successful stop into an error the
+ * creator cannot act on.
+ */
+export declare function endPreviewSession(cfg: ResolvedConfig, sessionId: string, fetchImpl?: typeof fetch): Promise<void>;

package/dist/preview/api.js

@@ -0,0 +1,174 @@
+// The preview-session calls against the Go API. Isolated from the runner so the
+// wire shapes are unit-testable and the runner stays orchestration.
+//
+// Every field name here is pinned to `api/internal/httpapi/handlers_preview.go`.
+// A CLI that guessed at them would pass its own suite while breaking the seam,
+// which is the f1 `redirect`/`redirect_uri` failure.
+import { createHash } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { BackendError, ProjectUnreachableError } from "../lib/backend.js";
+/** The mint rate limit (§2.16). `retryAfterSec` comes from the header, never the body. */
+export class PreviewRateLimitedError extends BackendError {
+    retryAfterSec;
+    constructor(retryAfterSec) {
+        super("Too many previews started recently.", 429);
+        this.retryAfterSec = retryAfterSec;
+        this.name = "PreviewRateLimitedError";
+    }
+}
+/** A preview already exists for this working tree and the mint lost the race. */
+export class PreviewConflictError extends BackendError {
+    constructor(message) {
+        super(message, 409);
+        this.name = "PreviewConflictError";
+    }
+}
+/**
+ * The session is gone — `preview_session_ended`, the CLI's terminal branch.
+ *
+ * `endReason` is the DISCRIMINATOR the five ending screens need, and it is
+ * `undefined` against the API as built: every terminal cause answers this route
+ * with a byte-identical body (`{"code":"preview_session_ended","message":"this
+ * preview has ended"}`), verified against the running stack with an `abandoned`
+ * row and an `expired` row. QA-F3-09 names that exact condition — "if the wire
+ * carried one undifferentiated 'ended', the designer's spec would be unbuildable
+ * and that is a fork, not a test failure".
+ *
+ * It is read here anyway so the client half is complete and the seam is one
+ * field: the day the API adds `endReason` to the 410 body, the abandoned and
+ * hard-max screens separate with no further client change.
+ */
+export class PreviewEndedError extends BackendError {
+    endReason;
+    constructor(message, endReason) {
+        super(message, 410);
+        this.endReason = endReason;
+        this.name = "PreviewEndedError";
+    }
+}
+/**
+ * workingTreeKey is sha256 of the REALPATH of the project root, and the raw path
+ * NEVER leaves the machine: it is a filesystem-layout disclosure with zero
+ * platform value, and the one legitimate use (the one-session-per-tree supersede
+ * rule) only needs a stable opaque key.
+ *
+ * realpath, not the literal argument, so `.`, a relative path and a symlink into
+ * the same tree all produce ONE key — otherwise "one preview per working tree"
+ * would be one preview per spelling of the path.
+ */
+export async function workingTreeKey(projectRoot) {
+    let resolved;
+    try {
+        resolved = await realpath(projectRoot);
+    }
+    catch {
+        resolved = projectRoot;
+    }
+    return createHash("sha256").update(resolved).digest("hex");
+}
+async function errorBody(res) {
+    try {
+        const parsed = await res.json();
+        return typeof parsed === "object" && parsed !== null ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function authHeaders(cfg) {
+    return { authorization: `Bearer ${cfg.pat}`, "content-type": "application/json" };
+}
+/**
+ * parseRetryAfter reads the 429's header. The BODY carries no discriminator for
+ * which of the two mint limits fired — the header answers "how long", never
+ * "which" — so a missing or unparseable value falls back to a minute rather than
+ * inventing a number the copy would then state as fact.
+ */
+export function parseRetryAfter(raw) {
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? Math.ceil(n) : 60;
+}
+/** POST /projects/{id}/preview-sessions — mint. */
+export async function mintPreviewSession(cfg, projectId, key, fetchImpl = fetch) {
+    const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/preview-sessions`, {
+        method: "POST",
+        headers: authHeaders(cfg),
+        body: JSON.stringify({ workingTreeKey: key }),
+    });
+    if (res.status === 429) {
+        throw new PreviewRateLimitedError(parseRetryAfter(res.headers.get("retry-after")));
+    }
+    if (!res.ok) {
+        const body = await errorBody(res);
+        if (res.status === 404) {
+            throw new ProjectUnreachableError(body.message ?? "This project is not available to you.");
+        }
+        if (res.status === 409) {
+            throw new PreviewConflictError(body.message ?? "a preview is already running for this folder");
+        }
+        throw new BackendError(body.message ?? `could not start a preview (${res.status})`, res.status);
+    }
+    return parseMint(await res.json());
+}
+/**
+ * parseMint refuses a response missing any field the CLI depends on rather than
+ * defaulting one. A defaulted `url` is a blank line where the creator expects the
+ * link; a defaulted `edgeUrl` is a tunnel dialed at the wrong host. f2's
+ * `parseProjectView` dropped its legacy tolerance for the same reason.
+ */
+export function parseMint(raw) {
+    const p = (raw ?? {});
+    const str = (k) => typeof p[k] === "string" ? p[k] : undefined;
+    const sessionId = str("sessionId");
+    const url = str("url");
+    const edgeUrl = str("edgeUrl");
+    const grant = str("grant");
+    const expiresAt = str("expiresAt");
+    const heartbeatSec = typeof p.heartbeatSec === "number" ? p.heartbeatSec : undefined;
+    if (!sessionId ||
+        !url ||
+        !edgeUrl ||
+        !grant ||
+        !expiresAt ||
+        heartbeatSec === undefined) {
+        throw new BackendError("mint preview: response is missing required fields");
+    }
+    return { sessionId, url, edgeUrl, grant, heartbeatSec, expiresAt };
+}
+/** POST /preview-sessions/{id}/heartbeat — keepalive AND re-authorization. */
+export async function heartbeatPreviewSession(cfg, sessionId, fetchImpl = fetch) {
+    const res = await fetchImpl(`${cfg.apiUrl}/preview-sessions/${encodeURIComponent(sessionId)}/heartbeat`, { method: "POST", headers: authHeaders(cfg) });
+    if (!res.ok) {
+        const body = await errorBody(res);
+        if (res.status === 410) {
+            throw new PreviewEndedError(body.message ?? "this preview has ended", typeof body.endReason === "string" ? body.endReason : undefined);
+        }
+        if (res.status === 404 || res.status === 403) {
+            throw new ProjectUnreachableError(body.message ?? "This project is not available to you.");
+        }
+        throw new BackendError(body.message ?? `heartbeat failed (${res.status})`, res.status);
+    }
+    const b = (await res.json());
+    return {
+        state: b.state ?? "live",
+        viewerCount: b.viewerCount ?? 0,
+        expiresAt: b.expiresAt ?? "",
+    };
+}
+/**
+ * DELETE /preview-sessions/{id} — end. Best-effort and never throws: the creator
+ * has already pressed Ctrl-C, and the session's own expiry reaps it regardless.
+ * Surfacing a teardown failure would turn a successful stop into an error the
+ * creator cannot act on.
+ */
+export async function endPreviewSession(cfg, sessionId, fetchImpl = fetch) {
+    try {
+        await fetchImpl(`${cfg.apiUrl}/preview-sessions/${encodeURIComponent(sessionId)}`, {
+            method: "DELETE",
+            headers: { authorization: `Bearer ${cfg.pat}` },
+        });
+    }
+    catch {
+        // See above.
+    }
+}

package/dist/preview/command.d.ts

@@ -0,0 +1,96 @@
+import type { DiagEvent } from "@vincentt-xr/harness/events";
+import type { TunnelState, UAClass } from "@vincentt-xr/harness/tunnel";
+import type { EventTags } from "../relay/server.js";
+import type { PreviewEndReason } from "./runner.js";
+export interface PreviewUiDeps {
+    print: (line: string) => void;
+    now: () => number;
+    /** The forward target, named identically in the start block and the 502. */
+    targetUrl: string;
+    color: boolean;
+    /** Filter the stream to one tester (`--tester`) — one tab, across refreshes. */
+    filterTester?: string;
+    /** Filter the stream to one connection (`--viewer`). */
+    filterViewer?: string;
+}
+/**
+ * PreviewUi owns every line after the mint. It is a pure sink — it takes events
+ * and prints strings — so the whole transcript is assertable without a terminal,
+ * a socket or a phone.
+ */
+export declare class PreviewUi {
+    private readonly deps;
+    private readonly roster;
+    private readonly perf;
+    private readonly p;
+    private readonly startedAt;
+    /** L18 prints ONCE PER STRETCH of failure, not once per occurrence. */
+    private originDown;
+    /** L21's soft warning prints once per preview. */
+    private egressWarned;
+    /** L20b's 30-minute warning prints once. */
+    private hardMaxWarned;
+    private tunnelState;
+    private ended;
+    constructor(deps: PreviewUiDeps);
+    get connectedCount(): number;
+    get totalConnections(): number;
+    private line;
+    private lines;
+    /**
+     * A CONNECTION arrived. Records it and prints NOTHING: one tab opens two
+     * connections under HTTP/1.1, so a line here is what made one QR scan read as
+     * two records. The creator's line comes from `testerSeen`.
+     *
+     * The tunnel client fires onViewer on EVERY OPEN frame, not once per
+     * connection, so the roster's idempotence is what keeps a phone that requests
+     * forty assets from announcing itself forty times.
+     */
+    viewerSeen(label: string, uaClass: UAClass): void;
+    viewerGone(label: string): void;
+    /**
+     * The harness introduced itself on a connection. This is what prints the
+     * creator's connect line — not `viewerSeen`, which now stays silent because
+     * one tab opens two connections and a line per connection is the defect this
+     * fixes.
+     */
+    testerSeen(label: string, tester: string): void;
+    /**
+     * The tester cap, once per refused session. It names the number so the creator
+     * can act on it, and says "this connection" rather than naming a tester —
+     * because there is none, and inventing one is the silent merge this design
+     * exists to prevent.
+     */
+    capReached(): void;
+    events(evs: DiagEvent[], tags: EventTags, opts?: {
+        attribute?: boolean;
+    }): void;
+    /**
+     * L18. Recovery is announced by the 200 that follows and by NOTHING else — a
+     * "recovered!" line would be a second interruption for a non-event.
+     */
+    originError(): void;
+    originRecovered(): void;
+    /** L19. The tunnel's own state is what the creator's network failure looks like. */
+    tunnel(state: TunnelState): void;
+    /** L21's soft threshold. Printed once; the preview KEEPS SERVING. */
+    egressSoft(): void;
+    /**
+     * L20b's 30-minute warning. `expiresAt` is the minted ceiling and a heartbeat
+     * never extends it, so this fires exactly once per preview.
+     */
+    checkHardMax(expiresAt: string): void;
+    /** The creator's own Ctrl-C. Prints the stopping line, then the ending. */
+    stopping(): void;
+    stopped(): void;
+    /** Every ending the creator did NOT cause. One first line per cause. */
+    endedBy(reason: PreviewEndReason, orgName: string): void;
+    following(label: string): void;
+    notFollowing(label: string): void;
+    notFollowingTester(tester: string): void;
+    /** Live testers — what `stopping`/`stopped` should be counting. */
+    get testerCount(): number;
+}
+export declare function endingLines(reason: PreviewEndReason, orgName: string): string[];
+/** `21:04` — what a creator plans a demo around, in their own local time. */
+export declare function clockTime(d: Date): string;

package/dist/preview/command.js

@@ -0,0 +1,276 @@
+// `vincentt preview` — the first LONG-RUNNING command in the product.
+//
+// It has three zones and a creator scrolling back should be able to find each by
+// shape alone:
+//   1. a START BLOCK that is quiet and complete (everything needed to hand off,
+//      above the fold);
+//   2. a STREAM that is uniform, prefixed and scannable, NEVER redrawn;
+//   3. ONE ending line plus one remedy.
+//
+// The stream is never repainted, there is no spinner and no status bar. The
+// reasons are cumulative: Ctrl-C stays clean, scrollback stays true, piping to a
+// file works, and an agent reading the transcript gets the same information a
+// human does.
+import * as copy from "./copy.js";
+import { PerfThrottle, palette, renderEvent, uaLabel } from "./stream.js";
+import { ViewerRoster } from "./viewers.js";
+import { MAX_TESTERS } from "../relay/testers.js";
+/**
+ * PreviewUi owns every line after the mint. It is a pure sink — it takes events
+ * and prints strings — so the whole transcript is assertable without a terminal,
+ * a socket or a phone.
+ */
+export class PreviewUi {
+    deps;
+    roster = new ViewerRoster();
+    perf;
+    p;
+    startedAt;
+    /** L18 prints ONCE PER STRETCH of failure, not once per occurrence. */
+    originDown = false;
+    /** L21's soft warning prints once per preview. */
+    egressWarned = false;
+    /** L20b's 30-minute warning prints once. */
+    hardMaxWarned = false;
+    tunnelState = "connecting";
+    ended = false;
+    constructor(deps) {
+        this.deps = deps;
+        this.p = palette(deps.color);
+        this.perf = new PerfThrottle();
+        this.startedAt = deps.now();
+    }
+    get connectedCount() {
+        return this.roster.size;
+    }
+    get totalConnections() {
+        return this.roster.totalConnections;
+    }
+    line(s) {
+        this.deps.print(s);
+    }
+    lines(ls) {
+        for (const l of ls)
+            this.deps.print(l);
+    }
+    // ---- viewers --------------------------------------------------------------
+    /**
+     * A CONNECTION arrived. Records it and prints NOTHING: one tab opens two
+     * connections under HTTP/1.1, so a line here is what made one QR scan read as
+     * two records. The creator's line comes from `testerSeen`.
+     *
+     * The tunnel client fires onViewer on EVERY OPEN frame, not once per
+     * connection, so the roster's idempotence is what keeps a phone that requests
+     * forty assets from announcing itself forty times.
+     */
+    viewerSeen(label, uaClass) {
+        const out = this.roster.connect(label, uaClass, this.deps.now());
+        if (out.connect === undefined)
+            return;
+        this.line("");
+        this.line(`  ${out.connect}`);
+        if (out.advisory)
+            this.lines(out.advisory.map((l) => `  ${l}`));
+        this.line("");
+    }
+    viewerGone(label) {
+        const out = this.roster.disconnect(label, this.deps.now());
+        this.perf.forget(label);
+        if (out.connect === undefined)
+            return;
+        this.line("");
+        this.line(`  ${out.connect}`);
+        this.line("");
+    }
+    /**
+     * The harness introduced itself on a connection. This is what prints the
+     * creator's connect line — not `viewerSeen`, which now stays silent because
+     * one tab opens two connections and a line per connection is the defect this
+     * fixes.
+     */
+    testerSeen(label, tester) {
+        const out = this.roster.attribute(label, tester);
+        if (out.connect === undefined)
+            return;
+        this.line("");
+        this.line(`  ${out.connect}`);
+        if (out.advisory)
+            this.lines(out.advisory.map((l) => `  ${l}`));
+        if (out.roster) {
+            this.line("");
+            this.lines(out.roster.map((l) => `  ${l}`));
+        }
+        this.line("");
+    }
+    /**
+     * The tester cap, once per refused session. It names the number so the creator
+     * can act on it, and says "this connection" rather than naming a tester —
+     * because there is none, and inventing one is the silent merge this design
+     * exists to prevent.
+     */
+    capReached() {
+        this.line("");
+        this.line(`  ! Tester limit reached (${MAX_TESTERS}). This connection's events are not attributed.`);
+        this.line("");
+    }
+    // ---- the stream -----------------------------------------------------------
+    events(evs, tags, opts = {}) {
+        const { tester, viewer } = tags;
+        // The first batch carrying a tester is ALSO the harness introducing itself,
+        // so attribution rides the event path rather than a second callback. There
+        // is no earlier signal available: the tester does not exist until the app
+        // mounts and flushes.
+        //
+        // A FOLLOWER passes attribute:false. It is polling a relay owned by another
+        // process and never saw the connections, so its roster is empty and it must
+        // not narrate arrivals it cannot actually observe.
+        if (opts.attribute !== false && tester !== undefined && viewer !== undefined) {
+            this.testerSeen(viewer, tester);
+        }
+        // Column one is the TESTER — the coordinate that still resolves by the time
+        // anyone reads the transcript. An event with no tester cannot be attributed,
+        // and rather than invent a placeholder that would read as a real one, it is
+        // dropped from the TERMINAL. The relay still holds it, so `vincentt logs`
+        // and the MCP tools see it.
+        if (tester === undefined)
+            return;
+        if (this.deps.filterTester !== undefined && tester !== this.deps.filterTester)
+            return;
+        if (this.deps.filterViewer !== undefined &&
+            (viewer === undefined || viewer !== this.deps.filterViewer)) {
+            return;
+        }
+        for (const e of evs) {
+            // Throttled per CONNECTION, not per tester: a tab's two sockets report
+            // independently, and gating on the tester would drop one of them.
+            const throttleKey = viewer ?? tester;
+            if (e.kind === "trace" && !this.perf.allow(throttleKey, this.deps.now()))
+                continue;
+            const rendered = renderEvent(tester, e, this.p);
+            if (rendered !== null)
+                this.line(`  ${rendered}`);
+        }
+    }
+    // ---- advisories -----------------------------------------------------------
+    /**
+     * L18. Recovery is announced by the 200 that follows and by NOTHING else — a
+     * "recovered!" line would be a second interruption for a non-event.
+     */
+    originError() {
+        if (this.originDown)
+            return;
+        this.originDown = true;
+        this.line("");
+        this.lines(copy.originDown(this.deps.targetUrl).map((l) => `  ${l}`));
+    }
+    originRecovered() {
+        this.originDown = false;
+    }
+    /** L19. The tunnel's own state is what the creator's network failure looks like. */
+    tunnel(state) {
+        const prev = this.tunnelState;
+        this.tunnelState = state;
+        if (state === "reconnecting" && prev === "live") {
+            this.line("");
+            this.lines(copy.reconnecting().map((l) => `  ${l}`));
+            return;
+        }
+        if (state === "live" && prev === "reconnecting") {
+            this.lines(copy.reconnected().map((l) => `  ${l}`));
+        }
+    }
+    /** L21's soft threshold. Printed once; the preview KEEPS SERVING. */
+    egressSoft() {
+        if (this.egressWarned)
+            return;
+        this.egressWarned = true;
+        this.line("");
+        this.lines(copy.egressSoft().map((l) => `  ${l}`));
+    }
+    /**
+     * L20b's 30-minute warning. `expiresAt` is the minted ceiling and a heartbeat
+     * never extends it, so this fires exactly once per preview.
+     */
+    checkHardMax(expiresAt) {
+        if (this.hardMaxWarned)
+            return;
+        const at = Date.parse(expiresAt);
+        if (!Number.isFinite(at))
+            return;
+        const msLeft = at - this.deps.now();
+        if (msLeft > 30 * 60_000 || msLeft <= 0)
+            return;
+        this.hardMaxWarned = true;
+        const minutes = Math.max(1, Math.round(msLeft / 60_000));
+        this.line("");
+        this.lines(copy.hardMaxWarning(clockTime(new Date(at)), minutes).map((l) => `  ${l}`));
+    }
+    // ---- endings --------------------------------------------------------------
+    /** The creator's own Ctrl-C. Prints the stopping line, then the ending. */
+    stopping() {
+        this.line("");
+        this.line(copy.stopping(this.roster.size));
+    }
+    stopped() {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.lines(copy.stopped(this.deps.now() - this.startedAt, this.roster.totalConnections));
+        this.line("");
+    }
+    /** Every ending the creator did NOT cause. One first line per cause. */
+    endedBy(reason, orgName) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.lines(endingLines(reason, orgName));
+    }
+    // ---- --viewer -------------------------------------------------------------
+    following(label) {
+        const v = this.roster.get(label);
+        this.lines(copy.followingBlock(label, v ? uaLabel(v.uaClass) : ""));
+    }
+    notFollowing(label) {
+        this.line(`  ${this.roster.notFollowing(label)}`);
+    }
+    notFollowingTester(tester) {
+        this.line(`  ${this.roster.notFollowingTester(tester)}`);
+    }
+    /** Live testers — what `stopping`/`stopped` should be counting. */
+    get testerCount() {
+        return this.roster.testerCount;
+    }
+}
+export function endingLines(reason, orgName) {
+    switch (reason) {
+        case "hard_max":
+            return copy.hardMaxReached();
+        case "superseded":
+            return copy.supersededLoser();
+        case "grace_exhausted":
+            return copy.graceExhausted();
+        case "grace_cap":
+            return copy.graceCapReached();
+        case "abandoned":
+            return copy.endedAbandoned();
+        case "authz_revoked":
+            return copy.endedUnreachable(orgName);
+        case "authz_unconfirmed":
+            return copy.endedUnconfirmed();
+        case "egress_cap":
+            return copy.egressHard();
+        case "stopped":
+            // The LOCAL stop. Reached only when this process held the timer and the
+            // counter, so the stats are real. A 410 carrying endReason "stopped"
+            // maps to `stopped_elsewhere`, NOT here — see copy.stoppedElsewhere.
+            return copy.stopped(0, 0);
+        case "stopped_elsewhere":
+            return copy.stoppedElsewhere();
+        case "disconnected":
+            return copy.endedDisconnected();
+    }
+}
+/** `21:04` — what a creator plans a demo around, in their own local time. */
+export function clockTime(d) {
+    return `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+}