@earendil-works/pi-voice 0.1.0

package/src/ui-components.ts

@@ -0,0 +1,432 @@
+import { DynamicBorder, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  Box,
+  type Component,
+  Container,
+  type Focusable,
+  fuzzyFilter,
+  Input,
+  Loader,
+  Spacer,
+  Text,
+  truncateToWidth,
+  visibleWidth,
+  type KeybindingsManager,
+  type TUI,
+} from "@earendil-works/pi-tui";
+import { formatBinarySize } from "./catalog.js";
+import type { DownloadState } from "./model-selection-controller.js";
+import { VoiceKeys } from "./keybindings.js";
+
+type UiTheme = ExtensionContext["ui"]["theme"];
+
+export const PANEL_PADDING = 1;
+export const LIST_PADDING = 1;
+
+export function panelBorder(theme: UiTheme): DynamicBorder {
+  return new DynamicBorder((text: string) => theme.fg("border", text));
+}
+
+/** The rule Pi's editor draws above and below its text. */
+export function editorBorder(theme: UiTheme): DynamicBorder {
+  return new DynamicBorder((text: string) => theme.fg("borderMuted", text));
+}
+
+/** Page title on the left; quieter setup context and progress on the right. */
+export function onboardingHeader(
+  theme: UiTheme,
+  title: string,
+  step: number,
+  total = 3,
+): Component {
+  const context = `Pi Voice setup · ${step} of ${total}`;
+  const compactContext = `${step} of ${total}`;
+  return {
+    invalidate() {},
+    render(width: number): string[] {
+      const innerWidth = Math.max(1, width - PANEL_PADDING * 2);
+      const titleWidth = visibleWidth(title);
+      const contextWidth = visibleWidth(context);
+      const left = theme.fg("accent", theme.bold(title));
+      let content: string;
+      if (titleWidth + contextWidth + 2 <= innerWidth) {
+        content = `${left}${" ".repeat(innerWidth - titleWidth - contextWidth)}${theme.fg("dim", context)}`;
+      } else {
+        const suffix = ` · ${compactContext}`;
+        const titleRoom = Math.max(1, innerWidth - visibleWidth(suffix));
+        content = `${truncateToWidth(left, titleRoom, "…")}${theme.fg("dim", suffix)}`;
+      }
+      return [truncateToWidth(`${" ".repeat(PANEL_PADDING)}${content}`, width, "")];
+    },
+  };
+}
+
+export type SingleSelectChoice<T extends string> = {
+  value: T;
+  label: string;
+  description?: string;
+};
+
+export function selectedWindow<T>(
+  items: readonly T[],
+  selected: number,
+  maximum: number,
+): [number, number] {
+  const start = Math.max(
+    0,
+    Math.min(selected - Math.floor(maximum / 2), items.length - maximum),
+  );
+  return [start, Math.min(start + maximum, items.length)];
+}
+
+/** Rows the host renders below an editor-mounted pane (its two footer lines). */
+const RESERVED_HOST_ROWS = 2;
+/** Below this a list stops shrinking and the pane is left to overflow. */
+export const MIN_VISIBLE_ROWS = 3;
+
+/** Rows available to a pane, or undefined when the terminal size is unknown. */
+export function paneRowBudget(tui: TUI): number | undefined {
+  const rows = (tui as Partial<TUI>).terminal?.rows;
+  return typeof rows === "number" && rows > 0
+    ? rows - RESERVED_HOST_ROWS
+    : undefined;
+}
+
+/** Window size that fits a list into a budget of rows. */
+export function windowSizeForBudget(
+  budget: number,
+  maximum: number,
+  minimum = MIN_VISIBLE_ROWS,
+): number {
+  return Math.max(minimum, Math.min(maximum, budget));
+}
+
+/** Compute a list window while reserving the pane's non-list content. */
+export function paneListWindow(
+  tui: TUI,
+  renderedRows: number,
+  listRows: number,
+  detailRows: number,
+  reservedDetailRows: number,
+  maximum: number,
+): number | undefined {
+  const budget = paneRowBudget(tui);
+  if (budget === undefined) return undefined;
+  const chrome = renderedRows - listRows - detailRows + reservedDetailRows;
+  return windowSizeForBudget(budget - chrome, maximum);
+}
+
+export function padToWidth(value: string, width: number): string {
+  const truncated = truncateToWidth(value, width, "…");
+  return `${truncated}${" ".repeat(Math.max(0, width - visibleWidth(truncated)))}`;
+}
+
+/** Shared fixed-width marker: the arrow is focus, while ✓ is selected/current. */
+export function selectionMarker(theme: UiTheme, selected: boolean): string {
+  return selected ? theme.fg("accent", "✓") : " ";
+}
+
+/** Shared download presentation; the picker owns and disposes its spinner. */
+export class DownloadPanel {
+  private readonly spinner: Loader;
+  private state: DownloadState;
+  private stats: string | undefined;
+
+  constructor(
+    tui: TUI,
+    private readonly theme: UiTheme,
+    private readonly keys: VoiceKeys,
+    state: DownloadState,
+  ) {
+    this.state = state;
+    this.spinner = new Loader(tui, (text) => theme.fg("accent", text), (text) => theme.fg("muted", text), state.message);
+  }
+
+  update(state: DownloadState, stats?: string): void {
+    this.state = state;
+    this.stats = stats;
+    this.spinner.setMessage(state.message);
+  }
+
+  render(width: number, maxRows = Infinity): string[] {
+    const { model, downloaded, total } = this.state;
+    const text = (value: string) => new Text(value, PANEL_PADDING, 0).render(width);
+    const ratio = total > 0 ? Math.max(0, Math.min(1, downloaded / total)) : 0;
+    const barWidth = Math.max(1, Math.min(36, width - PANEL_PADDING * 2 - 5));
+    const filled = Math.round(ratio * barWidth);
+    const bar = this.theme.fg("accent", "█".repeat(filled)) + this.theme.fg("dim", "─".repeat(barWidth - filled));
+    const title = this.theme.fg("accent", this.theme.bold(`Downloading ${model.name}`));
+    const progress = `${bar}${total > 0 ? this.theme.fg("dim", ` ${Math.floor(ratio * 100)}%`) : ""}`;
+    const stats = this.theme.fg("muted", this.stats ?? (total > 0
+      ? `${formatBinarySize(downloaded)} / ${formatBinarySize(total)}` : "Preparing download…"));
+    const privacy = this.theme.fg("dim", "Models run locally — audio never leaves this machine.");
+    const hint = this.keys.hint("tui.select.cancel", "stop (keeps progress)");
+    const activity = this.spinner.render(width);
+    const lines = ["", ...text(title), ...activity, "", ...text(progress), "", ...text(stats), ...text(privacy), "", ...text(hint)];
+    if (lines.length <= maxRows) return lines;
+    // Small terminals keep the current operation and cancel key visible.
+    const compact = [title, activity[1]?.trim() ?? this.state.message, progress, stats, privacy]
+      .slice(0, Math.max(0, maxRows - 1));
+    return [...compact, this.keys.hint("tui.select.cancel", "stop")].map((line) => truncateToWidth(` ${line}`, width));
+  }
+
+  invalidate(): void { this.spinner.invalidate(); }
+  dispose(): void { this.spinner.stop(); }
+}
+
+/** Pi-native single-choice picker with optional fuzzy search and current-value marker. */
+export class SingleSelectPicker<T extends string> extends Container implements Focusable {
+  private readonly search = new Input();
+  private readonly titleText: Text;
+  private readonly subtitleText: Text | undefined;
+  private readonly list = new Container();
+  private readonly detail = new Text("", PANEL_PADDING, 0);
+  private readonly footer = new Text("", PANEL_PADDING, 0);
+  private filtered: SingleSelectChoice<T>[];
+  private selectedIndex: number;
+  /** Rows the list window may use; shrinks to fit short terminals. */
+  private visibleLimit: number;
+  /** Width of the last render; row labels are laid out against it. */
+  private renderWidth = 80;
+  /** Lines of the longest description at the cached width. */
+  private detailReserve = 0;
+  private detailReserveWidth = -1;
+  private readonly hasDescriptions: boolean;
+  private _focused = false;
+
+  get focused(): boolean {
+    return this._focused;
+  }
+
+  set focused(value: boolean) {
+    this._focused = value;
+    this.search.focused = value && Boolean(this.options.searchable);
+  }
+
+  private readonly keys: VoiceKeys;
+
+  constructor(
+    private readonly tui: TUI,
+    private readonly theme: UiTheme,
+    keybindings: KeybindingsManager,
+    private readonly choices: readonly SingleSelectChoice<T>[],
+    private readonly current: T | undefined,
+    private readonly options: {
+      title: string;
+      subtitle?: string;
+      searchable?: boolean;
+      maximumVisible?: number;
+      cancelLabel?: string;
+      /** Extra footer legend, appended after the ✓ current marker. */
+      legend?: string;
+      /** Custom row body after the cursor and ✓ markers; handles its own active styling. */
+      renderLabel?: (choice: SingleSelectChoice<T>, active: boolean, width: number) => string;
+    },
+    private readonly done: (value: T | undefined) => void,
+  ) {
+    super();
+    this.keys = new VoiceKeys(keybindings);
+    this.visibleLimit = options.maximumVisible ?? 10;
+    this.hasDescriptions = choices.some((choice) => choice.description);
+    this.filtered = [...choices];
+    this.selectedIndex = Math.max(
+      0,
+      this.filtered.findIndex((choice) => choice.value === current),
+    );
+
+    this.titleText = new Text(
+      theme.fg("accent", theme.bold(options.title)),
+      PANEL_PADDING,
+      0,
+    );
+    this.subtitleText = options.subtitle
+      ? new Text(theme.fg("muted", options.subtitle), PANEL_PADDING, 0)
+      : undefined;
+
+    this.addChild(panelBorder(theme));
+    this.addChild(new Spacer(1));
+    this.addChild(this.titleText);
+    if (this.subtitleText) this.addChild(this.subtitleText);
+    this.addChild(new Spacer(1));
+    if (options.searchable) {
+      const searchBox = new Box(LIST_PADDING, 0);
+      searchBox.addChild(this.search);
+      this.addChild(searchBox);
+      this.addChild(new Spacer(1));
+    }
+    this.addChild(this.list);
+    this.addChild(new Spacer(1));
+    if (this.hasDescriptions) {
+      this.addChild(this.detail);
+      this.addChild(new Spacer(1));
+    }
+    this.addChild(this.footer);
+    this.addChild(new Spacer(1));
+    this.addChild(panelBorder(theme));
+    this.refresh();
+  }
+
+  private refresh(): void {
+    const query = this.search.getValue().trim();
+    this.filtered = query
+      ? fuzzyFilter([...this.choices], query, (choice) =>
+          `${choice.label} ${choice.value} ${choice.description ?? ""}`,
+        )
+      : [...this.choices];
+    this.selectedIndex = Math.min(
+      this.selectedIndex,
+      Math.max(0, this.filtered.length - 1),
+    );
+    this.list.clear();
+
+    if (this.filtered.length === 0) {
+      this.list.addChild(
+        new Text(this.theme.fg("muted", "  No matching choices"), LIST_PADDING, 0),
+      );
+      this.detail.setText("");
+    } else {
+      const maximum = this.visibleLimit;
+      const [start, end] = selectedWindow(
+        this.filtered,
+        this.selectedIndex,
+        maximum,
+      );
+      for (let index = start; index < end; index += 1) {
+        const choice = this.filtered[index]!;
+        const active = index === this.selectedIndex;
+        const prefix = active ? this.theme.fg("accent", "→ ") : "  ";
+        const current = this.current === undefined
+          ? ""
+          : `${selectionMarker(this.theme, choice.value === this.current)} `;
+        const label = this.options.renderLabel
+          ? this.options.renderLabel(choice, active, this.renderWidth)
+          : active
+            ? this.theme.fg("accent", choice.label)
+            : choice.label;
+        this.list.addChild(new Text(`${prefix}${current}${label}`, LIST_PADDING, 0));
+      }
+      this.detail.setText(
+        this.filtered[this.selectedIndex]?.description
+          ? this.theme.fg("dim", this.filtered[this.selectedIndex]!.description!)
+          : "",
+      );
+    }
+
+    // When the list is clipped the scroll position lives in this count, so
+    // the list itself never spends a row on an indicator.
+    const clipped = this.filtered.length > this.visibleLimit;
+    const shown = query
+      ? clipped
+        ? `${this.selectedIndex + 1}/${this.filtered.length} matching choices`
+        : `${this.filtered.length}/${this.choices.length} matching choices`
+      : clipped
+        ? `${this.selectedIndex + 1}/${this.choices.length} choices`
+        : `${this.choices.length} choices`;
+    const legend = [
+      this.current === undefined
+        ? undefined
+        : `${selectionMarker(this.theme, true)} ${this.theme.fg("dim", "current")}`,
+      this.options.legend,
+    ]
+      .filter((value): value is string => Boolean(value))
+      .join("  ");
+    this.footer.setText(
+      `${this.theme.fg("dim", shown)}${legend ? `  ${legend}` : ""}\n${this.keys.navHint("navigate")}  ${this.keys.hint("tui.select.confirm", "select")}  ${this.keys.hint("tui.select.cancel", query ? "clear search" : (this.options.cancelLabel ?? "back"))}`,
+    );
+    this.tui.requestRender();
+  }
+
+  override invalidate(): void {
+    super.invalidate();
+    this.titleText.setText(
+      this.theme.fg("accent", this.theme.bold(this.options.title)),
+    );
+    if (this.subtitleText && this.options.subtitle) {
+      this.subtitleText.setText(this.theme.fg("muted", this.options.subtitle));
+    }
+    this.refresh();
+  }
+
+  // The pane replaces the host editor and cannot scroll: when the terminal
+  // is short, shrink the list window so the title and footer stay on screen.
+  override render(width: number): string[] {
+    if (width !== this.renderWidth) {
+      this.renderWidth = width;
+      this.refresh();
+    }
+    const limit = paneListWindow(
+      this.tui,
+      super.render(width).length,
+      this.list.render(width).length,
+      this.detail.render(width).length,
+      this.maxDetailLines(width),
+      this.options.maximumVisible ?? 10,
+    );
+    if (limit !== undefined && limit !== this.visibleLimit) {
+      this.visibleLimit = limit;
+      this.refresh();
+    }
+    return super.render(width);
+  }
+
+  // Sizing against the longest description keeps the window height steady
+  // while the highlight moves across short and wrapping descriptions.
+  private maxDetailLines(width: number): number {
+    if (!this.hasDescriptions) return 0;
+    if (this.detailReserveWidth !== width) {
+      this.detailReserveWidth = width;
+      const probe = new Text("", PANEL_PADDING, 0);
+      this.detailReserve = Math.max(
+        ...this.choices.map((choice) => {
+          if (!choice.description) return 1;
+          probe.setText(choice.description);
+          return probe.render(width).length;
+        }),
+      );
+    }
+    return this.detailReserve;
+  }
+
+  handleInput(data: string): void {
+    if (this.keys.matches(data, "tui.select.up")) {
+      if (this.filtered.length > 0) {
+        this.selectedIndex =
+          this.selectedIndex === 0 ? this.filtered.length - 1 : this.selectedIndex - 1;
+        this.refresh();
+      }
+      return;
+    }
+    if (this.keys.matches(data, "tui.select.down")) {
+      if (this.filtered.length > 0) {
+        this.selectedIndex =
+          this.selectedIndex === this.filtered.length - 1 ? 0 : this.selectedIndex + 1;
+        this.refresh();
+      }
+      return;
+    }
+    if (this.keys.matches(data, "tui.select.confirm")) {
+      const selected = this.filtered[this.selectedIndex];
+      if (selected) this.done(selected.value);
+      return;
+    }
+    if (this.keys.matches(data, "tui.select.cancel")) {
+      if (this.search.getValue()) {
+        this.search.setValue("");
+        this.selectedIndex = Math.max(
+          0,
+          this.choices.findIndex((choice) => choice.value === this.current),
+        );
+        this.refresh();
+      } else {
+        this.done(undefined);
+      }
+      return;
+    }
+
+    if (this.options.searchable) {
+      this.search.handleInput(data);
+      this.selectedIndex = 0;
+      this.refresh();
+    }
+  }
+}

