pi-voicekit 0.1.0

package/extensions/voice/tts-onboarding-overlay.ts

@@ -0,0 +1,186 @@
+/**
+ * Rich first-run onboarding overlay for TTS — §9 of the v7.1 plan.
+ *
+ * Replaces the v7.0 notify-based hint with a focused overlay that
+ * shows the recommendation, the install size, and three explicit
+ * actions ([enter] try it / [m] pick another / [esc] skip). Per the
+ * §9 event-ordering contract:
+ *
+ *   - All three actions mark `ttsOnboardingShown = true` BEFORE any
+ *     async work so a failed install/cancel never prompts the user
+ *     again.
+ *   - `[enter]` returns `{ kind: "test" }` — the caller runs
+ *     /voice-speak-test which auto-installs the recommended model.
+ *   - `[m]` returns `{ kind: "pickModel" }` — caller opens settings
+ *     panel on the Speak tab so the user can browse alternatives.
+ *   - `[esc]` returns `{ kind: "skip" }` — silent dismissal.
+ *
+ * Visual design (no emoji per v7.1 hard constraint):
+ *
+ *   ┌─ pi-listen TTS ─────────────────────────────────────────────┐
+ *   │                                                              │
+ *   │   Voice output ready.                                        │
+ *   │                                                              │
+ *   │   ● Recommended:  Kitten Nano v0.2  (25 MB, en)              │
+ *   │     Smallest English TTS — sub-real-time on M-series         │
+ *   │                                                              │
+ *   │   Status:         not installed — press [↵] to download      │
+ *   │                                                              │
+ *   │   [↵] Try it now  [m] Pick another  [esc] Skip               │
+ *   └──────────────────────────────────────────────────────────────┘
+ */
+
+import { matchesKey, Key } from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { recommendDefaultModel, isTtsModelInstalled, getTtsModel } from "./tts-local-models";
+import { ICON } from "./ui-icons";
+import { isPanelTooNarrow, visualWidth, padRightVisual } from "./ui-width";
+
+export type OnboardingResult = { kind: "test" } | { kind: "pickModel" } | { kind: "skip" };
+
+export interface OnboardingOverlayDeps {
+	/** Active locale (e.g. "en", "zh") for recommendation. */
+	systemLocale: string | undefined;
+	/** Optional Pi theme for color routing. */
+	theme?: Theme;
+}
+
+/**
+ * Pi `Component`-shaped class — pass into `ctx.ui.custom()` directly.
+ * `done` is provided by the caller's factory closure to resolve the
+ * outer promise.
+ */
+export class TtsOnboardingOverlay {
+	private readonly deps: OnboardingOverlayDeps;
+	private readonly done: (result: OnboardingResult) => void;
+	private resolved = false;
+
+	constructor(deps: OnboardingOverlayDeps, done: (result: OnboardingResult) => void) {
+		this.deps = deps;
+		this.done = done;
+	}
+
+	render(width: number): string[] {
+		// v7.1 §10/§13: hard-block below 60 cols. The overlay is
+		// pure-content; below that, we render a dim "resize" hint and
+		// expose the same three actions as keys without the chrome.
+		if (isPanelTooNarrow(width)) {
+			return this.renderNarrow();
+		}
+
+		const w = Math.max(60, Math.min(width - 2, 80));
+		const innerW = w - 4;
+		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 success = (s: string) => (t ? t.fg("success", s) : s);
+		const warning = (s: string) => (t ? t.fg("warning", s) : s);
+
+		const recommendation = recommendDefaultModel(this.deps.systemLocale ?? "en");
+		let recModel;
+		try {
+			recModel = getTtsModel(recommendation.modelId);
+		} catch {
+			recModel = undefined;
+		}
+		const installed = recModel ? isTtsModelInstalled(recModel.id) : false;
+
+		const lines: string[] = [];
+		// v7.2: rounded corners for modal feel. Title sits inline on the
+		// top edge with thin spacing so the box reads as a "sheet"
+		// rather than a hard frame (HIG modal aesthetic).
+		const top = `${ICON.boxRoundedTL}${ICON.boxH.repeat(2)} ${bold("pi-listen TTS")} ${ICON.boxH.repeat(Math.max(0, innerW - 16))}${ICON.boxRoundedTR}`;
+		const bottom = `${ICON.boxRoundedBL}${ICON.boxH.repeat(innerW)}${ICON.boxRoundedBR}`;
+		const hr = `${ICON.boxV}${" ".repeat(innerW)}${ICON.boxV}`;
+		const row = (s: string): string => {
+			// CJK-aware pad-right (Codex final-review nit): use visualWidth
+			// not String.length so wide glyphs in Chinese/Japanese/Korean
+			// recommendation copy align correctly.
+			const w = visualWidth(s);
+			if (w <= innerW) return `${ICON.boxV}${padRightVisual(s, innerW)}${ICON.boxV}`;
+			return `${ICON.boxV}${s.slice(0, innerW)}${ICON.boxV}`;
+		};
+
+		lines.push(top);
+		lines.push(hr);
+		lines.push(row(`  ${accent("Voice output ready.")}`));
+		lines.push(hr);
+
+		if (recModel) {
+			const langs = recModel.languages.length > 1 ? `${recModel.languages.length} langs` : recModel.languages[0];
+			lines.push(
+				row(
+					`  ${success(ICON.bulletActive)} ${dim("Recommended:")}  ${accent(recModel.name)} ${dim(`(${recModel.size}, ${langs})`)}`
+				)
+			);
+			lines.push(row(`    ${dim(recModel.notes)}`));
+		} else {
+			lines.push(row(`  ${success(ICON.bulletActive)} ${dim("Recommended:")}  ${accent(recommendation.modelId)}`));
+		}
+
+		lines.push(hr);
+
+		const statusLabel = installed
+			? success("ready")
+			: warning(`not installed ${ICON.middot} press ${accent("[↵]")} to download`);
+		lines.push(row(`  ${dim("Status:")}        ${statusLabel}`));
+
+		if (recommendation.fallback) {
+			lines.push(hr);
+			lines.push(
+				row(
+					`  ${dim(`Note: ${this.deps.systemLocale ?? "your locale"} has no native voice — English fallback chosen.`)}`
+				)
+			);
+		}
+
+		lines.push(hr);
+		const hint = `  ${accent("[↵]")} ${dim("Try it now")}   ${accent("[m]")} ${dim("Pick another")}   ${accent("[esc]")} ${dim("Skip")}`;
+		lines.push(row(hint));
+		lines.push(bottom);
+		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);
+		return [
+			` ${accent("pi-listen TTS")}`,
+			` ${dim("Voice output ready. Resize to ≥60 cols for the full hint.")}`,
+			` ${accent("[↵]")} ${dim("test")}   ${accent("[m]")} ${dim("pick")}   ${accent("[esc]")} ${dim("skip")}`,
+		];
+	}
+
+	handleInput(data: string): void {
+		if (this.resolved) return;
+		if (matchesKey(data, Key.enter)) {
+			this.resolve({ kind: "test" });
+			return;
+		}
+		if (matchesKey(data, Key.escape)) {
+			this.resolve({ kind: "skip" });
+			return;
+		}
+		// Lowercase 'm' or 'M' picks model
+		if (data === "m" || data === "M") {
+			this.resolve({ kind: "pickModel" });
+			return;
+		}
+	}
+
+	invalidate(): void {
+		/* render is uncached */
+	}
+
+	private resolve(result: OnboardingResult): void {
+		if (this.resolved) return;
+		this.resolved = true;
+		try {
+			this.done(result);
+		} catch {
+			/* never fail closure */
+		}
+	}
+}

