@juicesharp/rpiv-voice 1.4.2

package/package.json

@@ -0,0 +1,94 @@
+{
+	"name": "@juicesharp/rpiv-voice",
+	"version": "1.4.2",
+	"private": false,
+	"description": "Pi extension. Voice dictation via /voice — local on-device STT with sherpa-onnx Whisper (base multilingual int8), microphone capture via decibri.",
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"rpiv",
+		"voice",
+		"dictation",
+		"stt",
+		"sherpa-onnx",
+		"overlay"
+	],
+	"type": "module",
+	"license": "MIT",
+	"author": "juicesharp",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/juicesharp/rpiv-mono.git",
+		"directory": "packages/rpiv-voice"
+	},
+	"homepage": "https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-voice#readme",
+	"bugs": {
+		"url": "https://github.com/juicesharp/rpiv-mono/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"test": "vitest run"
+	},
+	"files": [
+		"index.ts",
+		"audio/error-log.ts",
+		"audio/hallucination-filter.ts",
+		"audio/mic-source.ts",
+		"audio/model-download.ts",
+		"audio/pcm.ts",
+		"audio/sherpa-onnx-node.d.ts",
+		"audio/stt-engine.ts",
+		"command/pipeline-runner.ts",
+		"command/splash-runner.ts",
+		"command/voice-command.ts",
+		"config/voice-config.ts",
+		"state/i18n-bridge.ts",
+		"state/key-router.ts",
+		"state/screen-intent.ts",
+		"state/selectors/contract.ts",
+		"state/selectors/derivations.ts",
+		"state/selectors/focus.ts",
+		"state/selectors/projections.ts",
+		"state/state-reducer.ts",
+		"state/state.ts",
+		"state/status-intent.ts",
+		"state/voice-session.ts",
+		"view/component-binding.ts",
+		"view/components/equalizer-view.ts",
+		"view/components/settings-field-view.ts",
+		"view/components/settings-form-view.ts",
+		"view/components/splash-view.ts",
+		"view/components/status-bar-view.ts",
+		"view/components/transcript-view.ts",
+		"view/overlay-view.ts",
+		"view/props-adapter.ts",
+		"view/screen-content-strategy.ts",
+		"view/stateful-view.ts",
+		"locales/",
+		"docs/",
+		"README.md",
+		"CHANGELOG.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"dependencies": {
+		"sherpa-onnx-node": "^1.13.0",
+		"decibri": "^3.4.0"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
+		"@juicesharp/rpiv-i18n": "*"
+	},
+	"peerDependenciesMeta": {
+		"@juicesharp/rpiv-i18n": {
+			"optional": true
+		}
+	}
+}

package/state/i18n-bridge.ts

