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

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

@@ -0,0 +1,439 @@
+export const PINNED_PI_TUI_DAMAGE_GRAMMAR = "@earendil-works/pi-tui@0.87.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;
+// Invariant: in this grammar a row's painted content never repositions the cursor. The pinned engine
+// batches every row erase ahead of the paints for WezTerm frames that place Kitty images, so those
+// paints would otherwise be read as one row's content; an unrecognized frame is forwarded unchanged.
+const ROW_CONTENT_CURSOR = /\u001b\[\d+;1H/u;
+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);
+        if (ROW_CONTENT_CURSOR.test(content))
+            return null;
+        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;
+}

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

@@ -0,0 +1,9 @@
+export type { PiTuiComponentPort, PiTuiInputDiagnosticsEvent, PiTuiInputDiagnosticsPhase, PiTuiInputListener, PiTuiInputListenerResult, PiTuiLayoutEntry, PiTuiLayoutNode, PiTuiOverlayAnchor, PiTuiOverlayHandle, PiTuiOverlayMargin, PiTuiOverlayOptions, PiTuiOverlayUnfocusOptions, PiTuiPointerSurface, PiTuiPreInputListener, PiTuiRuntimeAdapterOptions, PiTuiRuntimeState, PiTuiScrollState, PiTuiSizeValue, PiTuiStopOptions, PiTuiTerminalPort, PiTuiViewport, } from "./contracts.js";
+export { samePointerSurfaces } from "./overlay-geometry.js";
+export { DamageAwareTerminalAdapter, PINNED_PI_TUI_DAMAGE_GRAMMAR } from "./damage-aware-terminal.js";
+export type { DamageAwareTerminalOptions, PiTuiDamageDecision, PiTuiDamageDecisionReason, PiTuiDamageFrameDescriptor, PiTuiDamageFrameSafety, } from "./damage-aware-terminal.js";
+export { InputPresentationCoordinator, classifyPiTuiInput } from "./input-presentation-coordinator.js";
+export type { InputPresentationCoordinatorOptions, PiTuiInputCoordinationDecision, PiTuiInputCoordinationScheduler, PiTuiInputCoordinationTrace, PiTuiInputSurfaceKind, } from "./input-presentation-coordinator.js";
+export { PiTuiRuntimeAdapter, PiTuiRuntimeError } from "./adapter.js";
+export type { PiTuiRuntimeErrorStage } from "./adapter.js";
+export { createPiPresentationRuntime, createPiTerminalBridge } from "./presentation-adapter.js";

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

@@ -0,0 +1,5 @@
+export { samePointerSurfaces } from "./overlay-geometry.js";
+export { DamageAwareTerminalAdapter, PINNED_PI_TUI_DAMAGE_GRAMMAR } from "./damage-aware-terminal.js";
+export { InputPresentationCoordinator, classifyPiTuiInput } from "./input-presentation-coordinator.js";
+export { PiTuiRuntimeAdapter, PiTuiRuntimeError } from "./adapter.js";
+export { createPiPresentationRuntime, createPiTerminalBridge } from "./presentation-adapter.js";

package/dist/integrations/pi/tui-runtime/input-presentation-coordinator.d.ts

@@ -0,0 +1,39 @@
+export type PiTuiInputCoordinationDecision = "safe" | "barrier";
+export type PiTuiInputSurfaceKind = "editor" | "owned" | "opaque";
+export interface PiTuiInputCoordinationScheduler {
+    scheduleImmediate(callback: () => void): ReturnType<typeof setImmediate>;
+    cancelImmediate(handle: ReturnType<typeof setImmediate>): void;
+}
+export interface PiTuiInputCoordinationTrace {
+    readonly phase: "receipt" | "semantic-start" | "semantic-end";
+    readonly revision: number;
+    readonly atMs: number;
+    readonly pendingDepth: number;
+    readonly pendingPresentationDepth: 0 | 1;
+    readonly appliedRevision: number;
+}
+export interface InputPresentationCoordinatorOptions {
+    readonly classify: (data: string) => PiTuiInputCoordinationDecision;
+    readonly deliver: (data: string) => void;
+    readonly onReceipt?: () => void;
+    readonly onTrace?: (event: PiTuiInputCoordinationTrace) => void;
+    readonly now?: () => number;
+    readonly scheduler?: PiTuiInputCoordinationScheduler;
+}
+/**
+ * Delivers complete terminal chunks in their original order while allowing Pi
+ * TUI's existing pending-render guard to present one current state per event
+ * loop turn. Unknown or effectful input is an immediate ordering barrier.
+ */
+export declare class InputPresentationCoordinator {
+    #private;
+    constructor(options: InputPresentationCoordinatorOptions);
+    get pendingDepth(): number;
+    get appliedRevision(): number;
+    get pendingPresentation(): boolean;
+    accept(data: string): void;
+    flush(): void;
+    dispose(deliverPending?: boolean): void;
+}
+/** Finite fail-closed grammar for input whose semantic handlers may run in one ordered drain. */
+export declare function classifyPiTuiInput(data: string, surface: PiTuiInputSurfaceKind): PiTuiInputCoordinationDecision;

package/dist/integrations/pi/tui-runtime/input-presentation-coordinator.js