package/src/visualizer.ts

@@ -0,0 +1,269 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { CAPTURE_SAMPLE_RATE } from "./audio-constants.js";
+import { STATUS_WIDGET_KEY } from "./shortcut-core.js";
+
+type UiTheme = ExtensionContext["ui"]["theme"];
+
+const WIDGET_KEY = STATUS_WIDGET_KEY;
+/** Repaint interval shared by every surface that draws the meter. */
+export const METER_UPDATE_MS = 50;
+const LEVEL_GAIN = 36;
+const DECAY = 0.65;
+const BLOCKS = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"] as const;
+const BAND_EDGES_HZ = [80, 160, 250, 400, 650, 1000, 1600, 2500, 4000, 6000] as const;
+
+function floorPowerOfTwo(value: number): number {
+  return 2 ** Math.floor(Math.log2(value));
+}
+
+function radix2Fft(re: Float64Array, im: Float64Array): void {
+  const n = re.length;
+  for (let index = 1, reversed = 0; index < n; index += 1) {
+    let bit = n >> 1;
+    while ((reversed & bit) !== 0) {
+      reversed ^= bit;
+      bit >>= 1;
+    }
+    reversed ^= bit;
+    if (index < reversed) {
+      const reTmp = re[index] ?? 0;
+      re[index] = re[reversed] ?? 0;
+      re[reversed] = reTmp;
+      const imTmp = im[index] ?? 0;
+      im[index] = im[reversed] ?? 0;
+      im[reversed] = imTmp;
+    }
+  }
+
+  for (let length = 2; length <= n; length <<= 1) {
+    const angle = (-2 * Math.PI) / length;
+    const stepRe = Math.cos(angle);
+    const stepIm = Math.sin(angle);
+    const half = length >> 1;
+    for (let start = 0; start < n; start += length) {
+      let twiddleRe = 1;
+      let twiddleIm = 0;
+      for (let offset = 0; offset < half; offset += 1) {
+        const even = start + offset;
+        const odd = even + half;
+        const oddRe = (re[odd] ?? 0) * twiddleRe - (im[odd] ?? 0) * twiddleIm;
+        const oddIm = (re[odd] ?? 0) * twiddleIm + (im[odd] ?? 0) * twiddleRe;
+        const evenRe = re[even] ?? 0;
+        const evenIm = im[even] ?? 0;
+        re[even] = evenRe + oddRe;
+        im[even] = evenIm + oddIm;
+        re[odd] = evenRe - oddRe;
+        im[odd] = evenIm - oddIm;
+        const nextRe = twiddleRe * stepRe - twiddleIm * stepIm;
+        twiddleIm = twiddleRe * stepIm + twiddleIm * stepRe;
+        twiddleRe = nextRe;
+      }
+    }
+  }
+}
+
+function bandEnergies(frame: Int16Array, re: Float64Array, im: Float64Array): number[] {
+  const n = re.length;
+  if (n < 2) return BAND_EDGES_HZ.slice(0, -1).map(() => 0);
+
+  re.fill(0);
+  im.fill(0);
+  for (let index = 0; index < n; index += 1) {
+    const window = 0.5 - 0.5 * Math.cos((2 * Math.PI * index) / (n - 1));
+    re[index] = ((frame[index] ?? 0) / 32_768) * window;
+  }
+  radix2Fft(re, im);
+
+  const bands: number[] = [];
+  for (let band = 0; band < BAND_EDGES_HZ.length - 1; band += 1) {
+    const start = Math.max(1, Math.floor((BAND_EDGES_HZ[band]! * n) / CAPTURE_SAMPLE_RATE));
+    const end = Math.min(
+      n / 2,
+      Math.ceil((BAND_EDGES_HZ[band + 1]! * n) / CAPTURE_SAMPLE_RATE),
+    );
+    let peak = 0;
+    for (let bin = start; bin < end; bin += 1) {
+      peak = Math.max(peak, Math.hypot(re[bin] ?? 0, im[bin] ?? 0));
+    }
+    bands.push(peak / n);
+  }
+  return bands;
+}
+
+function blockForLevel(level: number): string {
+  const normalized = Math.min(1, Math.max(0, level) * LEVEL_GAIN);
+  const index = Math.min(
+    BLOCKS.length - 1,
+    Math.round(Math.sqrt(normalized) * (BLOCKS.length - 1)),
+  );
+  return BLOCKS[index] ?? "▁";
+}
+
+export function formatElapsed(ms: number): string {
+  const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return `${minutes}:${seconds.toString().padStart(2, "0")}`;
+}
+
+/** Shared completion summary for regular dictation and the onboarding test. */
+export function formatTranscriptionSummary(
+  audioSeconds: number,
+  transcribeSeconds: number,
+): string {
+  return `Transcribed ${audioSeconds.toFixed(1)}s of audio in ${transcribeSeconds.toFixed(1)}s`;
+}
+
+export function showTranscribeStatus(
+  ctx: ExtensionContext,
+  text: string,
+  options?: { cancelKeys?: string },
+): void {
+  if (!ctx.hasUI) return;
+  const theme = ctx.ui.theme;
+  const hint = options?.cancelKeys ? `  ${theme.fg("dim", `${options.cancelKeys} to cancel`)}` : "";
+  ctx.ui.setWidget(WIDGET_KEY, [`${theme.fg("muted", text)}${hint}`]);
+}
+
+export function clearTranscribeWidget(ctx: ExtensionContext): void {
+  if (!ctx.hasUI) return;
+  ctx.ui.setWidget(WIDGET_KEY, undefined);
+}
+
+/**
+ * Ready line shown when setup finishes: a green check, then the body in the
+ * terminal's default foreground so it matches what the user types. The help
+ * command is accented and its description muted. The caller decides how long it stays.
+ */
+export function showReadyStatus(
+  ctx: ExtensionContext,
+  options: {
+    talk: string;
+    help: { command: string; description: string };
+  },
+): void {
+  if (!ctx.hasUI) return;
+  const theme = ctx.ui.theme;
+  ctx.ui.setWidget(WIDGET_KEY, [
+    `${theme.fg("success", "✓")} Pi Voice ready · ${options.talk}`,
+    `${theme.fg("accent", options.help.command)} ${theme.fg("muted", options.help.description)}`,
+  ]);
+}
+
+export type MeterModelState = "loading" | "ready" | "failed";
+
+/** Peak-hold band levels computed from capture frames. */
+export class SpectrumAnalyzer {
+  readonly bands: number[] = Array.from({ length: BAND_EDGES_HZ.length - 1 }, () => 0);
+  private re: Float64Array | undefined;
+  private im: Float64Array | undefined;
+
+  reset(): void {
+    this.bands.fill(0);
+    this.re = undefined;
+    this.im = undefined;
+  }
+
+  push(frame: Int16Array): void {
+    const n = floorPowerOfTwo(frame.length);
+    if (!this.re || !this.im || this.re.length !== n) {
+      this.re = new Float64Array(n);
+      this.im = new Float64Array(n);
+    }
+    const energies = bandEnergies(frame, this.re, this.im);
+    for (let index = 0; index < this.bands.length; index += 1) {
+      this.bands[index] = Math.max(energies[index] ?? 0, (this.bands[index] ?? 0) * DECAY);
+    }
+  }
+}
+
+/**
+ * The one-line recording meter: band blocks, elapsed time, model state, and
+ * an optional trailing hint. Every surface that shows a recording renders
+ * through here so the editor widget and the setup pane look the same.
+ */
+export function renderMeterLine(
+  theme: UiTheme,
+  options: {
+    bands: readonly number[];
+    elapsedMs: number;
+    modelState: MeterModelState;
+    actionHint?: string;
+    discardHint?: string;
+  },
+): string {
+  const parts = [
+    theme.fg("accent", options.bands.map(blockForLevel).join("")),
+    theme.fg("muted", formatElapsed(options.elapsedMs)),
+  ];
+  if (options.modelState === "loading") parts.push(theme.fg("dim", "loading model"));
+  if (options.modelState === "failed") parts.push(theme.fg("warning", "model load failed"));
+  if (options.actionHint) parts.push(theme.fg("muted", options.actionHint));
+  if (options.discardHint) parts.push(theme.fg("dim", options.discardHint));
+  return parts.join("  ");
+}
+
+/** Left-to-right FFT meter shown above the editor while recording. */
+export class RecordingMeter {
+  private readonly analyzer = new SpectrumAnalyzer();
+  private startedAt = 0;
+  private nextPaintAt = 0;
+  private lastLine: string | undefined;
+  private ctx: ExtensionContext | undefined;
+  private modelState: MeterModelState = "loading";
+  private hints: { action: string; discard: string } | undefined;
+
+  start(
+    ctx: ExtensionContext,
+    hints: { action: string; discard: string },
+  ): void {
+    if (!ctx.hasUI) return;
+    this.ctx = ctx;
+    this.hints = hints;
+    this.startedAt = Date.now();
+    this.analyzer.reset();
+    this.nextPaintAt = 0;
+    this.lastLine = undefined;
+    this.modelState = "loading";
+    this.paint();
+  }
+
+  setModelState(state: MeterModelState): void {
+    this.modelState = state;
+    this.paint();
+  }
+
+  push(frame: Int16Array): void {
+    if (!this.ctx) return;
+    this.analyzer.push(frame);
+    const now = Date.now();
+    if (now < this.nextPaintAt) return;
+    this.nextPaintAt = now + METER_UPDATE_MS;
+    this.paint();
+  }
+
+  stop(options?: { clearWidget?: boolean }): void {
+    // Callers transitioning to another status on the same slot pass
+    // clearWidget: false so the widget area never collapses between states.
+    if (options?.clearWidget !== false) this.ctx?.ui.setWidget(WIDGET_KEY, undefined);
+    this.ctx = undefined;
+    this.lastLine = undefined;
+    this.hints = undefined;
+  }
+
+  private paint(): void {
+    const ctx = this.ctx;
+    if (!ctx) return;
+
+    const line = renderMeterLine(ctx.ui.theme, {
+      bands: this.analyzer.bands,
+      elapsedMs: Date.now() - this.startedAt,
+      modelState: this.modelState,
+      actionHint: this.hints?.action,
+      discardHint: this.hints?.discard,
+    });
+    if (line === this.lastLine) return;
+    this.lastLine = line;
+    ctx.ui.setWidget(WIDGET_KEY, [line]);
+  }
+}