pi-voicekit 0.1.0

package/extensions/voice/ui-render-ticker.ts

@@ -0,0 +1,171 @@
+/**
+ * Single shared 10 Hz frame coalescer for animated widgets — §2 of the
+ * v7.1 plan.
+ *
+ * Why this exists: three independent `setInterval(…, 100ms)` widgets
+ * drift relative to each other and each call `ctx.ui.setWidget()`
+ * separately, causing 20-30 partial re-renders per second instead of 10
+ * cohesive ones. With this ticker, every animated widget subscribes to
+ * a single `setInterval`; all `setWidget` calls land in the same JS
+ * turn so the Pi TUI sees one batch of slot updates per tick.
+ *
+ * Failure isolation (Codex v4 #2 + Gemini v3 #2):
+ *   - Subscriber `tick()` is wrapped in try/catch — one throwing widget
+ *     cannot crash the loop.
+ *   - 3 consecutive throws auto-unsubscribe the widget. The ticker
+ *     then calls `sub.dispose?.()` to evict its slot — but the
+ *     `dispose()` invocation is ITSELF wrapped in try/catch, so a
+ *     widget whose state is corrupted enough to throw on render
+ *     (likely also throws on dispose) does not crash the ticker.
+ *
+ * Lifetime:
+ *   - Lazy start: `setInterval` is created on first subscriber.
+ *   - Lazy stop: `setInterval` is cleared on last unsubscribe.
+ *   - `dispose()` clears all subscribers + the interval. Idempotent.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+const VOICE_DEBUG = !!process.env.PI_VOICE_DEBUG;
+const VOICE_LOG_FILE = path.join(os.tmpdir(), "pi-voice-debug.log");
+
+function debug(...args: unknown[]) {
+	if (!VOICE_DEBUG) return;
+	const ts = new Date().toISOString().split("T")[1];
+	const line = `[voice-ticker ${ts}] ${args.map((a) => (typeof a === "object" ? JSON.stringify(a) : String(a))).join(" ")}\n`;
+	try {
+		fs.appendFileSync(VOICE_LOG_FILE, line);
+	} catch {
+		/* best-effort */
+	}
+}
+
+/** Tick frequency — 10 Hz keeps animation smooth without burning CPU. */
+const TICK_INTERVAL_MS = 100;
+
+/** Throws-in-a-row threshold before auto-eviction. */
+const THROW_THRESHOLD = 3;
+
+/**
+ * Subscriber descriptor — explicit ownership (Codex v3 #2). Pass
+ * `dispose` only when the ticker should evict this subscriber's slot
+ * after auto-unsubscribe; ad-hoc test subscribers can omit it.
+ */
+export interface TickerSubscriber {
+	/** Called once per tick (10 Hz). May throw; the ticker isolates. */
+	readonly tick: () => void;
+	/**
+	 * Optional ownership hook. If present and the subscriber is
+	 * auto-unsubscribed after `THROW_THRESHOLD` consecutive throws,
+	 * the ticker calls `dispose()` to tear down the broken widget's
+	 * slot. The call is wrapped in `try/catch` so a corrupted widget
+	 * cannot crash the ticker.
+	 */
+	readonly dispose?: () => void;
+	/** Optional debug label, surfaced in `voiceDebug()` output. */
+	readonly label?: string;
+}
+
+export interface RenderTicker {
+	/** Subscribe. Returns an unsubscribe fn — calling it is idempotent. */
+	subscribe(subscriber: TickerSubscriber): () => void;
+	/** Active subscriber count. Test/debug. */
+	refCount(): number;
+	/** Tear down the ticker — clears interval + subscribers. Idempotent. */
+	dispose(): void;
+}
+
+interface SubEntry {
+	readonly sub: TickerSubscriber;
+	throwsInARow: number;
+	unsubscribed: boolean;
+}
+
+class RenderTickerImpl implements RenderTicker {
+	private readonly entries = new Set<SubEntry>();
+	private timer: ReturnType<typeof setInterval> | null = null;
+	private disposed = false;
+
+	subscribe(subscriber: TickerSubscriber): () => void {
+		if (this.disposed) {
+			// Late subscriber after dispose — give them a no-op
+			// unsubscriber and don't start the timer.
+			return () => {};
+		}
+		const entry: SubEntry = { sub: subscriber, throwsInARow: 0, unsubscribed: false };
+		this.entries.add(entry);
+		if (this.timer == null) this.startTimer();
+		return () => {
+			if (entry.unsubscribed) return;
+			entry.unsubscribed = true;
+			this.entries.delete(entry);
+			if (this.entries.size === 0) this.stopTimer();
+		};
+	}
+
+	refCount(): number {
+		return this.entries.size;
+	}
+
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.stopTimer();
+		// Mark all entries unsubscribed so any retained closure that
+		// still calls its unsubscribe fn is a no-op.
+		for (const entry of this.entries) entry.unsubscribed = true;
+		this.entries.clear();
+	}
+
+	private startTimer(): void {
+		this.timer = setInterval(() => this.runTick(), TICK_INTERVAL_MS);
+		// Don't keep the event loop alive just for animation.
+		(this.timer as any)?.unref?.();
+	}
+
+	private stopTimer(): void {
+		if (this.timer != null) {
+			clearInterval(this.timer);
+			this.timer = null;
+		}
+	}
+
+	private runTick(): void {
+		// Snapshot entries before iterating — auto-eviction during the
+		// loop would otherwise mutate the live Set. Snapshot also lets
+		// us safely call dispose() on evicted entries after the loop.
+		const snapshot = Array.from(this.entries);
+		const evict: SubEntry[] = [];
+		for (const entry of snapshot) {
+			if (entry.unsubscribed) continue;
+			try {
+				entry.sub.tick();
+				entry.throwsInARow = 0;
+			} catch (err) {
+				entry.throwsInARow++;
+				debug("tick threw", entry.sub.label ?? "(unlabeled)", entry.throwsInARow, "/", THROW_THRESHOLD, String(err));
+				if (entry.throwsInARow >= THROW_THRESHOLD) evict.push(entry);
+			}
+		}
+		for (const entry of evict) {
+			if (entry.unsubscribed) continue;
+			entry.unsubscribed = true;
+			this.entries.delete(entry);
+			// Eviction dispose() — Gemini v3 #2: try/catch around
+			// dispose itself so a broken widget can't crash the ticker.
+			try {
+				entry.sub.dispose?.();
+			} catch (err) {
+				debug("eviction dispose threw", entry.sub.label ?? "(unlabeled)", String(err));
+			}
+		}
+		if (this.entries.size === 0) this.stopTimer();
+	}
+}
+
+/** Construct a fresh ticker. One per session is the expected shape. */
+export function makeRenderTicker(): RenderTicker {
+	return new RenderTickerImpl();
+}

