pi-voicekit 0.1.0

package/extensions/voice/ui-help-overlay.ts

@@ -0,0 +1,161 @@
+/**
+ * Keyboard / command reference overlay — §11 of the v7.1 plan.
+ *
+ * Stacks ABOVE any picker/panel via `ctx.ui.custom()`. Resolves with
+ * no result on `[esc]` so the caller can simply discard. Width-tier
+ * aware: at <60 cols it falls back to a flat list with no chrome.
+ *
+ * Hotkey routing (§11):
+ *   - `?`  opens help ONLY when no picker is open / no overlay in
+ *          front. Inside a picker it's a literal search character.
+ *          Caller is responsible for context-checked routing.
+ *   - `F1` always opens help.
+ *   - `h`  is intentionally NOT bound (vim users would trigger it).
+ */
+
+import { matchesKey, Key } from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { ICON } from "./ui-icons";
+import { isPanelTooNarrow } from "./ui-width";
+
+export interface HelpOverlayDeps {
+	readonly theme?: Theme;
+}
+
+interface HelpEntry {
+	readonly key: string;
+	readonly desc: string;
+}
+interface HelpSection {
+	readonly heading: string;
+	readonly entries: ReadonlyArray<HelpEntry>;
+}
+
+const HELP_SECTIONS: ReadonlyArray<HelpSection> = [
+	{
+		heading: "Settings panel",
+		entries: [
+			{ key: "← →", desc: "switch tab" },
+			{ key: "↑ ↓", desc: "navigate row (skips group headings)" },
+			{ key: "↵", desc: "select / activate" },
+			{ key: "esc", desc: "back to main / close panel" },
+			{ key: "type", desc: "filter (search)" },
+			{ key: "bksp", desc: "clear last search char" },
+		],
+	},
+	{
+		heading: "Voice (TTS)",
+		entries: [
+			{ key: "/voice-speak <text>", desc: "speak text out loud" },
+			{ key: "/voice-speak-test", desc: "speak a sample sentence" },
+			{ key: "/voice-speak-toggle", desc: "enable / disable TTS" },
+			{ key: "/voice-speak-models", desc: "open model picker" },
+			{ key: "/voice-speak-info", desc: "diagnose TTS state" },
+		],
+	},
+	{
+		heading: "Voice (STT)",
+		entries: [
+			{ key: "hold space", desc: "push-to-talk recording" },
+			{ key: "/voice-toggle", desc: "enable / disable STT" },
+			{ key: "/voice-settings", desc: "open settings panel" },
+			{ key: "/voice-models", desc: "browse / install local STT models" },
+		],
+	},
+	{
+		heading: "Active widget controls",
+		entries: [
+			{ key: "esc", desc: `cancel active install (when ${ICON.bulletActive} install widget mounted)` },
+			{ key: "esc", desc: "stop active playback (when no install in front)" },
+		],
+	},
+	{
+		heading: "Help",
+		entries: [
+			{ key: "F1", desc: "open this help (always)" },
+			{ key: "/voice-help", desc: "open this help via slash command" },
+			{ key: "esc / ↵", desc: "close help" },
+		],
+	},
+];
+
+/**
+ * Pi `Component`-shaped class — pass into `ctx.ui.custom()` directly.
+ */
+export class HelpOverlay {
+	private readonly deps: HelpOverlayDeps;
+	private readonly done: () => void;
+	private resolved = false;
+
+	constructor(deps: HelpOverlayDeps, done: () => void) {
+		this.deps = deps;
+		this.done = done;
+	}
+
+	render(width: number): string[] {
+		if (isPanelTooNarrow(width)) return this.renderNarrow();
+
+		const t = this.deps.theme;
+		const dim = (s: string) => (t ? t.fg("dim", s) : s);
+		const accent = (s: string) => (t ? t.fg("accent", s) : s);
+		const bold = (s: string) => (t ? t.fg("accent", s) : s);
+
+		const w = Math.max(60, Math.min(width - 2, 90));
+		const lines: string[] = [];
+		lines.push(
+			`  ${bold("pi-listen")} ${dim(ICON.middot)} ${bold("Help")} ${dim(`${ICON.middot} press [esc] to close`)}`
+		);
+		lines.push(`  ${dim(ICON.boxH.repeat(Math.min(w, 60)))}`);
+		for (const sec of HELP_SECTIONS) {
+			lines.push("");
+			lines.push(`  ${accent(sec.heading)}`);
+			const keyW = Math.max(...sec.entries.map((e) => e.key.length));
+			for (const e of sec.entries) {
+				const k = e.key.padEnd(keyW);
+				lines.push(`    ${accent(k)}  ${dim(ICON.middot)}  ${dim(e.desc)}`);
+			}
+		}
+		lines.push("");
+		lines.push(
+			`  ${dim("Note: Hindi (Devanagari) and Arabic voices fall back to romanized labels — see /voice-settings → Speak tab for the full voice list.")}`
+		);
+		return lines;
+	}
+
+	private renderNarrow(): string[] {
+		const t = this.deps.theme;
+		const dim = (s: string) => (t ? t.fg("dim", s) : s);
+		const accent = (s: string) => (t ? t.fg("accent", s) : s);
+		const lines: string[] = [];
+		lines.push(` ${accent("pi-listen Help")}`);
+		for (const sec of HELP_SECTIONS) {
+			lines.push("");
+			lines.push(` ${accent(sec.heading)}`);
+			for (const e of sec.entries) {
+				lines.push(`  ${accent(e.key)} ${dim(e.desc)}`);
+			}
+		}
+		lines.push("");
+		lines.push(` ${dim("[esc] close")}`);
+		return lines;
+	}
+
+	handleInput(data: string): void {
+		if (this.resolved) return;
+		if (matchesKey(data, Key.escape) || matchesKey(data, Key.enter)) {
+			this.resolved = true;
+			try {
+				this.done();
+			} catch {
+				/* never fail closure */
+			}
+			return;
+		}
+		// Any other key (including ? and F1 again) is ignored — overlay
+		// is read-only.
+	}
+
+	invalidate(): void {
+		/* render is uncached */
+	}
+}

