@timurproko/a1 0.1.8-dev.49ff83a → 0.1.8-dev.508

package/dist/integrations/pi/tui-runtime/contracts.d.ts

@@ -0,0 +1,156 @@
+import type { PresentationComponentPort, PresentationPointerSurface } from "../../../contracts/presentation/index.js";
+import type { PiTuiInputCoordinationDecision, PiTuiInputCoordinationScheduler, PiTuiInputSurfaceKind } from "./input-presentation-coordinator.js";
+export type PiTuiRuntimeState = "idle" | "running" | "stopping" | "stopped" | "failed";
+export interface PiTuiViewport {
+    readonly columns: number;
+    readonly rows: number;
+}
+export interface PiTuiScrollState {
+    readonly scrollTop: number;
+    readonly viewportHeight: number;
+    readonly followingEnd: boolean;
+    readonly scrollbarVisible: boolean;
+}
+export type PiTuiPointerSurface = PresentationPointerSurface;
+export interface PiTuiComponentPort extends PresentationComponentPort {
+    readonly wantsKeyRelease?: boolean;
+}
+export interface PiTuiTerminalPort {
+    start(onInput: (data: string) => void, onResize: () => void): void;
+    stop(): void;
+    drainInput(maxMs?: number, idleMs?: number): Promise<void>;
+    write(data: string): void;
+    readonly columns: number;
+    readonly rows: number;
+    readonly kittyProtocolActive: boolean;
+    moveBy(lines: number): void;
+    hideCursor(): void;
+    showCursor(): void;
+    clearLine(): void;
+    clearFromCursor(): void;
+    clearScreen(): void;
+    setTitle(title: string): void;
+    setProgress(active: boolean): void;
+}
+export type PiTuiSizeValue = number | `${number}%`;
+export type PiTuiOverlayAnchor = "center" | "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top-center" | "bottom-center" | "left-center" | "right-center";
+export interface PiTuiOverlayMargin {
+    readonly top?: number;
+    readonly right?: number;
+    readonly bottom?: number;
+    readonly left?: number;
+}
+export interface PiTuiOverlayOptions {
+    readonly width?: PiTuiSizeValue;
+    readonly minWidth?: number;
+    readonly maxHeight?: PiTuiSizeValue;
+    readonly anchor?: PiTuiOverlayAnchor;
+    readonly offsetX?: number;
+    readonly offsetY?: number;
+    readonly row?: PiTuiSizeValue;
+    readonly col?: PiTuiSizeValue;
+    readonly margin?: PiTuiOverlayMargin | number;
+    readonly visible?: (columns: number, rows: number) => boolean;
+    readonly nonCapturing?: boolean;
+    /** A1-owned input scheduling declaration; omitted extension overlays fail closed. */
+    readonly inputCoordination?: Exclude<PiTuiInputSurfaceKind, "editor">;
+}
+export interface PiTuiOverlayUnfocusOptions {
+    readonly target: PiTuiComponentPort | null;
+}
+export interface PiTuiOverlayHandle {
+    hide(): void;
+    setHidden(hidden: boolean): void;
+    isHidden(): boolean;
+    focus(): void;
+    unfocus(options?: PiTuiOverlayUnfocusOptions): void;
+    isFocused(): boolean;
+    /** The most recently rendered terminal-relative rectangle of a visible overlay. */
+    getBounds(): {
+        readonly row: number;
+        readonly col: number;
+        readonly width: number;
+        readonly height: number;
+    } | undefined;
+}
+export interface PiTuiInputListenerResult {
+    readonly consume?: boolean;
+    readonly data?: string;
+}
+export type PiTuiInputListener = (data: string) => PiTuiInputListenerResult | undefined;
+/** Runs at the terminal bridge before Pi TUI receives physical input. */
+export type PiTuiPreInputListener = PiTuiInputListener;
+export interface PiTuiLayoutEntry {
+    readonly node: PiTuiLayoutNode;
+    readonly basis?: number | "auto";
+    readonly grow?: number;
+    readonly shrink?: number;
+    readonly minSize?: number;
+    readonly maxSize?: number;
+    readonly visible?: (viewport: PiTuiViewport) => boolean;
+}
+export type PiTuiLayoutNode = {
+    readonly type: "component";
+    readonly component: PiTuiComponentPort;
+} | {
+    readonly type: "stack";
+    readonly direction: "vertical" | "horizontal";
+    readonly children: readonly PiTuiLayoutEntry[];
+    readonly gap?: number;
+    readonly align?: "stretch" | "start" | "center" | "end";
+} | {
+    readonly type: "scroll";
+    readonly id: string;
+    readonly child: PiTuiLayoutNode;
+    readonly follow?: "none" | "end";
+    readonly primary?: boolean;
+    readonly overscroll?: "chain" | "contain";
+    readonly scrollbar?: "hidden" | "auto" | "always";
+    /** Styles the scrollbar track; the pinned runtime draws it as foreground text. */
+    readonly scrollbarTrackStyle?: (text: string) => string;
+    /** Styles the scrollbar thumb; the pinned runtime draws it as foreground text. */
+    readonly scrollbarThumbStyle?: (text: string) => string;
+    readonly scrollbarHideDelayMs?: number;
+};
+export type PiTuiInputDiagnosticsPhase = "receipt" | "semantic-start" | "semantic-end" | "composition-start" | "composition-end" | "write-start" | "write-end";
+export interface PiTuiInputDiagnosticsEvent {
+    readonly phase: PiTuiInputDiagnosticsPhase;
+    readonly revision: number;
+    readonly atMs: number;
+    readonly pendingDepth: number;
+    readonly pendingPresentationDepth: 0 | 1;
+    readonly appliedRevision: number;
+}
+export interface PiTuiRuntimeAdapterOptions {
+    readonly root: PiTuiComponentPort;
+    /** Bare viewport only: painted overlays in back-to-front order; null while geometry is stale. */
+    readonly onOverlayGeometry?: (surfaces: readonly PiTuiPointerSurface[] | null) => void;
+    readonly mode?: "regular" | "fullscreen";
+    readonly layoutRoot?: PiTuiLayoutNode;
+    readonly terminal?: PiTuiTerminalPort;
+    /** A1-owned public-boundary decorator; comparison paths omit it. */
+    readonly decorateTerminal?: (terminal: PiTuiTerminalPort) => PiTuiTerminalPort;
+    /** Bare-custom-viewport scheduling policy; comparison paths omit it. */
+    readonly inputCoordination?: {
+        readonly classify: (data: string, focusedOverlay?: Exclude<PiTuiInputSurfaceKind, "editor">) => PiTuiInputCoordinationDecision;
+        readonly onReceipt?: () => void;
+        readonly scheduler?: PiTuiInputCoordinationScheduler;
+    };
+    /** Optional bounded evidence hook. Production composition omits it. */
+    readonly inputDiagnostics?: {
+        readonly onEvent: (event: PiTuiInputDiagnosticsEvent) => void;
+        readonly now?: () => number;
+    };
+    readonly hardwareCursor?: boolean;
+    readonly mouse?: boolean;
+    readonly wheelScrollLines?: number;
+    readonly openUrl?: (url: string) => void;
+    readonly onRightClickPaste?: () => void;
+    readonly logDirectory?: string;
+}
+export interface PiTuiStopOptions {
+    readonly preserveScreen?: boolean;
+    readonly drainInput?: boolean;
+    readonly drainMaxMs?: number;
+    readonly drainIdleMs?: number;
+}