package/extensions/voice/ui-widget-base.ts

@@ -0,0 +1,219 @@
+/**
+ * Widget ownership model for the v7.1 Settings UI redesign — §1 of the
+ * approved plan, hardened across v3/v4/v5 reviews.
+ *
+ * Why this exists: `ctx.ui.setWidget(key, content)` writes to a key-slotted
+ * store. Two widgets with different keys coexist; two widgets with the
+ * same key overwrite. v7.1 introduces install + playback widgets that
+ * must coexist with the recording widget, so we need a registry that
+ * (a) prevents same-key collision, (b) lets completed widgets evict
+ * themselves so the registry doesn't leak across long sessions, and
+ * (c) survives misbehaving widgets that throw on disposal.
+ *
+ * The contract was reviewed and SHIP'd by both Codex and Gemini at v5.
+ * Six load-bearing properties of the implementation:
+ *
+ *   1. `register(w)` synchronously calls `existing.dispose()` before
+ *      swapping in `w`, so a same-key handover never races.
+ *   2. `unregister(key, owner)` is OWNER-CHECKED — only deletes the Map
+ *      entry if it currently points to `owner`. A stale dispose path
+ *      (e.g. an old install widget's queued cleanup running after a
+ *      newer same-key widget was registered) cannot evict the
+ *      successor.
+ *   3. `disposeAll()` iterates a CLONED snapshot of values, because
+ *      each widget's `dispose()` will synchronously call back into
+ *      `unregister(key, this)`, mutating the underlying Map.
+ *   4. Each `dispose()` call inside `disposeAll()` is wrapped in
+ *      `try/catch` so one throwing widget cannot abort cleanup for
+ *      the rest.
+ *   5. `installWidgetKey(modelId)` produces per-model-id keys so two
+ *      installs for different models occupy different slots.
+ *   6. The base class's `dispose()` ordering — set `disposed` true
+ *      before any cleanup work — is enforced via `BaseDisposableWidget`,
+ *      so subclasses cannot accidentally clear timers / slots before
+ *      flipping the flag.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+const VOICE_DEBUG = !!process.env.PI_VOICE_DEBUG;
+const VOICE_LOG_FILE = path.join(os.tmpdir(), "pi-voice-debug.log");
+
+function debug(...args: unknown[]) {
+	if (!VOICE_DEBUG) return;
+	const ts = new Date().toISOString().split("T")[1];
+	const line = `[voice-ui ${ts}] ${args.map((a) => (typeof a === "object" ? JSON.stringify(a) : String(a))).join(" ")}\n`;
+	try {
+		fs.appendFileSync(VOICE_LOG_FILE, line);
+	} catch {
+		/* best-effort */
+	}
+}
+
+/** A widget that owns one slot key and can be torn down. */
+export interface DisposableWidget {
+	/**
+	 * Stable widget-key the slot writes to. Install widgets use
+	 * `installWidgetKey(modelId)`; recording uses `"voice-recording"`;
+	 * playback uses `"voice-tts-playback"`.
+	 */
+	readonly key: string;
+	/** Tear down the widget. MUST be idempotent (re-entry returns early). */
+	dispose(): void;
+}
+
+/**
+ * Registry that owns lifetime of every active widget. One per session,
+ * created in `session_start` and drained in `voiceCleanup`.
+ */
+export interface WidgetRegistry {
+	/**
+	 * Register a widget under its `key`. If a widget with the same
+	 * key is already registered, that incumbent's `dispose()` is
+	 * called synchronously BEFORE `w` takes the slot — preventing
+	 * same-key collision.
+	 */
+	register(w: DisposableWidget): void;
+	/**
+	 * Owner-checked eviction (Codex v4 #3). Removes the Map entry for
+	 * `key` ONLY if the current entry is `owner` (identity-equal). If
+	 * a stale dispose path runs after a NEW widget has taken the same
+	 * key, the unregister is a no-op and the new widget stays bound.
+	 * Calls with absent `key` or mismatched owner are no-ops.
+	 */
+	unregister(key: string, owner: DisposableWidget): void;
+	/**
+	 * Drains the registry. Iterates a CLONED snapshot of values
+	 * (Gemini v4 implementation note) because each `dispose()`
+	 * re-enters `unregister`. Each `dispose()` is wrapped in
+	 * `try/catch` so one throwing widget cannot abort cleanup for
+	 * the rest. Idempotent — safe to call twice.
+	 */
+	disposeAll(): void;
+	/** Active widget count. Test/debug only. */
+	size(): number;
+}
+
+class WidgetRegistryImpl implements WidgetRegistry {
+	private readonly entries = new Map<string, DisposableWidget>();
+
+	register(w: DisposableWidget): void {
+		const existing = this.entries.get(w.key);
+		if (existing && existing !== w) {
+			// Synchronous dispose of incumbent before swap — same-key
+			// handover never races. Wrap in try/catch so a throwing
+			// incumbent cannot prevent the new widget from registering.
+			try {
+				existing.dispose();
+			} catch (err) {
+				debug("register: incumbent dispose threw", w.key, String(err));
+			}
+		}
+		this.entries.set(w.key, w);
+	}
+
+	unregister(key: string, owner: DisposableWidget): void {
+		const cur = this.entries.get(key);
+		if (cur === owner) this.entries.delete(key);
+		// else: stale call — successor already took the slot, do nothing.
+	}
+
+	disposeAll(): void {
+		// Cloned snapshot — each dispose() re-enters unregister() and
+		// mutates the underlying Map. Iterating a snapshot guarantees
+		// no widget is skipped during the cascade.
+		const snapshot = Array.from(this.entries.values());
+		for (const w of snapshot) {
+			try {
+				w.dispose();
+			} catch (err) {
+				debug("disposeAll: dispose threw", w.key, String(err));
+			}
+		}
+		// Defensive: any widget that didn't unregister itself (buggy
+		// dispose) is force-evicted so a later disposeAll() is truly idempotent.
+		this.entries.clear();
+	}
+
+	size(): number {
+		return this.entries.size;
+	}
+}
+
+/** Construct a fresh registry. One per session is the expected shape. */
+export function makeWidgetRegistry(): WidgetRegistry {
+	return new WidgetRegistryImpl();
+}
+
+/**
+ * Per-instance install widget key. Concurrent installs of different
+ * model ids occupy different slots (`voice-tts-install:kitten-…` vs
+ * `voice-tts-install:kokoro-…`). Same-id installs are already
+ * serialized by `ensureTtsModelInstalled`'s in-flight Map.
+ */
+export function installWidgetKey(modelId: string): string {
+	return `voice-tts-install:${modelId}`;
+}
+
+/** Stable widget keys for non-install widgets. */
+export const WIDGET_KEY = {
+	recording: "voice-recording",
+	ttsPlayback: "voice-tts-playback",
+} as const;
+
+/**
+ * Optional base class enforcing the §1 dispose ordering. Subclasses
+ * implement `onDispose()` for their type-specific cleanup; the base
+ * runs the universal sequence around it.
+ *
+ * Order (Codex v4 #2 + Codex v5 nit):
+ *   (a) check `if (this.disposed) return;` — idempotency on PRIOR state
+ *   (b) set `this.disposed = true` BEFORE any cleanup work
+ *   (c) call `this.unsubTicker?.()` so ticker refcount drops
+ *   (d) `onDispose()` for subclass-specific cleanup (timers, etc.)
+ *   (e) clear the slot via the injected `clearSlot()` callback
+ *   (f) `registry.unregister(this.key, this)` — owner-checked eviction
+ */
+export abstract class BaseDisposableWidget implements DisposableWidget {
+	abstract readonly key: string;
+	protected disposed = false;
+	protected unsubTicker: (() => void) | null = null;
+	protected readonly registry: WidgetRegistry;
+	protected readonly clearSlot: () => void;
+
+	constructor(registry: WidgetRegistry, clearSlot: () => void) {
+		this.registry = registry;
+		this.clearSlot = clearSlot;
+	}
+
+	/** Subclass cleanup hook. Called between unsubTicker and clearSlot. */
+	protected onDispose(): void {}
+
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true;
+		try {
+			this.unsubTicker?.();
+		} catch (err) {
+			debug("dispose: unsubTicker threw", this.key, String(err));
+		}
+		this.unsubTicker = null;
+		try {
+			this.onDispose();
+		} catch (err) {
+			debug("dispose: onDispose threw", this.key, String(err));
+		}
+		try {
+			this.clearSlot();
+		} catch (err) {
+			debug("dispose: clearSlot threw", this.key, String(err));
+		}
+		try {
+			this.registry.unregister(this.key, this);
+		} catch (err) {
+			debug("dispose: unregister threw", this.key, String(err));
+		}
+	}
+}

