@timurproko/a1 0.1.8-dev.182 → 0.1.8-dev.218

package/dist/integrations/pi/session-ui/system-clipboard.js

@@ -28,7 +28,7 @@ export async function readSystemClipboardContent() {
                 return { kind: "image", ...image };
         }
         catch {
-            // Fall through to text and platform readers.
+            // Compatibility: fall through to text and platform readers.
         }
     }
     const text = await readSystemClipboardText();
@@ -48,7 +48,7 @@ export async function readSystemClipboardImage(reader) {
             }
         }
         catch {
-            // Older or partially available native bindings may still expose base64.
+            // Compatibility: older or partially available native bindings may still expose base64.
         }
     }
     if (reader.getImageBase64 !== undefined) {
@@ -59,13 +59,13 @@ export async function readSystemClipboardImage(reader) {
             });
         }
         catch {
-            // Fall through to the caller's text path.
+            // Compatibility: fall through to the caller's text path.
         }
     }
     return null;
 }
 export async function readSystemClipboardText() {
-    // Ctrl+C/Ctrl+X and Ctrl+V can arrive in adjacent input turns. Serialize the
+    // Concurrency: Ctrl+C/Ctrl+X and Ctrl+V can arrive in adjacent input turns. Serialize the
     // read behind our native write so paste never observes the previous value.
     await pendingClipboardWrite;
     if (process.platform === "win32" || process.platform === "darwin") {
@@ -77,7 +77,7 @@ export async function readSystemClipboardText() {
                     return text;
             }
             catch {
-                // Fall through to the platform command.
+                // Compatibility: fall through to the platform command.
             }
         }
     }
@@ -103,7 +103,7 @@ export function writeSystemClipboardText(text) {
                 return;
             }
             catch {
-                // The caller still emits its terminal clipboard fallback.
+                // Compatibility: the caller still emits its terminal clipboard fallback.
             }
         }
     };

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

@@ -1,9 +1,11 @@
 import type { PiTuiComponentPort, PiTuiInputListener, PiTuiOverlayHandle, PiTuiOverlayOptions, PiTuiPreInputListener, PiTuiRuntimeAdapterOptions, PiTuiRuntimeState, PiTuiScrollState, PiTuiStopOptions, PiTuiViewport } from "./contracts.js";
 export type PiTuiRuntimeErrorStage = "construction" | "start" | "input-drain" | "restoration";
+/** Identifies the Pi TUI lifecycle stage that failed while preserving the original cause. */
 export declare class PiTuiRuntimeError extends Error {
     readonly stage: PiTuiRuntimeErrorStage;
     constructor(stage: PiTuiRuntimeErrorStage, cause: unknown);
 }
