@timurproko/a1 0.1.8-dev.ece8cef → 0.2.0

package/dist/ui/components/transcript-viewport.js

@@ -0,0 +1,886 @@
+import { MAX_COPY_SOURCE_UNITS } from "./selection-copy.js";
+import { isThumbRow, scrollbarGeometry, scrollbarPresentation, } from "./scrollbar.js";
+import { backgroundSgrSpan, overlaySpan } from "./spans.js";
+import { faint, truncateToWidth, displayWidth, stripAnsi } from "./text.js";
+import { extendTextSelection, orderedTextSelection, pressTextSelection, releaseTextSelection, textSelectionLineExtendColumn, textSelectionPointAt, textSelectionText, usefulTextLineContent, } from "./text-selection.js";
+const CONTROL_STYLE_RESET = "\u001b]8;;\u001b\\\u001b[0m";
+// Invariant: scrollbar chrome closes source links and decoration without clearing
+// the row surface painted beneath its dedicated, non-semantic gutter.
+const GUTTER_DECORATION_RESET = "\u001b]8;;\u001b\\\u001b[22;23;24;25;27;28;29;39;54;55m";
+const IDENTITY_ROW = (row) => row;
+function documentSelectionAnchor(row, source) {
+    return { kind: "document", row, source, identity: stripAnsi(source).trimEnd() };
+}
+const DEFAULT_CONFIG = {
+    scrollbarAppearance: "auto",
+    scrollbarStyle: "thin",
+};
+const PLAIN_THEME = {
+    track: text => text,
+    thumb: text => text,
+    sticky: (text, hovered) => hovered ? `\u001b[7m${text}\u001b[27m` : text,
+    quietSticky: faint,
+    bottomControl: (text, hovered) => hovered ? `\u001b[7m${text}\u001b[27m` : `\u001b[7m${text}\u001b[27m`,
+    selection: (line, from, to) => backgroundSgrSpan(line, from, to),
+};
+/**
+ * A1-owned viewport state. It knows only rows and semantic prompt anchors; Pi
+ * components and transcript payloads remain outside this neutral boundary.
+ */
+export class TranscriptViewport {
+    #config = DEFAULT_CONFIG;
+    #scrollTop = 0;
+    #maxScroll = 0;
+    #followingEnd = true;
+    #newMessages = 0;
+    #activeUntil = 0;
+    #railHovered = false;
+    #railDragging = false;
+    #stickyHovered = false;
+    #selection;
+    #selectionAnchors;
+    #selectionClick;
+    #selectionRevision = 0;
+    #copyableSelection = false;
+    // Invariant: exact unselected rows cover the latest visible base frame and dock.
+    #selectionRows = [];
+    #paintedRowCache = new Map();
+    #baseRowCache = new Map();
+    #selectedRowCache = new Map();
+    #finalRowCache = new Map();
+    #functionIds = new WeakMap();
+    #nextFunctionId = 1;
+    #previousVisibleStates = [];
+    #documentRows = [];
+    #selectableDocumentRowCount = 0;
+    #promptAnchors = [];
+    #contentWidth = 0;
+    #selectionWidth = 0;
+    #viewportHeight = 0;
+    #firstSelectableRow = 0;
+    #selectionRowAnchors = [];
+    #frameId = 0;
+    #frame = null;
+    get scrollTop() { return this.#scrollTop; }
+    get maxScroll() { return this.#maxScroll; }
+    get followingEnd() { return this.#followingEnd; }
+    get newMessages() { return this.#newMessages; }
+    get frame() { return this.#frame; }
+    get selectionRevision() { return this.#selectionRevision; }
+    /** Counts one completed assistant reply while detached; tool rows never call this. */
+    noteNewMessage() {
+        if (this.#followingEnd)
+            return false;
+        this.#newMessages += 1;
+        return true;
+    }
+    setConfig(config) {
+        this.#config = config;
+        if (config.scrollbarAppearance === "hidden") {
+            this.#railHovered = false;
+            this.#railDragging = false;
+        }
+    }
+    noteScrollActivity(now = Date.now(), lingerMs = 900) {
+        this.#activeUntil = Math.max(this.#activeUntil, now + lingerMs);
+    }
+    setRailHovered(hovered) { this.#railHovered = hovered; }
+    setRailDragging(dragging) { this.#railDragging = dragging; }
+    setStickyHovered(hovered) { this.#stickyHovered = hovered; }
+    get selectionActive() { return this.#selection?.selecting === true; }
+    get hasSelection() { return orderedTextSelection(this.#selection) !== undefined; }
+    /** True when the active gesture began on transcript rows rather than the dock. */
+    get selectionFromContent() { return this.#selectionAnchors !== undefined && this.#selectionAnchors.anchor.kind !== "dock"; }
+    pressSelection(column, frameRow, now = Date.now()) {
+        const frameHeight = this.#frame?.rows.length ?? 0;
+        const selectionWidth = frameRow <= (this.#frame?.hits.viewportHeight ?? 0)
+            ? this.#contentWidth
+            : this.#selectionWidth;
+        if (frameRow <= this.#firstSelectableRow || frameRow > frameHeight || column < 1 || column > selectionWidth)
+            return false;
+        const line = frameRow - 1;
+        const pressed = pressTextSelection({
+            line,
+            column,
+            contentWidth: selectionWidth,
+            lineText: this.#selectionRows[line] ?? "",
+            lineContent: usefulTextLineContent(this.#selectionRows[line] ?? ""),
+            ...(this.#selectionClick === undefined ? {} : { previousClick: this.#selectionClick }),
+            now,
+        });
+        this.#selection = pressed.selection;
+        const rowAnchor = this.#selectionAnchorAt(line);
+        this.#selectionAnchors = pressed.selection === undefined || rowAnchor === undefined
+            ? undefined
+            : { anchor: rowAnchor, head: rowAnchor };
+        this.#selectionClick = pressed.click;
+        this.#selectionRevision += 1;
+        this.#updateCopyableSelection();
+        return true;
+    }
+    extendSelection(column, frameRow, now = Date.now(), autoScroll = true) {
+        const selection = this.#selection;
+        const frameHeight = this.#frame?.rows.length ?? 0;
+        if (selection?.selecting !== true || frameHeight <= 0 || this.#selectionRows.length === 0)
+            return false;
+        // Performance: pointer motion updates only the endpoint; the shell's fixed-cadence timer
+        // owns edge scrolling. Selection itself remains in visible-frame coordinates.
+        if (autoScroll && frameRow > frameHeight)
+            this.scrollBy(1, now);
+        else if (autoScroll && frameRow <= 1 && this.#scrollTop > 0)
+            this.scrollBy(-1, now);
+        const line = clamp(frameRow - 1, 0, this.#selectionRows.length - 1);
+        const selectionWidth = line < (this.#frame?.hits.viewportHeight ?? 0)
+            ? this.#contentWidth
+            : this.#selectionWidth;
+        const targetColumn = selection.fullRow
+            ? textSelectionLineExtendColumn(selection, line, selectionWidth)
+            : clamp(column, 1, selectionWidth);
+        const point = selection.fullRow
+            ? { line, column: targetColumn }
+            : textSelectionPointAt(line, targetColumn, this.#selectionRows[line] ?? "");
+        const next = extendTextSelection(selection, point);
+        if (next !== selection) {
+            const headAnchor = this.#selectionAnchorAt(line);
+            if (headAnchor === undefined || this.#selectionAnchors === undefined) {
+                this.clearSelection();
+                return true;
+            }
+            this.#selection = next;
+            this.#selectionAnchors = { ...this.#selectionAnchors, head: headAnchor };
+            this.#selectionRevision += 1;
+            this.#updateCopyableSelection();
+        }
+        return true;
+    }
+    releaseSelection() {
+        if (this.#selection?.selecting !== true)
+            return false;
+        this.#selection = releaseTextSelection(this.#selection);
+        if (this.#selection === undefined)
+            this.#selectionAnchors = undefined;
+        this.#selectionRevision += 1;
+        this.#updateCopyableSelection();
+        return true;
+    }
+    clearSelection() {
+        if (this.#selection === undefined)
+            return false;
+        this.#selection = undefined;
+        this.#selectionAnchors = undefined;
+        this.#copyableSelection = false;
+        this.#selectionRevision += 1;
+        return true;
+    }
+    selectedText() {
+        const selection = this.#visibleSelection();
+        if (selection === undefined)
+            return null;
+        const text = textSelectionText(selection, this.#selectionRows, line => usefulTextLineContent(this.#selectionRows[line] ?? ""));
+        return text.length === 0 ? null : text;
+    }
+    /** Captures only the selected visible frame text, never off-screen transcript history. */
+    captureSelectedText() {
+        if (!this.#copyableSelection)
+            return null;
+        const started = performance.now();
+        const text = this.selectedText();
+        if (text === null)
+            return null;
+        const normalized = {
+            start: { line: 0, column: 0 },
+            end: { line: 0, column: Number.MAX_SAFE_INTEGER },
+        };
+        if (text.length > MAX_COPY_SOURCE_UNITS) {
+            return { literal: true, selection: normalized, revision: this.#selectionRevision, rows: [], sourceUnits: 0,
+                captureMs: performance.now() - started, rejected: "size" };
+        }
+        return { literal: true, selection: normalized, revision: this.#selectionRevision, rows: [{ text }],
+            sourceUnits: text.length, captureMs: performance.now() - started };
+    }
+    scrollBy(lines, now = Date.now()) {
+        if (this.#maxScroll <= 0 || lines === 0)
+            return false;
+        const base = this.#followingEnd ? this.#maxScroll : this.#scrollTop;
+        const next = clamp(base + lines, 0, this.#maxScroll);
+        this.#scrollTop = next;
+        this.#followingEnd = next >= this.#maxScroll;
+        if (this.#followingEnd)
+            this.#newMessages = 0;
+        this.noteScrollActivity(now);
+        return true;
+    }
+    scrollTo(position, now = Date.now()) {
+        const next = clamp(position, 0, this.#maxScroll);
+        const changed = next !== this.#scrollTop || this.#followingEnd;
+        this.#scrollTop = next;
+        // Invariant: every scrolling path that reaches the final legal top row resumes follow.
+        this.#followingEnd = next >= this.#maxScroll;
+        if (this.#followingEnd)
+            this.#newMessages = 0;
+        this.noteScrollActivity(now);
+        return changed;
+    }
+    scrollToEnd(now = Date.now()) {
+        const changed = !this.#followingEnd || this.#scrollTop !== this.#maxScroll;
+        this.#followingEnd = true;
+        this.#scrollTop = this.#maxScroll;
+        this.#newMessages = 0;
+        this.noteScrollActivity(now);
+        return changed;
+    }
+    /** Jumps to the pinned prompt governing this position, then earlier prompts. */
+    scrollToPreviousPrompt(now = Date.now()) {
+        let target = -1;
+        let earliest = Number.POSITIVE_INFINITY;
+        for (const anchor of this.#promptAnchors) {
+            earliest = Math.min(earliest, anchor.firstRow);
+            if (anchor.firstRow < this.#scrollTop && anchor.firstRow > target)
+                target = anchor.firstRow;
+        }
+        // Invariant: the first prompt owns the document's opening breathing row. At that final
+        // navigation stop, reveal the spacer too rather than pinning the prompt to
+        // terminal row one as later prompt jumps do.
+        const destination = target === earliest ? 0 : target;
+        return target >= 0 && this.scrollTo(destination, now);
+    }
+    /** Jumps to the next submitted prompt, or resumes following at the bottom. */
+    scrollToNextPrompt(now = Date.now()) {
+        if (this.#promptAnchors.length === 0)
+            return false;
+        const earliest = Math.min(...this.#promptAnchors.map(anchor => anchor.firstRow));
+        // Invariant: scroll position zero is the first-prompt stop because it includes that
+        // prompt's opening spacer. Do not spend an extra keypress moving one row.
+        const after = this.#scrollTop === 0 ? earliest : this.#scrollTop;
+        let target = Number.POSITIVE_INFINITY;
+        for (const anchor of this.#promptAnchors) {
+            if (anchor.firstRow > after && anchor.firstRow < target)
+                target = anchor.firstRow;
+        }
+        return Number.isFinite(target) ? this.scrollTo(target, now) : this.scrollToEnd(now);
+    }
+    reset() {
+        this.#scrollTop = 0;
+        this.#maxScroll = 0;
+        this.#followingEnd = true;
+        this.#newMessages = 0;
+        if (this.#selection !== undefined)
+            this.#selectionRevision += 1;
+        this.#selection = undefined;
+        this.#selectionAnchors = undefined;
+        this.#copyableSelection = false;
+        this.#selectionRows = [];
+        this.#selectionRowAnchors = [];
+        this.#selectionClick = undefined;
+        this.#paintedRowCache.clear();
+        this.#baseRowCache.clear();
+        this.#selectedRowCache.clear();
+        this.#finalRowCache.clear();
+        this.#previousVisibleStates = [];
+        this.#documentRows = [];
+        this.#selectableDocumentRowCount = 0;
+        this.#promptAnchors = [];
+        this.#contentWidth = 0;
+        this.#selectionWidth = 0;
+        this.#viewportHeight = 0;
+        this.clearTransient();
+        this.#frame = null;
+    }
+    clearTransient() {
+        this.#activeUntil = 0;
+        this.#railHovered = false;
+        this.#railDragging = false;
+        this.#stickyHovered = false;
+    }
+    compose(input) {
+        const width = Math.max(1, input.width);
+        const height = Math.max(0, input.height);
+        const theme = input.theme ?? PLAIN_THEME;
+        const previousDescriptor = this.#frame?.descriptor ?? null;
+        const dock = input.dockRows.length > height ? input.dockRows.slice(-height) : [...input.dockRows];
+        const viewportHeight = Math.max(0, height - dock.length);
+        const bottomAlignedTailRowCount = clamp(input.bottomAlignedTailRowCount ?? 0, 0, input.documentRows.length);
+        const transientAlignmentGapRows = bottomAlignedTailRowCount > 0
+            ? Math.max(0, viewportHeight - input.documentRows.length)
+            : 0;
+        const tailStart = input.documentRows.length - bottomAlignedTailRowCount;
+        const documentRows = transientAlignmentGapRows === 0
+            ? input.documentRows
+            : [
+                ...input.documentRows.slice(0, tailStart),
+                ...Array.from({ length: transientAlignmentGapRows }, () => ""),
+                ...input.documentRows.slice(tailStart),
+            ];
+        this.#maxScroll = Math.max(0, documentRows.length - viewportHeight);
+        if (this.#followingEnd)
+            this.#scrollTop = this.#maxScroll;
+        else
+            this.#scrollTop = clamp(this.#scrollTop, 0, this.#maxScroll);
+        if (this.#scrollTop >= this.#maxScroll)
+            this.#followingEnd = true;
+        if (this.#followingEnd)
+            this.#newMessages = 0;
+        const geometry = scrollbarGeometry({
+            contentLength: documentRows.length,
+            viewportHeight,
+            scroll: this.#scrollTop,
+            // Compatibility: the session rail deliberately starts one line below the viewport top.
+            trackHeight: Math.max(0, viewportHeight - 1),
+        });
+        const presentation = scrollbarPresentation({
+            geometry,
+            appearance: this.#config.scrollbarAppearance,
+            style: this.#config.scrollbarStyle,
+            hovered: this.#railHovered,
+            dragging: this.#railDragging,
+            activeUntil: this.#activeUntil,
+            now: input.now ?? Date.now(),
+        });
+        const contentWidth = presentation.reservesSpace ? Math.max(1, width - 1) : width;
+        this.#documentRows = documentRows;
+        this.#selectableDocumentRowCount = clamp(input.selectableDocumentRowCount ?? input.documentRows.length, 0, input.documentRows.length);
+        this.#promptAnchors = input.promptAnchors;
+        this.#contentWidth = contentWidth;
+        // Invariant: dock rows remain selectable at full width; scrollable source rows
+        // use contentWidth and leave the gutter outside semantic selection.
+        this.#selectionWidth = width;
+        this.#viewportHeight = viewportHeight;
+        const paintDocumentRow = input.paintDocumentRow ?? IDENTITY_ROW;
+        const cacheLimit = Math.max(32, viewportHeight * 6);
+        trimCache(this.#paintedRowCache, cacheLimit);
+        trimCache(this.#baseRowCache, cacheLimit);
+        trimCache(this.#selectedRowCache, cacheLimit);
+        trimCache(this.#finalRowCache, cacheLimit);
+        const paintId = this.#functionId(paintDocumentRow);
+        const paintRecomputedRows = new Set();
+        const visibleSource = documentRows.slice(this.#scrollTop, this.#scrollTop + viewportHeight);
+        while (visibleSource.length < viewportHeight)
+            visibleSource.push("");
+        const visible = visibleSource.map((row, index) => {
+            const painted = cachedString(this.#paintedRowCache, `${paintId}\u0000${row}`, cacheLimit, () => paintDocumentRow(row));
+            if (!painted.reused)
+                paintRecomputedRows.add(index);
+            return painted.value;
+        });
+        const governing = governingPrompt(input.promptAnchors, this.#scrollTop);
+        const stickyActive = governing !== null && governing.firstRow < this.#scrollTop;
+        if (stickyActive && visible.length > 0) {
+            const quiet = this.#scrollTop > governing.lastRow;
+            // Compatibility: only non-hovered prominent rows may retain source metadata roles.
+            // Quiet and hover keep the established full-row styling; anchors without a
+            // variant retain their existing presentation in every state.
+            const sourceRow = !quiet && !this.#stickyHovered
+                ? governing.prominentSourceRow ?? governing.sourceRow
+                : governing.sourceRow;
+            const source = cachedString(this.#paintedRowCache, `${paintId}\u0000${sourceRow}`, cacheLimit, () => paintDocumentRow(sourceRow));
+            if (!source.reused)
+                paintRecomputedRows.add(0);
+            const sticky = theme.sticky(source.value, this.#stickyHovered);
+            visible[0] = quiet && !this.#stickyHovered ? theme.quietSticky(sticky) : sticky;
+            visibleSource[0] = sourceRow;
+        }
+        // Invariant: selection uses exact visible source rows within the rendered
+        // content boundary; paint-only guards and the rail gutter stay presentation-only.
+        this.#selectionRows = [
+            ...visibleSource.map(row => truncateToWidth(row, contentWidth)),
+            ...dock,
+        ].slice(0, height);
+        const visibleAnchors = Array.from({ length: viewportHeight }, (_value, row) => {
+            const documentRow = this.#scrollTop + row;
+            return documentRow < documentRows.length
+                ? documentSelectionAnchor(documentRow, documentRows[documentRow] ?? "")
+                : { kind: "screen", row, source: this.#selectionRows[row] ?? "" };
+        });
+        // Invariant: a pinned prompt is chrome over its hidden source row, which clips like off-screen rows.
+        this.#firstSelectableRow = stickyActive && viewportHeight > 0 ? 1 : 0;
+        this.#selectionRowAnchors = [
+            ...visibleAnchors,
+            ...dock.map((_row, index) => ({ kind: "dock", fromBottom: dock.length - index - 1 })),
+        ].slice(0, height);
+        this.#projectSelection(documentRows, dock, height);
+        const selectionPainterId = this.#functionId(theme.selection);
+        // Concurrency: a painter may synchronously route input in tests or host integrations.
+        // Label this frame with the exact selection snapshot it began composing.
+        const composingSelectionRevision = this.#selectionRevision;
+        const orderedSelection = this.#visibleSelection();
+        const recomputedRows = [];
+        const reusedRows = [];
+        const selectionDamagedRows = [];
+        const visibleStates = [];
+        const frameRows = [...visible, ...dock].slice(0, height);
+        const selectionRows = [...this.#selectionRows];
+        let bottomHit = null;
+        let control;
+        if (this.#maxScroll > 0 && !this.#followingEnd && frameRows.length > 0) {
+            const genericLabel = " Jump to bottom (Ctrl+End) ↓ ";
+            const countedLabel = this.#newMessages > 0
+                ? ` ${this.#newMessages} new message${this.#newMessages === 1 ? "" : "s"} (Ctrl+End) ↓ `
+                : genericLabel;
+            const label = displayWidth(countedLabel) <= contentWidth ? countedLabel : genericLabel;
+            const labelWidth = displayWidth(label);
+            if (labelWidth <= contentWidth) {
+                const fallbackRow = Math.max(0, viewportHeight - 1);
+                const row = clamp(input.bottomControlRow ?? fallbackRow, 0, frameRows.length - 1);
+                const left = Math.floor((contentWidth - labelWidth) / 2);
+                bottomHit = { row: row + 1, columnStart: left + 1, columnEnd: left + labelWidth };
+                // Invariant: appearance and hit testing share current geometry, even when no mouse moves.
+                const pointer = input.pointerPosition;
+                const bottomHovered = pointer !== undefined && pointer.row === bottomHit.row
+                    && pointer.column >= bottomHit.columnStart && pointer.column <= bottomHit.columnEnd;
+                control = { row, left, text: `${CONTROL_STYLE_RESET}${theme.bottomControl(label, bottomHovered)}` };
+                frameRows[row] = overlaySpan(padRowPreservingBackground(frameRows[row] ?? "", width), left, left + labelWidth, control.text);
+                // Invariant: the control floats above selection; its cells are never selected or copied.
+                selectionRows[row] = overlaySpan(padRowPreservingBackground(selectionRows[row] ?? "", width), left, left + labelWidth, " ".repeat(labelWidth));
+            }
+        }
+        for (const covered of input.coveredCells ?? []) {
+            const row = covered.row - 1;
+            if (row < 0 || row >= selectionRows.length)
+                continue;
+            const from = clamp(covered.columnStart - 1, 0, width);
+            const to = clamp(covered.columnEnd, from, width);
+            selectionRows[row] = overlaySpan(padRowPreservingBackground(selectionRows[row] ?? "", width), from, to, " ".repeat(to - from));
+        }
+        this.#selectionRows = selectionRows;
+        this.#updateCopyableSelection();
+        for (let row = 0; row < frameRows.length; row += 1) {
+            const painted = frameRows[row] ?? "";
+            const rowSelectionWidth = row < viewportHeight ? contentWidth : width;
+            const range = selectionRangeForLine(orderedSelection, row, this.#selectionRows.length, rowSelectionWidth);
+            // Invariant: the reserved rail gutter is not a semantic selection or copy cell,
+            // but a range that reaches the content boundary paints through it so the rail
+            // floats above one continuous selection surface.
+            const paintRange = range !== null && row < viewportHeight
+                && contentWidth < width && range.to === contentWidth
+                ? { from: range.from, to: width }
+                : range;
+            const padded = row < viewportHeight || paintRange !== null;
+            const base = cachedString(this.#baseRowCache, `${width}\u0000${contentWidth}\u0000${row < viewportHeight}\u0000${padded}\u0000${painted}`, cacheLimit, () => row < viewportHeight
+                ? padViewportRowWithGutter(painted, contentWidth, width)
+                : padded ? padRowPreservingBackground(painted, width) : painted);
+            let rowRecomputed = row < viewportHeight && paintRecomputedRows.has(row) || !base.reused;
+            const rangeKey = paintRange === null ? "-" : `${paintRange.from}:${paintRange.to}`;
+            const selected = paintRange === null
+                ? { value: base.value, reused: true }
+                : cachedString(this.#selectedRowCache, `${selectionPainterId}\u0000${rangeKey}\u0000${base.value}`, cacheLimit, () => theme.selection(base.value, paintRange.from, paintRange.to));
+            rowRecomputed ||= !selected.reused;
+            // Invariant: paint the rail after selection over the gutter's continued row
+            // background. Source content and selection still end at the preceding cell.
+            let railCell = "";
+            if (row < viewportHeight && presentation.visible && geometry !== null && row > 0) {
+                const trackRow = row - 1;
+                const thumb = isThumbRow(geometry, trackRow);
+                const glyph = thumb ? presentation.thumbGlyph : presentation.trackGlyph;
+                railCell = thumb ? theme.thumb(glyph, this.#railHovered || this.#railDragging) : theme.track(glyph);
+            }
+            const overlayLimit = row < viewportHeight ? contentWidth : width;
+            const overlayText = input.frameOverlay?.row === row + 1
+                ? truncateToWidth(input.frameOverlay.text, overlayLimit)
+                : "";
+            const overlayWidth = displayWidth(overlayText);
+            const final = cachedString(this.#finalRowCache, `${width}\u0000${railCell}\u0000${overlayText}\u0000${selected.value}`, cacheLimit, () => {
+                const withRail = railCell.length === 0 ? selected.value : overlaySpan(selected.value, width - 1, width, `${GUTTER_DECORATION_RESET}${railCell}`, { inheritStartStyle: true });
+                return overlayWidth === 0 ? withRail : overlaySpan(padRowPreservingBackground(withRail, width), overlayLimit - overlayWidth, overlayLimit, `${CONTROL_STYLE_RESET}${overlayText}`);
+            });
+            rowRecomputed ||= !final.reused;
+            frameRows[row] = control?.row === row && paintRange !== null && bottomHit !== null
+                ? overlaySpan(final.value, control.left, bottomHit.columnEnd, control.text)
+                : final.value;
+            (rowRecomputed ? recomputedRows : reusedRows).push(row + 1);
+            const state = `${width}\u0000${row}\u0000${painted}\u0000${rangeKey}\u0000${range === null ? "" : selectionPainterId}\u0000${railCell}\u0000${overlayText}`;
+            visibleStates.push(state);
+            if (this.#previousVisibleStates[row] !== state)
+                selectionDamagedRows.push(row + 1);
+        }
+        this.#previousVisibleStates = visibleStates;
+        const nextDocumentRange = {
+            start: this.#scrollTop,
+            end: Math.min(documentRows.length, this.#scrollTop + viewportHeight),
+        };
+        const previousDocumentRange = previousDescriptor?.nextDocumentRange ?? null;
+        const sameGeometry = previousDescriptor !== null
+            && previousDescriptor.width === width
+            && previousDescriptor.height === height
+            && sameRectangle(previousDescriptor.transcript, viewportHeight === 0 ? null : { rowStart: 1, rowEnd: viewportHeight })
+            && sameRectangle(previousDescriptor.dock, dock.length === 0 ? null : { rowStart: viewportHeight + 1, rowEnd: height });
+        const verticalShiftRows = previousDocumentRange === null ? 0 : nextDocumentRange.start - previousDocumentRange.start;
+        const safeVerticalShift = sameGeometry
+            && previousDescriptor?.followingEnd === true
+            && this.#followingEnd
+            && this.#selection === undefined
+            && verticalShiftRows > 0
+            && verticalShiftRows < viewportHeight;
+        const descriptor = {
+            frameId: ++this.#frameId,
+            width,
+            height,
+            transcript: viewportHeight === 0 ? null : { rowStart: 1, rowEnd: viewportHeight },
+            dock: dock.length === 0 ? null : { rowStart: viewportHeight + 1, rowEnd: height },
+            previousDocumentRange,
+            nextDocumentRange,
+            previousFollowingEnd: previousDescriptor?.followingEnd ?? null,
+            followingEnd: this.#followingEnd,
+            transientRowCount: Math.max(0, documentRows.length - this.#selectableDocumentRowCount),
+            transientAlignmentGapRows,
+            bottomAlignedTailRowCount,
+            liveTailRows: visibleLiveTailRows(input.liveTailStartRow, this.#selectableDocumentRowCount, this.#scrollTop, viewportHeight),
+            verticalShiftRows,
+            safeVerticalShift,
+            selectionRevision: composingSelectionRevision,
+            selectionDamagedRows,
+            cause: previousDescriptor === null
+                ? "initial"
+                : !sameGeometry
+                    ? "geometry-change"
+                    : !this.#followingEnd
+                        ? "detached"
+                        : safeVerticalShift
+                            ? "follow-shift"
+                            : "steady",
+        };
+        assertTranscriptViewportFrameDescriptor(descriptor);
+        const hits = {
+            viewportHeight,
+            rail: geometry === null || this.#config.scrollbarAppearance === "hidden" ? null : {
+                column: width,
+                rowStart: 2,
+                trackHeight: Math.max(0, viewportHeight - 1),
+                geometry,
+            },
+            sticky: stickyActive ? { row: 1, target: governing.firstRow, width: contentWidth } : null,
+            bottom: bottomHit,
+            transientTail: Array.from({ length: Math.max(0, Math.min(documentRows.length, this.#scrollTop + viewportHeight) - Math.max(this.#scrollTop, this.#selectableDocumentRowCount)) }, (_row, index) => Math.max(this.#scrollTop, this.#selectableDocumentRowCount) - this.#scrollTop + index + 1),
+        };
+        const frame = {
+            rows: frameRows,
+            contentWidth,
+            scrollTop: this.#scrollTop,
+            maxScroll: this.#maxScroll,
+            followingEnd: this.#followingEnd,
+            hits,
+            descriptor,
+            selectionDamage: {
+                revision: composingSelectionRevision,
+                recomputedRows,
+                reusedRows,
+                cacheEntries: this.#paintedRowCache.size + this.#baseRowCache.size
+                    + this.#selectedRowCache.size + this.#finalRowCache.size,
+            },
+        };
+        this.#frame = frame;
+        return frame;
+    }
+    /** Reuses an established transcript frame when only same-height dock rows changed. */
+    composeDockOnly(dockRows, width, height) {
+        const previous = this.#frame;
+        const boundedWidth = Math.max(1, width);
+        const boundedHeight = Math.max(0, height);
+        if (previous === null || previous.descriptor.width !== boundedWidth || previous.descriptor.height !== boundedHeight
+            || previous.descriptor.selectionRevision !== this.#selectionRevision || this.#selection !== undefined)
+            return null;
+        const dock = dockRows.length > boundedHeight ? dockRows.slice(-boundedHeight) : [...dockRows];
+        const viewportHeight = Math.max(0, boundedHeight - dock.length);
+        const expectedDock = dock.length === 0 ? null : { rowStart: viewportHeight + 1, rowEnd: boundedHeight };
+        const expectedTranscript = viewportHeight === 0 ? null : { rowStart: 1, rowEnd: viewportHeight };
+        if (!sameRectangle(previous.descriptor.dock, expectedDock)
+            || !sameRectangle(previous.descriptor.transcript, expectedTranscript))
+            return null;
+        const descriptor = {
+            frameId: ++this.#frameId,
+            width: boundedWidth,
+            height: boundedHeight,
+            transcript: expectedTranscript,
+            dock: expectedDock,
+            previousDocumentRange: previous.descriptor.nextDocumentRange,
+            nextDocumentRange: previous.descriptor.nextDocumentRange,
+            previousFollowingEnd: previous.followingEnd,
+            followingEnd: previous.followingEnd,
+            transientRowCount: previous.descriptor.transientRowCount,
+            transientAlignmentGapRows: previous.descriptor.transientAlignmentGapRows,
+            bottomAlignedTailRowCount: previous.descriptor.bottomAlignedTailRowCount,
+            liveTailRows: previous.descriptor.liveTailRows,
+            verticalShiftRows: 0,
+            safeVerticalShift: false,
+            selectionRevision: this.#selectionRevision,
+            selectionDamagedRows: [],
+            cause: "dock-input",
+        };
+        assertTranscriptViewportFrameDescriptor(descriptor);
+        this.#selectionRows = [...this.#selectionRows.slice(0, viewportHeight), ...dock].slice(0, boundedHeight);
+        const frame = {
+            rows: [...previous.rows.slice(0, viewportHeight), ...dock].slice(0, boundedHeight),
+            contentWidth: previous.contentWidth,
+            scrollTop: previous.scrollTop,
+            maxScroll: previous.maxScroll,
+            followingEnd: previous.followingEnd,
+            hits: previous.hits,
+            descriptor,
+            selectionDamage: {
+                revision: this.#selectionRevision,
+                recomputedRows: [],
+                reusedRows: Array.from({ length: viewportHeight }, (_, index) => index + 1),
+                cacheEntries: previous.selectionDamage.cacheEntries,
+            },
+        };
+        this.#frame = frame;
+        return frame;
+    }
+    #functionId(value) {
+        const existing = this.#functionIds.get(value);
+        if (existing !== undefined)
+            return existing;
+        const id = this.#nextFunctionId;
+        this.#nextFunctionId += 1;
+        this.#functionIds.set(value, id);
+        return id;
+    }
+    #selectionAnchorAt(line) {
+        if (line < 0 || line >= this.#selectionRows.length)
+            return undefined;
+        if (line < this.#viewportHeight) {
+            const existing = this.#selectionRowAnchors[line];
+            if (this.#frame?.scrollTop === this.#scrollTop)
+                return existing;
+            // Concurrency: selection edge auto-scroll updates scrollTop before the next frame is
+            // composed. Resolve ordinary viewport rows from that latest position instead of stale paint.
+            const documentRow = this.#scrollTop + line;
+            if (documentRow >= 0 && documentRow < this.#documentRows.length) {
+                return documentSelectionAnchor(documentRow, this.#documentRows[documentRow] ?? "");
+            }
+        }
+        return this.#selectionRowAnchors[line];
+    }
+    #projectSelection(documentRows, dockRows, height) {
+        const selection = this.#selection;
+        const anchors = this.#selectionAnchors;
+        if (selection === undefined || anchors === undefined)
+            return;
+        const project = (anchor) => {
+            if (anchor.kind === "dock") {
+                const dockIndex = dockRows.length - anchor.fromBottom - 1;
+                return dockIndex < 0 || dockIndex >= dockRows.length
+                    ? undefined
+                    : { line: height - dockRows.length + dockIndex, anchor };
+            }
+            if (anchor.kind === "screen") {
+                return anchor.row < 0 || anchor.row >= this.#selectionRows.length
+                    || this.#selectionRows[anchor.row] !== anchor.source
+                    ? undefined
+                    : { line: anchor.row, anchor };
+            }
+            if (anchor.row >= 0 && anchor.row < documentRows.length
+                && stripAnsi(documentRows[anchor.row] ?? "").trimEnd() === anchor.identity) {
+                const current = documentSelectionAnchor(anchor.row, documentRows[anchor.row] ?? "");
+                const visible = this.#selectionRowAnchors.findIndex(candidate => candidate?.kind === "document"
+                    && candidate.row === current.row && candidate.identity === current.identity);
+                return { line: visible >= 0 ? visible : current.row - this.#scrollTop, anchor: current };
+            }
+            // Invariant: reflow may move a retained source row, but remapping is allowed only when
+            // that exact source has one visible identity. Ambiguous or off-screen replacement clears it.
+            const visibleMatches = this.#selectionRowAnchors
+                .map((candidate, line) => ({ candidate, line }))
+                .filter((entry) => entry.candidate?.kind === "document" && entry.candidate.identity === anchor.identity);
+            return visibleMatches.length === 1
+                ? { line: visibleMatches[0].line, anchor: visibleMatches[0].candidate }
+                : undefined;
+        };
+        const projectedAnchor = project(anchors.anchor);
+        const projectedHead = project(anchors.head);
+        if (projectedAnchor === undefined || projectedHead === undefined) {
+            this.clearSelection();
+            return;
+        }
+        this.#selectionAnchors = { anchor: projectedAnchor.anchor, head: projectedHead.anchor };
+        if (selection.anchor.line === projectedAnchor.line && selection.head.line === projectedHead.line)
+            return;
+        this.#selection = {
+            ...selection,
+            anchor: { ...selection.anchor, line: projectedAnchor.line },
+            head: { ...selection.head, line: projectedHead.line },
+        };
+    }
+    #visibleSelection() {
+        const rows = this.#selectionAnchors?.anchor.kind === "document" ? this.#viewportHeight : this.#selectionRows.length;
+        return visibleTextSelection(orderedTextSelection(this.#selection), rows, this.#firstSelectableRow);
+    }
+    #updateCopyableSelection() {
+        this.#copyableSelection = this.selectedText() !== null;
+    }
+}
+function visibleTextSelection(selection, rowCount, firstRow) {
+    if (selection === undefined || rowCount <= firstRow || selection.end.line < firstRow || selection.start.line >= rowCount)
+        return undefined;
+    const startLine = Math.max(firstRow, selection.start.line);
+    const endLine = Math.min(rowCount - 1, selection.end.line);
+    return {
+        start: {
+            line: startLine,
+            column: selection.start.line < firstRow ? 0 : selection.start.column,
+        },
+        end: {
+            line: endLine,
+            column: selection.end.line >= rowCount ? Number.MAX_SAFE_INTEGER : selection.end.column,
+        },
+        ...(selection.fullRow ? { fullRow: true } : {}),
+        ...(selection.throughFinalColumn ? { throughFinalColumn: true } : {}),
+    };
+}
+function selectionRangeForLine(selection, documentLine, selectableRowCount, width) {
+    if (selection === undefined || documentLine >= selectableRowCount
+        || documentLine < selection.start.line || documentLine > selection.end.line)
+        return null;
+    const fullVisualRow = selection.fullRow === true
+        || (selection.start.line !== selection.end.line
+            && documentLine !== selection.start.line
+            && documentLine !== selection.end.line);
+    const from = fullVisualRow || documentLine !== selection.start.line
+        ? 0
+        : selection.start.column;
+    const throughFinalColumn = documentLine === selection.end.line && selection.throughFinalColumn === true;
+    const to = fullVisualRow || documentLine !== selection.end.line || throughFinalColumn
+        ? width
+        : selection.end.column;
+    const boundedFrom = clamp(from, 0, width);
+    const boundedTo = clamp(to, boundedFrom, width);
+    return boundedTo > boundedFrom ? { from: boundedFrom, to: boundedTo } : null;
+}
+function cachedString(cache, key, limit, create) {
+    const existing = cache.get(key);
+    if (existing !== undefined) {
+        cache.delete(key);
+        cache.set(key, existing);
+        return { value: existing, reused: true };
+    }
+    const value = create();
+    cache.set(key, value);
+    while (cache.size > limit)
+        cache.delete(cache.keys().next().value);
+    return { value, reused: false };
+}
+function trimCache(cache, limit) {
+    while (cache.size > limit)
+        cache.delete(cache.keys().next().value);
+}
+/**
+ * Rows of the streaming block that the visible window actually shows. Gap insertion happens
+ * after the selectable document, so live-block indices need no adjustment here.
+ */
+function visibleLiveTailRows(liveTailStartRow, selectableDocumentRowCount, scrollTop, viewportHeight) {
+    if (liveTailStartRow === undefined || !Number.isSafeInteger(liveTailStartRow))
+        return 0;
+    const start = clamp(liveTailStartRow, 0, selectableDocumentRowCount);
+    const visibleStart = Math.max(start, scrollTop);
+    const visibleEnd = Math.min(selectableDocumentRowCount, scrollTop + viewportHeight);
+    return Math.max(0, visibleEnd - visibleStart);
+}
+function governingPrompt(anchors, scrollTop) {
+    let result = null;
+    for (const anchor of anchors) {
+        if (anchor.firstRow > scrollTop)
+            break;
+        result = anchor;
+    }
+    return result;
+}
+function padViewportRowWithGutter(line, contentWidth, frameWidth) {
+    const boundedContentWidth = Math.min(Math.max(1, contentWidth), frameWidth);
+    const content = padRowPreservingBackground(line, boundedContentWidth);
+    const gutterWidth = frameWidth - boundedContentWidth;
+    if (gutterWidth === 0)
+        return content;
+    // Invariant: render no source glyph beyond contentWidth, but reuse the established
+    // row-padding background before stripping source foreground, links, and emphasis.
+    const gutterStyle = explicitBackgroundPaddingStyle(line);
+    return `${content}${GUTTER_DECORATION_RESET}${gutterStyle?.on ?? ""}${" ".repeat(gutterWidth)}${gutterStyle?.off ?? ""}`;
+}
+function explicitBackgroundPaddingStyle(line) {
+    const background = /\u001b\[(?:4[0-8]|10[0-7]|48;(?:2;\d+;\d+;\d+|5;\d+))m/.exec(line)?.[0];
+    return background === undefined ? null : { on: background, off: "\u001b[49m" };
+}
+function rowPaddingStyle(line) {
+    const background = explicitBackgroundPaddingStyle(line);
+    if (background !== null)
+        return background;
+    const reverse = /\u001b\[(?:7(?:;[0-9]+)*|[0-9;]*;7(?:;[0-9]+)*)m/.exec(line)?.[0];
+    return reverse === undefined ? null : { on: reverse, off: "\u001b[27m" };
+}
+function padRowPreservingBackground(line, width) {
+    const shown = displayWidth(line) > width ? truncateToWidth(line, width) : line;
+    const padding = Math.max(0, width - displayWidth(shown));
+    if (padding === 0)
+        return shown;
+    const style = rowPaddingStyle(line);
+    return style === null
+        ? shown + " ".repeat(padding)
+        : `${shown}${style.on}${" ".repeat(padding)}${style.off}`;
+}
+export function assertTranscriptViewportFrameDescriptor(descriptor) {
+    if (!Number.isSafeInteger(descriptor.frameId) || descriptor.frameId < 1)
+        throw new TypeError("viewport frame descriptor identity is invalid");
+    if (!Number.isSafeInteger(descriptor.width) || descriptor.width < 1)
+        throw new TypeError("viewport frame descriptor width is invalid");
+    if (!Number.isSafeInteger(descriptor.height) || descriptor.height < 0)
+        throw new TypeError("viewport frame descriptor height is invalid");
+    assertRectangle(descriptor.transcript, descriptor.height, "transcript");
+    assertRectangle(descriptor.dock, descriptor.height, "dock");
+    if (descriptor.transcript !== null && descriptor.dock !== null && descriptor.transcript.rowEnd >= descriptor.dock.rowStart) {
+        throw new TypeError("viewport frame descriptor regions overlap");
+    }
+    assertDocumentRange(descriptor.nextDocumentRange, "next");
+    if (descriptor.previousDocumentRange !== null)
+        assertDocumentRange(descriptor.previousDocumentRange, "previous");
+    if (!Number.isSafeInteger(descriptor.transientRowCount) || descriptor.transientRowCount < 0
+        || !Number.isSafeInteger(descriptor.transientAlignmentGapRows) || descriptor.transientAlignmentGapRows < 0
+        || !Number.isSafeInteger(descriptor.bottomAlignedTailRowCount) || descriptor.bottomAlignedTailRowCount < 0
+        || descriptor.transientAlignmentGapRows + descriptor.bottomAlignedTailRowCount > descriptor.transientRowCount) {
+        throw new TypeError("viewport frame descriptor transient geometry is invalid");
+    }
+    const transcriptHeight = descriptor.transcript === null
+        ? 0
+        : descriptor.transcript.rowEnd - descriptor.transcript.rowStart + 1;
+    if (!Number.isSafeInteger(descriptor.liveTailRows) || descriptor.liveTailRows < 0
+        || descriptor.liveTailRows > transcriptHeight) {
+        throw new TypeError("viewport frame descriptor live tail is invalid");
+    }
+    if (!Number.isSafeInteger(descriptor.verticalShiftRows))
+        throw new TypeError("viewport frame descriptor shift is invalid");
+    if (descriptor.previousDocumentRange === null && descriptor.verticalShiftRows !== 0) {
+        throw new TypeError("viewport frame descriptor initial shift is invalid");
+    }
+    if (descriptor.previousDocumentRange !== null
+        && descriptor.verticalShiftRows !== descriptor.nextDocumentRange.start - descriptor.previousDocumentRange.start) {
+        throw new TypeError("viewport frame descriptor shift disagrees with document ranges");
+    }
+    if (descriptor.safeVerticalShift && (descriptor.verticalShiftRows <= 0
+        || descriptor.previousFollowingEnd !== true
+        || !descriptor.followingEnd
+        || descriptor.cause !== "follow-shift")) {
+        throw new TypeError("viewport frame descriptor marks an unsafe shift");
+    }
+    if (!Number.isSafeInteger(descriptor.selectionRevision) || descriptor.selectionRevision < 0) {
+        throw new TypeError("viewport frame descriptor selection revision is invalid");
+    }
+    if (descriptor.selectionDamagedRows.some((row, index) => !Number.isSafeInteger(row)
+        || row < 1 || row > descriptor.height || (index > 0 && row <= descriptor.selectionDamagedRows[index - 1]))) {
+        throw new TypeError("viewport frame descriptor selection damage is invalid");
+    }
+}
+function assertRectangle(rectangle, height, label) {
+    if (rectangle === null)
+        return;
+    if (!Number.isSafeInteger(rectangle.rowStart) || !Number.isSafeInteger(rectangle.rowEnd)
+        || rectangle.rowStart < 1 || rectangle.rowEnd < rectangle.rowStart || rectangle.rowEnd > height) {
+        throw new TypeError(`viewport frame descriptor ${label} region is invalid`);
+    }
+}
+function assertDocumentRange(range, label) {
+    if (!Number.isSafeInteger(range.start) || !Number.isSafeInteger(range.end) || range.start < 0 || range.end < range.start) {
+        throw new TypeError(`viewport frame descriptor ${label} document range is invalid`);
+    }
+}
+function sameRectangle(left, right) {
+    return left === null ? right === null : right !== null && left.rowStart === right.rowStart && left.rowEnd === right.rowEnd;
+}
+function clamp(value, minimum, maximum) {
+    return Math.min(Math.max(value, minimum), maximum);
+}