newpr 0.1.0

package/src/llm/client.ts

@@ -0,0 +1,240 @@
+export interface LlmClientOptions {
+	api_key: string;
+	model: string;
+	timeout: number;
+}
+
+export interface LlmUsage {
+	prompt_tokens: number;
+	completion_tokens: number;
+	total_tokens: number;
+}
+
+export interface LlmResponse {
+	content: string;
+	model: string;
+	usage: LlmUsage;
+}
+
+export type StreamChunkCallback = (chunk: string, accumulated: string) => void;
+
+export interface LlmClient {
+	complete(systemPrompt: string, userPrompt: string): Promise<LlmResponse>;
+	completeStream(
+		systemPrompt: string,
+		userPrompt: string,
+		onChunk: StreamChunkCallback,
+	): Promise<LlmResponse>;
+}
+
+interface OpenRouterResponse {
+	choices: Array<{ message: { content: string } }>;
+	model: string;
+	usage?: { prompt_tokens?: number; completion_tokens?: number; total_tokens?: number };
+}
+
+interface OpenRouterStreamChunk {
+	choices: Array<{ delta: { content?: string }; finish_reason?: string | null }>;
+	model?: string;
+	usage?: { prompt_tokens?: number; completion_tokens?: number; total_tokens?: number };
+}
+
+const MAX_RETRIES = 10;
+const BASE_DELAY_MS = 1000;
+const MAX_DELAY_MS = 30_000;
+
+class NonRetriableError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "NonRetriableError";
+	}
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function buildRequestInit(
+	options: LlmClientOptions,
+	systemPrompt: string,
+	userPrompt: string,
+	stream: boolean,
+	signal: AbortSignal,
+): RequestInit {
+	return {
+		method: "POST",
+		signal,
+		headers: {
+			Authorization: `Bearer ${options.api_key}`,
+			"Content-Type": "application/json",
+			"HTTP-Referer": "https://github.com/sionic/newpr",
+			"X-Title": "newpr",
+		},
+		body: JSON.stringify({
+			model: options.model,
+			messages: [
+				{ role: "system", content: systemPrompt },
+				{ role: "user", content: userPrompt },
+			],
+			temperature: 0.1,
+			...(stream ? { stream: true } : {}),
+		}),
+	};
+}
+
+async function fetchWithRetry(
+	options: LlmClientOptions,
+	systemPrompt: string,
+	userPrompt: string,
+	stream: boolean,
+): Promise<Response> {
+	let lastError: Error | null = null;
+
+	for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+		if (attempt > 0) {
+			const delay = Math.min(BASE_DELAY_MS * 2 ** (attempt - 1), MAX_DELAY_MS);
+			await sleep(delay);
+		}
+
+		const controller = new AbortController();
+		const timeoutId = setTimeout(() => controller.abort(), options.timeout * 1000);
+
+		try {
+			const response = await fetch(
+				"https://openrouter.ai/api/v1/chat/completions",
+				buildRequestInit(options, systemPrompt, userPrompt, stream, controller.signal),
+			);
+
+			clearTimeout(timeoutId);
+
+			if (
+				response.status === 429 ||
+				response.status === 500 ||
+				response.status === 502 ||
+				response.status === 503
+			) {
+				lastError = new Error(
+					`OpenRouter ${response.status} (attempt ${attempt + 1}/${MAX_RETRIES + 1})`,
+				);
+				continue;
+			}
+
+			if (!response.ok) {
+				const body = await response.text();
+				throw new NonRetriableError(`OpenRouter API error ${response.status}: ${body}`);
+			}
+
+			return response;
+		} catch (error) {
+			clearTimeout(timeoutId);
+
+			if (error instanceof NonRetriableError) {
+				throw error;
+			}
+			if (error instanceof DOMException && error.name === "AbortError") {
+				throw new Error(`OpenRouter request timed out after ${options.timeout}s`);
+			}
+			lastError = error instanceof Error ? error : new Error(String(error));
+			if (attempt === MAX_RETRIES) break;
+		}
+	}
+
+	throw lastError ?? new Error("OpenRouter request failed after retries");
+}
+
+function parseUsage(
+	usage?: { prompt_tokens?: number; completion_tokens?: number; total_tokens?: number },
+): LlmUsage {
+	return {
+		prompt_tokens: usage?.prompt_tokens ?? 0,
+		completion_tokens: usage?.completion_tokens ?? 0,
+		total_tokens: usage?.total_tokens ?? 0,
+	};
+}
+
+async function readStream(
+	response: Response,
+	onChunk: StreamChunkCallback,
+): Promise<LlmResponse> {
+	const reader = response.body!.getReader();
+	const decoder = new TextDecoder();
+	let accumulated = "";
+	let model = "";
+	let usage: LlmUsage = { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 };
+	let buffer = "";
+
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+
+			buffer += decoder.decode(value, { stream: true });
+			const lines = buffer.split("\n");
+			buffer = lines.pop() ?? "";
+
+			for (const line of lines) {
+				const trimmed = line.trim();
+				if (!trimmed || trimmed === "data: [DONE]") continue;
+				if (!trimmed.startsWith("data: ")) continue;
+
+				try {
+					const chunk = JSON.parse(trimmed.slice(6)) as OpenRouterStreamChunk;
+					if (chunk.model) model = chunk.model;
+					if (chunk.usage) usage = parseUsage(chunk.usage);
+
+					const delta = chunk.choices[0]?.delta?.content;
+					if (delta) {
+						accumulated += delta;
+						onChunk(delta, accumulated);
+					}
+				} catch {
+					// skip malformed SSE chunks
+				}
+			}
+		}
+	} finally {
+		reader.releaseLock();
+	}
+
+	if (!accumulated) {
+		throw new NonRetriableError("OpenRouter returned empty streaming response");
+	}
+
+	return { content: accumulated, model, usage };
+}
+
+function createOpenRouterClient(options: LlmClientOptions): LlmClient {
+	return {
+		async complete(systemPrompt: string, userPrompt: string): Promise<LlmResponse> {
+			const response = await fetchWithRetry(options, systemPrompt, userPrompt, false);
+			const data = (await response.json()) as OpenRouterResponse;
+			const content = data.choices[0]?.message?.content;
+			if (!content) {
+				throw new NonRetriableError("OpenRouter returned empty response");
+			}
+			return {
+				content,
+				model: data.model,
+				usage: parseUsage(data.usage),
+			};
+		},
+
+		async completeStream(
+			systemPrompt: string,
+			userPrompt: string,
+			onChunk: StreamChunkCallback,
+		): Promise<LlmResponse> {
+			const response = await fetchWithRetry(options, systemPrompt, userPrompt, true);
+			return readStream(response, onChunk);
+		},
+	};
+}
+
+export function createLlmClient(options: LlmClientOptions): LlmClient {
+	if (options.api_key) {
+		return createOpenRouterClient(options);
+	}
+
+	const { createClaudeCodeClient: create } = require("./claude-code-client.ts");
+	return create(options.timeout);
+}

