@timurproko/a1 0.1.8-dev.447 → 0.1.8-dev.459

package/dist/integrations/pi/session-ui/quit-outro-effects.js

@@ -0,0 +1,242 @@
+/**
+ * Deterministic quit-outro effect plans, ported from the v2 sketch.
+ *
+ * Each effect turns the captured frame's per-row visible widths and a seed into
+ * two sorted schedules over unit playback progress: sparkles paint a glyph at a
+ * cell from `start`, and clears blank a cell at `end`. The player consumes both
+ * in order, so a fixed seed yields a byte-stable animation.
+ */
+export const QUIT_OUTRO_EFFECTS = Object.freeze(["fall", "dissolve", "starburst", "waves"]);
+export function isQuitOutroEffect(value) {
+    return typeof value === "string" && QUIT_OUTRO_EFFECTS.includes(value);
+}
+const WHITE = "\x1b[38;2;238;238;238m";
+const DUST_GLYPHS = [".", "·", "'", ":", "+", "°"];
+const FALL_GLYPHS = [".", ".", "·", "'", ":", "°"];
+const GRAVITY = 85;
+function mulberry32(seed) {
+    let value = seed >>> 0;
+    return () => {
+        value = (value + 0x6d2b79f5) | 0;
+        let next = Math.imul(value ^ (value >>> 15), 1 | value);
+        next = (next + Math.imul(next ^ (next >>> 7), 61 | next)) ^ next;
+        return ((next ^ (next >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+function pick(random, values) {
+    return values[Math.floor(random() * values.length)];
+}
+function rowWidth(rowWidths, row) {
+    return Math.max(0, Math.floor(rowWidths[row] ?? 0));
+}
+function finish(sparkles, clears) {
+    sparkles.sort((a, b) => a.start - b.start);
+    clears.sort((a, b) => a.end - b.end);
+    return { sparkles, clears };
+}
+/** Calm white ASCII dust dissolve. */
+function dissolvePlan(rowWidths, seed) {
+    const random = mulberry32(seed);
+    const height = Math.max(1, rowWidths.length);
+    const width = Math.max(1, ...rowWidths);
+    const sparkles = [];
+    const clears = [];
+    for (let row = 0; row < rowWidths.length; row++) {
+        for (let col = 0; col < rowWidth(rowWidths, row); col++) {
+            const sweep = (row / height) * 0.14 + (col / width) * 0.08;
+            const start = Math.min(0.76, sweep + random() * 0.54);
+            const cell = {
+                row, col, start,
+                end: Math.min(0.96, start + 0.1 + random() * 0.1),
+                glyph: pick(random, DUST_GLYPHS),
+                color: WHITE,
+            };
+            clears.push(cell);
+            if (random() < 0.34)
+                sparkles.push(cell);
+        }
+    }
+    return finish(sparkles, clears);
+}
+/** Soft white harmonic ripple dissolve. */
+function starburstPlan(rowWidths, seed) {
+    const random = mulberry32(seed);
+    const height = Math.max(1, rowWidths.length);
+    const width = Math.max(1, ...rowWidths);
+    const center = (width - 1) / 2;
+    const sparkles = [];
+    const clears = [];
+    for (let row = 0; row < rowWidths.length; row++) {
+        for (let col = 0; col < rowWidth(rowWidths, row); col++) {
+            const distance = Math.abs(col - center) / Math.max(1, width / 2);
+            const ripple = (Math.sin(distance * Math.PI * 3 + (row / height) * Math.PI) + 1) * 0.035;
+            const sweep = distance * 0.2 + (row / height) * 0.1 + ripple;
+            const start = Math.min(0.79, sweep + random() * 0.34);
+            const cell = {
+                row, col, start,
+                end: Math.min(0.97, start + 0.12 + random() * 0.1),
+                glyph: pick(random, DUST_GLYPHS),
+                color: WHITE,
+            };
+            clears.push(cell);
+            if (random() < 0.38)
+                sparkles.push(cell);
+        }
+    }
+    return finish(sparkles, clears);
+}
+/** White dotted fragments accelerating downward and collecting in a floor pile. */
+function fallPlan(rowWidths, seed) {
+    const random = mulberry32(seed);
+    const height = Math.max(1, rowWidths.length);
+    const width = Math.max(1, ...rowWidths);
+    const floor = height - 1;
+    const area = Math.max(1, width * height);
+    const fragmentChance = clamp(150 / area, 0.1, 0.24);
+    const particles = [];
+    const sparkles = [];
+    const clears = [];
+    let fallbackParticle;
+    for (let row = 0; row < rowWidths.length; row++) {
+        for (let col = 0; col < rowWidth(rowWidths, row); col++) {
+            const release = 0.025 + random() * 0.13 + (1 - row / height) * 0.035;
+            const glyph = pick(random, FALL_GLYPHS);
+            clears.push({ row, col, start: release, end: release + 0.04, glyph, color: WHITE });
+            if (row >= floor)
+                continue;
+            const particle = { row, col, release, glyph, velocityCol: (random() - 0.5) * 9 };
+            fallbackParticle ??= particle;
+            if (random() < fragmentChance)
+                particles.push(particle);
+        }
+    }
+    if (particles.length === 0 && fallbackParticle)
+        particles.push(fallbackParticle);
+    const arrival = (particle) => particle.release + Math.sqrt((2 * (floor - particle.row)) / GRAVITY);
+    particles.sort((a, b) => arrival(a) - arrival(b));
+    const pileHeights = Array(width).fill(0);
+    for (const particle of particles) {
+        const floorFallTime = Math.max(0.05, Math.sqrt((2 * (floor - particle.row)) / GRAVITY));
+        const predictedCol = clamp(Math.round(particle.col + particle.velocityCol * floorFallTime), 0, width - 1);
+        let landingCol = predictedCol;
+        for (let radius = 1; radius <= 3; radius++) {
+            for (const candidate of [predictedCol - radius, predictedCol + radius]) {
+                if (candidate >= 0 && candidate < width && pileHeights[candidate] < pileHeights[landingCol])
+                    landingCol = candidate;
+            }
+        }
+        const stackHeight = pileHeights[landingCol]++;
+        const restingRow = clamp(floor - stackHeight, particle.row + 1, floor);
+        const fallDistance = Math.max(1, restingRow - particle.row);
+        const fallTime = Math.sqrt((2 * fallDistance) / GRAVITY);
+        const velocityCol = (landingCol - particle.col) / fallTime;
+        const steps = Math.max(4, Math.min(14, Math.ceil(fallTime / 0.045)));
+        const interval = fallTime / steps;
+        for (let step = 1; step < steps; step++) {
+            const elapsed = step * interval;
+            const progress = step / steps;
+            const row = particle.row + 0.5 * GRAVITY * elapsed * elapsed;
+            const col = particle.col + velocityCol * elapsed + Math.sin(progress * Math.PI) * 0.3;
+            const start = clamp(particle.release + elapsed, 0, 0.93);
+            const cell = {
+                row: clamp(Math.round(row), 0, floor),
+                col: clamp(Math.round(col), 0, width - 1),
+                start,
+                end: Math.min(0.96, start + Math.max(0.025, interval * 0.72)),
+                glyph: particle.glyph,
+                color: WHITE,
+            };
+            sparkles.push(cell);
+            clears.push(cell);
+        }
+        const settledAt = clamp(particle.release + fallTime, 0, 0.93);
+        const settled = { row: restingRow, col: landingCol, start: settledAt, end: 0.97, glyph: particle.glyph, color: WHITE };
+        sparkles.push(settled);
+        clears.push(settled);
+    }
+    return finish(sparkles, clears);
+}
+/** Soft white dotted radio pulses expanding from a gently moving center. */
+function wavesPlan(rowWidths, seed) {
+    const random = mulberry32(seed);
+    const height = Math.max(1, rowWidths.length);
+    const width = Math.max(1, ...rowWidths);
+    const baseCenterCol = (width - 1) / 2;
+    const baseCenterRow = (height - 1) / 2;
+    const sparkles = [];
+    const clears = [];
+    const addPulseCell = (row, col, start, lifetime, glyph) => {
+        const safeStart = clamp(start, 0, 0.94);
+        const cell = {
+            row: clamp(Math.round(row), 0, height - 1),
+            col: clamp(Math.round(col), 0, width - 1),
+            start: safeStart,
+            end: clamp(safeStart + lifetime, safeStart + 0.02, 0.98),
+            glyph,
+            color: WHITE,
+        };
+        sparkles.push(cell);
+        clears.push(cell);
+    };
+    // Rationale: clear the frame in the same outward direction as the expanding signal.
+    for (let row = 0; row < rowWidths.length; row++) {
+        for (let col = 0; col < rowWidth(rowWidths, row); col++) {
+            const x = (col - baseCenterCol) / Math.max(1, width * 0.5);
+            const y = (row - baseCenterRow) / Math.max(1, height * 0.5);
+            const distance = Math.min(1.25, Math.sqrt(x * x + y * y));
+            const start = 0.04 + random() * 0.1;
+            const cell = {
+                row, col, start,
+                end: Math.min(0.95, 0.18 + distance * 0.54 + random() * 0.12),
+                glyph: pick(random, DUST_GLYPHS),
+                color: WHITE,
+            };
+            clears.push(cell);
+            if (random() < 0.055)
+                sparkles.push(cell);
+        }
+    }
+    const pulseCount = 4;
+    const expansionSteps = 9;
+    for (let pulse = 0; pulse < pulseCount; pulse++) {
+        const pulseStart = 0.025 + pulse * 0.135;
+        const phase = pulse * 1.47 + random() * 0.45;
+        for (let step = 0; step <= expansionSteps; step++) {
+            const progress = step / expansionSteps;
+            const centerCol = baseCenterCol + Math.sin(phase + progress * Math.PI) * width * 0.035;
+            const centerRow = baseCenterRow + Math.cos(phase + progress * Math.PI * 0.8) * height * 0.065;
+            const radiusCol = progress * width * 0.56;
+            const radiusRow = progress * height * 0.56;
+            const samples = Math.max(10, Math.min(58, Math.round(12 + radiusCol * 0.48)));
+            const time = pulseStart + progress * 0.28;
+            if (step === 0) {
+                addPulseCell(centerRow, centerCol, time, 0.1, pulse % 2 === 0 ? "+" : "°");
+                continue;
+            }
+            for (let sample = 0; sample < samples; sample++) {
+                if (random() < 0.08 + progress * 0.06)
+                    continue;
+                const angle = (sample / samples) * Math.PI * 2 + Math.sin(phase) * 0.035;
+                const shimmer = (random() - 0.5) * (0.25 + progress * 0.55);
+                const row = centerRow + Math.sin(angle) * radiusRow + shimmer * 0.4;
+                const col = centerCol + Math.cos(angle) * radiusCol + shimmer;
+                const glyph = progress < 0.28 ? "°" : progress < 0.62 ? "·" : random() < 0.72 ? "." : "'";
+                addPulseCell(row, col, time + random() * 0.018, 0.065 + (1 - progress) * 0.055, glyph);
+            }
+        }
+    }
+    return finish(sparkles, clears);
+}
+const PLANS = Object.freeze({
+    fall: fallPlan,
+    dissolve: dissolvePlan,
+    starburst: starburstPlan,
+    waves: wavesPlan,
+});
+/** Builds the selected effect's deterministic plan for the captured row widths. */
+export function createQuitOutroPlan(effect, rowWidths, seed) {
+    return PLANS[effect](rowWidths, seed);
+}

package/dist/integrations/pi/session-ui/quit-outro.d.ts

@@ -0,0 +1,38 @@
+import { type QuitOutroEffect } from "./quit-outro-effects.js";
+export interface QuitOutroFrame {
+    /** Row content as presented, truncated to `columns`; index 0 is the top row. */
+    readonly lines: readonly string[];
+    readonly columns: number;
+    readonly rows: number;
+    /** Visible width of each line, at most `columns`. */
+    readonly rowWidths: readonly number[];
+}
+export interface QuitOutroPlayback {
+    write(data: string): void;
+    /** Monotonic clock seam; defaults to `Date.now`. */
+    now?(): number;
+    /** Delay seam; defaults to a timer. */
+    sleep?(ms: number): Promise<void>;
+    /** Plan seed; defaults to a time- and geometry-derived value. */
+    readonly seed?: number;
+}
+export declare const QUIT_OUTRO_MIN_MS = 300;
+export declare const QUIT_OUTRO_MAX_MS = 2000;
+/** Wall-clock allowance beyond the clamped duration before playback abandons remaining ticks. */
+export declare const QUIT_OUTRO_GUARD_MS = 500;
+/** Tick ceiling for a clock that stops advancing: the longest playback plus its guard at 30 fps. */
+export declare const QUIT_OUTRO_MAX_TICKS: number;
+export declare function clampQuitOutroDuration(durationMs: number): number;
+/**
+ * Captures the presented rows into an outro frame. Returns null when nothing is
+ * visible, so a blank screen never animates.
+ */
+export declare function captureQuitOutroFrame(presented: readonly string[], columns: number, rows: number): QuitOutroFrame | null;
+/** The clear-and-repaint block that seeds the animation surface with the captured frame. */
+export declare function createQuitOutroSurfaceFrame(frame: QuitOutroFrame): string;
+/**
+ * Plays the effect over the frame. Resolves true when the plan was played to
+ * completion or abandoned at its guard, false when there was nothing to play.
+ * Write failures propagate so the caller can decide to continue restoration.
+ */
+export declare function playQuitOutro(frame: QuitOutroFrame, effect: QuitOutroEffect, durationMs: number, playback: QuitOutroPlayback): Promise<boolean>;

package/dist/integrations/pi/session-ui/quit-outro.js

@@ -0,0 +1,98 @@
+/**
+ * Bare A1's quit outro: the last presented fullscreen frame is captured, the
+ * selected effect animates over it on the alternate screen, and only then does
+ * the shell leave that screen. Every tick is one synchronized-output block so a
+ * terminal never shows a half-painted step, and playback is bounded so a slow
+ * terminal cannot delay restoration past the configured clamp.
+ */
+import { displayWidth, truncateToWidth } from "../../../ui/components/index.js";
+import { createQuitOutroPlan } from "./quit-outro-effects.js";
+export const QUIT_OUTRO_MIN_MS = 300;
+export const QUIT_OUTRO_MAX_MS = 2000;
+/** Wall-clock allowance beyond the clamped duration before playback abandons remaining ticks. */
+export const QUIT_OUTRO_GUARD_MS = 500;
+const FRAME_MS = 1000 / 30;
+/** Tick ceiling for a clock that stops advancing: the longest playback plus its guard at 30 fps. */
+export const QUIT_OUTRO_MAX_TICKS = Math.ceil((QUIT_OUTRO_MAX_MS + QUIT_OUTRO_GUARD_MS) / FRAME_MS) + 1;
+const SYNC_BEGIN = "\x1b[?2026h";
+const SYNC_END = "\x1b[?2026l";
+const RESET = "\x1b[0m";
+const CLEAR_SCREEN = "\x1b[2J";
+const HOME = "\x1b[H";
+const HIDE_CURSOR = "\x1b[?25l";
+export function clampQuitOutroDuration(durationMs) {
+    if (!Number.isFinite(durationMs))
+        return QUIT_OUTRO_MIN_MS;
+    return Math.max(QUIT_OUTRO_MIN_MS, Math.min(QUIT_OUTRO_MAX_MS, Math.floor(durationMs)));
+}
+function cursorAt(row, col) {
+    return `\x1b[${row + 1};${col + 1}H`;
+}
+/**
+ * Captures the presented rows into an outro frame. Returns null when nothing is
+ * visible, so a blank screen never animates.
+ */
+export function captureQuitOutroFrame(presented, columns, rows) {
+    const width = Math.max(1, Math.floor(columns));
+    const height = Math.max(1, Math.floor(rows));
+    const lines = presented.slice(0, height).map(line => truncateToWidth(line, width));
+    while (lines.length < height)
+        lines.push("");
+    const rowWidths = lines.map(line => Math.min(width, displayWidth(line)));
+    if (rowWidths.every(w => w === 0))
+        return null;
+    return { lines, columns: width, rows: height, rowWidths };
+}
+/** The clear-and-repaint block that seeds the animation surface with the captured frame. */
+export function createQuitOutroSurfaceFrame(frame) {
+    let output = `${SYNC_BEGIN}${HIDE_CURSOR}${CLEAR_SCREEN}${HOME}${RESET}`;
+    for (let row = 0; row < frame.rows; row++) {
+        const line = frame.lines[row] ?? "";
+        if (frame.rowWidths[row] > 0)
+            output += `${cursorAt(row, 0)}${line}${RESET}`;
+    }
+    return `${output}${SYNC_END}`;
+}
+/**
+ * Plays the effect over the frame. Resolves true when the plan was played to
+ * completion or abandoned at its guard, false when there was nothing to play.
+ * Write failures propagate so the caller can decide to continue restoration.
+ */
+export async function playQuitOutro(frame, effect, durationMs, playback) {
+    const now = playback.now ?? (() => Date.now());
+    const sleep = playback.sleep ?? ((ms) => new Promise(resolve => setTimeout(resolve, ms)));
+    const seed = playback.seed ?? (Date.now() ^ (frame.columns << 16) ^ frame.rows);
+    const plan = createQuitOutroPlan(effect, frame.rowWidths, seed);
+    if (plan.clears.length === 0)
+        return false;
+    const duration = clampQuitOutroDuration(durationMs);
+    let sparkleIndex = 0;
+    let clearIndex = 0;
+    let ticks = 0;
+    playback.write(createQuitOutroSurfaceFrame(frame));
+    const startedAt = now();
+    for (;;) {
+        ticks += 1;
+        const elapsed = now() - startedAt;
+        const progress = Math.min(1, elapsed / duration);
+        let output = `${SYNC_BEGIN}${RESET}`;
+        while (sparkleIndex < plan.sparkles.length && plan.sparkles[sparkleIndex].start <= progress) {
+            const cell = plan.sparkles[sparkleIndex++];
+            output += `${cursorAt(cell.row, cell.col)}${cell.color}${cell.glyph}`;
+        }
+        while (clearIndex < plan.clears.length && plan.clears[clearIndex].end <= progress) {
+            const cell = plan.clears[clearIndex++];
+            output += `${cursorAt(cell.row, cell.col)}${RESET} `;
+        }
+        const finished = clearIndex >= plan.clears.length || progress >= 1
+            || elapsed > duration + QUIT_OUTRO_GUARD_MS || ticks >= QUIT_OUTRO_MAX_TICKS;
+        // Invariant: the last block leaves the alternate screen blank regardless of which
+        // cells the plan reached, so the leave never reveals a half-cleared frame.
+        if (finished)
+            output += `${CLEAR_SCREEN}${HOME}`;
+        playback.write(`${output}${RESET}${SYNC_END}`);
+        if (finished)
+            return true;
+        await sleep(FRAME_MS);
+    }
+}

package/dist/integrations/pi/session-ui/session-shell-root.d.ts

@@ -1,4 +1,4 @@
-import type { OwnedUiPromptSuggestionGeneratorPort, OwnedUiSessionViewModel, OwnedUiViewportSettings, OwnedUiViewportSettingsPort, SuggestionDecision, SuggestionDiagnosticObserver } from "../../../contracts/owned-ui/index.js";
+import type { OwnedUiPromptSuggestionGeneratorPort, OwnedUiSessionViewModel, OwnedUiViewportSettings, OwnedUiViewportSettingsPort, OwnedUiQuitOutroSettingsPort, SuggestionDecision, SuggestionDiagnosticObserver } from "../../../contracts/owned-ui/index.js";
 import type { PiTuiPointerSurface } from "../tui-runtime/contracts.js";
 import type { UiRouteHost } from "../../../ui/apps/contracts.js";
 import type { TranscriptViewportFrame, TranscriptViewportFrameDescriptor } from "../../../ui/components/transcript-viewport.js";
@@ -47,6 +47,17 @@ export interface OwnedUiSessionShellOptions {
     readonly sessionLayout?: "pinned" | "custom-viewport";
     /** Live profile-local settings, supplied only to the bare-A1 composition. */
     readonly viewportSettings?: OwnedUiViewportSettingsPort;
+    /**
+     * Quit outro settings and seams, supplied only to the bare-A1 composition.
+     * `interactive` states whether the terminal can show the animation; production
+     * passes stdout's TTY state, tests opt in explicitly.
+     */
+    readonly quitOutro?: OwnedUiQuitOutroSettingsPort & {
+        readonly interactive: boolean;
+        readonly now?: () => number;
+        readonly sleep?: (ms: number) => Promise<void>;
+        readonly seed?: number;
+    };
     /** Optional platform seam; production uses A1's system clipboard adapter. */
     readonly clipboard?: OwnedUiClipboardPort;
     /** Owned response-copy transport and payload-free diagnostic seams. Comparison profiles ignore them. */

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

@@ -55,6 +55,7 @@ export class OwnedUiSessionShell {
     #responseCopy;
     #unbindClipboardWriter;
     #damageTerminal;
+    #quitOutro;
     #streamPresentation;
     #removeViewportPreInput;
     #unsubscribeSettings;
@@ -250,6 +251,7 @@ export class OwnedUiSessionShell {
         runtime = new PiTuiRuntimeAdapter(runtimeOptions);
         this.runtime = runtime;
         this.#damageTerminal = damageTerminal ?? null;
+        this.#quitOutro = options.quitOutro;
         const presentationInterval = options.streamPresentation?.intervalMs ?? STREAM_PRESENTATION_INTERVAL_MS;
         streamPresentation = options.streamPresentation?.scheduler === undefined
             ? new StreamPresentationCoalescer(() => this.runtime.requestRender(), presentationInterval)
@@ -282,7 +284,9 @@ export class OwnedUiSessionShell {
         this.runtime.setClearOnShrink(initialPiSettings.clearOnShrink);
         this.#terminalProgressEnabled = initialPiSettings.showTerminalProgress;
         this.#fullscreenExitOutput = initialPiSettings.fullscreenExitOutput;
-        this.#unbindShutdownSettings = this.backend.bindSettingsOwner("shutdown", {
+        // 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.
+        this.#unbindShutdownSettings = this.backend.settingsProductMode === "bare" ? () => { } : this.backend.bindSettingsOwner("shutdown", {
             fullscreenExitOutput: { apply() { } },
         });
         this.#unbindTerminalSettings = this.backend.bindSettingsOwner("terminal", {
@@ -1350,6 +1354,8 @@ export class OwnedUiSessionShell {
     }
     async #dispose() {
         this.#disposed = true;
+        // Invariant: the outro frame is what the terminal shows now, before any cleanup writes.
+        const outroFrame = this.#captureQuitOutroFrame();
         this.#responseCopy?.dispose();
         this.#cancelWaitingImages();
         const failures = [];
@@ -1373,11 +1379,13 @@ export class OwnedUiSessionShell {
         let fullscreenExitText = "";
         attempt(() => {
             const exitMode = this.backend.disposed ? this.#fullscreenExitOutput : this.backend.pinnedSettingsSnapshot().fullscreenExitOutput;
-            const exitTranscript = this.root.exitTranscript(this.runtime.viewport().columns);
             const resume = this.backend.currentSessionResumeMetadata();
             const resumeHint = resume === null ? "" : `${dim("To resume this session:")} ${formatSessionResumeCommand(resume)}`;
+            // Invariant: bare A1 leaves only the hint behind; the pinned comparison profile still
+            // honors fullscreenExitOutput, including the styled transcript.
             fullscreenExitText = this.runtime.mode !== "fullscreen" ? ""
-                : exitMode === "resume-hint" ? resumeHint : [exitTranscript, resumeHint].filter(Boolean).join("\n\n");
+                : this.#customViewport || exitMode === "resume-hint" ? resumeHint
+                    : [this.root.exitTranscript(this.runtime.viewport().columns), resumeHint].filter(Boolean).join("\n\n");
         });
         attempt(() => this.#unbindClipboardWriter());
         attempt(() => this.#unbindPiSettings());
@@ -1386,8 +1394,15 @@ export class OwnedUiSessionShell {
         attempt(() => this.#unsubscribe());
         attempt(() => this.#dialogHandle?.hide());
         attempt(() => this.#extensionBridge.dispose());
-        // Invariant: terminal restoration precedes any potentially stalled backend teardown.
-        await this.runtime.dispose().catch(error => failures.push(error));
+        // Invariant: from here to the leave nothing but the outro paints. A throttled frame the
+        // renderer still has queued would otherwise land during the stop-time input drain and
+        // flash the prompt and footer, whether or not an effect plays.
+        attempt(() => this.#freezeQuitPresentation());
+        await this.#playQuitOutro(outroFrame);
+        // Invariant: terminal restoration precedes any potentially stalled backend teardown. The
+        // fullscreen leave preserves the screen: the pinned runtime never dumps its final document
+        // into the parent terminal, so only the configured exit text follows the leave.
+        await this.runtime.dispose({ preserveScreen: this.runtime.mode === "fullscreen" }).catch(error => failures.push(error));
         await historyCleanup.catch(() => false); // Security: background durability outcomes never enter terminal output.
         await boundedCleanup(() => pasteCleanup).catch(error => failures.push(error));
         await boundedCleanup(() => this.backend.unbindExtensionUi()).catch(error => failures.push(error));
@@ -1396,6 +1411,51 @@ export class OwnedUiSessionShell {
         if (fullscreenExitText.length > 0)
             this.runtime.writeAfterStop(`${fullscreenExitText}\n`);
     }
+    // Invariant: the snapshot is synchronous; the outro module itself loads only at quit.
+    #captureQuitOutroFrame() {
+        const outro = this.#quitOutro;
+        if (outro === undefined || !outro.interactive || !this.#customViewport || this.#damageTerminal === null)
+            return null;
+        if (!this.runtime.active || this.runtime.mode !== "fullscreen")
+            return null;
+        try {
+            const { enabled, effect, durationMs } = outro.snapshot();
+            if (!enabled)
+                return null;
+            const viewport = this.runtime.viewport();
+            return { rows: this.#damageTerminal.presentedRows(), columns: viewport.columns, height: viewport.rows, settings: { effect, durationMs } };
+        }
+        catch {
+            return null;
+        }
+    }
+    #freezeQuitPresentation() {
+        if (!this.#customViewport || !this.runtime.active || this.runtime.mode !== "fullscreen")
+            return;
+        this.runtime.freezePresentation();
+    }
+    // Rationale: any failure here only skips the effect; restoration always follows.
+    async #playQuitOutro(capture) {
+        const outro = this.#quitOutro;
+        if (capture === null || outro === undefined || !this.runtime.active)
+            return;
+        try {
+            // Rationale: the effects stay off the startup graph; quit is the only time they load.
+            const { captureQuitOutroFrame, playQuitOutro } = await import("./quit-outro.js");
+            const frame = captureQuitOutroFrame(capture.rows, capture.columns, capture.height);
+            if (frame === null || !this.runtime.active)
+                return;
+            await playQuitOutro(frame, capture.settings.effect, capture.settings.durationMs, {
+                write: data => this.runtime.writeControl(data),
+                ...(outro.now === undefined ? {} : { now: outro.now }),
+                ...(outro.sleep === undefined ? {} : { sleep: outro.sleep }),
+                ...(outro.seed === undefined ? {} : { seed: outro.seed }),
+            });
+        }
+        catch {
+            // Rationale: a failed or interrupted effect must never hold the terminal; restoration follows.
+        }
+    }
     #settleStoppedLifecycle() {
         void this.dispose().then(() => this.#resolveStoppedLifecycle(), () => this.#resolveStoppedLifecycle());
     }

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

@@ -26,10 +26,18 @@ export declare class PiTuiRuntimeAdapter {
     hasFocusedOverlay(): boolean;
     /**
      * Writes a terminal control sequence. Used to enable and disable mouse
-     * reporting while an A1-owned application is presented, and for nothing else:
-     * the transparent and pinned paths never call it.
+     * reporting while an A1-owned application is presented and to paint the quit
+     * outro while presentation is frozen, and for nothing else: the transparent
+     * and pinned paths never call it.
      */
     writeControl(data: string): void;
+    /**
+     * Drops every pinned frame write until the runtime stops. The quit outro owns
+     * the alternate screen between the last presented frame and the leave; the
+     * renderer keeps scheduling but nothing it paints reaches the terminal.
+     */
+    freezePresentation(): void;
+    get presentationFrozen(): boolean;
     addPreInputListener(listener: PiTuiPreInputListener): () => void;
     addInputListener(listener: PiTuiInputListener): () => void;
     switchMode(mode: "regular" | "fullscreen"): boolean;

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

@@ -120,15 +120,20 @@ export class PiTuiRuntimeAdapter {
     #stopPromise;
     #rootDisposed = false;
     #terminalProgress = false;
+    #presentationFrozen = false;
     constructor(options) {
         this.#root = options.root;
         this.#overlayGeometry = options.onOverlayGeometry === undefined ? undefined : new OverlayGeometryTracker(options.onOverlayGeometry);
         this.#terminal = options.terminal ?? new ProcessTerminal();
         this.#inputDiagnostics = options.inputDiagnostics;
         this.#diagnosticNow = options.inputDiagnostics?.now ?? (() => performance.now());
+        // Invariant: the pinned renderer's frames pass through this gate, while writeControl and
+        // the stop sequence reach the terminal directly. Freezing drops frames without touching
+        // the renderer, so a scheduled repaint cannot land on top of the quit outro.
+        const gatedTerminal = frozenGateTerminal(this.#terminal, () => this.#presentationFrozen);
         const tracedTerminal = options.inputDiagnostics === undefined
-            ? this.#terminal
-            : diagnosticTerminal(this.#terminal, phase => this.#traceRuntimePhase(phase));
+            ? gatedTerminal
+            : diagnosticTerminal(gatedTerminal, phase => this.#traceRuntimePhase(phase));
         const decoratedTerminal = options.decorateTerminal?.(tracedTerminal) ?? tracedTerminal;
         const coordination = options.inputCoordination ?? (options.inputDiagnostics === undefined
             ? undefined
@@ -297,13 +302,26 @@ export class PiTuiRuntimeAdapter {
     }
     /**
      * Writes a terminal control sequence. Used to enable and disable mouse
-     * reporting while an A1-owned application is presented, and for nothing else:
-     * the transparent and pinned paths never call it.
+     * reporting while an A1-owned application is presented and to paint the quit
+     * outro while presentation is frozen, and for nothing else: the transparent
+     * and pinned paths never call it.
      */
     writeControl(data) {
         this.#assertRunning("control sequence");
         this.#terminal.write(data);
     }
+    /**
+     * Drops every pinned frame write until the runtime stops. The quit outro owns
+     * the alternate screen between the last presented frame and the leave; the
+     * renderer keeps scheduling but nothing it paints reaches the terminal.
+     */
+    freezePresentation() {
+        this.#assertRunning("presentation freeze");
+        this.#presentationFrozen = true;
+    }
+    get presentationFrozen() {
+        return this.#presentationFrozen;
+    }
     addPreInputListener(listener) {
         if (this.#preInputListeners.has(listener))
             throw new TypeError("Pi TUI pre-input listener is already registered");
@@ -433,6 +451,9 @@ export class PiTuiRuntimeAdapter {
         }
         try {
             const stopOptions = options.preserveScreen === undefined ? undefined : { preserveScreen: options.preserveScreen };
+            // Invariant: the gate opens only for the synchronous stop sequence, so no render
+            // scheduled during the outro can slip in before the alternate screen is left.
+            this.#presentationFrozen = false;
             this.#tui.stop(stopOptions);
         }
         catch (error) {
@@ -566,6 +587,7 @@ export class PiTuiRuntimeAdapter {
             throw new Error(`Pi TUI ${operation} requires a running runtime`);
     }
     #restoreAfterFailedStart() {
+        this.#presentationFrozen = false;
         try {
             this.#tui.stop();
         }
@@ -581,6 +603,7 @@ export class PiTuiRuntimeAdapter {
         this.#terminalProgress = false;
     }
     #bestEffortTerminalRestore() {
+        this.#presentationFrozen = false;
         this.#clearTerminalProgress();
         try {
             if (this.mode === "fullscreen")
@@ -676,6 +699,32 @@ function diagnosticTerminal(terminal, trace) {
         setProgress: active => terminal.setProgress(active),
     };
 }
+function frozenGateTerminal(terminal, frozen) {
+    return {
+        get columns() { return terminal.columns; },
+        get rows() { return terminal.rows; },
+        get kittyProtocolActive() { return terminal.kittyProtocolActive; },
+        start: (onInput, onResize) => terminal.start(onInput, onResize),
+        stop: () => terminal.stop(),
+        drainInput: (maxMs, idleMs) => terminal.drainInput(maxMs, idleMs),
+        write: data => { if (!frozen())
+            terminal.write(data); },
+        moveBy: lines => { if (!frozen())
+            terminal.moveBy(lines); },
+        hideCursor: () => { if (!frozen())
+            terminal.hideCursor(); },
+        showCursor: () => { if (!frozen())
+            terminal.showCursor(); },
+        clearLine: () => { if (!frozen())
+            terminal.clearLine(); },
+        clearFromCursor: () => { if (!frozen())
+            terminal.clearFromCursor(); },
+        clearScreen: () => { if (!frozen())
+            terminal.clearScreen(); },
+        setTitle: title => terminal.setTitle(title),
+        setProgress: active => terminal.setProgress(active),
+    };
+}
 function preInputTerminal(terminal, route, frameMouse) {
     let mouse;
     return {