@timurproko/a1 0.1.8-dev.21b95d6 → 0.1.8-dev.224

package/dist/integrations/pi/session-ui/session-viewport-controller.d.ts

@@ -0,0 +1,44 @@
+import type { OwnedUiViewportSettings } from "../../../contracts/owned-ui/index.js";
+import { type TranscriptViewportFrame, type TranscriptViewportFrameInput } from "../../../ui/components/index.js";
+import type { PiShellEditorPort } from "../components/index.js";
+export interface SessionViewportControllerOptions {
+    readonly enabled: boolean;
+    readonly editor: PiShellEditorPort;
+    readonly requestRender: (force?: boolean) => void;
+    /** Whether mutable editor URL chips need an immediate forced repaint on deletion. */
+    readonly hasEditorLinks?: () => boolean;
+}
+export interface SessionViewportInputResult {
+    readonly data: string;
+    readonly consumed: boolean;
+    readonly copyText?: string;
+}
+/**
+ * Owns the stateful interaction policy of the bare-A1 session viewport. The
+ * shell root supplies semantic rows and dock geometry; this controller owns
+ * follow state, selection, pointer latches, timers, and input routing.
+ */
+export declare class SessionViewportController {
+    #private;
+    constructor(options: SessionViewportControllerOptions);
+    get config(): OwnedUiViewportSettings;
+    get editorPointerSelecting(): boolean;
+    get transcriptPointerSelecting(): boolean;
+    get hasSelection(): boolean;
+    get selectionRevision(): number;
+    get presentationRevision(): number;
+    get frame(): TranscriptViewportFrame | null;
+    setEditorPointerFrame(frame: {
+        readonly rowStart: number;
+        readonly rowEnd: number;
+    } | undefined): void;
+    compose(input: TranscriptViewportFrameInput): TranscriptViewportFrame;
+    composeDockOnly(dockRows: readonly string[], width: number, height: number): TranscriptViewportFrame | null;
+    /** Returns true when document wrapping may have changed. */
+    setConfig(config: OwnedUiViewportSettings): boolean;
+    resumeFollowing(): void;
+    noteCompletedAssistantMessage(): void;
+    reset(): void;
+    clearPointerState(): void;
+    handlePreInput(data: string, allowWheel?: boolean, now?: number): SessionViewportInputResult;
+}

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