package/src/llm/prompts.ts

@@ -0,0 +1,176 @@
+import type { DiffChunk } from "../types/diff.ts";
+import type { FileGroup, FileStatus, PrSummary } from "../types/output.ts";
+import type { PrCommit } from "../types/github.ts";
+import type { ExplorationResult } from "../workspace/types.ts";
+
+export interface PromptPair {
+	system: string;
+	user: string;
+}
+
+export interface FileSummaryInput {
+	path: string;
+	summary: string;
+	status: FileStatus;
+}
+
+export interface PromptContext {
+	commits?: PrCommit[];
+	language?: string;
+}
+
+function langDirective(lang?: string): string {
+	if (!lang || lang === "English") return "";
+	return `\nCRITICAL LANGUAGE RULE: ALL text values in your response MUST be written in ${lang}. This includes every summary, description, name, purpose, scope, and impact field. JSON keys stay in English, but ALL string values MUST be in ${lang}. Do NOT use English for any descriptive text.`;
+}
+
+function formatCommitHistory(commits: PrCommit[]): string {
+	if (commits.length === 0) return "";
+	const lines = commits.map((c) => {
+		const firstLine = c.message.split("\n")[0]!;
+		const filesStr = c.files.length > 0 ? ` [${c.files.slice(0, 5).join(", ")}${c.files.length > 5 ? `, +${c.files.length - 5} more` : ""}]` : "";
+		return `- ${c.sha} ${firstLine}${filesStr}`;
+	});
+	return `\n\nCommit History (${commits.length} commits, chronological):\n${lines.join("\n")}`;
+}
+
+export function buildFileSummaryPrompt(chunks: DiffChunk[], ctx?: PromptContext): PromptPair {
+	const fileList = chunks
+		.map((c) => {
+			if (c.is_binary) return `File: ${c.file_path} (binary file, ${c.status})`;
+			return `File: ${c.file_path} (${c.status}, +${c.additions}/-${c.deletions})\n\`\`\`diff\n${c.diff_content}\n\`\`\``;
+		})
+		.join("\n\n---\n\n");
+
+	const commitCtx = ctx?.commits ? formatCommitHistory(ctx.commits) : "";
+
+	return {
+		system: `You are an expert code reviewer. Analyze the given diff and provide a 1-line summary for each changed file.
+Use the commit history to understand the intent behind each change — why the change was made, not just what changed.
+Respond ONLY with a JSON array. Each element: {"path": "file/path", "summary": "one line description of what changed"}.
+The "path" value must be the exact file path. The "summary" value is a human-readable description.
+No markdown, no explanation, just the JSON array.${langDirective(ctx?.language)}`,
+		user: `${fileList}${commitCtx}`,
+	};
+}
+
+export function buildGroupingPrompt(fileSummaries: FileSummaryInput[], ctx?: PromptContext): PromptPair {
+	const fileList = fileSummaries
+		.map((f) => `- ${f.path} (${f.status}): ${f.summary}`)
+		.join("\n");
+
+	const commitCtx = ctx?.commits ? formatCommitHistory(ctx.commits) : "";
+
+	return {
+		system: `You are an expert code reviewer. Group the following changed files by their semantic purpose.
+Each group should have a descriptive name, a type (one of: feature, refactor, bugfix, chore, docs, test, config), a description, and a list of file paths.
+A file MAY appear in multiple groups if it serves multiple purposes (e.g., index.ts re-exporting for both a feature and a refactor).
+Use the commit history to understand which changes belong together logically.
+Respond ONLY with a JSON array. Each element: {"name": "group name", "type": "feature|refactor|bugfix|chore|docs|test|config", "description": "what this group of changes does", "files": ["path1", "path2"]}.
+The "name" and "description" values are human-readable text. The "type" value must be one of the English keywords listed above. File paths stay as-is.
+Every file must appear in at least one group. No markdown, no explanation, just the JSON array.${langDirective(ctx?.language)}`,
+		user: `Changed files:\n${fileList}${commitCtx}`,
+	};
+}
+
+export function buildOverallSummaryPrompt(
+	prTitle: string,
+	groups: FileGroup[],
+	fileSummaries: Array<{ path: string; summary: string }>,
+	ctx?: PromptContext,
+): PromptPair {
+	const groupList = groups
+		.map((g) => `- [${g.type}] ${g.name}: ${g.description} (${g.files.length} files)`)
+		.join("\n");
+
+	const fileList = fileSummaries.map((f) => `- ${f.path}: ${f.summary}`).join("\n");
+	const commitCtx = ctx?.commits ? formatCommitHistory(ctx.commits) : "";
+
+	return {
+		system: `You are an expert code reviewer. Provide an overall summary of this Pull Request.
+Use the commit history to understand the development progression and intent.
+Respond ONLY with a JSON object: {"purpose": "why this PR exists (1-2 sentences)", "scope": "what areas of code are affected", "impact": "what is the impact of these changes", "risk_level": "low|medium|high"}.
+The "purpose", "scope", and "impact" values are human-readable text. The "risk_level" must be one of: low, medium, high (in English).
+No markdown, no explanation, just the JSON object.${langDirective(ctx?.language)}`,
+		user: `PR Title: ${prTitle}\n\nChange Groups:\n${groupList}\n\nFile Summaries:\n${fileList}${commitCtx}`,
+	};
+}
+
+export function buildNarrativePrompt(
+	prTitle: string,
+	summary: PrSummary,
+	groups: FileGroup[],
+	ctx?: PromptContext,
+): PromptPair {
+	const groupDetails = groups
+		.map((g) => `### ${g.name} (${g.type})\n${g.description}\nFiles: ${g.files.join(", ")}`)
+		.join("\n\n");
+
+	const commitCtx = ctx?.commits ? formatCommitHistory(ctx.commits) : "";
+	const lang = ctx?.language && ctx.language !== "English" ? ctx.language : null;
+
+	return {
+		system: `You are an expert code reviewer writing a review walkthrough for other developers.
+Write a clear, concise narrative that tells the "story" of this PR — what changes were made and in what logical order.
+Use the commit history to understand the development progression: which changes came first, how the PR evolved, and the intent behind each step.
+Use markdown formatting. Write 2-5 paragraphs. Do NOT use JSON. Write natural prose.
+${lang ? `CRITICAL: Write the ENTIRE narrative in ${lang}. Every sentence must be in ${lang}. Do NOT use English except for code identifiers, file paths, and [[group:...]]/[[file:...]] tokens.` : "If the PR title is in a non-English language, write the narrative in that same language."}
+
+IMPORTANT: When referencing a change group, wrap it as [[group:Group Name]]. When referencing a specific file, wrap it as [[file:path/to/file.ts]].
+Use the EXACT group names and file paths provided. Every group MUST be referenced at least once. Reference key files where relevant.
+Example: "The [[group:Auth Flow]] group introduces session management via [[file:src/auth/session.ts]] and [[file:src/auth/token.ts]]."`,
+		user: `PR Title: ${prTitle}\n\nSummary:\n- Purpose: ${summary.purpose}\n- Scope: ${summary.scope}\n- Impact: ${summary.impact}\n- Risk: ${summary.risk_level}\n\nChange Groups:\n${groupDetails}${commitCtx}`,
+	};
+}
+
+function formatCodebaseContext(exploration: ExplorationResult): string {
+	const sections: string[] = [];
+	if (exploration.project_structure) {
+		sections.push(`=== Project Structure ===\n${exploration.project_structure}`);
+	}
+	if (exploration.related_code) {
+		sections.push(`=== Related Code & Dependencies ===\n${exploration.related_code}`);
+	}
+	if (exploration.potential_issues) {
+		sections.push(`=== Potential Issues (from codebase analysis) ===\n${exploration.potential_issues}`);
+	}
+	return sections.join("\n\n");
+}
+
+export function buildEnrichedSummaryPrompt(
+	prTitle: string,
+	groups: FileGroup[],
+	fileSummaries: Array<{ path: string; summary: string }>,
+	exploration: ExplorationResult,
+	ctx?: PromptContext,
+): PromptPair {
+	const base = buildOverallSummaryPrompt(prTitle, groups, fileSummaries, ctx);
+	const context = formatCodebaseContext(exploration);
+
+	return {
+		system: base.system.replace(
+			"Provide an overall summary",
+			"Using the full codebase context below, provide a deeply informed summary",
+		),
+		user: `${base.user}\n\n--- CODEBASE CONTEXT (from agentic exploration) ---\n${context}`,
+	};
+}
+
+export function buildEnrichedNarrativePrompt(
+	prTitle: string,
+	summary: PrSummary,
+	groups: FileGroup[],
+	exploration: ExplorationResult,
+	ctx?: PromptContext,
+): PromptPair {
+	const base = buildNarrativePrompt(prTitle, summary, groups, ctx);
+	const context = formatCodebaseContext(exploration);
+
+	return {
+		system: `${base.system}
+You have access to full codebase analysis. Use it to explain HOW the changes relate to existing code, not just WHAT changed.
+Mention specific existing functions, modules, or patterns that are affected.
+Remember to use [[group:Name]] and [[file:path]] tokens as instructed.`,
+		user: `${base.user}\n\n--- CODEBASE CONTEXT (from agentic exploration) ---\n${context}`,
+	};
+}

