@timurproko/a1 0.1.8-dev.235df0e → 0.1.8-dev.259

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

@@ -0,0 +1,130 @@
+import { execFile } from "node:child_process";
+import { canonicalizeClipboardImage } from "./clipboard-image.js";
+const MAX_CLIPBOARD_BYTES = 16 * 1024 * 1024;
+let nativeClipboardPromise;
+let pendingClipboardWrite = Promise.resolve();
+/** Load the native adapter during shell startup so the first paste is warm. */
+export function preloadSystemClipboard() {
+    if (process.platform === "win32" || process.platform === "darwin")
+        void nativeClipboard();
+}
+/**
+ * Reads plain text through platform clipboard commands without importing Pi's
+ * private clipboard module. Failures are deliberately non-fatal: a denied or
+ * unavailable clipboard simply makes the paste action a no-op.
+ */
+export async function readSystemClipboardContent() {
+    await pendingClipboardWrite;
+    const native = await nativeClipboard();
+    if (native !== null) {
+        try {
+            if (process.platform === "win32" && native.availableFormats().some(isFileDropFormat)) {
+                const files = await readSystemClipboardText();
+                if (files !== null)
+                    return { kind: "text", text: files };
+            }
+            const image = await readSystemClipboardImage(native);
+            if (image !== null)
+                return { kind: "image", ...image };
+        }
+        catch {
+            // Compatibility: fall through to text and platform readers.
+        }
+    }
+    const text = await readSystemClipboardText();
+    return text === null ? null : { kind: "text", text };
+}
+export async function readSystemClipboardImage(reader) {
+    if (!reader.hasImage())
+        return null;
+    if (reader.getImageBinary !== undefined) {
+        try {
+            const bytes = await reader.getImageBinary();
+            if (bytes.length > 0 && bytes.every(byte => Number.isInteger(byte) && byte >= 0 && byte <= 255)) {
+                return canonicalizeClipboardImage({
+                    data: Buffer.from(bytes).toString("base64"),
+                    mimeType: "image/png",
+                });
+            }
+        }
+        catch {
+            // Compatibility: older or partially available native bindings may still expose base64.
+        }
+    }
+    if (reader.getImageBase64 !== undefined) {
+        try {
+            return canonicalizeClipboardImage({
+                data: await reader.getImageBase64(),
+                mimeType: "image/png",
+            });
+        }
+        catch {
+            // Compatibility: fall through to the caller's text path.
+        }
+    }
+    return null;
+}
+export async function readSystemClipboardText() {
+    // 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") {
+        const native = await nativeClipboard();
+        if (native !== null) {
+            try {
+                const text = await native.getText();
+                if (text.length > 0)
+                    return text;
+            }
+            catch {
+                // Compatibility: fall through to the platform command.
+            }
+        }
+    }
+    if (process.platform === "win32") {
+        const script = [
+            "[Console]::OutputEncoding=[System.Text.Encoding]::UTF8",
+            "$t=Get-Clipboard -Raw -ErrorAction SilentlyContinue",
+            "if ($null -ne $t -and $t.Length -gt 0) {[Console]::Out.Write($t)} else {$f=Get-Clipboard -Format FileDropList -ErrorAction SilentlyContinue; if ($f) {[Console]::Out.Write(($f | ForEach-Object {$_.FullName}) -join [Environment]::NewLine)}}",
+        ].join("; ");
+        return execClipboard("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script]);
+    }
+    if (process.platform === "darwin")
+        return execClipboard("pbpaste", []);
+    return (await execClipboard("wl-paste", ["--no-newline", "--type", "text"]))
+        ?? execClipboard("xclip", ["-selection", "clipboard", "-o"]);
+}
+export function writeSystemClipboardText(text) {
+    const write = async () => {
+        const native = await nativeClipboard();
+        if (native !== null) {
+            try {
+                await native.setText(text);
+                return;
+            }
+            catch {
+                // Compatibility: the caller still emits its terminal clipboard fallback.
+            }
+        }
+    };
+    const operation = pendingClipboardWrite.then(write, write);
+    pendingClipboardWrite = operation.catch(() => { });
+    return operation;
+}
+function nativeClipboard() {
+    nativeClipboardPromise ??= import("@mariozechner/clipboard").catch(() => null);
+    return nativeClipboardPromise;
+}
+function isFileDropFormat(format) {
+    return /(?:filedrop|hdrop|shell idlist)/iu.test(format);
+}
+function execClipboard(command, args) {
+    return new Promise(resolve => {
+        execFile(command, args, {
+            encoding: "utf8",
+            maxBuffer: MAX_CLIPBOARD_BYTES,
+            timeout: 5_000,
+            windowsHide: true,
+        }, (error, stdout) => resolve(error || stdout.length === 0 ? null : stdout));
+    });
+}

