@timurproko/a1 0.2.6 → 0.2.7-dev.1221

package/dist/app/session-shell/transcript-document.d.ts

@@ -0,0 +1,78 @@
+import type { OwnedUiSessionViewModel, OwnedUiViewportSettings } from "../../contracts/owned-ui/index.js";
+import type { TranscriptPromptAnchor } from "../../ui/components/transcript-viewport.js";
+import type { PiShellTranscriptComponentPort } from "../../integrations/pi/components/shell-shared-facade.js";
+type TranscriptBlock = OwnedUiSessionViewModel["transcript"][number];
+export interface TranscriptDocumentLayout {
+    readonly rows: readonly string[];
+    readonly promptAnchors: readonly TranscriptPromptAnchor[];
+    readonly liveTailStartRow: number | undefined;
+}
+/**
+ * Why the document's caches must drop. Layout-only reasons keep each block's rendered rows; the
+ * others also drop every block's rows because what a block draws has changed without its revision.
+ */
+export type TranscriptInvalidation = "editor-padding" | "diagnostics" | "workflow-status" | "extension-header" | "viewport-config" | "extension-renderers" | "block-presentation" | "tools-expanded" | "repaint";
+/** What the document reads from the shell around it on every uncached layout. */
+export interface TranscriptDocumentChrome {
+    diagnostics(): OwnedUiSessionViewModel["diagnostics"];
+    /** The extension header's rows when one is set, else the built-in header's rows for this layout. */
+    headerRows(width: number): readonly string[];
+    /** The loaded-resources listing the pinned layout shows above the transcript. */
+    resourceRows(width: number): readonly string[];
+    /** An extension header may animate, so a document under one is never cached. */
+    hasExtensionHeader(): boolean;
+    thinkingVisible(): boolean;
+    timeFormat(): OwnedUiViewportSettings["timeFormat"];
+}
+export interface TranscriptDocumentOptions {
+    readonly customViewport: boolean;
+    readonly cwd: string;
+    /** Creates the component for a newly seen block; its change callback should call `blockChanged`. */
+    mount(block: TranscriptBlock): PiShellTranscriptComponentPort;
+    readonly chrome: TranscriptDocumentChrome;
+}
+/**
+ * The only owner of the transcript's blocks, their order (including anchored workflow output), the
+ * per-block rendered rows, and the per-width document layouts. Every cache drop names its reason.
+ */
+export declare class TranscriptDocument {
+    #private;
+    constructor(options: TranscriptDocumentOptions);
+    /** Block component renders since construction, for rendering evidence. */
+    get renderCount(): number;
+    get lastId(): string | undefined;
+    component(id: string): PiShellTranscriptComponentPort | undefined;
+    components(): IterableIterator<PiShellTranscriptComponentPort>;
+    anchorOf(id: string): number | undefined;
+    /**
+     * Applies one block: its component is created or updated in place and the order grows
+     * only when the block is new. A streamed chunk costs one component update rather than a
+     * walk of the whole transcript.
+     */
+    apply(block: TranscriptBlock): void;
+    /** Replaces the whole transcript with the view's blocks, keeping anchored workflow output in place. */
+    sync(blocks: OwnedUiSessionViewModel["transcript"]): void;
+    /** Appends workflow output anchored after the transcript's first `anchor` blocks. */
+    appendAnchored(id: string, component: PiShellTranscriptComponentPort, anchor: number): void;
+    /** Disposes every anchored workflow output and drops it from the order. */
+    removeAnchored(): void;
+    /** One block's component drew something new: drop its rows and every layout that contains them. */
+    blockChanged(id: string): void;
+    invalidate(reason: TranscriptInvalidation): void;
+    /** A new session binding owns new mounts even when it reuses semantic invocation ids. */
+    reset(): void;
+    /** Disposes every component; anchors and blocks are left for a shell that is going away. */
+    dispose(): void;
+    layout(width: number): TranscriptDocumentLayout;
+    /** The transcript as plain rows for the parent terminal after a fullscreen leave. */
+    exitTranscript(width: number): string;
+}
+/** The release, command, and optional changelog carried by the adapter's `release-update` diagnostic. */
+export declare function parseReleaseUpdateDiagnostic(message: string): {
+    version: string;
+    command: string;
+    changelogUrl: string | null;
+} | null;
+/** Web URLs use link blue; file targets retain A1's cyan interactive accent. */
+export declare function nativeTranscriptLinkColor(text: string, target: string): string;
+export {};