package/src/llm/response-parser.ts

@@ -0,0 +1,71 @@
+import type { FileGroup, GroupType, PrSummary, RiskLevel } from "../types/output.ts";
+
+function extractJson(raw: string): string {
+	const codeBlockMatch = raw.match(/```(?:json)?\s*\n?([\s\S]*?)\n?\s*```/);
+	if (codeBlockMatch) return codeBlockMatch[1]!.trim();
+	return raw.trim();
+}
+
+const VALID_GROUP_TYPES = new Set<GroupType>([
+	"feature", "refactor", "bugfix", "chore", "docs", "test", "config",
+]);
+
+const VALID_RISK_LEVELS = new Set<RiskLevel>(["low", "medium", "high"]);
+
+export function parseFileSummaries(raw: string): Array<{ path: string; summary: string }> {
+	const jsonStr = extractJson(raw);
+	const parsed: unknown = JSON.parse(jsonStr);
+
+	if (!Array.isArray(parsed)) {
+		throw new Error("Expected JSON array for file summaries");
+	}
+
+	return parsed.map((item: Record<string, unknown>) => ({
+		path: String(item.path ?? ""),
+		summary: String(item.summary ?? "No summary available"),
+	}));
+}
+
+export function parseGroups(raw: string): FileGroup[] {
+	const jsonStr = extractJson(raw);
+	const parsed: unknown = JSON.parse(jsonStr);
+
+	if (!Array.isArray(parsed)) {
+		throw new Error("Expected JSON array for groups");
+	}
+
+	return parsed.map((item: Record<string, unknown>) => {
+		const rawType = String(item.type ?? "chore");
+		const type: GroupType = VALID_GROUP_TYPES.has(rawType as GroupType)
+			? (rawType as GroupType)
+			: "chore";
+
+		return {
+			name: String(item.name ?? "Ungrouped"),
+			type,
+			description: String(item.description ?? ""),
+			files: Array.isArray(item.files) ? item.files.map(String) : [],
+		};
+	});
+}
+
+export function parseSummary(raw: string): PrSummary {
+	const jsonStr = extractJson(raw);
+	const parsed = JSON.parse(jsonStr) as Record<string, unknown>;
+
+	const rawRisk = String(parsed.risk_level ?? "medium");
+	const risk_level: RiskLevel = VALID_RISK_LEVELS.has(rawRisk as RiskLevel)
+		? (rawRisk as RiskLevel)
+		: "medium";
+
+	return {
+		purpose: String(parsed.purpose ?? "No purpose provided"),
+		scope: String(parsed.scope ?? "Unknown scope"),
+		impact: String(parsed.impact ?? "Unknown impact"),
+		risk_level,
+	};
+}
+
+export function parseNarrative(raw: string): string {
+	return raw.trim();
+}

