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

package/src/chat/user-message.ts

@@ -0,0 +1,287 @@
+import { applyBackgroundToLine, padding, visibleWidth } from "../utils";
+import { type Component, Container } from "../tui";
+import { Disclosure } from "../components/disclosure";
+import { Markdown } from "../components/markdown";
+import { formatBytes } from "@oh-my-pi/pi-utils";
+import { ensureThemeSync, getMarkdownTheme, theme } from "../theme";
+import {
+	attachmentSgr,
+	collapseImageMarkers,
+	COMPOSER_TOKEN_REGEX,
+	composerTokenRegex,
+	modelChipStyle,
+	modelMentionChipLabel,
+	renderPlaceholders,
+	skillChipStyle,
+} from "../prompt/composer-attachments";
+import { MODEL_MENTION_TAG_RE } from "../prompt/model-mention-syntax";
+import { fileHyperlink } from "../render";
+import { imageReferenceHyperlink } from "../prompt/image-references";
+import { highlightMagicKeywords } from "../prompt/magic-keywords";
+import type { ReactionTarget } from "./reaction";
+
+// OSC 133 shell integration: marks prompt zones for terminal multiplexers.
+//
+// The zone must be *closed* within the same render. `133;B` sets a sticky
+// cursor semantic of `.input` in Ghostty (and Ghostty-derived terminals such
+// as cmux) that only a command-start marker clears; leaving it latched makes
+// `cursorIsAtPrompt()` permanently true and tags every subsequently painted
+// cell as `.input`. Combined with `cursor-click-to-move = true` (Ghostty's
+// default) that turns every left-click inside the pane into a burst of
+// synthesized arrow keys on omp's pty, slamming the editor caret to column 0
+// (#8030, #6115).
+//
+// `133;C` is therefore emitted immediately followed by `133;D;0` at the end of
+// the bubble. That clears the input state without reintroducing the grouping
+// problem the marker was originally omitted to avoid: the command zone opens
+// and finishes inside this component, so later assistant/tool output can never
+// be grouped under the first submitted prompt.
+const OSC133_ZONE_START = "\x1b]133;A\x07";
+const OSC133_ZONE_END = "\x1b]133;B\x07";
+const OSC133_COMMAND_START = "\x1b]133;C\x07";
+const OSC133_COMMAND_DONE = "\x1b]133;D;0\x07";
+const OSC133_ZONE_CLOSE = OSC133_ZONE_END + OSC133_COMMAND_START + OSC133_COMMAND_DONE;
+
+/** How a user bubble styles its prose and chips (see {@link userBubbleColor}). */
+export interface UserBubbleOptions {
+	/** Materialized `file://` targets per attached image, indexed by chip number. */
+	imageLinks?: readonly (string | undefined)[];
+	/** Agent-attributed input: dim, flat prose. */
+	synthetic?: boolean;
+	/** SKILL.md path for a skill chip by name; `undefined` leaves the chip unlinked. */
+	skillPath?: (name: string) => string | undefined;
+}
+
+/**
+ * Foreground styling for prose inside a user bubble: the bubble text color with the
+ * magic-keyword glow, attachment chips in their composer identity color, and skill
+ * chips as soft pills (linked to their SKILL.md) — each token restoring the bubble's
+ * own foreground after it. Shared by {@link UserMessageComponent} and the skill
+ * callout so both read as one turn.
+ */
+export function userBubbleColor(
+	options: UserBubbleOptions = {},
+	tokenRegex: RegExp = COMPOSER_TOKEN_REGEX,
+): (value: string) => string {
+	const { imageLinks, synthetic = false, skillPath } = options;
+	// The Markdown component routes code spans and fenced blocks through its own code styling
+	// (never `color`), so those are already excluded; `highlightMagicKeywords` additionally
+	// restores the bubble's own foreground after each painted keyword so the gradient never
+	// bleeds into the rest of the line.
+	const keywordReset = theme.getFgOnBgAnsi("userMessageText", "userMessageBg");
+	const bubbleReset = `${keywordReset}${theme.getBgAnsi("userMessageBg")}`;
+	const renderText = synthetic
+		? (text: string) => theme.fg("dim", text)
+		: (text: string) => theme.fgOnBg("userMessageText", "userMessageBg", highlightMagicKeywords(text, keywordReset));
+	return (value: string) =>
+		renderPlaceholders(
+			value,
+			{
+				renderText,
+				renderSkill: (label, name) => {
+					const styled = skillChipStyle(label, bubbleReset);
+					const path = skillPath?.(name);
+					return path ? fileHyperlink(path, styled, { line: 1 }) : styled;
+				},
+				renderMention: label => modelChipStyle(label, bubbleReset),
+				renderReference: (label, kind, index, form) => {
+					// Chip tokens keep their composer identity color; the bubble's own
+					// foreground resumes after the token (same pattern as keywords).
+					const styled =
+						form === "chip"
+							? `${attachmentSgr(kind, index)}\x1b[1m${label}\x1b[22m${keywordReset}`
+							: theme.fg("accent", `\x1b[1m${label}\x1b[22m`);
+					return kind === "image" || kind === "video"
+						? imageReferenceHyperlink(label, index, imageLinks, () => styled)
+						: styled;
+				},
+			},
+			tokenRegex,
+		);
+}
+
+/**
+ * Component that renders a user message. Accepts an agent reaction badge
+ * (see {@link ReactionTarget}) drawn right-aligned in the bubble's top padding row.
+ */
+export class UserMessageComponent extends Container implements ReactionTarget {
+	// Memoized OSC 133 zone wrapping keyed on the underlying container render
+	// (same source ref ⇒ identical rows ⇒ reuse the wrapped copy). Keeps this
+	// component reference-stable for the transcript's incremental assembly and
+	// never mutates the container's cached array.
+	#zoneSource: readonly string[] | undefined;
+	#zoneLines: string[] | undefined;
+	readonly #bgColor: (value: string) => string;
+	#reaction: string | undefined;
+
+	constructor(text: string, options: UserBubbleOptions = {}) {
+		super();
+		ensureThemeSync();
+		// Display-only collapse: the stored/wire text carries bracketed `[Image #N, WxH]` markers,
+		// but the transcript shows the same compact `<icon> #N` chip the composer used. Runs before
+		// Markdown layout so wrapping and bubble padding are computed on the visible text.
+		text = collapseImageMarkers(text, Number.POSITIVE_INFINITY, () => {});
+		const mentionLabels: string[] = [];
+		MODEL_MENTION_TAG_RE.lastIndex = 0;
+		text = text.replace(MODEL_MENTION_TAG_RE, (_tag, _agent: string, name: string) => {
+			const label = modelMentionChipLabel(name);
+			mentionLabels.push(label);
+			return label;
+		});
+		const bgColor = (value: string) => theme.bg("userMessageBg", value);
+		this.#bgColor = bgColor;
+		const md = new Markdown(text, 1, 1, getMarkdownTheme(), {
+			bgColor,
+			color: userBubbleColor(options, composerTokenRegex(mentionLabels)),
+		});
+		md.setIgnoreTight(true);
+		this.addChild(md);
+	}
+
+	setReaction(emoji: string): void {
+		if (this.#reaction === emoji) return;
+		this.#reaction = emoji;
+		this.#zoneLines = undefined;
+	}
+
+	/** The top padding row with the reaction badge right-aligned inside the horizontal padding. */
+	#reactionRow(width: number): string {
+		const emoji = this.#reaction!;
+		return applyBackgroundToLine(padding(width - 1 - visibleWidth(emoji)) + emoji, width, this.#bgColor);
+	}
+
+	override render(width: number): readonly string[] {
+		const lines = super.render(width);
+		if (lines.length === 0) {
+			return lines;
+		}
+		if (this.#zoneSource === lines && this.#zoneLines !== undefined) {
+			return this.#zoneLines;
+		}
+		const wrapped = lines.slice();
+		if (this.#reaction !== undefined) wrapped[0] = this.#reactionRow(width);
+		wrapped[0] = OSC133_ZONE_START + wrapped[0];
+		wrapped[wrapped.length - 1] = wrapped[wrapped.length - 1] + OSC133_ZONE_CLOSE;
+		this.#zoneSource = lines;
+		this.#zoneLines = wrapped;
+		return wrapped;
+	}
+}
+
+/**
+ * Always-visible dim summary row for a collapsed synthetic input. Kept as a
+ * small domain renderer so the width-truncated label never pays Markdown
+ * layout; the heavy body lives in the {@link Disclosure} detail slot.
+ */
+class SyntheticSummary implements Component {
+	readonly #summary: string;
+	#cache: { width: number; lines: readonly string[] } | undefined;
+
+	constructor(summary: string) {
+		this.#summary = summary;
+	}
+
+	invalidate(): void {
+		this.#cache = undefined;
+	}
+
+	render(width: number): readonly string[] {
+		width = Math.max(1, width);
+		if (this.#cache?.width === width) return this.#cache.lines;
+		const hint = `${theme.sep.dot.trim()} ctrl+o`;
+		const lines = [` ${theme.fg("dim", truncateSummary(`${this.#summary} ${hint}`, Math.max(10, width - 1)))}`];
+		this.#cache = { width, lines };
+		return lines;
+	}
+}
+
+/**
+ * Collapsed placeholder for a synthetic (agent-attributed) user input in the
+ * file/remote-backed transcript viewer — chiefly the advisor's `Session update`
+ * replay dumps, which can each be hundreds of KiB of Markdown and, on cold open,
+ * blocked the TUI for tens of seconds while every historical body was laid out
+ * before the viewport clip (issue #6308).
+ *
+ * Collapsed by default: renders one dim summary row (label · size · line count ·
+ * expand hint) and builds NO Markdown. The heavy {@link UserMessageComponent} is
+ * constructed lazily only when expanded via `ctrl+o`, so blocks above the
+ * viewport never pay layout cost until the reader asks to see them. The raw
+ * observability data stays intact in `__advisor.jsonl`.
+ */
+export class CollapsedSyntheticMessageComponent implements Component {
+	#disclosure: Disclosure;
+
+	readonly #text: string;
+	readonly #imageLinks?: readonly (string | undefined)[];
+
+	constructor(text: string, imageLinks?: readonly (string | undefined)[]) {
+		this.#text = text;
+		this.#imageLinks = imageLinks;
+
+		// The heavy UserMessageComponent is constructed lazily only on the
+		// first expanded render and retained across collapse/re-expand cycles.
+		this.#disclosure = new Disclosure({
+			summary: new SyntheticSummary(summarizeSyntheticInput(text)),
+			body: () => new UserMessageComponent(this.#text, { synthetic: true, imageLinks: this.#imageLinks }),
+		});
+	}
+
+	/** ctrl+o toggle: reveal/hide the full Markdown body. */
+	setExpanded(expanded: boolean): void {
+		this.#disclosure.setExpanded(expanded);
+	}
+
+	setIgnoreTight(ignore: boolean): this {
+		this.#disclosure.setIgnoreTight(ignore);
+		return this;
+	}
+
+	invalidate(): void {
+		this.#disclosure.invalidate();
+	}
+
+	dispose(): void {
+		this.#disclosure.dispose();
+	}
+
+	render(width: number): readonly string[] {
+		return this.#disclosure.render(width);
+	}
+}
+
+/** Truncate a plain summary label to `maxWidth` display columns, appending `…`. */
+function truncateSummary(text: string, maxWidth: number): string {
+	if (Bun.stringWidth(text, { countAnsiEscapeCodes: false }) <= maxWidth) return text;
+	let out = "";
+	let w = 0;
+	for (const ch of text) {
+		const cw = Bun.stringWidth(ch, { countAnsiEscapeCodes: false });
+		if (w + cw > maxWidth - 1) break;
+		out += ch;
+		w += cw;
+	}
+	return `${out}…`;
+}
+
+/**
+ * One-line summary for a collapsed synthetic input: `<label> · <size> · <n>
+ * lines`. The label is the first Markdown heading's text (e.g. `Session
+ * update`), falling back to `Synthetic input` when the body opens with none.
+ */
+function summarizeSyntheticInput(text: string): string {
+	const size = formatBytes(Buffer.byteLength(text, "utf-8"));
+	const lineCount = text === "" ? 0 : text.split("\n").length;
+	const dot = theme.sep.dot.trim();
+	return `${syntheticInputLabel(text)} ${dot} ${size} ${dot} ${lineCount} line${lineCount === 1 ? "" : "s"}`;
+}
+
+/** First Markdown heading text in `text`, else `Synthetic input`. */
+function syntheticInputLabel(text: string): string {
+	for (const raw of text.split("\n")) {
+		const line = raw.trim();
+		if (!line) continue;
+		const heading = /^#{1,6}\s+(.*)$/.exec(line);
+		return heading ? heading[1]!.trim() || "Synthetic input" : "Synthetic input";
+	}
+	return "Synthetic input";
+}

package/src/chrome/chat-block.ts

@@ -0,0 +1,110 @@
+import { Container } from "../tui";
+/**
+ * Capabilities a mounted {@link ChatBlock} may use against its host transcript.
+ * Kept minimal so blocks never reach into the full TUI/InteractiveMode surface.
+ */
+export interface ChatBlockHost {
+	/** Schedule a repaint of the transcript. */
+	requestRender(): void;
+}
+
+/**
+ * Lifecycle-aware transcript block — the "return a block, let the host mount it"
+ * primitive, modelled on React/Svelte component lifecycles.
+ *
+ * Producers build and return a `ChatBlock` instead of poking `chatContainer` and
+ * `ui.requestRender()` directly. The host (`ctx.present`) appends it and calls
+ * {@link mount}, which runs {@link onMount}; effects started there register
+ * teardown via {@link onCleanup}. The block repaints through {@link requestRender}
+ * — never touching the TUI — and tears down exactly once on {@link finish}
+ * (self-complete: stop the animation, keep the final frame in the transcript) or
+ * {@link dispose} (host discards it, e.g. a transcript reset).
+ *
+ * While mounted and unfinished a block reports `isTranscriptBlockFinalized() ===
+ * false` so {@link "../components/transcript-container".TranscriptContainer}
+ * keeps it in the live, repaintable region on ED3-risk terminals; after
+ * `finish()`/`dispose()` it reports `true` and freezes at its final content.
+ */
+export abstract class ChatBlock extends Container {
+	#host: ChatBlockHost | undefined;
+	#cleanups: Array<() => void> = [];
+	#active = false;
+	#disposed = false;
+
+	/**
+	 * Run setup after the block is in the transcript: start timers/subscriptions
+	 * and register their teardown with {@link onCleanup}. Default: no-op (a block
+	 * whose content is fixed at construction needs no mount work).
+	 */
+	protected onMount(): void {}
+
+	/**
+	 * Register a teardown to run on {@link finish}/{@link dispose}, à la a
+	 * `useEffect` cleanup. If the block is already disposed the cleanup runs
+	 * immediately so callers never leak.
+	 */
+	protected onCleanup(cleanup: () => void): void {
+		if (this.#disposed) {
+			cleanup();
+			return;
+		}
+		this.#cleanups.push(cleanup);
+	}
+
+	/** Ask the host to repaint. No-op before mount or after dispose. */
+	protected requestRender(): void {
+		this.#host?.requestRender();
+	}
+
+	/** True between {@link mount} and {@link finish}/{@link dispose}. */
+	protected get active(): boolean {
+		return this.#active;
+	}
+
+	/**
+	 * Host-only: attach the host and run {@link onMount}. Idempotent — a second
+	 * call (e.g. a transcript rebuild that re-presents the same instance) is a
+	 * no-op.
+	 */
+	mount(host: ChatBlockHost): void {
+		if (this.#host || this.#disposed) return;
+		this.#host = host;
+		this.#active = true;
+		this.onMount();
+	}
+
+	/**
+	 * Self-complete: stop ongoing effects and freeze the block at its current
+	 * content, leaving it rendered in the transcript. Use when the operation the
+	 * block represents finishes (connection resolved, download done).
+	 */
+	finish(): void {
+		if (!this.#active) return;
+		this.#active = false;
+		this.#runCleanups();
+		this.requestRender();
+	}
+
+	/**
+	 * Host-only teardown: release everything and propagate to children. Called
+	 * when the host permanently discards the block (transcript reset). Idempotent.
+	 */
+	override dispose(): void {
+		if (this.#disposed) return;
+		this.#disposed = true;
+		this.#active = false;
+		this.#runCleanups();
+		super.dispose();
+		this.#host = undefined;
+	}
+
+	/** Live blocks stay repaintable; finished/disposed ones may freeze. */
+	isTranscriptBlockFinalized(): boolean {
+		return !this.#active;
+	}
+
+	#runCleanups(): void {
+		const cleanups = this.#cleanups.splice(0);
+		for (const cleanup of cleanups) cleanup();
+	}
+}

package/src/chrome/collab-qrcode.ts

@@ -0,0 +1,74 @@
+import type { Component } from "../tui";
+import { Ellipsis, truncateToWidth, visibleWidth } from "../utils";
+import type { AnimationFrame, TranscriptPresentationTarget } from "./transcript-container";
+import { fgOrPlain } from "../theme/theme";
+import { urlHyperlinkAlways } from "../render/index";
+import { QrCode, renderQrHalfBlocks } from "./qrcode";
+
+/** Scheme-less display form of a collab browser deep link, OSC-8 linked. */
+export function collabBrowserLink(webLink: string, label?: string): string {
+	const schemeLess = webLink.replace(/^https?:\/\//, "");
+	const display = fgOrPlain("accent", `\x1b[4m${label ?? schemeLess}\x1b[24m`);
+	const linked = urlHyperlinkAlways(webLink, display);
+	// Without OSC-8 support, keep the literal URL at the visible prefix.
+	return label !== undefined && linked === display ? fgOrPlain("accent", `\x1b[4m${schemeLess}\x1b[24m`) : linked;
+}
+
+/**
+ * One-shot transcript block that prints a collab browser-join URL as a
+ * scannable QR code. The symbol is encoded once at construction (byte mode,
+ * EC level M) and rendered as ANSI half-blocks; on terminals too narrow for
+ * the symbol it degrades to a one-line hint that includes the URL.
+ *
+ * The transcript viewport can also clip a live block to a single row under
+ * pressure (many short settled blocks — typical when thinking is a one-line
+ * summary rather than a tall trace). The QR's first/last rows are a white
+ * quiet zone, so a 1-row clip looks like an empty white line. When the
+ * allocated height cannot fit the full symbol, degrade to the same hint.
+ * The sibling `/collab` status heading can also collapse to its first row
+ * under that pressure, so the hint must carry the URL itself — "use the
+ * URL above" is not reachable.
+ */
+export class CollabQrCodeComponent implements Component, TranscriptPresentationTarget {
+	readonly #lines: readonly string[];
+	readonly #minWidth: number;
+	#allocatedRows = Number.POSITIVE_INFINITY;
+
+	constructor(readonly url: string) {
+		const rows = renderQrHalfBlocks(QrCode.encodeText(url, "M"));
+		this.#lines = rows.map(row => ` ${row}`);
+		this.#minWidth = rows.reduce((max, row) => Math.max(max, visibleWidth(row)), 0) + 1;
+	}
+
+	setTranscriptAllocation(rows: number, _frame?: AnimationFrame): void {
+		this.#allocatedRows = Number.isFinite(rows) ? Math.max(0, Math.trunc(rows)) : Number.POSITIVE_INFINITY;
+	}
+
+	render(width: number): readonly string[] {
+		if (width < this.#minWidth) {
+			return [this.#hiddenHint(`terminal width ${width}; need ${this.#minWidth}`, width)];
+		}
+		if (this.#allocatedRows < this.#lines.length) {
+			return [this.#hiddenHint(`viewport height ${this.#allocatedRows}; need ${this.#lines.length}`, width)];
+		}
+		return this.#lines;
+	}
+
+	/** Survives emergency 1-row transcript pressure when this block is otherwise hidden. */
+	renderTranscriptBlockEmergencyRow(width: number): string {
+		return this.#hiddenHint(
+			Number.isFinite(this.#allocatedRows)
+				? `viewport height ${this.#allocatedRows}; need ${this.#lines.length}`
+				: "transcript pressure",
+			width,
+		);
+	}
+
+	#hiddenHint(reason: string, width: number): string {
+		return truncateToWidth(
+			`${collabBrowserLink(this.url, "Join")} ${fgOrPlain("warning", `QR code hidden: ${reason}.`)}`,
+			width,
+			Ellipsis.Omit,
+		);
+	}
+}

package/src/chrome/context-thresholds.ts

@@ -0,0 +1,85 @@
+import { formatNumber } from "@oh-my-pi/pi-utils";
+import type { ThemeColor } from "../theme/index";
+export type ContextUsageLevel = "normal" | "warning" | "purple" | "error";
+
+const CONTEXT_WARNING_PERCENT_THRESHOLD = 50;
+const CONTEXT_WARNING_TOKEN_THRESHOLD = 150_000;
+const CONTEXT_PURPLE_PERCENT_THRESHOLD = 70;
+const CONTEXT_PURPLE_TOKEN_THRESHOLD = 270_000;
+const CONTEXT_ERROR_PERCENT_THRESHOLD = 90;
+const CONTEXT_ERROR_TOKEN_THRESHOLD = 500_000;
+
+function reachesThreshold(
+	contextPercent: number,
+	contextWindow: number,
+	percentThreshold: number,
+	tokenThreshold: number,
+): boolean {
+	if (!Number.isFinite(contextPercent) || contextPercent <= 0) {
+		return false;
+	}
+
+	if (!Number.isFinite(contextWindow) || contextWindow <= 0) {
+		return contextPercent >= percentThreshold;
+	}
+
+	const tokenPercentThreshold = (tokenThreshold / contextWindow) * 100;
+	return contextPercent >= Math.min(percentThreshold, tokenPercentThreshold);
+}
+
+export function getContextUsageLevel(contextPercent: number, contextWindow: number): ContextUsageLevel {
+	if (
+		reachesThreshold(contextPercent, contextWindow, CONTEXT_ERROR_PERCENT_THRESHOLD, CONTEXT_ERROR_TOKEN_THRESHOLD)
+	) {
+		return "error";
+	}
+
+	if (
+		reachesThreshold(contextPercent, contextWindow, CONTEXT_PURPLE_PERCENT_THRESHOLD, CONTEXT_PURPLE_TOKEN_THRESHOLD)
+	) {
+		return "purple";
+	}
+
+	if (
+		reachesThreshold(
+			contextPercent,
+			contextWindow,
+			CONTEXT_WARNING_PERCENT_THRESHOLD,
+			CONTEXT_WARNING_TOKEN_THRESHOLD,
+		)
+	) {
+		return "warning";
+	}
+
+	return "normal";
+}
+
+/**
+ * Format context usage as `<percent>%/<window>` when the model window is known.
+ * Unknown windows render as `<tokens>/?`, because `0.0%/0` suggests a real
+ * empty context instead of missing provider metadata.
+ */
+export function formatContextUsage(
+	contextPercent: number | null | undefined,
+	contextWindow: number,
+	usedTokens?: number,
+): string {
+	if (!Number.isFinite(contextWindow) || contextWindow <= 0) {
+		return `${formatNumber(usedTokens ?? 0)}/?`;
+	}
+	const pct = contextPercent === null || contextPercent === undefined ? "?" : `${contextPercent.toFixed(1)}%`;
+	return `${pct}/${formatNumber(contextWindow)}`;
+}
+
+export function getContextUsageThemeColor(level: ContextUsageLevel): ThemeColor {
+	switch (level) {
+		case "error":
+			return "error";
+		case "purple":
+			return "thinkingHigh";
+		case "warning":
+			return "warning";
+		case "normal":
+			return "statusLineContext";
+	}
+}

package/src/chrome/countdown-timer.ts

@@ -0,0 +1,74 @@
+/**
+ * Reusable countdown timer for dialog components.
+ */
+import type { TUI } from "../tui";
+export class CountdownTimer {
+	#intervalId: NodeJS.Timeout | undefined;
+	#expireTimeoutId: NodeJS.Timeout | undefined;
+	#remainingSeconds: number;
+	#deadlineMs = 0;
+	readonly #initialMs: number;
+
+	constructor(
+		timeoutMs: number,
+		private tui: TUI | undefined,
+		private onTick: (seconds: number) => void,
+		private onExpire: () => void,
+	) {
+		this.#initialMs = timeoutMs;
+		this.#remainingSeconds = Math.ceil(timeoutMs / 1000);
+		this.#start();
+	}
+
+	#calculateRemainingSeconds(now = Date.now()): number {
+		const remainingMs = Math.max(0, this.#deadlineMs - now);
+		return Math.ceil(remainingMs / 1000);
+	}
+
+	#start(): void {
+		const now = Date.now();
+		this.#deadlineMs = now + this.#initialMs;
+		this.#remainingSeconds = this.#calculateRemainingSeconds(now);
+		this.onTick(this.#remainingSeconds);
+		this.tui?.requestRender();
+
+		this.#expireTimeoutId = setTimeout(() => {
+			this.dispose();
+			this.onExpire();
+		}, this.#initialMs);
+
+		this.#startInterval();
+	}
+
+	#startInterval(): void {
+		if (this.#intervalId) {
+			clearInterval(this.#intervalId);
+			this.#intervalId = undefined;
+		}
+		this.#intervalId = setInterval(() => {
+			const remainingSeconds = this.#calculateRemainingSeconds();
+			if (remainingSeconds !== this.#remainingSeconds) {
+				this.#remainingSeconds = remainingSeconds;
+				this.onTick(this.#remainingSeconds);
+			}
+			this.tui?.requestRender();
+		}, 1000);
+	}
+
+	/** Reset the countdown to its initial value */
+	reset(): void {
+		this.dispose();
+		this.#start();
+	}
+
+	dispose(): void {
+		if (this.#intervalId) {
+			clearInterval(this.#intervalId);
+			this.#intervalId = undefined;
+		}
+		if (this.#expireTimeoutId) {
+			clearTimeout(this.#expireTimeoutId);
+			this.#expireTimeoutId = undefined;
+		}
+	}
+}