@@ -0,0 +1,51 @@
+/**
+ * i18n bridge for rpiv-voice — single thin import surface so every translation
+ * call site routes through one place. Backed by `@juicesharp/rpiv-i18n`'s SDK
+ * when available; degrades to canonical-English fallbacks when not.
+ *
+ * - `t(key, fallback)` is `scope("@juicesharp/rpiv-voice")` if the SDK is
+ *   installed (live `/languages` updates propagate). If the SDK is missing
+ *   (standalone install without rpiv-i18n), `t` is an identity passthrough
+ *   that returns the inline English fallback at every call site, so the
+ *   extension stays online with English UI.
+ * - `getActiveLocale()` exposes the current locale string ("en", "ru", …) so
+ *   the STT engine can pre-set Whisper's `language` field for accuracy gains.
+ *   Returns `undefined` if rpiv-i18n isn't installed or no locale is active —
+ *   in which case Whisper falls back to its built-in auto-detect.
+ *
+ * Strings are registered ONCE at extension load (see ../index.ts). Call sites
+ * MUST use this module at render time — never bake the result into a top-level
+ * `const X = t(...)`.
+ */
+
+export const I18N_NAMESPACE = "@juicesharp/rpiv-voice";
+
+type ScopeFn = (key: string, fallback: string) => string;
+type LocaleFn = () => string | undefined;
+type I18nSDK = {
+	scope: (namespace: string) => ScopeFn;
+	getActiveLocale: LocaleFn;
+};
+
+// Prefer the live SDK if installed: closures it returns track the active
+// locale, so /languages picker propagates to our render call sites. If the
+// SDK isn't installed (standalone install of this extension without
+// rpiv-i18n), the dynamic import fails, every t(key, fallback) returns the
+// canonical English literal, getActiveLocale returns undefined, and the
+// extension stays online with English UI + Whisper auto-detect.
+//
+// Top-level await is required so a synchronous call sees the resolved scope;
+// ESM module loading awaits this before evaluating any importer.
+let scopeImpl: ScopeFn;
+let activeLocaleImpl: LocaleFn;
+try {
+	const sdk = (await import("@juicesharp/rpiv-i18n")) as I18nSDK;
+	scopeImpl = sdk.scope(I18N_NAMESPACE);
+	activeLocaleImpl = sdk.getActiveLocale;
+} catch {
+	scopeImpl = (_key, fallback) => fallback;
+	activeLocaleImpl = () => undefined;
+}
+
+export const t: ScopeFn = scopeImpl;
+export const getActiveLocale: LocaleFn = activeLocaleImpl;

package/state/key-router.ts

@@ -0,0 +1,46 @@
+import { Key, matchesKey } from "@earendil-works/pi-tui";
+import type { VoiceRuntime, VoiceState } from "./state.js";
+
+const KEYBIND_CONFIRM = "tui.select.confirm";
+// Mirrors the rpiv-ask-user-question peer pattern — cancel goes through the
+// user's configurable keybinding (defaults to Esc) instead of a hardcoded
+// `Key.escape`. Users who remap Esc still get a working cancel.
+const KEYBIND_CANCEL = "tui.select.cancel";
+
+const SPACE_KEY = " ";
+const CTRL_S = "\x13";
+
+export type VoiceAction =
+	| { kind: "audio_chunk"; level: number }
+	| { kind: "audio_transcript_appended"; text: string }
+	| { kind: "audio_partial_transcript_set"; text: string }
+	| { kind: "toggle_pause" }
+	| { kind: "commit" }
+	| { kind: "cancel" }
+	| { kind: "open_settings" }
+	| { kind: "close_settings" }
+	| { kind: "toggle_focused_setting" }
+	| { kind: "focus_settings_next" }
+	| { kind: "focus_settings_prev" }
+	| { kind: "settings_save" }
+	| { kind: "ignore" };
+
+export function routeKey(data: string, state: VoiceState, runtime: VoiceRuntime): VoiceAction {
+	const kb = runtime.keybindings;
+
+	if (state.currentScreen === "settings") {
+		if (data === CTRL_S) return { kind: "settings_save" };
+		if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "close_settings" };
+		if (matchesKey(data, Key.tab)) return { kind: "close_settings" };
+		if (matchesKey(data, Key.up)) return { kind: "focus_settings_prev" };
+		if (matchesKey(data, Key.down)) return { kind: "focus_settings_next" };
+		if (kb.matches(data, KEYBIND_CONFIRM)) return { kind: "toggle_focused_setting" };
+		return { kind: "ignore" };
+	}
+
+	if (kb.matches(data, KEYBIND_CANCEL)) return { kind: "cancel" };
+	if (kb.matches(data, KEYBIND_CONFIRM)) return { kind: "commit" };
+	if (matchesKey(data, Key.tab)) return { kind: "open_settings" };
+	if (data === SPACE_KEY) return { kind: "toggle_pause" };
+	return { kind: "ignore" };
+}

package/state/screen-intent.ts