package/extensions/voice/tts-onboarding.ts

@@ -0,0 +1,87 @@
+/**
+ * First-run TTS onboarding helper.
+ *
+ * v7.0.0 ships the lightweight version: when a user enables TTS for the
+ * first time (and onboarding hasn't been completed), the orchestrator
+ * shows a single notify() with the smart-default recommendation and
+ * tells the user how to either accept it (run /voice-speak-test) or
+ * customize (run /voice-speak-models).
+ *
+ * Why not a multi-step picker overlay (the v7 plan's full vision):
+ *   - The settings panel already exposes every knob with proper UX
+ *   - A first-run popup that hijacks the editor on every initial enable
+ *     is annoying for advanced users who already configured things via
+ *     settings.json
+ *   - The lightweight surface is honest: "here's the recommendation,
+ *     here's where to change it" — and it composes with the rest of
+ *     the v7 surface (Speak tab, /voice-speak-info)
+ *
+ * If field reports show users want a richer flow, we can swap this
+ * notify-based version for a `ctx.ui.custom()` overlay in v7.1
+ * without changing any other code path.
+ */
+
+import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { VoiceConfig, VoiceSettingsScope } from "./config";
+import type { DeviceProfile } from "./device";
+import { recommendDefaultModel, isTtsModelInstalled, getTtsModel } from "./tts-local-models";
+
+type NotifyContext = ExtensionContext | ExtensionCommandContext;
+
+export interface OnboardTtsOpts {
+	ctx: NotifyContext;
+	config: VoiceConfig;
+	device: DeviceProfile;
+	cwd: string;
+	saveConfig: (config: VoiceConfig, scope: VoiceSettingsScope, cwd: string) => void;
+}
+
+/**
+ * Run the first-run TTS onboarding hint. Idempotent — only shows the
+ * hint once per config (`config.onboarding.completed` controls the
+ * generic onboarding flag; we co-opt a parallel `ttsOnboardingShown`
+ * marker on the config to avoid spamming the hint on every enable).
+ *
+ * Returns true if the hint was shown this call.
+ */
+export function maybeShowTtsOnboarding(opts: OnboardTtsOpts): boolean {
+	const { ctx, config, device, cwd, saveConfig } = opts;
+	if (!ctx.hasUI) return false;
+	if ((config as any).ttsOnboardingShown) return false;
+
+	const recommendation = recommendDefaultModel(device.systemLocale ?? "en");
+	let recModel;
+	try {
+		recModel = getTtsModel(recommendation.modelId);
+	} catch {
+		recModel = undefined;
+	}
+	const installed = isTtsModelInstalled(recommendation.modelId);
+
+	const lines = [
+		"TTS enabled — voice output for Pi.",
+		"",
+		`  ${recommendation.reason}`,
+		"",
+		recModel
+			? `  Recommended:  ${recModel.name} (${recModel.size}, ${recModel.languages.join("/")})`
+			: `  Recommended:  ${recommendation.modelId}`,
+		`  Status:       ${installed ? "ready ✓" : `not installed — first speak downloads ${recModel?.size ?? "model"}`}`,
+		"",
+		"  Try it:       /voice-speak-test",
+		"  Pick another: /voice-speak-models  (or /voice-settings → Speak tab)",
+		"  Diagnose:     /voice-speak-info",
+		"  Disable:      /voice-speak-toggle",
+	];
+	if (recommendation.fallback) {
+		lines.push("");
+		lines.push(`  Note: ${device.systemLocale ?? "your locale"} has no built-in voice — English fallback chosen.`);
+	}
+
+	ctx.ui.notify(lines.join("\n"), "info");
+
+	// Mark the hint as shown (and persist) so subsequent enables are quiet.
+	(config as any).ttsOnboardingShown = true;
+	saveConfig(config, config.scope === "project" ? "project" : "global", cwd);
+	return true;
+}

