@timurproko/a1 0.1.8-dev.182 → 0.1.8-dev.214

package/dist/integrations/pi/session-ui/session-shell.js

@@ -2,11 +2,13 @@ import { PRODUCT_TEXT } from "../../../product-identity.js";
 import { MOUSE_TRACKING_OFF, MOUSE_TRACKING_ON, parseMouseInput } from "../../../ui/components/index.js";
 import { PINNED_PI_HIDDEN_COMMAND_NAMES, PINNED_PI_WORKFLOW_COMMAND_NAMES, } from "../engine/index.js";
 import { createPiExtensionUiBridge, createPiQueuedInputStatus, createPiShellArmin, createPiShellAuthProviderSelector, createPiShellChangelog, createPiShellDaxnuts, createPiShellDialog, createPiShellEarendilAnnouncement, createPiShellEditor, createPiShellExtensionSelector, createPiShellFooter, createPiShellHeader, createPiShellHotkeys, createPiShellLoadedResources, createPiShellLoginDialog, createPiShellModelSelector, createPiShellOperationLoader, createPiShellReloadBox, createPiShellScopedModelsSelector, createPiShellSelector, createPiShellSessionInfo, createPiShellSessionSelector, createPiShellSettingsSelector, createPiShellStatus, createPiShellTranscriptComponent, createPiShellTreeSelector, createPiShellTrustSelector, createPiShellUserMessageSelector, onPiThemeChange, piTheme, renderPiShellPackageUpdateNotice, renderPiShellStartupDiagnostic, renderPiShellStatusText, renderPiShellTranscriptBlock, } from "../components/index.js";
-import { PiTuiRuntimeAdapter, } from "../tui-runtime/index.js";
+import { DamageAwareTerminalAdapter, PiTuiRuntimeAdapter, classifyPiTuiInput, } from "../tui-runtime/index.js";
 import { canonicalizeClipboardImage } from "./clipboard-image.js";
+import { STREAM_PRESENTATION_INTERVAL_MS, StreamPresentationCoalescer, } from "./stream-presentation-coalescer.js";
 import { preloadSystemClipboard, readSystemClipboardContent, writeSystemClipboardText, } from "./system-clipboard.js";
 import { OwnedUiSessionShellRoot, shellResourceEntries, } from "./session-shell-root.js";
 export { OwnedUiSessionShellRoot } from "./session-shell-root.js";