package/dist/integrations/pi/tui-runtime/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/integrations/pi/tui-runtime/damage-aware-terminal.d.ts

@@ -0,0 +1,88 @@
+import type { PiTuiTerminalPort } from "./contracts.js";
+export declare const PINNED_PI_TUI_DAMAGE_GRAMMAR = "@earendil-works/pi-tui@0.85.1:tui-alt-screen-one-write-v1";
+export interface PiTuiDamageFrameDescriptor {
+    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;
+    /**
+     * Visible rows owned by the block that is currently streaming. A live block repaints
+     * every row it owns when it reflows, so the allowed damage follows the declared tail
+     * instead of assuming a one-row tail.
+     */
+    readonly liveTailRows?: number;
+    readonly verticalShiftRows: number;
+    readonly safeVerticalShift: boolean;
+    readonly cause: string;
+}
+export interface PiTuiDamageFrameSafety {
+    readonly overlayActive: boolean;
+    readonly selectionActive: boolean;
+    readonly replacementSurfaceActive: boolean;
+}
+export type PiTuiDamageDecisionReason = "transformed" | "suppressed-redundant-clear" | "hyperlink-cleanup" | "pending-hyperlink-cleanup" | "not-armed" | "unsafe-frame" | "stale-frame" | "unsupported-region-scroll" | "geometry-mismatch" | "grammar-mismatch" | "unsafe-terminal-content" | "incomplete-prior-frame" | "excessive-real-damage";
+export interface PiTuiDamageDecision {
+    readonly frameId: number | null;
+    readonly transformed: boolean;
+    readonly reason: PiTuiDamageDecisionReason;
+    readonly shiftRows: number;
+    readonly paintedRows: readonly number[];
+}
+export interface DamageAwareTerminalOptions {
+    readonly regionalScroll: boolean;
+    /** The shell supplies visible-row analysis; the terminal layer owns no UI parser. */
+    readonly inspectHyperlinks: (content: string) => {
+        readonly ranges: readonly unknown[];
+        readonly hasExplicitLink: boolean;
+        readonly signature: string;
+        readonly replaySafe: boolean;
+        readonly width: number;
+    };
+    readonly onResize?: () => void;
+    readonly onHyperlinkCleanupRequired?: () => void;
+}
+/**
+ * A fail-closed adapter for one pinned Pi fullscreen write grammar. Semantic
+ * viewport metadata authorizes a shift; bytes are inspected only to validate
+ * and preserve Pi's complete row paint and cursor syntax.
+ */
+export declare class DamageAwareTerminalAdapter implements PiTuiTerminalPort {
+    #private;
+    readonly inner: PiTuiTerminalPort;
+    readonly options: DamageAwareTerminalOptions;
+    constructor(inner: PiTuiTerminalPort, options: DamageAwareTerminalOptions);
+    get columns(): number;
+    get rows(): number;
+    get kittyProtocolActive(): boolean;
+    get lastDecision(): PiTuiDamageDecision;
+    get hyperlinkCleanupPending(): boolean;
+    /**
+     * The rows as last forwarded to the terminal, top to bottom, with styling
+     * intact. A row the adapter has not seen since its last invalidation is empty.
+     * The quit outro animates over this snapshot because it is what the terminal
+     * shows, not what a fresh render would produce.
+     */
+    presentedRows(): readonly string[];
+    /** Latches the former link rows, including rows whose replacement contains no link. */
+    requestHyperlinkCleanup(rows?: readonly number[]): void;
+    arm(descriptor: PiTuiDamageFrameDescriptor, safety: PiTuiDamageFrameSafety): void;
+    start(onInput: (data: string) => void, onResize: () => void): void;
+    stop(): void;
+    drainInput(maxMs?: number, idleMs?: number): Promise<void>;
+    write(data: string): void;
+    moveBy(lines: number): void;
+    hideCursor(): void;
+    showCursor(): void;
+    clearLine(): void;
+    clearFromCursor(): void;
+    clearScreen(): void;
+    setTitle(title: string): void;
+    setProgress(active: boolean): void;
+}

