@timurproko/a1 0.1.8-dev.ece8cef → 0.2.1-dev.590

package/dist/ui/components/text-selection.js

@@ -0,0 +1,210 @@
+import { displayWidth, stripAnsi } from "./text.js";
+const GRAPHEMES = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+export const TEXT_SELECTION_MULTI_CLICK_MS = 500;
+export function orderedTextSelection(selection) {
+    if (selection === undefined)
+        return undefined;
+    const { anchor, head } = selection;
+    if (selection.fullRow) {
+        const startLine = Math.min(anchor.line, head.line);
+        const endLine = Math.max(anchor.line, head.line);
+        return {
+            start: { line: startLine, column: 0 },
+            end: { line: endLine, column: Number.MAX_SAFE_INTEGER },
+            fullRow: true,
+            ...(selection.throughFinalColumn ? { throughFinalColumn: true } : {}),
+        };
+    }
+    if (!selection.cell && selection.dragged !== true)
+        return undefined;
+    // Invariant: an accepted drag includes both endpoint graphemes, even after returning
+    // to its anchor. Only an unextended point press is empty; paint and copy stay half-open.
+    const anchorFirst = comparePoints(anchor, head) <= 0;
+    const first = anchorFirst ? anchor : head;
+    const last = anchorFirst ? head : anchor;
+    return {
+        start: { line: first.line, column: pointBefore(first) },
+        end: { line: last.line, column: pointAfter(last) },
+        ...(selection.throughFinalColumn ? { throughFinalColumn: true } : {}),
+    };
+}
+export function pressTextSelection(input) {
+    const now = input.now ?? Date.now();
+    const previous = input.previousClick;
+    const count = previous !== undefined
+        && now - previous.time <= TEXT_SELECTION_MULTI_CLICK_MS
+        && previous.line === input.line
+        && Math.abs(previous.column - input.column) <= 1
+        ? previous.count + 1
+        : 1;
+    const click = { time: now, line: input.line, column: input.column, count };
+    const column = clamp(input.column, 1, Math.max(1, input.contentWidth));
+    const kind = ((count - 1) % 3) + 1;
+    if (kind === 2) {
+        const selection = selectWord(input.line, column, input.contentWidth, input.lineText);
+        return selection === undefined ? { click, kind: "word" } : { selection, click, kind: "word" };
+    }
+    if (kind === 3) {
+        if (input.lineContent?.selectable === false)
+            return { click, kind: "line" };
+        const from = clamp(input.lineContent?.from ?? 1, 1, Math.max(1, input.contentWidth));
+        const to = clamp(input.lineContent?.to ?? input.contentWidth, from, Math.max(1, input.contentWidth));
+        return {
+            selection: {
+                anchor: { line: input.line, column: from },
+                head: { line: input.line, column: to },
+                selecting: true,
+                cell: true,
+                fullRow: true,
+            },
+            click,
+            kind: "line",
+        };
+    }
+    const point = textSelectionPointAt(input.line, column, input.lineText);
+    return {
+        selection: {
+            anchor: point,
+            head: point,
+            selecting: true,
+            dragged: false,
+        },
+        click,
+        kind: "point",
+    };
+}
+export function extendTextSelection(selection, point) {
+    if (selection?.selecting !== true)
+        return selection;
+    const distinctMotion = comparePoints(selection.head, point) !== 0;
+    if (!distinctMotion)
+        return selection;
+    if (selection.fullRow)
+        return { ...selection, head: point };
+    return {
+        ...selection,
+        head: point,
+        dragged: true,
+    };
+}
+export function releaseTextSelection(selection) {
+    if (selection === undefined)
+        return undefined;
+    const released = selection.selecting ? { ...selection, selecting: false } : selection;
+    return orderedTextSelection(released) === undefined ? undefined : released;
+}
+export function textSelectionLineExtendColumn(selection, line, contentWidth) {
+    return line < selection.anchor.line ? 1 : Math.max(1, contentWidth);
+}
+/** Resolves a reported one-based pointer cell to the complete grapheme it intersects. */
+export function textSelectionPointAt(line, column, lineText) {
+    const plain = stripAnsi(lineText);
+    const target = Math.max(0, column - 1);
+    let width = 0;
+    for (const { segment } of GRAPHEMES.segment(plain)) {
+        const cellWidth = displayWidth(segment);
+        const next = width + cellWidth;
+        if (cellWidth > 0 && target >= width && target < next) {
+            return { line, column, from: width, to: next };
+        }
+        width = next;
+    }
+    return { line, column, from: target, to: target + 1 };
+}
+export function textSelectionText(selection, rows, lineContent) {
+    const parts = [];
+    for (let line = selection.start.line; line <= selection.end.line && line < rows.length; line += 1) {
+        const plain = stripAnsi(rows[line] ?? "");
+        const content = lineContent?.(line);
+        if (content?.selectable === false) {
+            parts.push("");
+            continue;
+        }
+        const baseFrom = line === selection.start.line ? selection.start.column : 0;
+        const baseTo = line === selection.end.line ? selection.end.column : Number.MAX_SAFE_INTEGER;
+        const contentFrom = Math.max(0, (content?.from ?? 1) - 1);
+        const contentTo = Math.max(contentFrom, (content?.to ?? Number.MAX_SAFE_INTEGER) - 1);
+        const from = Math.max(baseFrom, contentFrom);
+        const to = Math.max(from, Math.min(baseTo, contentTo));
+        parts.push(plain.slice(indexAtDisplayBoundary(plain, from, "start"), indexAtDisplayBoundary(plain, to, "end")).trimEnd());
+    }
+    return parts.join("\n");
+}
+/** Returns the plain cells covered by [from,to), expanding at grapheme edges. */
+export function plainTextBetweenColumns(line, from, to) {
+    const plain = stripAnsi(line);
+    return plain.slice(indexAtDisplayBoundary(plain, from, "start"), indexAtDisplayBoundary(plain, to, "end"));
+}
+export function usefulTextLineContent(line, from = 1) {
+    const start = Math.max(1, from);
+    const end = displayWidth(stripAnsi(line).replace(/\s+$/, "")) + 1;
+    return { from: start, to: Math.max(start, end) };
+}
+function selectWord(line, column, contentWidth, lineText) {
+    const plain = stripAnsi(lineText);
+    const segments = [];
+    let width = 0;
+    for (const { segment } of GRAPHEMES.segment(plain)) {
+        const cellWidth = displayWidth(segment);
+        if (cellWidth <= 0)
+            continue;
+        segments.push({ cls: characterClass(segment), from: width, to: width + cellWidth });
+        width += cellWidth;
+    }
+    const at = clamp(column, 1, Math.max(1, contentWidth)) - 1;
+    const index = segments.findIndex(segment => at >= segment.from && at < segment.to);
+    if (index < 0)
+        return undefined;
+    let low = index;
+    let high = index;
+    while (low > 0 && segments[low - 1]?.cls === segments[index]?.cls)
+        low -= 1;
+    while (high + 1 < segments.length && segments[high + 1]?.cls === segments[index]?.cls)
+        high += 1;
+    const end = segments[high]?.to ?? 1;
+    return {
+        anchor: { line, column: (segments[low]?.from ?? 0) + 1 },
+        head: { line, column: end },
+        selecting: true,
+        cell: true,
+        throughFinalColumn: segments[index]?.cls === 0 && end >= contentWidth,
+    };
+}
+function characterClass(character) {
+    if (/\s/u.test(character))
+        return 0;
+    if (/[\p{L}\p{N}_]/u.test(character))
+        return 1;
+    return 2;
+}
+function indexAtDisplayBoundary(plain, column, edge) {
+    if (column <= 0)
+        return 0;
+    if (column >= Number.MAX_SAFE_INTEGER - 1)
+        return plain.length;
+    let width = 0;
+    let index = 0;
+    for (const { segment } of GRAPHEMES.segment(plain)) {
+        const cellWidth = displayWidth(segment);
+        const next = width + cellWidth;
+        if (column < next)
+            return edge === "start" ? index : index + segment.length;
+        index += segment.length;
+        width = next;
+        if (width >= column)
+            return index;
+    }
+    return index;
+}
+function pointBefore(point) {
+    return point.from ?? Math.max(0, point.column - 1);
+}
+function pointAfter(point) {
+    return point.to ?? Math.max(0, point.column);
+}
+function comparePoints(left, right) {
+    return left.line === right.line ? left.column - right.column : left.line - right.line;
+}
+function clamp(value, minimum, maximum) {
+    return Math.max(minimum, Math.min(value, maximum));
+}