package/extensions/voice/ui-width.ts

@@ -0,0 +1,112 @@
+/**
+ * Visual-width and width-tier helpers for the v7.1 Settings UI.
+ *
+ * `visualWidth(s)` returns terminal column count for a string, treating
+ * East-Asian Wide / Fullwidth codepoints as 2 columns and everything else
+ * as 1. Iteration is done in UTF-32 code points (via `for…of`) so surrogate
+ * pairs (`String.length 2`, single code point) count as one wide unit, not
+ * two halves of nothing.
+ *
+ * Hand-curated EAW Wide/Fullwidth ranges from Unicode 15.1 EastAsianWidth.txt
+ * — only the blocks pi-listen actually ships labels for (CJK, Hangul,
+ * Hiragana/Katakana, fullwidth ASCII). Hindi/Devanagari and Arabic
+ * intentionally NOT covered: per the v7.1 plan their voices are rendered
+ * with romanized labels, so a precise width here is unnecessary and a
+ * partial width table would silently mis-align their rows. Keeping the
+ * table small also keeps the zero-dependency promise.
+ *
+ * Width tiers (§10): three buckets — "wide" (≥80), "mid" (60..79), "narrow"
+ * (<60 — hard block at the panel level).
+ */
+
+// Hand-curated EAW Wide / Fullwidth ranges, sorted ascending by `lo` so the
+// scanner can early-exit on `cp < lo`. Comments label the Unicode block.
+const EAW_WIDE_RANGES: ReadonlyArray<readonly [number, number]> = [
+	[0x1100, 0x11ff], // Hangul Jamo
+	[0x3000, 0x30ff], // CJK Symbols & Punctuation, Hiragana, Katakana
+	[0x3100, 0x312f], // Bopomofo
+	[0x3130, 0x318f], // Hangul Compatibility Jamo
+	[0x31a0, 0x31bf], // Bopomofo Extended
+	[0x31c0, 0x31ef], // CJK Strokes
+	[0x31f0, 0x31ff], // Katakana Phonetic Extensions
+	[0x3400, 0x4dbf], // CJK Unified Ideographs Extension A
+	[0x4e00, 0x9fff], // CJK Unified Ideographs (main block)
+	[0xac00, 0xd7a3], // Hangul Syllables (Korean)
+	[0xf900, 0xfaff], // CJK Compatibility Ideographs
+	[0xff01, 0xff60], // Fullwidth ASCII
+	[0xffe0, 0xffe6], // Fullwidth signs
+	[0x20000, 0x2fffd], // CJK Unified Ideographs Extension B–F
+	[0x30000, 0x3fffd], // CJK Unified Ideographs Extension G
+];
+
+function isWide(cp: number): boolean {
+	for (const [lo, hi] of EAW_WIDE_RANGES) {
+		if (cp >= lo && cp <= hi) return true;
+		if (cp < lo) return false; // ranges are sorted
+	}
+	return false;
+}
+
+/**
+ * Visual width of `s` in terminal columns. Surrogate pairs count as one
+ * code point. EAW Wide/Fullwidth code points count as 2; everything else
+ * as 1. Combining marks are NOT subtracted (Devanagari/Arabic are out of
+ * scope per §8) — pass romanized labels for those scripts.
+ */
+export function visualWidth(s: string): number {
+	let w = 0;
+	for (const ch of s) {
+		const cp = ch.codePointAt(0) ?? 0;
+		w += isWide(cp) ? 2 : 1;
+	}
+	return w;
+}
+
+/**
+ * Truncate `s` to fit within `max` columns, appending `…` (1 column) when
+ * truncation occurs. Uses code-point iteration so surrogate pairs and
+ * wide characters are never sliced mid-glyph.
+ */
+export function truncateToVisualWidth(s: string, max: number): string {
+	if (max <= 0) return "";
+	if (visualWidth(s) <= max) return s;
+	if (max === 1) return "…";
+	let w = 0;
+	let out = "";
+	for (const ch of s) {
+		const cw = isWide(ch.codePointAt(0) ?? 0) ? 2 : 1;
+		if (w + cw > max - 1) break; // reserve 1 col for ellipsis
+		out += ch;
+		w += cw;
+	}
+	return out + "…";
+}
+
+/** Pad `s` on the right (with spaces) to occupy exactly `width` columns. */
+export function padRightVisual(s: string, width: number): string {
+	const w = visualWidth(s);
+	if (w >= width) return s;
+	return s + " ".repeat(width - w);
+}
+
+/** Pad `s` on the left (with spaces) to occupy exactly `width` columns. */
+export function padLeftVisual(s: string, width: number): string {
+	const w = visualWidth(s);
+	if (w >= width) return s;
+	return " ".repeat(width - w) + s;
+}
+
+/** Width tier labels — see §10 of the v7.1 plan. */
+export type WidthTier = "wide" | "mid" | "narrow";
+
+/** Map a column count to a tier. ≥80 wide, 60..79 mid, <60 narrow (block). */
+export function widthTier(cols: number): WidthTier {
+	if (cols >= 80) return "wide";
+	if (cols >= 60) return "mid";
+	return "narrow";
+}
+
+/** True when the panel should hard-block rendering (§10). */
+export function isPanelTooNarrow(cols: number): boolean {
+	return widthTier(cols) === "narrow";
+}