package/src/tui/App.tsx

@@ -0,0 +1,97 @@
+import { useState, useCallback } from "react";
+import { Box, useInput, useApp, useStdout } from "ink";
+import type { NewprOutput } from "../types/output.ts";
+import { Header } from "./Header.tsx";
+import { TabBar } from "./TabBar.tsx";
+import { Footer } from "./Footer.tsx";
+import { HelpOverlay } from "./HelpOverlay.tsx";
+import { StoryPanel } from "./panels/StoryPanel.tsx";
+import { WalkthroughPanel } from "./panels/WalkthroughPanel.tsx";
+import { SummaryPanel } from "./panels/SummaryPanel.tsx";
+import { GroupsPanel } from "./panels/GroupsPanel.tsx";
+import { FilesPanel } from "./panels/FilesPanel.tsx";
+import { NarrativePanel } from "./panels/NarrativePanel.tsx";
+
+const TAB_COUNT = 6;
+
+export function App({ data, onBack }: { data: NewprOutput; onBack?: () => void }) {
+	const { exit } = useApp();
+	const [activeTab, setActiveTab] = useState(0);
+	const [showHelp, setShowHelp] = useState(false);
+
+	const switchTab = useCallback(
+		(dir: number) => setActiveTab((t) => (t + dir + TAB_COUNT) % TAB_COUNT),
+		[],
+	);
+
+	useInput(
+		(input, key) => {
+			if (input === "q") {
+				if (onBack) {
+					onBack();
+				} else {
+					exit();
+				}
+				return;
+			}
+			if (key.escape && onBack) {
+				onBack();
+				return;
+			}
+			if (input === "?") {
+				setShowHelp((s) => !s);
+				return;
+			}
+			if (key.tab) {
+				switchTab(key.shift ? -1 : 1);
+				return;
+			}
+			if (input === "1") setActiveTab(0);
+			else if (input === "2") setActiveTab(1);
+			else if (input === "3") setActiveTab(2);
+			else if (input === "4") setActiveTab(3);
+			else if (input === "5") setActiveTab(4);
+			else if (input === "6") setActiveTab(5);
+		},
+		{ isActive: !showHelp },
+	);
+
+	if (showHelp) {
+		return (
+			<Box flexDirection="column">
+				<Header meta={data.meta} />
+				<HelpOverlay onClose={() => setShowHelp(false)} />
+			</Box>
+		);
+	}
+
+	const { stdout } = useStdout();
+	const termHeight = stdout?.rows ?? 24;
+	const panelHeight = Math.max(5, Math.floor(termHeight * 0.8) - 7);
+
+	return (
+		<Box flexDirection="column">
+			<Header meta={data.meta} />
+			<TabBar activeIndex={activeTab} />
+
+			<Box flexDirection="column" height={panelHeight} overflow="hidden">
+				{activeTab === 0 && (
+					<StoryPanel data={data} isFocused={activeTab === 0} viewportHeight={panelHeight} />
+				)}
+				{activeTab === 1 && (
+					<WalkthroughPanel data={data} isFocused={activeTab === 1} viewportHeight={panelHeight} />
+				)}
+				{activeTab === 2 && <SummaryPanel summary={data.summary} meta={data.meta} />}
+				{activeTab === 3 && (
+					<GroupsPanel groups={data.groups} files={data.files} isFocused={activeTab === 3} viewportHeight={panelHeight} />
+				)}
+				{activeTab === 4 && <FilesPanel files={data.files} isFocused={activeTab === 4} viewportHeight={panelHeight} />}
+				{activeTab === 5 && (
+					<NarrativePanel narrative={data.narrative} isFocused={activeTab === 5} viewportHeight={panelHeight} />
+				)}
+			</Box>
+
+			<Footer context={onBack ? "Esc/q: back" : undefined} />
+		</Box>
+	);
+}