package/dist/ui/components/text.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Display-width text handling. Terminals lay out by column, not by code unit,
+ * so measuring with `String.length` mis-sizes CJK, emoji, and combining marks,
+ * and counting styling escapes as visible width breaks every layout that uses
+ * colour.
+ */
+/** Removes styling sequences so only visible characters remain. */
+export declare function stripAnsi(text: string): string;
+export interface DisplayColumnRange {
+    readonly from: number;
+    readonly to: number;
+}
+/** Visible-column segment (word, whitespace, or punctuation) under a pointer column. */
+export declare function displayWordColumnRange(text: string, pointerColumn: number): DisplayColumnRange | null;
+export interface DisplayColumnSlice {
+    /** Grapheme-aligned visible bounds in the source row. */
+    readonly from: number;
+    readonly to: number;
+    readonly text: string;
+}
+/** Plain graphemes intersecting a visible-column range, expanded at wide-character edges. */
+export declare function displayColumnSlice(text: string, requestedFrom: number, requestedTo: number): DisplayColumnSlice;
+/** Columns this text occupies once styling is removed. */
+export declare function displayWidth(text: string): number;
+/**
+ * Truncates to a column budget without splitting a grapheme. Styling sequences
+ * are carried through and a reset is appended when any style was opened, so a
+ * truncated row cannot leak colour into the rest of the line.
+ */
+export declare function truncateToWidth(text: string, maxWidth: number): string;
+/** Pads to an exact column count, truncating when the text is already wider. */
+export declare function padToWidth(text: string, width: number): string;
+/**
+ * A control that is present but cannot be used: the terminal own faint
+ * attribute over whatever colour it already carries, so it reads as half of what
+ * it would otherwise be in any theme.
+ */
+export declare function faint(text: string): string;

