@timurproko/a1 0.1.8-dev.139 → 0.1.8-dev.151

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

@@ -0,0 +1,39 @@
+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;
+    setEditorPointerFrame(frame: {
+        readonly rowStart: number;
+        readonly rowEnd: number;
+    } | undefined): void;
+    compose(input: TranscriptViewportFrameInput): TranscriptViewportFrame;
+    /** 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,369 @@
+import { TranscriptViewport, 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;
+    /** A left-button sequence begun in status/editor/footer chrome is swallowed. */
+    #dockPointerSuppressed = false;
+    /** True only while the editor owns a held left mouse button. */
+    #editorPointerSelecting = false;
+    /** Last composed terminal rows occupied by the default prompt editor. */
+    #editorPointerFrame;
+    #selectionAutoScrollTimer;
+    #selectionAutoScrollPointer;
+    #activityTimer;
+    constructor(options) {
+        this.#enabled = options.enabled;
+        this.#editor = options.editor;
+        this.#requestRender = options.requestRender;
+        this.#hasEditorLinks = options.hasEditorLinks ?? (() => false);
+    }
+    get config() {
+        return this.#config;
+    }
+    get editorPointerSelecting() {
+        return this.#editorPointerSelecting;
+    }
+    get transcriptPointerSelecting() {
+        return this.#viewport.selectionActive;
+    }
+    setEditorPointerFrame(frame) {
+        this.#editorPointerFrame = frame;
+    }
+    compose(input) {
+        this.#viewport.setConfig(this.#config);
+        return this.#viewport.compose(input);
+    }
+    /** 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.#clearActivityTimer();
+        this.#stopSelectionAutoScroll();
+        this.#editorPointerSelecting = false;
+        this.#editorPointerFrame = undefined;
+        this.#viewport.reset();
+    }
+    clearPointerState() {
+        this.#clearActivityTimer();
+        this.#dragGrabOffset = null;
+        this.#dockPointerSuppressed = false;
+        this.#editorPointerSelecting = false;
+        this.#editorPointerFrame = undefined;
+        this.#stopSelectionAutoScroll();
+        this.#viewport.clearSelection();
+        this.#viewport.clearTransient();
+    }
+    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
+        // before the focused vanilla editor handles this input.
+        this.#editor.activateKeybindings();
+        // 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.
+        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.#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();
+                    // 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.#requestRender(forceRepaint);
+        return routed;
+    }
+    #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.#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/system-clipboard.d.ts

@@ -0,0 +1,11 @@
+import type { PiShellClipboardContent } from "../components/index.js";
+/** 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 readSystemClipboardText(): Promise<string | null>;
+export declare function writeSystemClipboardText(text: string): Promise<void>;

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

@@ -0,0 +1,101 @@
+import { execFile } from "node:child_process";
+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 };
+            }
+            if (native.hasImage()) {
+                const data = await native.getImageBase64();
+                if (data.length > 0)
+                    return { kind: "image", data, mimeType: "image/png" };
+            }
+        }
+        catch {
+            // Fall through to text and platform readers.
+        }
+    }
+    const text = await readSystemClipboardText();
+    return text === null ? null : { kind: "text", text };
+}
+export async function readSystemClipboardText() {
+    // 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 {
+                // 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 {
+                // 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/integrations/pi/tui-runtime/contracts.d.ts

@@ -1,3 +1,4 @@
+import type { PresentationComponentPort } from "../../../contracts/presentation/index.js";
 export type PiTuiRuntimeState = "idle" | "running" | "stopping" | "stopped" | "failed";
 export interface PiTuiViewport {
     readonly columns: number;
@@ -9,13 +10,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;

package/dist/native/darwin-arm64/manifest.json

@@ -5,7 +5,7 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "unsupported",
-  "builtAt": "2026-08-27T09:31:38.156Z",
+  "builtAt": "2026-08-28T10:16:08.776Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "7524bf568992517f50ed53196c861c5edeba0d7275633bb4735ab45bd5963a28",

package/dist/native/linux-x64/manifest.json

@@ -5,11 +5,11 @@
   "platform": "linux",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-08-27T09:31:34.074Z",
+  "builtAt": "2026-08-28T10:16:08.593Z",
   "artifact": {
     "filename": "process-guardian",
-    "sha256": "29e22fe29de2828982bc67ef418c4adcaab1490281477b7bea592ec6fe621bcd",
-    "size": 415696
+    "sha256": "ee8a00eaaf79c707459bbbfb52518e9739314967049fbe5fa625f36ce33db9ee",
+    "size": 414568
   },
   "provenance": {
     "language": "Rust",

package/dist/native/win32-x64/manifest.json

@@ -5,11 +5,11 @@
   "platform": "win32",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-08-27T09:32:08.840Z",
+  "builtAt": "2026-08-28T10:16:41.229Z",
   "artifact": {
     "filename": "process-guardian.exe",
-    "sha256": "41b1b470549052c30109bdbd3187693ce4de9236295d729acc3a1204a2687025",
-    "size": 172544
+    "sha256": "8daa77c737ea8f96eb022fce63a25a4fce3e5d15c409201712a7f36853c8e8e4",
+    "size": 177664
   },
   "provenance": {
     "language": "Rust",

package/dist/ui/apps/contracts.d.ts

@@ -1,4 +1,4 @@
-import type { PaneInputResult, PaneMouseEvent, PaneRect, UiTheme } from "../components/index.js";
+import type { PaneInputResult, PaneMouseEvent, PaneRect, RenderCacheContract, UiTheme } from "../components/index.js";
 export interface AppSize {
     readonly width: number;
     readonly height: number;
@@ -27,6 +27,8 @@ export interface AppHostServices {
 }
 export interface UiApp {
     readonly id: string;
+    /** Optional declared revisions used by the host's shared frame cache. */
+    readonly renderCache?: RenderCacheContract;
     render(rect: PaneRect, host: AppHostServices): readonly string[];
     onInput?(data: string, host: AppHostServices): PaneInputResult;
     onMouse?(event: PaneMouseEvent, host: AppHostServices): PaneInputResult;