package/src/tui/Footer.tsx

@@ -0,0 +1,34 @@
+import { Box, Text } from "ink";
+import { T } from "./theme.ts";
+
+function Key({ k }: { k: string }) {
+	return <Text color={T.primaryBold} bold>{k}</Text>;
+}
+
+function Sep() {
+	return <Text color={T.faint}>  │  </Text>;
+}
+
+export function Footer({ context }: { context?: string }) {
+	return (
+		<Box paddingX={1} borderStyle="single" borderColor={T.border} borderTop borderBottom={false} borderLeft={false} borderRight={false}>
+			<Key k="Tab/1-6" /><Text dimColor> panels</Text>
+			<Sep />
+			<Key k="↑↓/jk" /><Text dimColor> scroll</Text>
+			<Sep />
+			<Key k="]/[" /><Text dimColor> anchor</Text>
+			<Sep />
+			<Key k="Enter" /><Text dimColor> pin</Text>
+			<Sep />
+			<Key k="?" /><Text dimColor> help</Text>
+			<Sep />
+			<Key k="q" /><Text dimColor> quit</Text>
+			{context && (
+				<>
+					<Sep />
+					<Text color={T.accent}>{context}</Text>
+				</>
+			)}
+		</Box>
+	);
+}

package/src/tui/Header.tsx

