@oh-my-pi/pi-tui 18.2.3 → 18.2.5

package/src/overlays/btw-panel.ts

@@ -0,0 +1,167 @@
+import { type Component, Markdown, Text, type TUI } from "../index";
+import { replaceTabs } from "../render/render-utils";
+import { getMarkdownTheme, theme } from "../theme/theme";
+import { sanitizeErrorLine } from "../chrome/error-block";
+import { OverlayPanel } from "../chrome/overlay-box";
+import { StreamingPanelContent } from "../chrome/streaming-panel";
+
+type BtwPanelState = "running" | "complete" | "branching" | "aborted" | "error";
+
+interface BtwPanelComponentOptions {
+	question: string;
+	tui: TUI;
+	canBranch?: () => boolean;
+	canFollowUp?: () => boolean;
+}
+
+export class BtwPanelComponent extends OverlayPanel {
+	#tui: TUI;
+	#canBranch: (() => boolean) | undefined;
+	#canFollowUp: (() => boolean) | undefined;
+	#state: BtwPanelState = "running";
+	#answer = "";
+	#errorMessage: string | undefined;
+	#visibleAnswer = "";
+	#closed = false;
+	#copied = false;
+	#baseTitle: string;
+	readonly #content: StreamingPanelContent;
+
+	constructor(options: BtwPanelComponentOptions) {
+		const baseTitle = `/btw ${replaceTabs(options.question)}`;
+		super(baseTitle);
+		this.#baseTitle = baseTitle;
+		this.#tui = options.tui;
+		this.#canBranch = options.canBranch;
+		this.#canFollowUp = options.canFollowUp;
+		this.#content = new StreamingPanelContent(() => ({
+			sections: [this.#contentComponent()],
+			footer: () => this.#footerLine(),
+		}));
+		this.addChild(this.#content);
+		this.#rebuild();
+	}
+
+	appendText(delta: string): void {
+		if (!delta || this.#closed) return;
+		this.#answer += delta;
+		this.#visibleAnswer = replaceTabs(this.#answer).trim();
+		this.#setCopied(false);
+		this.#rebuild();
+	}
+
+	setAnswer(text: string): void {
+		if (this.#closed) return;
+		this.#answer = text;
+		this.#visibleAnswer = replaceTabs(text).trim();
+		this.#setCopied(false);
+		this.#rebuild();
+	}
+
+	markComplete(): void {
+		if (this.#closed) return;
+		this.#state = "complete";
+		this.#errorMessage = undefined;
+		this.#setCopied(false);
+		this.#rebuild();
+	}
+
+	/** Visual confirmation that `c` copied the answer to the clipboard. */
+	markCopied(): void {
+		if (this.#closed || !this.isCopyable()) return;
+		this.#setCopied(true);
+		this.#rebuild();
+	}
+
+	#setCopied(copied: boolean): void {
+		this.#copied = copied;
+		this.title = copied ? `${this.#baseTitle} ✓ Copied` : this.#baseTitle;
+	}
+
+	/** Shows that the completed answer is being promoted into the chat session. */
+	markBranching(): void {
+		if (this.#closed) return;
+		this.#state = "branching";
+		this.#errorMessage = undefined;
+		this.#setCopied(false);
+		this.#rebuild();
+	}
+
+	markAborted(): void {
+		if (this.#closed) return;
+		this.#state = "aborted";
+		this.#errorMessage = undefined;
+		this.#setCopied(false);
+		this.#rebuild();
+	}
+
+	markError(message: string): void {
+		if (this.#closed) return;
+		this.#state = "error";
+		this.#errorMessage = message;
+		this.#setCopied(false);
+		this.#rebuild();
+	}
+	isBranchable(): boolean {
+		return this.isCopyable();
+	}
+
+	isCopyable(): boolean {
+		return this.#state === "complete" && this.#visibleAnswer.length > 0;
+	}
+
+	getCopyText(): string | undefined {
+		if (!this.isCopyable()) return undefined;
+		return this.#visibleAnswer;
+	}
+
+	close(): void {
+		this.#closed = true;
+	}
+
+	#rebuild(): void {
+		this.#content.refresh();
+		// Component-scoped: a rebuild replaces only this panel's own children
+		// (streaming deltas arrive per token, and a full compose would re-walk
+		// the whole transcript each time). Before the panel is mounted the TUI
+		// cannot resolve it and falls back to a full compose on its own.
+		this.#tui.requestComponentRender(this);
+	}
+
+	#footerLine(): string {
+		switch (this.#state) {
+			case "running":
+				return theme.fg("muted", "Esc to cancel");
+			case "complete": {
+				const actions: string[] = [];
+				if (this.isCopyable()) actions.push(this.#copied ? "c to copy again" : "c to copy");
+				if (this.#canFollowUp?.()) actions.push("f to follow up");
+				if (this.#canBranch?.() ?? this.isBranchable()) actions.push("b to branch");
+				actions.push("Esc to close");
+				if (this.#copied) {
+					return `${theme.fg("success", "✓ Copied to clipboard")}${theme.fg("muted", actions.length > 0 ? ` · ${actions.join(" · ")}` : "")}`;
+				}
+				return theme.fg("muted", actions.join(" · "));
+			}
+			case "branching":
+				return theme.fg("muted", `${theme.status.pending} Branching to chat…`);
+			case "aborted":
+				return theme.fg("warning", `${theme.status.warning} Cancelled · Esc to close`);
+			case "error":
+				return theme.fg("error", `${theme.status.error} Error · Esc to close`);
+		}
+	}
+
+	#contentComponent(): Component {
+		if (this.#state === "error") {
+			return new Text(theme.fg("error", sanitizeErrorLine(this.#errorMessage ?? "Unknown error")), 0, 0);
+		}
+		const text = this.#visibleAnswer;
+		if (!text) {
+			const waiting =
+				this.#state === "running" ? `${theme.status.pending} Waiting for response…` : "No text returned.";
+			return new Text(theme.fg("dim", waiting), 0, 0);
+		}
+		return new Markdown(text, 0, 0, getMarkdownTheme());
+	}
+}

package/src/overlays/cleanse-panel.ts

@@ -0,0 +1,167 @@
+/** Anchored `/cleanse` overlay rendering the host's live board above the editor. */
+import { Text, type TUI } from "../index";
+import type { AgentProgress } from "../tools/task";
+import { replaceTabs } from "../render/render-utils";
+import { theme } from "../theme/theme";
+import { OverlayPanel } from "../chrome/overlay-box";
+import { StreamingPanelContent, type StreamingPanelPresentation } from "../chrome/streaming-panel";
+import type {
+	CleanseBoardModel,
+	CleanseCheckerDescriptor,
+	CleanseCheckResult,
+	CleanseAssignment,
+	CleanseAgentOutcome,
+} from "../apps/cleanse-board";
+
+const SPINNER_INTERVAL_MS = 80;
+const MAX_LOG_LINES = 14;
+
+export type CleansePanelRunStatus = "clean" | "unresolved" | "unsupported" | "cancelled";
+
+interface CleansePanelComponentOptions {
+	model: CleanseBoardModel;
+	/** Free-form request shown in the header; omitted for checker-discovery runs. */
+	request?: string;
+	tui: TUI;
+}
+
+/** Terminal state of the run, mirrored into the footer once the core settles. */
+type CleansePanelOutcome = CleansePanelRunStatus | "error";
+
+export class CleansePanelComponent extends OverlayPanel {
+	readonly interactive = true;
+
+	readonly #tui: TUI;
+	readonly #model: CleanseBoardModel;
+	readonly #logLines: string[] = [];
+	#outcome: CleansePanelOutcome | undefined;
+	#errorMessage: string | undefined;
+	#frame = 0;
+	#timer: NodeJS.Timeout | undefined;
+	#liveClosed = false;
+	readonly #content: StreamingPanelContent;
+
+	constructor(options: CleansePanelComponentOptions) {
+		super(options.request ? `/cleanse ${replaceTabs(options.request)}` : "/cleanse");
+		this.#tui = options.tui;
+		this.#model = options.model;
+		this.#content = new StreamingPanelContent(() => this.#presentation());
+		this.addChild(this.#content);
+		this.#timer = setInterval(() => {
+			this.#frame = (this.#frame + 1) % theme.getSpinnerFrames("activity").length;
+			this.#rebuild();
+		}, SPINNER_INTERVAL_MS);
+		this.#timer.unref?.();
+		this.#rebuild();
+	}
+
+	log(text: string): void {
+		this.#logLines.push(text);
+		if (this.#logLines.length > MAX_LOG_LINES) this.#logLines.splice(0, this.#logLines.length - MAX_LOG_LINES);
+		this.#rebuild();
+	}
+
+	/** Permanent line styled as a failure (the core's stderr-equivalent). */
+	logError(text: string): void {
+		this.log(theme.fg("error", text));
+	}
+
+	phase(text: string | undefined): void {
+		this.#model.phase(text);
+		this.#rebuild();
+	}
+
+	checkerStarted(checker: CleanseCheckerDescriptor): void {
+		this.#model.checkerStarted(checker);
+		this.#rebuild();
+	}
+
+	checkerFinished(check: CleanseCheckResult, durationMs: number): void {
+		this.log(this.#model.checkerFinished(check, durationMs));
+	}
+
+	repairFinished(): void {
+		this.#model.repairFinished();
+		this.#rebuild();
+	}
+
+	agentStarted(name: string, assignment: CleanseAssignment): void {
+		this.#model.agentStarted(name, assignment);
+		this.#rebuild();
+	}
+
+	agentProgress(name: string, progress: AgentProgress): void {
+		this.#model.agentProgress(name, progress);
+	}
+
+	agentFinished(outcome: CleanseAgentOutcome, assignment: CleanseAssignment): void {
+		this.log(this.#model.agentFinished(outcome, assignment));
+	}
+
+	/** Stop the live area; the panel stays mounted until the user dismisses it. */
+	close(): void {
+		this.#liveClosed = true;
+		this.#stopTimer();
+		this.#rebuild();
+	}
+
+	/** Record the settled run result and switch the footer to its dismiss hint. */
+	finish(status: CleansePanelRunStatus): void {
+		this.#outcome = status;
+		this.close();
+	}
+
+	/** Record an unexpected failure and switch the footer to its dismiss hint. */
+	markError(message: string): void {
+		this.#outcome = "error";
+		this.#errorMessage = message;
+		this.close();
+	}
+
+	/** Release the repaint timer during teardown. */
+	override dispose(): void {
+		this.#stopTimer();
+		super.dispose();
+	}
+
+	#stopTimer(): void {
+		if (!this.#timer) return;
+		clearInterval(this.#timer);
+		this.#timer = undefined;
+	}
+
+	#presentation(): StreamingPanelPresentation {
+		const frames = theme.getSpinnerFrames("activity");
+		const liveLines = this.#liveClosed ? [] : this.#model.renderLive(frames[this.#frame % frames.length]);
+		return {
+			sections: [
+				this.#logLines.length > 0 ? this.#logLines.map(line => new Text(replaceTabs(line), 0, 0)) : undefined,
+				liveLines.length > 0 ? liveLines.map(line => new Text(replaceTabs(line), 0, 0)) : undefined,
+				this.#errorMessage ? new Text(theme.fg("error", replaceTabs(this.#errorMessage)), 0, 0) : undefined,
+			],
+			footer: this.#footerLine(),
+		};
+	}
+
+	#rebuild(): void {
+		this.#content.refresh();
+		this.#tui.requestRender();
+	}
+
+	#footerLine(): string {
+		switch (this.#outcome) {
+			case undefined:
+				return theme.fg("muted", "Esc cancel /cleanse");
+			case "clean":
+				return theme.fg("success", `${theme.status.success} Clean · Esc dismiss`);
+			case "unresolved":
+				return theme.fg("warning", `${theme.status.warning} Diagnostics remain · Esc dismiss`);
+			case "unsupported":
+				return theme.fg("warning", `${theme.status.warning} No runnable checker · Esc dismiss`);
+			case "cancelled":
+				return theme.fg("warning", `${theme.status.warning} Cancelled · Esc dismiss`);
+			case "error":
+				return theme.fg("error", `${theme.status.error} Error · Esc dismiss`);
+		}
+	}
+}

package/src/overlays/codex-reset-fireworks.ts

@@ -0,0 +1,375 @@
+import {
+	type Component,
+	getSegmenter,
+	matchesKey,
+	type OverlayHandle,
+	type OverlayOptions,
+	truncateToWidth,
+	visibleWidth,
+} from "../index";
+import { type ThemeColor, theme } from "../theme/theme";
+
+const FRAME_INTERVAL_MS = 85;
+const FRAME_COUNT = 34;
+
+const FIREWORK_THEME_COLORS = {
+	cyan: "mdLink",
+	dim: "dim",
+	gold: "warning",
+	green: "success",
+	pink: "accent",
+	violet: "thinkingXhigh",
+	white: "text",
+} as const satisfies Record<string, ThemeColor>;
+
+type FireworkColor = keyof typeof FIREWORK_THEME_COLORS;
+
+/** The active Codex account fields retained between status refreshes. */
+export interface CodexResetUsageSnapshot {
+	/** When this usage report was observed, if supplied by the provider. */
+	observedAt?: number;
+	/** Weekly usage, its quota identity, and its previously scheduled reset deadline. */
+	sevenDay?: { percent: number; resetsAt?: number; tier?: string; plan?: string };
+	savedResets?: number;
+}
+
+/** A detected Codex quota event that can trigger the fireworks presentation. */
+export type CodexResetFireworksEvent =
+	| { kind: "unscheduled-weekly-reset" }
+	| { kind: "saved-reset-banked"; added: number; available: number };
+
+interface CanvasCell {
+	glyph: string;
+	color: FireworkColor;
+	priority: number;
+}
+
+interface FireworkBurst {
+	x: number;
+	y: number;
+	start: number;
+	color: FireworkColor;
+}
+
+interface ActiveFireworks {
+	component: CodexResetFireworksComponent;
+	overlay: OverlayHandle;
+}
+
+interface CodexResetFireworksHost {
+	ui: {
+		showOverlay(component: Component, options?: OverlayOptions): OverlayHandle;
+		setFocus(component: Component): void;
+		requestRender(): void;
+		readonly terminal: { readonly rows: number };
+	};
+}
+
+const BURSTS: readonly FireworkBurst[] = [
+	{ x: 0.17, y: 0.46, start: 5, color: "pink" },
+	{ x: 0.48, y: 0.2, start: 9, color: "cyan" },
+	{ x: 0.78, y: 0.42, start: 13, color: "gold" },
+	{ x: 0.31, y: 0.24, start: 17, color: "violet" },
+	{ x: 0.65, y: 0.28, start: 21, color: "green" },
+	{ x: 0.88, y: 0.18, start: 25, color: "pink" },
+];
+
+/**
+ * Compare consecutive reports for one Codex account. A saved-reset grant takes
+ * precedence when both changes arrive in the same report. A verified decrease,
+ * or a prior positive balance becoming unavailable, suppresses the weekly event
+ * because the user may have redeemed a credit. Other weekly usage drops are
+ * celebrated only when the provider advances the quota deadline before the
+ * previously scheduled reset.
+ */
+export function detectCodexResetFireworks(
+	previous: CodexResetUsageSnapshot,
+	current: CodexResetUsageSnapshot,
+): CodexResetFireworksEvent | undefined {
+	const previousSavedResets = previous.savedResets;
+	const currentSavedResets = current.savedResets;
+	if (previousSavedResets !== undefined) {
+		if (currentSavedResets === undefined) {
+			if (previousSavedResets > 0) return undefined;
+		} else {
+			if (currentSavedResets > previousSavedResets) {
+				return {
+					kind: "saved-reset-banked",
+					added: currentSavedResets - previousSavedResets,
+					available: currentSavedResets,
+				};
+			}
+			if (currentSavedResets < previousSavedResets) return undefined;
+		}
+	}
+
+	if (!previous.sevenDay || !current.sevenDay) return undefined;
+	if (previous.sevenDay.tier !== current.sevenDay.tier || previous.sevenDay.plan !== current.sevenDay.plan) {
+		return undefined;
+	}
+	const previousWeeklyPercent = Math.round(Math.max(0, Math.min(100, previous.sevenDay.percent)));
+	const currentWeeklyPercent = Math.round(Math.max(0, Math.min(100, current.sevenDay.percent)));
+	if (previousWeeklyPercent === 0 || currentWeeklyPercent >= previousWeeklyPercent) return undefined;
+
+	const scheduledResetAt = previous.sevenDay.resetsAt;
+	const nextResetAt = current.sevenDay.resetsAt;
+	if (
+		scheduledResetAt === undefined ||
+		!Number.isFinite(scheduledResetAt) ||
+		nextResetAt === undefined ||
+		!Number.isFinite(nextResetAt) ||
+		nextResetAt <= scheduledResetAt ||
+		typeof current.observedAt !== "number" ||
+		!Number.isFinite(current.observedAt) ||
+		current.observedAt >= scheduledResetAt
+	) {
+		return undefined;
+	}
+	return { kind: "unscheduled-weekly-reset" };
+}
+
+function setCell(
+	canvas: Array<Array<CanvasCell | undefined>>,
+	x: number,
+	y: number,
+	glyph: string,
+	color: FireworkColor,
+	priority: number,
+): void {
+	const row = canvas[y];
+	if (!row || x < 0 || x >= row.length) return;
+	const current = row[x];
+	if (!current || priority >= current.priority) row[x] = { glyph, color, priority };
+}
+
+function drawText(
+	canvas: Array<Array<CanvasCell | undefined>>,
+	x: number,
+	y: number,
+	text: string,
+	color: FireworkColor,
+	priority: number,
+): void {
+	let column = x;
+	for (const { segment } of getSegmenter().segment(text)) {
+		const width = visibleWidth(segment);
+		if (width <= 0) continue;
+		setCell(canvas, column, y, segment, color, priority);
+		for (let continuation = 1; continuation < width; continuation++) {
+			setCell(canvas, column + continuation, y, "", color, priority);
+		}
+		column += width;
+	}
+}
+
+function drawBanner(
+	canvas: Array<Array<CanvasCell | undefined>>,
+	left: number,
+	artWidth: number,
+	height: number,
+	event: CodexResetFireworksEvent,
+): void {
+	if (height < 3 || artWidth < 8) return;
+	const panelWidth = Math.min(62, artWidth);
+	const panelLeft = left + Math.floor((artWidth - panelWidth) / 2);
+	const top = height - 3;
+	const innerWidth = panelWidth - 2;
+	const titleText =
+		event.kind === "unscheduled-weekly-reset" ? " O P E N A I   R E S E T " : " S A V E D   R E S E T ";
+	const subtitleText =
+		event.kind === "unscheduled-weekly-reset"
+			? "Weekly usage cleared early · ESC to return"
+			: event.added === 1
+				? `New reset banked · ${event.available} available · ESC to return`
+				: `${event.added} resets banked · ${event.available} available · ESC to return`;
+	const title = truncateToWidth(titleText, innerWidth, "");
+	const subtitle = truncateToWidth(subtitleText, innerWidth, "");
+	const titleOffset = Math.floor((innerWidth - visibleWidth(title)) / 2);
+	const subtitleOffset = Math.floor((innerWidth - visibleWidth(subtitle)) / 2);
+
+	drawText(canvas, panelLeft, top, `╭${"─".repeat(innerWidth)}╮`, "violet", 20);
+	drawText(canvas, panelLeft + 1 + titleOffset, top, title, "gold", 21);
+	drawText(canvas, panelLeft, top + 1, `│${" ".repeat(innerWidth)}│`, "violet", 20);
+	drawText(canvas, panelLeft + 1 + subtitleOffset, top + 1, subtitle, "cyan", 21);
+	drawText(canvas, panelLeft, top + 2, `╰${"─".repeat(innerWidth)}╯`, "violet", 20);
+}
+
+function drawStars(
+	canvas: Array<Array<CanvasCell | undefined>>,
+	left: number,
+	artWidth: number,
+	skyHeight: number,
+	frame: number,
+): void {
+	if (skyHeight <= 0) return;
+	const count = Math.min(26, Math.max(5, Math.floor(artWidth / 3)));
+	for (let index = 0; index < count; index++) {
+		const x = left + ((index * 37 + 11) % artWidth);
+		const y = (index * 7 + 2) % skyHeight;
+		const bright = (index + Math.floor(frame / 3)) % 5 === 0;
+		setCell(canvas, x, y, bright ? "+" : ".", bright ? "white" : "dim", bright ? 2 : 1);
+	}
+}
+
+function drawBurst(
+	canvas: Array<Array<CanvasCell | undefined>>,
+	burst: FireworkBurst,
+	left: number,
+	artWidth: number,
+	skyHeight: number,
+	frame: number,
+): void {
+	if (skyHeight <= 1) return;
+	const centerX = left + Math.round((artWidth - 1) * burst.x);
+	const centerY = Math.max(0, Math.min(skyHeight - 2, Math.round((skyHeight - 1) * burst.y)));
+	const age = frame - burst.start;
+
+	if (age >= -6 && age < 0) {
+		const progress = (age + 6) / 6;
+		const y = skyHeight - 1 - Math.round(progress * (skyHeight - 1 - centerY));
+		setCell(canvas, centerX, y, "^", "white", 8);
+		setCell(canvas, centerX, y + 1, "|", burst.color, 7);
+		setCell(canvas, centerX, y + 2, ".", "gold", 6);
+		return;
+	}
+	if (age < 0 || age > 8) return;
+
+	const radius = age === 0 ? 0 : 0.8 + age * 0.92;
+	const gravity = Math.floor((age * age) / 22);
+	const glyphs = ["@", "*", "*", "+", "o", "o", ".", ".", "."] as const;
+	const particleColor: FireworkColor = age <= 5 ? burst.color : age <= 7 ? "gold" : "dim";
+
+	for (let particle = 0; particle < 20; particle++) {
+		const angle = (particle / 20) * Math.PI * 2 + burst.start * 0.17;
+		const x = centerX + Math.round(Math.cos(angle) * radius * 1.75);
+		const y = centerY + Math.round(Math.sin(angle) * radius * 0.58 + gravity);
+		setCell(canvas, x, y, glyphs[age], particleColor, 10);
+		if (age >= 2 && age <= 6) {
+			const trailRadius = Math.max(0, radius - 1.4);
+			const trailX = centerX + Math.round(Math.cos(angle) * trailRadius * 1.75);
+			const trailY = centerY + Math.round(Math.sin(angle) * trailRadius * 0.58 + gravity);
+			setCell(canvas, trailX, trailY, ".", "dim", 5);
+		}
+	}
+	if (age <= 2) setCell(canvas, centerX, centerY, age === 0 ? "@" : "+", "white", 12);
+}
+
+function renderCanvas(canvas: Array<Array<CanvasCell | undefined>>): string[] {
+	return canvas.map(row => {
+		let output = "";
+		let run = "";
+		let runColor: FireworkColor | undefined;
+		for (const cell of row) {
+			if (cell && cell.color !== runColor) {
+				if (run) output += runColor ? theme.fg(FIREWORK_THEME_COLORS[runColor], run) : run;
+				run = "";
+				runColor = cell.color;
+			}
+			run += cell?.glyph ?? " ";
+		}
+		if (run) output += runColor ? theme.fg(FIREWORK_THEME_COLORS[runColor], run) : run;
+		return output;
+	});
+}
+
+/** Render one deterministic animation frame for the top-third overlay. */
+function renderCodexResetFireworks(
+	width: number,
+	height: number,
+	frame: number,
+	event: CodexResetFireworksEvent,
+): string[] {
+	const safeWidth = Math.max(1, Math.floor(width));
+	const safeHeight = Math.max(1, Math.floor(height));
+	const artWidth = Math.min(96, safeWidth);
+	const left = Math.floor((safeWidth - artWidth) / 2);
+	const skyHeight = Math.max(0, safeHeight - 3);
+	// oxlint-disable-next-line unicorn/no-new-array -- length preallocation
+	const canvas = Array.from({ length: safeHeight }, () => new Array<CanvasCell | undefined>(safeWidth));
+
+	drawStars(canvas, left, artWidth, skyHeight, frame);
+	for (const burst of BURSTS) drawBurst(canvas, burst, left, artWidth, skyHeight, frame);
+	drawBanner(canvas, left, artWidth, safeHeight, event);
+	return renderCanvas(canvas);
+}
+
+class CodexResetFireworksComponent implements Component {
+	#timer: NodeJS.Timeout | undefined;
+	#done = Promise.withResolvers<void>();
+	#frame = 0;
+	#disposed = false;
+
+	constructor(
+		readonly host: CodexResetFireworksHost,
+		readonly event: CodexResetFireworksEvent,
+	) {}
+
+	run(): Promise<void> {
+		this.#timer ??= setInterval(() => {
+			if (this.#disposed) return;
+			this.#frame = (this.#frame + 1) % FRAME_COUNT;
+			this.host.ui.requestRender();
+		}, FRAME_INTERVAL_MS);
+		this.host.ui.requestRender();
+		return this.#done.promise;
+	}
+
+	dispose(): void {
+		if (this.#disposed) return;
+		this.#disposed = true;
+		if (this.#timer) {
+			clearInterval(this.#timer);
+			this.#timer = undefined;
+		}
+		this.#done.resolve();
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "escape") || matchesKey(data, "esc")) this.#done.resolve();
+	}
+
+	render(width: number): readonly string[] {
+		const height = Math.max(1, Math.floor(this.host.ui.terminal.rows * 0.33));
+		return renderCodexResetFireworks(width, height, this.#frame, this.event);
+	}
+}
+
+/** Owns the at-most-one modal celebration lifecycle for an interactive session. */
+export class CodexResetFireworksController {
+	#active: ActiveFireworks | undefined;
+
+	constructor(private readonly host: CodexResetFireworksHost) {}
+
+	/** Present a celebration unless another one already owns the modal overlay. */
+	show(event: CodexResetFireworksEvent): boolean {
+		if (this.#active) return false;
+		const component = new CodexResetFireworksComponent(this.host, event);
+		const overlay = this.host.ui.showOverlay(component, {
+			anchor: "top-center",
+			width: "100%",
+			maxHeight: "33%",
+			margin: 0,
+		});
+		this.#active = { component, overlay };
+		this.host.ui.setFocus(component);
+		void component.run().then(() => this.#finish(component));
+		return true;
+	}
+
+	/** Stop the active celebration and release its overlay, if present. */
+	dispose(): void {
+		const active = this.#active;
+		if (!active) return;
+		this.#active = undefined;
+		active.component.dispose();
+		active.overlay.hide();
+	}
+
+	#finish(component: CodexResetFireworksComponent): void {
+		const active = this.#active;
+		if (!active || active.component !== component) return;
+		this.#active = undefined;
+		component.dispose();
+		active.overlay.hide();
+	}
+}