package/dist/ui/components/text.js

@@ -0,0 +1,185 @@
+/**
+ * Display-width text handling. Terminals lay out by column, not by code unit,
+ * so measuring with `String.length` mis-sizes CJK, emoji, and combining marks,
+ * and counting styling escapes as visible width breaks every layout that uses
+ * colour.
+ */
+const ANSI_PATTERN = /\[[0-9;:?]*[ -/]*[@-~]|[\]_][^]*(?:|\\)|[@-Z\\-_]/g;
+const SEGMENTER = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+const WORD_SEGMENTER = new Intl.Segmenter(undefined, { granularity: "word" });
+/**
+ * Recommended-for-general-interchange emoji. Terminals give every one of these
+ * two columns wherever its code points sit, so the wide blocks in
+ * `codePointWidth` cannot carry the measurement alone: a lone U+26A1 or any
+ * U+FE0F presentation sequence escapes them and would measure one column short.
+ */
+const RGI_EMOJI_PATTERN = /^\p{RGI_Emoji}$/v;
+/** Columns a terminal advances for a tab, matching the host runtime. */
+const TAB_WIDTH = 3;
+/** Removes styling sequences so only visible characters remain. */
+export function stripAnsi(text) {
+    return text.replace(ANSI_PATTERN, "");
+}
+function codePointWidth(codePoint) {
+    // Protocol: zero-width includes combining marks, joiners, variation selectors, and format characters.
+    if (codePoint === 0x200d || codePoint === 0xfeff)
+        return 0;
+    if (codePoint >= 0x0300 && codePoint <= 0x036f)
+        return 0;
+    if (codePoint >= 0x200b && codePoint <= 0x200f)
+        return 0;
+    if (codePoint >= 0xfe00 && codePoint <= 0xfe0f)
+        return 0;
+    if (codePoint >= 0x20d0 && codePoint <= 0x20f0)
+        return 0;
+    if (codePoint >= 0x1ab0 && codePoint <= 0x1aff)
+        return 0;
+    if (codePoint >= 0x1dc0 && codePoint <= 0x1dff)
+        return 0;
+    if (codePoint >= 0xe0100 && codePoint <= 0xe01ef)
+        return 0;
+    // Protocol: wide cells include CJK, Hangul, fullwidth forms, and the emoji planes terminals render double-width.
+    if (codePoint >= 0x1100 && codePoint <= 0x115f)
+        return 2;
+    if (codePoint >= 0x2e80 && codePoint <= 0xa4cf && codePoint !== 0x303f)
+        return 2;
+    if (codePoint >= 0xac00 && codePoint <= 0xd7a3)
+        return 2;
+    if (codePoint >= 0xf900 && codePoint <= 0xfaff)
+        return 2;
+    if (codePoint >= 0xfe30 && codePoint <= 0xfe6f)
+        return 2;
+    if (codePoint >= 0xff00 && codePoint <= 0xff60)
+        return 2;
+    if (codePoint >= 0xffe0 && codePoint <= 0xffe6)
+        return 2;
+    if (codePoint >= 0x1f300 && codePoint <= 0x1f64f)
+        return 2;
+    if (codePoint >= 0x1f900 && codePoint <= 0x1f9ff)
+        return 2;
+    if (codePoint >= 0x20000 && codePoint <= 0x3fffd)
+        return 2;
+    // Protocol: a tab advances to the host runtime's stop; other control characters occupy nothing.
+    if (codePoint === 0x09)
+        return TAB_WIDTH;
+    if (codePoint < 0x20 || (codePoint >= 0x7f && codePoint < 0xa0))
+        return 0;
+    return 1;
+}
+/** Cheap pre-filter: only clusters that could be emoji pay for the RGI test. */
+function couldBeEmoji(grapheme) {
+    const codePoint = grapheme.codePointAt(0) ?? 0;
+    return ((codePoint >= 0x1f000 && codePoint <= 0x1fbff) ||
+        (codePoint >= 0x2300 && codePoint <= 0x23ff) ||
+        (codePoint >= 0x2600 && codePoint <= 0x27bf) ||
+        (codePoint >= 0x2b00 && codePoint <= 0x2bff) ||
+        grapheme.length > 1);
+}
+/** Width of one grapheme cluster: two for emoji, else the widest code point it contains. */
+function graphemeWidth(grapheme) {
+    if (couldBeEmoji(grapheme) && RGI_EMOJI_PATTERN.test(grapheme))
+        return 2;
+    let width = 0;
+    for (const character of grapheme) {
+        width = Math.max(width, codePointWidth(character.codePointAt(0) ?? 0));
+    }
+    return width;
+}
+/** Visible-column segment (word, whitespace, or punctuation) under a pointer column. */
+export function displayWordColumnRange(text, pointerColumn) {
+    const plain = stripAnsi(text);
+    const pointer = Math.max(0, pointerColumn);
+    let column = 0;
+    for (const { segment } of WORD_SEGMENTER.segment(plain)) {
+        const width = displayWidth(segment);
+        const from = column;
+        const to = column + width;
+        if (pointer >= from && pointer < to)
+            return { from, to };
+        column = to;
+    }
+    return null;
+}
+/** Plain graphemes intersecting a visible-column range, expanded at wide-character edges. */
+export function displayColumnSlice(text, requestedFrom, requestedTo) {
+    const plain = stripAnsi(text);
+    const from = Math.max(0, requestedFrom);
+    const to = Math.max(from, requestedTo);
+    let column = 0;
+    let actualFrom;
+    let actualTo = from;
+    let selected = "";
+    for (const { segment } of SEGMENTER.segment(plain)) {
+        const width = graphemeWidth(segment);
+        const start = column;
+        const end = column + width;
+        if (end > from && start < to) {
+            actualFrom ??= start;
+            actualTo = end;
+            selected += segment;
+        }
+        column = end;
+        if (start >= to)
+            break;
+    }
+    return { from: actualFrom ?? from, to: actualFrom === undefined ? from : actualTo, text: selected };
+}
+/** Columns this text occupies once styling is removed. */
+export function displayWidth(text) {
+    let width = 0;
+    for (const { segment } of SEGMENTER.segment(stripAnsi(text)))
+        width += graphemeWidth(segment);
+    return width;
+}
+/**
+ * Truncates to a column budget without splitting a grapheme. Styling sequences
+ * are carried through and a reset is appended when any style was opened, so a
+ * truncated row cannot leak colour into the rest of the line.
+ */
+export function truncateToWidth(text, maxWidth) {
+    if (maxWidth <= 0)
+        return "";
+    if (displayWidth(text) <= maxWidth)
+        return text;
+    let out = "";
+    let width = 0;
+    let styled = false;
+    let index = 0;
+    while (index < text.length) {
+        ANSI_PATTERN.lastIndex = index;
+        const match = ANSI_PATTERN.exec(text);
+        if (match && match.index === index) {
+            out += match[0];
+            styled = true;
+            index += match[0].length;
+            continue;
+        }
+        const nextEscape = match ? match.index : text.length;
+        for (const { segment } of SEGMENTER.segment(text.slice(index, nextEscape))) {
+            const segmentWidth = graphemeWidth(segment);
+            if (width + segmentWidth > maxWidth)
+                return styled ? `${out}` : out;
+            out += segment;
+            width += segmentWidth;
+        }
+        index = nextEscape;
+    }
+    return styled ? `${out}` : out;
+}
+/** Pads to an exact column count, truncating when the text is already wider. */
+export function padToWidth(text, width) {
+    if (width <= 0)
+        return "";
+    const current = displayWidth(text);
+    if (current > width)
+        return truncateToWidth(text, width);
+    return text + " ".repeat(width - current);
+}
+/**
+ * A control that is present but cannot be used: the terminal own faint
+ * attribute over whatever colour it already carries, so it reads as half of what
+ * it would otherwise be in any theme.
+ */
+export function faint(text) {
+    return `${text}`;
+}

