@timurproko/a1 0.2.7-dev.1255 → 0.2.7-dev.1265

package/dist/integrations/pi/engine/workflow-share.d.ts

@@ -0,0 +1,9 @@
+import type { AgentSession, AgentSessionRuntime } from "../startup-public.js";
+import type { PiWorkflowHost, PiWorkflowRequest, PiWorkflowResult } from "./workflows.js";
+export interface PiShareCall {
+    readonly request: PiWorkflowRequest;
+    readonly session: AgentSession;
+    readonly runtime: AgentSessionRuntime;
+    readonly host: PiWorkflowHost;
+}
+export declare function runShareWorkflow({ request, session, runtime, host }: PiShareCall): Promise<PiWorkflowResult>;

package/dist/integrations/pi/engine/workflow-share.js

@@ -0,0 +1,168 @@
+/**
+ * Pinned Pi's `/share` workflow: the Radius artifact route with a gist fallback. The runner loads
+ * this module on the first `/share`, so its network clients stay off the startup path.
+ */
+import { randomUUID } from "node:crypto";
+import { readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { PRODUCT_IDENTITY } from "../../../product-identity.js";
+import { isRecord, requireCapability, stringProperty } from "./message-values.js";
+import { commandMissing, errorMessage, isAbortError, workflowResult } from "./workflow-support.js";
+// Provenance: the pinned engine's modes/interactive/session-share.ts Radius route and the model
+// runtime's DEFAULT_RADIUS_GATEWAY; neither is in the public API, so each upgrade re-checks them.
+const RADIUS_SHARE_GATEWAY = "https://radius.pi.dev";
+const RADIUS_AUTH_MIN_VALIDITY_MS = 5 * 60_000;
+export async function runShareWorkflow({ request, session, runtime, host }) {
+    const signal = request.signal;
+    if (signal?.aborted)
+        return shareCancelled(request);
+    const destination = runtime.services.settingsManager?.getSessionShareDestination?.() ?? "auto";
+    if (destination !== "gist") {
+        const radius = await shareViaRadius({ request, session, runtime, host });
+        if (radius !== undefined)
+            return radius;
+        if (destination === "radius")
+            return workflowResult(request.command, "failed", "Radius authentication is not configured. Run '/login radius' first.");
+    }
+    request.onProgress?.("Creating gist…");
+    try {
+        await host.runCommand("gh", ["auth", "status"], signal === undefined ? undefined : { signal });
+    }
+    catch (error) {
+        if (signal?.aborted || isAbortError(error))
+            return shareCancelled(request);
+        const message = commandMissing(error)
+            ? "GitHub CLI (gh) is not installed. Install it from https://cli.github.com/"
+            : "GitHub CLI is not logged in. Run 'gh auth login' first.";
+        return workflowResult(request.command, "failed", message);
+    }
+    const temporary = join(tmpdir(), `${PRODUCT_IDENTITY.filesystem.temporaryPrefix}pi-session-${process.pid}.html`);
+    try {
+        try {
+            await requireCapability(session.exportToHtml, "exportToHtml").call(session, temporary);
+        }
+        catch (error) {
+            return workflowResult(request.command, "failed", `Failed to export session: ${errorMessage(error, "Unknown error")}`);
+        }
+        if (signal?.aborted)
+            return shareCancelled(request);
+        let gist;
+        try {
+            gist = await host.runCommand("gh", ["gist", "create", "--public=false", temporary], signal === undefined ? undefined : { signal });
+        }
+        catch (error) {
+            if (signal?.aborted || isAbortError(error))
+                return shareCancelled(request);
+            return workflowResult(request.command, "failed", `Failed to create gist: ${shareCommandFailureDetail(error)}`);
+        }
+        if (signal?.aborted)
+            return shareCancelled(request);
+        const gistUrl = gist.stdout.trim();
+        const gistId = gistUrl.split("/").at(-1);
+        if (!gistId)
+            return workflowResult(request.command, "failed", "Failed to parse gist ID from gh output");
+        return workflowResult(request.command, "completed", `Share URL: ${shareViewerUrl(gistId)}`, gistUrl);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+function shareCancelled(request) {
+    return workflowResult(request.command, "cancelled", "Share cancelled", undefined, "status");
+}
+// Protocol: the pinned Radius `/share` route. Undefined means Radius has no provider or credential,
+// so the caller may fall back to a gist; any other outcome, including an upload failure, is final.
+async function shareViaRadius({ request, session, runtime, host }) {
+    const signal = request.signal;
+    const models = runtime.services.modelRuntime;
+    if (models.getProvider?.("radius") === undefined)
+        return undefined;
+    const token = radiusAuthCredential(await models.getAuth("radius", { minOAuthValidityMs: RADIUS_AUTH_MIN_VALIDITY_MS }));
+    if (!token)
+        return undefined;
+    if (signal?.aborted)
+        return shareCancelled(request);
+    request.onProgress?.("Uploading to Radius…");
+    const temporary = join(tmpdir(), `${PRODUCT_IDENTITY.filesystem.temporaryPrefix}pi-session-${process.pid}.jsonl`);
+    let body;
+    try {
+        requireCapability(session.exportToJsonl, "exportToJsonl").call(session, temporary);
+        body = withRadiusShareTrailingEntry(await readFile(temporary, "utf8"), session.state ?? {}, randomUUID().slice(0, 8));
+    }
+    catch (error) {
+        return workflowResult(request.command, "failed", `Failed to export session: ${errorMessage(error, "Unknown error")}`);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    const url = new URL("/v1/artifacts", RADIUS_SHARE_GATEWAY);
+    url.searchParams.set("visibility", "organization");
+    url.searchParams.set("title", "Pi session");
+    try {
+        const response = await (host.fetch ?? fetch)(url, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/x-ndjson" },
+            body,
+            ...(signal === undefined ? {} : { signal }),
+        });
+        const json = await response.json().catch(() => null);
+        if (signal?.aborted)
+            return shareCancelled(request);
+        const artifact = isRecord(json) && isRecord(json.artifact) ? json.artifact : undefined;
+        const shareUrl = artifact === undefined ? undefined : stringProperty(artifact, "canonical_url");
+        if (!response.ok || shareUrl === undefined) {
+            const detail = (isRecord(json) ? stringProperty(json, "error") : undefined) || response.statusText || String(response.status);
+            return workflowResult(request.command, "failed", `Failed to upload Radius artifact: ${detail}`);
+        }
+        return workflowResult(request.command, "completed", `Share URL: ${shareUrl}`);
+    }
+    catch (error) {
+        if (signal?.aborted || isAbortError(error))
+            return shareCancelled(request);
+        return workflowResult(request.command, "failed", `Failed to upload Radius artifact: ${errorMessage(error, "Unknown error")}`);
+    }
+}
+function shareCommandFailureDetail(error) {
+    // Compatibility: Pi reports a failed child's stderr, not execFile's command wrapper.
+    if (isRecord(error) && (typeof error.code === "number" || typeof error.signal === "string") && typeof error.stderr === "string") {
+        return error.stderr.trim() || "Unknown error";
+    }
+    return errorMessage(error, "Unknown error");
+}
+function shareViewerUrl(gistId) {
+    const baseUrl = process.env.PI_SHARE_VIEWER_URL || "https://pi.dev/session/";
+    return `${baseUrl}#${gistId}`;
+}
+/** The bearer token in a model-runtime auth result: an API key or an `Authorization: Bearer` header. */
+function radiusAuthCredential(auth) {
+    const resolved = isRecord(auth) && isRecord(auth.auth) ? auth.auth : undefined;
+    if (resolved === undefined)
+        return undefined;
+    if (typeof resolved.apiKey === "string" && resolved.apiKey)
+        return resolved.apiKey;
+    const headers = isRecord(resolved.headers) ? resolved.headers : {};
+    const authorization = Object.entries(headers).find(([name]) => name.toLowerCase() === "authorization")?.[1];
+    return typeof authorization === "string" ? /^Bearer\s+(.+)$/iu.exec(authorization)?.[1] : undefined;
+}
+/**
+ * Append the pinned `pi.share` trailing entry (system prompt and tool schemas for the session viewer)
+ * to a branch JSONL export. It chains to the last exported entry and reuses the header timestamp.
+ */
+function withRadiusShareTrailingEntry(jsonl, state, id) {
+    const lines = jsonl.split("\n").filter(line => line.length > 0);
+    const header = lines[0] === undefined ? undefined : JSON.parse(lines[0]);
+    const last = lines.length > 1 ? JSON.parse(lines.at(-1)) : undefined;
+    const entry = {
+        type: "custom",
+        customType: "pi.share",
+        id,
+        parentId: isRecord(last) && typeof last.id === "string" ? last.id : null,
+        timestamp: isRecord(header) && typeof header.timestamp === "string" ? header.timestamp : new Date().toISOString(),
+        data: {
+            systemPrompt: state.systemPrompt,
+            tools: (state.tools ?? []).filter(isRecord).map(tool => ({ name: tool.name, description: tool.description, parameters: tool.parameters })),
+        },
+    };
+    return `${[...lines, JSON.stringify(entry)].join("\n")}\n`;
+}

package/dist/integrations/pi/engine/workflow-support.d.ts

@@ -12,22 +12,8 @@ export declare function workflowLoginNotification(event: unknown): PiWorkflowLog
 export declare function workflowResult(command: PiWorkflowRequest["command"], outcome: PiWorkflowResult["outcome"], message: string, detail?: string, messageKind?: PiWorkflowResult["messageKind"], messages?: readonly PiWorkflowMessage[]): PiWorkflowResult;
 export declare function workflowConfirmation(command: PiWorkflowRequest["command"], message: string, detail?: string): PiWorkflowResult;
 export declare function errorMessage(error: unknown, fallback: string): string;
-export declare function shareCommandFailureDetail(error: unknown): string;
 export declare function commandMissing(error: unknown): boolean;
 export declare function isAbortError(error: unknown): boolean;
-export declare function shareViewerUrl(gistId: string): string;
-export declare const RADIUS_SHARE_GATEWAY = "https://radius.pi.dev";
-export declare const RADIUS_AUTH_MIN_VALIDITY_MS: number;
-/** The bearer token in a model-runtime auth result: an API key or an `Authorization: Bearer` header. */
-export declare function radiusAuthCredential(auth: unknown): string | undefined;
-/**
- * Append the pinned `pi.share` trailing entry (system prompt and tool schemas for the session viewer)
- * to a branch JSONL export. It chains to the last exported entry and reuses the header timestamp.
- */
-export declare function withRadiusShareTrailingEntry(jsonl: string, state: {
-    readonly systemPrompt?: unknown;
-    readonly tools?: readonly unknown[];
-}, id: string): string;
 export declare function workflowOptions(value: unknown, idKey: string, labelKey: string): readonly PiWorkflowOption[];
 export declare function pathArgument(value: string): string | undefined;
 export declare function pinnedHotkeySummary(): string;

package/dist/integrations/pi/engine/workflow-support.js

@@ -262,59 +262,12 @@ export function workflowConfirmation(command, message, detail) {
 export function errorMessage(error, fallback) {
     return error instanceof Error ? error.message : fallback;
 }
-export function shareCommandFailureDetail(error) {
-    // Compatibility: Pi reports a failed child's stderr, not execFile's command wrapper.
-    if (isRecord(error) && (typeof error.code === "number" || typeof error.signal === "string") && typeof error.stderr === "string") {
-        return error.stderr.trim() || "Unknown error";
-    }
-    return errorMessage(error, "Unknown error");
-}
 export function commandMissing(error) {
     return isRecord(error) && error.code === "ENOENT";
 }
 export function isAbortError(error) {
     return isRecord(error) && (error.name === "AbortError" || error.code === "ABORT_ERR");
 }
-export function shareViewerUrl(gistId) {
-    const baseUrl = process.env.PI_SHARE_VIEWER_URL || "https://pi.dev/session/";
-    return `${baseUrl}#${gistId}`;
-}
-// Provenance: the pinned engine's modes/interactive/session-share.ts Radius route and the model
-// runtime's DEFAULT_RADIUS_GATEWAY; neither is in the public API, so each upgrade re-checks them.
-export const RADIUS_SHARE_GATEWAY = "https://radius.pi.dev";
-export const RADIUS_AUTH_MIN_VALIDITY_MS = 5 * 60_000;
-/** The bearer token in a model-runtime auth result: an API key or an `Authorization: Bearer` header. */
-export function radiusAuthCredential(auth) {
-    const resolved = isRecord(auth) && isRecord(auth.auth) ? auth.auth : undefined;
-    if (resolved === undefined)
-        return undefined;
-    if (typeof resolved.apiKey === "string" && resolved.apiKey)
-        return resolved.apiKey;
-    const headers = isRecord(resolved.headers) ? resolved.headers : {};
-    const authorization = Object.entries(headers).find(([name]) => name.toLowerCase() === "authorization")?.[1];
-    return typeof authorization === "string" ? /^Bearer\s+(.+)$/iu.exec(authorization)?.[1] : undefined;
-}
-/**
- * Append the pinned `pi.share` trailing entry (system prompt and tool schemas for the session viewer)
- * to a branch JSONL export. It chains to the last exported entry and reuses the header timestamp.
- */
-export function withRadiusShareTrailingEntry(jsonl, state, id) {
-    const lines = jsonl.split("\n").filter(line => line.length > 0);
-    const header = lines[0] === undefined ? undefined : JSON.parse(lines[0]);
-    const last = lines.length > 1 ? JSON.parse(lines.at(-1)) : undefined;
-    const entry = {
-        type: "custom",
-        customType: "pi.share",
-        id,
-        parentId: isRecord(last) && typeof last.id === "string" ? last.id : null,
-        timestamp: isRecord(header) && typeof header.timestamp === "string" ? header.timestamp : new Date().toISOString(),
-        data: {
-            systemPrompt: state.systemPrompt,
-            tools: (state.tools ?? []).filter(isRecord).map(tool => ({ name: tool.name, description: tool.description, parameters: tool.parameters })),
-        },
-    };
-    return `${[...lines, JSON.stringify(entry)].join("\n")}\n`;
-}
 export function workflowOptions(value, idKey, labelKey) {
     if (!Array.isArray(value))
         return [];

package/dist/integrations/pi/tui-runtime/adapter.d.ts

@@ -1,5 +1,5 @@
 import { type ProgramStatus, type WheelScrollLines } from "@earendil-works/pi-tui";
-import type { PiTuiComponentPort, PiTuiInputListener, PiTuiOverlayHandle, PiTuiOverlayOptions, PiTuiPreInputListener, PiTuiRuntimeAdapterOptions, PiTuiRuntimeState, PiTuiScrollState, PiTuiStopOptions, PiTuiViewport } from "./contracts.js";
+import type { TerminalComponentPort, TerminalInputListener, TerminalOverlayHandle, TerminalOverlayOptions, TerminalPreInputListener, TerminalRuntimeOptions, TerminalRuntimeState, TerminalStopOptions, TerminalViewport } from "../../../contracts/presentation/index.js";
 /**
  * Re-encodes one key report decoded by pi-tui in the legacy form, so a kitty-keyboard terminal
  * and a legacy terminal produce the same owned-screen action. Releases decode
@@ -15,19 +15,14 @@ export declare class PiTuiRuntimeError extends Error {
 /** Bridges neutral presentation ports to one Pi TUI instance and owns terminal restoration on stop. */
 export declare class PiTuiRuntimeAdapter {
     #private;
-    constructor(options: PiTuiRuntimeAdapterOptions);
-    get state(): PiTuiRuntimeState;
+    constructor(options: TerminalRuntimeOptions);
+    get state(): TerminalRuntimeState;
     get active(): boolean;
     get mode(): "regular" | "fullscreen";
     get fullRedraws(): number;
-    viewport(): PiTuiViewport;
-    scrollState(id?: string): PiTuiScrollState;
-    scrollBy(lines: number, id?: string): void;
-    scrollToTop(id?: string): void;
-    scrollToBottom(id?: string): void;
+    viewport(): TerminalViewport;
     start(): void;
-    setFocus(component: PiTuiComponentPort | null): void;
-    showOverlay(component: PiTuiComponentPort, options?: PiTuiOverlayOptions): PiTuiOverlayHandle;
+    showOverlay(component: TerminalComponentPort, options?: TerminalOverlayOptions): TerminalOverlayHandle;
     hasOverlay(): boolean;
     /** Keyboard capture is independent of a passive overlay's visible pointer region. */
     hasFocusedOverlay(): boolean;
@@ -44,30 +39,25 @@ export declare class PiTuiRuntimeAdapter {
      * renderer keeps scheduling but nothing it paints reaches the terminal.
      */
     freezePresentation(): void;
-    get presentationFrozen(): boolean;
     /**
      * Keeps asynchronous replacement-surface construction atomic at the terminal. Renderers may
      * compose while held, but their writes are dropped until the final forced repaint on release.
      */
     beginPresentationHold(): () => void;
     get presentationHeld(): boolean;
-    addPreInputListener(listener: PiTuiPreInputListener): () => void;
-    addInputListener(listener: PiTuiInputListener): () => void;
+    addPreInputListener(listener: TerminalPreInputListener): () => void;
+    addInputListener(listener: TerminalInputListener): () => void;
     switchMode(mode: "regular" | "fullscreen"): boolean;
     setHardwareCursor(enabled: boolean): void;
-    getHardwareCursor(): boolean;
     setClearOnShrink(enabled: boolean): void;
     setWheelScrollLines(lines: WheelScrollLines): void;
-    getClearOnShrink(): boolean;
     setTerminalProgress(active: boolean): void;
     setProgramStatus(status: ProgramStatus): void;
     setTitle(title: string): void;
-    /** Shows a bounded fullscreen acknowledgement without changing root layout geometry. */
-    showFlash(message: string, durationMs?: number): void;
     writeAfterStop(text: string): void;
     invalidate(): void;
     requestRender(force?: boolean): void;
     renderNow(force?: boolean): void;
-    stop(options?: PiTuiStopOptions): Promise<void>;
-    dispose(options?: PiTuiStopOptions): Promise<void>;
+    stop(options?: TerminalStopOptions): Promise<void>;
+    dispose(options?: TerminalStopOptions): Promise<void>;
 }

package/dist/integrations/pi/tui-runtime/adapter.js

@@ -128,7 +128,7 @@ export class PiTuiRuntimeAdapter {
     #rootBridge;
     #bridges = new WeakMap();
     #mountedComponents = new Set();
-    #scrollViews = new Map();
+    #scrollIds = new Set();
     #overlayGeometry;
     #overlayDisposers = new Set();
     #overlayInputCoordination = new Map();
@@ -222,53 +222,6 @@ export class PiTuiRuntimeAdapter {
             rows: Math.max(1, this.#terminal.rows),
         };
     }
-    scrollState(id) {
-        if (id === undefined) {
-            if (!(this.#tui instanceof TuiAltScreen)) {
-                throw new Error("Pi TUI application scrolling is available only in fullscreen mode");
-            }
-            return {
-                scrollTop: this.#tui.viewportTop,
-                viewportHeight: this.viewport().rows,
-                followingEnd: this.#tui.isFollowingOutput,
-                scrollbarVisible: false,
-            };
-        }
-        const scrollView = this.#requireScrollView(id);
-        return {
-            scrollTop: scrollView.scrollTop,
-            viewportHeight: scrollView.viewportHeight,
-            followingEnd: scrollView.isFollowingEnd,
-            scrollbarVisible: scrollView.isScrollbarVisible,
-        };
-    }
-    scrollBy(lines, id) {
-        this.#assertRunning("scroll");
-        if (id === undefined)
-            this.#requireFullscreen().scrollBy(lines);
-        else {
-            this.#requireScrollView(id).scrollBy(lines);
-            this.#tui.requestRender();
-        }
-    }
-    scrollToTop(id) {
-        this.#assertRunning("scroll");
-        if (id === undefined)
-            this.#requireFullscreen().scrollToTop();
-        else {
-            this.#requireScrollView(id).scrollToStart();
-            this.#tui.requestRender();
-        }
-    }
-    scrollToBottom(id) {
-        this.#assertRunning("scroll");
-        if (id === undefined)
-            this.#requireFullscreen().scrollToBottom();
-        else {
-            this.#requireScrollView(id).scrollToEnd();
-            this.#tui.requestRender();
-        }
-    }
     start() {
         if (this.#state === "running")
             return;
@@ -286,12 +239,6 @@ export class PiTuiRuntimeAdapter {
             throw new PiTuiRuntimeError("start", error);
         }
     }
-    setFocus(component) {
-        this.#assertRunning("focus");
-        if (this.#overlayInputCoordination.size > 0)
-            this.#overlayGeometry?.invalidate();
-        this.#tui.setFocus(this.#bridgeFor(component));
-    }
     showOverlay(component, options) {
         this.#assertRunning("overlay");
         if (this.#bridges.has(component))
@@ -340,9 +287,6 @@ export class PiTuiRuntimeAdapter {
         this.#assertRunning("presentation freeze");
         this.#presentationFrozen = true;
     }
-    get presentationFrozen() {
-        return this.#presentationFrozen;
-    }
     /**
      * Keeps asynchronous replacement-surface construction atomic at the terminal. Renderers may
      * compose while held, but their writes are dropped until the final forced repaint on release.
@@ -394,7 +338,7 @@ export class PiTuiRuntimeAdapter {
             previous.clear();
             if (previous instanceof TuiAltScreen)
                 previous.setLayoutRoot(undefined);
-            this.#scrollViews.clear();
+            this.#scrollIds.clear();
             const next = this.#createTui(mode, hardwareCursor);
             next.setClearOnShrink(clearOnShrink);
             this.#mountTui(next);
@@ -417,9 +361,6 @@ export class PiTuiRuntimeAdapter {
         if (this.active)
             this.#tui.requestRender();
     }
-    getHardwareCursor() {
-        return this.#tui.getShowHardwareCursor();
-    }
     setClearOnShrink(enabled) {
         this.#tui.setClearOnShrink(enabled);
     }
@@ -428,9 +369,6 @@ export class PiTuiRuntimeAdapter {
         if (this.#tui instanceof TuiAltScreen)
             this.#tui.setWheelScrollLines(lines);
     }
-    getClearOnShrink() {
-        return this.#tui.getClearOnShrink();
-    }
     setTerminalProgress(active) {
         if (this.#terminalProgress === active)
             return;
@@ -443,11 +381,6 @@ export class PiTuiRuntimeAdapter {
     setTitle(title) {
         this.#terminal.setTitle(title);
     }
-    /** Shows a bounded fullscreen acknowledgement without changing root layout geometry. */
-    showFlash(message, durationMs) {
-        this.#assertRunning("flash");
-        this.#requireFullscreen().flash(message, durationMs);
-    }
     writeAfterStop(text) {
         if (this.#state !== "stopped")
             throw new Error("terminal output requires a stopped Pi TUI runtime");
@@ -580,7 +513,7 @@ export class PiTuiRuntimeAdapter {
         if (node.type === "component")
             return this.#mount(node.component);
         if (node.type === "scroll") {
-            if (this.#scrollViews.has(node.id))
+            if (this.#scrollIds.has(node.id))
                 throw new TypeError(`duplicate Pi TUI scroll layout id: ${node.id}`);
             const options = {
                 ...(node.follow === undefined ? {} : { follow: node.follow }),
@@ -591,9 +524,8 @@ export class PiTuiRuntimeAdapter {
                 ...(node.scrollbarThumbStyle === undefined ? {} : { scrollbarThumbStyle: node.scrollbarThumbStyle }),
                 ...(node.scrollbarHideDelayMs === undefined ? {} : { scrollbarHideDelayMs: node.scrollbarHideDelayMs }),
             };
-            const scrollView = new ScrollView(this.#buildLayout(node.child), options);
-            this.#scrollViews.set(node.id, scrollView);
-            return scrollView;
+            this.#scrollIds.add(node.id);
+            return new ScrollView(this.#buildLayout(node.child), options);
         }
         const children = node.children.map(entry => ({
             component: this.#buildLayout(entry.node),
@@ -610,19 +542,6 @@ export class PiTuiRuntimeAdapter {
         };
         return node.direction === "vertical" ? new VStack(children, options) : new HStack(children, options);
     }
-    #requireFullscreen() {
-        if (!(this.#tui instanceof TuiAltScreen)) {
-            throw new Error("Pi TUI application scrolling is available only in fullscreen mode");
-        }
-        return this.#tui;
-    }
-    #requireScrollView(id) {
-        this.#requireFullscreen();
-        const scrollView = this.#scrollViews.get(id);
-        if (!scrollView)
-            throw new TypeError(`unknown Pi TUI scroll layout id: ${id}`);
-        return scrollView;
-    }
     #assertRunning(operation) {
         if (!this.active)
             throw new Error(`Pi TUI ${operation} requires a running runtime`);
@@ -683,12 +602,33 @@ export class PiTuiRuntimeAdapter {
         this.#disposeRoot();
     }
 }
-function coordinatedInputTerminal(terminal, coordinator, setSink, frameMouse) {
-    const mouse = frameMouse ? new MouseReportInput(data => coordinator.accept(data)) : undefined;
+/**
+ * Forwards every terminal member to `terminal` unless `overrides` replaces it.
+ * Invariant: the size and keyboard getters stay live; spreading the inner terminal would freeze them.
+ */
+function forwardingTerminal(terminal, overrides = {}) {
     return {
         get columns() { return terminal.columns; },
         get rows() { return terminal.rows; },
         get kittyProtocolActive() { return terminal.kittyProtocolActive; },
+        start: overrides.start ?? ((onInput, onResize) => terminal.start(onInput, onResize)),
+        stop: overrides.stop ?? (() => terminal.stop()),
+        drainInput: overrides.drainInput ?? ((maxMs, idleMs) => terminal.drainInput(maxMs, idleMs)),
+        write: overrides.write ?? (data => terminal.write(data)),
+        moveBy: overrides.moveBy ?? (lines => terminal.moveBy(lines)),
+        hideCursor: overrides.hideCursor ?? (() => terminal.hideCursor()),
+        showCursor: overrides.showCursor ?? (() => terminal.showCursor()),
+        clearLine: overrides.clearLine ?? (() => terminal.clearLine()),
+        clearFromCursor: overrides.clearFromCursor ?? (() => terminal.clearFromCursor()),
+        clearScreen: overrides.clearScreen ?? (() => terminal.clearScreen()),
+        setTitle: overrides.setTitle ?? (title => terminal.setTitle(title)),
+        setProgress: overrides.setProgress ?? (active => terminal.setProgress(active)),
+        setProgramStatus: overrides.setProgramStatus ?? (status => terminal.setProgramStatus?.(status)),
+    };
+}
+function coordinatedInputTerminal(terminal, coordinator, setSink, frameMouse) {
+    const mouse = frameMouse ? new MouseReportInput(data => coordinator.accept(data)) : undefined;
+    return forwardingTerminal(terminal, {
         start(onInput, onResize) {
             setSink(onInput);
             terminal.start(data => mouse === undefined ? coordinator.accept(data) : mouse.accept(data), () => {
@@ -703,27 +643,10 @@ function coordinatedInputTerminal(terminal, coordinator, setSink, frameMouse) {
             setSink(undefined);
             terminal.stop();
         },
-        drainInput: (maxMs, idleMs) => terminal.drainInput(maxMs, idleMs),
-        write: data => terminal.write(data),
-        moveBy: lines => terminal.moveBy(lines),
-        hideCursor: () => terminal.hideCursor(),
-        showCursor: () => terminal.showCursor(),
-        clearLine: () => terminal.clearLine(),
-        clearFromCursor: () => terminal.clearFromCursor(),
-        clearScreen: () => terminal.clearScreen(),
-        setTitle: title => terminal.setTitle(title),
-        setProgress: active => terminal.setProgress(active),
-        setProgramStatus: status => terminal.setProgramStatus?.(status),
-    };
+    });
 }
 function diagnosticTerminal(terminal, trace) {
-    return {
-        get columns() { return terminal.columns; },
-        get rows() { return terminal.rows; },
-        get kittyProtocolActive() { return terminal.kittyProtocolActive; },
-        start: (onInput, onResize) => terminal.start(onInput, onResize),
-        stop: () => terminal.stop(),
-        drainInput: (maxMs, idleMs) => terminal.drainInput(maxMs, idleMs),
+    return forwardingTerminal(terminal, {
         write(data) {
             trace("write-start");
             try {
@@ -733,25 +656,10 @@ function diagnosticTerminal(terminal, trace) {
                 trace("write-end");
             }
         },
-        moveBy: lines => terminal.moveBy(lines),
-        hideCursor: () => terminal.hideCursor(),
-        showCursor: () => terminal.showCursor(),
-        clearLine: () => terminal.clearLine(),
-        clearFromCursor: () => terminal.clearFromCursor(),
-        clearScreen: () => terminal.clearScreen(),
-        setTitle: title => terminal.setTitle(title),
-        setProgress: active => terminal.setProgress(active),
-        setProgramStatus: status => terminal.setProgramStatus?.(status),
-    };
+    });
 }
 function frozenGateTerminal(terminal, frozen) {
-    return {
-        get columns() { return terminal.columns; },
-        get rows() { return terminal.rows; },
-        get kittyProtocolActive() { return terminal.kittyProtocolActive; },
-        start: (onInput, onResize) => terminal.start(onInput, onResize),
-        stop: () => terminal.stop(),
-        drainInput: (maxMs, idleMs) => terminal.drainInput(maxMs, idleMs),
+    return forwardingTerminal(terminal, {
         write: data => { if (!frozen())
             terminal.write(data); },
         moveBy: lines => { if (!frozen())
@@ -766,17 +674,11 @@ function frozenGateTerminal(terminal, frozen) {
             terminal.clearFromCursor(); },
         clearScreen: () => { if (!frozen())
             terminal.clearScreen(); },
-        setTitle: title => terminal.setTitle(title),
-        setProgress: active => terminal.setProgress(active),
-        setProgramStatus: status => terminal.setProgramStatus?.(status),
-    };
+    });
 }
 function preInputTerminal(terminal, route, frameMouse) {
     let mouse;
-    return {
-        get columns() { return terminal.columns; },
-        get rows() { return terminal.rows; },
-        get kittyProtocolActive() { return terminal.kittyProtocolActive; },
+    return forwardingTerminal(terminal, {
         start(onInput, onResize) {
             const deliver = (data) => {
                 const routed = route(data);
@@ -790,18 +692,7 @@ function preInputTerminal(terminal, route, frameMouse) {
             });
         },
         stop: () => { mouse?.reset(); terminal.stop(); },
-        drainInput: (maxMs, idleMs) => terminal.drainInput(maxMs, idleMs),
-        write: data => terminal.write(data),
-        moveBy: lines => terminal.moveBy(lines),
-        hideCursor: () => terminal.hideCursor(),
-        showCursor: () => terminal.showCursor(),
-        clearLine: () => terminal.clearLine(),
-        clearFromCursor: () => terminal.clearFromCursor(),
-        clearScreen: () => terminal.clearScreen(),
-        setTitle: title => terminal.setTitle(title),
-        setProgress: active => terminal.setProgress(active),
-        setProgramStatus: status => terminal.setProgramStatus?.(status),
-    };
+    });
 }
 function toOverlayOptions(options) {
     if (options === undefined)

package/dist/integrations/pi/tui-runtime/damage-aware-terminal.d.ts

@@ -1,4 +1,4 @@
-import type { PiTuiTerminalPort } from "./contracts.js";
+import type { TerminalPort } from "../../../contracts/presentation/index.js";
 export declare const PINNED_PI_TUI_DAMAGE_GRAMMAR = "@earendil-works/pi-tui@1.5.0:tui-alt-screen-one-write-v1";
 import type { TerminalDamageDecision, TerminalDamageDecisionReason, TerminalDamageFrameDescriptor, TerminalDamageFrameSafety } from "../../../contracts/presentation/index.js";
 export type PiTuiDamageFrameDescriptor = TerminalDamageFrameDescriptor;
@@ -34,11 +34,11 @@ export interface DamageAwareTerminalOptions {
  * viewport metadata authorizes a shift; bytes are inspected only to validate
  * and preserve Pi's complete row paint and cursor syntax.
  */
-export declare class DamageAwareTerminalAdapter implements PiTuiTerminalPort {
+export declare class DamageAwareTerminalAdapter implements TerminalPort {
     #private;
-    readonly inner: PiTuiTerminalPort;
+    readonly inner: TerminalPort;
     readonly options: DamageAwareTerminalOptions;
-    constructor(inner: PiTuiTerminalPort, options: DamageAwareTerminalOptions);
+    constructor(inner: TerminalPort, options: DamageAwareTerminalOptions);
     get columns(): number;
     get rows(): number;
     get kittyProtocolActive(): boolean;

package/dist/integrations/pi/tui-runtime/index.d.ts

@@ -1,4 +1,3 @@
-export type { PiTuiComponentPort, PiTuiInputDiagnosticsEvent, PiTuiInputDiagnosticsPhase, PiTuiInputListener, PiTuiInputListenerResult, PiTuiLayoutEntry, PiTuiLayoutNode, PiTuiOverlayAnchor, PiTuiOverlayHandle, PiTuiOverlayMargin, PiTuiOverlayOptions, PiTuiOverlayUnfocusOptions, PiTuiPointerSurface, PiTuiPreInputListener, PiTuiRuntimeAdapterOptions, PiTuiRuntimeState, PiTuiScrollState, PiTuiSizeValue, PiTuiStopOptions, PiTuiTerminalPort, PiTuiViewport, } from "./contracts.js";
 export { samePointerSurfaces } from "./overlay-geometry.js";
 export { PI_TERMINAL_RUNTIME } from "./runtime-factory.js";
 export { DamageAwareTerminalAdapter, PINNED_PI_TUI_DAMAGE_GRAMMAR, paintTerminalCanvasFrame, rebaseTerminalDefaultBackground, } from "./damage-aware-terminal.js";