@timurproko/a1 0.1.8-dev.3b54f21 → 0.1.8-dev.402

package/dist/{src/foundation/ui-apps → ui/apps}/contracts.d.ts

@@ -1,4 +1,4 @@
-import type { PaneInputResult, PaneMouseEvent, PaneRect, UiTheme } from "../ui-components/index.js";
+import type { PaneInputResult, PaneMouseEvent, PaneRect, RenderCacheContract, UiTheme } from "../components/index.js";
 export interface AppSize {
     readonly width: number;
     readonly height: number;
@@ -27,6 +27,8 @@ export interface AppHostServices {
 }
 export interface UiApp {
     readonly id: string;
+    /** Optional declared revisions used by the host's shared frame cache. */
+    readonly renderCache?: RenderCacheContract;
     render(rect: PaneRect, host: AppHostServices): readonly string[];
     onInput?(data: string, host: AppHostServices): PaneInputResult;
     onMouse?(event: PaneMouseEvent, host: AppHostServices): PaneInputResult;
@@ -39,4 +41,24 @@ export interface AppRegistration {
     readonly route: string;
     create(): UiApp;
 }
+/** A neutral owned-app surface mounted by a surrounding presentation runtime. */
+export interface UiRouteSurface {
+    readonly id: string;
+    /** Renders exactly `height` rows of at most `width` columns. */
+    render(width: number, height: number): readonly string[];
+    /** True when the key was consumed; false leaves it to the surrounding shell. */
+    handleInput(data: string): boolean;
+    /** Mouse report in surface-local coordinates. True when consumed. */
+    handleMouse(event: PaneMouseEvent): boolean;
+    isClosed(): boolean;
+    close(): void;
+    onRenderRequested(listener: () => void): void;
+    /** The surface asks to leave A1 entirely, not merely to close itself. */
+    onExitRequested(listener: () => void): void;
+}
+/** Route lookup seam shared by owned apps and any presentation runtime hosting them. */
+export interface UiRouteHost {
+    claims(route: string): boolean;
+    open(route: string): UiRouteSurface | null;
+}
 export declare function assertAppRegistration(registration: AppRegistration): void;

package/dist/{src/foundation/ui-apps → ui/apps}/host.d.ts

@@ -1,4 +1,4 @@
-import { type PaneInputResult, type PaneMouseEvent, type UiTheme } from "../ui-components/index.js";
+import { type PaneInputResult, type PaneMouseEvent, type UiTheme } from "../components/index.js";
 import type { AppSize, UiApp } from "./contracts.js";
 import type { UiAppRegistry } from "./registry.js";
 export interface AppHostSurface {

package/dist/{src/foundation/ui-apps → ui/apps}/host.js

@@ -1,5 +1,5 @@
-import { FrameCache, finalizeFrame, } from "../ui-components/index.js";
-// The interrupt byte, written as an escape: as a raw byte it is invisible to
+import { FrameCache, finalizeFrame, } from "../components/index.js";
+// Invariant: the interrupt byte is written as an escape: as a raw byte it is invisible to
 // every text tool, and this constant had already been emptied by one.
 const INTERRUPT = "";
 /** How long the first interrupt of the chord stays armed. */
@@ -14,8 +14,9 @@ export class UiAppHost {
     #surface;
     #closeOnInterrupt;
     #theme;
-    /** When the first interrupt of a chord was seen, or null when disarmed. */
+    // Invariant: the first interrupt timestamp is null whenever the chord is disarmed.
     #interruptArmedAt = null;
+    #renderedInterruptArmed;
     #cache = new FrameCache();
     #app = null;
     constructor(options) {
@@ -58,7 +59,11 @@ export class UiAppHost {
         }
         const size = this.#surface.size();
         const rect = { width: Math.max(0, size.width), height: Math.max(0, size.height) };
-        const lines = this.#guard(() => finalizeFrame(app.render(rect, this.#services()), rect, app.id));
+        const interruptArmed = this.interruptArmed;
+        if (this.#renderedInterruptArmed !== interruptArmed)
+            this.#cache.invalidate();
+        this.#renderedInterruptArmed = interruptArmed;
+        const lines = this.#guard(() => this.#cache.render(app, rect, () => finalizeFrame(app.render(rect, this.#services()), rect, app.id)));
         this.#surface.present(lines ?? null);
     }
     handleInput(data) {
@@ -86,11 +91,7 @@ export class UiAppHost {
             this.render();
         return result;
     }
-    /**
-     * Two interrupts leave A1, from any screen. One arms the chord and repaints so
-     * the screen can say so; a second within the window exits rather than merely
-     * closing the screen, which is what the chord means everywhere else.
-     */
+    // Protocol: two interrupts within the chord window leave A1 from every screen.
     #interrupt() {
         const now = Date.now();
         const armed = this.#interruptArmedAt;
@@ -101,6 +102,9 @@ export class UiAppHost {
             return { consumed: true, render: true };
         }
         this.#interruptArmedAt = now;
+        // Invariant: host-owned state participates in the app's next frame independently of
+        // the app's own revision contract.
+        this.#cache.invalidate();
         return { consumed: true, render: true };
     }
     get interruptArmed() {
@@ -135,7 +139,7 @@ export class UiAppHost {
             ...(this.#theme === undefined ? {} : { theme: this.#theme }),
         };
     }
-    /** Contains a failure: the app is closed and the surface restored, never left broken. */
+    // Security: an app failure closes its app and restores the surface.
     #guard(work) {
         try {
             return work();

package/dist/{src/foundation/ui-apps → ui/apps}/registry.d.ts

@@ -1,4 +1,5 @@
 import { type AppRegistration } from "./contracts.js";
+/** Registers owned applications under unique routes and unregisters only the matching definition. */
 export declare class UiAppRegistry {
     #private;
     /** Registering a known id replaces its definition rather than adding a second app. */

package/dist/{src/foundation/ui-apps → ui/apps}/registry.js

@@ -1,4 +1,5 @@
 import { assertAppRegistration } from "./contracts.js";
+/** Registers owned applications under unique routes and unregisters only the matching definition. */
 export class UiAppRegistry {
     #byId = new Map();
     /** Registering a known id replaces its definition rather than adding a second app. */

package/dist/{src/foundation/ui-components → ui/components}/dialog-panel.js

@@ -17,9 +17,11 @@ export function renderDialogPanel(state, width, theme) {
         const padded = `${row.label}${" ".repeat(Math.max(0, labelColumn - displayWidth(row.label)))}`;
         const cursor = selected ? "→ " : "  ";
         const raw = `${cursor}${padded}  ${row.value}`;
-        // An unselected label is left unpainted and its value quietened, both lifted
-        // to the accent on the row the cursor is on — as the engine paints its own.
-        const painted = `${theme.fg("accent", cursor)}${selected ? theme.fg("accent", padded) : padded}  ${theme.fg("muted", row.value)}`;
+        // Compatibility: match pinned SettingsList: selected cursor, label, and value all use the
+        // accent role; an unselected label is plain and its value is muted.
+        const painted = selected
+            ? `${theme.fg("accent", cursor)}${theme.fg("accent", padded)}  ${theme.fg("accent", row.value)}`
+            : `${cursor}${padded}  ${theme.fg("muted", row.value)}`;
         return pad(truncateToWidth(painted, width), width, raw);
     });
     const description = state.rows[state.index]?.description ?? "";

package/dist/{src/foundation/ui-components → ui/components}/frame.d.ts

@@ -2,6 +2,7 @@ export interface PaneRect {
     readonly width: number;
     readonly height: number;
 }
+/** Identifies the pane whose bounded frame geometry or rendered rows violated the contract. */
 export declare class FrameContractError extends Error {
     readonly pane: string;
     constructor(pane: string, message: string);

package/dist/{src/foundation/ui-components → ui/components}/frame.js

@@ -1,4 +1,5 @@
 import { displayWidth, truncateToWidth } from "./text.js";
+/** Identifies the pane whose bounded frame geometry or rendered rows violated the contract. */
 export class FrameContractError extends Error {
     pane;
     constructor(pane, message) {

package/dist/{src/foundation/ui-components → ui/components}/index.d.ts

@@ -2,17 +2,24 @@ export * from "./dialog-panel.js";
 export * from "./frame.js";
 export * from "./label.js";
 export * from "./line-input.js";
+export * from "./prompt-input.js";
 export * from "./list-block.js";
 export * from "./list-view.js";
 export * from "./mouse.js";
 export * from "./pane.js";
+export * from "./progress-status.js";
 export * from "./revision.js";
+export * from "./selection-copy.js";
 export * from "./scrollbar.js";
 export * from "./shortcuts.js";
 export * from "./spans.js";
+export * from "./visible-hyperlinks.js";
 export * from "./status-line.js";
+export * from "./submitted-prompt.js";
 export * from "./stepper.js";
+export * from "./transcript-viewport.js";
 export * from "./surface.js";
 export * from "./text.js";
+export * from "./text-selection.js";
 export * from "./theme.js";
 export * from "./value-menu.js";

package/dist/{src/foundation/ui-components → ui/components}/index.js

@@ -2,17 +2,24 @@ export * from "./dialog-panel.js";
 export * from "./frame.js";
 export * from "./label.js";
 export * from "./line-input.js";
+export * from "./prompt-input.js";
 export * from "./list-block.js";
 export * from "./list-view.js";
 export * from "./mouse.js";
 export * from "./pane.js";
+export * from "./progress-status.js";
 export * from "./revision.js";
+export * from "./selection-copy.js";
 export * from "./scrollbar.js";
 export * from "./shortcuts.js";
 export * from "./spans.js";
+export * from "./visible-hyperlinks.js";
 export * from "./status-line.js";
+export * from "./submitted-prompt.js";
 export * from "./stepper.js";
+export * from "./transcript-viewport.js";
 export * from "./surface.js";
 export * from "./text.js";
+export * from "./text-selection.js";
 export * from "./theme.js";
 export * from "./value-menu.js";

package/dist/{src/foundation/ui-components → ui/components}/line-input.d.ts

@@ -1,3 +1,4 @@
+import type { UiTheme } from "./theme.js";
 export type LineInputOutcome = {
     readonly kind: "editing";
 } | {
@@ -47,14 +48,6 @@ export declare class LineInput {
 }
 /** Applies one key to the input and reports whether the caller should commit. */
 export declare function handleLineInputKey(input: LineInput, data: string): LineInputOutcome;
-/**
- * The prompt the reference draws at the head of an input row, in the grey it
- * uses for one (#9AA0A6), painted foreground-only so anything drawn behind the
- * row survives.
- */
-/** A rule drawn in the prompt's own grey, as the reference rules an input row. */
-export declare function promptRule(width: number): string;
-export declare const PROMPT_GLYPH = "\u001B[38;2;154;160;166m\u276F\u001B[39m ";
 /**
  * The caret the reference draws: the cell under it is reversed rather than given
  * a colour of its own, so it reads as a block in whatever theme is in use.
@@ -65,6 +58,7 @@ export interface InputRowOptions {
     readonly placeholder?: string;
     /** Rules above and below, in the prompt's own grey. Default true. */
     readonly ruled?: boolean;
+    readonly theme?: Pick<UiTheme, "fg">;
 }
 export interface InputRow {
     /** The rows to draw, already padded to the width. */

package/dist/{src/foundation/ui-components → ui/components}/line-input.js

@@ -1,4 +1,5 @@
 import { displayWidth, faint, truncateToWidth } from "./text.js";
+import { PromptInput } from "./prompt-input.js";
 const MAX_VALUE_LENGTH = 4_096;
 const GRAPHEMES = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 /** Character class for a word boundary: 0 space, 1 word, 2 anything else. */
@@ -148,7 +149,7 @@ export function handleLineInputKey(input, data) {
         return { kind: "accepted", value: input.value };
     if (data === "\u001b" || data === "\u0003")
         return { kind: "cancelled" };
-    // A word delete is decided before a plain one: on Windows Terminal the raw
+    // Platform: a word delete is decided before a plain one: on Windows Terminal the raw
     // backspace byte IS ctrl+backspace, and the plain branch would swallow it.
     if (data === "\b" || data === "\u001b\u007f" || data === "\u0017") {
         input.deleteWordBefore();
@@ -190,7 +191,7 @@ export function handleLineInputKey(input, data) {
         input.moveCaretToEnd();
         return { kind: "editing" };
     }
-    // Any other escape sequence is a key this input has no answer for - a page
+    // Rationale: any other escape sequence is a key this input has no answer for - a page
     // key, a function key, a chord. It is swallowed rather than typed, because the
     // one thing it certainly is not is text the reader meant to enter.
     if (data.startsWith("\u001b"))
@@ -198,16 +199,6 @@ export function handleLineInputKey(input, data) {
     input.insert(data);
     return { kind: "editing" };
 }
-/**
- * The prompt the reference draws at the head of an input row, in the grey it
- * uses for one (#9AA0A6), painted foreground-only so anything drawn behind the
- * row survives.
- */
-/** A rule drawn in the prompt's own grey, as the reference rules an input row. */
-export function promptRule(width) {
-    return `\u001b[38;2;154;160;166m${"─".repeat(Math.max(0, width))}\u001b[39m`;
-}
-export const PROMPT_GLYPH = `\u001b[38;2;154;160;166m❯\u001b[39m `;
 /**
  * The caret the reference draws: the cell under it is reversed rather than given
  * a colour of its own, so it reads as a block in whatever theme is in use.
@@ -217,29 +208,17 @@ export function caretCell(text) {
 }
 /** The input row as the reference draws one, padded to exactly the width. */
 export function renderInputRow(input, width, options = {}) {
-    const inner = Math.max(0, width - 2);
-    const view = input.view(inner);
+    const presentation = new PromptInput(options.theme);
+    const view = input.view(Math.max(0, width - presentation.geometry(width).prefixWidth));
     const placeholder = options.placeholder ?? "";
     const empty = view.text.length === 0 && placeholder.length > 0;
     const before = view.text.slice(0, view.caretColumn);
     const under = view.text.slice(view.caretColumn, view.caretColumn + 1) || " ";
     const after = view.text.slice(view.caretColumn + 1);
-    // Typed text is left unpainted, the caret reverses its cell, and the
+    // Rationale: typed text is left unpainted, the caret reverses its cell, and the
     // placeholder is quietened by weight rather than by a colour of its own.
     const body = empty
         ? `${caretCell(placeholder.slice(0, 1))}${faint(placeholder.slice(1))}`
         : `${before}${caretCell(under)}${after}`;
-    const plain = empty
-        ? placeholder
-        : `${view.text}${view.caretColumn >= view.text.length ? " " : ""}`;
-    const row = padVisible(truncateToWidth(`${PROMPT_GLYPH}${body}`, width), width, `❯ ${plain}`);
-    if (options.ruled === false)
-        return { lines: [row] };
-    const rule = promptRule(width);
-    return { lines: [rule, row, rule] };
-}
-/** Pads by visible width, so styling escapes do not shift the layout. */
-function padVisible(line, width, raw) {
-    const visible = displayWidth(raw);
-    return visible >= width ? line : line + " ".repeat(width - visible);
+    return { lines: presentation.render(width, () => ({ rows: [body] }), options.ruled) };
 }

package/dist/{src/foundation/ui-components → ui/components}/list-view.d.ts

@@ -1,10 +1,4 @@
 import type { UiTheme } from "./theme.js";
-/**
- * A list of things that each carry a label and a value. It owns where a value
- * starts, how a row reads when it is selected or pointed at, and which part of a
- * row the pointer is on — so a screen decides what a row means and this decides
- * how it looks and where it can be touched.
- */
 /** The part of a row the pointer is over. A label selects; a value acts. */
 export type ListRegion = "label" | "value" | "minus" | "plus";
 /** Columns a stepper's controls occupy on either side of the value. */

package/dist/{src/foundation/ui-components → ui/components}/list-view.js

@@ -6,8 +6,8 @@ export const STEPPER_RESERVE = 2;
  * and with the stepper's columns reserved for every row when any row has one, so
  * a number does not shift its own value out of the column it shares.
  */
-export function valueColumnFor(rows, indent = 4, gap = 2) {
-    const widest = Math.max(0, ...rows.map(row => displayWidth(row.label)));
+export function valueColumnFor(rows, indent = 2, gap = 2) {
+    const widest = Math.min(30, Math.max(0, ...rows.map(row => displayWidth(row.label))));
     const stepper = rows.some(row => row.stepper !== undefined) ? STEPPER_RESERVE : 0;
     return indent + widest + gap + stepper;
 }
@@ -22,14 +22,21 @@ export function renderGroupHeader(title, width, theme) {
  */
 export function renderListRow(row, state, valueColumn, width, theme) {
     const cursor = state.selected ? "→ " : "  ";
-    const leftRaw = `${cursor}  ${row.label}`;
-    const left = `${theme.fg("accent", cursor)}  ${state.selected ? theme.fg("accent", row.label) : theme.plain(row.label)}`;
+    const labelColumn = Math.max(displayWidth(row.label), valueColumn - 4 - (row.stepper === undefined ? 0 : STEPPER_RESERVE));
+    const labelPadded = `${row.label}${" ".repeat(Math.max(0, labelColumn - displayWidth(row.label)))}`;
+    const leftRaw = `${cursor}${labelPadded}`;
+    const left = state.selected
+        ? `${theme.fg("accent", cursor)}${theme.fg("accent", labelPadded)}`
+        : `${cursor}${theme.plain(labelPadded)}`;
     const gap = Math.max(2, valueColumn - displayWidth(leftRaw));
-    // Pointing anywhere on the row is pointing at the item; pointing at the value
-    // is what brightens it. The selection speaks through the label alone.
+    // Compatibility: pinned SettingsList gives the selected label and value the same accent
+    // role. Pointer hover may brighten an unselected value without changing the
+    // keyboard selection.
     const valueHovered = state.hovered && state.region !== "label";
     const stepper = row.stepper !== undefined && valueHovered;
-    const value = valueHovered ? theme.plain(row.value) : theme.fg("muted", row.value);
+    const value = state.selected
+        ? theme.fg("accent", row.value)
+        : valueHovered ? theme.plain(row.value) : theme.fg("muted", row.value);
     const minus = stepper
         ? row.stepper?.lower === true
             ? state.region === "minus" ? theme.plain("- ") : theme.fg("dim", "- ")

package/dist/{src/foundation/ui-components → ui/components}/mouse.d.ts

@@ -13,3 +13,13 @@ export interface ParsedMouseInput {
 }
 /** Extracts SGR mouse reports, leaving any keyboard input untouched. */
 export declare function parseMouseInput(data: string): ParsedMouseInput;
+export interface RoutedMouseInput {
+    /** Input left for the TUI after only claimed reports were removed. */
+    readonly data: string;
+    readonly consumed: boolean;
+}
+/**
+ * Routes every SGR report independently, preserving keyboard bytes and mouse
+ * reports the caller does not claim even when they share one physical chunk.
+ */
+export declare function routeMouseInput(data: string, claim: (event: PaneMouseEvent, report: string) => boolean): RoutedMouseInput;

package/dist/{src/foundation/ui-components → ui/components}/mouse.js

@@ -30,6 +30,30 @@ export function parseMouseInput(data) {
     rest += data.slice(index);
     return { events: Object.freeze(events), rest };
 }
+/**
+ * Routes every SGR report independently, preserving keyboard bytes and mouse
+ * reports the caller does not claim even when they share one physical chunk.
+ */
+export function routeMouseInput(data, claim) {
+    if (!data.includes("\u001b[<"))
+        return { data, consumed: false };
+    let output = "";
+    let index = 0;
+    let consumed = false;
+    // Concurrency: reentrant routing may deliver a report to another component using this parser.
+    const pattern = new RegExp(SGR_PATTERN.source, "g");
+    for (let match = pattern.exec(data); match !== null; match = pattern.exec(data)) {
+        output += data.slice(index, match.index);
+        index = match.index + match[0].length;
+        const event = toEvent(Number.parseInt(match[1] ?? "", 10), Number.parseInt(match[2] ?? "", 10), Number.parseInt(match[3] ?? "", 10), match[4] === "m");
+        if (event !== null && claim(event, match[0]))
+            consumed = true;
+        else
+            output += match[0];
+    }
+    output += data.slice(index);
+    return { data: output, consumed };
+}
 function toEvent(code, column, row, released) {
     if ((code & 64) !== 0) {
         const kind = (code & 1) === 0 ? "wheel-up" : "wheel-down";

package/dist/ui/components/progress-status.d.ts

@@ -0,0 +1,2 @@
+/** Returns spinner-backed status text with A1's canonical three-period marker. */
+export declare function progressStatusText(message: string): string;

package/dist/ui/components/progress-status.js

@@ -0,0 +1,4 @@
+/** Returns spinner-backed status text with A1's canonical three-period marker. */
+export function progressStatusText(message) {
+    return `${message.replace(/(?:…|\.+)$/u, "")}...`;
+}

package/dist/ui/components/prompt-input.d.ts

@@ -0,0 +1,32 @@
+import { type UiTheme } from "./theme.js";
+export declare const PROMPT_GLYPH = "\u276F ";
+export declare const PROMPT_PREFIX_WIDTH = 2;
+export declare function promptRuleText(text: string): string;
+export declare function promptRule(width: number): string;
+export declare function promptArrow(text: string, theme: Pick<UiTheme, "fg">): string;
+export interface PromptInputBody {
+    readonly rows: readonly string[];
+    /** Semantic border fragments retain editor history and scroll annotations. */
+    readonly topRule?: string | undefined;
+    readonly bottomRule?: string | undefined;
+    readonly after?: readonly string[];
+}
+export interface PromptInputMetrics {
+    readonly measure: (text: string) => number;
+    readonly truncate: (text: string, width: number) => string;
+}
+/** Composes shared input chrome around controller-owned body rows without owning editing state. */
+export declare class PromptInput {
+    readonly theme: Pick<UiTheme, "fg">;
+    readonly metrics: PromptInputMetrics;
+    constructor(theme?: Pick<UiTheme, "fg">, metrics?: PromptInputMetrics);
+    styleRule(text: string): string;
+    geometry(width: number, padding?: number): {
+        prefixWidth: number;
+        innerWidth: number;
+        paddingX: number;
+        contentWidth: number;
+        layoutWidth: number;
+    };
+    render(width: number, renderBody: (innerWidth: number) => PromptInputBody, ruled?: boolean, padding?: number): string[];
+}

package/dist/ui/components/prompt-input.js

@@ -0,0 +1,54 @@
+import { displayWidth, truncateToWidth } from "./text.js";
+import { PLAIN_THEME } from "./theme.js";
+export const PROMPT_GLYPH = "❯ ";
+export const PROMPT_PREFIX_WIDTH = 2;
+export function promptRuleText(text) {
+    return `\u001b[38;2;154;160;166m${text}\u001b[39m`;
+}
+export function promptRule(width) {
+    return promptRuleText("─".repeat(Math.max(0, width)));
+}
+export function promptArrow(text, theme) {
+    return theme.fg("muted", text);
+}
+/** Composes shared input chrome around controller-owned body rows without owning editing state. */
+export class PromptInput {
+    theme;
+    metrics;
+    constructor(theme = PLAIN_THEME, metrics = { measure: displayWidth, truncate: truncateToWidth }) {
+        this.theme = theme;
+        this.metrics = metrics;
+    }
+    styleRule(text) { return promptRuleText(text); }
+    geometry(width, padding = 0) {
+        const prefixWidth = Math.min(PROMPT_PREFIX_WIDTH, Math.max(0, width));
+        // Compatibility: editor wrapping needs room for a two-cell grapheme plus its cursor cell.
+        // Lay out against a safe virtual width, then clip only at the shared frame boundary.
+        const innerWidth = Math.max(3 + padding * 2, width - prefixWidth);
+        const paddingX = Math.min(padding, Math.max(0, Math.floor((innerWidth - 1) / 2)));
+        const contentWidth = Math.max(1, innerWidth - paddingX * 2);
+        return { prefixWidth, innerWidth, paddingX, contentWidth, layoutWidth: Math.max(1, contentWidth - (paddingX ? 0 : 1)) };
+    }
+    render(width, renderBody, ruled = true, padding = 0) {
+        if (width <= 0)
+            return [];
+        const { prefixWidth, innerWidth } = this.geometry(width, padding);
+        const body = renderBody(innerWidth);
+        const fit = (row) => {
+            const clipped = this.metrics.truncate(row, width);
+            return clipped + " ".repeat(Math.max(0, width - this.metrics.measure(clipped)));
+        };
+        const rows = body.rows.map((row, index) => fit(`${index === 0
+            ? promptArrow(PROMPT_GLYPH, this.theme)
+            : " ".repeat(prefixWidth)}${row}`));
+        const rule = (fragment) => fragment === undefined
+            ? promptRule(width)
+            : fit(fragment + promptRule(Math.max(0, width - this.metrics.measure(fragment))));
+        return [
+            ...(ruled ? [rule(body.topRule)] : []),
+            ...rows,
+            ...(ruled ? [rule(body.bottomRule)] : []),
+            ...(body.after ?? []).map(row => fit(`${" ".repeat(prefixWidth)}${row}`)),
+        ];
+    }
+}

package/dist/ui/components/prompt-row.d.ts

@@ -0,0 +1,14 @@
+export interface TimestampedPromptRowsInput {
+    readonly width: number;
+    readonly sourceTimestamp: number | Date;
+    readonly render: (contentWidth: number) => readonly string[];
+    /** Styles the reserved suffix while keeping policy independent of a vendor theme. */
+    readonly decorateSuffix?: (text: string, firstRow: boolean) => string;
+    readonly minimumWidth?: number;
+}
+export declare function formatPromptTimestamp(source: number | Date): string | null;
+/**
+ * Reserves timestamp columns before wrapping, so the clock never overwrites
+ * prompt content. At narrow widths the same renderer is used without a clock.
+ */
+export declare function composeTimestampedPromptRows(input: TimestampedPromptRowsInput): readonly string[];

package/dist/ui/components/prompt-row.js

@@ -0,0 +1,20 @@
+import { overlaySpan } from "./spans.js";
+export function formatPromptTimestamp(source) {
+    const date = source instanceof Date ? source : new Date(source);
+    if (Number.isNaN(date.getTime()))
+        return null;
+    return `${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}`;
+}
+/**
+ * Reserves timestamp columns before wrapping, so the clock never overwrites
+ * prompt content. At narrow widths the same renderer is used without a clock.
+ */
+export function composeTimestampedPromptRows(input) {
+    const timestamp = formatPromptTimestamp(input.sourceTimestamp);
+    if (timestamp === null || input.width < (input.minimumWidth ?? 20))
+        return input.render(input.width);
+    const suffixWidth = timestamp.length + 2;
+    const contentWidth = Math.max(1, input.width - suffixWidth);
+    const decorate = input.decorateSuffix ?? ((text) => text);
+    return input.render(contentWidth).map((row, index) => overlaySpan(row, contentWidth, input.width, decorate(index === 0 ? `  ${timestamp}` : " ".repeat(suffixWidth), index === 0)));
+}

package/dist/{src/foundation/ui-components → ui/components}/scrollbar.d.ts

@@ -19,6 +19,30 @@ export interface ScrollbarInput {
     readonly scroll: number;
     readonly trackHeight: number;
 }
+export type ScrollbarAppearance = "auto" | "always" | "hidden";
+export type ScrollbarStyle = "thin" | "thick";
+export type ScrollbarSpeed = "normal" | "fast" | "high";
+/** Wheel distance: normal (3), fast (6), high as normal + fast (9). */
+export declare function scrollbarWheelRows(speed: ScrollbarSpeed): number;
+/** Selection edge distance uses the same configured rate as a wheel event. */
+export declare function scrollbarSelectionRows(speed: ScrollbarSpeed): number;
+export interface ScrollbarPresentationInput {
+    readonly geometry: ScrollbarGeometry | null;
+    readonly appearance: ScrollbarAppearance;
+    readonly style: ScrollbarStyle;
+    readonly hovered: boolean;
+    readonly dragging: boolean;
+    readonly activeUntil: number;
+    readonly now: number;
+}
+export interface ScrollbarPresentation {
+    readonly visible: boolean;
+    readonly reservesSpace: boolean;
+    readonly trackGlyph: "│" | "┃";
+    readonly thumbGlyph: "│" | "┃";
+}
+/** Pure appearance decision; activity time is supplied so tests own the clock. */
+export declare function scrollbarPresentation(input: ScrollbarPresentationInput): ScrollbarPresentation;
 /** Null when the content fits: no scrollbar is drawn and no width is reserved. */
 export declare function scrollbarGeometry(input: ScrollbarInput): ScrollbarGeometry | null;
 export declare function scrollbarReservesSpace(geometry: ScrollbarGeometry | null): boolean;
@@ -48,6 +72,8 @@ export interface RailPointer {
  */
 export declare class ScrollbarRails {
     #private;
+    noteActivity(key: string, now: number, lingerMs?: number): void;
+    isRecentlyActive(key: string, now: number): boolean;
     isHovered(key: string): boolean;
     isDragging(key: string): boolean;
     get draggingKey(): string | null;

package/dist/{src/foundation/ui-components → ui/components}/scrollbar.js

@@ -3,6 +3,33 @@
  * rail rather than to a global, because two scrollable surfaces can be visible
  * at once and a shared flag lights up the wrong one.
  */
+/** Wheel distance: normal (3), fast (6), high as normal + fast (9). */
+export function scrollbarWheelRows(speed) {
+    return speed === "high" ? 9 : speed === "fast" ? 6 : 3;
+}
+/** Selection edge distance uses the same configured rate as a wheel event. */
+export function scrollbarSelectionRows(speed) {
+    return scrollbarWheelRows(speed);
+}
+/** Pure appearance decision; activity time is supplied so tests own the clock. */
+export function scrollbarPresentation(input) {
+    const overflowing = input.geometry !== null;
+    // Invariant: auto/always reserve the final rail cell even while content fits.
+    // The blank gutter prevents prompt timestamps from touching the terminal edge
+    // and keeps later scrollbar appearance from reflowing the transcript.
+    const reservesSpace = input.appearance !== "hidden";
+    const visible = overflowing && reservesSpace && (input.appearance === "always"
+        || input.hovered
+        || input.dragging
+        || (input.activeUntil > 0 && input.now <= input.activeUntil));
+    const thick = input.style === "thick";
+    return {
+        visible,
+        reservesSpace,
+        trackGlyph: thick ? "┃" : "│",
+        thumbGlyph: thick || input.hovered || input.dragging ? "┃" : "│",
+    };
+}
 /** Null when the content fits: no scrollbar is drawn and no width is reserved. */
 export function scrollbarGeometry(input) {
     const { contentLength, viewportHeight, trackHeight } = input;
@@ -51,7 +78,14 @@ export function scrollForTrackPage(geometry, trackRow, scroll, viewportHeight) {
  */
 export class ScrollbarRails {
     #hovered = new Set();
+    #activeUntil = new Map();
     #dragging;
+    noteActivity(key, now, lingerMs = 900) {
+        this.#activeUntil.set(key, Math.max(this.#activeUntil.get(key) ?? 0, now + Math.max(0, lingerMs)));
+    }
+    isRecentlyActive(key, now) {
+        return now <= (this.#activeUntil.get(key) ?? 0);
+    }
     isHovered(key) {
         return this.#hovered.has(key);
     }
@@ -97,6 +131,7 @@ export class ScrollbarRails {
     }
     clear() {
         this.#hovered.clear();
+        this.#activeUntil.clear();
         this.#dragging = undefined;
     }
 }