@@ -0,0 +1,139 @@
+const SYSTEM_SCHEDULER = {
+    scheduleImmediate: callback => setImmediate(callback),
+    cancelImmediate: handle => clearImmediate(handle),
+};
+/**
+ * Delivers complete terminal chunks in their original order while allowing Pi
+ * TUI's existing pending-render guard to present one current state per event
+ * loop turn. Unknown or effectful input is an immediate ordering barrier.
+ */
+export class InputPresentationCoordinator {
+    #classify;
+    #deliver;
+    #onReceipt;
+    #onTrace;
+    #now;
+    #scheduler;
+    #pending = [];
+    #scheduled;
+    #nextRevision = 1;
+    #appliedRevision = 0;
+    #disposed = false;
+    constructor(options) {
+        this.#classify = options.classify;
+        this.#deliver = options.deliver;
+        this.#onReceipt = options.onReceipt;
+        this.#onTrace = options.onTrace;
+        this.#now = options.now ?? (() => performance.now());
+        this.#scheduler = options.scheduler ?? SYSTEM_SCHEDULER;
+    }
+    get pendingDepth() { return this.#pending.length; }
+    get appliedRevision() { return this.#appliedRevision; }
+    get pendingPresentation() { return this.#scheduled !== undefined; }
+    accept(data) {
+        if (this.#disposed || data.length === 0)
+            return;
+        const input = { revision: this.#nextRevision++, data };
+        this.#onReceipt?.();
+        if (this.#classify(data) === "barrier") {
+            this.#trace("receipt", input.revision);
+            this.flush();
+            this.#deliverOne(input);
+            return;
+        }
+        this.#pending.push(input);
+        if (this.#scheduled === undefined) {
+            this.#scheduled = this.#scheduler.scheduleImmediate(() => {
+                this.#scheduled = undefined;
+                this.#drain();
+            });
+        }
+        this.#trace("receipt", input.revision);
+    }
+    flush() {
+        if (this.#scheduled !== undefined)
+            this.#scheduler.cancelImmediate(this.#scheduled);
+        this.#scheduled = undefined;
+        this.#drain();
+    }
+    dispose(deliverPending = true) {
+        if (this.#disposed)
+            return;
+        if (deliverPending)
+            this.flush();
+        else {
+            if (this.#scheduled !== undefined)
+                this.#scheduler.cancelImmediate(this.#scheduled);
+            this.#scheduled = undefined;
+            this.#pending.length = 0;
+        }
+        this.#disposed = true;
+    }
+    #drain() {
+        while (this.#pending.length > 0)
+            this.#deliverOne(this.#pending.shift());
+    }
+    #deliverOne(input) {
+        this.#trace("semantic-start", input.revision);
+        try {
+            this.#deliver(input.data);
+        }
+        finally {
+            this.#appliedRevision = input.revision;
+            this.#trace("semantic-end", input.revision);
+        }
+    }
+    #trace(phase, revision) {
+        this.#onTrace?.({
+            phase,
+            revision,
+            atMs: this.#now(),
+            pendingDepth: this.#pending.length,
+            pendingPresentationDepth: this.#scheduled === undefined ? 0 : 1,
+            appliedRevision: this.#appliedRevision,
+        });
+    }
+}
+const SAFE_EDITING_INPUTS = new Set([
+    "\b",
+    "\u007f",
+    "\u001b[A",
+    "\u001b[B",
+    "\u001b[C",
+    "\u001b[D",
+    "\u001b[1;2A",
+    "\u001b[1;2B",
+    "\u001b[1;5C",
+    "\u001b[1;5D",
+    "\u001b[3~",
+    "\u001b[H",
+    "\u001b[F",
+    "\u001b[1~",
+    "\u001b[4~",
+]);
+const MAX_SAFE_TEXT_DELIVERY = 4096;
+/** Finite fail-closed grammar for input whose semantic handlers may run in one ordered drain. */
+export function classifyPiTuiInput(data, surface) {
+    if (surface === "opaque" || data.length === 0 || data.length > MAX_SAFE_TEXT_DELIVERY)
+        return "barrier";
+    if (SAFE_EDITING_INPUTS.has(data))
+        return "safe";
+    if (data.includes("\u001b") || data.includes("\r") || data.includes("\n") || data.includes("\u0003"))
+        return "barrier";
+    for (let index = 0; index < data.length; index += 1) {
+        const code = data.charCodeAt(index);
+        if (code < 0x20 || code === 0x7f)
+            return "barrier";
+        if (code >= 0xd800 && code <= 0xdbff) {
+            if (index + 1 >= data.length)
+                return "barrier";
+            const next = data.charCodeAt(index + 1);
+            if (next < 0xdc00 || next > 0xdfff)
+                return "barrier";
+            index += 1;
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff)
+            return "barrier";
+    }
+    return "safe";
+}

package/dist/integrations/pi/tui-runtime/mouse-report-input.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Removes complete SGR mouse reports outside bracketed paste while preserving
+ * every adjacent byte in order. Incomplete reports remain available to the
+ * caller's framing boundary rather than being guessed at here.
+ */
+export declare function stripSgrMouseReports(data: string): string;
+/**
+ * Keeps mouse reports and adjacent keyboard input in physical delivery order.
+ * ProcessTerminal already frames escape/paste sequences; this also handles hosts
+ * that batch reports or split an SGR report after its introducer. Paste payloads
+ * are opaque and never interpreted as pointer input.
+ */
+export declare class MouseReportInput {
+    #private;
+    readonly deliver: (data: string) => void;
+    constructor(deliver: (data: string) => void);
+    accept(chunk: string): void;
+    reset(): void;
+}