@@ -0,0 +1,27 @@
+import { Box, Text } from "ink";
+import type { PrMeta } from "../types/output.ts";
+import { T } from "./theme.ts";
+
+export function Header({ meta }: { meta: PrMeta }) {
+	return (
+		<Box flexDirection="column" borderStyle="double" borderColor={T.primary} paddingX={1}>
+			<Box gap={1}>
+				<Text color={T.primary} bold>PR #{meta.pr_number}</Text>
+				<Text bold color={T.textBold}>{meta.pr_title}</Text>
+			</Box>
+			<Box gap={0}>
+				<Text color={T.muted}>{meta.author}</Text>
+				<Text dimColor> │ </Text>
+				<Text color={T.primary}>{meta.base_branch}</Text>
+				<Text color={T.faint}> ← </Text>
+				<Text color={T.primaryBold}>{meta.head_branch}</Text>
+				<Text dimColor> │ </Text>
+				<Text color={T.accent}>{meta.total_files_changed}</Text>
+				<Text dimColor> files │ </Text>
+				<Text color={T.added}>+{meta.total_additions}</Text>
+				<Text dimColor> </Text>
+				<Text color={T.deleted}>-{meta.total_deletions}</Text>
+			</Box>
+		</Box>
+	);
+}

package/src/tui/HelpOverlay.tsx