package/dist/{src/foundation/pi-tui-runtime-adapter → integrations/pi/tui-runtime}/adapter.d.ts

@@ -1,9 +1,11 @@
-import type { PiTuiComponentPort, PiTuiInputListener, PiTuiOverlayHandle, PiTuiOverlayOptions, PiTuiRuntimeAdapterOptions, PiTuiRuntimeState, PiTuiScrollState, PiTuiStopOptions, PiTuiViewport } from "./contracts.js";
+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);
@@ -26,11 +28,16 @@ export declare class PiTuiRuntimeAdapter {
      * the transparent and pinned paths never call it.
      */
     writeControl(data: string): void;
+    addPreInputListener(listener: PiTuiPreInputListener): () => void;
     addInputListener(listener: PiTuiInputListener): () => void;
     switchMode(mode: "regular" | "fullscreen"): boolean;
     setHardwareCursor(enabled: boolean): void;
     getHardwareCursor(): boolean;
+    setClearOnShrink(enabled: boolean): void;
+    getClearOnShrink(): boolean;
+    setTerminalProgress(active: boolean): void;
     setTitle(title: string): void;
+    writeAfterStop(text: string): void;
     invalidate(): void;
     requestRender(force?: boolean): void;
     renderNow(force?: boolean): void;

package/dist/{src/foundation/pi-tui-runtime-adapter → 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,8 +89,10 @@ 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;
     #tui;
     #root;
     #layoutRoot;
@@ -91,16 +103,53 @@ 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;
+    #terminalProgress = false;
     constructor(options) {
         this.#root = options.root;
         this.#terminal = options.terminal ?? new ProcessTerminal();
+        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 {
@@ -220,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);
     }
@@ -239,6 +290,12 @@ export class PiTuiRuntimeAdapter {
         this.#assertRunning("control sequence");
         this.#terminal.write(data);
     }
+    addPreInputListener(listener) {
+        if (this.#preInputListeners.has(listener))
+            throw new TypeError("Pi TUI pre-input listener is already registered");
+        this.#preInputListeners.add(listener);
+        return () => this.#preInputListeners.delete(listener);
+    }
     addInputListener(listener) {
         this.#assertRunning("input listener");
         if (this.#inputListeners.has(listener))
@@ -292,9 +349,26 @@ export class PiTuiRuntimeAdapter {
     getHardwareCursor() {
         return this.#tui.getShowHardwareCursor();
     }
+    setClearOnShrink(enabled) {
+        this.#tui.setClearOnShrink(enabled);
+    }
+    getClearOnShrink() {
+        return this.#tui.getClearOnShrink();
+    }
+    setTerminalProgress(active) {
+        if (this.#terminalProgress === active)
+            return;
+        this.#terminal.setProgress(active);
+        this.#terminalProgress = active;
+    }
     setTitle(title) {
         this.#terminal.setTitle(title);
     }
+    writeAfterStop(text) {
+        if (this.#state !== "stopped")
+            throw new Error("terminal output requires a stopped Pi TUI runtime");
+        this.#terminal.write(text);
+    }
     invalidate() {
         this.#tui.invalidate();
         if (this.active)
@@ -313,6 +387,8 @@ export class PiTuiRuntimeAdapter {
             return this.#stopPromise;
         if (this.#state === "idle") {
             this.#state = "stopped";
+            this.#clearTerminalProgress();
+            this.#preInputListeners.clear();
             this.#disposeRoot();
             return Promise.resolve();
         }
@@ -326,6 +402,7 @@ export class PiTuiRuntimeAdapter {
     }
     async #stop(options) {
         this.#state = "stopping";
+        this.#inputCoordinator?.flush();
         let failure;
         if (options.drainInput !== false) {
             try {
@@ -344,6 +421,7 @@ export class PiTuiRuntimeAdapter {
             this.#bestEffortTerminalRestore();
         }
         finally {
+            this.#clearTerminalProgress();
             this.#disposeComponents();
         }
         this.#state = failure === undefined ? "stopped" : "failed";
@@ -352,8 +430,44 @@ export class PiTuiRuntimeAdapter {
     }
     #createTui(mode, hardwareCursor) {
         return mode === "fullscreen"
-            ? new TuiAltScreen(this.#terminal, hardwareCursor, this.#logDirectory, this.#tuiOptions)
-            : new TuiMainScreen(this.#terminal, hardwareCursor, this.#logDirectory);
+            ? new TuiAltScreen(this.#tuiTerminal, hardwareCursor, this.#logDirectory, this.#tuiOptions)
+            : new TuiMainScreen(this.#tuiTerminal, hardwareCursor, this.#logDirectory);
+    }
+    #routePreInput(data) {
+        let current = data;
+        for (const listener of this.#preInputListeners) {
+            if (current.length === 0)
+                break;
+            const result = listener(current);
+            if (result?.data !== undefined)
+                current = result.data;
+            else if (result?.consume === true)
+                current = "";
+        }
+        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);
@@ -436,7 +550,15 @@ export class PiTuiRuntimeAdapter {
             this.#bestEffortTerminalRestore();
         }
     }
+    #clearTerminalProgress() {
+        try {
+            this.#terminal.setProgress(false);
+        }
+        catch { }
+        this.#terminalProgress = false;
+    }
     #bestEffortTerminalRestore() {
+        this.#clearTerminalProgress();
         try {
             this.#terminal.showCursor();
         }
@@ -455,14 +577,99 @@ 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; },
+        get rows() { return terminal.rows; },
+        get kittyProtocolActive() { return terminal.kittyProtocolActive; },
+        start(onInput, onResize) {
+            terminal.start(data => {
+                const routed = route(data);
+                if (routed.length > 0)
+                    onInput(routed);
+            }, onResize);
+        },
+        stop: () => 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 toOverlayOptions(options) {
     if (options === undefined)
         return undefined;

package/dist/{src/foundation/pi-tui-runtime-adapter → integrations/pi/tui-runtime}/contracts.d.ts

@@ -1,3 +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;
@@ -9,13 +11,8 @@ export interface PiTuiScrollState {
     readonly followingEnd: boolean;
     readonly scrollbarVisible: boolean;
 }
-export interface PiTuiComponentPort {
-    render(width: number): readonly string[];
-    invalidate(): void;
-    handleInput?(data: string): void;
+export interface PiTuiComponentPort extends PresentationComponentPort {
     readonly wantsKeyRelease?: boolean;
-    setFocused?(focused: boolean): void;
-    dispose?(): void;
 }
 export interface PiTuiTerminalPort {
     start(onInput: (data: string) => void, onResize: () => void): void;
@@ -54,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;
@@ -71,6 +70,8 @@ export interface PiTuiInputListenerResult {
     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";
@@ -100,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,74 @@
+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" | "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 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;
+    /** Latches cleanup through composition/coalescing until a complete write covers it. */
+    requestHyperlinkCleanup(): 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;
+}