@@ -0,0 +1,27 @@
+import type { ScreenKind } from "./state.js";
+
+export type FooterHintKey =
+	| "enter_paste"
+	| "space_pause"
+	| "tab_settings"
+	| "esc_cancel"
+	| "esc_back"
+	| "ctrl_s_save"
+	| "enter_toggle"
+	| "up_down_select";
+
+export interface ScreenIntentMeta {
+	label: string;
+	footerHints: readonly FooterHintKey[];
+}
+
+export const SCREEN_META: Record<ScreenKind, ScreenIntentMeta> = {
+	dictation: {
+		label: "Dictation",
+		footerHints: ["enter_paste", "space_pause", "tab_settings", "esc_cancel"],
+	},
+	settings: {
+		label: "Settings",
+		footerHints: ["up_down_select", "enter_toggle", "ctrl_s_save", "esc_back"],
+	},
+};

package/state/selectors/contract.ts

@@ -0,0 +1,13 @@
+import type { ActiveView } from "../../view/stateful-view.js";
+import type { ScreenKind, VoiceState } from "../state.js";
+
+export interface BindingContext {
+	readonly activeView: ActiveView;
+}
+
+export interface PerScreenBindingContext extends BindingContext {
+	readonly kind: ScreenKind;
+}
+
+export type GlobalSelector<P> = (state: VoiceState, ctx: BindingContext) => P;
+export type PerScreenSelector<P> = (state: VoiceState, ctx: PerScreenBindingContext) => P;

package/state/selectors/derivations.ts

@@ -0,0 +1,9 @@
+const MIN_RENDER_ROWS = 4;
+const MAX_HEIGHT_RATIO = 0.85;
+
+// Top-clip so banner + latest transcript + footer stay visible at the bottom.
+export function clipToTerminalHeight(lines: readonly string[], terminalRows: number): string[] {
+	const maxRows = Math.max(MIN_RENDER_ROWS, Math.floor(terminalRows * MAX_HEIGHT_RATIO));
+	if (lines.length <= maxRows) return [...lines];
+	return lines.slice(lines.length - maxRows);
+}

package/state/selectors/focus.ts

@@ -0,0 +1,6 @@
+import type { ActiveView } from "../../view/stateful-view.js";
+import type { VoiceState } from "../state.js";
+
+export function selectActiveView(state: VoiceState): ActiveView {
+	return state.currentScreen === "settings" ? "settings" : "dictation";
+}

package/state/selectors/projections.ts