@@ -0,0 +1,46 @@
+import { Box, Text, useInput } from "ink";
+import { T } from "./theme.ts";
+
+const BINDINGS = [
+	["Tab / 1-6", "Switch panels"],
+	["↑ / k", "Move up / scroll up"],
+	["↓ / j", "Move down / scroll down"],
+	["] / [", "Next / prev anchor (Story)"],
+	["Enter", "Pin anchor / expand group"],
+	["← → / h l", "Prev / next step (Walk)"],
+	["/", "Filter files (Files panel)"],
+	["Esc", "Clear filter / close / back"],
+	["q", "Quit / go back"],
+	["?", "Toggle this help"],
+];
+
+export function HelpOverlay({ onClose }: { onClose: () => void }) {
+	useInput((input, key) => {
+		if (input === "?" || key.escape || input === "q") {
+			onClose();
+		}
+	});
+
+	return (
+		<Box
+			flexDirection="column"
+			borderStyle="round"
+			borderColor={T.primary}
+			paddingX={2}
+			paddingY={1}
+		>
+			<Text bold color={T.primary}> Keyboard Shortcuts </Text>
+			<Text> </Text>
+			{BINDINGS.map(([key, desc]) => (
+				<Box key={key} gap={1}>
+					<Box width={16}>
+						<Text bold color={T.primaryBold}>{key}</Text>
+					</Box>
+					<Text color={T.muted}>{desc}</Text>
+				</Box>
+			))}
+			<Text> </Text>
+			<Text dimColor>Press <Text color={T.primaryBold}>?</Text> or <Text color={T.primaryBold}>Esc</Text> to close</Text>
+		</Box>
+	);
+}