@timurproko/a1 0.1.8-dev.444 → 0.1.8-dev.457

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,11 @@ 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));
+        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 +1407,47 @@ 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 { effect, durationMs } = outro.snapshot();
+            if (effect === "off")
+                return null;
+            const viewport = this.runtime.viewport();
+            return { rows: this.#damageTerminal.presentedRows(), columns: viewport.columns, height: viewport.rows, settings: { effect, durationMs } };
+        }
+        catch {
+            return null;
+        }
+    }
+    // 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;
+            this.runtime.freezePresentation();
+            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());
     }