package/dist/app/session-shell/transcript-document.js

@@ -0,0 +1,365 @@
+import { acceptsTranscriptUpdate } from "../../contracts/owned-ui/index.js";
+import { formatSubmittedPromptTime, submittedPromptLayout } from "../../ui/components/submitted-prompt.js";
+import { nativeHyperlinkStyle, overlaySpan } from "../../ui/components/spans.js";
+import { displayWidth } from "../../ui/components/text.js";
+import { createPiShellChangelog, createPiShellCollapsedChangelog, renderPiShellPackageUpdateNotice, renderPiShellReleaseUpdateNotice, } from "../../integrations/pi/components/shell-presenters-info.js";
+import { isPiPromptStyleCompaction, paintPiSubmittedPromptTimestamp, renderPiShellStartupDiagnostic, renderPiShellTranscriptBlock, } from "../../integrations/pi/components/shell-presenters-transcript.js";
+import { piTheme } from "../../integrations/pi/components/upstream/theme/theme.js";
+const LAYOUT_ONLY = new Set(["editor-padding", "diagnostics", "workflow-status", "extension-header"]);
+const WORKFLOW_STATUS_PREFIX = "workflow-status-";
+/**
+ * The only owner of the transcript's blocks, their order (including anchored workflow output), the
+ * per-block rendered rows, and the per-width document layouts. Every cache drop names its reason.
+ */
+export class TranscriptDocument {
+    #options;
+    #components = new Map();
+    #blocks = new Map();
+    #anchors = new Map();
+    #order = [];
+    #renderedRows = new Map();
+    // Performance: document layouts are shared by wheel, rail, jump, and selection frames.
+    #layouts = new Map();
+    #renders = 0;
+    constructor(options) {
+        this.#options = options;
+    }
+    /** Block component renders since construction, for rendering evidence. */
+    get renderCount() {
+        return this.#renders;
+    }
+    get lastId() {
+        return this.#order.at(-1);
+    }
+    component(id) {
+        return this.#components.get(id);
+    }
+    components() {
+        return this.#components.values();
+    }
+    anchorOf(id) {
+        return this.#anchors.get(id);
+    }
+    /**
+     * Applies one block: its component is created or updated in place and the order grows
+     * only when the block is new. A streamed chunk costs one component update rather than a
+     * walk of the whole transcript.
+     */
+    apply(block) {
+        const current = this.#blocks.get(block.id);
+        // Invariant: a full-view/final presentation may preempt queued partials. Never revive an older revision.
+        if (current !== undefined && !acceptsTranscriptUpdate(current, block))
+            return;
+        this.#blocks.set(block.id, block);
+        const component = this.#components.get(block.id);
+        if (component === undefined) {
+            this.#components.set(block.id, this.#options.mount(block));
+            this.#order.push(block.id);
+        }
+        else if (component.revision !== block.revision) {
+            component.update(block);
+        }
+        // Performance: one chunk touches one block, and the updated component tracks its own dirtiness.
+        // Invalidating the whole shell here would re-wrap the entire transcript per chunk.
+        this.blockChanged(block.id);
+    }
+    /** Replaces the whole transcript with the view's blocks, keeping anchored workflow output in place. */
+    sync(blocks) {
+        const previousIds = this.#order.filter(id => !id.startsWith(WORKFLOW_STATUS_PREFIX));
+        const transcriptChanged = previousIds.length !== blocks.length || blocks.some((block, index) => {
+            const previous = this.#blocks.get(block.id);
+            return previousIds[index] !== block.id || previous?.revision !== block.revision;
+        });
+        if (transcriptChanged)
+            this.#layouts.clear();
+        this.#blocks.clear();
+        for (const block of blocks)
+            this.#blocks.set(block.id, block);
+        const nextIds = new Set(blocks.map(block => block.id));
+        for (const [id, component] of this.#components) {
+            if (id.startsWith(WORKFLOW_STATUS_PREFIX) || nextIds.has(id))
+                continue;
+            component.dispose?.();
+            this.#components.delete(id);
+            this.#renderedRows.delete(id);
+        }
+        for (const block of blocks) {
+            const component = this.#components.get(block.id);
+            if (component === undefined)
+                this.#components.set(block.id, this.#options.mount(block));
+            else if (component.revision !== block.revision)
+                component.update(block);
+        }
+        const statusIds = [...this.#anchors.keys()];
+        const order = [];
+        for (let index = 0; index <= blocks.length; index += 1) {
+            for (const statusId of statusIds) {
+                if (this.#anchors.get(statusId) === index)
+                    order.push(statusId);
+            }
+            const block = blocks[index];
+            if (block !== undefined)
+                order.push(block.id);
+        }
+        const placed = new Set(order);
+        for (const statusId of statusIds) {
+            if (!placed.has(statusId))
+                order.push(statusId);
+        }
+        this.#order = order;
+    }
+    /** Appends workflow output anchored after the transcript's first `anchor` blocks. */
+    appendAnchored(id, component, anchor) {
+        if (!id.startsWith(WORKFLOW_STATUS_PREFIX))
+            throw new TypeError(`anchored output id must start with ${WORKFLOW_STATUS_PREFIX}`);
+        this.#components.set(id, component);
+        this.#anchors.set(id, anchor);
+        this.#order.push(id);
+        this.#layouts.clear();
+    }
+    /** Disposes every anchored workflow output and drops it from the order. */
+    removeAnchored() {
+        for (const id of this.#anchors.keys()) {
+            this.#components.get(id)?.dispose?.();
+            this.#components.delete(id);
+        }
+        this.#anchors.clear();
+        this.#order = this.#order.filter(id => !id.startsWith(WORKFLOW_STATUS_PREFIX));
+        this.#layouts.clear();
+    }
+    /** One block's component drew something new: drop its rows and every layout that contains them. */
+    blockChanged(id) {
+        this.#renderedRows.delete(id);
+        this.#layouts.clear();
+    }
+    invalidate(reason) {
+        if (!LAYOUT_ONLY.has(reason))
+            this.#renderedRows.clear();
+        this.#layouts.clear();
+        if (reason === "repaint")
+            for (const component of this.#components.values())
+                component.invalidate();
+    }
+    /** A new session binding owns new mounts even when it reuses semantic invocation ids. */
+    reset() {
+        for (const component of this.#components.values())
+            component.dispose?.();
+        this.#components.clear();
+        this.#blocks.clear();
+        this.#order = [];
+        this.#renderedRows.clear();
+        this.#layouts.clear();
+    }
+    /** Disposes every component; anchors and blocks are left for a shell that is going away. */
+    dispose() {
+        for (const component of this.#components.values())
+            component.dispose?.();
+        this.#components.clear();
+        this.#renderedRows.clear();
+        this.#layouts.clear();
+    }
+    layout(width) {
+        const { chrome, customViewport } = this.#options;
+        // Performance: extension headers may animate independently of transcript revisions, so
+        // only the stable built-in document participates in this frame cache.
+        const cacheable = !chrome.hasExtensionHeader();
+        const cached = cacheable ? this.#layouts.get(width) : undefined;
+        if (cached !== undefined)
+            return cached;
+        const diagnostics = chrome.diagnostics();
+        const thinkingVisible = chrome.thinkingVisible();
+        const startupRows = diagnostics
+            // Compatibility: the pinned route keeps trust failures with Pi-style startup diagnostics;
+            // bare A1 presents them in its prompt-adjacent notice dock instead.
+            .filter(diagnostic => diagnostic.code === "engine-startup"
+            || !customViewport && diagnostic.code === "project-trust")
+            .flatMap(diagnostic => renderPiShellStartupDiagnostic(diagnostic, width));
+        const resourceRows = [...chrome.resourceRows(width)];
+        if (resourceRows.at(-1) === "")
+            resourceRows.pop();
+        const rows = [
+            ...startupRows,
+            ...chrome.headerRows(width),
+            ...resourceRows,
+        ];
+        const promptAnchors = [];
+        // Rationale: a block that is still streaming re-renders every row it owns, so the frame
+        // reports where its rows begin. Damage-aware painting uses that to tell a live block's
+        // own reflow apart from a repaint that reaches settled rows.
+        let liveTailStartRow;
+        for (let index = 0; index < this.#order.length; index += 1) {
+            const id = this.#order[index];
+            const block = this.#blocks.get(id);
+            if (!thinkingVisible && block?.kind === "thinking")
+                continue;
+            const promptLike = block !== undefined
+                && (block.kind === "user" || customViewport && isPiPromptStyleCompaction(block));
+            // Invariant: the custom viewport has already removed its rail gutter from this width.
+            // Prompt-like and ordinary blocks therefore share one right content edge.
+            const blockWidth = width;
+            const blockRows = this.#blockRows(id, block, blockWidth);
+            if (promptLike) {
+                // Compatibility: the first natural prompt gets one breathing row at the document top.
+                // Once scrolling advances, the prompt itself reaches row zero and then
+                // becomes sticky there, so the spacer is never pinned with it.
+                if (customViewport && index === 0)
+                    rows.push("");
+                else if (index > 0)
+                    rows.push("");
+            }
+            const firstRow = rows.length;
+            if (liveTailStartRow === undefined && block !== undefined && block.status !== "finalized") {
+                liveTailStartRow = firstRow;
+            }
+            rows.push(...blockRows);
+            if (promptLike && blockRows[0] !== undefined) {
+                const source = pinnedPromptSource(block, blockRows[0], blockWidth, chrome.timeFormat());
+                promptAnchors.push({
+                    id: block.id,
+                    firstRow,
+                    lastRow: Math.max(firstRow, rows.length - 1),
+                    sourceRow: source.row,
+                    copySuffixWidth: source.copySuffixWidth,
+                    prominentSourceRow: blockRows[0],
+                });
+            }
+        }
+        rows.push(...this.#noticeRows(diagnostics, width));
+        const layout = { rows: Object.freeze(rows), promptAnchors: Object.freeze(promptAnchors), liveTailStartRow };
+        if (cacheable) {
+            this.#layouts.set(width, layout);
+            // Performance: the custom viewport commonly probes full width and reserved-rail width.
+            while (this.#layouts.size > 2)
+                this.#layouts.delete(this.#layouts.keys().next().value);
+        }
+        return layout;
+    }
+    // Invariant: release, package, and changelog notices, then the last three other diagnostics, close the document.
+    #noticeRows(diagnostics, width) {
+        const { customViewport, cwd } = this.#options;
+        const rows = [];
+        // Invariant: the A1 release notice precedes the extension-package notice, matching pinned Pi's order.
+        // Bare A1 docks it in the viewport tail instead of the document.
+        rows.push(...diagnostics
+            .filter(diagnostic => !customViewport && diagnostic.code === "release-update")
+            .flatMap(diagnostic => {
+            const release = parseReleaseUpdateDiagnostic(diagnostic.message);
+            return release === null ? [] : renderPiShellReleaseUpdateNotice(release, width);
+        }));
+        rows.push(...diagnostics
+            .filter(diagnostic => diagnostic.code === "package-updates")
+            .flatMap(diagnostic => renderPiShellPackageUpdateNotice(diagnostic.message.split("\n").filter(line => line.startsWith("- ")).map(line => line.slice(2)), width)));
+        rows.push(...diagnostics
+            .filter(diagnostic => diagnostic.code === "changelog-collapsed" || diagnostic.code === "changelog-expanded")
+            // Rationale: bare A1 translates either startup diagnostic into transient dock chrome;
+            // the pinned layout retains Pi's collapsed hint or expanded document.
+            .flatMap(diagnostic => customViewport
+            ? []
+            : diagnostic.code === "changelog-collapsed"
+                ? createPiShellCollapsedChangelog().render(width)
+                : createPiShellChangelog(diagnostic.message).render(width)));
+        rows.push(...diagnostics
+            .filter(diagnostic => diagnostic.code !== "engine-startup" && diagnostic.code !== "project-trust"
+            && diagnostic.code !== "release-update" && diagnostic.code !== "release-update-installed"
+            && diagnostic.code !== "package-updates" && diagnostic.code !== "changelog-collapsed"
+            && diagnostic.code !== "changelog-expanded")
+            .slice(-3)
+            .flatMap(diagnostic => renderPiShellTranscriptBlock({
+            id: `diagnostic-${diagnostic.sequence}`,
+            kind: diagnostic.severity === "error" ? "error" : "system",
+            status: "finalized",
+            revision: diagnostic.sequence,
+            title: diagnostic.code,
+            text: diagnostic.message,
+            payload: {},
+        }, width, cwd)));
+        return rows;
+    }
+    /** The transcript as plain rows for the parent terminal after a fullscreen leave. */
+    exitTranscript(width) {
+        const thinkingVisible = this.#options.chrome.thinkingVisible();
+        const rows = [];
+        for (const id of this.#order) {
+            const block = this.#blocks.get(id);
+            if (block === undefined || (!thinkingVisible && block.kind === "thinking"))
+                continue;
+            if (rows.length > 0 && (block.kind === "user" || this.#options.customViewport && isPiPromptStyleCompaction(block)))
+                rows.push("");
+            rows.push(...this.#blockRows(id, block, width).map(sanitizeExitTranscriptRow));
+        }
+        while (rows.at(-1) === "")
+            rows.pop();
+        return rows.join("\n");
+    }
+    // Performance: finalized blocks cache by revision and width; live blocks always render.
+    #blockRows(id, block, width) {
+        const component = this.#components.get(id);
+        if (component === undefined)
+            return [];
+        const render = () => {
+            this.#renders += 1;
+            const rows = component.render(width);
+            if (!this.#options.customViewport || block?.kind === "user")
+                return rows;
+            return rows.map(row => nativeHyperlinkStyle(row, nativeTranscriptLinkColor));
+        };
+        if (block === undefined || block.status !== "finalized")
+            return render();
+        let byWidth = this.#renderedRows.get(id);
+        const cached = byWidth?.get(width);
+        const presentationRevision = component.presentationRevision ?? 0;
+        if (cached?.revision === block.revision && cached.presentationRevision === presentationRevision)
+            return cached.rows;
+        const rows = render();
+        if (byWidth === undefined) {
+            byWidth = new Map();
+            this.#renderedRows.set(id, byWidth);
+        }
+        byWidth.set(width, { revision: block.revision, presentationRevision, rows });
+        // Invariant: bare A1 probes full width before reserving the overflowing rail column;
+        // retain both widths without turning resize history into an unbounded cache.
+        while (byWidth.size > 2)
+            byWidth.delete(byWidth.keys().next().value);
+        return rows;
+    }
+}
+/** The release, command, and optional changelog carried by the adapter's `release-update` diagnostic. */
+export function parseReleaseUpdateDiagnostic(message) {
+    const [instruction, changelog] = message.split("\n");
+    const match = /^New version (\S+) is available\. Run (.+)$/.exec(instruction ?? "");
+    if (match === null)
+        return null;
+    const url = changelog === undefined ? null : /^Changelog: (\S+)$/.exec(changelog)?.[1] ?? null;
+    return { version: match[1], command: match[2], changelogUrl: url };
+}
+const KITTY_IMAGE_CONTROL = /\u001b_G[\s\S]*?\u001b\\/g;
+const ITERM_IMAGE_CONTROL = /\u001b]1337;File=[^\u0007]*(?:\u0007|\u001b\\)/g;
+/** Keep semantic SGR/OSC styling while excluding non-replayable image payloads. */
+function sanitizeExitTranscriptRow(row) {
+    return row.replace(KITTY_IMAGE_CONTROL, "").replace(ITERM_IMAGE_CONTROL, "");
+}
+/** Web URLs use link blue; file targets retain A1's cyan interactive accent. */
+export function nativeTranscriptLinkColor(text, target) {
+    return piTheme().fg(/^file:/iu.test(target) ? "accent" : "mdLink", text);
+}
+/** Preserve the stable metadata-grey foreground for every pinned timestamp state. */
+function pinnedPromptSource(block, sourceRow, width, timeFormat) {
+    const unchanged = { row: sourceRow, copySuffixWidth: 0 };
+    if (typeof block.payload !== "object" || block.payload === null)
+        return unchanged;
+    const value = block.payload.timestamp;
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return unchanged;
+    const format = timeFormat ?? "8:00 PM";
+    const timestamp = formatSubmittedPromptTime(value, format);
+    if (timestamp === null || submittedPromptLayout(width, value, format).timestamp === null)
+        return unchanged;
+    const rowWidth = displayWidth(sourceRow);
+    const timestampWidth = displayWidth(timestamp);
+    if (rowWidth < timestampWidth)
+        return unchanged;
+    return {
+        row: overlaySpan(sourceRow, rowWidth - timestampWidth, rowWidth, paintPiSubmittedPromptTimestamp(timestamp)),
+        copySuffixWidth: timestampWidth,
+    };
+}

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

@@ -0,0 +1,31 @@
+import type { TranscriptPromptAnchor, TranscriptViewportFrameInput } from "../../ui/components/transcript-viewport.js";
+import type { PiShellComponentPort } from "../../integrations/pi/components/shell-shared-facade.js";
+import type { ShellLayout, ShellLayoutPorts } from "./shell-layout.js";
+interface VisibleViewportSnapshot {
+    readonly width: number;
+    readonly height: number;
+    readonly documentRows: readonly string[];
+    readonly transientSignature: string;
+    readonly promptAnchors: readonly TranscriptPromptAnchor[];
+    readonly dockLength: number;
+    readonly inputSurface: PiShellComponentPort;
+    readonly viewportRevision: number;
+    readonly selectionRevision: number;
+    readonly pointerPosition: TranscriptViewportFrameInput["pointerPosition"];
+}
+/**
+ * Bare A1's custom viewport: a bounded transcript viewport above the dock, composed by the session
+ * viewport controller. It owns the snapshot that lets a safe keystroke repaint only the dock.
+ */
+export declare class ViewportLayout implements ShellLayout {
+    #private;
+    constructor(ports: ShellLayoutPorts);
+    invalidate(): void;
+    composed(): VisibleViewportSnapshot | undefined;
+    compositions(): {
+        readonly full: number;
+        readonly dockOnly: number;
+    };
+    render(width: number): readonly string[];
+}
+export {};

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

@@ -0,0 +1,160 @@
+import { heldNativeHyperlinkStyle } from "../../ui/components/spans.js";
+/**
+ * Bare A1's custom viewport: a bounded transcript viewport above the dock, composed by the session
+ * viewport controller. It owns the snapshot that lets a safe keystroke repaint only the dock.
+ */
+export class ViewportLayout {
+    #ports;
+    #snapshot;
+    #fullCompositions = 0;
+    #dockOnlyCompositions = 0;
+    constructor(ports) {
+        this.#ports = ports;
+    }
+    invalidate() {
+        this.#snapshot = undefined;
+    }
+    composed() {
+        return this.#snapshot;
+    }
+    compositions() {
+        return { full: this.#fullCompositions, dockOnly: this.#dockOnlyCompositions };
+    }
+    render(width) {
+        const { viewport, input, dockChrome } = this.#ports;
+        const height = Math.max(0, this.#ports.rows());
+        const dock = this.#ports.dock(width);
+        const copyAcknowledgement = dockChrome.renderCopyAcknowledgement(width);
+        // Invariant: auto/always own one stable final-column gutter. Every scrollable
+        // surface ends before it; the dock remains full-width and hidden mode returns it.
+        const documentWidth = viewport.config.scrollbarAppearance === "hidden"
+            ? width
+            : Math.max(1, width - 1);
+        const document = this.#ports.document(documentWidth);
+        const steeringRows = this.#ports.queued(documentWidth);
+        const releaseBanner = dockChrome.renderReleaseBanner(this.#ports.diagnostics(), documentWidth);
+        // Rationale: the release notice rides the bottom-aligned tail directly above Working, so it
+        // never displaces transcript content and scrolls away with the live status.
+        // Invariant: when idle the banner's last row sits on the line Working would occupy.
+        const statusRows = [...releaseBanner?.rows ?? [], ...this.#ports.liveStatus(documentWidth)];
+        const transientSignature = transientRowsSignature(steeringRows, statusRows);
+        const snapshot = this.#snapshot;
+        // Invariant: paint-only feedback may cover either viewport or dock cells, so
+        // ordinary dock-only reuse cannot safely omit its overlay composition.
+        const dockInputCandidate = input.dockInputCandidate && copyAcknowledgement === undefined;
+        // Concurrency: input may change after a keyboard receipt but before its paint.
+        // Capture only the live inputs this composition will actually represent.
+        const inputSurface = input.surface;
+        const dockRows = dock.rows;
+        const dockStartRow = height - dockRows.length + 1;
+        const copyableDockRows = this.#copyableDockRows(dock);
+        this.#placeInputFrames(dock, width, height, dockStartRow);
+        const viewportRevision = viewport.presentationRevision;
+        const selectionRevision = viewport.selectionRevision;
+        const pointerPosition = viewport.pointerPosition;
+        input.takeDockInputCandidate();
+        let frame = dockInputCandidate
+            && snapshot !== undefined
+            && snapshot.width === width
+            && snapshot.height === height
+            && snapshot.documentRows === document.rows
+            && snapshot.transientSignature === transientSignature
+            && snapshot.promptAnchors === document.promptAnchors
+            && snapshot.dockLength === dockRows.length
+            && snapshot.inputSurface === inputSurface
+            && snapshot.viewportRevision === viewportRevision
+            && snapshot.selectionRevision === selectionRevision
+            ? viewport.composeDockOnly(dockRows, width, height, copyableDockRows)
+            : null;
+        if (frame === null) {
+            frame = viewport.compose({
+                // Performance: do not copy the complete document on unchanged dock-only input.
+                // Steering and Working retain their one non-persistent viewport-tail ownership.
+                documentRows: [...document.rows, ...steeringRows, ...statusRows],
+                ...(viewport.transcriptPointerSelecting
+                    ? { paintDocumentRow: heldNativeHyperlinkStyle }
+                    : {}),
+                // Invariant: this boundary tracks persistent transcript rows for streaming and
+                // geometry; transient Steering and Working rows remain complete-frame selectable.
+                selectableDocumentRowCount: document.rows.length,
+                ...(document.liveTailStartRow === undefined ? {} : { liveTailStartRow: document.liveTailStartRow }),
+                bottomAlignedTailRowCount: steeringRows.length + statusRows.length,
+                dockRows,
+                copyableDockRows,
+                promptAnchors: document.promptAnchors,
+                width,
+                height,
+                // Invariant: the control belongs immediately above the complete dock and
+                // floats over transient viewport content rather than consuming a dock row.
+                bottomControlRow: Math.max(0, height - Math.min(height, dockRows.length) - 1),
+                ...(copyAcknowledgement === undefined || height <= 0 ? {} : {
+                    frameOverlay: {
+                        row: Math.max(1, Math.min(height, dockStartRow + dock.inputOffset - 1)),
+                        text: copyAcknowledgement,
+                    },
+                }),
+                theme: this.#ports.theme,
+            });
+            this.#fullCompositions += 1;
+        }
+        else
+            this.#dockOnlyCompositions += 1;
+        dockChrome.locateReleaseClose(frame, releaseBanner, document.rows.length + steeringRows.length + statusRows.length, statusRows.length);
+        this.#snapshot = {
+            width,
+            height,
+            documentRows: document.rows,
+            transientSignature,
+            promptAnchors: document.promptAnchors,
+            dockLength: dockRows.length,
+            inputSurface,
+            // Invariant: a callback during composition cannot bless older rows with its
+            // newer revision. Its ordinary pending render will publish the newer state.
+            viewportRevision,
+            selectionRevision: frame.descriptor.selectionRevision,
+            pointerPosition,
+        };
+        this.#ports.onFrame?.(frame);
+        return frame.rows;
+    }
+    #copyableDockRows(dock) {
+        // Rationale: rendered chip tags are lossy presentation (truncated labels), so a frame drag over
+        // a draft holding chips stays visual-only; editor-owned word/line selection still copies the
+        // expanded chip text through its semantic route.
+        const draft = this.#ports.input.usesEditor ? this.#ports.editor.getText() : "";
+        const promptCopyRows = draft.length > 0
+            && !draft.split("\n").some(line => this.#ports.promptChips.atomicRanges(line).length > 0)
+            ? Math.max(0, dock.inputRows - 2)
+            : 0;
+        return [
+            ...dock.copyableMessageRows,
+            ...Array.from({ length: promptCopyRows }, (_value, index) => ({
+                row: dock.editorOffset + index + 1,
+                prompt: index === 0 ? "first" : "continuation",
+            })),
+            ...Array.from({ length: dock.footerRows }, (_value, index) => ({
+                row: dock.rows.length - dock.footerRows + index,
+            })),
+        ];
+    }
+    // Invariant: pointer routing needs the replacement surface's frame, or the editor's rows when it is active.
+    #placeInputFrames(dock, width, height, dockStartRow) {
+        const { viewport, input } = this.#ports;
+        viewport.setInputSurfaceFrame(input.usesEditor ? undefined : {
+            component: input.surface,
+            columnStart: 1,
+            columnEnd: width,
+            rowStart: Math.max(1, dockStartRow + dock.editorOffset),
+            rowEnd: Math.min(height, dockStartRow + dock.editorOffset + dock.inputRows - 1),
+        });
+        viewport.setEditorPointerFrame(input.usesEditor
+            ? {
+                rowStart: dockStartRow + dock.editorOffset,
+                rowEnd: dockStartRow + dock.editorOffset + dock.inputRows - 1,
+            }
+            : undefined);
+    }
+}
+function transientRowsSignature(steeringRows, statusRows) {
+    return `${steeringRows.length}\u0000${steeringRows.join("\u0000")}\u0001${statusRows.length}\u0000${statusRows.join("\u0000")}`;
+}

package/dist/app/session-shell/workflow-output.d.ts

@@ -0,0 +1,33 @@
+import type { ImageAttachmentError, OwnedUiWorkflowMessage, OwnedUiWorkflowResult } from "../../contracts/owned-ui/index.js";
+import { type PiShellHotkeysPresentation } from "../../integrations/pi/components/shell-presenters-info.js";
+import type { DockChrome } from "./dock-chrome.js";
+import type { TranscriptDocument } from "./transcript-document.js";
+export interface WorkflowOutputPorts {
+    readonly customViewport: boolean;
+    readonly document: Pick<TranscriptDocument, "lastId" | "anchorOf" | "invalidate" | "appendAnchored" | "removeAnchored">;
+    readonly dock: Pick<DockChrome, "setNotice" | "dismissNotice">;
+    /** How many semantic transcript blocks precede new output; workflow output anchors after them. */
+    transcriptLength(): number;
+    outputPad(): 0 | 1;
+    hotkeysPresentation(): PiShellHotkeysPresentation;
+    readonly componentRuntime: {
+        getColumns(): number;
+        getRows(): number;
+        requestRender(): void;
+    };
+    /** Output changed what the shell draws; the root invalidates. */
+    invalidate(): void;
+}
+/**
+ * Presents workflow results: bare A1 answers in the dock notice, the pinned profile appends
+ * transcript-anchored output, and consecutive status lines at the same anchor replace each other.
+ */
+export declare class WorkflowOutput {
+    #private;
+    constructor(ports: WorkflowOutputPorts);
+    appendStatus(message: string): void;
+    appendMessage(message: OwnedUiWorkflowMessage, errorCode?: ImageAttachmentError["code"]): void;
+    appendResult(result: OwnedUiWorkflowResult, errorCode?: ImageAttachmentError["code"]): void;
+    /** Drops every anchored output and the status-replacement chain. */
+    reset(): void;
+}