@@ -39,4 +41,24 @@ export interface AppRegistration {
     readonly route: string;
     create(): UiApp;
 }
+/** A neutral owned-app surface mounted by a surrounding presentation runtime. */
+export interface UiRouteSurface {
+    readonly id: string;
+    /** Renders exactly `height` rows of at most `width` columns. */
+    render(width: number, height: number): readonly string[];
+    /** True when the key was consumed; false leaves it to the surrounding shell. */
+    handleInput(data: string): boolean;
+    /** Mouse report in surface-local coordinates. True when consumed. */
+    handleMouse(event: PaneMouseEvent): boolean;
+    isClosed(): boolean;
+    close(): void;
+    onRenderRequested(listener: () => void): void;
+    /** The surface asks to leave A1 entirely, not merely to close itself. */
+    onExitRequested(listener: () => void): void;
+}
+/** Route lookup seam shared by owned apps and any presentation runtime hosting them. */
+export interface UiRouteHost {
+    claims(route: string): boolean;
+    open(route: string): UiRouteSurface | null;
+}
 export declare function assertAppRegistration(registration: AppRegistration): void;

package/dist/ui/apps/host.js

@@ -16,6 +16,7 @@ export class UiAppHost {
     #theme;
     /** When the first interrupt of a chord was seen, or null when disarmed. */
     #interruptArmedAt = null;
+    #renderedInterruptArmed;
     #cache = new FrameCache();
     #app = null;
     constructor(options) {
@@ -58,7 +59,11 @@ export class UiAppHost {
         }
         const size = this.#surface.size();
         const rect = { width: Math.max(0, size.width), height: Math.max(0, size.height) };
-        const lines = this.#guard(() => finalizeFrame(app.render(rect, this.#services()), rect, app.id));
+        const interruptArmed = this.interruptArmed;
+        if (this.#renderedInterruptArmed !== interruptArmed)
+            this.#cache.invalidate();
+        this.#renderedInterruptArmed = interruptArmed;
+        const lines = this.#guard(() => this.#cache.render(app, rect, () => finalizeFrame(app.render(rect, this.#services()), rect, app.id)));
         this.#surface.present(lines ?? null);
     }
     handleInput(data) {
@@ -101,6 +106,9 @@ export class UiAppHost {
             return { consumed: true, render: true };
         }
         this.#interruptArmedAt = now;
+        // Host-owned state participates in the app's next frame independently of
+        // the app's own revision contract.
+        this.#cache.invalidate();
         return { consumed: true, render: true };
     }
     get interruptArmed() {

package/dist/ui/components/scrollbar.d.ts

@@ -19,12 +19,12 @@ export interface ScrollbarInput {
     readonly scroll: number;
     readonly trackHeight: number;
 }
-export type ScrollbarAppearance = "always" | "hover" | "hidden";
+export type ScrollbarAppearance = "auto" | "always" | "hidden";
 export type ScrollbarStyle = "thin" | "thick";
 export type ScrollbarSpeed = "normal" | "fast" | "high";
 /** Wheel distance: normal (3), fast (6), high as normal + fast (9). */
 export declare function scrollbarWheelRows(speed: ScrollbarSpeed): number;
-/** Selection edge distance at each fixed 30ms tick. */
+/** Selection edge distance uses the same configured rate as a wheel event. */
 export declare function scrollbarSelectionRows(speed: ScrollbarSpeed): number;
 export interface ScrollbarPresentationInput {
     readonly geometry: ScrollbarGeometry | null;