pi-voicekit 0.1.0

package/extensions/voice/tts-text-filter.ts

@@ -0,0 +1,404 @@
+/**
+ * Text preprocessing for TTS — strips formats that read aloud poorly,
+ * enforces length limits, and normalizes whitespace.
+ *
+ * Used by:
+ *   - Auto-speak path (`speak.ts` → after_assistant_message): the agent's
+ *     full response goes through `prepareForSpeech()` before synthesis.
+ *     Critical because raw assistant output contains code fences,
+ *     markdown links, ANSI escapes from prior tool output, and other
+ *     forms that read as gibberish.
+ *   - Manual `/voice-speak <text>` path: light normalization only —
+ *     trim + collapse whitespace. Users typing explicit text don't want
+ *     us second-guessing their input.
+ *
+ * Pure functions, no I/O, no global state. Easy to test against the
+ * regression cases locked in tests/tts-text-filter.test.ts.
+ *
+ * Design choices:
+ *   - Code blocks are dropped entirely, not paraphrased. "function foo
+ *     opens brace const x equals one closes brace" is worse than silence.
+ *     Surface "[code block omitted]" once per response so users know
+ *     content was skipped.
+ *   - Markdown link syntax `[text](url)` collapses to `text` — URLs read
+ *     as gibberish ("h-t-t-p-s-colon-slash-slash-...") and the link text
+ *     is what the speaker meant.
+ *   - ANSI escapes (color codes, cursor moves) are stripped — they leak
+ *     in from quoted tool output and synthesize as noise.
+ *   - Inline code spans (single backticks) are kept inline — "use the
+ *     `useState` hook" reads naturally. Triple-backtick fences are the
+ *     hard skip.
+ *   - Length cap is enforced AFTER stripping, so a 5000-char response
+ *     that's mostly code blocks may pass.
+ */
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+export interface PrepareForSpeechOpts {
+	/**
+	 * Maximum characters in the output. If the cleaned text exceeds this,
+	 * `prepareForSpeech` returns `{ skipped: true, reason: "too long" }`.
+	 * Auto-speak callers default to 2000; manual /voice-speak passes
+	 * Infinity.
+	 */
+	maxChars?: number;
+	/**
+	 * If true, drop fenced code blocks entirely. If false, keep them but
+	 * unwrap the fences (rare — code reads poorly aloud).
+	 */
+	stripCodeBlocks?: boolean;
+	/**
+	 * If true, replace markdown link syntax with link text only. If false,
+	 * keep the URL appended (only useful for debugging — no real users
+	 * want to hear "https colon slash slash ..." aloud).
+	 */
+	collapseLinks?: boolean;
+}
+
+export interface PrepareForSpeechResult {
+	/** True if the text was rejected (length cap, empty after stripping, etc). */
+	skipped: boolean;
+	/** Cleaned text ready for synthesis. Empty string when skipped. */
+	text: string;
+	/** Human-readable reason when skipped. */
+	reason?: string;
+	/** Diagnostic counts so callers can show "[N code blocks omitted]" hints. */
+	stats: {
+		codeBlocksRemoved: number;
+		linksCollapsed: number;
+		ansiEscapesRemoved: number;
+		originalChars: number;
+		finalChars: number;
+	};
+}
+
+const DEFAULT_OPTS: Required<PrepareForSpeechOpts> = {
+	maxChars: 2000,
+	stripCodeBlocks: true,
+	collapseLinks: true,
+};
+
+/**
+ * Prepare assistant text for TTS synthesis. See module-level doc for the
+ * design rationale on each transform.
+ */
+export function prepareForSpeech(input: string, opts: PrepareForSpeechOpts = {}): PrepareForSpeechResult {
+	const config = { ...DEFAULT_OPTS, ...opts };
+	const stats = {
+		codeBlocksRemoved: 0,
+		linksCollapsed: 0,
+		ansiEscapesRemoved: 0,
+		originalChars: typeof input === "string" ? input.length : 0,
+		finalChars: 0,
+	};
+
+	if (typeof input !== "string" || !input) {
+		return { skipped: true, text: "", reason: "empty input", stats };
+	}
+
+	let text = input;
+
+	// 1. Strip ANSI escape sequences. CSI patterns from tool output:
+	//    - `\x1b[<digits>;<digits>m` (color/style)
+	//    - `\x1b[<digits>;<digits>H` (cursor moves)
+	//    - `\x1b]...\x07` (OSC sequences for window titles, hyperlinks)
+	const ansiPattern = /\x1b\[[\d;?]*[A-Za-z]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g;
+	const ansiMatches = text.match(ansiPattern);
+	stats.ansiEscapesRemoved = ansiMatches?.length ?? 0;
+	text = text.replace(ansiPattern, "");
+
+	// 2. Drop fenced code blocks. Match ``` or ~~~ fences with an optional
+	//    language tag. The middle content can include any characters
+	//    including newlines and other backticks. Greedy on opening, lazy
+	//    on closing.
+	if (config.stripCodeBlocks) {
+		const codeBlockPattern = /```[\w-]*\r?\n[\s\S]*?\r?\n```|~~~[\w-]*\r?\n[\s\S]*?\r?\n~~~/g;
+		const codeMatches = text.match(codeBlockPattern);
+		stats.codeBlocksRemoved = codeMatches?.length ?? 0;
+		text = text.replace(codeBlockPattern, " [code block omitted] ");
+	}
+
+	// 3. Collapse markdown link syntax `[text](url)` → `text`. We DO NOT
+	//    resolve image syntax `![alt](url)` to alt text — image alt
+	//    contents are usually decorative and rarely meaningful aloud.
+	//    Drop image syntax entirely.
+	if (config.collapseLinks) {
+		// Image alt: drop entire `![alt](url)` form — alt text is usually
+		// decorative ("a screenshot showing...") and rarely worth speaking.
+		text = text.replace(/!\[[^\]]*\]\([^)]+\)/g, "");
+		// Regular links: keep the visible text only.
+		text = text.replace(/\[([^\]]+)\]\([^)]+\)/g, (_full, linkText: string) => {
+			stats.linksCollapsed++;
+			return linkText;
+		});
+	}
+
+	// 4. Strip HTML tags that occasionally leak in from doc comments.
+	//    Defensive — most assistant output is plain markdown.
+	text = text.replace(/<\/?[a-zA-Z][^>]*>/g, " ");
+
+	// 5. Strip raw URLs that aren't inside markdown link syntax. These
+	//    read as gibberish aloud. Stop at whitespace; closing-paren is
+	//    included as a stop char so URLs inside parenthetical asides
+	//    like "(see https://x.dev/p)" don't swallow the closing `)`.
+	text = text.replace(/https?:\/\/[^\s)]+/g, " [link omitted] ");
+
+	// 6. Normalize markdown emphasis markers. "**bold** text *italic* text"
+	//    should read as "bold text italic text" — TTS doesn't emphasize
+	//    on punctuation. Preserve the inner text only.
+	text = text.replace(/\*\*([^*]+)\*\*/g, "$1");
+	text = text.replace(/__([^_]+)__/g, "$1");
+	text = text.replace(/\*([^*\n]+)\*/g, "$1");
+	text = text.replace(/_([^_\n]+)_/g, "$1");
+
+	// 7. Normalize headings — drop the `#` markers but keep the heading
+	//    text as a sentence. "# Hello\n" → "Hello. ".
+	text = text.replace(/^#{1,6}\s+(.+?)$/gm, "$1.");
+
+	// 8. Strip blockquote markers ("> quoted text" → "quoted text").
+	text = text.replace(/^>\s+/gm, "");
+
+	// 9. Strip horizontal rules.
+	text = text.replace(/^[-*_]{3,}$/gm, "");
+
+	// 10. Strip leading bullet markers from list items so "- foo" reads
+	//     as "foo". Each item retains its trailing newline so the
+	//     sentence segmenter (Intl.Segmenter in speak.ts) treats them
+	//     as separate sentences with natural pause boundaries — a more
+	//     natural speech cadence than collapsing to a comma list, which
+	//     would be one long run-on with no breath points.
+	text = text.replace(/^[ \t]*[-*+][ \t]+/gm, "");
+
+	// 11. Inline code spans: keep the inner text but drop backticks.
+	//     "use `useState`" → "use useState".
+	text = text.replace(/`([^`\n]+)`/g, "$1");
+
+	// 11a. v7.1.3 — text normalization (TN). Compact local TTS engines
+	//      (Kitten/Piper) read raw "Dr." as letters and bare numbers
+	//      digit-by-digit. Expand the highest-value patterns:
+	//      - common English abbreviations / titles
+	//      - bare cardinal numbers up to a few digits
+	//      Locale-aware long-form (Microsoft Recognizers-Text style)
+	//      is out of scope; this is the deterministic ~30-pattern pass
+	//      that catches 80% of CLI assistant output gripes.
+	text = expandAbbreviations(text);
+	text = expandSimpleNumbers(text);
+
+	// 12. v7.1.3 — strip emojis and pictographs. The TTS engines either
+	//     read them as literal "smiling face with smiling eyes" (espeak
+	//     fallback) or skip+space+resume in a way that breaks prosody.
+	//     Using Unicode property `Extended_Pictographic` covers the
+	//     full emoji set including skin-tone variants. Variation
+	//     Selector-16 (U+FE0F) often follows pictographs to force emoji
+	//     presentation; remove it too.
+	text = text.replace(/[\p{Extended_Pictographic}\u{FE0F}\u{200D}]/gu, "");
+
+	// 13. Strip leftover decorative chars that have no spoken equivalent:
+	//     - U+2500-257F box drawing
+	//     - U+2580-259F block elements
+	//     - U+25A0-25FF geometric shapes
+	//     - U+2600-26FF misc symbols (✓✗★, weather, etc.)
+	//     - U+2700-27BF dingbats (✂✈✏…)
+	//     - U+2190-21FF arrows (→←↑↓⇒)
+	//     - U+2300-23FF technical (⌘⌥⏎)
+	text = text.replace(/[←-⇿⌀-⏿─-╿▀-▟■-◿☀-⛿✀-➿]/g, "");
+
+	// 14. Collapse runs of repeated punctuation. "!!!" / "..." / "???"
+	//     read as comically long pauses. Reduce to a single mark.
+	text = text.replace(/([!?.])\1{2,}/g, "$1");
+	text = text.replace(/-{3,}/g, " ");
+
+	// 15. Collapse whitespace runs. Keep paragraph breaks (double newline)
+	//     because the segmenter uses them; everything else becomes a
+	//     single space.
+	text = text.replace(/[ \t]+/g, " ");
+	text = text.replace(/\n{3,}/g, "\n\n");
+	text = text.trim();
+
+	stats.finalChars = text.length;
+
+	if (!text) {
+		return { skipped: true, text: "", reason: "empty after stripping", stats };
+	}
+
+	if (text.length > config.maxChars) {
+		return {
+			skipped: true,
+			text: "",
+			reason: `text length (${text.length}) exceeds maxChars (${config.maxChars})`,
+			stats,
+		};
+	}
+
+	return { skipped: false, text, stats };
+}
+
+// ─── Text normalization helpers (v7.1.3) ──────────────────────────────────────
+
+/**
+ * Common English abbreviations, in regex+replacement form. Word-boundary
+ * matched so "Dr." → "Doctor" but "Dropout" stays unchanged. Order matters:
+ * longer patterns must precede prefixes that would partially match them.
+ */
+const ABBREV_RULES: ReadonlyArray<readonly [RegExp, string]> = [
+	[/\bDr\./g, "Doctor"],
+	[/\bMr\./g, "Mister"],
+	[/\bMrs\./g, "Misses"],
+	[/\bMs\./g, "Miss"],
+	[/\bSt\./g, "Saint"],
+	[/\bProf\./g, "Professor"],
+	[/\bSr\./g, "Senior"],
+	[/\bJr\./g, "Junior"],
+	[/\bvs\./g, "versus"],
+	[/\bi\.e\./gi, "that is"],
+	[/\be\.g\./gi, "for example"],
+	[/\betc\./gi, "et cetera"],
+	[/\bapprox\./gi, "approximately"],
+	[/\bvol\./gi, "volume"],
+	[/\bch\./gi, "chapter"],
+	[/\bp\.s\./gi, "P S"],
+	[/\bU\.S\./g, "U S"],
+	[/\bU\.K\./g, "U K"],
+	[/\bE\.U\./g, "E U"],
+	// CLI / dev terms commonly read poorly
+	[/\bAPI\b/g, "A P I"],
+	[/\bCLI\b/g, "C L I"],
+	[/\bURL\b/g, "U R L"],
+	[/\bHTTP\b/g, "H T T P"],
+	[/\bHTTPS\b/g, "H T T P S"],
+	[/\bSQL\b/g, "S Q L"],
+	[/\bJSON\b/g, "JAY-son"],
+	[/\bYAML\b/g, "YAH-mul"],
+	[/\bCSS\b/g, "C S S"],
+	[/\bHTML\b/g, "H T M L"],
+];
+
+export function expandAbbreviations(text: string): string {
+	let out = text;
+	for (const [re, rep] of ABBREV_RULES) out = out.replace(re, rep);
+	return out;
+}
+
+const ONES = ["zero", "one", "two", "three", "four", "five", "six", "seven", "eight", "nine"];
+const TEENS = [
+	"ten",
+	"eleven",
+	"twelve",
+	"thirteen",
+	"fourteen",
+	"fifteen",
+	"sixteen",
+	"seventeen",
+	"eighteen",
+	"nineteen",
+];
+const TENS = ["", "", "twenty", "thirty", "forty", "fifty", "sixty", "seventy", "eighty", "ninety"];
+
+function numberToWords(n: number): string {
+	if (n < 0 || n > 9_999_999 || !Number.isInteger(n)) return String(n);
+	if (n === 0) return "zero";
+	const parts: string[] = [];
+	if (n >= 1_000_000) {
+		parts.push(numberToWords(Math.floor(n / 1_000_000)), "million");
+		n %= 1_000_000;
+	}
+	if (n >= 1_000) {
+		parts.push(numberToWords(Math.floor(n / 1_000)), "thousand");
+		n %= 1_000;
+	}
+	if (n >= 100) {
+		parts.push(ONES[Math.floor(n / 100)]!, "hundred");
+		n %= 100;
+	}
+	if (n >= 20) {
+		parts.push(TENS[Math.floor(n / 10)]!);
+		n %= 10;
+		if (n > 0) parts[parts.length - 1] += "-" + ONES[n]!;
+		n = 0;
+	}
+	if (n >= 10) parts.push(TEENS[n - 10]!);
+	else if (n > 0) parts.push(ONES[n]!);
+	return parts.join(" ");
+}
+
+/**
+ * Expand bare cardinal numbers (1..9_999_999) to words. Skips:
+ *   - numbers attached to letters (`v2`, `5k`, `100ms`) — version/unit
+ *     suffixes read fine as-is
+ *   - decimals (`3.14`) — engines handle these reasonably
+ *   - years between 1900-2099 (left as digits — engines say "twenty
+ *     twenty-six" naturally for `2026`)
+ *   - hex-like tokens (`0xFF`)
+ */
+export function expandSimpleNumbers(text: string): string {
+	// Negative lookbehind: reject digits that are part of a version/decimal
+	// (`v1.2`, `3.14`) or a word (`v2`, `5k`).
+	// Negative lookahead: reject digits followed by a word char (`100ms`)
+	// or by `.<digit>` (decimal/version) but ALLOW sentence-ending `.`.
+	return text.replace(/(?<![\w.])(\d{1,7})(?![\w]|\.\d)/g, (match, digits: string) => {
+		const n = parseInt(digits, 10);
+		// Years pass through unchanged — TTS engines handle them well.
+		if (digits.length === 4 && n >= 1900 && n <= 2099) return match;
+		return numberToWords(n);
+	});
+}
+
+/**
+ * Lightweight version for the manual `/voice-speak <text>` path. Trims
+ * and collapses whitespace runs, but leaves code/links/ANSI alone — the
+ * user typed exactly what they want spoken.
+ */
+export function lightNormalize(input: string): string {
+	if (typeof input !== "string") return "";
+	return input.replace(/[ \t]+/g, " ").trim();
+}
+
+// ─── BCP-47 normalization ─────────────────────────────────────────────────────
+
+/**
+ * Canonicalize a BCP-47-ish language tag.
+ *
+ * Subtag handling per RFC 5646 casing convention:
+ *   - language (2-3 letters): lowercase           — `en`, `zh`
+ *   - script (4 letters):     Title-case          — `Hant`, `Latn`
+ *   - region (2 letters or 3 digits): UPPERCASE   — `US`, `BR`, `419`
+ *   - variant (5+ letters or starts with digit): kept as-is, lowercase
+ *
+ * Inputs we accept: `en`, `en-US`, `en_US`, `EN-us`, `pt-br`, `zh_CN`,
+ * `zh-Hant-TW`, `sl-rozaj`. Output preserves all subtags in canonical
+ * casing; we never drop information.
+ *
+ * This is the single canonical form used by every TTS code path —
+ * comparing two tags after passing both through this function is the
+ * only safe way to check equality.
+ */
+export function normalizeBCP47(tag: string): string {
+	if (typeof tag !== "string" || !tag) return "";
+	const parts = tag.replace(/_/g, "-").split("-").filter(Boolean);
+	if (parts.length === 0) return "";
+	const out: string[] = [];
+	for (let i = 0; i < parts.length; i++) {
+		const sub = parts[i]!;
+		if (i === 0) {
+			// Primary language: 2-3 letter code, lowercase
+			out.push(sub.toLowerCase());
+		} else if (sub.length === 4 && /^[A-Za-z]{4}$/.test(sub)) {
+			// Script subtag: Title case (e.g. Hant, Latn, Cyrl)
+			out.push(sub.charAt(0).toUpperCase() + sub.slice(1).toLowerCase());
+		} else if (/^[A-Za-z]{2}$/.test(sub) || /^\d{3}$/.test(sub)) {
+			// Region subtag: 2-letter alpha or 3-digit UN M.49 → uppercase
+			out.push(sub.toUpperCase());
+		} else {
+			// Variant / extension subtag: keep lowercase
+			out.push(sub.toLowerCase());
+		}
+	}
+	return out.join("-");
+}
+
+/** Extract the base language code from a BCP-47 tag. `en-US` → `en`. */
+export function baseLanguage(tag: string): string {
+	const norm = normalizeBCP47(tag);
+	const idx = norm.indexOf("-");
+	return idx === -1 ? norm : norm.slice(0, idx);
+}

package/extensions/voice/ui-aura.ts

@@ -0,0 +1,272 @@
+/**
+ * "Auroral" visual language — v7.2 world-class polish.
+ *
+ * Three primitives that elevate pi-listen's visual identity from
+ * "minimal CLI" to "premium application":
+ *
+ *  1. Liquid Braille waveform — sub-cell vertical bars at 4-level
+ *     resolution per column, packed two-per-cell via braille glyphs.
+ *     Eight effective vertical levels per CELL vs the current ▁▂▃▄▅▆▇█
+ *     8-step block scale, and TWO samples per cell width (so a 16-cell
+ *     waveform resolves 32 audio samples — 2× the current density).
+ *
+ *  2. Aurora truecolor gradient — Catppuccin-inspired ramp from
+ *     cool lavender at the edges through warm peach at the peak. RGB
+ *     interpolated across 64 stops; per-cell color reflects local
+ *     amplitude so loud peaks "burn" toward red while soft tails stay
+ *     ethereal blue. Pure ANSI 24-bit escape (`\x1b[38;2;R;G;Bm`),
+ *     no theme dependency, falls back gracefully on legacy terminals
+ *     (ANSI escape just renders as nothing on non-truecolor TTYs).
+ *
+ *  3. Floating Island chrome — `╭─╮│╰╯` bordered 3-line "card" with
+ *     title in bold accent, content row, and dim keybind footer.
+ *     Establishes "voice mode" spatial authority on screen rather
+ *     than blending in as a single inline status line.
+ *
+ * References (Gemini world-class design recommendation, derived from):
+ *   - Charm Bracelet lipgloss/gum nested borders + truecolor:
+ *     https://github.com/charmbracelet/lipgloss
+ *   - Atuin command palette layout: https://github.com/atuinsh/atuin
+ *   - Lazygit pane focus + dim non-active: https://github.com/jesseduffield/lazygit
+ *   - K9s status density: https://github.com/derailed/k9s
+ */
+
+import { ICON } from "./ui-icons";
+import { visualWidth, padRightVisual } from "./ui-width";
+
+// ─── Liquid Braille ───────────────────────────────────────────────────────────
+
+/**
+ * Encode (leftLevel, rightLevel) ∈ [0..4]² as a single braille glyph.
+ * Each cell visually holds TWO column-bars (left + right), each
+ * up to 4 dots tall — so one row of N cells = 2N audio samples.
+ *
+ * Braille bit layout (Unicode U+2800 + 8-bit pattern):
+ *   1 4
+ *   2 5
+ *   3 6
+ *   7 8     (rows top-down; 7,8 are bottom row)
+ *
+ * Vertical bars rise from the bottom up. Left column dots in order
+ * 7→3→2→1 = 0x40→0x44→0x46→0x47. Right column 8→6→5→4 = 0x80→0xA0
+ * →0xB0→0xB8.
+ */
+const BRAILLE_LEFT_BITS = [0, 0x40, 0x44, 0x46, 0x47] as const;
+const BRAILLE_RIGHT_BITS = [0, 0x80, 0xa0, 0xb0, 0xb8] as const;
+
+export function brailleBar(left: number, right: number): string {
+	const l = Math.max(0, Math.min(4, Math.round(left)));
+	const r = Math.max(0, Math.min(4, Math.round(right)));
+	return String.fromCodePoint(0x2800 + BRAILLE_LEFT_BITS[l]! + BRAILLE_RIGHT_BITS[r]!);
+}
+
+/**
+ * Render a "Liquid Braille" waveform from a sample array. Each cell
+ * encodes the LEFT and RIGHT sample as 0..4 bar levels, so `cells = N/2`.
+ *
+ * Pass an array of samples ∈ [0..1]. Sample 0 → leftmost cell's left
+ * bar; sample 1 → leftmost cell's right bar; etc.
+ *
+ * Apply `colorFn(level)` per CELL using the cell's max(left, right)
+ * to pick a gradient stop — produces the auroral effect where
+ * peaks "burn" warmer.
+ */
+export function liquidBraille(samples: number[], colorFn?: (level: number) => string): string {
+	const cells = Math.ceil(samples.length / 2);
+	let out = "";
+	for (let i = 0; i < cells; i++) {
+		const leftSample = samples[i * 2] ?? 0;
+		const rightSample = samples[i * 2 + 1] ?? 0;
+		const left = leftSample * 4; // 0..1 → 0..4
+		const right = rightSample * 4;
+		const glyph = brailleBar(left, right);
+		if (colorFn) {
+			const peak = Math.max(leftSample, rightSample);
+			out += colorFn(peak) + glyph;
+		} else {
+			out += glyph;
+		}
+	}
+	if (colorFn) out += "\x1b[0m"; // reset at end of run
+	return out;
+}
+
+// ─── Aurora Truecolor Gradient ────────────────────────────────────────────────
+
+/** Catppuccin-Mocha-inspired ramp: cool lavender → warm peach. */
+const AURORA_STOPS: ReadonlyArray<readonly [number, number, number]> = [
+	[180, 190, 254], // lavender (low)
+	[137, 180, 250], // blue
+	[203, 166, 247], // mauve
+	[245, 194, 231], // pink
+	[250, 179, 135], // peach
+	[243, 139, 168], // red (peak)
+];
+
+/**
+ * Return a 24-bit ANSI foreground escape for `level` ∈ [0..1].
+ * Linearly interpolates across the AURORA_STOPS palette. The escape
+ * is `\x1b[38;2;R;G;Bm` — no reset (caller must emit `\x1b[0m`
+ * at end of the colored run).
+ */
+export function auroraColor(level: number): string {
+	const t = Math.max(0, Math.min(1, level));
+	const segments = AURORA_STOPS.length - 1;
+	const pos = t * segments;
+	const idx = Math.min(segments - 1, Math.floor(pos));
+	const f = pos - idx;
+	const a = AURORA_STOPS[idx]!;
+	const b = AURORA_STOPS[idx + 1]!;
+	const r = Math.round(a[0] + (b[0] - a[0]) * f);
+	const g = Math.round(a[1] + (b[1] - a[1]) * f);
+	const blue = Math.round(a[2] + (b[2] - a[2]) * f);
+	return `\x1b[38;2;${r};${g};${blue}m`;
+}
+
+/**
+ * Slow "breathing" color for static titles. Returns a truecolor ANSI
+ * escape that smoothly cycles through a narrow band of the aurora
+ * palette (mauve ↔ pink) on a ~4s cycle. Time `tickMs` should be
+ * `Date.now()` from the caller so all widgets breathe in phase.
+ *
+ * The cycle is intentionally narrow (3 stops, indices 2–4) so the
+ * title stays accent-coloured at all times; only the saturation
+ * subtly shifts. Combined with bold, reads as a premium "alive but
+ * not distracting" indicator.
+ */
+export function titleBreathe(tickMs: number): string {
+	// 4-second cycle: phase ∈ [0, 1).
+	const phase = (((tickMs / 4000) % 1) + 1) % 1;
+	// sin-shaped modulation: 0 → mauve (idx 2), 1 → pink (idx 3).
+	const sinT = (Math.sin(phase * Math.PI * 2) + 1) / 2; // 0..1
+	// Map to aurora stops 2..4 (mauve → pink → peach edge).
+	const t = 0.4 + sinT * 0.25; // narrow band centered around mauve/pink
+	return auroraColor(t);
+}
+
+/**
+ * Live audio-activity badge — a small chip-style indicator that
+ * reflects the current RMS level. Replaces silent timers with a
+ * one-glance "is anything happening?" signal.
+ *
+ *   level < 0.05 : ▁ quiet  (dim)
+ *   level < 0.20 : ▃ voice  (cool aurora)
+ *   level < 0.50 : ▅ active (mid aurora)
+ *   level ≥ 0.50 : ▇ loud   (hot aurora)
+ *
+ * Returns the chip pre-styled with truecolor ANSI escapes; no
+ * theme dependency. Caller wraps in any spacing they like.
+ */
+export function activityTag(level: number, dim: (s: string) => string): string {
+	if (level < 0.05) return dim("▁ quiet");
+	if (level < 0.2) return auroraColor(0.1) + "▃ voice" + "\x1b[0m";
+	if (level < 0.5) return auroraColor(0.45) + "▅ active" + "\x1b[0m";
+	return auroraColor(0.85) + "▇ loud" + "\x1b[0m";
+}
+
+/** Hex-color string version (for callers that want to mix into rgb fonts). */
+export function auroraHex(level: number): string {
+	const t = Math.max(0, Math.min(1, level));
+	const segments = AURORA_STOPS.length - 1;
+	const pos = t * segments;
+	const idx = Math.min(segments - 1, Math.floor(pos));
+	const f = pos - idx;
+	const a = AURORA_STOPS[idx]!;
+	const b = AURORA_STOPS[idx + 1]!;
+	const r = Math.round(a[0] + (b[0] - a[0]) * f);
+	const g = Math.round(a[1] + (b[1] - a[1]) * f);
+	const blue = Math.round(a[2] + (b[2] - a[2]) * f);
+	const hex = (n: number) => n.toString(16).padStart(2, "0");
+	return `#${hex(r)}${hex(g)}${hex(blue)}`;
+}
+
+// ─── Floating Island chrome ────────────────────────────────────────────────────
+
+/** ANSI escape stripper — required before any visual-width math on
+ * styled strings, since `visualWidth` counts each ESC byte as 1 col. */
+const ANSI_RE = /\x1b\[[\d;]*[A-Za-z]/g;
+const stripAnsi = (s: string): string => s.replace(ANSI_RE, "");
+/** Visual width of a pre-styled string (ANSI escapes excluded). */
+function trueWidth(s: string): number {
+	return visualWidth(stripAnsi(s));
+}
+
+/**
+ * Render a 3-line "floating island" with rounded borders.
+ *
+ *   ╭─ {title} ─────────────────────╮
+ *   │  {content}                    │
+ *   ╰─ {footer} ────────────────────╯
+ *
+ * The title sits inline on the top border, footer inline on the
+ * bottom border — the box reads as a "card" rather than a block.
+ * All three lines use rounded corners (Material 3 sheet aesthetic).
+ *
+ * Pass pre-styled (already ANSI-coloured) strings; this helper
+ * doesn't apply theming itself, just chrome.
+ *
+ * `width` is the OUTER width including the two `│` borders. All
+ * width math is ANSI-stripped — the right edge always lands on the
+ * `╮` / `╯` even when content is full of color escapes.
+ */
+export function island(opts: {
+	width: number;
+	title: string; // pre-styled or plain
+	content: string; // pre-styled or plain
+	footer?: string; // pre-styled or plain (optional 3rd line)
+	dim: (s: string) => string; // theme dim wrapper
+	bold?: (s: string) => string; // unused (retained for API stability)
+}): string[] {
+	const { width, title, content, footer, dim } = opts;
+	const innerW = Math.max(4, width - 2);
+
+	// Top border with title inlaid: `╭─ TITLE ────╮`
+	// Layout: corner + boxH + space + title + space + filler + corner.
+	// All widths stripped of ANSI before counting.
+	const titleW = trueWidth(title);
+	const topFillerCount = Math.max(0, innerW - 1 - 1 - titleW - 1); // -1 leading boxH, -1+1 spaces, -1 trailing boxH... fixed:
+	// Layout cells:
+	//   [boxH][ ][title][ ][boxH × topFillerCount]   = innerW cells total
+	//   1     1  titleW 1   topFillerCount = innerW
+	// → topFillerCount = innerW - titleW - 3
+	const topFill = Math.max(0, innerW - titleW - 3);
+	const top =
+		dim(ICON.boxRoundedTL) +
+		dim(ICON.boxH) +
+		" " +
+		title +
+		" " +
+		dim(ICON.boxH.repeat(topFill)) +
+		dim(ICON.boxRoundedTR);
+
+	// Content row — pad to fill innerW visually (with ANSI-stripped width)
+	const contentW = trueWidth(content);
+	const contentPadded = contentW < innerW ? content + " ".repeat(Math.max(0, innerW - contentW)) : content;
+	const middle = dim(ICON.boxV) + contentPadded + dim(ICON.boxV);
+
+	// Bottom border with optional footer inlaid (same math as top).
+	let bottom: string;
+	if (footer) {
+		const fW = trueWidth(footer);
+		const botFill = Math.max(0, innerW - fW - 3);
+		bottom =
+			dim(ICON.boxRoundedBL) +
+			dim(ICON.boxH) +
+			" " +
+			footer +
+			" " +
+			dim(ICON.boxH.repeat(botFill)) +
+			dim(ICON.boxRoundedBR);
+	} else {
+		bottom = dim(ICON.boxRoundedBL) + dim(ICON.boxH.repeat(innerW)) + dim(ICON.boxRoundedBR);
+	}
+
+	return [top, middle, bottom];
+}
+
+/** Pad-right helper that respects pre-styled (ANSI-escape-laden) strings. */
+export function padToWidth(s: string, width: number): string {
+	const w = trueWidth(s);
+	if (w >= width) return s;
+	return s + " ".repeat(width - w);
+}