package/extensions/voice/ui-icons.ts

@@ -0,0 +1,124 @@
+/**
+ * Shared glyph table — v7.2 visual polish refresh.
+ *
+ * Design language synthesized from established minimal-TUI references
+ * (Charm Bracelet's lipgloss/bubbletea, charm/gum, lazygit, k9s, fzf,
+ * and Apple HIG / Material 3 principles translated to terminal):
+ *
+ *   - Spinner: braille 10-frame rotation (Charm convention) — smoother
+ *     and more modern than 4-frame quarter-circle.
+ *   - Borders: rounded `╭─╮│╰╯` for modals/overlays (Material modal feel,
+ *     softer than sharp), sharp for inline tables.
+ *   - Progress: 8-step subpixel fill via `▏▎▍▌▋▊▉█` for smooth gradient
+ *     (Charm/lipgloss progress).
+ *   - Cursor: thin left bar `│` + accent text on selected row, dim on
+ *     non-selected (HIG "deference": chrome stays subtle).
+ *   - Status: colored dot + label (e.g. `● ready`, `○ download`).
+ *
+ * Hard rule unchanged from v7.1: NO emoji. Every glyph is geometric
+ * Unicode (U+2500-25FF + braille U+2800-28FF) or one of the small
+ * allowlist marks (✓ ✗ ☐ ☑ • · …).
+ *
+ * Roles are semantic, not visual — call sites use `ICON.activeMarker`
+ * and not the literal `"›"` so a future theme swap is one edit.
+ */
+export const ICON = {
+	// State / status
+	checkOk: "✓",
+	checkFail: "✗",
+	bulletActive: "●",
+	bulletInactive: "○",
+	bulletDim: "·",
+	checkboxOff: "☐",
+	checkboxOn: "☑",
+
+	// Cursors / selection
+	activeMarker: "›",
+	chevronRight: "›",
+	chevronLeft: "‹",
+	cursorBar: "│", // v7.2: thin left bar for selected picker rows
+
+	// Arrows
+	arrowRight: "→",
+	arrowLeft: "←",
+	arrowUp: "↑",
+	arrowDown: "↓",
+	doubleArrowRight: "⇒",
+
+	// v7.2 — Spinner frames. Two profiles, both phase-aligned at 10 Hz:
+	//   - braille (10 frames): the Charm convention. Smooth, minimal.
+	//     Each glyph is 1 cell wide, suitable for inline status lines.
+	//   - arc (4 frames): retained as fallback for terminals without
+	//     good braille font coverage (e.g. Windows default cmd.exe).
+	spinnerFrames: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const,
+	spinnerFramesArc: ["◐", "◓", "◑", "◒"] as const,
+	// Pulse for "alive but waiting" states (e.g. install paused).
+	pulseFrames: ["·", "∙", "●", "∙"] as const,
+
+	// Progress bar
+	barFilled: "█",
+	barEmpty: "░",
+	barPartial: ["▏", "▎", "▍", "▌", "▋", "▊", "▉"] as const, // 1/8 .. 7/8
+	// v7.2: thin-line progress for compact widgets — modern alternative
+	// to the chunky █░ block bar. Pair with a leading-edge cap for
+	// "moving" feel during indeterminate progress.
+	barThinFilled: "━",
+	barThinEmpty: "─",
+	barThinCap: "╾", // leading-edge cap for moving progress
+
+	// Box drawing (U+2500-257F) for borders / separators
+	boxH: "─",
+	boxV: "│",
+	boxTL: "┌",
+	boxTR: "┐",
+	boxBL: "└",
+	boxBR: "┘",
+	boxTeeL: "├",
+	boxTeeR: "┤",
+	boxTeeT: "┬",
+	boxTeeB: "┴",
+	boxCross: "┼",
+
+	// v7.2 — Rounded corners for modal/overlay chrome. Softer "pill"
+	// feel that matches Apple HIG sheet/modal aesthetics.
+	boxRoundedTL: "╭",
+	boxRoundedTR: "╮",
+	boxRoundedBL: "╰",
+	boxRoundedBR: "╯",
+
+	// Heavy / double for emphasis
+	boxHHeavy: "━",
+	boxVHeavy: "┃",
+	boxHDouble: "═",
+	boxVDouble: "║",
+
+	// Section dividers
+	bullet: "•",
+	middot: "·",
+	ellipsis: "…",
+} as const;
+
+/** Semantic icon role — pick one in widget code, never hardcode the glyph. */
+export type IconRole = keyof typeof ICON;
+
+/**
+ * Return spinner frame for tick `t` (any non-negative integer). Rotates
+ * through `ICON.spinnerFrames` in order. Used by every animated widget
+ * driven by §2's RenderTicker, so all spinners stay in phase per frame.
+ *
+ * v7.2: defaults to the 10-frame braille rotation (Charm convention).
+ * Pass `arc` for the legacy 4-frame quarter-circle if a terminal has
+ * limited braille font coverage.
+ */
+export function spinnerFrame(t: number, profile: "braille" | "arc" = "braille"): string {
+	const frames = profile === "arc" ? ICON.spinnerFramesArc : ICON.spinnerFrames;
+	return frames[((t % frames.length) + frames.length) % frames.length];
+}
+
+/** Pulse frame — for "alive but waiting" states (no rotation, breathing). */
+export function pulseFrame(t: number): string {
+	const frames = ICON.pulseFrames;
+	// Half-speed pulse: each frame holds for 2 ticks.
+	const idx = Math.floor(t / 2) % frames.length;
+	return frames[idx]!;
+}

