@timurproko/a1 0.1.8-dev.157 → 0.1.8-dev.214

package/dist/integrations/pi/session-ui/session-viewport-controller.js

@@ -1,4 +1,4 @@
-import { TranscriptViewport, routeMouseInput, scrollForTrackPage, scrollForThumbRow, scrollbarSelectionRows, scrollbarWheelRows, } from "../../../ui/components/index.js";
+import { TranscriptViewport, hyperlinkTargetAtColumn, routeMouseInput, scrollForTrackPage, scrollForThumbRow, scrollbarSelectionRows, scrollbarWheelRows, } from "../../../ui/components/index.js";
 /**
  * Owns the stateful interaction policy of the bare-A1 session viewport. The
  * shell root supplies semantic rows and dock geometry; this controller owns
@@ -16,19 +16,26 @@ export class SessionViewportController {
         scrollbarSpeed: "normal",
     };
     #dragGrabOffset = null;
-    /** A left-button sequence begun in status/editor/footer chrome is swallowed. */
+    // Invariant: a left-button sequence begun in dock chrome remains owned by the dock.
     #dockPointerSuppressed = false;
-    /** True only while the editor owns a held left mouse button. */
+    // Invariant: editor selection remains true only while its left button is held.
     #editorPointerSelecting = false;
-    /** Last composed terminal rows occupied by the default prompt editor. */
+    // Invariant: pointer routing uses the most recently composed editor rows.
     #editorPointerFrame;
     #selectionAutoScrollTimer;
     #selectionAutoScrollPointer;
