@buyi1net/pi-toolkit 0.0.1

package/modules/tui/status/session-status.ts

@@ -0,0 +1,325 @@
+import type {
+	ContextUsage,
+	ExtensionContext,
+	Theme,
+} from "@earendil-works/pi-coding-agent";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { resolveGlyphs, type IconGlyphs } from "../renderer/icons.ts";
+import { sanitizeSingleLine } from "./project-status.ts";
+import {
+	cacheHitStatusColor,
+	compactionStatusColor,
+	contextUsageStatusColor,
+	turnStatusColor,
+	type StatusSegment,
+} from "./status-segments.ts";
+
+const SEPARATOR = " · ";
+const DEFAULT_GLYPHS = resolveGlyphs("unicode");
+
+export type SessionStatusSegmentId = "session" | "tokens" | "cache" | "cost";
+export type EditorUsageSegmentId = "tokens" | "cache" | "context";
+
+export interface SessionStatusSnapshot {
+	sessionId: string;
+	sessionName?: string;
+	inputTokens: number;
+	outputTokens: number;
+	cacheReadTokens: number;
+	cacheWriteTokens: number;
+	/** 最新 assistant 消息的缓存命中率，口径与 Pi 原生 Footer 一致。 */
+	cacheHitPercent?: number;
+	cost: number;
+	turns: number;
+	compactions: number;
+}
+
+interface UsageValue {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: { total: number };
+}
+
+export interface StatusLineSegment {
+	id: string;
+	text: string;
+	compactText?: string;
+	priority: number;
+}
+
+interface RenderState {
+	segment: StatusLineSegment;
+	text: string;
+	compacted: boolean;
+	hidden: boolean;
+}
+
+function safeAmount(value: number): number {
+	return Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+function addUsage(snapshot: SessionStatusSnapshot, usage: UsageValue): void {
+	snapshot.inputTokens += safeAmount(usage.input);
+	snapshot.outputTokens += safeAmount(usage.output);
+	snapshot.cacheReadTokens += safeAmount(usage.cacheRead);
+	snapshot.cacheWriteTokens += safeAmount(usage.cacheWrite);
+	snapshot.cost += safeAmount(usage.cost.total);
+}
+
+export function collectSessionStatus(
+	sessionManager: ExtensionContext["sessionManager"],
+): SessionStatusSnapshot {
+	const entries = sessionManager.getEntries();
+	const branchEntries = sessionManager.getBranch?.() ?? entries;
+	const snapshot: SessionStatusSnapshot = {
+		sessionId: sanitizeSingleLine(sessionManager.getSessionId()),
+		sessionName: sanitizeSingleLine(sessionManager.getSessionName() ?? "") || undefined,
+		inputTokens: 0,
+		outputTokens: 0,
+		cacheReadTokens: 0,
+		cacheWriteTokens: 0,
+		cost: 0,
+		turns: branchEntries.filter((entry) => entry.type === "message" && entry.message.role === "user").length,
+		compactions: branchEntries.filter((entry) => entry.type === "compaction").length,
+	};
+
+	// 命中率只取最新 assistant 请求，口径与 Pi 原生 Footer 一致；
+	// toolResult / compaction 的 usage 不参与 CH。
+	let latestCacheHitPercent: number | undefined;
+
+	for (const entry of entries) {
+		let usage: UsageValue | undefined;
+		if (entry.type === "message" && entry.message.role === "assistant") {
+			usage = entry.message.usage as UsageValue | undefined;
+			if (usage) {
+				const promptTokens = safeAmount(usage.input) + safeAmount(usage.cacheRead) + safeAmount(usage.cacheWrite);
+				latestCacheHitPercent = promptTokens > 0
+					? (safeAmount(usage.cacheRead) / promptTokens) * 100
+					: undefined;
+			}
+		} else if (entry.type === "message" && entry.message.role === "toolResult" && entry.message.usage) {
+			usage = entry.message.usage as UsageValue;
+		} else if ((entry.type === "compaction" || entry.type === "branch_summary") && entry.usage) {
+			usage = entry.usage as UsageValue;
+		}
+		if (usage) addUsage(snapshot, usage);
+	}
+	snapshot.cacheHitPercent = latestCacheHitPercent;
+
+	return snapshot;
+}
+
+export function formatTokenCount(count: number): string {
+	if (count < 1_000) return String(count);
+	if (count < 10_000) return `${(count / 1_000).toFixed(1)}k`;
+	if (count < 1_000_000) return `${Math.round(count / 1_000)}k`;
+	if (count < 10_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
+	return `${Math.round(count / 1_000_000)}M`;
+}
+
+function formatContextTokenCount(count: number): string {
+	if (count < 1_000) return String(count);
+	if (count < 1_000_000) return `${(count / 1_000).toFixed(1).replace(/\.0$/, "")}k`;
+	if (count < 1_000_000_000) return `${(count / 1_000_000).toFixed(1).replace(/\.0$/, "")}M`;
+	return `${(count / 1_000_000_000).toFixed(1).replace(/\.0$/, "")}B`;
+}
+
+function formatContextUsageTokenCount(count: number): string {
+	return safeAmount(count) === 0 ? "0k" : formatContextTokenCount(count);
+}
+
+function formatCacheHitPercent(percent: number | undefined): string {
+	const safePercent = Number.isFinite(percent) && percent !== undefined && percent >= 0
+		? percent
+		: 0;
+	return safePercent.toFixed(1).replace(/\.0$/, "");
+}
+
+export function buildEditorUsageSegments(
+	snapshot: SessionStatusSnapshot,
+	contextUsage: ContextUsage | undefined,
+	contextWindowFallback: number | undefined,
+	theme: Theme,
+	glyphs: IconGlyphs,
+	segments: readonly EditorUsageSegmentId[],
+	autoCompactionEnabled = false,
+): StatusSegment[] {
+	// 统计组一体：↑↓ R 默认灰色，只有全局缓存命中率 CH 保留档位色
+	const statsParts = [
+		theme.fg("muted", `${glyphs.inputTokens}${formatTokenCount(safeAmount(snapshot.inputTokens))}`),
+		theme.fg("muted", `${glyphs.outputTokens}${formatTokenCount(safeAmount(snapshot.outputTokens))}`),
+		theme.fg("muted", `R${safeAmount(snapshot.cacheReadTokens) > 0 ? formatTokenCount(snapshot.cacheReadTokens) : "0k"}`),
+	];
+	const cacheHit = theme.fg(
+		cacheHitStatusColor(snapshot.cacheHitPercent),
+		`CH${formatCacheHitPercent(snapshot.cacheHitPercent)}%`,
+	);
+	const statsSeparator = theme.fg("muted", " · ");
+	const statsText = `${statsParts.join(" ")}${statsSeparator}${cacheHit}`;
+	const statsCompact = `${statsParts[2]!}${statsSeparator}${cacheHit}`;
+	const contextWindow = contextUsage?.contextWindow ?? contextWindowFallback;
+	const contextTokens = contextUsage?.tokens ?? 0;
+	const contextValue = contextWindow
+		? `${formatContextUsageTokenCount(contextTokens)}/${formatContextTokenCount(contextWindow)}`
+		: `${formatContextUsageTokenCount(contextTokens)}/?`;
+	const contextText = `${glyphs.context} ${contextValue}`;
+	const stats = {
+		id: "tokens",
+		text: statsText,
+		compactText: statsCompact,
+		priority: 4,
+	};
+	const byId: Readonly<Record<EditorUsageSegmentId, StatusSegment>> = {
+		// tokens 与 cache 已合并为统计组，两个段 id 任一启用即显示
+		tokens: stats,
+		cache: stats,
+		context: {
+			id: "context",
+			text: theme.fg(contextUsageStatusColor(contextUsage?.percent), contextText),
+			priority: 0,
+			required: true,
+		},
+	};
+	const showConversationCounts = segments.includes("tokens")
+		|| segments.includes("cache")
+		|| snapshot.turns > 0
+		|| snapshot.compactions > 0;
+	const turnStatus: StatusSegment = {
+		id: "turns",
+		text: snapshot.turns > 0 ? theme.fg(turnStatusColor(snapshot.turns), `${glyphs.turns} T${snapshot.turns}`) : "",
+		priority: 6,
+	};
+	const compactionStatus: StatusSegment = {
+		id: "compactions",
+		text: theme.fg(
+			compactionStatusColor(snapshot.compactions),
+			`${glyphs.compaction} ${autoCompactionEnabled ? "Auto" : "Off"}${snapshot.compactions > 0 ? `（C${snapshot.compactions}）` : ""}`,
+		),
+		priority: 5,
+	};
+	const seen = new Set<string>();
+	return segments.flatMap((segment) => {
+		const status = byId[segment];
+		if (!status.text || seen.has(status.id)) return [];
+		seen.add(status.id);
+		if (segment !== "context") return [status];
+		const extras: StatusSegment[] = [compactionStatus];
+		const ordered = showConversationCounts
+			? [turnStatus, status, ...extras]
+			: [status, ...extras];
+		return ordered.filter((extra) => extra.text);
+	});
+}
+
+function buildSegments(
+	snapshot: SessionStatusSnapshot,
+	theme: Theme,
+	glyphs: IconGlyphs,
+): Readonly<Record<SessionStatusSegmentId, StatusLineSegment>> {
+	const sessionLabel = snapshot.sessionName ?? snapshot.sessionId.slice(0, 8);
+	const input = snapshot.inputTokens > 0
+		? theme.fg("text", `${glyphs.inputTokens} ${formatTokenCount(snapshot.inputTokens)}`)
+		: "";
+	const compactInput = snapshot.inputTokens > 0
+		? theme.fg("text", `${glyphs.inputTokens}${formatTokenCount(snapshot.inputTokens)}`)
+		: "";
+	const output = snapshot.outputTokens > 0
+		? theme.fg("success", `${glyphs.outputTokens} ${formatTokenCount(snapshot.outputTokens)}`)
+		: "";
+	const compactOutput = snapshot.outputTokens > 0
+		? theme.fg("success", `${glyphs.outputTokens}${formatTokenCount(snapshot.outputTokens)}`)
+		: "";
+	const cacheParts = [
+		snapshot.cacheReadTokens > 0 ? `R${formatTokenCount(snapshot.cacheReadTokens)}` : "",
+		snapshot.cacheWriteTokens > 0 ? `W${formatTokenCount(snapshot.cacheWriteTokens)}` : "",
+		snapshot.cacheHitPercent !== undefined
+			? `CH${snapshot.cacheHitPercent.toFixed(1)}%`
+			: "",
+	].filter(Boolean);
+	const compactCache = snapshot.cacheHitPercent !== undefined
+		? `${Math.round(snapshot.cacheHitPercent)}%`
+		: formatTokenCount(snapshot.cacheReadTokens + snapshot.cacheWriteTokens);
+	const costValue = `$${snapshot.cost.toFixed(3)}`;
+	const costText = glyphs.cost === "$" ? costValue : `${glyphs.cost} ${costValue}`;
+
+	return {
+		session: {
+			id: "session",
+			text: sessionLabel ? theme.fg("accent", `${glyphs.session} ${sessionLabel}`) : "",
+			compactText: sessionLabel ? theme.fg("accent", `${glyphs.session}${sessionLabel}`) : "",
+			priority: 4,
+		},
+		tokens: {
+			id: "tokens",
+			text: [input, output].filter(Boolean).join(" "),
+			compactText: [compactInput, compactOutput].filter(Boolean).join(" "),
+			priority: 1,
+		},
+		cache: {
+			id: "cache",
+			text: cacheParts.length > 0
+				? theme.fg("muted", `${glyphs.cache} ${cacheParts.join(" ")}`)
+				: "",
+			compactText: cacheParts.length > 0
+				? theme.fg("muted", `${glyphs.cache}${compactCache}`)
+				: "",
+			priority: 3,
+		},
+		cost: {
+			id: "cost",
+			text: snapshot.cost > 0 ? theme.fg("warning", costText) : "",
+			priority: 2,
+		},
+	};
+}
+
+function renderStates(states: readonly RenderState[], separator: string): string {
+	return states.filter((state) => !state.hidden && state.text).map((state) => state.text).join(separator);
+}
+
+export function renderStatusLineSegments(
+	segments: readonly StatusLineSegment[],
+	width: number,
+	separator = SEPARATOR,
+): string {
+	if (width <= 0) return "";
+	const states: RenderState[] = segments.map((segment) => ({
+		segment,
+		text: segment.text,
+		compacted: false,
+		hidden: !segment.text,
+	}));
+	let line = renderStates(states, separator);
+
+	while (visibleWidth(line) > width) {
+		const state = states
+			.filter((candidate) => !candidate.hidden)
+			.sort((left, right) => right.segment.priority - left.segment.priority)[0];
+		if (!state) return "";
+		const compact = state.segment.compactText;
+		if (!state.compacted && compact && compact !== state.text) {
+			state.text = compact;
+			state.compacted = true;
+		} else {
+			state.hidden = true;
+		}
+		line = renderStates(states, separator);
+	}
+
+	return line;
+}
+
+export function renderSessionStatusLine(
+	snapshot: SessionStatusSnapshot,
+	width: number,
+	theme: Theme,
+	glyphs: IconGlyphs = DEFAULT_GLYPHS,
+	segments: readonly SessionStatusSegmentId[] = ["tokens", "cost"],
+	extraSegments: readonly StatusLineSegment[] = [],
+): string {
+	const byId = buildSegments(snapshot, theme, glyphs);
+	const ordered = [...new Set(segments)].map((segment) => byId[segment]);
+	return renderStatusLineSegments([...ordered, ...extraSegments], width);
+}

package/modules/tui/status/status-config.ts

@@ -0,0 +1,95 @@
+import type { ProjectStatusSegmentId } from "./project-status.ts";
+import type { EditorUsageSegmentId } from "./session-status.ts";
+
+export type StatusPresetName = "minimal" | "default" | "full";
+export type EditorLeftSegmentId = "provider" | "model" | "thinking" | "balance" | "subscription" | "duration";
+export type FooterExtraSegmentId = "extensions";
+export type StatusSegmentId =
+	| EditorLeftSegmentId
+	| EditorUsageSegmentId
+	| ProjectStatusSegmentId
+	| FooterExtraSegmentId;
+
+export interface ResolvedStatusSettings {
+	preset: StatusPresetName;
+	editorLeft: EditorLeftSegmentId[];
+	footerUsage: EditorUsageSegmentId[];
+	footerPrimary: ProjectStatusSegmentId[];
+	footerExtra: FooterExtraSegmentId[];
+}
+
+export interface StatusSettingsOverride {
+	preset?: StatusPresetName;
+	segments?: readonly StatusSegmentId[] | null;
+}
+
+const PRESET_SEGMENTS: Readonly<Record<StatusPresetName, readonly StatusSegmentId[]>> = {
+	minimal: ["model", "context", "project", "git"],
+	default: ["provider", "model", "thinking", "balance", "subscription", "tokens", "cache", "context", "project", "git", "duration", "extensions"],
+	full: ["provider", "model", "thinking", "balance", "subscription", "tokens", "cache", "context", "project", "git", "duration", "runtime", "extensions"],
+};
+
+const VALID_PRESETS = new Set<StatusPresetName>(["minimal", "default", "full"]);
+const VALID_SEGMENTS = new Set<StatusSegmentId>(PRESET_SEGMENTS.full);
+const EDITOR_LEFT = new Set<StatusSegmentId>(["provider", "model", "thinking", "balance", "subscription", "duration"]);
+const FOOTER_USAGE = new Set<StatusSegmentId>(["tokens", "cache", "context"]);
+const FOOTER_PRIMARY = new Set<StatusSegmentId>(["project", "git", "runtime"]);
+const FOOTER_EXTRA = new Set<StatusSegmentId>(["extensions"]);
+
+export const STATUS_PRESET_NAMES: readonly StatusPresetName[] = ["minimal", "default", "full"];
+export const STATUS_SEGMENT_IDS: readonly StatusSegmentId[] = PRESET_SEGMENTS.full;
+
+export function statusPresetSegments(preset: StatusPresetName): StatusSegmentId[] {
+	return [...PRESET_SEGMENTS[preset]];
+}
+
+export function readStatusPreset(
+	env: Readonly<Record<string, string | undefined>> = process.env,
+): StatusPresetName {
+	const candidate = env.PI_UI_STATUS_PRESET?.trim().toLowerCase() as StatusPresetName | undefined;
+	return candidate && VALID_PRESETS.has(candidate) ? candidate : "default";
+}
+
+function readSegmentOrder(
+	preset: StatusPresetName,
+	env: Readonly<Record<string, string | undefined>>,
+): StatusSegmentId[] {
+	const raw = env.PI_UI_STATUS_SEGMENTS?.trim();
+	if (!raw) return [...PRESET_SEGMENTS[preset]];
+
+	const seen = new Set<StatusSegmentId>();
+	for (const token of raw.split(",")) {
+		const segment = token.trim().toLowerCase() as StatusSegmentId;
+		if (VALID_SEGMENTS.has(segment)) seen.add(segment);
+	}
+	return seen.size > 0 ? [...seen] : [...PRESET_SEGMENTS[preset]];
+}
+
+function normalizeSegmentOrder(segments: readonly StatusSegmentId[]): StatusSegmentId[] {
+	const seen = new Set<StatusSegmentId>();
+	for (const segment of segments) {
+		if (VALID_SEGMENTS.has(segment)) seen.add(segment);
+	}
+	return [...seen];
+}
+
+export function resolveStatusSettings(
+	env: Readonly<Record<string, string | undefined>> = process.env,
+	override: StatusSettingsOverride = {},
+): ResolvedStatusSettings {
+	const preset = env.PI_UI_STATUS_PRESET?.trim()
+		? readStatusPreset(env)
+		: override.preset ?? "default";
+	const segments = env.PI_UI_STATUS_SEGMENTS?.trim()
+		? readSegmentOrder(preset, env)
+		: override.segments === undefined || override.segments === null
+			? statusPresetSegments(preset)
+			: normalizeSegmentOrder(override.segments);
+	return {
+		preset,
+		editorLeft: segments.filter((segment): segment is EditorLeftSegmentId => EDITOR_LEFT.has(segment)),
+		footerUsage: segments.filter((segment): segment is EditorUsageSegmentId => FOOTER_USAGE.has(segment)),
+		footerPrimary: segments.filter((segment): segment is ProjectStatusSegmentId => FOOTER_PRIMARY.has(segment)),
+		footerExtra: segments.filter((segment): segment is FooterExtraSegmentId => FOOTER_EXTRA.has(segment)),
+	};
+}

package/modules/tui/status/status-segments.ts

@@ -0,0 +1,263 @@
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+const SEGMENT_SEPARATOR = " · ";
+const EDITOR_STATUS_CHROME_WIDTH = 11;
+
+export interface StatusSegment {
+	readonly id: string;
+	readonly text: string;
+	readonly compactText?: string;
+	/** 数值越大越早压缩或隐藏。 */
+	readonly priority: number;
+	readonly required?: boolean;
+}
+
+export interface EditorStatusLayout {
+	left: string;
+	right: string;
+}
+
+interface SegmentState {
+	readonly segment: StatusSegment;
+	readonly side: "left" | "right";
+	readonly order: number;
+	text: string;
+	compacted: boolean;
+	hidden: boolean;
+}
+
+function renderSide(states: readonly SegmentState[], side: SegmentState["side"]): string {
+	return states
+		.filter((state) => state.side === side && !state.hidden && state.text)
+		.map((state) => state.text)
+		.join(side === "right" ? " " : SEGMENT_SEPARATOR);
+}
+
+function layoutWidth(layout: EditorStatusLayout): number {
+	const gap = layout.left && layout.right ? 1 : 0;
+	return visibleWidth(layout.left) + visibleWidth(layout.right) + gap;
+}
+
+function renderLayout(states: readonly SegmentState[]): EditorStatusLayout {
+	return {
+		left: renderSide(states, "left"),
+		right: renderSide(states, "right"),
+	};
+}
+
+function nextReduction(states: readonly SegmentState[]): SegmentState | undefined {
+	return states
+		.filter((state) => {
+			if (state.hidden) return false;
+			const compact = state.segment.compactText;
+			return (!state.compacted && compact !== undefined && compact !== state.text) || !state.segment.required;
+		})
+		.sort((left, right) =>
+			right.segment.priority - left.segment.priority || left.order - right.order,
+		)[0];
+}
+
+function reduceState(state: SegmentState): void {
+	const compact = state.segment.compactText;
+	if (!state.compacted && compact !== undefined && compact !== state.text) {
+		state.text = compact;
+		state.compacted = true;
+		return;
+	}
+	state.hidden = true;
+}
+
+function truncateRequiredLayout(layout: EditorStatusLayout, budget: number): EditorStatusLayout {
+	if (budget <= 0) return { left: "", right: "" };
+	if (!layout.left) return { left: "", right: truncateToWidth(layout.right, budget, "") };
+	if (!layout.right) return { left: truncateToWidth(layout.left, budget, "…"), right: "" };
+
+	const rightBudget = Math.min(visibleWidth(layout.right), Math.max(1, Math.floor(budget * 0.4)));
+	const right = truncateToWidth(layout.right, rightBudget, "");
+	const leftBudget = Math.max(0, budget - visibleWidth(right) - 1);
+	return {
+		left: truncateToWidth(layout.left, leftBudget, "…"),
+		right,
+	};
+}
+
+export function layoutEditorStatus(
+	left: readonly StatusSegment[],
+	right: readonly StatusSegment[],
+	terminalWidth: number,
+): EditorStatusLayout {
+	const budget = Math.max(0, terminalWidth - EDITOR_STATUS_CHROME_WIDTH);
+	const states: SegmentState[] = [
+		...left.map((segment, order) => ({
+			segment,
+			side: "left" as const,
+			order,
+			text: segment.text,
+			compacted: false,
+			hidden: !segment.text,
+		})),
+		...right.map((segment, order) => ({
+			segment,
+			side: "right" as const,
+			order: left.length + order,
+			text: segment.text,
+			compacted: false,
+			hidden: !segment.text,
+		})),
+	];
+
+	let layout = renderLayout(states);
+	while (layoutWidth(layout) > budget) {
+		const candidate = nextReduction(states);
+		if (!candidate) break;
+		reduceState(candidate);
+		layout = renderLayout(states);
+	}
+
+	return layoutWidth(layout) <= budget ? layout : truncateRequiredLayout(layout, budget);
+}
+
+export type TurnTimerState = "idle" | "working" | "done";
+
+const THINKING_COLORS: Readonly<Record<string, ThemeColor>> = {
+	off: "thinkingOff",
+	minimal: "thinkingMinimal",
+	low: "thinkingLow",
+	medium: "thinkingMedium",
+	high: "thinkingHigh",
+	xhigh: "thinkingXhigh",
+	max: "thinkingMax",
+};
+
+export function thinkingStatusColor(level: string | undefined): ThemeColor {
+	return THINKING_COLORS[level ?? "off"] ?? "thinkingOff";
+}
+
+export function cacheHitStatusColor(percent: number | null | undefined): ThemeColor {
+	if (percent === null || percent === undefined || !Number.isFinite(percent) || percent < 0) return "muted";
+	if (percent < 30) return "error";
+	if (percent < 70) return "warning";
+	if (percent < 90) return "accent";
+	return "success";
+}
+
+export function contextUsageStatusColor(percent: number | null | undefined): ThemeColor {
+	if (percent === null || percent === undefined || !Number.isFinite(percent) || percent <= 0) return "muted";
+	if (percent <= 10) return "success";
+	if (percent <= 30) return "accent";
+	if (percent <= 60) return "warning";
+	return "error";
+}
+
+export function turnStatusColor(turns: number): ThemeColor {
+	if (!Number.isFinite(turns) || turns <= 10) return "muted";
+	if (turns <= 20) return "success";
+	if (turns < 40) return "warning";
+	return "error";
+}
+
+export function compactionStatusColor(compactions: number): ThemeColor {
+	if (!Number.isFinite(compactions) || compactions <= 0) return "muted";
+	if (compactions === 1) return "success";
+	if (compactions === 2) return "accent";
+	if (compactions === 3) return "warning";
+	return "error";
+}
+
+export function durationStatusColor(state: TurnTimerState): ThemeColor {
+	if (state === "working") return "accent";
+	if (state === "done") return "success";
+	return "dim";
+}
+
+export interface TurnTimerSnapshot {
+	state: TurnTimerState;
+	elapsedMs: number;
+}
+
+export function formatElapsed(elapsedMs: number): string {
+	const totalSeconds = Math.max(0, Math.floor(elapsedMs / 1000));
+	const seconds = totalSeconds % 60;
+	const totalMinutes = Math.floor(totalSeconds / 60);
+	if (totalMinutes < 1) return `${seconds}s`;
+	const minutes = totalMinutes % 60;
+	const hours = Math.floor(totalMinutes / 60);
+	if (hours > 0) return `${hours}h ${String(minutes).padStart(2, "0")}m`;
+	return `${minutes}m ${String(seconds).padStart(2, "0")}s`;
+}
+
+export class TurnTimerController {
+	private readonly requestRender: () => void;
+	private readonly intervalMs: number;
+	private readonly now: () => number;
+	private startedAt: number | undefined;
+	private completedElapsedMs: number | undefined;
+	private interval: ReturnType<typeof setInterval> | undefined;
+	private disposed = false;
+
+	constructor(
+		requestRender: () => void,
+		intervalMs = 1000,
+		now: () => number = Date.now,
+		completedElapsedMs?: number,
+	) {
+		this.requestRender = requestRender;
+		this.intervalMs = intervalMs;
+		this.now = now;
+		if (Number.isFinite(completedElapsedMs) && (completedElapsedMs ?? -1) >= 0) {
+			this.completedElapsedMs = completedElapsedMs;
+		}
+	}
+
+	start(): void {
+		if (this.disposed) return;
+		this.stopInterval();
+		this.startedAt = this.now();
+		this.completedElapsedMs = undefined;
+		this.interval = setInterval(() => this.requestRender(), this.intervalMs);
+		this.interval.unref();
+		this.requestRender();
+	}
+
+	end(): number | undefined {
+		if (this.disposed || this.startedAt === undefined) return undefined;
+		this.completedElapsedMs = Math.max(0, this.now() - this.startedAt);
+		this.startedAt = undefined;
+		this.stopInterval();
+		this.requestRender();
+		return this.completedElapsedMs;
+	}
+
+	restore(elapsedMs: number): void {
+		if (this.disposed || !Number.isFinite(elapsedMs) || elapsedMs < 0) return;
+		this.startedAt = undefined;
+		this.completedElapsedMs = elapsedMs;
+		this.stopInterval();
+		this.requestRender();
+	}
+
+	getSnapshot(): TurnTimerSnapshot {
+		if (this.startedAt !== undefined) {
+			return {
+				state: "working",
+				elapsedMs: Math.max(0, this.now() - this.startedAt),
+			};
+		}
+		if (this.completedElapsedMs !== undefined) {
+			return { state: "done", elapsedMs: this.completedElapsedMs };
+		}
+		return { state: "idle", elapsedMs: 0 };
+	}
+
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.stopInterval();
+	}
+
+	private stopInterval(): void {
+		if (this.interval) clearInterval(this.interval);
+		this.interval = undefined;
+	}
+}