@@ -0,0 +1,434 @@
+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
+ * follow state, selection, pointer latches, timers, and input routing.
+ */
+export class SessionViewportController {
+    #enabled;
+    #editor;
+    #requestRender;
+    #hasEditorLinks;
+    #viewport = new TranscriptViewport();
+    #config = {
+        scrollbarAppearance: "auto",
+        scrollbarStyle: "thin",
+        scrollbarSpeed: "normal",
+    };
+    #dragGrabOffset = null;
+    // Invariant: a left-button sequence begun in dock chrome remains owned by the dock.
+    #dockPointerSuppressed = false;
+    // Invariant: editor selection remains true only while its left button is held.
+    #editorPointerSelecting = false;
+    // 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 = force => {
+            this.#presentationRevision += 1;
+            options.requestRender(force);
+        };
+        this.#hasEditorLinks = options.hasEditorLinks ?? (() => false);
+    }
+    get config() {
+        return this.#config;
+    }
+    get editorPointerSelecting() {
+        return this.#editorPointerSelecting;
+    }
+    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);
+        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) {
+        const appearanceChanged = config.scrollbarAppearance !== this.#config.scrollbarAppearance;
+        this.#config = config;
+        this.#viewport.setConfig(config);
+        this.#requestRender();
+        return appearanceChanged;
+    }
+    resumeFollowing() {
+        if (!this.#enabled)
+            return;
+        this.#stopSelectionAutoScroll();
+        const selectionChanged = this.#viewport.clearSelection();
+        const scrolled = this.#viewport.scrollToEnd();
+        if (scrolled)
+            this.#scheduleActivityExpiry();
+        if (scrolled || selectionChanged)
+            this.#requestRender();
+    }
+    noteCompletedAssistantMessage() {
+        if (!this.#enabled || !this.#viewport.noteNewMessage())
+            return;
+        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();
+    }
+    handlePreInput(data, allowWheel = true, now = Date.now()) {
+        if (!this.#enabled)
+            return { data, consumed: false };
+        // Compatibility: Pi components share one keybinding manager. Restore bare A1's aliases
+        // before the focused vanilla editor handles this input.
+        this.#editor.activateKeybindings();
+        // 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 };
+        }
+        // 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)
+            return { data, consumed: false };
+        if (data === "\u0003") {
+            if (this.#editor.hasSelection()) {
+                if (this.#viewport.clearSelection())
+                    this.#requestRender();
+            }
+            else {
+                const copyText = this.#viewport.selectedText();
+                if (copyText !== null && copyText.length > 0) {
+                    this.#viewport.clearSelection();
+                    this.#requestRender();
+                    return { data: "", consumed: true, copyText };
+                }
+            }
+        }
+        if (allowWheel && this.#editor.matchesTerminalKey(data, "home")) {
+            if (this.#viewport.scrollTo(0, now)) {
+                this.#scheduleActivityExpiry();
+                this.#requestRender();
+            }
+            return { data: "", consumed: true };
+        }
+        if (allowWheel && this.#editor.matchesTerminalKey(data, "end")) {
+            if (!this.#viewport.followingEnd) {
+                this.#viewport.scrollToEnd(now);
+                this.#scheduleActivityExpiry();
+                this.#requestRender();
+            }
+            return { data: "", consumed: true };
+        }
+        if (allowWheel && (SHIFT_UP_INPUTS.has(data) || SHIFT_DOWN_INPUTS.has(data))) {
+            const scrolled = SHIFT_UP_INPUTS.has(data)
+                ? this.#viewport.scrollToPreviousPrompt(now)
+                : this.#viewport.scrollToNextPrompt(now);
+            if (scrolled) {
+                this.#scheduleActivityExpiry();
+                this.#requestRender();
+            }
+            return { data: "", consumed: true };
+        }
+        if (!data.includes("\u001b[<") && data !== "\u0003" && this.#viewport.clearSelection()) {
+            this.#requestRender();
+        }
+        const frame = this.#viewport.frame;
+        let repaint = false;
+        let forceRepaint = false;
+        let activity = false;
+        const routed = routeMouseInput(data, event => {
+            const hits = frame.hits;
+            const overRail = hits.rail !== null
+                && event.column === hits.rail.column
+                && event.row >= hits.rail.rowStart
+                && event.row < hits.rail.rowStart + hits.rail.trackHeight;
+            const overSticky = hits.sticky !== null && event.row === hits.sticky.row && event.column <= hits.sticky.width;
+            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);
+                repaint = true;
+                if (this.#editor.ownsPointer() && this.#editorPointerFrame !== undefined) {
+                    this.#editor.handlePointer({
+                        kind: "motion",
+                        button: event.button,
+                        column: event.column,
+                        row: event.row - this.#editorPointerFrame.rowStart + 1,
+                    });
+                    return true;
+                }
+                if (this.#dockPointerSuppressed)
+                    return true;
+                if (this.#viewport.selectionActive) {
+                    this.#viewport.extendSelection(event.column, event.row, now, false);
+                    this.#updateSelectionAutoScroll(event.column, event.row, hits.viewportHeight);
+                    activity = true;
+                    return true;
+                }
+                if (this.#dragGrabOffset !== null && hits.rail !== null) {
+                    const target = scrollForThumbRow(hits.rail.geometry, event.row - hits.rail.rowStart - this.#dragGrabOffset);
+                    this.#viewport.scrollTo(target, now);
+                    activity = true;
+                    return true;
+                }
+                return overRail || overSticky || overBottom;
+            }
+            if (event.kind === "wheel-up" || event.kind === "wheel-down") {
+                if (!allowWheel || event.row < 1 || event.row > hits.viewportHeight)
+                    return false;
+                const distance = scrollbarWheelRows(this.#config.scrollbarSpeed);
+                this.#viewport.scrollBy(event.kind === "wheel-up" ? -distance : distance, now);
+                activity = true;
+                repaint = true;
+                forceRepaint = true;
+                return true;
+            }
+            if (event.kind === "press") {
+                const editorFrame = this.#editorPointerFrame;
+                if (event.button === 2 && editorFrame !== undefined
+                    && event.row >= editorFrame.rowStart && event.row <= editorFrame.rowEnd) {
+                    this.#stopSelectionAutoScroll();
+                    if (this.#viewport.clearSelection())
+                        repaint = true;
+                    this.#editor.pasteClipboard();
+                    this.#dockPointerSuppressed = true;
+                    repaint = true;
+                    return true;
+                }
+                if (event.button !== 0)
+                    return false;
+                this.#stopSelectionAutoScroll();
+                if (this.#viewport.clearSelection())
+                    repaint = true;
+                if (overBottom) {
+                    this.#viewport.scrollToEnd(now);
+                    activity = true;
+                    repaint = true;
+                    return true;
+                }
+                if (overSticky && hits.sticky !== null) {
+                    this.#viewport.scrollTo(hits.sticky.target, now);
+                    activity = true;
+                    repaint = true;
+                    return true;
+                }
+                if (overRail && hits.rail !== null) {
+                    const trackRow = event.row - hits.rail.rowStart;
+                    const geometry = hits.rail.geometry;
+                    if (trackRow >= geometry.thumbTop && trackRow < geometry.thumbTop + geometry.thumbHeight) {
+                        this.#dragGrabOffset = trackRow - geometry.thumbTop;
+                        this.#viewport.setRailDragging(true);
+                    }
+                    else {
+                        this.#viewport.scrollTo(scrollForTrackPage(geometry, trackRow, frame.scrollTop, hits.viewportHeight), now);
+                    }
+                    activity = true;
+                    repaint = true;
+                    return true;
+                }
+                if (editorFrame !== undefined && event.row >= editorFrame.rowStart && event.row <= editorFrame.rowEnd) {
+                    const handled = this.#editor.handlePointer({
+                        kind: "press",
+                        button: event.button,
+                        column: event.column,
+                        row: event.row - editorFrame.rowStart + 1,
+                    });
+                    if (!handled)
+                        this.#dockPointerSuppressed = true;
+                    this.#editorPointerSelecting = handled;
+                    repaint = true;
+                    return true;
+                }
+                if (event.row > hits.viewportHeight) {
+                    this.#dockPointerSuppressed = true;
+                    return true;
+                }
+                if (event.row >= 1 && event.row <= hits.viewportHeight && event.column <= frame.contentWidth) {
+                    this.#viewport.pressSelection(event.column, event.row, now);
+                    repaint = true;
+                    return true;
+                }
+                return false;
+            }
+            if (event.kind === "release") {
+                if (this.#editor.ownsPointer() && this.#editorPointerFrame !== undefined) {
+                    const wasEditorSelecting = this.#editorPointerSelecting;
+                    this.#editor.handlePointer({
+                        kind: "release",
+                        button: event.button,
+                        column: event.column,
+                        row: event.row - this.#editorPointerFrame.rowStart + 1,
+                    });
+                    this.#editorPointerSelecting = false;
+                    forceRepaint ||= wasEditorSelecting;
+                    repaint = true;
+                    return true;
+                }
+                if (this.#viewport.releaseSelection()) {
+                    this.#stopSelectionAutoScroll();
+                    // 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;
+                    return true;
+                }
+                if (this.#dragGrabOffset !== null) {
+                    this.#dragGrabOffset = null;
+                    this.#viewport.setRailDragging(false);
+                    repaint = true;
+                    return true;
+                }
+                if (this.#dockPointerSuppressed) {
+                    this.#dockPointerSuppressed = false;
+                    return true;
+                }
+            }
+            return false;
+        });
+        if (activity)
+            this.#scheduleActivityExpiry();
+        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) {
+            this.#stopSelectionAutoScroll();
+            return;
+        }
+        this.#selectionAutoScrollPointer = { column, row };
+        if (this.#selectionAutoScrollTimer !== undefined)
+            return;
+        this.#selectionAutoScrollTimer = setTimeout(() => this.#selectionAutoScrollTick(), SELECTION_AUTO_SCROLL_INTERVAL_MS);
+        this.#selectionAutoScrollTimer.unref?.();
+    }
+    #selectionAutoScrollTick() {
+        this.#selectionAutoScrollTimer = undefined;
+        const pointer = this.#selectionAutoScrollPointer;
+        if (pointer === undefined || !this.#viewport.selectionActive) {
+            this.#stopSelectionAutoScroll();
+            return;
+        }
+        const before = this.#viewport.scrollTop;
+        const rowsPerTick = scrollbarSelectionRows(this.#config.scrollbarSpeed);
+        for (let row = 0; row < rowsPerTick; row += 1) {
+            const previous = this.#viewport.scrollTop;
+            this.#viewport.extendSelection(pointer.column, pointer.row);
+            if (this.#viewport.scrollTop === previous)
+                break;
+        }
+        if (this.#viewport.scrollTop === before) {
+            this.#stopSelectionAutoScroll();
+            return;
+        }
+        this.#lastRequestedSelectionRevision = this.#viewport.selectionRevision;
+        this.#requestRender();
+        this.#scheduleActivityExpiry();
+        this.#selectionAutoScrollTimer = setTimeout(() => this.#selectionAutoScrollTick(), SELECTION_AUTO_SCROLL_INTERVAL_MS);
+        this.#selectionAutoScrollTimer.unref?.();
+    }
+    #stopSelectionAutoScroll() {
+        if (this.#selectionAutoScrollTimer !== undefined)
+            clearTimeout(this.#selectionAutoScrollTimer);
+        this.#selectionAutoScrollTimer = undefined;
+        this.#selectionAutoScrollPointer = undefined;
+    }
+    #clearActivityTimer() {
+        if (this.#activityTimer !== undefined)
+            clearTimeout(this.#activityTimer);
+        this.#activityTimer = undefined;
+    }
+    #scheduleActivityExpiry() {
+        this.#clearActivityTimer();
+        this.#activityTimer = setTimeout(() => {
+            this.#activityTimer = undefined;
+            this.#requestRender();
+        }, 925);
+        this.#activityTimer.unref?.();
+    }
+}
+const SELECTION_AUTO_SCROLL_INTERVAL_MS = 30;
+const EDITOR_LINK_DELETION_INPUTS = new Set(["\b", "\u007f", "\u001b[3~"]);
+const SHIFT_UP_INPUTS = new Set(["\u001b[1;2A"]);
+const SHIFT_DOWN_INPUTS = new Set(["\u001b[1;2B"]);

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

@@ -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(): 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>;