package/extensions/voice/ui-locale-labels.ts

@@ -0,0 +1,110 @@
+/**
+ * Native-script + gender labels for the Voice picker (§8 of v7.1 plan).
+ *
+ * Hand-curated for the languages pi-listen ships voices for, using the
+ * BCP-47 base-language tag (not script/region) as the lookup key. Three
+ * intentional omissions:
+ *
+ *   - `ar` (Arabic): RTL embedding inside fixed-width LTR terminal
+ *     columns breaks cursor positioning on enough terminals (especially
+ *     stripped-down SSH PTYs) to make it a stability hazard. Arabic
+ *     voices fall back to the romanized label.
+ *   - `hi` (Hindi): Devanagari uses combining marks and zero-width
+ *     vowels. Without a real grapheme segmenter (which would violate
+ *     the zero-dependency rule), `visualWidth` would overcount their
+ *     width and break right-aligned columns. Hindi voices fall back to
+ *     romanized labels.
+ *   - Anything else not in this table — fall back to English
+ *     `(Language · M/F)` via `formatRomanizedLabel()`.
+ *
+ * Gender-word translations come from the dictionary forms used in
+ * mainstream OS locale pickers (macOS Languages & Region, Windows
+ * Settings → Language). They're labels, not full phrases — terse on
+ * purpose so they fit in a narrow voice-picker column.
+ */
+
+export interface LocaleLabel {
+	/** Native-script language name (e.g. 中文, 日本語, 한국어). */
+	readonly nativeName: string;
+	/** Native masculine gender word, when available. */
+	readonly masc?: string;
+	/** Native feminine gender word, when available. */
+	readonly fem?: string;
+}
+
+/**
+ * Keyed by BCP-47 base language. Look up via `localeLabel(baseLang)`
+ * — DO NOT index this map directly; the helper handles missing-key
+ * fallback uniformly. Twelve scripts intentional; ar/hi intentionally
+ * omitted (see file header).
+ */
+const LOCALE_LABELS: Record<string, LocaleLabel> = {
+	en: { nativeName: "English", masc: "Male", fem: "Female" },
+	zh: { nativeName: "中文", masc: "男声", fem: "女声" },
+	ja: { nativeName: "日本語", masc: "男性", fem: "女性" },
+	ko: { nativeName: "한국어", masc: "남성", fem: "여성" },
+	es: { nativeName: "Español", masc: "Masculino", fem: "Femenino" },
+	fr: { nativeName: "Français", masc: "Masculin", fem: "Féminin" },
+	de: { nativeName: "Deutsch", masc: "Männlich", fem: "Weiblich" },
+	it: { nativeName: "Italiano", masc: "Maschile", fem: "Femminile" },
+	pt: { nativeName: "Português", masc: "Masculino", fem: "Feminino" },
+	ru: { nativeName: "Русский", masc: "Мужской", fem: "Женский" },
+	nl: { nativeName: "Nederlands", masc: "Mannelijk", fem: "Vrouwelijk" },
+	tr: { nativeName: "Türkçe", masc: "Erkek", fem: "Kadın" },
+};
+
+/**
+ * Look up native label by BCP-47 base language tag. Pass the base only
+ * (e.g. "zh", not "zh-Hant-TW") — variants share native names. Returns
+ * `null` for omitted scripts (ar, hi) and unknown tags so the caller can
+ * fall back to romanized via `formatRomanizedLabel()`.
+ */
+export function localeLabel(baseLang: string): LocaleLabel | null {
+	const key = baseLang.toLowerCase();
+	return LOCALE_LABELS[key] ?? null;
+}
+
+/** English-language base-name map for romanized fallback labels. */
+const ROMANIZED_NAMES: Record<string, string> = {
+	en: "English",
+	zh: "Chinese",
+	ja: "Japanese",
+	ko: "Korean",
+	es: "Spanish",
+	fr: "French",
+	de: "German",
+	it: "Italian",
+	pt: "Portuguese",
+	ru: "Russian",
+	nl: "Dutch",
+	tr: "Turkish",
+	ar: "Arabic",
+	hi: "Hindi",
+	pl: "Polish",
+	sv: "Swedish",
+	da: "Danish",
+	no: "Norwegian",
+	fi: "Finnish",
+	cs: "Czech",
+	uk: "Ukrainian",
+	hu: "Hungarian",
+	ro: "Romanian",
+	el: "Greek",
+	he: "Hebrew",
+	vi: "Vietnamese",
+	th: "Thai",
+	id: "Indonesian",
+};
+
+/**
+ * Romanized fallback label "<Language> · M" or "<Language> · F" — used
+ * for ar, hi, and any unknown language tag. Gender is rendered with the
+ * same single-letter abbreviation everywhere, so the label width is
+ * predictable across all fallback rows.
+ */
+export function formatRomanizedLabel(baseLang: string, gender: "M" | "F" | undefined): string {
+	const key = baseLang.toLowerCase();
+	const name = ROMANIZED_NAMES[key] ?? baseLang.toUpperCase();
+	if (!gender) return name;
+	return `${name} · ${gender}`;
+}