@@ -0,0 +1,112 @@
+import type { EqualizerViewProps } from "../../view/components/equalizer-view.js";
+import type { SettingsFieldViewProps } from "../../view/components/settings-field-view.js";
+import type { StatusBarViewProps } from "../../view/components/status-bar-view.js";
+import type { TranscriptViewProps } from "../../view/components/transcript-view.js";
+import { getActiveLocale, t } from "../i18n-bridge.js";
+import type { FooterHintKey } from "../screen-intent.js";
+import { SCREEN_META } from "../screen-intent.js";
+import type { GlobalSelector } from "./contract.js";
+
+// Locales the bundled Whisper base multilingual model recognizes well. Mirror
+// of WHISPER_SUPPORTED_LANGUAGES in voice-command.ts — duplicated rather than
+// imported to keep selectors free of command-layer deps. Codes outside this
+// set fall through to the auto-detect display.
+//
+// Endonyms (self-names) so the same string reads naturally regardless of the
+// active UI locale: a Russian user sees `Русский`, an English user sees the
+// same `Русский` — always self-recognizable, no translation matrix needed.
+const LANGUAGE_DISPLAY_BY_CODE: Record<string, string> = {
+	de: "Deutsch",
+	en: "English",
+	es: "Español",
+	fr: "Français",
+	it: "Italiano",
+	ja: "日本語",
+	pt: "Português",
+	ru: "Русский",
+	uk: "Українська",
+	zh: "中文",
+};
+
+// Selector functions resolve i18n at projection time so /languages flips
+// propagate without re-instantiating the views.
+function hintLabel(key: FooterHintKey, status: { status: string }): string {
+	switch (key) {
+		case "enter_paste":
+			return t("footer.enter_paste", "Enter to paste");
+		case "space_pause":
+			return status.status === "paused"
+				? t("footer.space_resume", "Space to resume")
+				: t("footer.space_pause", "Space to pause");
+		case "tab_settings":
+			return t("footer.tab_settings", "Tab for settings");
+		case "esc_cancel":
+			return t("footer.esc_cancel", "Esc to cancel");
+		case "esc_back":
+			return t("footer.esc_back", "Esc to go back");
+		case "ctrl_s_save":
+			return t("footer.ctrl_s_save", "Ctrl-S to save");
+		case "enter_toggle":
+			return t("footer.enter_toggle", "Enter to toggle");
+		case "up_down_select":
+			return t("footer.up_down_select", "↑↓ to select");
+	}
+}
+
+export const selectStatusBarProps: GlobalSelector<StatusBarViewProps> = (state, _ctx) => {
+	const meta = SCREEN_META[state.currentScreen];
+	const hints: string[] = [];
+	for (const key of meta.footerHints) hints.push(hintLabel(key, state));
+	return { status: state.status, hints };
+};
+
+export const selectTranscriptProps: GlobalSelector<TranscriptViewProps> = (state, _ctx) => ({
+	text: state.transcript,
+	partial: state.partialTranscript,
+	placeholder: t("transcript.placeholder", "Listening..."),
+});
+
+export const selectEqualizerProps: GlobalSelector<EqualizerViewProps> = (state, _ctx) => ({
+	level: state.audioLevel,
+	status: state.status,
+	enabled: state.settingsDraft.equalizerEnabled,
+});
+
+// `active` reflects the focused settings field — only one toggle wears the
+// pointer at a time. `hint` stays present so the settings body height is
+// stable across focus changes (the field hides its own hint when not active,
+// per settings-field-view's render gate).
+export const selectHallucinationFilterFieldProps: GlobalSelector<SettingsFieldViewProps> = (state, _ctx) => ({
+	label: t("settings.hallucination_filter_label", "Filter Whisper noise"),
+	active: state.settingsFocus === "hallucination",
+	field: { kind: "toggle", enabled: state.settingsDraft.hallucinationFilterEnabled },
+	hint: t(
+		"settings.hallucination_filter_hint",
+		"Drops silence-segment artifacts. Turn off for single-word dictation.",
+	),
+});
+
+export const selectEqualizerFieldProps: GlobalSelector<SettingsFieldViewProps> = (state, _ctx) => ({
+	label: t("settings.equalizer_label", "Equalizer"),
+	active: state.settingsFocus === "equalizer",
+	field: { kind: "toggle", enabled: state.settingsDraft.equalizerEnabled },
+	hint: t("settings.equalizer_hint", "Show the live audio waveform under the transcript. Off by default."),
+});
+
+export const selectMicReadonlyFieldProps: GlobalSelector<SettingsFieldViewProps> = (_state, _ctx) => ({
+	label: t("settings.microphone_label", "Microphone"),
+	active: false,
+	field: { kind: "readonly", value: t("settings.microphone_value_default", "System default input") },
+});
+
+export const selectLanguageReadonlyFieldProps: GlobalSelector<SettingsFieldViewProps> = (_state, _ctx) => {
+	const locale = getActiveLocale();
+	const base = locale ? (locale.split("-")[0] ?? locale) : undefined;
+	const display = base ? (LANGUAGE_DISPLAY_BY_CODE[base] ?? base) : t("settings.language_value_auto", "Auto-detect");
+	return {
+		label: t("settings.language_label", "Language"),
+		active: false,
+		field: { kind: "readonly", value: display },
+		hint: t("settings.language_hint", "Run /languages to change."),
+	};
+};

package/state/state-reducer.ts