package/dist/ui/components/theme.d.ts

@@ -0,0 +1,19 @@
+export type UiThemeToken = "accent" | "mdHeading" | "text" | "muted" | "dim" | "border" | "error";
+export interface UiTheme {
+    fg(token: UiThemeToken, text: string): string;
+    bold(text: string): string;
+    /**
+     * The terminal's own foreground, left unpainted. What a list's own text is:
+     * a theme built for a light background would otherwise write near-black rows
+     * into a dark terminal, which is how the engine leaves its lists too.
+     */
+    plain(text: string): string;
+    /** Inverted styling for the active row of a floating surface. */
+    highlight(text: string): string;
+    /** A control that is present but cannot act: quieter than quiet text. */
+    disabled(text: string): string;
+    /** Background for a floating surface, so it reads as above the content. */
+    panel(text: string): string;
+}
+/** Renders every token as plain text. What tests assert against. */
+export declare const PLAIN_THEME: UiTheme;

package/dist/ui/components/theme.js

@@ -0,0 +1,9 @@
+/** Renders every token as plain text. What tests assert against. */
+export const PLAIN_THEME = Object.freeze({
+    fg: (_token, text) => text,
+    bold: (text) => text,
+    plain: (text) => text,
+    highlight: (text) => text,
+    disabled: (text) => text,
+    panel: (text) => text,
+});