package/extensions/voice/ui-picker.ts

@@ -0,0 +1,209 @@
+/**
+ * Shared picker chassis (§3 of v7.1 plan).
+ *
+ * Three pickers (Language / Models / Voice) currently duplicate the same
+ * state machine in `settings-panel.ts`. This chassis encapsulates the
+ * common behavior: heading-aware navigation, search filtering with empty
+ * state, cursor preservation across filter changes, and a width-tier
+ * compact mode. Pickers feed it data; the chassis owns navigation.
+ *
+ * Contract (§3):
+ *   1. Headings are non-selectable. ↑↓ skip them.
+ *   2. Search filtering also skips headings: a heading appears iff at
+ *      least one row under it matches; otherwise drop the entire group.
+ *   3. Cursor restoration: when the search query changes, the cursor
+ *      moves to the first selectable row of the new view. When the
+ *      search clears, the cursor returns to the previously-active row
+ *      if visible, else first selectable.
+ *   4. Empty state: render-aware — `getViewModel()` returns
+ *      `{ kind: "empty" }` when no data rows match.
+ *   5. Page bounds: cursor wraps top-to-bottom only across selectable rows.
+ *   6. Width fallback: when compact mode is true, headings are dropped
+ *      from the view (the picker may still show group separators
+ *      elsewhere) so narrow terminals see only the data rows.
+ */
+
+/** A row in a picker — either a heading (non-selectable) or a data row. */
+export type PickerRow<T> =
+	| { readonly kind: "heading"; readonly label: string }
+	| { readonly kind: "data"; readonly value: T; readonly searchKey: string };
+
+/** Output passed to the renderer. Either an empty result or a viewport slice. */
+export type PickerView<T> =
+	| { readonly kind: "empty"; readonly query: string }
+	| {
+			readonly kind: "list";
+			readonly rows: ReadonlyArray<PickerRow<T>>;
+			readonly viewportStart: number;
+			readonly viewportEnd: number;
+			readonly totalSelectable: number;
+			readonly selectedIndex: number;
+			/** Index INTO `rows` of the currently-selected data row (≥0). */
+			readonly cursorRowIndex: number;
+	  };
+
+/** Per-call render input. */
+export interface PickerRenderInput {
+	/** Visible row budget for the body — usually 12 in 24-line overlays. */
+	readonly maxVisible: number;
+	/** True for narrow-terminal compact mode (drops headings from view). */
+	readonly compact: boolean;
+}
+
+/**
+ * State machine. Pickers create one of these per open session and call:
+ *   - `setRows(rows)` whenever the data source changes (e.g. after install)
+ *   - `setSearch(q)` on every keystroke
+ *   - `moveUp()` / `moveDown()` for navigation
+ *   - `selected()` to read the currently-highlighted data value
+ *   - `view(input)` to compute the renderable slice
+ *
+ * The chassis owns: search query, cursor index (over selectable rows
+ * only), viewport scrolling.
+ */
+export class PickerChassis<T> {
+	private rows: ReadonlyArray<PickerRow<T>> = [];
+	private query = "";
+	/** Cursor index INTO the filtered selectable subset. */
+	private cursor = 0;
+	/** Sticky pre-search cursor — used to restore on search clear. */
+	private preSearchValue: T | null = null;
+
+	setRows(rows: ReadonlyArray<PickerRow<T>>): void {
+		this.rows = rows;
+		this.clampCursor();
+	}
+
+	getQuery(): string {
+		return this.query;
+	}
+
+	setSearch(q: string): void {
+		const wasEmpty = this.query.length === 0;
+		const isEmpty = q.length === 0;
+		if (wasEmpty && !isEmpty) {
+			// Entering search — remember current selection so we can
+			// restore on clear.
+			this.preSearchValue = this.selected();
+		}
+		this.query = q;
+		this.cursor = 0; // every search change resets to first match
+		if (isEmpty && this.preSearchValue != null) {
+			// Restore cursor to previously-active value if still present.
+			const filtered = this.filteredSelectable();
+			const idx = filtered.findIndex((r) => r.value === this.preSearchValue);
+			if (idx >= 0) this.cursor = idx;
+			this.preSearchValue = null;
+		}
+	}
+
+	appendSearchChar(ch: string): void {
+		this.setSearch(this.query + ch);
+	}
+
+	backspaceSearch(): void {
+		if (this.query.length === 0) return;
+		this.setSearch(this.query.slice(0, -1));
+	}
+
+	clearSearch(): void {
+		this.setSearch("");
+	}
+
+	moveUp(): void {
+		const n = this.filteredSelectable().length;
+		if (n === 0) return;
+		this.cursor = this.cursor === 0 ? n - 1 : this.cursor - 1;
+	}
+
+	moveDown(): void {
+		const n = this.filteredSelectable().length;
+		if (n === 0) return;
+		this.cursor = this.cursor === n - 1 ? 0 : this.cursor + 1;
+	}
+
+	/** Move cursor to the first selectable whose `value === target`. */
+	selectValue(target: T): void {
+		const filtered = this.filteredSelectable();
+		const idx = filtered.findIndex((r) => r.value === target);
+		if (idx >= 0) this.cursor = idx;
+	}
+
+	/** Currently-highlighted data value, or null when no rows match. */
+	selected(): T | null {
+		const filtered = this.filteredSelectable();
+		return filtered[this.cursor]?.value ?? null;
+	}
+
+	/** Compute the renderable view: heading-aware, viewport-windowed. */
+	view(input: PickerRenderInput): PickerView<T> {
+		const filteredAll = this.filteredView(input.compact);
+		const selectable = filteredAll.filter((r): r is { kind: "data"; value: T; searchKey: string } => r.kind === "data");
+		if (selectable.length === 0) {
+			return { kind: "empty", query: this.query };
+		}
+		const sel = Math.min(this.cursor, selectable.length - 1);
+		const selectedValue = selectable[sel]!.value;
+		const cursorRowIndex = filteredAll.findIndex((r) => r.kind === "data" && r.value === selectedValue);
+
+		// Center the viewport on the cursor.
+		const total = filteredAll.length;
+		let start = Math.max(0, cursorRowIndex - Math.floor(input.maxVisible / 2));
+		let end = Math.min(start + input.maxVisible, total);
+		if (end - start < input.maxVisible) start = Math.max(0, end - input.maxVisible);
+
+		return {
+			kind: "list",
+			rows: filteredAll.slice(start, end),
+			viewportStart: start,
+			viewportEnd: end,
+			totalSelectable: selectable.length,
+			selectedIndex: sel,
+			cursorRowIndex,
+		};
+	}
+
+	private clampCursor(): void {
+		const n = this.filteredSelectable().length;
+		if (n === 0) this.cursor = 0;
+		else if (this.cursor >= n) this.cursor = n - 1;
+	}
+
+	private rowMatches(r: PickerRow<T>): boolean {
+		if (r.kind === "heading") return false;
+		if (this.query.length === 0) return true;
+		return r.searchKey.toLowerCase().includes(this.query.toLowerCase());
+	}
+
+	/** Filtered subset, headings retained when at least one child row matches. */
+	private filteredView(compact: boolean): ReadonlyArray<PickerRow<T>> {
+		const out: PickerRow<T>[] = [];
+		// Walk groups: stash the most recent heading; emit it inline at
+		// first matching child, then clear so subsequent matches in the
+		// same group don't re-emit. In compact mode, never emit
+		// headings (narrow terminals get a flat list).
+		let pendingHeading: PickerRow<T> | null = null;
+		for (const r of this.rows) {
+			if (r.kind === "heading") {
+				pendingHeading = r;
+				continue;
+			}
+			if (this.rowMatches(r)) {
+				if (pendingHeading && !compact) {
+					out.push(pendingHeading);
+				}
+				pendingHeading = null;
+				out.push(r);
+			}
+		}
+		return out;
+	}
+
+	private filteredSelectable(): ReadonlyArray<{ kind: "data"; value: T; searchKey: string }> {
+		const out: { kind: "data"; value: T; searchKey: string }[] = [];
+		for (const r of this.rows) {
+			if (r.kind === "data" && this.rowMatches(r)) out.push(r);
+		}
+		return out;
+	}
+}