package/extensions/voice/tts-playback-indicator.ts

@@ -0,0 +1,127 @@
+/**
+ * Honest playback state indicator — §6 of v7.1 plan.
+ *
+ * v1 of the plan proposed a fake amplitude meter; both Codex and Gemini
+ * flagged it as misleading (a bouncing meter would imply audio is
+ * playing even when the player is muted, stuck, or failed). v7.1 ships
+ * a state spinner only:
+ *
+ *   ◓ Synthesizing · 1s
+ *   ◑ Playing · 4s · [esc] stop
+ *   (mounted only while state ∈ {synthesizing, playing}; dismissed on idle)
+ *
+ * Rotating spinner phase comes from the shared `RenderTicker`, so it
+ * stays in phase with any concurrently-mounted install bar — no
+ * tearing.
+ *
+ * v7.2 may add a real PCM amplitude bar ALONGSIDE the state word once
+ * the streaming-playback path emits real levels; until then the
+ * label-only design keeps every signal honest.
+ */
+
+import { BaseDisposableWidget, type WidgetRegistry, WIDGET_KEY } from "./ui-widget-base";
+import type { RenderTicker } from "./ui-render-ticker";
+import { spinnerFrame } from "./ui-icons";
+import type { InstallWidgetUI } from "./tts-install-progress";
+
+export type PlaybackState = "idle" | "synthesizing" | "playing";
+
+export interface TtsPlaybackIndicatorOpts {
+	readonly ui: InstallWidgetUI;
+	readonly registry: WidgetRegistry;
+	readonly ticker: RenderTicker;
+	readonly onStop?: () => void;
+}
+
+export class TtsPlaybackIndicator extends BaseDisposableWidget {
+	readonly key = WIDGET_KEY.ttsPlayback;
+	private readonly ui: InstallWidgetUI;
+	private readonly onStop?: () => void;
+	private state: PlaybackState = "idle";
+	private startedAt: number | null = null;
+	private spinnerTick = 0;
+
+	constructor(opts: TtsPlaybackIndicatorOpts) {
+		super(opts.registry, () => opts.ui.setWidget(WIDGET_KEY.ttsPlayback, undefined));
+		this.ui = opts.ui;
+		this.onStop = opts.onStop;
+		this.unsubTicker = opts.ticker.subscribe({
+			tick: () => this.onTick(),
+			dispose: () => this.dispose(),
+			label: "tts-playback",
+		});
+		opts.registry.register(this);
+	}
+
+	/** Caller flips state through (synthesizing → playing → idle). */
+	setState(s: PlaybackState): void {
+		if (this.disposed) return;
+		if (s === this.state) return;
+		this.state = s;
+		if (s === "idle") {
+			// Idle dismisses the widget — render an empty slot, then
+			// dispose so the registry/ticker drop us cleanly.
+			this.dispose();
+			return;
+		}
+		// Re-arm timestamp on each non-idle transition so the elapsed
+		// counter resets between synthesize and play.
+		this.startedAt = Date.now();
+		this.renderFrame();
+	}
+
+	/** Caller invokes this from [esc] when the indicator owns escape. */
+	stop(): void {
+		try {
+			this.onStop?.();
+		} catch {
+			/* never fail caller */
+		}
+		this.dispose();
+	}
+
+	private onTick(): void {
+		if (this.disposed) return;
+		this.spinnerTick++;
+		this.renderFrame();
+	}
+
+	private renderFrame(): void {
+		const state = this.state;
+		const startedAt = this.startedAt ?? Date.now();
+		const tick = this.spinnerTick;
+		this.ui.setWidget(
+			this.key,
+			(_tui: any, theme: any) => ({
+				invalidate() {},
+				render: (width: number): string[] => renderPlaybackLine({ theme, width, state, startedAt, tick }),
+			}),
+			{ placement: "belowEditor" }
+		);
+	}
+}
+
+interface RenderInput {
+	theme: any;
+	width: number;
+	state: PlaybackState;
+	startedAt: number;
+	tick: number;
+}
+
+/** Pure render — exported for tests. */
+export function renderPlaybackLine(input: RenderInput): string[] {
+	const fg = (role: string, s: string): string => (input.theme?.fg ? input.theme.fg(role, s) : s);
+	const dim = (s: string) => fg("dim", s);
+	const accent = (s: string) => fg("accent", s);
+
+	if (input.state === "idle") return [""];
+
+	const spinner = spinnerFrame(input.tick);
+	const word = input.state === "synthesizing" ? "Synthesizing" : "Playing";
+	const elapsed = Math.max(0, Math.round((Date.now() - input.startedAt) / 1000));
+	const elapsedStr = `${elapsed}s`;
+	const showHint = input.width >= 60;
+	const hint = showHint ? ` ${dim("·")} ${dim("[esc] stop")}` : "";
+	return [` ${accent(spinner)} ${accent(word)} ${dim("·")} ${dim(elapsedStr)}${hint}`];
+}