@@ -0,0 +1,197 @@
+import { isEqualizerEnabled, isHallucinationFilterEnabled, type VoiceConfig } from "../config/voice-config.js";
+import { t } from "./i18n-bridge.js";
+import type { VoiceAction } from "./key-router.js";
+import { SETTINGS_FIELD_ORDER, type SettingsDraft, type SettingsFieldKey, type VoiceState } from "./state.js";
+import { STATUS_META } from "./status-intent.js";
+
+export interface ApplyContext {
+	persistedConfig: VoiceConfig;
+}
+
+export type Effect =
+	| { kind: "request_render" }
+	| { kind: "paste_to_editor"; text: string }
+	| { kind: "notify"; level: "error" | "info"; message: string }
+	| { kind: "abort_session" }
+	| { kind: "stop_mic" }
+	| { kind: "set_pipeline_paused"; paused: boolean }
+	| { kind: "set_hallucination_filter"; enabled: boolean }
+	| { kind: "save_config"; config: VoiceConfig }
+	| { kind: "done"; result: VoiceResult };
+
+export interface VoiceResult {
+	intent: "commit" | "cancel";
+	transcript: string;
+}
+
+export interface ApplyResult {
+	state: VoiceState;
+	effects: readonly Effect[];
+}
+
+type Handler<K extends VoiceAction["kind"]> = (
+	state: VoiceState,
+	action: Extract<VoiceAction, { kind: K }>,
+	ctx: ApplyContext,
+) => ApplyResult;
+
+const audioChunk: Handler<"audio_chunk"> = (state, action, _ctx) => {
+	if (state.audioLevel === action.level) return { state, effects: [] };
+	return { state: { ...state, audioLevel: action.level }, effects: [{ kind: "request_render" }] };
+};
+
+// Final commit. Appends to the persisted transcript and clears the in-progress
+// partial — rolling re-decodes get superseded by the authoritative final.
+const audioTranscriptAppended: Handler<"audio_transcript_appended"> = (state, action, _ctx) => {
+	if (action.text.length === 0) {
+		// Nothing to append, but a finalization still ends the partial.
+		if (!state.partialTranscript) return { state, effects: [] };
+		return { state: { ...state, partialTranscript: "" }, effects: [{ kind: "request_render" }] };
+	}
+	const next = state.transcript ? `${state.transcript} ${action.text}` : action.text;
+	return {
+		state: { ...state, transcript: next, partialTranscript: "" },
+		effects: [{ kind: "request_render" }],
+	};
+};
+
+// Replaces the partial wholesale — each rolling decode produces a fresh
+// reading of the active utterance.
+const audioPartialTranscriptSet: Handler<"audio_partial_transcript_set"> = (state, action, _ctx) => {
+	if (state.partialTranscript === action.text) return { state, effects: [] };
+	return { state: { ...state, partialTranscript: action.text }, effects: [{ kind: "request_render" }] };
+};
+
+const togglePause: Handler<"toggle_pause"> = (state, _action, _ctx) => {
+	const nextStatus = state.status === "paused" ? "recording" : "paused";
+	return {
+		state: { ...state, status: nextStatus },
+		effects: [
+			{ kind: "set_pipeline_paused", paused: STATUS_META[nextStatus].gatesSttPipeline },
+			{ kind: "request_render" },
+		],
+	};
+};
+
+// Include the in-flight partial when committing — what the user sees on
+// screen (committed + grayed preview) is what they get pasted. Waiting for a
+// "proper" final decode here would add 0.5–2 s of latency between Enter and
+// paste; the visible partial is already a complete utterance from Whisper's
+// perspective, just one without the trailing-silence padding.
+const commit: Handler<"commit"> = (state, _action, _ctx) => {
+	const merged = state.partialTranscript
+		? state.transcript
+			? `${state.transcript} ${state.partialTranscript}`
+			: state.partialTranscript
+		: state.transcript;
+	return {
+		state,
+		effects: [{ kind: "done", result: { intent: "commit", transcript: merged } }],
+	};
+};
+
+const cancel: Handler<"cancel"> = (state, _action, _ctx) => ({
+	state,
+	effects: [{ kind: "abort_session" }, { kind: "done", result: { intent: "cancel", transcript: "" } }],
+});
+
+const openSettings: Handler<"open_settings"> = (state, _action, _ctx) => ({
+	state: { ...state, currentScreen: "settings" },
+	effects: [{ kind: "request_render" }],
+});
+
+// Leaving the settings screen silently persists the draft. Ctrl-S remains the
+// explicit save path (with a confirmation notify); this just makes the common
+// "toggle then Esc/Tab" flow not lose changes.
+const closeSettings: Handler<"close_settings"> = (state, _action, _ctx) => ({
+	state: { ...state, currentScreen: "dictation" },
+	effects: [{ kind: "save_config", config: configFromDraft(state.settingsDraft) }, { kind: "request_render" }],
+});
+
+const toggleFocusedSetting: Handler<"toggle_focused_setting"> = (state, _action, _ctx) => {
+	const focus = state.settingsFocus;
+	if (focus === "hallucination") {
+		const enabled = !state.settingsDraft.hallucinationFilterEnabled;
+		return {
+			state: { ...state, settingsDraft: { ...state.settingsDraft, hallucinationFilterEnabled: enabled } },
+			effects: [{ kind: "set_hallucination_filter", enabled }, { kind: "request_render" }],
+		};
+	}
+	// equalizer toggle is purely view-side: no pipeline reconfig needed, the
+	// view reads the draft directly to decide whether to render its row pair.
+	const enabled = !state.settingsDraft.equalizerEnabled;
+	return {
+		state: { ...state, settingsDraft: { ...state.settingsDraft, equalizerEnabled: enabled } },
+		effects: [{ kind: "request_render" }],
+	};
+};
+
+const focusSettingsNext: Handler<"focus_settings_next"> = (state, _action, _ctx) => {
+	const next = stepFocus(state.settingsFocus, +1);
+	if (next === state.settingsFocus) return { state, effects: [] };
+	return { state: { ...state, settingsFocus: next }, effects: [{ kind: "request_render" }] };
+};
+
+const focusSettingsPrev: Handler<"focus_settings_prev"> = (state, _action, _ctx) => {
+	const next = stepFocus(state.settingsFocus, -1);
+	if (next === state.settingsFocus) return { state, effects: [] };
+	return { state: { ...state, settingsFocus: next }, effects: [{ kind: "request_render" }] };
+};
+
+function stepFocus(current: SettingsFieldKey, delta: 1 | -1): SettingsFieldKey {
+	const order = SETTINGS_FIELD_ORDER;
+	const idx = order.indexOf(current);
+	const next = (idx + delta + order.length) % order.length;
+	return order[next] ?? current;
+}
+
+const settingsSave: Handler<"settings_save"> = (state, _action, _ctx) => {
+	const config = configFromDraft(state.settingsDraft);
+	return {
+		state,
+		effects: [
+			{ kind: "save_config", config },
+			{ kind: "notify", level: "info", message: t("notify.settings_saved", "Voice settings saved") },
+		],
+	};
+};
+
+const ignore: Handler<"ignore"> = (state, _action, _ctx) => ({ state, effects: [] });
+
+const HANDLERS: { [K in VoiceAction["kind"]]: Handler<K> } = {
+	audio_chunk: audioChunk,
+	audio_transcript_appended: audioTranscriptAppended,
+	audio_partial_transcript_set: audioPartialTranscriptSet,
+	toggle_pause: togglePause,
+	commit,
+	cancel,
+	open_settings: openSettings,
+	close_settings: closeSettings,
+	toggle_focused_setting: toggleFocusedSetting,
+	focus_settings_next: focusSettingsNext,
+	focus_settings_prev: focusSettingsPrev,
+	settings_save: settingsSave,
+	ignore,
+};
+
+export function reduce(state: VoiceState, action: VoiceAction, ctx: ApplyContext): ApplyResult {
+	const handler = HANDLERS[action.kind] as Handler<typeof action.kind>;
+	return handler(state, action as never, ctx);
+}
+
+export function configFromDraft(draft: SettingsDraft): VoiceConfig {
+	const out: { -readonly [K in keyof VoiceConfig]: VoiceConfig[K] } = {};
+	// Only persist the non-default state. Hallucination filter defaults ON, so
+	// only the off-state lands on disk; equalizer defaults OFF, so only the
+	// on-state does. Both rules keep voice.json minimal and forward-compatible.
+	if (draft.hallucinationFilterEnabled === false) out.hallucinationFilterEnabled = false;
+	if (draft.equalizerEnabled === true) out.equalizerEnabled = true;
+	return out;
+}
+
+export function draftFromConfig(config: VoiceConfig): SettingsDraft {
+	return {
+		hallucinationFilterEnabled: isHallucinationFilterEnabled(config),
+		equalizerEnabled: isEqualizerEnabled(config),
+	};
+}