+    #pointerPosition;
+    #hoveredHyperlinkKey;
+    #lastRequestedSelectionRevision = -1;
+    #presentationRevision = 0;
     #activityTimer;
     constructor(options) {
         this.#enabled = options.enabled;
         this.#editor = options.editor;
-        this.#requestRender = options.requestRender;
+        this.#requestRender = force => {
+            this.#presentationRevision += 1;
+            options.requestRender(force);
+        };
         this.#hasEditorLinks = options.hasEditorLinks ?? (() => false);
     }
     get config() {
@@ -40,12 +47,45 @@ export class SessionViewportController {
     get transcriptPointerSelecting() {
         return this.#viewport.selectionActive;
     }
+    get hasSelection() {
+        return this.#viewport.hasSelection;
+    }
+    get selectionRevision() {
+        return this.#viewport.selectionRevision;
+    }
+    get presentationRevision() {
+        return this.#presentationRevision;
+    }
+    get frame() {
+        return this.#viewport.frame;
+    }
     setEditorPointerFrame(frame) {
         this.#editorPointerFrame = frame;
     }
     compose(input) {
         this.#viewport.setConfig(this.#config);
-        return this.#viewport.compose(input);
+        const selectionRevision = this.#viewport.selectionRevision;
+        const frame = this.#viewport.compose(input);
+        // Concurrency: if selection changed during composition, this frame truthfully carries
+        // the older revision and exactly one ordinary follow-up render publishes the latest.
+        if (this.#viewport.selectionRevision !== selectionRevision
+            && this.#lastRequestedSelectionRevision < this.#viewport.selectionRevision) {
+            this.#lastRequestedSelectionRevision = this.#viewport.selectionRevision;
+            this.#requestRender();
+        }
+        if (this.#pointerPosition !== undefined && !this.#viewport.selectionActive && !this.#editorPointerSelecting) {
+            const next = this.#hyperlinkKeyAt(frame, this.#pointerPosition.column, this.#pointerPosition.row);
+            if (this.#hoveredHyperlinkKey !== undefined && next !== this.#hoveredHyperlinkKey) {
+                // Platform: Windows Terminal can leave its solid native-hover underline behind
+                // when a following viewport moves the link away from a stationary pointer.
+                this.#requestRender(true);
+            }
+            this.#hoveredHyperlinkKey = next;
+        }
+        return frame;
+    }
+    composeDockOnly(dockRows, width, height) {
+        return this.#viewport.composeDockOnly(dockRows, width, height);
     }
     /** Returns true when document wrapping may have changed. */
     setConfig(config) {
@@ -72,18 +112,24 @@ export class SessionViewportController {
         this.#requestRender();
     }
     reset() {
+        this.#presentationRevision += 1;
         this.#clearActivityTimer();
         this.#stopSelectionAutoScroll();
         this.#editorPointerSelecting = false;
         this.#editorPointerFrame = undefined;
+        this.#pointerPosition = undefined;
+        this.#hoveredHyperlinkKey = undefined;
         this.#viewport.reset();
     }
     clearPointerState() {
+        this.#presentationRevision += 1;
         this.#clearActivityTimer();
         this.#dragGrabOffset = null;
         this.#dockPointerSuppressed = false;
         this.#editorPointerSelecting = false;
         this.#editorPointerFrame = undefined;
+        this.#pointerPosition = undefined;
+        this.#hoveredHyperlinkKey = undefined;
         this.#stopSelectionAutoScroll();
         this.#viewport.clearSelection();
         this.#viewport.clearTransient();
@@ -91,15 +137,15 @@ export class SessionViewportController {
     handlePreInput(data, allowWheel = true, now = Date.now()) {
         if (!this.#enabled)
             return { data, consumed: false };
-        // Pi components share one keybinding manager. Restore bare A1's aliases
+        // Compatibility: Pi components share one keybinding manager. Restore bare A1's aliases
         // before the focused vanilla editor handles this input.
         this.#editor.activateKeybindings();
-        // Handle the physical paste chord at the pre-input boundary. Windows
+        // Platform: handle the physical paste chord at the pre-input boundary. Windows
         // terminals vary between forwarding Ctrl+V and terminal-owned bracketed paste.
         if (this.#editor.matchesTerminalKey(data, "ctrl+v") && this.#editor.pasteClipboard()) {
             return { data: "", consumed: true };
         }
-        // URL chip deletion must overwrite terminal link cells in the same frame.
+        // Platform: URL chip deletion must overwrite terminal link cells in the same frame.
         if (EDITOR_LINK_DELETION_INPUTS.has(data) && this.#hasEditorLinks())
             this.#requestRender(true);
         if (this.#viewport.frame === null)
@@ -160,6 +206,16 @@ export class SessionViewportController {
             const overBottom = hits.bottom !== null && event.row === hits.bottom.row
                 && event.column >= hits.bottom.columnStart && event.column <= hits.bottom.columnEnd;
             if (event.kind === "motion") {
+                this.#pointerPosition = { column: event.column, row: event.row };
+                if (!this.#viewport.selectionActive && !this.#editorPointerSelecting) {
+                    const nextHyperlink = this.#hyperlinkKeyAt(frame, event.column, event.row);
+                    if (this.#hoveredHyperlinkKey !== undefined && nextHyperlink !== this.#hoveredHyperlinkKey) {
+                        // Platform: a forced redraw overwrites Windows Terminal's cached solid hover
+                        // underline exactly once when the pointer leaves or changes links.
+                        forceRepaint = true;
+                    }
+                    this.#hoveredHyperlinkKey = nextHyperlink;
+                }
                 this.#viewport.setRailHovered(overRail);
                 this.#viewport.setStickyHovered(overSticky);
                 this.#viewport.setBottomHovered(overBottom);
@@ -282,7 +338,7 @@ export class SessionViewportController {
                 }
                 if (this.#viewport.releaseSelection()) {
                     this.#stopSelectionAutoScroll();
-                    // Restore OSC 8 links only after the held-button selection paint has
+                    // Platform: restore OSC 8 links only after the held-button selection paint has
                     // ended, then overwrite any terminal-cached hover cells immediately.
                     forceRepaint = true;
                     repaint = true;
@@ -303,10 +359,18 @@ export class SessionViewportController {
         });
         if (activity)
             this.#scheduleActivityExpiry();
-        if (repaint)
+        if (repaint) {
+            this.#lastRequestedSelectionRevision = this.#viewport.selectionRevision;
             this.#requestRender(forceRepaint);
+        }
         return routed;
     }
+    #hyperlinkKeyAt(frame, column, row) {
+        if (row < 1 || row > frame.rows.length || column < 1)
+            return undefined;
+        const target = hyperlinkTargetAtColumn(frame.rows[row - 1] ?? "", column - 1);
+        return target === undefined ? undefined : `${row}\u0000${target}`;
+    }
     #updateSelectionAutoScroll(column, row, viewportHeight) {
         const beyondEdge = row <= 1 || row > viewportHeight;
         if (!beyondEdge) {
@@ -338,6 +402,7 @@ export class SessionViewportController {
             this.#stopSelectionAutoScroll();
             return;
         }
+        this.#lastRequestedSelectionRevision = this.#viewport.selectionRevision;
         this.#requestRender();
         this.#scheduleActivityExpiry();
         this.#selectionAutoScrollTimer = setTimeout(() => this.#selectionAutoScrollTick(), SELECTION_AUTO_SCROLL_INTERVAL_MS);

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

@@ -0,0 +1,29 @@
+/**
+ * 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 declare const STREAM_PRESENTATION_INTERVAL_MS = 33;
+export interface StreamPresentationScheduler {
+    now(): number;
+    setTimeout(callback: () => void, delayMs: number): ReturnType<typeof setTimeout>;
+    clearTimeout(timer: ReturnType<typeof setTimeout>): void;
+}
+/** Bounds terminal presentation requests while semantic root state remains current. */
+export declare class StreamPresentationCoalescer {
+    #private;
+    readonly present: () => void;
+    readonly intervalMs: number;
+    readonly scheduler: StreamPresentationScheduler;
+    constructor(present: () => void, intervalMs?: number, scheduler?: StreamPresentationScheduler);
+    get pending(): boolean;
+    request(): void;
+    /** Cancels a superseded stream frame; the immediate input/overlay/resize path renders current state. */
+    preempt(): void;
+    /** Records an immediate input/status/overlay frame and cancels an obsolete stream timer. */
+    noteImmediatePresentation(): void;
+    /** Presents current semantic state immediately regardless of pending stream work. */
+    presentImmediate(): void;
+    /** Presents the newest semantic state immediately only when a stream frame is pending. */
+    flush(): void;
+    dispose(): void;
+}

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

@@ -1,4 +1,9 @@
 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;
 /**
@@ -7,5 +12,9 @@ export declare function preloadSystemClipboard(): void;
  * unavailable clipboard simply makes the paste action a no-op.
  */
 export declare function readSystemClipboardContent(): Promise<PiShellClipboardContent | null>;
+export declare function readSystemClipboardImage(reader: SystemClipboardImageReader): Promise<{
+    readonly data: string;
+    readonly mimeType: string;
+} | null>;
 export declare function readSystemClipboardText(): Promise<string | null>;
 export declare function writeSystemClipboardText(text: string): Promise<void>;

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

@@ -1,4 +1,5 @@
 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();
@@ -22,21 +23,49 @@ export async function readSystemClipboardContent() {
                 if (files !== null)
                     return { kind: "text", text: files };
             }
-            if (native.hasImage()) {
-                const data = await native.getImageBase64();
-                if (data.length > 0)
-                    return { kind: "image", data, mimeType: "image/png" };
-            }
+            const image = await readSystemClipboardImage(native);
+            if (image !== null)
+                return { kind: "image", ...image };
         }
         catch {
-            // Fall through to text and platform readers.
+            // 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() {
-    // 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") {
@@ -48,7 +77,7 @@ export async function readSystemClipboardText() {
                     return text;
             }
             catch {
-                // Fall through to the platform command.
+                // Compatibility: fall through to the platform command.
             }
         }
     }
@@ -74,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);
@@ -31,7 +33,11 @@ export declare class PiTuiRuntimeAdapter {
     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;