+/** Bridges neutral presentation ports to one Pi TUI instance and owns terminal restoration on stop. */
 export declare class PiTuiRuntimeAdapter {
     #private;
     constructor(options: PiTuiRuntimeAdapterOptions);

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

@@ -1,4 +1,6 @@
 import { HStack, ProcessTerminal, ScrollView, TuiAltScreen, TuiMainScreen, VStack, visibleWidth, } from "#pi-tui";
+import { InputPresentationCoordinator, } from "./input-presentation-coordinator.js";
+/** Identifies the Pi TUI lifecycle stage that failed while preserving the original cause. */
 export class PiTuiRuntimeError extends Error {
     stage;
     constructor(stage, cause) {
@@ -9,9 +11,11 @@ export class PiTuiRuntimeError extends Error {
 }
 class ComponentBridge {
     port;
+    traceComposition;
     #focused = false;
-    constructor(port) {
+    constructor(port, traceComposition) {
         this.port = port;
+        this.traceComposition = traceComposition;
     }
     get focused() {
         return this.#focused;
@@ -24,12 +28,18 @@ class ComponentBridge {
         return this.port.wantsKeyRelease ?? false;
     }
     render(width) {
-        const lines = [...this.port.render(width)];
-        const overflow = lines.findIndex(line => visibleWidth(line) > width);
-        if (overflow >= 0) {
-            throw new RangeError(`Pi TUI component row ${overflow} exceeds available width ${width}`);
+        this.traceComposition?.("composition-start");
+        try {
+            const lines = [...this.port.render(width)];
+            const overflow = lines.findIndex(line => visibleWidth(line) > width);
+            if (overflow >= 0) {
+                throw new RangeError(`Pi TUI component row ${overflow} exceeds available width ${width}`);
+            }
+            return lines;
+        }
+        finally {
+            this.traceComposition?.("composition-end");
         }
-        return lines;
     }
     handleInput(data) {
         this.port.handleInput?.(data);
@@ -79,6 +89,7 @@ class OverlayHandleBridge {
         return !this.#disposed && this.handle.isFocused();
     }
 }
+/** Bridges neutral presentation ports to one Pi TUI instance and owns terminal restoration on stop. */
 export class PiTuiRuntimeAdapter {
     #terminal;
     #tuiTerminal;
@@ -92,8 +103,13 @@ export class PiTuiRuntimeAdapter {
     #mountedComponents = new Set();
     #scrollViews = new Map();
     #overlayDisposers = new Set();
+    #overlayInputCoordination = new Map();
     #inputListeners = new Map();
     #preInputListeners = new Set();
+    #inputCoordinator;
+    #inputDiagnostics;
+    #diagnosticNow;
+    #inputSink;
     #state = "idle";
     #stopPromise;
     #rootDisposed = false;
@@ -101,10 +117,39 @@ export class PiTuiRuntimeAdapter {
     constructor(options) {
         this.#root = options.root;
         this.#terminal = options.terminal ?? new ProcessTerminal();
-        this.#tuiTerminal = preInputTerminal(this.#terminal, data => this.#routePreInput(data));
+        this.#inputDiagnostics = options.inputDiagnostics;
+        this.#diagnosticNow = options.inputDiagnostics?.now ?? (() => performance.now());
+        const tracedTerminal = options.inputDiagnostics === undefined
+            ? this.#terminal
+            : diagnosticTerminal(this.#terminal, phase => this.#traceRuntimePhase(phase));
+        const decoratedTerminal = options.decorateTerminal?.(tracedTerminal) ?? tracedTerminal;
+        const coordination = options.inputCoordination ?? (options.inputDiagnostics === undefined
+            ? undefined
+            : { classify: () => "barrier" });
+        this.#inputCoordinator = coordination === undefined
+            ? undefined
+            : new InputPresentationCoordinator({
+                classify: data => coordination.classify(data, this.#focusedOverlayInputCoordination()),
+                deliver: data => {
+                    const routed = this.#routePreInput(data);
+                    if (routed.length > 0)
+                        this.#inputSink?.(routed);
+                },
+                ...(coordination.onReceipt === undefined ? {} : { onReceipt: coordination.onReceipt }),
+                ...(coordination.scheduler === undefined ? {} : { scheduler: coordination.scheduler }),
+                now: this.#diagnosticNow,
+                ...(options.inputDiagnostics === undefined ? {} : {
+                    onTrace: event => this.#traceInputCoordination(event),
+                }),
+            });
+        this.#tuiTerminal = this.#inputCoordinator === undefined
+            ? preInputTerminal(decoratedTerminal, data => this.#routePreInput(data))
+            : coordinatedInputTerminal(decoratedTerminal, this.#inputCoordinator, sink => { this.#inputSink = sink; });
         this.#layoutRoot = options.layoutRoot;
         this.#logDirectory = options.logDirectory;
-        this.#rootBridge = new ComponentBridge(options.root);
+        this.#rootBridge = new ComponentBridge(options.root, options.inputDiagnostics === undefined
+            ? undefined
+            : phase => this.#traceRuntimePhase(phase));
         this.#bridges.set(options.root, this.#rootBridge);
         this.#mountedComponents.add(options.root);
         try {
@@ -224,10 +269,12 @@ export class PiTuiRuntimeAdapter {
                 return;
             hidden = true;
             this.#overlayDisposers.delete(dispose);
+            this.#overlayInputCoordination.delete(bridge);
             this.#bridges.delete(component);
             component.dispose?.();
         };
         this.#overlayDisposers.add(dispose);
+        this.#overlayInputCoordination.set(bridge, options?.inputCoordination ?? "opaque");
         const handle = this.#tui.showOverlay(bridge, toOverlayOptions(options));
         return new OverlayHandleBridge(handle, target => this.#bridgeFor(target), dispose);
     }
@@ -355,6 +402,7 @@ export class PiTuiRuntimeAdapter {
     }
     async #stop(options) {
         this.#state = "stopping";
+        this.#inputCoordinator?.flush();
         let failure;
         if (options.drainInput !== false) {
             try {
@@ -398,6 +446,29 @@ export class PiTuiRuntimeAdapter {
         }
         return current;
     }
+    #focusedOverlayInputCoordination() {
+        for (const [bridge, coordination] of this.#overlayInputCoordination) {
+            if (bridge.focused)
+                return coordination;
+        }
+        return undefined;
+    }
+    #traceInputCoordination(event) {
+        this.#inputDiagnostics?.onEvent(event);
+    }
+    #traceRuntimePhase(phase) {
+        if (this.#inputDiagnostics === undefined)
+            return;
+        const coordinator = this.#inputCoordinator;
+        this.#inputDiagnostics.onEvent({
+            phase,
+            revision: coordinator?.appliedRevision ?? 0,
+            atMs: this.#diagnosticNow(),
+            pendingDepth: coordinator?.pendingDepth ?? 0,
+            pendingPresentationDepth: coordinator?.pendingPresentation === true ? 1 : 0,
+            appliedRevision: coordinator?.appliedRevision ?? 0,
+        });
+    }
     #mountTui(tui) {
         tui.addChild(this.#rootBridge);
         if (tui instanceof TuiAltScreen && this.#layoutRoot !== undefined) {
@@ -506,15 +577,74 @@ export class PiTuiRuntimeAdapter {
         this.#mountedComponents.clear();
     }
     #disposeComponents() {
+        this.#inputCoordinator?.dispose(false);
+        this.#inputSink = undefined;
         for (const remove of this.#inputListeners.values())
             remove();
         this.#inputListeners.clear();
         this.#preInputListeners.clear();
         for (const dispose of [...this.#overlayDisposers])
             dispose();
+        this.#overlayInputCoordination.clear();
         this.#disposeRoot();
     }
 }
+function coordinatedInputTerminal(terminal, coordinator, setSink) {
+    return {
+        get columns() { return terminal.columns; },
+        get rows() { return terminal.rows; },
+        get kittyProtocolActive() { return terminal.kittyProtocolActive; },
+        start(onInput, onResize) {
+            setSink(onInput);
+            terminal.start(data => coordinator.accept(data), () => {
+                coordinator.flush();
+                onResize();
+            });
+        },
+        stop() {
+            coordinator.flush();
+            setSink(undefined);
+            terminal.stop();
+        },
+        drainInput: (maxMs, idleMs) => terminal.drainInput(maxMs, idleMs),
+        write: data => terminal.write(data),
+        moveBy: lines => terminal.moveBy(lines),
+        hideCursor: () => terminal.hideCursor(),
+        showCursor: () => terminal.showCursor(),
+        clearLine: () => terminal.clearLine(),
+        clearFromCursor: () => terminal.clearFromCursor(),
+        clearScreen: () => terminal.clearScreen(),
+        setTitle: title => terminal.setTitle(title),
+        setProgress: active => terminal.setProgress(active),
+    };
+}
+function diagnosticTerminal(terminal, trace) {
+    return {
+        get columns() { return terminal.columns; },
+        get rows() { return terminal.rows; },
+        get kittyProtocolActive() { return terminal.kittyProtocolActive; },
+        start: (onInput, onResize) => terminal.start(onInput, onResize),
+        stop: () => terminal.stop(),
+        drainInput: (maxMs, idleMs) => terminal.drainInput(maxMs, idleMs),
+        write(data) {
+            trace("write-start");
+            try {
+                terminal.write(data);
+            }
+            finally {
+                trace("write-end");
+            }
+        },
+        moveBy: lines => terminal.moveBy(lines),
+        hideCursor: () => terminal.hideCursor(),
+        showCursor: () => terminal.showCursor(),
+        clearLine: () => terminal.clearLine(),
+        clearFromCursor: () => terminal.clearFromCursor(),
+        clearScreen: () => terminal.clearScreen(),
+        setTitle: title => terminal.setTitle(title),
+        setProgress: active => terminal.setProgress(active),
+    };
+}
 function preInputTerminal(terminal, route) {
     return {
         get columns() { return terminal.columns; },

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

@@ -1,4 +1,5 @@
 import type { PresentationComponentPort } 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;
@@ -50,6 +51,8 @@ export interface PiTuiOverlayOptions {
     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;
@@ -98,11 +101,33 @@ export type PiTuiLayoutNode = {
     readonly scrollbarStyle?: (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;
     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;

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

@@ -0,0 +1,63 @@
+import type { PiTuiTerminalPort } from "./contracts.js";
+export declare const PINNED_PI_TUI_DAMAGE_GRAMMAR = "@earendil-works/pi-tui@0.84.2: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;
+    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" | "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;
+    readonly onResize?: () => 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;
+    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,240 @@
+export const PINNED_PI_TUI_DAMAGE_GRAMMAR = "@earendil-works/pi-tui@0.84.2: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 OSC8 = /\u001b\]8;[^;\u0007\u001b]*;([^\u0007\u001b]*)(?:\u0007|\u001b\\)/gu;
+/**
+ * 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 {
+    inner;
+    options;
+    #rows = new Map();
+    #armed;
+    #lastConsumedFrameId = 0;
+    #cacheWidth = 0;
+    #cacheHeight = 0;
+    #decision = {
+        frameId: null,
+        transformed: false,
+        reason: "not-armed",
+        shiftRows: 0,
+        paintedRows: [],
+    };
+    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; }
+    arm(descriptor, safety) {
+        this.#armed = { descriptor, safety };
+    }
+    start(onInput, onResize) {
+        this.inner.start(onInput, () => {
+            this.#invalidateRows();
+            this.options.onResize?.();
+            onResize();
+        });
+    }
+    stop() {
+        this.#armed = undefined;
+        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);
+        const decision = this.#decide(armed, parsed);
+        this.#decision = decision;
+        if (decision.reason === "suppressed-redundant-clear" && parsed !== null) {
+            this.inner.write(buildClearlessWrite(parsed));
+        }
+        else if (decision.transformed && armed !== undefined && parsed !== null) {
+            this.inner.write(buildDamageWrite(parsed, armed.descriptor, new Set(decision.paintedRows), this.#rows));
+        }
+        else {
+            this.inner.write(data);
+        }
+        this.#rememberFrame(armed?.descriptor, parsed, data);
+    }
+    moveBy(lines) { this.inner.moveBy(lines); }
+    hideCursor() { this.inner.hideCursor(); }
+    showCursor() { this.inner.showCursor(); }
+    clearLine() { this.#invalidateRows(); this.inner.clearLine(); }
+    clearFromCursor() { this.#invalidateRows(); this.inner.clearFromCursor(); }
+    clearScreen() { this.#invalidateRows(); 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 (parsed !== null && parsed.structuralPrefix === "\u001b[2J"
+            && this.#cacheWidth === descriptor.width && this.#cacheHeight === descriptor.height
+            && hasCompleteScreenRows(parsed.rows, descriptor.height) && !hasUnsafeTerminalContent(parsed)) {
+            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)) {
+            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: ordinary followed prose may change one active tail source row, expose
+        // the shifted suffix, and restyle one sticky boundary row. Larger changes indicate
+        // Markdown/theme/overlay reflow and fail closed.
+        if (painted.size > descriptor.verticalShiftRows + 2 + 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;
+        if (descriptor !== undefined && (descriptor.width !== this.#cacheWidth || descriptor.height !== this.#cacheHeight)) {
+            this.#invalidateRows();
+            this.#cacheWidth = descriptor.width;
+            this.#cacheHeight = descriptor.height;
+        }
+        for (const row of parsed.rows)
+            this.#rows.set(row.row, row.content);
+    }
+    #invalidateRows() {
+        this.#rows.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 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) {
+    const data = parsed.rows.map(row => row.content).join("");
+    if (data.includes("\u001b_G") || data.includes("\u001bPq") || data.includes("\u001b[2J"))
+        return true;
+    for (const match of data.matchAll(OSC8))
+        if ((match[1] ?? "").length > 0)
+            return true;
+    return false;
+}
+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}`;
+}
+function buildClearlessWrite(parsed) {
+    return `${BEGIN_SYNCHRONIZED_OUTPUT}${parsed.rows.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;
+}

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

@@ -1,4 +1,6 @@
 export * from "./contracts.js";
+export * from "./damage-aware-terminal.js";
+export * from "./input-presentation-coordinator.js";
 export * from "./adapter.js";
 export * from "./conformance.js";
 export * from "./presentation-adapter.js";

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

@@ -1,4 +1,6 @@
 export * from "./contracts.js";
+export * from "./damage-aware-terminal.js";
+export * from "./input-presentation-coordinator.js";
 export * from "./adapter.js";
 export * from "./conformance.js";
 export * from "./presentation-adapter.js";