tickmarkr 1.80.0 → 1.83.0

package/dist/tui/cockpit/capture.d.ts

@@ -1,5 +1,6 @@
 import { type ReactNode } from "react";
 import { type DemoCaptures } from "./demo.js";
+import { type RunInteractionState, type RunKeyProjection } from "./keys.js";
 export type CockpitName = "run" | "setup";
 export type CockpitRenderer = "frame" | "plain";
 export type RendererCaptureOptions = {
@@ -21,6 +22,8 @@ export type CaptureCockpitOptions = {
     readonly interactive?: boolean;
     readonly colour?: boolean;
     readonly ci?: boolean;
+    readonly runInteraction?: RunInteractionState;
+    readonly runKeyProjection?: RunKeyProjection;
     readonly captures?: DemoCaptures;
     readonly plainRenderer?: (cockpit: CockpitName, binaryVersion: string, captures: DemoCaptures) => string;
     readonly frameRenderer?: FrameRenderer;
@@ -40,6 +43,98 @@ export declare const WIDTH_BAND_CASES: readonly [{
     readonly columns: 140;
 }];
 export declare const HEIGHT_TIER_BOUNDARIES: readonly [14, 18, 24, 40];
+export declare const COCKPIT_CONTRACT_DOMAIN: {
+    readonly columns: {
+        readonly minimum: 40;
+        readonly maximum: 220;
+    };
+    readonly rows: {
+        readonly minimum: 14;
+        readonly maximum: 50;
+    };
+};
+/**
+ * What the contract's artwork draws for the rail: a 15-cell content band, then
+ * one blank gutter cell, then the divider at cell 16. Both numbers are measured
+ * from the approved frames in the design contract, and the rail span the plan
+ * allocates is the same 15.
+ */
+export declare const COCKPIT_SIDEBAR_CONTENT_COLUMNS = 15;
+export declare const COCKPIT_SIDEBAR_GUTTER_COLUMNS = 1;
+/** Content plus gutter — the cells before the divider. */
+export declare const COCKPIT_SIDEBAR_COLUMNS: number;
+/**
+ * Where the paint puts the frame's own region boundaries, read off the bytes.
+ * The contract's artwork draws a region edge as a glyph — a full-width rule
+ * between row bands, a vertical between the rail and the body — so a region
+ * that moved or that overlaps its neighbour is visible here as a boundary in
+ * the wrong place, at unchanged outer dimensions.
+ */
+export type CockpitFrameBoundaries = {
+    /** The paint is exactly `rows` lines of exactly `columns` cells. */
+    readonly grid: boolean;
+    /** Rows drawn as a full-width horizontal rule, in order. */
+    readonly ruleRows: readonly number[];
+    /** Columns carrying a vertical boundary inside the body band, in order. */
+    readonly dividerColumns: readonly number[];
+    /** Every contiguous vertical boundary span the paint draws in the body. */
+    readonly dividerSpans: readonly CockpitBoundarySpan[];
+    /** Rows carrying an advertised key label, in order. */
+    readonly keyRows: readonly number[];
+};
+export type CockpitBoundarySpan = {
+    readonly column: number;
+    readonly row: number;
+    readonly rows: number;
+};
+export type CockpitFrameContractInspection = {
+    readonly tiles: boolean;
+    /** The boundary geometry `tiles` is decided from. */
+    readonly boundaries: CockpitFrameBoundaries;
+    readonly withinWidth: boolean;
+    readonly headerCount: number;
+    readonly markGlyphCount: number;
+    readonly keybarContained: boolean;
+    /** Cells the rail's content band occupies; 0 where the plan draws no rail. */
+    readonly sidebarContentColumns: number;
+    /** Blank cells between that band and the divider; 0 where there is no rail. */
+    readonly sidebarGutterColumns: number;
+    /** Focus markers inside the navigation zone alone — never the whole frame. */
+    readonly sidebarFocusMarkers: number;
+    /** Selection markers inside the active list zone alone. */
+    readonly listSelectionMarkers: number;
+};
+/**
+ * The mark's alphabet: the block range minus the glyphs the approved artwork
+ * itself draws — the sparkline's eighth-block ramp (▁▂▃▄▅▆▇█) and the meter's
+ * shades (░▒▓). Subtracting them is what lets the scan run over the whole frame
+ * rather than over a header band a renderer could redefine, which is the point:
+ * a mark reintroduced anywhere is found.
+ */
+export declare const COCKPIT_MARK_ALPHABET = "[\u2580\u2589-\u2590\u2594-\u259F]";
+/** Where the paint drew the header signature, in cells rather than in bytes. */
+export type HeaderSignatureHit = {
+    readonly row: number;
+    readonly column: number;
+    readonly text: string;
+};
+/**
+ * Every header signature in a painted frame, at whatever indentation it was
+ * drawn. The inspector counts these and the falsification lever plants one, so
+ * neither can hold a private idea of what a header looks like.
+ */
+export declare function findHeaderSignatures(lines: readonly string[]): HeaderSignatureHit[];
+/**
+ * Inspect emitted terminal bytes without re-planning their geometry. This is
+ * deliberately renderer-agnostic: the sweep and the production capture path
+ * can judge the same paint, and a future renderer cannot move this target by
+ * changing its own plan. The one thing it does take from the plan is where the
+ * zones are, because "one zone holds focus" is a statement about zones and
+ * cannot be counted as a frame-wide glyph total.
+ */
+export declare function inspectCockpitFrameContract(output: string, columns: number, rows: number): CockpitFrameContractInspection;
+/** What the contract's artwork draws at one size — the sweep's expectation. */
+export declare function cockpitFrameContractExpectation(columns: number, rows: number): Omit<CockpitFrameContractInspection, "listSelectionMarkers" | "boundaries">;
 export type GoldenFrameCase = {
     readonly id: string;
     readonly fixture: string;
@@ -51,6 +146,14 @@ export type GoldenFrameCase = {
     readonly colour: boolean;
     readonly ci: boolean;
 };
+/** The surfaces whose rendered appearance this redesign moved. */
+export declare const RETIRED_RENDERED_COCKPITS: readonly CockpitName[];
+/**
+ * A golden case is RETIRED when its cockpit's rendered appearance moved and
+ * the case is a rendered one. Retirement keeps the superseded bytes committed
+ * and the case in the shipped manifest — only regeneration skips it (OBS-207).
+ */
+export declare const isRetiredGoldenFrame: (golden: GoldenFrameCase) => boolean;
 export declare const GOLDEN_FRAME_CASES: readonly GoldenFrameCase[];
 export type ColourFrameCase = {
     readonly id: "healthy-colour" | "healthy-no-colour" | "warning-failure-colour";
@@ -62,7 +165,9 @@ export type ColourFrameCase = {
 };
 /**
  * The colour corpus has a deliberately separate manifest from the layout
- * corpus. Layout cases stay colourless; these cases alone exercise real ink.
+ * corpus. Layout cases stay colourless; these cases alone exercise real ink,
+ * and their committed bytes are RETIRED superseded evidence: the ink oracles
+ * render each case fresh and judge it.
  */
 export declare const COLOUR_FRAME_CASES: readonly [{
     readonly id: "healthy-colour";
@@ -86,6 +191,7 @@ export declare const COLOUR_FRAME_CASES: readonly [{
     readonly rows: 24;
     readonly colour: true;
 }];
+export declare function defaultPlainRenderer(cockpit: CockpitName, binaryVersion: string, captures: DemoCaptures, columns?: number, runInteraction?: RunInteractionState, runKeyProjection?: RunKeyProjection): string;
 /**
  * Capture exactly the bytes Ink writes for one static paint. Debug mode is
  * deliberate: it exposes the complete frame rather than terminal patch

package/dist/tui/cockpit/capture.js

@@ -9,17 +9,259 @@ import { GLYPHS } from "../../brand.js";
 import { version } from "../../cli/commands/version.js";
 import { KEYBAR_KEYS } from "./components.js";
 import { loadDemoCaptures } from "./demo.js";
-import { resolveCockpitLayout, } from "./layout.js";
-import { deriveRunCockpitData, RunCockpitFrame, } from "./run-cockpit.js";
+import { planFrame, RAIL_COLUMNS, resolveCockpitLayout, } from "./layout.js";
+import { deriveRunCockpitData, deriveRunViewRows, RunCockpitFrame, } from "./run-cockpit.js";
 import { deriveSetupCockpitData, SetupCockpitFrame, } from "./setup-cockpit.js";
+import { formatKeybarEntries, initialRunInteractionState, projectRunKeyEntries, } from "./keys.js";
+import { cellWidth } from "./width.js";
 export const WIDTH_BAND_CASES = [
     { arrangement: "stacked", columns: 80 },
     { arrangement: "folded-keys", columns: 100 },
     { arrangement: "three-column", columns: 140 },
 ];
 export const HEIGHT_TIER_BOUNDARIES = [14, 18, 24, 40];
+export const COCKPIT_CONTRACT_DOMAIN = {
+    columns: { minimum: 40, maximum: 220 },
+    rows: { minimum: 14, maximum: 50 },
+};
+/**
+ * What the contract's artwork draws for the rail: a 15-cell content band, then
+ * one blank gutter cell, then the divider at cell 16. Both numbers are measured
+ * from the approved frames in the design contract, and the rail span the plan
+ * allocates is the same 15.
+ */
+export const COCKPIT_SIDEBAR_CONTENT_COLUMNS = RAIL_COLUMNS;
+export const COCKPIT_SIDEBAR_GUTTER_COLUMNS = 1;
+/** Content plus gutter — the cells before the divider. */
+export const COCKPIT_SIDEBAR_COLUMNS = COCKPIT_SIDEBAR_CONTENT_COLUMNS + COCKPIT_SIDEBAR_GUTTER_COLUMNS;
+const CAPTURE_ANSI = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+/**
+ * The mark's alphabet: the block range minus the glyphs the approved artwork
+ * itself draws — the sparkline's eighth-block ramp (▁▂▃▄▅▆▇█) and the meter's
+ * shades (░▒▓). Subtracting them is what lets the scan run over the whole frame
+ * rather than over a header band a renderer could redefine, which is the point:
+ * a mark reintroduced anywhere is found.
+ */
+export const COCKPIT_MARK_ALPHABET = "[▀▉-▐▔-▟]";
+const COCKPIT_MARK_GLYPHS = new RegExp(COCKPIT_MARK_ALPHABET, "gu");
+const KEYBAR_LABEL = /(?:↑↓ Move|⏎ Open|← Back|Tab (?:Setup|Watch)|1–5 View|f Follow|\? Help|q Quit)/u;
+/**
+ * The header signature: the brand word standing on its own, wherever the paint
+ * puts it. Indentation is not part of the signature — the artwork insets the
+ * word on wide frames, so anchoring at column zero would read a valid header as
+ * absent and an indented duplicate as absent too. A path or branch reference
+ * that merely contains the word (`tickmarkr/run-…`) is not a header, so both
+ * sides are bounded against the characters such a reference joins with.
+ */
+const HEADER_SIGNATURE = /(?<![\w/-])tickmarkr(?![\w/-])/gu;
+const FOCUS_MARKER = "❯";
+/** The glyphs the contract's artwork draws a region edge with. */
+const RULE_GLYPH = "─";
+const DIVIDER_GLYPH = "│";
+const sameSequence = (observed, planned) => observed.length === planned.length
+    && observed.every((value, index) => value === planned[index]);
+const sameBoundarySpans = (observed, planned) => observed.length === planned.length
+    && observed.every((span, index) => {
+        const expected = planned[index];
+        return expected !== undefined
+            && span.column === expected.column
+            && span.row === expected.row
+            && span.rows === expected.rows;
+    });
+/** Display-cell offsets carrying `glyph`, never code-point offsets. */
+function glyphColumns(line, glyph) {
+    return [...line.matchAll(new RegExp(glyph, "gu"))].map((match) => cellWidth(line.slice(0, match.index)));
+}
+/** Contiguous row spans for every column carrying the vertical boundary. */
+function verticalBoundarySpans(lines, region) {
+    if (!region)
+        return [];
+    const rowsByColumn = new Map();
+    for (let row = region.row; row < region.row + region.rows; row += 1) {
+        for (const column of glyphColumns(lines[row] ?? "", DIVIDER_GLYPH)) {
+            const observedRows = rowsByColumn.get(column) ?? [];
+            observedRows.push(row);
+            rowsByColumn.set(column, observedRows);
+        }
+    }
+    return [...rowsByColumn.entries()]
+        .sort(([left], [right]) => left - right)
+        .flatMap(([column, observedRows]) => {
+        const spans = [];
+        let start = observedRows[0];
+        let previous = start;
+        for (const row of observedRows.slice(1)) {
+            if (previous !== undefined && row === previous + 1) {
+                previous = row;
+                continue;
+            }
+            if (start !== undefined && previous !== undefined) {
+                spans.push({ column, row: start, rows: previous - start + 1 });
+            }
+            start = row;
+            previous = row;
+        }
+        if (start !== undefined && previous !== undefined) {
+            spans.push({ column, row: start, rows: previous - start + 1 });
+        }
+        return spans;
+    });
+}
+/**
+ * Every header signature in a painted frame, at whatever indentation it was
+ * drawn. The inspector counts these and the falsification lever plants one, so
+ * neither can hold a private idea of what a header looks like.
+ */
+export function findHeaderSignatures(lines) {
+    return lines.flatMap((line, row) => [...line.matchAll(HEADER_SIGNATURE)].map((match) => ({
+        row,
+        // Cells, not code units — the same count the frame's cells are read in.
+        column: cellWidth(line.slice(0, match.index)),
+        text: match[0],
+    })));
+}
+/** The cells of one row inside a planned region's column span. */
+function regionSlice(line, region) {
+    const cells = [...line];
+    return cells.slice(region.column, region.column + region.columns).join("");
+}
+function markersIn(lines, region) {
+    if (!region)
+        return 0;
+    let markers = 0;
+    for (let row = region.row; row < region.row + region.rows; row += 1) {
+        const line = lines[row];
+        if (line === undefined)
+            continue;
+        markers += [...regionSlice(line, region)]
+            .filter((glyph) => glyph === FOCUS_MARKER).length;
+    }
+    return markers;
+}
+/**
+ * Inspect emitted terminal bytes without re-planning their geometry. This is
+ * deliberately renderer-agnostic: the sweep and the production capture path
+ * can judge the same paint, and a future renderer cannot move this target by
+ * changing its own plan. The one thing it does take from the plan is where the
+ * zones are, because "one zone holds focus" is a statement about zones and
+ * cannot be counted as a frame-wide glyph total.
+ */
+export function inspectCockpitFrameContract(output, columns, rows) {
+    const visible = output.replace(CAPTURE_ANSI, "").replace(/\n$/u, "");
+    const lines = visible.split("\n");
+    const widths = lines.map((line) => cellWidth(line));
+    const headerCount = findHeaderSignatures(lines).length;
+    const markGlyphCount = lines.reduce((count, line) => count + [...line.matchAll(COCKPIT_MARK_GLYPHS)].length, 0);
+    const keyRows = lines.flatMap((line, row) => KEYBAR_LABEL.test(line) ? [row] : []);
+    const plan = planFrame({ columns, rows });
+    const regions = plan.kind === "frame" ? plan.regions : [];
+    const region = (id) => regions.find((candidate) => candidate.id === id);
+    const body = region("body");
+    const rail = region("rail");
+    const navigation = rail ?? region("strip");
+    const keybar = region("keybar");
+    // The boundaries the paint actually draws. A full-width rule is a row band's
+    // edge; a vertical inside the body band is the rail's edge. Both are read
+    // from the bytes and neither is inferred from whichever row happens to be
+    // painted last.
+    const ruleRows = lines.flatMap((line, row) => {
+        const cells = [...line];
+        return cells.length > 0 && cellWidth(line) === columns
+            && cells.every((glyph) => glyph === RULE_GLYPH)
+            ? [row]
+            : [];
+    });
+    const dividerSpans = verticalBoundarySpans(lines, body);
+    const dividerColumns = [...new Set(dividerSpans.map(({ column }) => column))];
+    const boundaries = {
+        grid: lines.length === rows
+            && lines.every((line) => cellWidth(line) === columns),
+        ruleRows,
+        dividerColumns,
+        dividerSpans,
+        keyRows,
+    };
+    // What the plan says those boundaries must be: a rule at each rule band, and
+    // — only where the artwork draws a rail — one vertical, at the divider cell
+    // the rail's content band and its gutter end at.
+    const plannedRuleRows = regions
+        .filter((candidate) => candidate.id === "rule" || candidate.id === "rule2")
+        .map((candidate) => candidate.row)
+        .sort((left, right) => left - right);
+    const plannedDividerColumns = rail ? [COCKPIT_SIDEBAR_COLUMNS] : [];
+    const plannedDividerSpans = rail && body
+        ? [{
+                column: COCKPIT_SIDEBAR_COLUMNS,
+                row: body.row,
+                rows: body.rows,
+            }]
+        : [];
+    // The rail's content band and its gutter, read off the paint: the divider
+    // column the body rows agree on, less the blank cells every one of them
+    // leaves in front of it.
+    let sidebarContentColumns = 0;
+    let sidebarGutterColumns = 0;
+    if (rail && body) {
+        const railRows = lines
+            .slice(body.row, body.row + body.rows)
+            .filter((line) => line.includes("│"));
+        const dividers = new Set(railRows.map((line) => cellWidth(line.slice(0, line.indexOf("│")))));
+        if (railRows.length === body.rows && dividers.size === 1) {
+            const divider = [...dividers][0];
+            let gutter = 0;
+            while (gutter < divider
+                && railRows.every((line) => ([...line][divider - gutter - 1] ?? " ") === " ")) {
+                gutter += 1;
+            }
+            sidebarContentColumns = divider - gutter;
+            sidebarGutterColumns = gutter;
+        }
+    }
+    return {
+        // Tiling is region ownership, not a filled rectangle: the paint covers the
+        // whole grid AND every boundary sits at the offset the plan gives it, so a
+        // region moved or overlapped at unchanged outer dimensions is a violation.
+        tiles: boundaries.grid
+            && sameSequence(ruleRows, plannedRuleRows)
+            && sameSequence(dividerColumns, plannedDividerColumns)
+            && sameBoundarySpans(dividerSpans, plannedDividerSpans),
+        boundaries,
+        withinWidth: widths.every((width) => width <= columns),
+        headerCount,
+        markGlyphCount,
+        // Contained means inside the keybar band the plan allocated — never
+        // "wherever the last painted row turned out to be", which accepts a keybar
+        // one row above its own blank band.
+        keybarContained: keybar !== undefined
+            && keyRows.length > 0
+            && keyRows.every((row) => row === keybar.row),
+        sidebarContentColumns,
+        sidebarGutterColumns,
+        sidebarFocusMarkers: markersIn(lines, navigation),
+        listSelectionMarkers: markersIn(lines, body),
+    };
+}
+/** What the contract's artwork draws at one size — the sweep's expectation. */
+export function cockpitFrameContractExpectation(columns, rows) {
+    const plan = planFrame({ columns, rows });
+    const sidebar = plan.kind === "frame" && plan.band === "sidebar";
+    return {
+        tiles: true,
+        withinWidth: true,
+        headerCount: 1,
+        markGlyphCount: 0,
+        keybarContained: true,
+        sidebarContentColumns: sidebar ? COCKPIT_SIDEBAR_CONTENT_COLUMNS : 0,
+        sidebarGutterColumns: sidebar ? COCKPIT_SIDEBAR_GUTTER_COLUMNS : 0,
+        sidebarFocusMarkers: 1,
+    };
+}
 const fixtureName = (cockpit, id, columns, rows) => `${cockpit}.${id}.${columns}x${rows}.txt`;
-const goldenCasesFor = (cockpit) => [
+/**
+ * The rendered corpus of one surface: a frame at each contracted width band and
+ * each height tier boundary, plus the colourless variant.
+ */
+const renderedCasesFor = (cockpit) => [
     ...WIDTH_BAND_CASES.map(({ arrangement, columns }) => ({
         id: `${cockpit}-width-${arrangement}`,
         fixture: fixtureName(cockpit, `width-${arrangement}`, columns, 24),
@@ -53,6 +295,9 @@ const goldenCasesFor = (cockpit) => [
         colour: false,
         ci: false,
     },
+];
+/** The two machine surfaces: output this redesign did not move. */
+const machineCasesFor = (cockpit) => [
     {
         id: `${cockpit}-non-tty`,
         fixture: fixtureName(cockpit, "non-tty", 140, 24),
@@ -76,13 +321,29 @@ const goldenCasesFor = (cockpit) => [
         ci: true,
     },
 ];
+/** The surfaces whose rendered appearance this redesign moved. */
+export const RETIRED_RENDERED_COCKPITS = ["run"];
+/**
+ * A golden case is RETIRED when its cockpit's rendered appearance moved and
+ * the case is a rendered one. Retirement keeps the superseded bytes committed
+ * and the case in the shipped manifest — only regeneration skips it (OBS-207).
+ */
+export const isRetiredGoldenFrame = (golden) => RETIRED_RENDERED_COCKPITS.includes(golden.cockpit)
+    && golden.interactive
+    && !golden.ci;
+const goldenCasesFor = (cockpit) => [
+    ...renderedCasesFor(cockpit),
+    ...machineCasesFor(cockpit),
+];
 export const GOLDEN_FRAME_CASES = [
     ...goldenCasesFor("run"),
     ...goldenCasesFor("setup"),
 ];
 /**
  * The colour corpus has a deliberately separate manifest from the layout
- * corpus. Layout cases stay colourless; these cases alone exercise real ink.
+ * corpus. Layout cases stay colourless; these cases alone exercise real ink,
+ * and their committed bytes are RETIRED superseded evidence: the ink oracles
+ * render each case fresh and judge it.
  */
 export const COLOUR_FRAME_CASES = [
     {
@@ -137,15 +398,20 @@ function stateGlyph(state) {
         return GLYPHS.attention;
     return GLYPHS.neutral;
 }
-function defaultPlainRenderer(cockpit, binaryVersion, captures) {
+export function defaultPlainRenderer(cockpit, binaryVersion, captures, columns = 140, runInteraction = initialRunInteractionState(), runKeyProjection = projectRunKeyEntries) {
     const derived = derivedData(cockpit, binaryVersion, captures);
     if (derived.cockpit === "run") {
         const data = derived.data;
+        const rowIds = deriveRunViewRows(data, runInteraction.activeView, runInteraction.filterQuery).map((row) => row.id);
         return [
             `tickmarkr v${binaryVersion}`,
             `${data.runId} ${data.status} ${data.elapsed}`,
             ...data.statusItems.map((item) => `${stateGlyph(item.state)} ${item.text}`),
-            `keys ${KEYBAR_KEYS.run.map((item) => `${item.key} ${item.label}`).join(" · ")}`,
+            `keys ${formatKeybarEntries(runKeyProjection({
+                interaction: runInteraction,
+                columns,
+                rowIds,
+            }))}`,
             "",
         ].join("\n");
     }
@@ -161,12 +427,14 @@ function defaultPlainRenderer(cockpit, binaryVersion, captures) {
         "",
     ].join("\n");
 }
-function frameNode(derived, columns, rows) {
+function frameNode(derived, columns, rows, runInteraction = initialRunInteractionState(), runKeyProjection = projectRunKeyEntries) {
     if (derived.cockpit === "run") {
         return createElement(RunCockpitFrame, {
             data: derived.data,
             columns,
             rows,
+            interaction: runInteraction,
+            keyProjection: runKeyProjection,
         });
     }
     return createElement(SetupCockpitFrame, {
@@ -239,7 +507,9 @@ export async function captureCockpitOutput(options) {
         ?? process.env.NO_COLOR === undefined;
     const ci = options.ci ?? process.env.CI === "true";
     const captures = options.captures ?? loadDemoCaptures();
-    const plain = () => (options.plainRenderer ?? defaultPlainRenderer)(options.cockpit, options.binaryVersion, captures);
+    const plain = () => options.plainRenderer === undefined
+        ? defaultPlainRenderer(options.cockpit, options.binaryVersion, captures, columns, options.runInteraction, options.runKeyProjection)
+        : options.plainRenderer(options.cockpit, options.binaryVersion, captures);
     const layout = resolveCockpitLayout(columns, rows);
     if (!interactive || options.output.isTTY !== true || ci || layout.renderer === "plain") {
         const plainOutput = plain();
@@ -247,7 +517,7 @@ export async function captureCockpitOutput(options) {
         return { renderer: "plain", output: plainOutput };
     }
     const derived = derivedData(options.cockpit, options.binaryVersion, captures);
-    const frameOutput = await (options.frameRenderer ?? captureRendererOutput)(frameNode(derived, columns, rows), { columns, rows, colour });
+    const frameOutput = await (options.frameRenderer ?? captureRendererOutput)(frameNode(derived, columns, rows, options.runInteraction, options.runKeyProjection), { columns, rows, colour });
     if (frameOutput.length === 0) {
         const plainOutput = plain();
         options.output.write(plainOutput);
@@ -261,6 +531,10 @@ export async function regenerateGoldenFrames(binaryVersion) {
     const captures = loadDemoCaptures();
     const regenerated = [];
     for (const golden of GOLDEN_FRAME_CASES) {
+        // Regenerating a retired case would produce the new appearance, and
+        // byte-comparing would force the re-stamp the contract forbids.
+        if (isRetiredGoldenFrame(golden))
+            continue;
         const output = new PassThrough();
         output.isTTY = golden.interactive;
         output.columns = golden.columns;
@@ -291,7 +565,10 @@ export async function regenerateGoldenFrames(binaryVersion) {
     return regenerated;
 }
 export function findGoldenFrameMismatches(regenerated, committed) {
-    const expected = new Set(regenerated.map((frame) => frame.fixture));
+    // Membership is judged against the whole shipped manifest, retired cases
+    // included: a retired fixture is claimed, so only its bytes are exempt.
+    // Anything committed that no case claims is still named.
+    const expected = new Set(GOLDEN_FRAME_CASES.map((frame) => frame.fixture));
     return [
         ...regenerated.flatMap((frame) => committed.get(frame.fixture) === frame.output ? [] : [frame.fixture]),
         ...[...committed.keys()].filter((fixture) => !expected.has(fixture)),

package/dist/tui/cockpit/components.d.ts

@@ -13,96 +13,16 @@ export type BandAllocationOptions = {
 };
 export type TextEmphasis = keyof typeof TEXT_EMPHASIS_TOKENS;
 export type ComponentState = "active" | "inactive" | "pass" | "fail" | "warn" | "neutral";
-export type KeybarSurface = "run" | "setup";
 export type KeybarItem = {
     readonly key: string;
     readonly label: string;
 };
 export declare const KEYBAR_KEYS: {
-    readonly run: readonly [{
-        readonly key: "↑↓";
-        readonly label: "Move";
-    }, {
-        readonly key: "⏎";
-        readonly label: "Open";
-    }, {
-        readonly key: "←";
-        readonly label: "Back";
-    }, {
-        readonly key: "Tab";
-        readonly label: "Panel";
-    }, {
-        readonly key: "?";
-        readonly label: "Help";
-    }, {
-        readonly key: "q";
-        readonly label: "Quit";
-    }, {
-        readonly key: "f";
-        readonly label: "Follow";
-    }, {
-        readonly key: "/";
-        readonly label: "Filter";
-    }];
-    readonly setup: readonly [{
-        readonly key: "↑↓";
-        readonly label: "Move";
-    }, {
-        readonly key: "⏎";
-        readonly label: "Next";
-    }, {
-        readonly key: "←";
-        readonly label: "Back";
-    }, {
-        readonly key: "Tab";
-        readonly label: "Panel";
-    }, {
-        readonly key: "?";
-        readonly label: "Help";
-    }, {
-        readonly key: "q";
-        readonly label: "Quit";
-    }, {
-        readonly key: "␣";
-        readonly label: "Toggle";
-    }, {
-        readonly key: "a";
-        readonly label: "All";
-    }, {
-        readonly key: "r";
-        readonly label: "Re-probe";
-    }, {
-        readonly key: "s";
-        readonly label: "Save";
-    }, {
-        readonly key: "n";
-        readonly label: "Next";
-    }, {
-        readonly key: "p";
-        readonly label: "Prev";
-    }];
-    readonly setupAdditional: readonly [{
-        readonly key: "␣";
-        readonly label: "Toggle";
-    }, {
-        readonly key: "a";
-        readonly label: "All";
-    }, {
-        readonly key: "r";
-        readonly label: "Re-probe";
-    }, {
-        readonly key: "s";
-        readonly label: "Save";
-    }, {
-        readonly key: "n";
-        readonly label: "Next";
-    }, {
-        readonly key: "p";
-        readonly label: "Prev";
-    }];
+    readonly setup: readonly import("./keys.js").KeybarEntry[];
+    readonly setupAdditional: import("./keys.js").KeybarEntry[];
 };
 export type JournalRow = {
-    readonly id?: string;
+    readonly id: string;
     readonly time: string;
     readonly state: ComponentState;
     readonly text: string;
@@ -159,8 +79,15 @@ export declare function ProgressMeter({ value, width, }: {
     value: number;
     width?: number;
 }): ReactElement;
-export declare function Keybar({ surface, width, }: {
-    surface: KeybarSurface;
+/**
+ * Wrap a projected roster without losing a byte. Unlike prose wrapping, these
+ * rows are exact consecutive slices: stripping continuation markers and
+ * joining the slices reconstructs the registry projection byte for byte.
+ */
+export declare function keyRosterLines(entries: readonly KeybarItem[], columns: number): readonly string[];
+/** The lossless, width-safe rendering of one projected key roster. */
+export declare function KeyRoster({ entries, width, }: {
+    entries: readonly KeybarItem[];
     width: number;
 }): ReactElement;
 export type StatusStripItem = {
@@ -171,9 +98,11 @@ export declare function StatusStrip({ items, width, }: {
     items: readonly StatusStripItem[];
     width: number;
 }): ReactElement;
-export declare function JournalRowPanel({ rows, width, focused, title, }: {
+export declare function JournalRowPanel({ rows, width, focused, title, selection, }: {
     rows: readonly JournalRow[];
     width?: number | string;
     focused?: boolean;
     title?: string;
+    /** Index of the row the pointer marks; undefined draws no pointer. */
+    selection?: number;
 }): ReactElement;