@sayknow-cli/coding-agent 0.6.4 → 0.6.6

package/src/modes/components/welcome.ts

@@ -1,19 +1,34 @@
-import { type Component, padding, TERMINAL, truncateToWidth, visibleWidth } from "@sayknow-cli/tui";
-import { APP_NAME } from "@sayknow-cli/utils";
+import type { ThinkingLevel } from "@sayknow-cli/agent-core";
+import {
+	type Component,
+	type PetSkinId,
+	padding,
+	renderPetHalfBlocks,
+	type SayknowPixelFrameName,
+	truncateToWidth,
+	visibleWidth,
+} from "@sayknow-cli/tui";
 import { formatBuildLabel } from "../../build-metadata";
 import { formatKeyHint, type KeyDisplayContext } from "../../config/keybindings";
-import { t } from "../../i18n";
-import { type ThemeColor, theme } from "../../modes/theme/theme";
+import { type MsgKey, t } from "../../i18n";
+import { theme } from "../../modes/theme/theme";
 
 export interface RecentSession {
 	name: string;
 	timeAgo: string;
 }
 
-export interface LspServerInfo {
-	name: string;
-	status: "idle" | "ready" | "error" | "connecting";
-	fileTypes: string[];
+/**
+ * Workspace facts on the launch card. Every field is optional: the card renders
+ * what is known and fills in git state once the asynchronous probe settles.
+ */
+export interface WelcomeSnapshot {
+	/** Display path of the project directory (already home-shortened). */
+	cwd?: string;
+	/** Current branch, `"detached"`, or `null` outside a git repository. */
+	branch?: string | null;
+	gitChanges?: { staged: number; unstaged: number; untracked: number } | null;
+	thinkingLevel?: ThinkingLevel | string;
 }
 
 export type WelcomeLogoMode = "unicode" | "square" | "ascii";
@@ -22,57 +37,78 @@ export interface WelcomeComponentOptions {
 	getReservedBottomRows?: (termWidth: number) => number;
 	changelogMarkdown?: string;
 	rightGutterWidth?: number;
+	/** Show only the version on the release line, without its first note. */
 	collapseChangelog?: boolean;
 	buildLabel?: string;
 	keyDisplayContext?: KeyDisplayContext;
 	skipLogoAnimation?: boolean;
+	snapshot?: WelcomeSnapshot;
+	/** Key bound to the resume picker (`app.session.resume`); the card names it. */
+	resumeKey?: string;
+	/** Key bound to `app.session.continue`, which resumes the first session on the card. */
+	continueKey?: string;
+	/** Which Sayknow pet stands on the card (default red). */
+	petSkin?: PetSkinId;
 }
 
-const WELCOME_STATIC_RIGHT_ROWS_EXCLUDING_DYNAMIC_SECTIONS = 15;
-const DEFAULT_WHATS_NEW_ROWS = 3;
-const MAX_WHATS_NEW_ROWS = 12;
-
-function flowKeyItems(context: KeyDisplayContext): ReadonlyArray<{ key: string; label: string }> {
-	const newlineKey = context.platform === "win32" ? "alt+enter" : "ctrl+j";
-	return [
-		{ key: "/", label: "commands" },
-		{ key: "#", label: "actions" },
-		{ key: "!", label: "shell" },
-		{ key: "$", label: "python" },
-		{ key: "?", label: "keymap" },
-		{ key: "ctrl+l", label: "model" },
-		{ key: "shift+tab", label: "reasoning" },
-		{ key: "tab", label: "complete" },
-		{ key: newlineKey, label: "newline" },
-		{ key: "ctrl+c", label: "clear" },
-	];
+/** Left margin of the card, and the widest the card grows on wide terminals. */
+const MARGIN = 2;
+const MAX_CARD_WIDTH = 76;
+/** Gap between the mark and the identity lines. */
+const MARK_GAP = 3;
+/** Below this card width the mark is dropped and only the identity lines remain. */
+const MIN_WIDTH_FOR_MARK = 44;
+/** Recent sessions on the card; the resume picker has the rest. */
+const SESSION_ROWS = 3;
+
+/** ASCII-safe stand-in for the pet when the banner must avoid block glyphs. */
+const MARK_ASCII = ["  .---.  ", " ( o o ) ", "  )   (  ", " /\\/\\/\\/ "] as const;
+const MARK_ASCII_WAVE = " \\/\\/\\/\\ ";
+
+/**
+ * Intro: the pet does a short para-para (tentacles sway left, right, left) and
+ * lands on its resting pose while color spreads down the card.
+ */
+const INTRO_POSES: readonly SayknowPixelFrameName[] = ["danceL", "danceR", "danceL", "base"];
+const SECTION_STAGGER_MS = 55;
+const SECTION_SETTLE_MS = 90;
+const WAVE_STEP_MS = 140;
+const INTRO_MS = INTRO_POSES.length * WAVE_STEP_MS;
+
+/** A block of rows that takes its colors together during the intro. */
+interface Section {
+	lines: string[];
+	/** When the viewport is short, the section with the highest rank is dropped first. */
+	dropRank: number;
 }
 
 /**
- * Sayknow-CLI launch surface: a blue-gradient SAYKNOW wordmark, compact
- * command affordances, and project signals — a distinct identity, not a
- * copy of another agent shell.
+ * Sayknow-CLI launch card: the octopus mark beside who and where you are
+ * (version, model and reasoning, project and branch), then the three most recent
+ * sessions and a single row of keys. Everything else — the full session list,
+ * workflows, the keymap, release notes — is one key away, not on the card.
  */
 export class WelcomeComponent implements Component {
 	#animStart: number | null = null;
 	#animTimer: NodeJS.Timeout | null = null;
+	#snapshot: WelcomeSnapshot;
 
 	constructor(
 		private readonly version: string,
 		private modelName: string,
 		private providerName: string,
 		private recentSessions: RecentSession[] = [],
-		private lspServers: LspServerInfo[] = [],
 		private readonly logoMode: WelcomeLogoMode = "unicode",
 		private readonly options: WelcomeComponentOptions = {},
-	) {}
+	) {
+		this.#snapshot = { ...options.snapshot };
+	}
 
 	invalidate(): void {}
 
 	/**
-	 * Play a one-shot intro that sweeps the gradient through every phase
-	 * before settling on the resting frame. Safe to call multiple times —
-	 * subsequent calls reset and replay.
+	 * Play the short launch intro. Content is fully readable from the first frame;
+	 * only color and the tentacles move. Safe to call again — it restarts.
 	 */
 	playIntro(requestRender: () => void): void {
 		this.#stopAnimation();
@@ -84,9 +120,7 @@ export class WelcomeComponent implements Component {
 		requestRender();
 		this.#animTimer = setInterval(() => {
 			const elapsed = performance.now() - (this.#animStart ?? 0);
-			if (elapsed >= INTRO_MS) {
-				this.#stopAnimation();
-			}
+			if (elapsed >= INTRO_MS) this.#stopAnimation();
 			requestRender();
 		}, INTRO_TICK_MS);
 		this.#animTimer.unref?.();
@@ -113,433 +147,206 @@ export class WelcomeComponent implements Component {
 		this.recentSessions = sessions;
 	}
 
-	setLspServers(servers: LspServerInfo[]): void {
-		this.lspServers = servers;
+	/** Merge newly probed workspace facts into the card. */
+	setSnapshot(patch: WelcomeSnapshot): void {
+		this.#snapshot = { ...this.#snapshot, ...patch };
 	}
 
 	render(termWidth: number): string[] {
-		const rightGutterWidth = this.#rightGutterWidth(termWidth);
-		const boxWidth = Math.max(0, termWidth - rightGutterWidth);
-		if (boxWidth < 4) {
-			return [];
-		}
+		const gutterWidth = this.#rightGutterWidth(termWidth);
+		const width = Math.max(0, termWidth - gutterWidth);
+		if (width < 4) return [];
 
 		const targetRows = this.#targetRows(termWidth);
-		if (targetRows !== undefined && targetRows <= 0) {
-			return [];
-		}
-		const targetContentRows = targetRows === undefined ? undefined : Math.max(0, targetRows - 2);
-		const dualContentWidth = boxWidth - 3; // 3 = │ + │ + │
-		const minLeftCol = 20; // wordmark plus Sayknow identity labels
-		const minRightCol = 24;
-		const modelPill = this.#pill(theme.icon.model || "model", this.modelName, "statusLineModel");
-		const providerPill = this.#pill(theme.icon.package || "provider", this.providerName, "statusLinePath");
-		const logoLines = this.#logoLines();
-		const logoMinWidth = Math.max(...logoLines.map(line => visibleWidth(line)));
-		const leftMinContentWidth = Math.max(
-			minLeftCol,
-			logoMinWidth,
-			visibleWidth(t("welcome.tagline")),
-			visibleWidth(modelPill),
-			visibleWidth(providerPill),
-		);
-		const evenLeftCol = Math.floor(dualContentWidth / 2);
-		const maxLeftColWithRightMinimum = Math.max(1, dualContentWidth - minRightCol);
-		const desiredLeftCol = Math.max(leftMinContentWidth, evenLeftCol);
-		const dualLeftCol =
-			dualContentWidth >= minRightCol + 1
-				? Math.min(desiredLeftCol, maxLeftColWithRightMinimum)
-				: Math.max(1, dualContentWidth - 1);
-		const dualRightCol = Math.max(1, dualContentWidth - dualLeftCol);
-		const showRightColumn = dualLeftCol >= leftMinContentWidth && dualRightCol >= minRightCol;
-		const leftCol = showRightColumn ? dualLeftCol : boxWidth - 2;
-		const rightCol = showRightColumn ? dualRightCol : 0;
-
-		const logoColored = this.#currentLogoFrame(logoLines);
-
-		// When no model is resolved yet, guide the user instead of showing "Unknown".
-		const hasModel = this.modelName !== "Unknown" && this.modelName.length > 0;
-		const identityTail = hasModel
-			? [this.#centerText(modelPill, leftCol), this.#centerText(providerPill, leftCol)]
-			: [
-					this.#centerText(
-						this.#pill(theme.icon.model || "model", t("welcome.chooseModel"), "statusLineModel"),
-						leftCol,
-					),
-					this.#centerText(theme.fg("dim", t("welcome.modelHint")), leftCol),
-				];
-
-		// Left column - centered identity stack: wordmark, tagline, then model state.
-		const leftLines = [
-			"",
-			...logoColored.map(l => this.#centerText(l, leftCol)),
-			"",
-			this.#centerText(theme.fg("muted", t("welcome.tagline")), leftCol),
-			"",
-			...identityTail,
-		];
-
-		const buildSeparator = (columnWidth: number): string =>
-			` ${theme.fg("dim", theme.boxRound.horizontal.repeat(Math.max(0, columnWidth - 2)))}`;
-
-		const rightColumnWidth = showRightColumn ? rightCol : leftCol;
-		const separator = buildSeparator(rightColumnWidth);
-		const lspLines: string[] = [];
-		if (this.lspServers.length === 0) {
-			lspLines.push(` ${theme.fg("dim", t("welcome.noLsp"))}`);
-		} else {
-			for (const server of this.lspServers.slice(0, 4)) {
-				const icon =
-					server.status === "ready"
-						? theme.styledSymbol("status.success", "success")
-						: server.status === "error"
-							? theme.styledSymbol("status.error", "error")
-							: theme.styledSymbol("status.pending", "muted");
-				const exts = server.fileTypes.slice(0, 3).join(" ");
-				lspLines.push(` ${icon} ${theme.fg("muted", server.name)} ${theme.fg("dim", exts)}`);
-			}
-		}
+		if (targetRows !== undefined && targetRows <= 0) return [];
+		if (targetRows === 1) return this.#withRightGutter([this.#fit(this.#titleLine(true), width)], gutterWidth);
+
+		const cardWidth = Math.max(1, Math.min(MAX_CARD_WIDTH, width - MARGIN));
+		const sections = this.#sections(cardWidth);
+		const lines = this.#fitRows(sections, targetRows);
+		const margin = padding(MARGIN);
+		const out = lines.map(line => this.#fit(line ? margin + line : "", width));
+		if (targetRows !== undefined) while (out.length < targetRows) out.push(padding(width));
+		return this.#withRightGutter(out, gutterWidth);
+	}
 
-		const flowPreferredRows = this.#flowKeyRows(rightColumnWidth).length;
-		const changelogRowLimit = this.#whatsNewRowLimit(targetContentRows, lspLines.length, flowPreferredRows);
-		const changelogLines = this.#whatsNewLines(rightColumnWidth, changelogRowLimit);
-		const flowRowLimit = this.#flowKeyRowLimit(
-			targetContentRows,
-			changelogLines.length,
-			lspLines.length,
-			rightColumnWidth,
-		);
-		const flowLines = this.#flowKeyLines(rightColumnWidth, flowRowLimit);
-		const sessionLimit = this.#sessionTrailLimit(
-			targetContentRows,
-			changelogLines.length,
-			lspLines.length,
-			flowLines.length,
-		);
-		const sessionLines = this.#sessionTrailLines(rightColumnWidth, sessionLimit);
-
-		// Workflow affordances: pad the command so descriptions align.
-		const wf = (cmd: string, desc: string): string => {
-			const pad = " ".repeat(Math.max(1, 17 - visibleWidth(cmd)));
-			return ` ${theme.fg("accent", cmd)}${pad}${theme.fg("muted", desc)}`;
+	/**
+	 * Lay the sections out with a blank row above and between them. When the
+	 * viewport is short, whole sections go by rank — keys, then the release
+	 * note, then sessions — and the identity block is clipped last.
+	 */
+	#fitRows(sections: { identity: string[]; others: Section[] }, targetRows: number | undefined): string[] {
+		const colored = this.#colorReveal(1 + sections.others.length);
+		const identity = this.#inkSection(sections.identity, 0, colored);
+		let others = sections.others.map((section, index) => ({
+			...section,
+			lines: this.#inkSection(section.lines, index + 1, colored),
+		}));
+		const assemble = (): string[] => {
+			const out = ["", ...identity];
+			for (const section of others) out.push("", ...section.lines);
+			return out;
 		};
-
-		const rightLines = [
-			"",
-			` ${theme.bold(theme.fg("accent", "What's New"))}`,
-			...changelogLines,
-			separator,
-			` ${theme.bold(theme.fg("accent", t("welcome.workflows")))}`,
-			wf("/deep-interview", t("welcome.wf.deepInterview")),
-			wf("/ralplan", t("welcome.wf.ralplan")),
-			wf("/ultragoal", t("welcome.wf.ultragoal")),
-			wf("/team", t("welcome.wf.team")),
-			separator,
-			` ${theme.bold(theme.fg("accent", t("welcome.flowKeys")))}`,
-			...flowLines,
-			separator,
-			` ${theme.bold(theme.fg("accent", t("welcome.projectPulse")))}`,
-			...lspLines,
-			separator,
-			` ${theme.bold(theme.fg("accent", t("welcome.sessionTrail")))}`,
-			...sessionLines,
-			"",
-		];
-
-		const contentRows =
-			targetContentRows ??
-			(showRightColumn ? Math.max(leftLines.length, rightLines.length) : leftLines.length + rightLines.length);
-		const outputRows = targetRows === undefined ? Math.max(3, contentRows + 2) : targetRows;
-		const bodyRows = Math.max(0, outputRows - 2);
-
-		const hChar = theme.boxRound.horizontal;
-		const h = theme.fg("dim", hChar);
-		const v = theme.fg("dim", theme.boxRound.vertical);
-		const tl = theme.fg("dim", theme.boxRound.topLeft);
-		const tr = theme.fg("dim", theme.boxRound.topRight);
-		const bl = theme.fg("dim", theme.boxRound.bottomLeft);
-		const br = theme.fg("dim", theme.boxRound.bottomRight);
-
-		const lines: string[] = [];
-		const buildLabel = this.options.buildLabel ?? formatBuildLabel();
-		const title = ` ${APP_NAME} · Sayknow-CLI v${this.version} · ${buildLabel} `;
-		const titlePrefixRaw = hChar.repeat(3);
-		const titleStyled = theme.fg("dim", titlePrefixRaw) + theme.fg("muted", title);
-		const titleVisLen = visibleWidth(titlePrefixRaw) + visibleWidth(title);
-		const titleSpace = boxWidth - 2;
-		if (titleVisLen >= titleSpace) {
-			lines.push(tl + truncateToWidth(titleStyled, titleSpace) + tr);
-		} else {
-			const afterTitle = titleSpace - titleVisLen;
-			lines.push(tl + titleStyled + theme.fg("dim", hChar.repeat(afterTitle)) + tr);
-		}
-		if (outputRows === 1) {
-			return this.#withRightGutter(lines, rightGutterWidth);
-		}
-
-		if (showRightColumn) {
-			const leftBlock = this.#fitBlock(leftLines, bodyRows, "center");
-			const rightBlock = this.#fitBlock(rightLines, bodyRows, "top");
-			for (let i = 0; i < bodyRows; i++) {
-				const left = this.#fitToWidth(leftBlock[i] ?? "", leftCol);
-				const right = this.#fitToWidth(rightBlock[i] ?? "", rightCol);
-				lines.push(v + left + v + right + v);
-			}
-			lines.push(bl + h.repeat(leftCol) + theme.fg("dim", theme.boxSharp.teeUp) + h.repeat(rightCol) + br);
-		} else {
-			const compactLeftLines =
-				bodyRows < 14
-					? [
-							this.#centerText(theme.bold(theme.fg("accent", "SKC Forge")), leftCol),
-							this.#centerText(this.#loadingLine(), leftCol),
-							this.#centerText(modelPill, leftCol),
-						]
-					: leftLines;
-			const singleBlock = this.#fitBlock([...compactLeftLines, separator, ...rightLines], bodyRows, "top");
-			for (let i = 0; i < bodyRows; i++) {
-				lines.push(v + this.#fitToWidth(singleBlock[i] ?? "", leftCol) + v);
-			}
-			lines.push(bl + h.repeat(leftCol) + br);
+		let lines = assemble();
+		if (targetRows === undefined) return lines;
+		while (lines.length > targetRows && others.length > 0) {
+			const drop = others.reduce((worst, section) => (section.dropRank > worst.dropRank ? section : worst));
+			others = others.filter(section => section !== drop);
+			lines = assemble();
 		}
+		return lines.slice(0, targetRows);
+	}
 
-		return this.#withRightGutter(lines, rightGutterWidth);
+	#sections(cardWidth: number): { identity: string[]; others: Section[] } {
+		const others: Section[] = [];
+		const note = this.#releaseNoteLine(cardWidth);
+		if (note) others.push({ lines: [note], dropRank: 2 });
+		others.push({ lines: this.#sessionLines(cardWidth), dropRank: 1 });
+		others.push({ lines: [this.#keysLine(cardWidth)], dropRank: 3 });
+		return { identity: this.#identityLines(cardWidth), others };
 	}
 
-	/** Center text within a given width */
-	#centerText(text: string, width: number): string {
-		const visLen = visibleWidth(text);
-		if (visLen >= width) {
-			return truncateToWidth(text, width);
+	// ── Identity: mark + who and where ──────────────────────────────────────
+
+	#identityLines(cardWidth: number): string[] {
+		const withMark = cardWidth >= MIN_WIDTH_FOR_MARK;
+		const mark = withMark ? this.#markRows() : [];
+		const markWidth = Math.max(0, ...mark.map(row => visibleWidth(row)));
+		const infoWidth = Math.max(1, withMark ? cardWidth - markWidth - MARK_GAP : cardWidth);
+		const info = [
+			this.#truncate(this.#titleLine(!withMark), infoWidth),
+			this.#truncate(theme.fg("muted", t("welcome.tagline")), infoWidth),
+			this.#truncate(this.#modelLine(), infoWidth),
+			this.#truncate(this.#whereLine(infoWidth), infoWidth),
+		];
+		if (!withMark) return info;
+		// Center the four identity lines against the pet's height.
+		const offset = Math.max(0, Math.floor((mark.length - info.length) / 2));
+		const rows = Math.max(mark.length, info.length + offset);
+		const out: string[] = [];
+		for (let row = 0; row < rows; row++) {
+			const art = mark[row] ?? padding(markWidth);
+			const text = info[row - offset] ?? "";
+			out.push(text ? `${art}${padding(MARK_GAP)}${text}` : art);
 		}
-		const leftPad = Math.floor((width - visLen) / 2);
-		const rightPad = width - visLen - leftPad;
-		return padding(leftPad) + text + padding(rightPad);
+		return out;
 	}
 
-	/** Fit string to exact width with native ANSI/wide-glyph truncation and padding. */
-	#fitToWidth(str: string, width: number): string {
-		const visLen = visibleWidth(str);
-		if (visLen > width) {
-			return truncateToWidth(str, width, null, true);
+	/** The Sayknow pet itself, in half blocks; the pose follows the intro. */
+	#markRows(): string[] {
+		const step = this.#animStart == null ? -1 : Math.floor((performance.now() - this.#animStart) / WAVE_STEP_MS);
+		if (this.logoMode === "ascii") {
+			const rows: string[] = [...MARK_ASCII];
+			if (step >= 0 && step < INTRO_POSES.length - 1 && step % 2 === 1) rows[3] = MARK_ASCII_WAVE;
+			return rows.map(row => theme.fg("accent", row));
 		}
-		return str + padding(width - visLen);
-	}
-	#rightGutterWidth(termWidth: number): number {
-		const configured = this.options.rightGutterWidth ?? 0;
-		if (!Number.isFinite(configured) || configured <= 0) return 0;
-		const gutterWidth = Math.floor(configured);
-		return Math.min(gutterWidth, Math.max(0, termWidth - 4));
+		const pose = step >= 0 && step < INTRO_POSES.length ? INTRO_POSES[step]! : "base";
+		return renderPetHalfBlocks(pose, this.options.petSkin ?? "red", theme.getColorMode());
 	}
 
-	#withRightGutter(lines: string[], rightGutterWidth: number): string[] {
-		if (rightGutterWidth <= 0) return lines;
-		const gutter = padding(rightGutterWidth);
-		return lines.map(line => line + gutter);
+	/** `withIcon` adds the 🐙 glyph for layouts that have no room for the drawn mark. */
+	#titleLine(withIcon = false): string {
+		const buildLabel = this.options.buildLabel ?? formatBuildLabel();
+		const mark = withIcon && this.logoMode !== "ascii" && theme.icon.pi ? `${theme.icon.pi} ` : "";
+		return `${mark}${theme.bold(theme.fg("text", "Sayknow-CLI"))}${theme.fg("dim", ` v${this.version} · ${buildLabel}`)}`;
 	}
 
-	#targetRows(termWidth: number): number | undefined {
-		const viewportRows = this.options.getViewportRows?.();
-		if (typeof viewportRows !== "number" || !Number.isFinite(viewportRows) || viewportRows <= 0) {
-			return undefined;
+	#modelLine(): string {
+		const sep = theme.fg("dim", " · ");
+		if (this.modelName === "Unknown" || this.modelName.length === 0) {
+			return `${theme.fg("accent", t("welcome.chooseModel"))}${sep}${theme.fg("dim", t("welcome.modelHint"))}`;
 		}
-		const reservedRows = Math.max(0, Math.floor(this.options.getReservedBottomRows?.(termWidth) ?? 0));
-		return Math.max(0, Math.floor(viewportRows) - reservedRows);
+		const parts = [theme.bold(theme.fg("statusLineModel", this.modelName))];
+		const level = this.#snapshot.thinkingLevel;
+		if (level) parts.push(theme.getThinkingBorderColor(String(level) as ThinkingLevel)(String(level)));
+		else if (this.providerName) parts.push(theme.fg("muted", this.providerName));
+		return parts.join(sep);
 	}
 
-	#loadingLine(): string {
-		const frames = theme.spinnerFrames;
-		const elapsed = this.#animStart == null ? 0 : performance.now() - this.#animStart;
-		const frame = frames.length > 0 ? (frames[Math.floor(elapsed / 100) % frames.length] ?? "*") : "*";
-		const label = this.#animStart == null ? "ready" : "warming workspace";
-		return `${theme.fg("warning", frame)} ${theme.fg("muted", label)}`;
+	#whereLine(width: number): string {
+		const { cwd, branch } = this.#snapshot;
+		const sep = theme.fg("dim", " · ");
+		const branchPart =
+			typeof branch === "string"
+				? `${theme.fg(this.#isDirty() ? "statusLineGitDirty" : "statusLineGitClean", branch)}${this.#changeSummary()}`
+				: "";
+		if (!cwd) return branchPart;
+		const pathBudget = Math.max(8, width - (branchPart ? visibleWidth(branchPart) + 3 : 0));
+		const path = theme.fg("statusLinePath", this.#shortenFromLeft(cwd, pathBudget));
+		return branchPart ? `${path}${sep}${branchPart}` : path;
 	}
 
-	#fitBlock(lines: string[], rows: number, align: "top" | "center"): string[] {
-		if (rows <= 0) return [];
-		const clipped =
-			lines.length > rows
-				? rows === 1
-					? [theme.fg("dim", " …")]
-					: [...lines.slice(0, rows - 1), theme.fg("dim", " …")]
-				: lines;
-		const missingRows = rows - clipped.length;
-		if (missingRows <= 0) return clipped;
-		const topPad = align === "center" ? Math.floor(missingRows / 2) : 0;
-		const bottomPad = missingRows - topPad;
-		return [...Array.from({ length: topPad }, () => ""), ...clipped, ...Array.from({ length: bottomPad }, () => "")];
+	#isDirty(): boolean {
+		const changes = this.#snapshot.gitChanges;
+		return !!changes && changes.staged + changes.unstaged + changes.untracked > 0;
 	}
 
-	#flowKeyItemText(item: { key: string; label: string }): string {
-		const context = this.options.keyDisplayContext ?? { platform: process.platform };
-		return `${theme.fg("dim", formatKeyHint(item.key, context))}${theme.fg("muted", ` ${this.#flowKeyLabel(item.label)}`)}`;
-	}
-
-	#flowKeyLabel(label: string): string {
-		switch (label) {
-			case "commands":
-				return t("welcome.commands");
-			case "actions":
-				return t("welcome.actions");
-			case "shell":
-				return t("welcome.shell");
-			case "python":
-				return t("welcome.python");
-			case "keymap":
-				return t("welcome.keymap");
-			case "model":
-				return t("welcome.model");
-			case "reasoning":
-				return t("welcome.reasoning");
-			default:
-				return label;
-		}
+	#changeSummary(): string {
+		const changes = this.#snapshot.gitChanges;
+		if (!changes || !this.#isDirty()) return "";
+		const parts: string[] = [];
+		if (changes.staged > 0) parts.push(theme.fg("statusLineStaged", `+${changes.staged}`));
+		if (changes.unstaged > 0) parts.push(theme.fg("statusLineDirty", `~${changes.unstaged}`));
+		if (changes.untracked > 0) parts.push(theme.fg("statusLineUntracked", `?${changes.untracked}`));
+		return ` ${parts.join(" ")}`;
 	}
 
-	#flowKeyRows(width: number): string[] {
-		const contentWidth = Math.max(1, width - 1);
-		const separator = ` ${theme.fg("dim", "·")} `;
-		const rows: string[] = [];
-		let current = "";
-		for (const item of flowKeyItems(this.options.keyDisplayContext ?? { platform: process.platform })) {
-			const segment = this.#flowKeyItemText(item);
-			const next = current ? `${current}${separator}${segment}` : segment;
-			if (current && visibleWidth(next) > contentWidth) {
-				rows.push(` ${current}`);
-				current = segment;
-			} else {
-				current = next;
-			}
-		}
-		if (current) rows.push(` ${current}`);
-		return rows.length > 0 ? rows : [` ${theme.fg("dim", "No flow keys")}`];
-	}
-
-	#flowKeyLines(width: number, maxRows: number): string[] {
-		const rows = this.#flowKeyRows(width);
-		const rowLimit = Math.max(1, Math.floor(maxRows));
-		if (rows.length <= rowLimit) return rows;
-		if (rowLimit === 1) {
-			const firstItem = flowKeyItems(this.options.keyDisplayContext ?? { platform: process.platform })[0];
-			const firstSegment = firstItem ? this.#flowKeyItemText(firstItem) : theme.fg("dim", "keys");
-			return [this.#fitToWidth(` ${firstSegment} ${theme.fg("dim", "· … ")}${theme.bold("/help")}`, width)];
-		}
-		return [...rows.slice(0, rowLimit - 1), ` ${theme.fg("dim", `… ${theme.bold("/help")} for more`)}`];
-	}
-
-	#flowKeyRowLimit(
-		targetContentRows: number | undefined,
-		changelogLineCount: number,
-		lspLineCount: number,
-		rightColumnWidth: number,
-	): number {
-		const preferredRows = this.#flowKeyRows(rightColumnWidth).length;
-		if (targetContentRows === undefined) return preferredRows;
-
-		const sessionBaselineRows = this.recentSessions.length === 0 ? 1 : Math.min(3, this.recentSessions.length);
-		const availableRows =
-			targetContentRows -
-			WELCOME_STATIC_RIGHT_ROWS_EXCLUDING_DYNAMIC_SECTIONS -
-			changelogLineCount -
-			lspLineCount -
-			sessionBaselineRows;
-		return Math.max(1, Math.min(preferredRows, availableRows));
-	}
-
-	#whatsNewRowLimit(targetContentRows: number | undefined, lspLineCount: number, flowLineCount: number): number {
-		if (targetContentRows === undefined) return 5;
-
-		const sessionBaselineRows = this.recentSessions.length === 0 ? 1 : Math.min(3, this.recentSessions.length);
-		const dynamicRows = Math.max(
-			1,
-			targetContentRows - WELCOME_STATIC_RIGHT_ROWS_EXCLUDING_DYNAMIC_SECTIONS - flowLineCount - lspLineCount,
-		);
-		const rowsAfterBaselineSessions = Math.max(1, dynamicRows - sessionBaselineRows);
-		const spareRows = Math.max(0, rowsAfterBaselineSessions - DEFAULT_WHATS_NEW_ROWS);
-		return Math.max(
-			1,
-			Math.min(MAX_WHATS_NEW_ROWS, rowsAfterBaselineSessions, DEFAULT_WHATS_NEW_ROWS + Math.floor(spareRows / 2)),
-		);
-	}
-
-	#sessionTrailLimit(
-		targetContentRows: number | undefined,
-		changelogLineCount: number,
-		lspLineCount: number,
-		flowLineCount: number,
-	): number {
-		if (this.recentSessions.length === 0) return 0;
-
-		const defaultLimit = Math.min(3, this.recentSessions.length);
-		if (targetContentRows === undefined) return defaultLimit;
-
-		const rowsWithDefaultTrail =
-			WELCOME_STATIC_RIGHT_ROWS_EXCLUDING_DYNAMIC_SECTIONS +
-			changelogLineCount +
-			flowLineCount +
-			lspLineCount +
-			defaultLimit;
-		const extraRows = Math.max(0, targetContentRows - rowsWithDefaultTrail);
-		return Math.min(this.recentSessions.length, defaultLimit + extraRows);
-	}
-
-	#sessionTrailLines(rightColumnWidth: number, limit: number): string[] {
-		if (this.recentSessions.length === 0) {
-			return [` ${theme.fg("dim", t("welcome.noSessions"))}`];
-		}
-
-		const bulletPrefix = ` ${theme.md.bullet} `;
-		const prefixWidth = visibleWidth(bulletPrefix);
-		const lines: string[] = [];
-		for (const session of this.recentSessions.slice(0, limit)) {
-			const timeSuffixRaw = ` (${session.timeAgo})`;
-			const timeWidth = visibleWidth(timeSuffixRaw);
-			const nameBudget = Math.max(1, rightColumnWidth - prefixWidth - timeWidth);
-			const nameVis = visibleWidth(session.name);
-			const name = nameVis > nameBudget ? truncateToWidth(session.name, nameBudget) : session.name;
-			lines.push(`${theme.fg("dim", bulletPrefix)}${theme.fg("muted", name)}${theme.fg("dim", timeSuffixRaw)}`);
-		}
-		return lines;
-	}
+	// ── Release note, sessions, keys ────────────────────────────────────────
 
-	#whatsNewLines(width: number, maxRows: number): string[] {
-		const rowLimit = Math.max(1, Math.floor(maxRows));
+	/** One line, only after an update: the new version, its first note, and a pointer to /changelog. */
+	#releaseNoteLine(width: number): string | undefined {
 		const changelog = this.options.changelogMarkdown?.trim();
-		if (!changelog) {
-			return [` ${theme.fg("dim", "Ready for your next prompt")}`];
-		}
-
+		if (!changelog) return undefined;
 		const version = this.#latestChangelogVersion(changelog);
-		if (this.options.collapseChangelog) {
-			return [
-				` ${theme.fg("muted", `Updated to v${version}`)}`,
-				` ${theme.fg("dim", `Use ${theme.bold("/changelog")} for details`)}`,
-			].slice(0, rowLimit);
-		}
-
-		const items = this.#changelogItems(changelog);
-		if (items.length === 0) {
-			return [
-				` ${theme.fg("muted", `Updated to v${version}`)}`,
-				` ${theme.fg("dim", `Use ${theme.bold("/changelog")} for details`)}`,
-			].slice(0, rowLimit);
-		}
+		const lead = theme.bold(theme.fg("accent", `v${version}`));
+		const pointer = theme.fg("dim", "/changelog");
+		const first = this.options.collapseChangelog ? undefined : this.#changelogItems(changelog)[0];
+		if (!first) return this.#spread(lead, pointer, width);
+		const room = width - visibleWidth(lead) - visibleWidth(pointer) - 4;
+		const body = room >= 12 ? `  ${theme.fg("muted", this.#truncate(first, room))}` : "";
+		return this.#spread(`${lead}${body}`, pointer, width);
+	}
 
-		const prefix = ` ${theme.md.bullet} `;
-		const textWidth = Math.max(1, width - visibleWidth(prefix));
-		const visibleItemCount = items.length > rowLimit ? Math.max(1, rowLimit - 1) : rowLimit;
-		const visibleItems = items.slice(0, visibleItemCount).map(item => {
-			const text = visibleWidth(item) > textWidth ? truncateToWidth(item, textWidth) : item;
-			return `${theme.fg("dim", prefix)}${theme.fg("muted", text)}`;
+	#sessionLines(width: number): string[] {
+		const heading = theme.bold(theme.fg("accent", t("welcome.sessionTrail")));
+		if (this.recentSessions.length === 0) return [heading, theme.fg("dim", t("welcome.noSessions"))];
+		const context = this.options.keyDisplayContext ?? { platform: process.platform };
+		const hints = [t("welcome.allSessions", { key: this.#resumeKey() })];
+		if (this.options.continueKey)
+			hints.unshift(t("welcome.continue", { key: formatKeyHint(this.options.continueKey, context) }));
+		const lines = [this.#spread(heading, theme.fg("dim", hints.join(" · ")), width)];
+		this.recentSessions.slice(0, SESSION_ROWS).forEach((session, index) => {
+			// The first row is the one the continue key resumes; mark it.
+			const lead = index === 0 && this.options.continueKey ? theme.fg("accent", "› ") : "  ";
+			const time = theme.fg("dim", session.timeAgo);
+			const nameWidth = Math.max(1, width - visibleWidth(lead) - visibleWidth(time) - 2);
+			const name = theme.fg(index === 0 ? "text" : "muted", this.#truncate(session.name, nameWidth));
+			lines.push(this.#spread(`${lead}${name}`, time, width));
 		});
-		if (items.length > visibleItems.length && visibleItems.length < rowLimit) {
-			visibleItems.push(` ${theme.fg("dim", `… ${theme.bold("/changelog")} for full notes`)}`);
-		}
-		return visibleItems;
+		return lines;
+	}
+
+	#keysLine(width: number): string {
+		const context = this.options.keyDisplayContext ?? { platform: process.platform };
+		const items: ReadonlyArray<{ key: string; label: MsgKey }> = [
+			{ key: "/", label: "welcome.commands" },
+			{ key: this.#resumeKey(), label: "welcome.sessions" },
+			{ key: formatKeyHint("ctrl+l", context), label: "welcome.model" },
+			{ key: "?", label: "welcome.keymap" },
+		];
+		const text = items
+			.map(item => `${theme.fg("text", item.key)} ${theme.fg("dim", t(item.label))}`)
+			.join(theme.fg("dim", "   "));
+		return this.#truncate(text, width);
+	}
+
+	#resumeKey(): string {
+		const context = this.options.keyDisplayContext ?? { platform: process.platform };
+		return this.options.resumeKey ? formatKeyHint(this.options.resumeKey, context) : "/resume";
 	}
 
 	#latestChangelogVersion(markdown: string): string {
-		const versionMatch = markdown.match(/##\s+\[?(\d+\.\d+\.\d+)\]?/);
-		return versionMatch?.[1] ?? this.version;
+		return markdown.match(/##\s+\[?(\d+\.\d+\.\d+)\]?/)?.[1] ?? this.version;
 	}
 
 	#changelogItems(markdown: string): string[] {
@@ -551,158 +358,84 @@ export class WelcomeComponent implements Component {
 				inFence = !inFence;
 				continue;
 			}
-			if (inFence || !line || /^#{1,6}\s+/.test(line) || /^-{3,}$/.test(line)) {
-				continue;
-			}
-			const withoutBullet = line
+			if (inFence || !line || /^#{1,6}\s+/.test(line) || /^-{3,}$/.test(line)) continue;
+			const cleaned = line
 				.replace(/^[-*]\s+/, "")
 				.replace(/^\d+\.\s+/, "")
-				.replace(/^>\s*/, "");
-			const cleaned = this.#stripMarkdown(withoutBullet);
+				.replace(/^>\s*/, "")
+				.replace(/`([^`]+)`/g, "$1")
+				.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+				.replace(/\*\*([^*]+)\*\*/g, "$1")
+				.replace(/__([^_]+)__/g, "$1")
+				.replace(/\*([^*]+)\*/g, "$1")
+				.replace(/[_~]/g, "")
+				.trim();
 			if (cleaned) items.push(cleaned);
 		}
 		return items;
 	}
 
-	#stripMarkdown(text: string): string {
-		return text
-			.replace(/`([^`]+)`/g, "$1")
-			.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
-			.replace(/\*\*([^*]+)\*\*/g, "$1")
-			.replace(/__([^_]+)__/g, "$1")
-			.replace(/\*([^*]+)\*/g, "$1")
-			.replace(/[_~]/g, "")
-			.trim();
+	// ── Intro ───────────────────────────────────────────────────────────────
+
+	/** Sections that have taken their colors; the rest are drawn in dim ink until the intro reaches them. */
+	#colorReveal(sectionCount: number): number {
+		if (this.#animStart == null) return sectionCount;
+		const elapsed = performance.now() - this.#animStart;
+		return Math.min(sectionCount, Math.floor((elapsed - SECTION_SETTLE_MS) / SECTION_STAGGER_MS) + 1);
 	}
 
-	#pill(icon: string, text: string, color: ThemeColor): string {
-		return `${theme.fg("borderMuted", "[")} ${theme.fg(color, icon)} ${theme.fg("muted", text)} ${theme.fg(
-			"borderMuted",
-			"]",
-		)}`;
+	#inkSection(lines: string[], order: number, colored: number): string[] {
+		return order < colored ? lines : lines.map(line => theme.fg("dim", Bun.stripANSI(line)));
 	}
 
-	/** Pick the logo frame for the current intro phase, or the resting frame. */
-	#currentLogoFrame(logoLines: readonly string[]): readonly string[] {
-		if (this.#animStart == null) return REST_FRAMES[this.logoMode];
-		const elapsed = performance.now() - this.#animStart;
-		if (elapsed >= INTRO_MS) return REST_FRAMES[this.logoMode];
-		// Ease-out cubic so the spin decelerates into the resting state.
-		const progress = elapsed / INTRO_MS;
-		const eased = 1 - (1 - progress) ** 3;
-		// Sweep backward through INTRO_SWEEPS full rotations so the gradient
-		// visibly spins multiple times. `eased == 1` → phase = 0 = resting frame.
-		const phase = ((((1 - eased) * INTRO_SWEEPS) % 1) + 1) % 1;
-		// Shine traverses the diagonal at a steady pace, decoupled from the
-		// gradient phase so the two layers parallax. Strength fades out with
-		// the same ease-out curve so the highlight is gone by the resting frame.
-		const shinePos = (((progress * INTRO_SHINE_TRAVERSALS) % 1) + 1) % 1;
-		const shineStrength = (1 - eased) ** 1.5;
-		return gradientLogo(logoLines, phase, { strength: shineStrength, pos: shinePos });
-	}
-
-	#logoLines(): readonly string[] {
-		return BRAND_LOGO;
+	// ── Layout helpers ──────────────────────────────────────────────────────
+
+	/** `left` and `right` on one row, `right` flush with the card's right edge. */
+	#spread(left: string, right: string, width: number): string {
+		const room = width - visibleWidth(left) - visibleWidth(right);
+		return room >= 2 ? `${left}${padding(room)}${right}` : this.#truncate(left, width);
 	}
-}
 
-// biome-ignore format: preserve ASCII art layout
-const BRAND_LOGO = [
-	"╔═╗╔═╗╦ ╦╦╔═╔╗╔╔═╗╦ ╦",
-	"╚═╗╠═╣╚╦╝╠╩╗║║║║ ║║║║",
-	"╚═╝╩ ╩ ╩ ╩ ╩╝╚╝╚═╝╚╩╝",
-];
-
-/** Multi-stop palette for the blue-octopus diagonal gradient. */
-const GRADIENT_STOPS: ReadonlyArray<readonly [number, number, number]> = [
-	[6, 19, 33], // deep navy
-	[11, 79, 138], // ocean
-	[47, 155, 255], // octopus mantle blue
-	[94, 200, 255], // bright tentacle blue
-	[168, 224, 255], // sky highlight
-];
-
-/** 256-color ramp fallback when truecolor isn't available. */
-const GRADIENT_RAMP_256 = [17, 18, 24, 31, 38, 75, 117];
-
-/** Half-width of the shine highlight band, expressed in gradient-t units. */
-const SHINE_HALF_WIDTH = 0.18;
-
-interface ShineConfig {
-	/** Overall opacity of the shine overlay, in [0, 1]. */
-	strength: number;
-	/** Center of the shine band along the diagonal, in [0, 1]. */
-	pos: number;
-}
-/**
- * Apply a multi-stop diagonal gradient (bottom-left → top-right) plus an
- * optional sliding shine band across multi-line art. `phase` (0..1) shifts the
- * gradient along the diagonal, wrapping at 1. When `shine` is provided, a soft
- * white highlight is composited on top, centered at `shine.pos`.
- */
-function gradientLogo(lines: readonly string[], phase = 0, shine?: ShineConfig): string[] {
-	const reset = "\x1b[0m";
-	const rows = lines.length;
-	const cols = Math.max(...lines.map(l => l.length));
-	// span+1 so `base` stays strictly < 1: avoids the wrap-around at the
-	// far corner mapping back to t=0 (hot pink) on the resting frame.
-	const span = Math.max(1, cols + rows - 1);
-	const shineStrength = shine && shine.strength > 0 ? shine.strength : 0;
-	const shinePos = shine ? shine.pos : 0;
-	const colorAt = TERMINAL.trueColor
-		? (t: number): string => {
-				// 5-stop palette widens the visible color range and avoids the
-				// deep-blue valley a naive HSL lerp falls into.
-				const stops = GRADIENT_STOPS;
-				const seg = t * (stops.length - 1);
-				const i = Math.min(stops.length - 2, Math.floor(seg));
-				const f = seg - i;
-				const a = stops[i];
-				const b = stops[i + 1];
-				let r = a[0] + (b[0] - a[0]) * f;
-				let g = a[1] + (b[1] - a[1]) * f;
-				let bl = a[2] + (b[2] - a[2]) * f;
-				if (shineStrength > 0) {
-					const dist = Math.abs(t - shinePos);
-					const intensity = Math.max(0, 1 - dist / SHINE_HALF_WIDTH) * shineStrength;
-					if (intensity > 0) {
-						r += (255 - r) * intensity;
-						g += (255 - g) * intensity;
-						bl += (255 - bl) * intensity;
-					}
-				}
-				return `\x1b[38;2;${Math.round(r)};${Math.round(g)};${Math.round(bl)}m`;
-			}
-		: (t: number): string => {
-				const ramp = GRADIENT_RAMP_256;
-				let idx = Math.min(ramp.length - 1, Math.max(0, Math.floor(t * (ramp.length - 1) + 0.5)));
-				if (shineStrength > 0) {
-					const dist = Math.abs(t - shinePos);
-					const intensity = Math.max(0, 1 - dist / SHINE_HALF_WIDTH) * shineStrength;
-					// Promote to the brightest ramp slot when the shine band peaks here.
-					if (intensity > 0.5) idx = ramp.length - 1;
-				}
-				return `\x1b[38;5;${ramp[idx]}m`;
-			};
-	return lines.map((line, y) => {
-		let result = "";
-		for (let x = 0; x < line.length; x++) {
-			const char = line[x];
-			if (char === " ") {
-				result += char;
-				continue;
-			}
-			// Diagonal: bottom-left (x=0, y=rows-1) → top-right (x=cols-1, y=0)
-			const base = (x + (rows - 1 - y)) / span;
-			const t = (((base + phase) % 1) + 1) % 1;
-			result += colorAt(t) + char + reset;
-		}
-		return result;
-	});
+	#truncate(text: string, width: number): string {
+		return visibleWidth(text) > width ? truncateToWidth(text, width) : text;
+	}
+
+	/** Keep the tail of a long path — the project directory is the part that identifies it. */
+	#shortenFromLeft(value: string, width: number): string {
+		if (visibleWidth(value) <= width) return value;
+		if (width <= 1) return "…";
+		let tail = value;
+		while (tail.length > 0 && visibleWidth(tail) > width - 1) tail = tail.slice(1);
+		return `…${tail}`;
+	}
+
+	/** Fit a string to exactly `width` columns (native ANSI/wide-glyph aware). */
+	#fit(str: string, width: number): string {
+		const visLen = visibleWidth(str);
+		if (visLen > width) return truncateToWidth(str, width, null, true);
+		return str + padding(width - visLen);
+	}
+
+	#rightGutterWidth(termWidth: number): number {
+		const configured = this.options.rightGutterWidth ?? 0;
+		if (!Number.isFinite(configured) || configured <= 0) return 0;
+		return Math.min(Math.floor(configured), Math.max(0, termWidth - 4));
+	}
+
+	#withRightGutter(lines: string[], rightGutterWidth: number): string[] {
+		if (rightGutterWidth <= 0) return lines;
+		const gutter = padding(rightGutterWidth);
+		return lines.map(line => line + gutter);
+	}
+
+	#targetRows(termWidth: number): number | undefined {
+		const viewportRows = this.options.getViewportRows?.();
+		if (typeof viewportRows !== "number" || !Number.isFinite(viewportRows) || viewportRows <= 0) return undefined;
+		const reservedRows = Math.max(0, Math.floor(this.options.getReservedBottomRows?.(termWidth) ?? 0));
+		return Math.max(0, Math.floor(viewportRows) - reservedRows);
+	}
 }
 
-/** Total length of the intro animation. */
-const INTRO_MS = 3000;
 /** Resolve the intro cadence without making tests mutate global process state. */
 export function resolveWelcomeIntroTickMs(
 	platform: NodeJS.Platform = process.platform,
@@ -713,14 +446,3 @@ export function resolveWelcomeIntroTickMs(
 
 /** Render at 30fps directly, but cap native Windows multiplexers at 10fps to avoid ConPTY output backpressure. */
 const INTRO_TICK_MS = resolveWelcomeIntroTickMs();
-/** Number of full gradient rotations the sweep performs before settling. */
-const INTRO_SWEEPS = 2.5;
-/** Number of times the shine highlight crosses the diagonal across the intro. */
-const INTRO_SHINE_TRAVERSALS = 3;
-
-/** Resting gradient frames, cached for re-renders outside of the intro. */
-const REST_FRAMES: Record<WelcomeLogoMode, readonly string[]> = {
-	unicode: gradientLogo(BRAND_LOGO, 0),
-	square: gradientLogo(BRAND_LOGO, 0),
-	ascii: gradientLogo(BRAND_LOGO, 0),
-};