@timurproko/a1 0.1.8-dev.3b54f21 → 0.1.8-dev.402

package/dist/integrations/pi/session-ui/stream-presentation-coalescer.js

@@ -0,0 +1,79 @@
+/**
+ * 33 ms (30.3 fps): baseline chunks arrive every 5 ms, while this cadence
+ * retains immediate first paint/input and explicit final-state flushing.
+ */
+export const STREAM_PRESENTATION_INTERVAL_MS = 33;
+const SYSTEM_SCHEDULER = {
+    now: Date.now,
+    setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+    clearTimeout: timer => clearTimeout(timer),
+};
+/** Bounds terminal presentation requests while semantic root state remains current. */
+export class StreamPresentationCoalescer {
+    present;
+    intervalMs;
+    scheduler;
+    #timer;
+    #lastPresentationAt = Number.NEGATIVE_INFINITY;
+    #disposed = false;
+    constructor(present, intervalMs = STREAM_PRESENTATION_INTERVAL_MS, scheduler = SYSTEM_SCHEDULER) {
+        this.present = present;
+        this.intervalMs = intervalMs;
+        this.scheduler = scheduler;
+        if (!Number.isSafeInteger(intervalMs) || intervalMs < 1)
+            throw new RangeError("stream presentation interval must be positive");
+    }
+    get pending() { return this.#timer !== undefined; }
+    request() {
+        if (this.#disposed || this.#timer !== undefined)
+            return;
+        const elapsed = this.scheduler.now() - this.#lastPresentationAt;
+        if (elapsed >= this.intervalMs) {
+            this.#presentNow();
+            return;
+        }
+        this.#timer = this.scheduler.setTimeout(() => {
+            this.#timer = undefined;
+            this.#presentNow();
+        }, Math.max(0, this.intervalMs - elapsed));
+    }
+    /** Cancels a superseded stream frame; the immediate input/overlay/resize path renders current state. */
+    preempt() {
+        if (this.#timer === undefined)
+            return;
+        this.scheduler.clearTimeout(this.#timer);
+        this.#timer = undefined;
+    }
+    /** Records an immediate input/status/overlay frame and cancels an obsolete stream timer. */
+    noteImmediatePresentation() {
+        if (this.#disposed)
+            return;
+        this.preempt();
+        this.#lastPresentationAt = this.scheduler.now();
+    }
+    /** Presents current semantic state immediately regardless of pending stream work. */
+    presentImmediate() {
+        if (this.#disposed)
+            return;
+        this.noteImmediatePresentation();
+        this.present();
+    }
+    /** Presents the newest semantic state immediately only when a stream frame is pending. */
+    flush() {
+        if (this.#disposed || this.#timer === undefined)
+            return;
+        this.scheduler.clearTimeout(this.#timer);
+        this.#timer = undefined;
+        this.#presentNow();
+    }
+    dispose() {
+        this.preempt();
+        this.#disposed = true;
+    }
+    #presentNow() {
+        if (this.#disposed)
+            return;
+        this.#lastPresentationAt = this.scheduler.now();
+        this.present();
+    }
+}

package/dist/integrations/pi/session-ui/system-clipboard.d.ts

@@ -0,0 +1,20 @@
+import type { PiShellClipboardContent } from "../components/index.js";
+export interface SystemClipboardImageReader {
+    hasImage(): boolean;
+    getImageBinary?(): Promise<readonly number[]>;
+    getImageBase64?(): Promise<string>;
+}
+/** Load the native adapter during shell startup so the first paste is warm. */
+export declare function preloadSystemClipboard(): void;
+/**
+ * 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 declare function readSystemClipboardContent(signal?: AbortSignal, strict?: boolean): Promise<PiShellClipboardContent | null>;
+export declare function readSystemClipboardImage(reader: SystemClipboardImageReader): Promise<{
+    readonly data: string;
+    readonly mimeType: string;
+} | null>;
+export declare function readSystemClipboardText(signal?: AbortSignal, strict?: boolean): Promise<string | null>;
+export declare function writeSystemClipboardText(text: string): Promise<void>;

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

@@ -0,0 +1,156 @@
+import { execFile } from "node:child_process";
+import { canonicalizeClipboardImage } from "./clipboard-image.js";
+import { ImageAttachmentError } from "../../../contracts/owned-ui/index.js";
+import { assertSourceBytes } from "./image-source.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(signal, strict = false) {
+    await pendingClipboardWrite;
+    const native = await nativeClipboard();
+    if (native !== null) {
+        try {
+            if (process.platform === "win32" && native.availableFormats().some(isFileDropFormat)) {
+                const files = await readSystemClipboardText(signal, strict);
+                if (files !== null)
+                    return { kind: "text", text: files };
+            }
+            const image = await readSystemClipboardImage(native);
+            if (image !== null)
+                return { kind: "image", ...image };
+        }
+        catch (error) {
+            if (error instanceof ImageAttachmentError)
+                throw error;
+            // Compatibility: fall through to text and platform readers.
+        }
+    }
+    const text = await readSystemClipboardText(signal, strict);
+    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)
+                assertSourceBytes(bytes.length);
+            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",
+                }, true);
+            }
+        }
+        catch (error) {
+            if (error instanceof ImageAttachmentError)
+                throw error;
+            // 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",
+            }, true);
+        }
+        catch (error) {
+            if (error instanceof ImageAttachmentError)
+                throw error;
+            // Compatibility: fall through to the caller's text path.
+        }
+    }
+    return null;
+}
+export async function readSystemClipboardText(signal, strict = false) {
+    // 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;
+                if (strict)
+                    return null;
+            }
+            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], signal, strict);
+    }
+    if (process.platform === "darwin")
+        return execClipboard("pbpaste", [], signal, strict);
+    try {
+        const value = await execClipboard("wl-paste", ["--no-newline", "--type", "text"], signal, strict);
+        if (strict || value !== null)
+            return value;
+    }
+    catch { /* Compatibility: X11 may be available when the Wayland command is not. */ }
+    return execClipboard("xclip", ["-selection", "clipboard", "-o"], signal, strict);
+}
+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, signal, strict = false) {
+    if (signal?.aborted)
+        return strict ? Promise.reject(new ImageAttachmentError("paste-timeout")) : Promise.resolve(null);
+    return new Promise((resolve, reject) => {
+        execFile(command, args, {
+            encoding: "utf8",
+            maxBuffer: MAX_CLIPBOARD_BYTES,
+            timeout: 5_000,
+            windowsHide: true,
+            ...(strict ? { killSignal: "SIGKILL" } : {}),
+            ...(signal === undefined ? {} : { signal }),
+        }, (error, stdout) => {
+            if (error && strict)
+                reject(new ImageAttachmentError("paste-unavailable"));
+            else
+                resolve(error || stdout.length === 0 ? null : stdout);
+        });
+    });
+}

package/dist/integrations/pi/session-ui/text-paste.d.ts

@@ -0,0 +1,5 @@
+/** Normalize clipboard text and classify its compact label using the pinned Pi 0.84.2 paste policy. */
+export declare function prepareTextPaste(source: string): {
+    readonly text: string;
+    readonly label?: string;
+};

package/dist/integrations/pi/session-ui/text-paste.js

@@ -0,0 +1,16 @@
+/** Normalize clipboard text and classify its compact label using the pinned Pi 0.84.2 paste policy. */
+export function prepareTextPaste(source) {
+    // Compatibility: extended-key terminals can encode literal controls inside bracketed paste.
+    const decoded = source.replace(/\x1b\[(\d+);5u/g, (sequence, value) => {
+        const code = Number(value);
+        if (code >= 65 && code <= 90)
+            return String.fromCharCode(code - 64);
+        if (code >= 97 && code <= 122)
+            return String.fromCharCode(code - 96);
+        return sequence;
+    });
+    const text = decoded.replace(/\r\n?/g, "\n").replace(/\t/g, "    ").replace(/[\x00-\x09\x0b-\x1f]/g, "");
+    const lines = text.split("\n").length;
+    const label = lines > 10 ? `+${lines} lines` : text.length > 1000 ? `${text.length} chars` : undefined;
+    return { text, ...(label === undefined ? {} : { label }) };
+}

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);
@@ -20,17 +22,24 @@ export declare class PiTuiRuntimeAdapter {
     setFocus(component: PiTuiComponentPort | null): void;
     showOverlay(component: PiTuiComponentPort, options?: PiTuiOverlayOptions): PiTuiOverlayHandle;
     hasOverlay(): boolean;
+    /** Keyboard capture is independent of a passive overlay's visible pointer region. */
+    hasFocusedOverlay(): boolean;
     /**
      * Writes a terminal control sequence. Used to enable and disable mouse
      * reporting while an A1-owned application is presented, and for nothing else:
      * 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;