package/dist/ui/components/transcript-viewport.d.ts

@@ -0,0 +1,187 @@
+import { type SelectionCopySnapshot } from "./selection-copy.js";
+import { type ScrollbarAppearance, type ScrollbarGeometry, type ScrollbarStyle } from "./scrollbar.js";
+export interface TranscriptPromptAnchor {
+    readonly id: string;
+    readonly firstRow: number;
+    readonly lastRow: number;
+    /** The source first row, including its submitted-prompt styling and timestamp. */
+    readonly sourceRow: string;
+    /** Optional source-styled row used only while prominent and not hovered. */
+    readonly prominentSourceRow?: string;
+}
+export interface TranscriptViewportConfig {
+    readonly scrollbarAppearance: ScrollbarAppearance;
+    readonly scrollbarStyle: ScrollbarStyle;
+}
+export interface TranscriptViewportTheme {
+    readonly track: (text: string) => string;
+    readonly thumb: (text: string, active: boolean) => string;
+    readonly sticky: (text: string, hovered: boolean) => string;
+    readonly quietSticky: (text: string) => string;
+    readonly bottomControl: (text: string, hovered: boolean) => string;
+    readonly selection: (line: string, from: number, to: number) => string;
+}
+export interface TranscriptViewportFrameInput {
+    readonly documentRows: readonly string[];
+    /** Optional paint-only transform; semantic selection and copying keep documentRows exact. */
+    readonly paintDocumentRow?: (row: string) => string;
+    /** Leading document rows that participate in pointer selection and copying. */
+    readonly selectableDocumentRowCount?: number;
+    /**
+     * First document row owned by the block that is currently streaming, if any. Rows from
+     * here to the end of the selectable document reflow together whenever that block
+     * re-renders, so the frame can declare how much damage is legitimately its own.
+     */
+    readonly liveTailStartRow?: number;
+    /** Final transient rows to bottom-align with unused viewport space while content fits. */
+    readonly bottomAlignedTailRowCount?: number;
+    readonly dockRows: readonly string[];
+    readonly promptAnchors: readonly TranscriptPromptAnchor[];
+    readonly width: number;
+    readonly height: number;
+    /**
+     * Optional zero-based terminal row for the floating bottom control. The shell
+     * supplies a stable anchor above its editor group so transient status and
+     * notification rows cannot make the control jump vertically.
+     */
+    readonly bottomControlRow?: number;
+    /** Latest reported one-based terminal coordinates; bottom hover uses this frame's hit region. */
+    readonly pointerPosition?: {
+        readonly column: number;
+        readonly row: number;
+    };
+    /** Base-frame cells hidden by modal/replacement surfaces and therefore excluded from visual copy. */
+    readonly coveredCells?: readonly {
+        readonly row: number;
+        readonly columnStart: number;
+        readonly columnEnd: number;
+    }[];
+    /** Transient paint-only text that must not participate in frame allocation or copying. */
+    readonly frameOverlay?: {
+        /** One-based terminal row. */
+        readonly row: number;
+        readonly text: string;
+    };
+    readonly now?: number;
+    readonly theme?: TranscriptViewportTheme;
+}
+export interface TranscriptViewportHitRegions {
+    readonly viewportHeight: number;
+    readonly rail: {
+        readonly column: number;
+        /** One-based terminal row. The one-row top inset is intentionally excluded. */
+        readonly rowStart: number;
+        readonly trackHeight: number;
+        readonly geometry: ScrollbarGeometry;
+    } | null;
+    readonly sticky: {
+        readonly row: number;
+        readonly target: number;
+        readonly width: number;
+    } | null;
+    readonly bottom: {
+        readonly row: number;
+        readonly columnStart: number;
+        readonly columnEnd: number;
+    } | null;
+    /** Transient non-selectable document-tail rows currently visible in the viewport. */
+    readonly transientTail: readonly number[];
+}
+export interface TranscriptViewportFrameDescriptor {
+    readonly frameId: number;
+    readonly width: number;
+    readonly height: number;
+    readonly transcript: {
+        readonly rowStart: number;
+        readonly rowEnd: number;
+    } | null;
+    readonly dock: {
+        readonly rowStart: number;
+        readonly rowEnd: number;
+    } | null;
+    readonly previousDocumentRange: {
+        readonly start: number;
+        readonly end: number;
+    } | null;
+    readonly nextDocumentRange: {
+        readonly start: number;
+        readonly end: number;
+    };
+    readonly previousFollowingEnd: boolean | null;
+    readonly followingEnd: boolean;
+    /** Complete non-selectable suffix, including pending steering, alignment, and status rows. */
+    readonly transientRowCount: number;
+    /** Flexible rows inserted before the bottom-aligned live status while content fits. */
+    readonly transientAlignmentGapRows: number;
+    /** Bottom-aligned transient rows. */
+    readonly bottomAlignedTailRowCount: number;
+    /** Visible rows owned by the currently streaming transcript block. */
+    readonly liveTailRows: number;
+    readonly verticalShiftRows: number;
+    readonly safeVerticalShift: boolean;
+    /** Monotonic interaction revision used to reject stale selection evidence. */
+    readonly selectionRevision: number;
+    /** One-based terminal rows whose source or normalized selection range changed. */
+    readonly selectionDamagedRows: readonly number[];
+    readonly cause: "initial" | "steady" | "dock-input" | "follow-shift" | "detached" | "geometry-change";
+}
+export interface TranscriptViewportFrame {
+    readonly rows: readonly string[];
+    readonly contentWidth: number;
+    readonly scrollTop: number;
+    readonly maxScroll: number;
+    readonly followingEnd: boolean;
+    readonly hits: TranscriptViewportHitRegions;
+    readonly descriptor: TranscriptViewportFrameDescriptor;
+    /** Deterministic evidence for bounded selection-only row composition. */
+    readonly selectionDamage: {
+        readonly revision: number;
+        readonly recomputedRows: readonly number[];
+        readonly reusedRows: readonly number[];
+        readonly cacheEntries: number;
+    };
+}
+/**
+ * A1-owned viewport state. It knows only rows and semantic prompt anchors; Pi
+ * components and transcript payloads remain outside this neutral boundary.
+ */
+export declare class TranscriptViewport {
+    #private;
+    get scrollTop(): number;
+    get maxScroll(): number;
+    get followingEnd(): boolean;
+    get newMessages(): number;
+    get frame(): TranscriptViewportFrame | null;
+    get selectionRevision(): number;
+    /** Counts one completed assistant reply while detached; tool rows never call this. */
+    noteNewMessage(): boolean;
+    setConfig(config: TranscriptViewportConfig): void;
+    noteScrollActivity(now?: number, lingerMs?: number): void;
+    setRailHovered(hovered: boolean): void;
+    setRailDragging(dragging: boolean): void;
+    setStickyHovered(hovered: boolean): void;
+    get selectionActive(): boolean;
+    get hasSelection(): boolean;
+    /** True when the active gesture began on transcript rows rather than the dock. */
+    get selectionFromContent(): boolean;
+    pressSelection(column: number, frameRow: number, now?: number): boolean;
+    extendSelection(column: number, frameRow: number, now?: number, autoScroll?: boolean): boolean;
+    releaseSelection(): boolean;
+    clearSelection(): boolean;
+    selectedText(): string | null;
+    /** Captures only the selected visible frame text, never off-screen transcript history. */
+    captureSelectedText(): SelectionCopySnapshot | null;
+    scrollBy(lines: number, now?: number): boolean;
+    scrollTo(position: number, now?: number): boolean;
+    scrollToEnd(now?: number): boolean;
+    /** Jumps to the pinned prompt governing this position, then earlier prompts. */
+    scrollToPreviousPrompt(now?: number): boolean;
+    /** Jumps to the next submitted prompt, or resumes following at the bottom. */
+    scrollToNextPrompt(now?: number): boolean;
+    reset(): void;
+    clearTransient(): void;
+    compose(input: TranscriptViewportFrameInput): TranscriptViewportFrame;
+    /** Reuses an established transcript frame when only same-height dock rows changed. */
+    composeDockOnly(dockRows: readonly string[], width: number, height: number): TranscriptViewportFrame | null;
+}
+export declare function assertTranscriptViewportFrameDescriptor(descriptor: TranscriptViewportFrameDescriptor): void;