package/state/state.ts

@@ -0,0 +1,48 @@
+export type RecordingStatus = "recording" | "paused";
+export type ScreenKind = "dictation" | "settings";
+
+export type SettingsFieldKey = "hallucination" | "equalizer";
+
+export interface SettingsDraft {
+	hallucinationFilterEnabled: boolean;
+	equalizerEnabled: boolean;
+}
+
+export interface VoiceState {
+	currentScreen: ScreenKind;
+	status: RecordingStatus;
+	/** Committed text — produced by the final decode at each VAD silence /
+	 *  cap boundary. This is what the editor receives on commit. */
+	transcript: string;
+	/** In-progress text — rolling re-decodes of the still-active utterance,
+	 *  emitted every ~1 s. Replaced wholesale by each successive partial.
+	 *  Cleared (and concatenated into `transcript`) on the final decode of
+	 *  the utterance. Rendered after `transcript` in a dim style. */
+	partialTranscript: string;
+	audioLevel: number;
+	/** In-flight editor draft — auto-persists on `close_settings` (Esc/Tab) so
+	 *  toggling and exiting saves; Ctrl-S (`settings_save`) is the explicit
+	 *  save+notify path. */
+	settingsDraft: SettingsDraft;
+	/** Which interactive settings field is currently focused. Up/Down arrows
+	 *  cycle through `SETTINGS_FIELD_ORDER`; Enter toggles the focused one. */
+	settingsFocus: SettingsFieldKey;
+}
+
+export const SETTINGS_FIELD_ORDER: readonly SettingsFieldKey[] = ["hallucination", "equalizer"];
+
+export interface VoiceRuntime {
+	keybindings: { matches(data: string, name: string): boolean };
+}
+
+export function initialVoiceState(draft: SettingsDraft): VoiceState {
+	return {
+		currentScreen: "dictation",
+		status: "recording",
+		transcript: "",
+		partialTranscript: "",
+		audioLevel: 0,
+		settingsDraft: draft,
+		settingsFocus: SETTINGS_FIELD_ORDER[0]!,
+	};
+}

package/state/status-intent.ts

@@ -0,0 +1,23 @@
+import type { RecordingStatus } from "./state.js";
+
+export interface StatusIntentMeta {
+	glyph: string;
+	glyphColorKey: "error" | "warning";
+	label: string;
+	gatesSttPipeline: boolean;
+}
+
+export const STATUS_META: Record<RecordingStatus, StatusIntentMeta> = {
+	recording: {
+		glyph: "●",
+		glyphColorKey: "error",
+		label: "Recording",
+		gatesSttPipeline: false,
+	},
+	paused: {
+		glyph: "⏸",
+		glyphColorKey: "warning",
+		label: "Paused",
+		gatesSttPipeline: true,
+	},
+};