+/** Coordinates backend, owned presentation, and Pi TUI lifecycles for one interactive session. */
 export class OwnedUiSessionShell {
     backend;
     root;
@@ -26,6 +28,8 @@ export class OwnedUiSessionShell {
     #disposed = false;
     #pointerReporting = false;
     #customViewport;
+    #damageTerminal;
+    #streamPresentation;
     #removeViewportPreInput;
     #unsubscribeSettings;
     #unbindPiSettings;
@@ -52,11 +56,19 @@ export class OwnedUiSessionShell {
             this.#resolveStopped = resolve;
         });
         let runtime;
+        let damageTerminal;
+        let streamPresentation;
         let pendingClipboardWrite = Promise.resolve();
         this.root = new OwnedUiSessionShellRoot(this.backend.view(), options.cwd, {
             getColumns: () => runtime?.viewport().columns ?? options.terminal?.columns ?? 80,
             getRows: () => runtime?.viewport().rows ?? options.terminal?.rows ?? 24,
             requestRender: force => runtime?.requestRender(force),
+            onViewportFrame: frame => damageTerminal?.arm(frame.descriptor, {
+                overlayActive: runtime?.hasOverlay() ?? false,
+                selectionActive: this.root.hasActiveSelection(),
+                replacementSurfaceActive: !this.root.usesDefaultInputSurface(),
+            }),
+            enableDockInputReuse: options.inputPresentation?.viewportReuse !== false,
             onSubmit: text => { void this.submit(text); },
             onInterrupt: () => { void this.interrupt(); },
             onClear: () => { void this.clearOrExit(); },
@@ -91,7 +103,7 @@ export class OwnedUiSessionShell {
                     }
                 }
                 catch {
-                    // Treat an unavailable or malformed image as text-capable clipboard input.
+                    // Compatibility: treat an unavailable or malformed image as text-capable clipboard input.
                 }
                 const text = await options.clipboard.readText();
                 return text === null ? null : { kind: "text", text };
@@ -105,7 +117,7 @@ export class OwnedUiSessionShell {
         }, options.sessionLayout, {
             resolve: assetId => this.backend.resolveTranscriptImage(assetId),
         });
-        // Bare A1 owns a bounded viewport and therefore always runs on the alternate
+        // Invariant: bare A1 owns a bounded viewport and therefore always runs on the alternate
         // fullscreen surface. The pinned comparison profiles still honor Pi's mode.
         const tuiMode = this.#customViewport
             ? "fullscreen"
@@ -113,12 +125,41 @@ export class OwnedUiSessionShell {
         const runtimeOptions = {
             root: this.root,
             mode: tuiMode,
-            ...(this.#customViewport ? {} : { layoutRoot: this.root.layoutRoot() }),
+            ...(this.#customViewport ? {
+                decorateTerminal: (terminal) => {
+                    damageTerminal = new DamageAwareTerminalAdapter(terminal, {
+                        regionalScroll: process.env.TERM !== "dumb",
+                        onResize: () => streamPresentation?.noteImmediatePresentation(),
+                    });
+                    return damageTerminal;
+                },
+                ...(options.inputPresentation?.coordination === false ? {} : {
+                    inputCoordination: {
+                        classify: (data, focusedOverlay) => classifyPiTuiInput(data, focusedOverlay ?? this.root.inputCoordinationSurface()),
+                        onReceipt: () => streamPresentation?.noteImmediatePresentation(),
+                        ...(options.inputPresentation?.scheduler === undefined
+                            ? {}
+                            : { scheduler: options.inputPresentation.scheduler }),
+                    },
+                }),
+            } : { layoutRoot: this.root.layoutRoot() }),
+            ...(options.inputPresentation?.onEvent === undefined ? {} : {
+                inputDiagnostics: {
+                    onEvent: options.inputPresentation.onEvent,
+                    ...(options.inputPresentation.now === undefined ? {} : { now: options.inputPresentation.now }),
+                },
+            }),
             ...(options.terminal === undefined ? {} : { terminal: options.terminal }),
             hardwareCursor: this.backend.view().terminal.hardwareCursor,
         };
         runtime = new PiTuiRuntimeAdapter(runtimeOptions);
         this.runtime = runtime;
+        this.#damageTerminal = damageTerminal ?? null;
+        const presentationInterval = options.streamPresentation?.intervalMs ?? STREAM_PRESENTATION_INTERVAL_MS;
+        streamPresentation = options.streamPresentation?.scheduler === undefined
+            ? new StreamPresentationCoalescer(() => this.runtime.requestRender(), presentationInterval)
+            : new StreamPresentationCoalescer(() => this.runtime.requestRender(), presentationInterval, options.streamPresentation.scheduler);
+        this.#streamPresentation = streamPresentation;
         const initialPiSettings = this.backend.pinnedSettingsSnapshot();
         this.runtime.setHardwareCursor(initialPiSettings.showHardwareCursor);
         this.runtime.setClearOnShrink(initialPiSettings.clearOnShrink);
@@ -147,7 +188,9 @@ export class OwnedUiSessionShell {
         });
         this.#removeViewportPreInput = this.#customViewport
             ? this.runtime.addPreInputListener(data => {
-                // An overlay or editor-replacement screen owns its entire pointer
+                if (options.inputPresentation?.coordination === false)
+                    this.#streamPresentation.noteImmediatePresentation();
+                // Invariant: an overlay or editor-replacement screen owns its entire pointer
                 // surface. Letting the transcript pre-router inspect those reports
                 // steals settings value menus and numeric +/- controls before the
                 // settings app can receive them.
@@ -228,7 +271,7 @@ export class OwnedUiSessionShell {
                 requestRender: () => this.runtime.requestRender(),
             },
             agentDir: this.backend.agentDir,
-            setInputSurface: component => this.root.setInputSurface(component),
+            setInputSurface: component => this.root.setInputSurface(component, true, "opaque"),
             showOverlay: (component, overlayOptions) => this.runtime.showOverlay(component, overlayOptions),
             listenInput: handler => this.runtime.addInputListener(handler),
             replaceWidget: (key, component, placement) => this.root.setExtensionWidget(key, component, placement),
@@ -242,7 +285,7 @@ export class OwnedUiSessionShell {
             setEditorText: text => this.root.editor.setText(text),
             pasteToEditor: text => this.root.editor.insertText(text),
             addAutocompleteProvider: factory => this.root.editor.addAutocompleteProvider(factory),
-            setCustomEditor: component => this.root.setInputSurface(component),
+            setCustomEditor: component => this.root.setInputSurface(component, true, "opaque"),
             getFooterData: () => this.root.extensionFooterData(),
             getToolsExpanded: () => this.root.toolsExpanded,
             setToolsExpanded: expanded => this.root.setToolsExpanded(expanded),
@@ -255,7 +298,7 @@ export class OwnedUiSessionShell {
         });
         this.root.editor.setAutocompleteCommands(this.backend.workflowAutocompleteCommands());
         this.#unsubscribe = this.backend.onEvent(event => {
-            // A streamed chunk names one block, and touching only that block is what keeps the
+            // Performance: a streamed chunk names one block, and touching only that block is what keeps the
             // cost of a chunk the same in a long session as in a new one. Everything else
             // resynchronizes the view, which is cheap next to re-reading the transcript.
             if (event.type === "agent-run-started")
@@ -278,6 +321,9 @@ export class OwnedUiSessionShell {
     view() {
         return this.backend.view();
     }
+    damagePresentationDecision() {
+        return this.#damageTerminal?.lastDecision ?? null;
+    }
     start() {
         if (this.#started)
             return;
@@ -367,7 +413,7 @@ export class OwnedUiSessionShell {
             this.root.editor.setText("");
             return { outcome: "completed", diagnostic: null };
         }
-        // Match Pi: with an empty editor, two escapes inside 500 ms open the
+        // Compatibility: match Pi: with an empty editor, two escapes inside 500 ms open the
         // configured session navigator. The first escape intentionally does not
         // interrupt or mutate the prompt.
         const action = this.backend.pinnedSettingsSnapshot().doubleEscapeAction;
@@ -486,7 +532,12 @@ export class OwnedUiSessionShell {
                 onCancel?.();
             },
         });
-        const handle = this.runtime.showOverlay(component, { width: "70%", maxHeight: "80%", anchor: "center" });
+        const handle = this.runtime.showOverlay(component, {
+            width: "70%",
+            maxHeight: "80%",
+            anchor: "center",
+            inputCoordination: "owned",
+        });
         this.#dialogHandle = handle;
         return handle;
     }
@@ -686,7 +737,7 @@ export class OwnedUiSessionShell {
                     return;
                 }
                 if (callback === "onTuiModeChange") {
-                    // The custom bare-A1 surface is permanently fullscreen; this callback
+                    // Invariant: the custom bare-A1 surface is permanently fullscreen; this callback
                     // remains available only to pinned comparison profiles.
                     if (this.#customViewport)
                         return;
@@ -907,12 +958,7 @@ export class OwnedUiSessionShell {
             this.root.appendDaxnuts();
         }
     }
-    /**
-     * Turns terminal pointer reporting on for a screen that reads the pointer, and off for
-     * every path that ends it. While it is on the terminal hands A1 the wheel and the
-     * button instead of scrolling and selecting itself, so leaving it on outlives the
-     * screen that wanted it and takes the terminal's own scrolling and selection with it.
-     */
+    // Invariant: pointer reporting is disabled on every path that ends the owning screen.
     #setPointerReporting(enabled, forceOff = false) {
         const effective = forceOff ? false : this.#customViewport || enabled;
         if (this.#pointerReporting === effective)
@@ -929,13 +975,16 @@ export class OwnedUiSessionShell {
         this.root.clearViewportPointerState();
         this.#setPointerReporting(false, true);
         this.#removeViewportPreInput();
+        this.#streamPresentation.dispose();
         this.#unsubscribeSettings();
         const exitMode = this.backend.disposed
             ? this.#fullscreenExitOutput
             : this.backend.pinnedSettingsSnapshot().fullscreenExitOutput;
         const exitTranscript = this.root.exitTranscript(this.runtime.viewport().columns);
-        const sessionFile = this.backend.currentSessionFile();
-        const resumeHint = sessionFile === null ? "" : `Resume: ${formatSessionResumeCommand(sessionFile)}`;
+        const resume = this.backend.currentSessionResumeMetadata();
+        const resumeHint = resume === null
+            ? ""
+            : `${dim("To resume this session:")} ${formatSessionResumeCommand(resume)}`;
         const fullscreenExitText = this.runtime.mode !== "fullscreen"
             ? ""
             : exitMode === "resume-hint"
@@ -952,13 +1001,18 @@ export class OwnedUiSessionShell {
         if (fullscreenExitText.length > 0)
             this.runtime.writeAfterStop(`${fullscreenExitText}\n`);
     }
-    /**
-     * Applies one transcript block without re-reading the session. The listeners still hear
-     * the view they would have heard, so nothing downstream can tell the difference.
-     */
+    // Invariant: incremental block updates notify listeners with the same complete view contract.
     #syncBlock(block) {
         this.root.applyTranscriptBlock(block);
-        this.runtime.requestRender();
+        if (this.#customViewport && block.status === "live" && isCoalescedStreamBlock(block.kind)) {
+            this.#streamPresentation.request();
+        }
+        else if (this.#streamPresentation.pending) {
+            this.#streamPresentation.flush();
+        }
+        else {
+            this.#streamPresentation.presentImmediate();
+        }
         const view = this.view();
         for (const listener of this.#listeners)
             listener(view);
@@ -970,12 +1024,13 @@ export class OwnedUiSessionShell {
         this.runtime.setTerminalProgress(this.#terminalProgressEnabled && view.lifecycle === "busy");
     }
     #syncView() {
+        this.#streamPresentation.noteImmediatePresentation();
         const view = this.view();
         if (this.backend.sessionGeneration !== this.#sessionGeneration) {
             this.#sessionGeneration = this.backend.sessionGeneration;
             this.#activeLoginDialog = undefined;
             this.#extensionBridge.reset();
-            // A replaced session takes its transient viewport and owned-route state with it.
+            // Invariant: a replaced session takes its transient viewport and owned-route state with it.
             this.root.resetViewport();
             this.#dialogHandle?.hide();
             this.#dialogHandle = undefined;
@@ -1001,10 +1056,10 @@ export class OwnedUiSessionShell {
             return { outcome: "failed", diagnostic: "runtime is not active" };
         this.#dialogHandle?.hide();
         this.#dialogSource = "route";
-        // Any-event reporting: hover and drag are what the screen is driven by, and
+        // Protocol: any-event reporting: hover and drag are what the screen is driven by, and
         // it also stops the terminal treating a drag as a text selection.
         this.#setPointerReporting(true);
-        // The interrupt chord is global, so it is watched on raw input rather than
+        // Protocol: the interrupt chord is global, so it is watched on raw input rather than
         // through the overlay: the pinned shell handles that key before an overlay
         // ever sees it, which is why an owned screen must not rely on being asked.
         let armedAt = 0;
@@ -1020,7 +1075,7 @@ export class OwnedUiSessionShell {
             }
             armedAt = now;
             this.runtime.requestRender();
-            // The presented screen owns the chord, so the pinned shell never sees a
+            // Invariant: the presented screen owns the chord, so the pinned shell never sees a
             // stray interrupt while it is up.
             return { consume: true };
         });
@@ -1034,7 +1089,7 @@ export class OwnedUiSessionShell {
             this.#dialogId = undefined;
             this.#dialogSource = undefined;
         };
-        // Fullscreen Pi owns a fallback text-selection layer before focused overlay
+        // Compatibility: fullscreen Pi owns a fallback text-selection layer before focused overlay
         // components see pointer input. Route every mouse report to the owned screen
         // at the pre-input boundary so dropdowns, value hover, and numeric +/- work,
         // and consume even unhandled reports so settings content is never selected.
@@ -1072,7 +1127,12 @@ export class OwnedUiSessionShell {
             closeSurface();
             void this.shutdown();
         });
-        this.#dialogHandle = this.runtime.showOverlay(component, { width: "100%", maxHeight: "100%", anchor: "top-left" });
+        this.#dialogHandle = this.runtime.showOverlay(component, {
+            width: "100%",
+            maxHeight: "100%",
+            anchor: "top-left",
+            inputCoordination: "owned",
+        });
         this.#dialogId = surface.id;
         return { outcome: "completed", diagnostic: null };
     }
@@ -1080,7 +1140,7 @@ export class OwnedUiSessionShell {
         if (!this.runtime.active)
             return;
         if (dialog === null) {
-            // Locally owned routes (notably /settings) are independent of backend
+            // Invariant: locally owned routes (notably /settings) are independent of backend
             // lifecycle/status events and remain open while an agent is working.
             if (this.#dialogSource !== "backend")
                 return;
@@ -1108,7 +1168,12 @@ export class OwnedUiSessionShell {
                 this.#dialogSource = undefined;
             },
         });
-        this.#dialogHandle = this.runtime.showOverlay(component, { width: "70%", maxHeight: "80%", anchor: "center" });
+        this.#dialogHandle = this.runtime.showOverlay(component, {
+            width: "70%",
+            maxHeight: "80%",
+            anchor: "center",
+            inputCoordination: "owned",
+        });
         this.#dialogId = dialog.id;
     }
     async #slashCommand(text) {
@@ -1120,7 +1185,7 @@ export class OwnedUiSessionShell {
             return this.#openOwnedRoute(name);
         if (isWorkflowRoute(name))
             return this.runWorkflow({ command: name, argument });
-        // Unknown slash input, prompt templates, skills, and extension commands remain Pi prompt input.
+        // Compatibility: unknown slash input, prompt templates, skills, and extension commands remain Pi prompt input.
         this.root.editor.addToHistory(text);
         this.root.resumeViewportFollowing();
         return this.#execute({
@@ -1259,14 +1324,24 @@ export class OwnedUiSessionShell {
         return `pi-shell-${prefix}-${this.#sequence}`;
     }
 }
-export function formatSessionResumeCommand(sessionFile) {
-    return `${PRODUCT_TEXT.commandName} --session ${quoteCommandArgument(sessionFile)}`;
+function isCoalescedStreamBlock(kind) {
+    return kind === "assistant" || kind === "thinking" || kind === "tool-call" || kind === "tool-result";
+}
+export function formatSessionResumeCommand(metadata) {
+    const args = [PRODUCT_TEXT.commandName];
+    if (!metadata.usesDefaultSessionDir)
+        args.push("--session-dir", quoteCommandArgument(metadata.sessionDir));
+    args.push("--session", metadata.sessionId);
+    return args.join(" ");
 }
 export function quoteCommandArgument(value) {
-    if (process.platform === "win32")
-        return `"${value.replaceAll("\"", "\"\"")}"`;
+    if (value.length > 0 && !/[^a-zA-Z0-9_\-./~:@]/.test(value))
+        return value;
     return `'${value.replaceAll("'", `'\\''`)}'`;
 }
+function dim(value) {
+    return `\u001b[2m${value}\u001b[22m`;
+}
 function modelReference(model) {
     if (typeof model !== "object" || model === null)
         return "";

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

@@ -24,11 +24,16 @@ export declare class SessionViewportController {
     get config(): OwnedUiViewportSettings;
     get editorPointerSelecting(): boolean;
     get transcriptPointerSelecting(): boolean;
+    get hasSelection(): boolean;
+    get selectionRevision(): number;
+    get presentationRevision(): number;
+    get frame(): TranscriptViewportFrame | null;
     setEditorPointerFrame(frame: {
         readonly rowStart: number;
         readonly rowEnd: number;
     } | undefined): void;
     compose(input: TranscriptViewportFrameInput): TranscriptViewportFrame;
+    composeDockOnly(dockRows: readonly string[], width: number, height: number): TranscriptViewportFrame | null;
     /** Returns true when document wrapping may have changed. */
     setConfig(config: OwnedUiViewportSettings): boolean;
     resumeFollowing(): void;

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

@@ -16,21 +16,26 @@ export class SessionViewportController {
         scrollbarSpeed: "normal",
     };
     #dragGrabOffset = null;
-    /** A left-button sequence begun in status/editor/footer chrome is swallowed. */
+    // Invariant: a left-button sequence begun in dock chrome remains owned by the dock.
     #dockPointerSuppressed = false;
-    /** True only while the editor owns a held left mouse button. */
+    // Invariant: editor selection remains true only while its left button is held.
     #editorPointerSelecting = false;
-    /** Last composed terminal rows occupied by the default prompt editor. */
+    // Invariant: pointer routing uses the most recently composed editor rows.
     #editorPointerFrame;
     #selectionAutoScrollTimer;
     #selectionAutoScrollPointer;
     #pointerPosition;
     #hoveredHyperlinkKey;
+    #lastRequestedSelectionRevision = -1;
+    #presentationRevision = 0;
     #activityTimer;
     constructor(options) {
         this.#enabled = options.enabled;
         this.#editor = options.editor;
-        this.#requestRender = options.requestRender;
+        this.#requestRender = force => {
+            this.#presentationRevision += 1;
+            options.requestRender(force);
+        };
         this.#hasEditorLinks = options.hasEditorLinks ?? (() => false);
     }
     get config() {
@@ -42,16 +47,36 @@ export class SessionViewportController {
     get transcriptPointerSelecting() {
         return this.#viewport.selectionActive;
     }
+    get hasSelection() {
+        return this.#viewport.hasSelection;
+    }
+    get selectionRevision() {
+        return this.#viewport.selectionRevision;
+    }
+    get presentationRevision() {
+        return this.#presentationRevision;
+    }
+    get frame() {
+        return this.#viewport.frame;
+    }
     setEditorPointerFrame(frame) {
         this.#editorPointerFrame = frame;
     }
     compose(input) {
         this.#viewport.setConfig(this.#config);
+        const selectionRevision = this.#viewport.selectionRevision;
         const frame = this.#viewport.compose(input);
+        // Concurrency: if selection changed during composition, this frame truthfully carries
+        // the older revision and exactly one ordinary follow-up render publishes the latest.
+        if (this.#viewport.selectionRevision !== selectionRevision
+            && this.#lastRequestedSelectionRevision < this.#viewport.selectionRevision) {
+            this.#lastRequestedSelectionRevision = this.#viewport.selectionRevision;
+            this.#requestRender();
+        }
         if (this.#pointerPosition !== undefined && !this.#viewport.selectionActive && !this.#editorPointerSelecting) {
             const next = this.#hyperlinkKeyAt(frame, this.#pointerPosition.column, this.#pointerPosition.row);
             if (this.#hoveredHyperlinkKey !== undefined && next !== this.#hoveredHyperlinkKey) {
-                // Windows Terminal can leave its solid native-hover underline behind
+                // Platform: Windows Terminal can leave its solid native-hover underline behind
                 // when a following viewport moves the link away from a stationary pointer.
                 this.#requestRender(true);
             }
@@ -59,6 +84,9 @@ export class SessionViewportController {
         }
         return frame;
     }
+    composeDockOnly(dockRows, width, height) {
+        return this.#viewport.composeDockOnly(dockRows, width, height);
+    }
     /** Returns true when document wrapping may have changed. */
     setConfig(config) {
         const appearanceChanged = config.scrollbarAppearance !== this.#config.scrollbarAppearance;
@@ -84,6 +112,7 @@ export class SessionViewportController {
         this.#requestRender();
     }
     reset() {
+        this.#presentationRevision += 1;
         this.#clearActivityTimer();
         this.#stopSelectionAutoScroll();
         this.#editorPointerSelecting = false;
@@ -93,6 +122,7 @@ export class SessionViewportController {
         this.#viewport.reset();
     }
     clearPointerState() {
+        this.#presentationRevision += 1;
         this.#clearActivityTimer();
         this.#dragGrabOffset = null;
         this.#dockPointerSuppressed = false;
@@ -107,15 +137,15 @@ export class SessionViewportController {
     handlePreInput(data, allowWheel = true, now = Date.now()) {
         if (!this.#enabled)
             return { data, consumed: false };
-        // Pi components share one keybinding manager. Restore bare A1's aliases
+        // Compatibility: Pi components share one keybinding manager. Restore bare A1's aliases
         // before the focused vanilla editor handles this input.
         this.#editor.activateKeybindings();
-        // Handle the physical paste chord at the pre-input boundary. Windows
+        // Platform: handle the physical paste chord at the pre-input boundary. Windows
         // terminals vary between forwarding Ctrl+V and terminal-owned bracketed paste.
         if (this.#editor.matchesTerminalKey(data, "ctrl+v") && this.#editor.pasteClipboard()) {
             return { data: "", consumed: true };
         }
-        // URL chip deletion must overwrite terminal link cells in the same frame.
+        // Platform: URL chip deletion must overwrite terminal link cells in the same frame.
         if (EDITOR_LINK_DELETION_INPUTS.has(data) && this.#hasEditorLinks())
             this.#requestRender(true);
         if (this.#viewport.frame === null)
@@ -180,7 +210,7 @@ export class SessionViewportController {
                 if (!this.#viewport.selectionActive && !this.#editorPointerSelecting) {
                     const nextHyperlink = this.#hyperlinkKeyAt(frame, event.column, event.row);
                     if (this.#hoveredHyperlinkKey !== undefined && nextHyperlink !== this.#hoveredHyperlinkKey) {
-                        // A forced redraw overwrites Windows Terminal's cached solid hover
+                        // Platform: a forced redraw overwrites Windows Terminal's cached solid hover
                         // underline exactly once when the pointer leaves or changes links.
                         forceRepaint = true;
                     }
@@ -308,7 +338,7 @@ export class SessionViewportController {
                 }
                 if (this.#viewport.releaseSelection()) {
                     this.#stopSelectionAutoScroll();
-                    // Restore OSC 8 links only after the held-button selection paint has
+                    // Platform: restore OSC 8 links only after the held-button selection paint has
                     // ended, then overwrite any terminal-cached hover cells immediately.
                     forceRepaint = true;
                     repaint = true;
@@ -329,8 +359,10 @@ export class SessionViewportController {
         });
         if (activity)
             this.#scheduleActivityExpiry();
-        if (repaint)
+        if (repaint) {
+            this.#lastRequestedSelectionRevision = this.#viewport.selectionRevision;
             this.#requestRender(forceRepaint);
+        }
         return routed;
     }
     #hyperlinkKeyAt(frame, column, row) {
@@ -370,6 +402,7 @@ export class SessionViewportController {
             this.#stopSelectionAutoScroll();
             return;
         }
+        this.#lastRequestedSelectionRevision = this.#viewport.selectionRevision;
         this.#requestRender();
         this.#scheduleActivityExpiry();
         this.#selectionAutoScrollTimer = setTimeout(() => this.#selectionAutoScrollTick(), SELECTION_AUTO_SCROLL_INTERVAL_MS);

package/dist/integrations/pi/session-ui/stream-presentation-coalescer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 33 ms (30.3 fps): baseline chunks arrive every 5 ms, while this cadence
+ * retains immediate first paint/input and explicit final-state flushing.
+ */
+export declare const STREAM_PRESENTATION_INTERVAL_MS = 33;
+export interface StreamPresentationScheduler {
+    now(): number;
+    setTimeout(callback: () => void, delayMs: number): ReturnType<typeof setTimeout>;
+    clearTimeout(timer: ReturnType<typeof setTimeout>): void;
+}
+/** Bounds terminal presentation requests while semantic root state remains current. */
+export declare class StreamPresentationCoalescer {
+    #private;
+    readonly present: () => void;
+    readonly intervalMs: number;
+    readonly scheduler: StreamPresentationScheduler;
+    constructor(present: () => void, intervalMs?: number, scheduler?: StreamPresentationScheduler);
+    get pending(): boolean;
+    request(): void;
+    /** Cancels a superseded stream frame; the immediate input/overlay/resize path renders current state. */
+    preempt(): void;
+    /** Records an immediate input/status/overlay frame and cancels an obsolete stream timer. */
+    noteImmediatePresentation(): void;
+    /** Presents current semantic state immediately regardless of pending stream work. */
+    presentImmediate(): void;
+    /** Presents the newest semantic state immediately only when a stream frame is pending. */
+    flush(): void;
+    dispose(): void;
+}

package/dist/integrations/pi/session-ui/stream-presentation-coalescer.js

@@ -0,0 +1,79 @@
+/**
+ * 33 ms (30.3 fps): baseline chunks arrive every 5 ms, while this cadence
+ * retains immediate first paint/input and explicit final-state flushing.
+ */
+export const STREAM_PRESENTATION_INTERVAL_MS = 33;
+const SYSTEM_SCHEDULER = {
+    now: Date.now,
+    setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+    clearTimeout: timer => clearTimeout(timer),
+};
+/** Bounds terminal presentation requests while semantic root state remains current. */
+export class StreamPresentationCoalescer {
+    present;
+    intervalMs;
+    scheduler;
+    #timer;
+    #lastPresentationAt = Number.NEGATIVE_INFINITY;
+    #disposed = false;
+    constructor(present, intervalMs = STREAM_PRESENTATION_INTERVAL_MS, scheduler = SYSTEM_SCHEDULER) {
+        this.present = present;
+        this.intervalMs = intervalMs;
+        this.scheduler = scheduler;
+        if (!Number.isSafeInteger(intervalMs) || intervalMs < 1)
+            throw new RangeError("stream presentation interval must be positive");
+    }
+    get pending() { return this.#timer !== undefined; }
+    request() {
+        if (this.#disposed || this.#timer !== undefined)
+            return;
+        const elapsed = this.scheduler.now() - this.#lastPresentationAt;
+        if (elapsed >= this.intervalMs) {
+            this.#presentNow();
+            return;
+        }
+        this.#timer = this.scheduler.setTimeout(() => {
+            this.#timer = undefined;
+            this.#presentNow();
+        }, Math.max(0, this.intervalMs - elapsed));
+    }
+    /** Cancels a superseded stream frame; the immediate input/overlay/resize path renders current state. */
+    preempt() {
+        if (this.#timer === undefined)
+            return;
+        this.scheduler.clearTimeout(this.#timer);
+        this.#timer = undefined;
+    }
+    /** Records an immediate input/status/overlay frame and cancels an obsolete stream timer. */
+    noteImmediatePresentation() {
+        if (this.#disposed)
+            return;
+        this.preempt();
+        this.#lastPresentationAt = this.scheduler.now();
+    }
+    /** Presents current semantic state immediately regardless of pending stream work. */
+    presentImmediate() {
+        if (this.#disposed)
+            return;
+        this.noteImmediatePresentation();
+        this.present();
+    }
+    /** Presents the newest semantic state immediately only when a stream frame is pending. */
+    flush() {
+        if (this.#disposed || this.#timer === undefined)
+            return;
+        this.scheduler.clearTimeout(this.#timer);
+        this.#timer = undefined;
+        this.#presentNow();
+    }
+    dispose() {
+        this.preempt();
+        this.#disposed = true;
+    }
+    #presentNow() {
+        if (this.#disposed)
+            return;
+        this.#lastPresentationAt = this.scheduler.now();
+        this.present();
+    }
+}