package/dist/integrations/pi/tui-runtime/damage-aware-terminal.js

@@ -0,0 +1,433 @@
+export const PINNED_PI_TUI_DAMAGE_GRAMMAR = "@earendil-works/pi-tui@0.85.1:tui-alt-screen-one-write-v1";
+const BEGIN_SYNCHRONIZED_OUTPUT = "\u001b[?2026h";
+const END_SYNCHRONIZED_OUTPUT = "\u001b[?2026l";
+const ROW_MARKER = /\u001b\[(\d+);1H\u001b\[2K/gu;
+const CURSOR_SUFFIX = /(?:\u001b\[(\d+);(\d+)H)?\u001b\[\?25[hl]\u001b\[\?2026l$/u;
+const OUT_OF_BAND = /^(?:\u001b\](?:0|2|9|52);[^\u0007\u001b]*(?:\u0007|\u001b\\)|\u001b\[\?25[hl])+$/u;
+/**
+ * A fail-closed adapter for one pinned Pi fullscreen write grammar. Semantic
+ * viewport metadata authorizes a shift; bytes are inspected only to validate
+ * and preserve Pi's complete row paint and cursor syntax.
+ */
+export class DamageAwareTerminalAdapter {
+    #rows = new Map();
+    #links = new Map();
+    #cleanupRevision = 0;
+    #cleanupRows = new Set();
+    #cleanupNeedsCompleteFrame = false;
+    #cleanedRevision = 0;
+    #recoveryRevision = 0;
+    #epoch = 0;
+    #armed;
+    #lastConsumedFrameId = 0;
+    #cacheWidth = 0;
+    #cacheHeight = 0;
+    #decision = {
+        frameId: null,
+        transformed: false,
+        reason: "not-armed",
+        shiftRows: 0,
+        paintedRows: [],
+    };
+    inner;
+    options;
+    constructor(inner, options) { this.inner = inner; this.options = options; }
+    get columns() { return this.inner.columns; }
+    get rows() { return this.inner.rows; }
+    get kittyProtocolActive() { return this.inner.kittyProtocolActive; }
+    get lastDecision() { return this.#decision; }
+    get hyperlinkCleanupPending() { return this.#cleanupRevision > this.#cleanedRevision; }
+    /**
+     * The rows as last forwarded to the terminal, top to bottom, with styling
+     * intact. A row the adapter has not seen since its last invalidation is empty.
+     * The quit outro animates over this snapshot because it is what the terminal
+     * shows, not what a fresh render would produce.
+     */
+    presentedRows() {
+        const presented = [];
+        for (let row = 1; row <= this.rows; row += 1)
+            presented.push(this.#rows.get(row) ?? "");
+        return presented;
+    }
+    /** Latches the former link rows, including rows whose replacement contains no link. */
+    requestHyperlinkCleanup(rows) {
+        this.#cleanupRevision += 1;
+        if (rows !== undefined) {
+            for (const row of rows) {
+                if (Number.isSafeInteger(row) && row >= 1 && row <= this.rows)
+                    this.#cleanupRows.add(row);
+            }
+        }
+        else {
+            // Invariant: no known pointer is not proof of no host-hover decoration. Unscoped
+            // removal/invalidation repairs every previously linked row, not every screen row.
+            for (const [row, state] of this.#links)
+                if (state.ranges.length > 0)
+                    this.#cleanupRows.add(row);
+        }
+    }
+    arm(descriptor, safety) {
+        this.#armed = { descriptor, safety };
+    }
+    start(onInput, onResize) {
+        this.inner.start(onInput, () => {
+            this.#epoch += 1;
+            this.#recoveryRevision = 0;
+            this.#invalidatePresentation();
+            this.options.onResize?.();
+            onResize();
+        });
+    }
+    stop() {
+        this.#epoch += 1;
+        this.#armed = undefined;
+        this.#cleanupRevision = this.#cleanedRevision = this.#recoveryRevision = 0;
+        this.#cleanupRows.clear();
+        this.#cleanupNeedsCompleteFrame = false;
+        this.#lastConsumedFrameId = 0;
+        this.#invalidateRows();
+        this.inner.stop();
+    }
+    drainInput(maxMs, idleMs) { return this.inner.drainInput(maxMs, idleMs); }
+    write(data) {
+        const armed = this.#armed;
+        this.#armed = undefined;
+        const parsed = parsePinnedFullscreenWrite(data);
+        if (armed !== undefined && armed.descriptor.frameId <= this.#lastConsumedFrameId) {
+            // Concurrency: a recognized obsolete frame must never repaint newer cells,
+            // acknowledge cleanup, or become the reference for a subsequent differential.
+            this.#decision = this.#decide(armed, parsed);
+            return;
+        }
+        const sameGeometry = this.#cacheWidth === this.columns && this.#cacheHeight === this.rows;
+        const unknownPaint = parsed === null && !OUT_OF_BAND.test(data);
+        if (!sameGeometry || unknownPaint)
+            this.#invalidatePresentation();
+        if (unknownPaint && !this.hyperlinkCleanupPending && this.options.inspectHyperlinks(data).ranges.length > 0) {
+            this.requestHyperlinkCleanup();
+            this.#cleanupNeedsCompleteFrame = true;
+        }
+        // Invariant: a deliberate same-geometry reset discards presented link state. Ordinary streamed
+        // row changes are not cleanup requests: candidate-looking text is not terminal state.
+        if (sameGeometry && parsed?.structuralPrefix === "\u001b[2J"
+            && hasCompleteScreenRows(parsed.rows, this.rows) && !this.hyperlinkCleanupPending
+            && !this.#hasSameHyperlinkState(parsed.rows))
+            this.requestHyperlinkCleanup();
+        const decision = this.#decide(armed, parsed);
+        const coveredRevision = this.#cleanupRevision;
+        const cleanup = this.hyperlinkCleanupPending && parsed !== null
+            && (armed === undefined || (armed.descriptor.width === this.columns && armed.descriptor.height === this.rows))
+            ? this.#boundedCleanupFrame(parsed) : null;
+        const epoch = this.#epoch;
+        let output = data;
+        if (cleanup !== null) {
+            output = buildCompleteWrite(cleanup);
+            this.#decision = {
+                frameId: armed?.descriptor.frameId ?? null, transformed: output !== data,
+                reason: "hyperlink-cleanup", shiftRows: 0, paintedRows: cleanup.rows.map(row => row.row),
+            };
+        }
+        else {
+            this.#decision = decision;
+            if (decision.reason === "suppressed-redundant-clear" && parsed !== null) {
+                output = buildClearlessWrite(parsed, this.#rows);
+            }
+            else if (decision.transformed && armed !== undefined && parsed !== null) {
+                output = buildDamageWrite(parsed, armed.descriptor, new Set(decision.paintedRows), this.#rows);
+            }
+        }
+        this.inner.write(output);
+        if (epoch !== this.#epoch
+            || (armed !== undefined && this.#lastConsumedFrameId !== armed.descriptor.frameId))
+            return;
+        // Invariant: cache invalidation follows forwarded bytes, not a suppressed clear.
+        // A bounded cleanup preserves prior rows and publishes all changed or invalidated rows.
+        this.#rememberFrame(armed?.descriptor, cleanup ?? parsed, output);
+        if (cleanup !== null) {
+            this.#cleanedRevision = Math.max(this.#cleanedRevision, coveredRevision);
+            if (this.#cleanupRevision === coveredRevision) {
+                this.#cleanupRows.clear();
+                this.#cleanupNeedsCompleteFrame = false;
+            }
+        }
+        this.#scheduleCleanupRecovery();
+    }
+    moveBy(lines) { this.inner.moveBy(lines); }
+    hideCursor() { this.inner.hideCursor(); }
+    showCursor() { this.inner.showCursor(); }
+    clearLine() { this.#invalidatePresentation(); this.inner.clearLine(); }
+    clearFromCursor() { this.#invalidatePresentation(); this.inner.clearFromCursor(); }
+    clearScreen() { this.#invalidatePresentation(); this.inner.clearScreen(); }
+    setTitle(title) { this.inner.setTitle(title); }
+    setProgress(active) { this.inner.setProgress(active); }
+    #decide(armed, parsed) {
+        if (armed === undefined) {
+            return { frameId: null, transformed: false, reason: "not-armed", shiftRows: 0, paintedRows: [] };
+        }
+        const descriptor = armed.descriptor;
+        const base = {
+            frameId: descriptor.frameId,
+            transformed: false,
+            shiftRows: descriptor.verticalShiftRows,
+            paintedRows: [],
+        };
+        if (descriptor.frameId <= this.#lastConsumedFrameId)
+            return { ...base, reason: "stale-frame" };
+        this.#lastConsumedFrameId = descriptor.frameId;
+        if (this.hyperlinkCleanupPending)
+            return { ...base, reason: "pending-hyperlink-cleanup" };
+        if (parsed !== null && parsed.structuralPrefix === "\u001b[2J"
+            && this.#cacheWidth === descriptor.width && this.#cacheHeight === descriptor.height
+            && descriptor.width === this.columns && descriptor.height === this.rows
+            && hasCompleteScreenRows(parsed.rows, descriptor.height) && this.#hasSameHyperlinkState(parsed.rows)) {
+            return {
+                frameId: descriptor.frameId,
+                transformed: true,
+                reason: "suppressed-redundant-clear",
+                shiftRows: 0,
+                paintedRows: parsed.rows.map(row => row.row),
+            };
+        }
+        if (!descriptor.safeVerticalShift || armed.safety.overlayActive || armed.safety.selectionActive
+            || armed.safety.replacementSurfaceActive || descriptor.transcript === null) {
+            return { ...base, reason: "unsafe-frame" };
+        }
+        if (!this.options.regionalScroll)
+            return { ...base, reason: "unsupported-region-scroll" };
+        if (descriptor.width !== this.columns || descriptor.height !== this.rows
+            || descriptor.verticalShiftRows < 1
+            || descriptor.verticalShiftRows >= descriptor.transcript.rowEnd - descriptor.transcript.rowStart + 1) {
+            return { ...base, reason: "geometry-mismatch" };
+        }
+        if (parsed === null)
+            return { ...base, reason: "grammar-mismatch" };
+        if (parsed.structuralPrefix.length > 0
+            || hasUnsafeTerminalContent(parsed, this.options.inspectHyperlinks, descriptor.transcript)
+            || this.#hasExplicitLinkRisk(descriptor.transcript) || this.#hasUnsafeRows(descriptor.transcript)) {
+            return { ...base, reason: "unsafe-terminal-content" };
+        }
+        const { rowStart, rowEnd } = descriptor.transcript;
+        const desired = new Map(parsed.rows.map(row => [row.row, row.content]));
+        for (let row = rowStart; row <= rowEnd; row += 1) {
+            if (!desired.has(row) && !this.#rows.has(row))
+                return { ...base, reason: "incomplete-prior-frame" };
+            if (row <= rowEnd - descriptor.verticalShiftRows && !this.#rows.has(row + descriptor.verticalShiftRows)) {
+                return { ...base, reason: "incomplete-prior-frame" };
+            }
+        }
+        for (const row of parsed.rows) {
+            const inTranscript = row.row >= rowStart && row.row <= rowEnd;
+            const inDock = descriptor.dock !== null && row.row >= descriptor.dock.rowStart && row.row <= descriptor.dock.rowEnd;
+            if (!inTranscript && !inDock)
+                return { ...base, reason: "grammar-mismatch" };
+        }
+        const painted = new Set();
+        for (let row = rowStart; row <= rowEnd; row += 1) {
+            const source = row + descriptor.verticalShiftRows;
+            const desiredContent = desired.get(row) ?? this.#rows.get(row);
+            if (source > rowEnd || desiredContent !== this.#rows.get(source))
+                painted.add(row);
+        }
+        for (const row of parsed.rows) {
+            if (descriptor.dock !== null && row.row >= descriptor.dock.rowStart && row.row <= descriptor.dock.rowEnd)
+                painted.add(row.row);
+        }
+        // Rationale: a followed frame may repaint the live tail it declares, expose the shifted
+        // suffix, and restyle one sticky boundary row. A frame that declares no tail keeps the
+        // historical one-row allowance. Anything beyond that reaches settled rows and fails closed.
+        const liveTailRows = Math.max(1, descriptor.liveTailRows ?? 1);
+        if (painted.size > descriptor.verticalShiftRows + liveTailRows + 1 + countDockRows(parsed.rows, descriptor.dock)) {
+            return { ...base, reason: "excessive-real-damage" };
+        }
+        return {
+            frameId: descriptor.frameId,
+            transformed: true,
+            reason: "transformed",
+            shiftRows: descriptor.verticalShiftRows,
+            paintedRows: [...painted].sort((left, right) => left - right),
+        };
+    }
+    #rememberFrame(descriptor, parsed, raw) {
+        if (raw.includes("\u001b[2J") || raw.includes("\u001b[?1049") || raw.includes("\u001b_G") || raw.includes("\u001bPq")) {
+            this.#invalidateRows();
+        }
+        if (parsed === null)
+            return;
+        const width = descriptor?.width ?? this.columns;
+        const height = descriptor?.height ?? this.rows;
+        if (width !== this.#cacheWidth || height !== this.#cacheHeight) {
+            this.#invalidateRows();
+            this.#cacheWidth = width;
+            this.#cacheHeight = height;
+        }
+        if (parsed.rows.some(row => row.row > this.rows)) {
+            this.#invalidatePresentation();
+            return;
+        }
+        for (const row of parsed.rows) {
+            if (this.#rows.get(row.row) !== row.content)
+                this.#links.set(row.row, this.options.inspectHyperlinks(row.content));
+            this.#rows.set(row.row, row.content);
+        }
+    }
+    #hasSameHyperlinkState(rows) {
+        return rows.every(row => {
+            const previous = this.#links.get(row.row);
+            const next = row.content === this.#rows.get(row.row) ? previous : this.options.inspectHyperlinks(row.content);
+            return next?.replaySafe === true && (previous?.signature ?? "") === next.signature;
+        });
+    }
+    #hasExplicitLinkRisk(region) {
+        for (const [row, state] of this.#links) {
+            if (row >= region.rowStart && row <= region.rowEnd && state.hasExplicitLink)
+                return true;
+        }
+        return false;
+    }
+    #hasUnsafeRows(region) {
+        for (const [row, state] of this.#links) {
+            if (row >= region.rowStart && row <= region.rowEnd && !state.replaySafe)
+                return true;
+        }
+        return false;
+    }
+    #boundedCleanupFrame(parsed) {
+        const sameGeometry = this.#cacheWidth === this.columns && this.#cacheHeight === this.rows;
+        const complete = hasCompleteScreenRows(parsed.rows, this.rows);
+        if (this.#cleanupNeedsCompleteFrame && !complete)
+            return null;
+        const suppressReset = sameGeometry && !this.#cleanupNeedsCompleteFrame
+            && parsed.structuralPrefix === "\u001b[2J" && complete;
+        const structuralPrefix = suppressReset ? "" : parsed.structuralPrefix;
+        const desired = structuralPrefix.length === 0 ? new Map(this.#rows) : new Map();
+        const dirty = new Set([...this.#cleanupRows].filter(row => row <= this.rows));
+        for (const row of parsed.rows) {
+            if (row.row > this.rows)
+                return null;
+            desired.set(row.row, row.content);
+            if (structuralPrefix.length > 0 || this.#cleanupNeedsCompleteFrame
+                || this.#rows.get(row.row) !== row.content)
+                dirty.add(row.row);
+        }
+        // Invariant: validate all incoming rows before dropping an apparent redundant reset. Unknown
+        // content must pass through unchanged, never become a partially transformed frame.
+        for (const row of parsed.rows) {
+            const state = row.content === this.#rows.get(row.row) ? this.#links.get(row.row) : this.options.inspectHyperlinks(row.content);
+            if (state?.replaySafe !== true || state.width > this.columns)
+                return null;
+        }
+        const rows = [];
+        for (const row of [...dirty].sort((left, right) => left - right)) {
+            const content = desired.get(row);
+            if (content === undefined)
+                return null;
+            const state = content === this.#rows.get(row) ? this.#links.get(row) : this.options.inspectHyperlinks(content);
+            if (state?.replaySafe !== true || state.width > this.columns)
+                return null;
+            rows.push({ row, content, segment: `\u001b[${row};1H\u001b[2K${content}` });
+        }
+        // Invariant: only preserve a structural clear supplied by Pi; cleanup never manufactures one.
+        return { structuralPrefix, rows, cursorSuffix: parsed.cursorSuffix };
+    }
+    #scheduleCleanupRecovery() {
+        if (!this.hyperlinkCleanupPending || this.#recoveryRevision === this.#cleanupRevision
+            || this.options.onHyperlinkCleanupRequired === undefined)
+            return;
+        this.#recoveryRevision = this.#cleanupRevision;
+        const epoch = this.#epoch;
+        // Concurrency: force only after Pi finishes updating its previous-screen
+        // state. One recovery per revision avoids loops on unsupported image frames.
+        queueMicrotask(() => {
+            if (epoch === this.#epoch && this.hyperlinkCleanupPending)
+                this.options.onHyperlinkCleanupRequired?.();
+        });
+    }
+    #invalidatePresentation() {
+        if ([...this.#links.values()].some(state => state.ranges.length > 0) && !this.hyperlinkCleanupPending) {
+            this.requestHyperlinkCleanup();
+        }
+        // Invariant: after unknown paint or geometry loss, exact former row locations are no longer
+        // authoritative. Wait for a complete safe frame instead of guessing a partial repair.
+        if (this.hyperlinkCleanupPending)
+            this.#cleanupNeedsCompleteFrame = true;
+        this.#invalidateRows();
+    }
+    #invalidateRows() {
+        this.#rows.clear();
+        this.#links.clear();
+        this.#cacheWidth = 0;
+        this.#cacheHeight = 0;
+    }
+}
+function parsePinnedFullscreenWrite(data) {
+    if (!data.startsWith(BEGIN_SYNCHRONIZED_OUTPUT) || !data.endsWith(END_SYNCHRONIZED_OUTPUT))
+        return null;
+    const suffix = data.match(CURSOR_SUFFIX);
+    if (suffix?.index === undefined)
+        return null;
+    const body = data.slice(BEGIN_SYNCHRONIZED_OUTPUT.length, suffix.index);
+    const matches = [...body.matchAll(ROW_MARKER)];
+    if (matches.length === 0)
+        return body.length === 0
+            ? { structuralPrefix: "", rows: [], cursorSuffix: data.slice(suffix.index) } : null;
+    const structuralPrefix = body.slice(0, matches[0].index);
+    if (structuralPrefix !== "" && structuralPrefix !== "\u001b[2J")
+        return null;
+    const rows = [];
+    let previousRow = 0;
+    for (let index = 0; index < matches.length; index += 1) {
+        const match = matches[index];
+        const row = Number.parseInt(match[1], 10);
+        if (!Number.isSafeInteger(row) || row < 1 || row <= previousRow)
+            return null;
+        previousRow = row;
+        const start = match.index;
+        const contentStart = start + match[0].length;
+        const end = matches[index + 1]?.index ?? body.length;
+        const content = body.slice(contentStart, end);
+        rows.push({ row, content, segment: body.slice(start, end) });
+    }
+    return { structuralPrefix, rows, cursorSuffix: data.slice(suffix.index) };
+}
+function hasUnsafeTerminalContent(parsed, inspect, linkRegion) {
+    const data = parsed.rows.map(row => row.content).join("");
+    if (data.includes("\u001b_G") || data.includes("\u001bPq") || data.includes("\u001b[2J"))
+        return true;
+    return parsed.rows.some(row => {
+        if (linkRegion !== undefined && (row.row < linkRegion.rowStart || row.row > linkRegion.rowEnd))
+            return false;
+        const state = inspect(row.content);
+        return !state.replaySafe || state.hasExplicitLink;
+    });
+}
+function buildDamageWrite(parsed, descriptor, paintedRows, previousRows) {
+    const transcript = descriptor.transcript;
+    const regionShift = `\u001b[${transcript.rowStart};${transcript.rowEnd}r`
+        + `\u001b[${transcript.rowStart};1H`
+        + `\u001b[${descriptor.verticalShiftRows}S`
+        + "\u001b[r";
+    const parsedRows = new Map(parsed.rows.map(row => [row.row, row]));
+    const rowPaint = [...paintedRows].sort((left, right) => left - right).map(row => {
+        const parsedRow = parsedRows.get(row);
+        if (parsedRow !== undefined)
+            return parsedRow.segment;
+        return `\u001b[${row};1H\u001b[2K${previousRows.get(row) ?? ""}`;
+    }).join("");
+    return `${BEGIN_SYNCHRONIZED_OUTPUT}${regionShift}${rowPaint}${parsed.cursorSuffix}`;
+}
+/** Keeps required cleanup rows and current content in one synchronized transaction. */
+function buildCompleteWrite(parsed) {
+    return `${BEGIN_SYNCHRONIZED_OUTPUT}${parsed.structuralPrefix}${parsed.rows.map(row => row.segment).join("")}${parsed.cursorSuffix}`;
+}
+function buildClearlessWrite(parsed, previousRows) {
+    const changed = parsed.rows.filter(row => previousRows.get(row.row) !== row.content);
+    return `${BEGIN_SYNCHRONIZED_OUTPUT}${changed.map(row => row.segment).join("")}${parsed.cursorSuffix}`;
+}
+function hasCompleteScreenRows(rows, height) {
+    return rows.length === height && rows.every((row, index) => row.row === index + 1);
+}
+function countDockRows(rows, dock) {
+    if (dock === null)
+        return 0;
+    return rows.filter(row => row.row >= dock.rowStart && row.row <= dock.rowEnd).length;
+}