@timurproko/a1 0.2.6 → 0.2.7-dev.1221

package/dist/app/session-shell/session-viewport-controller.d.ts

@@ -1,7 +1,7 @@
 import type { PiTuiPointerSurface } from "../../integrations/pi/tui-runtime/contracts.js";
 import type { OwnedUiViewportSettings } from "../../contracts/owned-ui/index.js";
 import { type TranscriptViewportFrame, type TranscriptViewportFrameInput } from "../../ui/components/transcript-viewport.js";
-import type { SelectionCopySnapshot } from "../../ui/components/selection-copy.js";
+import { type SelectionCopySnapshot } from "../../ui/components/selection-copy.js";
 import type { PiShellEditorPort } from "../../integrations/pi/components/shell-shared-facade.js";
 import type { PasteEvent } from "./paste-protocol.js";
 export interface SessionViewportControllerOptions {
@@ -64,7 +64,7 @@ export declare class SessionViewportController {
     setOverlaySurfaces(surfaces: readonly PiTuiPointerSurface[] | null): void;
     get inputGeometryReady(): boolean;
     compose(input: Omit<TranscriptViewportFrameInput, "pointerPosition">): TranscriptViewportFrame;
-    composeDockOnly(dockRows: readonly string[], width: number, height: number): TranscriptViewportFrame | null;
+    composeDockOnly(dockRows: readonly string[], width: number, height: number, copyableDockRows?: TranscriptViewportFrameInput["copyableDockRows"]): TranscriptViewportFrame | null;
     /** Returns true when document wrapping may have changed. */
     setConfig(config: OwnedUiViewportSettings): boolean;
     resumeFollowing(): void;

package/dist/app/session-shell/session-viewport-controller.js

@@ -3,6 +3,7 @@ import { TranscriptViewport } from "../../ui/components/transcript-viewport.js";
 import { readVisibleHyperlinks } from "../../ui/components/visible-hyperlinks.js";
 import { routeMouseInput } from "../../ui/components/mouse.js";
 import { scrollForTrackPage, scrollForThumbRow, scrollbarSelectionRows, scrollbarWheelRows } from "../../ui/components/scrollbar.js";
+import { literalSelectionCopySnapshot } from "../../ui/components/selection-copy.js";
 function withinTailControl(region, column, row) {
     return row >= region.rowStart && row <= region.rowEnd && column >= region.columnStart && column <= region.columnEnd;
 }
@@ -22,6 +23,7 @@ export class SessionViewportController {
     #pasteDiagnosticRequest = 0;
     #viewport = new TranscriptViewport();
     #config = {
+        timeFormat: "8:00 PM",
         scrollbarAppearance: "auto",
         scrollbarStyle: "thin",
         scrollbarSpeed: "normal",
@@ -165,16 +167,18 @@ export class SessionViewportController {
         }
         return frame;
     }
-    composeDockOnly(dockRows, width, height) {
-        return this.#viewport.composeDockOnly(dockRows, width, height);
+    composeDockOnly(dockRows, width, height, copyableDockRows = []) {
+        return this.#viewport.composeDockOnly(dockRows, width, height, copyableDockRows);
     }
     /** Returns true when document wrapping may have changed. */
     setConfig(config) {
-        const appearanceChanged = config.scrollbarAppearance !== this.#config.scrollbarAppearance;
-        this.#config = config;
-        this.#viewport.setConfig(config);
+        const normalized = { ...config, timeFormat: config.timeFormat ?? "8:00 PM" };
+        const layoutChanged = normalized.scrollbarAppearance !== this.#config.scrollbarAppearance
+            || normalized.timeFormat !== this.#config.timeFormat;
+        this.#config = normalized;
+        this.#viewport.setConfig(normalized);
         this.#requestRender();
-        return appearanceChanged;
+        return layoutChanged;
     }
     resumeFollowing() {
         if (!this.#enabled)
@@ -302,11 +306,9 @@ export class SessionViewportController {
             });
         }
         if (data === "\u0003") {
-            if (editorActive && this.#editor.hasSelection()) {
-                if (this.#viewport.clearSelection())
-                    this.#requestRender();
-            }
-            else if (this.#viewport.hasSelection) {
+            // Invariant: the newest complete-frame gesture owns explicit copy even if an
+            // older editor word/line selection remains painted beneath it.
+            if (this.#viewport.hasSelection) {
                 const copySelection = this.#viewport.captureSelectedText();
                 this.#viewport.clearSelection();
                 this.#stopSelectionAutoScroll();
@@ -315,9 +317,13 @@ export class SessionViewportController {
                     ? { data: "", consumed: true }
                     : { data: "", consumed: true, copySelection };
             }
+            if (editorActive && this.#editor.hasSelection()) {
+                if (this.#viewport.clearSelection())
+                    this.#requestRender();
+            }
         }
-        const previousPrompt = SHIFT_UP_INPUTS.has(data) || this.#editor.matchesTerminalKey(data, "alt+home");
-        if (editorActive && allowWheel && (previousPrompt || SHIFT_DOWN_INPUTS.has(data))) {
+        const previousPrompt = PROMPT_UP_INPUTS.has(data) || this.#editor.matchesTerminalKey(data, "alt+home");
+        if (editorActive && allowWheel && (previousPrompt || PROMPT_DOWN_INPUTS.has(data))) {
             const scrolled = previousPrompt
                 ? this.#viewport.scrollToPreviousPrompt(now)
                 : this.#viewport.scrollToNextPrompt(now);
@@ -541,6 +547,12 @@ export class SessionViewportController {
                         const editorRow = pendingEditorClick.row - this.#editorPointerFrame.rowStart + 1;
                         this.#editor.handlePointer({ kind: "press", button: 0, column: pendingEditorClick.column, row: editorRow });
                         this.#editor.handlePointer({ kind: "release", button: 0, column: pendingEditorClick.column, row: editorRow });
+                        if (this.#copyOnSelect) {
+                            const selected = this.#editor.selectedText?.();
+                            if (selected !== undefined) {
+                                completedCopy = literalSelectionCopySnapshot(selected, this.#viewport.selectionRevision) ?? undefined;
+                            }
+                        }
                     }
                     forceRepaint = true;
                     repaint = true;
@@ -658,5 +670,7 @@ export class SessionViewportController {
 }
 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"]);
+// Platform: Windows Terminal may consume Shift+Arrow for native selection. Ctrl+Arrow matches
+// solo A1's Windows binding while retaining Shift+Arrow whenever the terminal delivers it.
+const PROMPT_UP_INPUTS = new Set(["\u001b[1;2A", "\u001b[1;5A"]);
+const PROMPT_DOWN_INPUTS = new Set(["\u001b[1;2B", "\u001b[1;5B"]);

package/dist/app/session-shell/settings-bindings.d.ts

@@ -0,0 +1,17 @@
+import type { OwnedUiSessionSettingsPort, OwnedUiSessionSettingsSnapshot } from "../../contracts/owned-ui/index.js";
+import type { OwnedUiPresenterTerminal } from "./shell-host.js";
+import type { OwnedUiSessionShellRoot } from "./session-shell-root.js";
+/** What the session's live setting effects reach: terminal modes, root presentation, and the presenter's progress flag. */
+export interface SessionSettingsTargets {
+    readonly terminal: Pick<OwnedUiPresenterTerminal, "setHardwareCursor" | "setClearOnShrink" | "setWheelScrollLines">;
+    readonly root: Pick<OwnedUiSessionShellRoot, "setEditorPaddingX" | "setAutocompleteMaxVisible" | "setOutputPad" | "setHideThinkingBlock" | "setMermaidRenderingMode" | "setImagePresentation" | "setFullscreenCopyOnSelect">;
+    setTerminalProgress(enabled: boolean): void;
+}
+/**
+ * Applies the snapshot's presentation settings, then binds every live setting effect the session
+ * owns, one owner at a time. The returned function releases the owners in reverse; a failed bind
+ * releases the owners already bound before it throws.
+ */
+export declare function bindSessionSettings(settings: Pick<OwnedUiSessionSettingsPort, "bindOwner" | "productMode">, snapshot: OwnedUiSessionSettingsSnapshot, targets: SessionSettingsTargets, options: {
+    readonly customViewport: boolean;
+}): () => void;

package/dist/app/session-shell/settings-bindings.js

@@ -0,0 +1,91 @@
+const isBoolean = (value) => typeof value === "boolean";
+const isNumber = (value) => typeof value === "number";
+const isOutputPad = (value) => value === 0 || value === 1;
+const isMermaidMode = (value) => value === "off" || value === "final" || value === "streaming";
+const isImageWidth = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 1;
+const isWheelDistance = (value) => value === "auto" || typeof value === "number" && Number.isSafeInteger(value) && value >= 1 && value <= 100;
+function snapshotValue(snapshot, key) {
+    const values = snapshot;
+    return values[key];
+}
+/** One validated setting; `seeded` also installs the snapshot's value at bind time. */
+function setting(owner, key, invalid, accepts, apply, seeded = true) {
+    return {
+        owner,
+        key,
+        live: value => {
+            if (!accepts(value))
+                throw new TypeError(invalid);
+            apply(value);
+        },
+        ...(seeded ? {
+            seed: (snapshot) => {
+                const value = snapshotValue(snapshot, key);
+                if (accepts(value))
+                    apply(value);
+            },
+        } : {}),
+    };
+}
+function settingBindings(targets, snapshot, customViewport, bare) {
+    const { root, terminal } = targets;
+    let showImages = snapshot.showImages;
+    let imageWidthCells = snapshot.imageWidthCells;
+    const presentImages = () => root.setImagePresentation(showImages, imageWidthCells);
+    return [
+        // Invariant: bare A1 prints only the resume hint at exit, so the pinned exit-output
+        // choice is hidden there and cannot be bound; the comparison profile binds and honors it.
+        ...(bare ? [] : [{ owner: "shutdown", key: "fullscreenExitOutput", live: () => { } }]),
+        setting("terminal", "showHardwareCursor", "Hardware cursor setting is invalid", isBoolean, value => terminal.setHardwareCursor(value)),
+        setting("terminal", "clearOnShrink", "Clear-on-shrink setting is invalid", isBoolean, value => terminal.setClearOnShrink(value)),
+        setting("terminal", "showTerminalProgress", "Terminal progress setting is invalid", isBoolean, value => targets.setTerminalProgress(value)),
+        setting("shell", "editorPaddingX", "Editor padding is invalid", isNumber, value => root.setEditorPaddingX(value)),
+        setting("shell", "autocompleteMaxVisible", "Autocomplete maximum is invalid", isNumber, value => root.setAutocompleteMaxVisible(value)),
+        setting("shell", "outputPad", "Output padding is invalid", isOutputPad, value => root.setOutputPad(value)),
+        setting("shell", "hideThinkingBlock", "Thinking-block visibility is invalid", isBoolean, value => root.setHideThinkingBlock(value)),
+        setting("shell", "mermaidRenderingMode", "Mermaid mode is invalid", isMermaidMode, value => root.setMermaidRenderingMode(value)),
+        setting("shell", "showImages", "Image visibility is invalid", isBoolean, value => { showImages = value; presentImages(); }, false),
+        setting("shell", "imageWidthCells", "Image width is invalid", isImageWidth, value => { imageWidthCells = value; presentImages(); }, false),
+        { owner: null, key: "imageWidthCells", live: () => { }, seed: presentImages },
+        // Invariant: the custom viewport owns copy-on-select; the pinned comparison profile keeps Pi's wheel distance.
+        customViewport
+            ? setting("shell", "fullscreenCopyOnSelect", "Fullscreen copy-on-select setting is invalid", isBoolean, value => root.setFullscreenCopyOnSelect(value))
+            : setting("shell", "fullscreenWheelScrollLines", "Fullscreen wheel-scroll distance is invalid", isWheelDistance, value => terminal.setWheelScrollLines(value), false),
+        ...(customViewport ? [] : [{
+                owner: null,
+                key: "fullscreenCopyOnSelect",
+                live: () => { },
+                seed: (initial) => root.setFullscreenCopyOnSelect(initial.fullscreenCopyOnSelect),
+            }]),
+    ];
+}
+/**
+ * Applies the snapshot's presentation settings, then binds every live setting effect the session
+ * owns, one owner at a time. The returned function releases the owners in reverse; a failed bind
+ * releases the owners already bound before it throws.
+ */
+export function bindSessionSettings(settings, snapshot, targets, options) {
+    const bindings = settingBindings(targets, snapshot, options.customViewport, settings.productMode === "bare");
+    for (const binding of bindings)
+        binding.seed?.(snapshot);
+    const owners = [...new Set(bindings.flatMap(binding => binding.owner === null ? [] : [binding.owner]))];
+    const releases = [];
+    const release = () => {
+        for (const unbind of releases.splice(0).reverse())
+            unbind();
+    };
+    try {
+        for (const owner of owners) {
+            const handlers = {};
+            for (const binding of bindings.filter(candidate => candidate.owner === owner)) {
+                handlers[binding.key] = { apply: value => binding.live(value) };
+            }
+            releases.push(settings.bindOwner(owner, handlers));
+        }
+    }
+    catch (error) {
+        release();
+        throw error;
+    }
+    return release;
+}

package/dist/app/session-shell/shell-editor-factory.d.ts

@@ -0,0 +1,27 @@
+import { type PiShellEditorOptions, type PiShellEditorPort } from "../../integrations/pi/components/shell-shared-facade.js";
+import type { PasteEvent, PasteSource } from "./paste-protocol.js";
+import type { PromptChipStore } from "./prompt-chips.js";
+/** The shell callbacks the editor is wired to; the editor receives the whole object as its own options. */
+export type ShellEditorHandlers = Omit<PiShellEditorOptions, "onChange" | "onToolsExpand" | "keybindingProfile"> & {
+    readonly requestRender: (force?: boolean) => void;
+    readonly onEditorChange?: (text: string) => void;
+    readonly captureClipboardPaste?: () => PasteSource;
+    readonly pasteDiagnostics?: (event: PasteEvent) => void;
+};
+export interface ShellEditorPorts {
+    readonly handlers: ShellEditorHandlers;
+    readonly customViewport: boolean;
+    readonly cwd: string;
+    readonly agentDir?: string;
+    readonly promptChips: PromptChipStore;
+    /** True while a pointer drag selects editor text, which paints links as plain underlines. */
+    readonly editorPointerSelecting: () => boolean;
+    /** The next payload-free paste diagnostic id, shared with the viewport's own paste diagnostics. */
+    readonly nextPasteDiagnosticRequest: () => number;
+    readonly toggleToolsExpanded: () => void;
+}
+/**
+ * Builds the session's prompt editor: chip-aware paste, selection, and hyperlink decoration over
+ * the Pi editor, plus bare A1's prompt presentation and terminal paste diagnostics.
+ */
+export declare function createShellEditor(ports: ShellEditorPorts): PiShellEditorPort;

package/dist/app/session-shell/shell-editor-factory.js

@@ -0,0 +1,102 @@
+import { caretCell } from "../../ui/components/line-input.js";
+import { PromptInput } from "../../ui/components/prompt-input.js";
+import { backgroundSgrSpan, hyperlinkSgrSpan } from "../../ui/components/spans.js";
+import { faint, stripAnsi } from "../../ui/components/text.js";
+import { createPiShellEditor } from "../../integrations/pi/components/shell-editor-autocomplete.js";
+import { piTheme } from "../../integrations/pi/components/upstream/theme/theme.js";
+import { piShellTruncateToWidth, piShellVisibleWidth, } from "../../integrations/pi/components/shell-shared-facade.js";
+import { EditorHyperlinkBudget } from "./editor-hyperlink-budget.js";
+import { canPreparePasteInline } from "./paste-text-preparation.js";
+/**
+ * Builds the session's prompt editor: chip-aware paste, selection, and hyperlink decoration over
+ * the Pi editor, plus bare A1's prompt presentation and terminal paste diagnostics.
+ */
+export function createShellEditor(ports) {
+    const { handlers, customViewport, promptChips } = ports;
+    let terminalPasteDiagnosticRequest;
+    const editor = createPiShellEditor({
+        ...handlers,
+        keybindingProfile: customViewport ? "a1" : "pi",
+        ...(handlers.keybindings === undefined ? {} : { keybindings: handlers.keybindings }),
+        paintEditorSelection: (line, from, to, atomic) => backgroundSgrSpan(line, from, to, atomic ? "\u001b[7m" : "\u001b[27m\u001b[48;2;38;79;120m", atomic ? "\u001b[27m" : "\u001b[49m", piShellVisibleWidth),
+        transformPastedContent: content => {
+            try {
+                return promptChips.transformPastedContent(content, editor.getText());
+            }
+            catch (error) {
+                handlers.onPasteRejected?.(error);
+                return "";
+            }
+        },
+        ...(customViewport ? {
+            beginClipboardPaste: () => promptChips.beginPaste(editor.getText(), handlers.captureClipboardPaste?.() ?? { kind: "provided", read: signal => handlers.readClipboardContent?.(signal) ?? Promise.resolve(null) }, error => handlers.onPasteRejected?.(error), () => handlers.requestRender()),
+            onPasteInput: (bytes, phase) => {
+                try {
+                    if (phase === "framing")
+                        terminalPasteDiagnosticRequest = ports.nextPasteDiagnosticRequest();
+                    const request = terminalPasteDiagnosticRequest ?? ports.nextPasteDiagnosticRequest();
+                    handlers.pasteDiagnostics?.({ request, phase, bytes, atMs: performance.now(), pending: 0, transport: "terminal",
+                        ...(phase === "settled" ? { outcome: "ready" } : {}) });
+                    if (phase === "settled")
+                        terminalPasteDiagnosticRequest = undefined;
+                }
+                catch { /* Invariant: payload-free diagnostics cannot interfere with the input path. */ }
+            },
+            deferTextPaste: text => !canPreparePasteInline(text),
+            beginTextPaste: text => promptChips.beginPaste(editor.getText(), { kind: "text", text }, error => handlers.onPasteRejected?.(error)),
+        } : {}),
+        editorAtomicRanges: line => promptChips.atomicRanges(line),
+        editorHiddenRanges: line => promptChips.hiddenRanges(line),
+        decorateEditorRow: editorRowDecorator(promptChips, ports.editorPointerSelecting),
+        expandCopiedEditorText: text => promptChips.expandCopiedText(text),
+        cwd: ports.cwd,
+        ...(ports.agentDir === undefined ? {} : { agentDir: ports.agentDir }),
+        onToolsExpand: () => ports.toggleToolsExpanded(),
+        ...(customViewport ? {
+            promptPresentation: {
+                input: new PromptInput({ fg: (token, text) => piTheme().fg(token, text) }, {
+                    measure: piShellVisibleWidth,
+                    truncate: piShellTruncateToWidth,
+                }),
+                styleSuggestion: faint,
+                styleSuggestionCaret: caretCell,
+            },
+        } : {}),
+        onChange: text => {
+            handlers.onEditorChange?.(text);
+            // Concurrency: Pi clears before onSubmit; capture waiting references before pruning removed chips.
+            queueMicrotask(() => promptChips.reconcileDraft(editor.getText()));
+        },
+        ...(handlers.onPromptSuggestionAccepted === undefined ? {} : { onPromptSuggestionAccepted: handlers.onPromptSuggestionAccepted }),
+    });
+    return editor;
+}
+/**
+ * Dims unsent chips and turns the draft's URLs into terminal hyperlinks, each target once per
+ * decoration pass; while a pointer drag selects, links paint as plain underlines instead.
+ */
+function editorRowDecorator(promptChips, editorPointerSelecting) {
+    const editorHyperlinks = new EditorHyperlinkBudget();
+    return (row, width, rowIndex) => {
+        if (rowIndex === 0)
+            editorHyperlinks.reset();
+        const plain = stripAnsi(row);
+        const dimmed = promptChips.unsentRanges(plain).reduce((result, range) => backgroundSgrSpan(result, piShellVisibleWidth(plain.slice(0, range.start)), piShellVisibleWidth(plain.slice(0, range.end)), "\u001b[2m", "\u001b[22m", piShellVisibleWidth), row);
+        const ranges = promptChips.hyperlinkRanges(plain);
+        if (ranges.length === 0 || !editorHyperlinks.takeCleanup())
+            return dimmed;
+        const linkResetAndTail = `\u001b]8;;\u001b\\\u001b[24m${" ".repeat(Math.max(0, width - piShellVisibleWidth(dimmed)))}`;
+        // Platform: VS15 is zero-column and default-ignorable. It breaks Windows Terminal's
+        // plain-text URL detector only in the held-button paint; semantic text stays exact.
+        const selecting = editorPointerSelecting();
+        const paintRow = selecting
+            ? dimmed.replaceAll("https://", "https:︎//").replaceAll("http://", "http:︎//")
+            : dimmed;
+        const decorated = selecting
+            ? ranges.reduce((result, range) => backgroundSgrSpan(result, piShellVisibleWidth(plain.slice(0, range.start)), piShellVisibleWidth(plain.slice(0, range.end)), "\u001b[4:4m", "\u001b[24m", piShellVisibleWidth), paintRow)
+            : ranges.filter(range => editorHyperlinks.take(range.target)).reduce((result, range) => hyperlinkSgrSpan(result, piShellVisibleWidth(plain.slice(0, range.start)), piShellVisibleWidth(plain.slice(0, range.end)), range.target, piShellVisibleWidth), dimmed);
+        // Platform: Windows Terminal can retain stale native dotted-link cells when a mutable
+        // prompt replaces a longer URL. Explicit non-link spaces overwrite that tail.
+        return `${decorated}${linkResetAndTail}`;
+    };
+}

package/dist/app/session-shell/shell-host.d.ts

@@ -78,6 +78,12 @@ export interface OwnedUiTerminalHostOptions {
     readonly backgroundSettings?: OwnedUiBackgroundSettingsPort;
     readonly quitOutro?: OwnedUiShellPresentationOptions["quitOutro"];
 }
+/** The size and render request a Pi component reads from the terminal it is shown on, read on every call. */
+export declare function componentRuntime(terminal: Pick<OwnedUiPresenterTerminal, "viewport" | "requestRender">): {
+    getColumns(): number;
+    getRows(): number;
+    requestRender(): void;
+};
 /** The terminal a session's shell options call for: its layout, TUI mode, cursor, and presentation seams. */
 export declare function sessionTerminalHostOptions(options: OwnedUiSessionShellOptions): OwnedUiTerminalHostOptions;
 /**

package/dist/app/session-shell/shell-host.js

@@ -1,10 +1,20 @@
 import { MOUSE_TRACKING_OFF, MOUSE_TRACKING_ON, parseMouseInput } from "../../ui/components/mouse.js";
 import { readVisibleHyperlinks } from "../../ui/components/visible-hyperlinks.js";
 import { piCanvasBackgroundAnsi } from "../../integrations/pi/components/theme.js";
+import { residentFixtureControl } from "../../foundation/resident-tabs/fixture-control.js";
+import { residentProgressObserver } from "../../foundation/resident-tabs/progress-observation.js";
 import { DamageAwareTerminalAdapter, } from "../../integrations/pi/tui-runtime/damage-aware-terminal.js";
-import { PiTuiRuntimeAdapter } from "../../integrations/pi/tui-runtime/adapter.js";
+import { PiTuiRuntimeAdapter, legacyKeyInput } from "../../integrations/pi/tui-runtime/adapter.js";
 import { classifyPiTuiInput } from "../../integrations/pi/tui-runtime/input-presentation-coordinator.js";
 import { pinnedLayoutRoot, } from "./session-shell-root.js";
+/** The size and render request a Pi component reads from the terminal it is shown on, read on every call. */
+export function componentRuntime(terminal) {
+    return {
+        getColumns: () => terminal.viewport().columns,
+        getRows: () => terminal.viewport().rows,
+        requestRender: () => terminal.requestRender(),
+    };
+}
 /** The terminal a session's shell options call for: its layout, TUI mode, cursor, and presentation seams. */
 export function sessionTerminalHostOptions(options) {
     const { backend, sessionLayout } = options.engine;
@@ -47,6 +57,8 @@ export class OwnedUiTerminalHost {
         this.#customViewport = options.layout === "custom-viewport";
         this.#quitOutro = options.quitOutro;
         const input = options.input;
+        const fixtureControl = residentFixtureControl();
+        const progressObserver = residentProgressObserver();
         let damageTerminal;
         const surface = {
             render: width => this.#active?.render(width) ?? [],
@@ -72,6 +84,13 @@ export class OwnedUiTerminalHost {
                         inspectHyperlinks: readVisibleHyperlinks,
                         onResize: () => this.#active?.noteImmediatePresentation(),
                         onHyperlinkCleanupRequired: () => this.runtime?.requestRender(true),
+                        ...(fixtureControl === null ? {} : {
+                            allowWrite: () => !fixtureControl.stopped("child-render-write"),
+                            writeChunks: data => fixtureControl.fragmentChildWrite(data),
+                        }),
+                        ...(progressObserver === null ? {} : {
+                            onWrite: ({ bytes, fragments, transaction, frameId, cause }) => progressObserver.childRenderWrite(bytes, fragments, transaction, frameId, cause),
+                        }),
                     });
                     return damageTerminal;
                 },
@@ -83,10 +102,13 @@ export class OwnedUiTerminalHost {
                     },
                 }),
             } : { layoutRoot: pinnedLayoutRoot(this.#delegatingLayoutParts()) }),
-            ...(input?.onEvent === undefined ? {} : {
+            ...(input?.onEvent === undefined && progressObserver === null ? {} : {
                 inputDiagnostics: {
-                    onEvent: input.onEvent,
-                    ...(input.now === undefined ? {} : { now: input.now }),
+                    onEvent: event => {
+                        input?.onEvent?.(event);
+                        progressObserver?.inputPhase?.(event.phase, event.revision);
+                    },
+                    ...(input?.now === undefined ? {} : { now: input.now }),
                 },
             }),
             ...(options.terminal === undefined ? {} : { terminal: options.terminal }),
@@ -146,6 +168,8 @@ export class OwnedUiTerminalHost {
     active() {
         return this.#active;
     }
+    // Invariant: resident tab visibility never gates rendering here; a hidden tab keeps painting into its
+    // resident terminal, and the native holder alone withholds inactive surfaces from attach clients.
     requestRender(from, force = false) {
         if (from === this.#active)
             this.runtime.requestRender(force);
@@ -335,7 +359,8 @@ export class OwnedUiTerminalHost {
                 callbacks.closed(rendered);
         };
         removeInterruptWatch = runtime.addInputListener(data => {
-            if (!attached() || !data.includes(INTERRUPT))
+            // Compatibility: a kitty-keyboard child reports Ctrl+C as a CSI-u sequence rather than the byte.
+            if (!attached() || !data.includes(INTERRUPT) && legacyKeyInput(data) !== INTERRUPT)
                 return undefined;
             // Protocol: route hosts decide whether one interrupt closes their app. Raw-input forwarding
             // is required because Pi handles Ctrl+C before the fullscreen overlay receives normal input.
@@ -393,8 +418,10 @@ export class OwnedUiTerminalHost {
                 const { events, rest } = parseMouseInput(data);
                 for (const event of events)
                     surface.handleMouse(event);
-                if (rest.length > 0)
-                    surface.handleInput(rest);
+                // Invariant: owned screens see legacy key bytes whether the terminal reports legacy or kitty keys.
+                const key = rest.length > 0 ? legacyKeyInput(rest) : "";
+                if (key.length > 0)
+                    surface.handleInput(key);
                 if (surface.isClosed()) {
                     closeSurface(true);
                     return;

package/dist/app/session-shell/shell-layout.d.ts

@@ -0,0 +1,64 @@
+import type { OwnedUiSessionViewModel } from "../../contracts/owned-ui/index.js";
+import type { TranscriptViewportFrame, TranscriptViewportFrameInput, TranscriptViewportTheme } from "../../ui/components/transcript-viewport.js";
+import type { PiShellEditorPort } from "../../integrations/pi/components/shell-shared-facade.js";
+import type { DockChrome } from "./dock-chrome.js";
+import type { InputSurfaceSwitch } from "./input-surface-switch.js";
+import type { PromptChipStore } from "./prompt-chips.js";
+import type { SessionViewportController } from "./session-viewport-controller.js";
+import type { TranscriptDocumentLayout } from "./transcript-document.js";
+/** The dock's rows and where its input and footer sit inside them. */
+export interface DockLayout {
+    readonly rows: readonly string[];
+    readonly inputOffset: number;
+    readonly editorOffset: number;
+    readonly inputRows: number;
+    readonly footerRows: number;
+    /** Exact status, warning, error, command-result, and notice rows; queued and structural rows stay excluded. */
+    readonly copyableMessageRows: NonNullable<TranscriptViewportFrameInput["copyableDockRows"]>;
+}
+/** What a layout reads from the shell root to compose one frame. */
+export interface ShellLayoutPorts {
+    readonly viewport: SessionViewportController;
+    readonly input: InputSurfaceSwitch;
+    readonly editor: Pick<PiShellEditorPort, "getText">;
+    readonly promptChips: Pick<PromptChipStore, "atomicRanges">;
+    readonly dockChrome: Pick<DockChrome, "renderCopyAcknowledgement" | "renderReleaseBanner" | "locateReleaseClose">;
+    readonly theme: TranscriptViewportTheme;
+    readonly onFrame?: (frame: TranscriptViewportFrame) => void;
+    rows(): number;
+    dock(width: number): DockLayout;
+    document(width: number): TranscriptDocumentLayout;
+    queued(width: number): readonly string[];
+    liveStatus(width: number): readonly string[];
+    diagnostics(): OwnedUiSessionViewModel["diagnostics"];
+}
+/**
+ * How one session's root composes a frame. The root picks one layout at construction and never
+ * consults the layout mode again on the render path.
+ */
+export interface ShellLayout {
+    render(width: number): readonly string[];
+    /** Visible content changed outside a render, so the next frame may not reuse the last one. */
+    invalidate(): void;
+    /** What the last composed frame represented, for payload-free evidence; undefined before one exists. */
+    composed(): {
+        readonly viewportRevision: number;
+        readonly pointerPosition: TranscriptViewportFrameInput["pointerPosition"];
+    } | undefined;
+    compositions(): {
+        readonly full: number;
+        readonly dockOnly: number;
+    };
+}
+/** The pinned comparison profile: the whole document above the dock; the terminal host scrolls it. */
+export declare class PinnedLayout implements ShellLayout {
+    #private;
+    constructor(ports: ShellLayoutPorts);
+    render(width: number): readonly string[];
+    invalidate(): void;
+    composed(): undefined;
+    compositions(): {
+        readonly full: number;
+        readonly dockOnly: number;
+    };
+}

package/dist/app/session-shell/shell-layout.js

@@ -0,0 +1,18 @@
+/** The pinned comparison profile: the whole document above the dock; the terminal host scrolls it. */
+export class PinnedLayout {
+    #ports;
+    constructor(ports) {
+        this.#ports = ports;
+    }
+    render(width) {
+        this.#ports.viewport.setEditorPointerFrame(undefined);
+        return [...this.#ports.document(width).rows, ...this.#ports.dock(width).rows];
+    }
+    invalidate() { }
+    composed() {
+        return undefined;
+    }
+    compositions() {
+        return { full: 0, dockOnly: 0 };
+    }
+}

package/dist/app/session-shell/suggestion-surface.d.ts

@@ -0,0 +1,25 @@
+import type { OwnedUiEvent, OwnedUiPromptSuggestionIdentity, OwnedUiSessionViewModel, SuggestionDecision } from "../../contracts/owned-ui/index.js";
+import type { ContextualPromptSuggestionController, ContextualPromptSuggestionSurface } from "./prompt-suggestion-controller.js";
+import type { OwnedUiSessionShellRoot } from "./session-shell-root.js";
+type ResponseEvent = Extract<OwnedUiEvent, {
+    readonly type: "assistant-message-completed" | "agent-run-settled";
+}>;
+/** The provider/model key a suggestion identity and the session view are compared by; empty without a model. */
+export declare function suggestionModelKey(view: Pick<OwnedUiSessionViewModel, "activeModel">): string;
+/**
+ * Why a completed response cannot seed a suggestion, checked in order; `prepareBlockReason` is asked
+ * only when the response itself qualifies.
+ */
+export declare function responseSuggestionDecision(event: ResponseEvent, prepareBlockReason: () => SuggestionDecision): SuggestionDecision;
+/** Hands one completed or settled response to the controller: skipped without a model, otherwise considered or settled. */
+export declare function routeResponseToSuggestions(controller: Pick<ContextualPromptSuggestionController, "skip" | "consider" | "settle"> | null, event: ResponseEvent, prepareBlockReason: () => SuggestionDecision): void;
+export interface SuggestionPresentationState {
+    readonly disposed: boolean;
+    readonly view: Pick<OwnedUiSessionViewModel, "sessionId" | "activeModel">;
+    readonly sessionGeneration: number;
+}
+/** Why a prepared suggestion cannot be shown now: a released shell, a different session or model, or the root's own reason. */
+export declare function suggestionPresentationBlockReason(identity: OwnedUiPromptSuggestionIdentity, state: SuggestionPresentationState, rootBlockReason: () => SuggestionDecision): SuggestionDecision;
+/** The controller's view of the shell: ghost text in the root's editor, gated by `blockReason`. */
+export declare function promptSuggestionSurface(root: Pick<OwnedUiSessionShellRoot, "canPresentPromptSuggestion" | "setPromptSuggestion">, blockReason: (identity: OwnedUiPromptSuggestionIdentity) => SuggestionDecision, requestRender: () => void): ContextualPromptSuggestionSurface;
+export {};

package/dist/app/session-shell/suggestion-surface.js

@@ -0,0 +1,63 @@
+/** The provider/model key a suggestion identity and the session view are compared by; empty without a model. */
+export function suggestionModelKey(view) {
+    return view.activeModel === null ? "" : `${view.activeModel.providerId}/${view.activeModel.modelId}`;
+}
+/**
+ * Why a completed response cannot seed a suggestion, checked in order; `prepareBlockReason` is asked
+ * only when the response itself qualifies.
+ */
+export function responseSuggestionDecision(event, prepareBlockReason) {
+    if (!event.successful)
+        return "failed-response";
+    if (event.toolContinuation || event.stopReason === "toolUse")
+        return "tool-continuation";
+    if (event.stopReason !== "stop")
+        return "incomplete-response";
+    if (event.assistantMessageCount < 2)
+        return "early-conversation";
+    return prepareBlockReason();
+}
+/** Hands one completed or settled response to the controller: skipped without a model, otherwise considered or settled. */
+export function routeResponseToSuggestions(controller, event, prepareBlockReason) {
+    const identity = {
+        sessionId: event.sessionId,
+        sessionGeneration: event.sessionGeneration,
+        runSequence: event.runSequence,
+        responseSequence: event.responseSequence,
+        model: event.model,
+    };
+    if (event.model === null) {
+        controller?.skip(identity, "no-model");
+        return;
+    }
+    const known = { ...identity, model: event.model };
+    const decision = responseSuggestionDecision(event, prepareBlockReason);
+    if (event.type === "assistant-message-completed")
+        controller?.consider(known, decision);
+    else
+        controller?.settle(known, decision);
+}
+/** Why a prepared suggestion cannot be shown now: a released shell, a different session or model, or the root's own reason. */
+export function suggestionPresentationBlockReason(identity, state, rootBlockReason) {
+    if (state.disposed)
+        return "disposed";
+    if (identity.sessionId !== state.view.sessionId || identity.sessionGeneration !== state.sessionGeneration
+        || suggestionModelKey(state.view) !== `${identity.model.providerId}/${identity.model.modelId}`)
+        return "stale-identity";
+    return rootBlockReason();
+}
+/** The controller's view of the shell: ghost text in the root's editor, gated by `blockReason`. */
+export function promptSuggestionSurface(root, blockReason, requestRender) {
+    return {
+        canPresent: identity => blockReason(identity) === null,
+        presentationBlockReason: blockReason,
+        present: text => {
+            if (!root.canPresentPromptSuggestion())
+                return false;
+            root.setPromptSuggestion(text);
+            return true;
+        },
+        clear: () => root.setPromptSuggestion(null),
+        requestRender,
+    };
+}