@hienlh/ppm 0.23.6 → 0.23.7

package/src/web/hooks/use-minute-clock.ts

@@ -0,0 +1,20 @@
+import { useEffect, useState } from "react";
+
+/**
+ * `Date.now()`, re-read once a minute.
+ *
+ * Re-read rather than counted: a phone that slept for six hours throttles timers or drops
+ * them entirely, so an accumulated tally comes back six hours short — and every caller here
+ * is measuring exactly the kind of gap a sleeping device produces.
+ *
+ * One minute because that is the finest unit any of this is displayed at; a second-resolution
+ * tick would re-render the composer sixty times for a label that cannot change.
+ */
+export function useMinuteClock(): number {
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    const id = setInterval(() => setNow(Date.now()), 60_000);
+    return () => clearInterval(id);
+  }, []);
+  return now;
+}

package/src/web/hooks/use-whisper-voice-input.ts

@@ -0,0 +1,113 @@
+import { useCallback, useRef, useState } from "react";
+import { toast } from "sonner";
+import { getAuthToken } from "@/lib/api-client";
+import { recordingToWav } from "@/lib/voice-wav";
+
+/**
+ * The chat mic when Settings has it pointed at Whisper on the PPM host.
+ *
+ * Same shape as `useVoiceInput` (the browser's own recogniser) so the composer
+ * can swap one for the other, with one extra state: Whisper is not streaming,
+ * so there is a wait between "stopped talking" and "text appears" that the
+ * button has to show — `isTranscribing`.
+ *
+ * `supported` is about recording, not recognising: any browser with
+ * `MediaRecorder` can feed this, which is the point of doing it on the server.
+ * Both still need a secure context — `navigator.mediaDevices` does not exist on
+ * a plain-HTTP origin, so neither engine can reach the mic there.
+ */
+export function useWhisperVoiceInput(language = "vi") {
+  const [isListening, setIsListening] = useState(false);
+  const [isTranscribing, setIsTranscribing] = useState(false);
+  const recorderRef = useRef<MediaRecorder | null>(null);
+  const chunksRef = useRef<Blob[]>([]);
+  const cancelledRef = useRef(false);
+
+  const supported =
+    typeof window !== "undefined" &&
+    typeof MediaRecorder !== "undefined" &&
+    typeof navigator !== "undefined" &&
+    !!navigator.mediaDevices?.getUserMedia &&
+    typeof OfflineAudioContext !== "undefined";
+
+  const start = useCallback(
+    async (onResult: (text: string, isFinal: boolean) => void) => {
+      if (!supported || recorderRef.current) return;
+      let stream: MediaStream;
+      try {
+        stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+      } catch {
+        toast.error("Microphone unavailable", { description: "Allow microphone access for this site." });
+        return;
+      }
+
+      const recorder = new MediaRecorder(stream);
+      recorderRef.current = recorder;
+      chunksRef.current = [];
+      cancelledRef.current = false;
+
+      recorder.ondataavailable = (e) => {
+        if (e.data.size > 0) chunksRef.current.push(e.data);
+      };
+
+      recorder.onstop = async () => {
+        // Release the mic before the wait, or the browser keeps its recording
+        // indicator lit for the whole transcription.
+        for (const track of stream.getTracks()) track.stop();
+        recorderRef.current = null;
+        setIsListening(false);
+
+        const chunks = chunksRef.current;
+        chunksRef.current = [];
+        if (cancelledRef.current || chunks.length === 0) return;
+
+        setIsTranscribing(true);
+        try {
+          const wav = await recordingToWav(new Blob(chunks, { type: recorder.mimeType }));
+          const text = await postForTranscript(wav, language);
+          if (text) onResult(text, true);
+          else
+            toast.info("Nothing was picked up", {
+              description: "Speak closer to the mic, or check which input device is selected.",
+            });
+        } catch (e) {
+          toast.error("Could not transcribe", { description: e instanceof Error ? e.message : String(e) });
+        } finally {
+          setIsTranscribing(false);
+        }
+      };
+
+      recorder.start();
+      setIsListening(true);
+    },
+    [supported, language],
+  );
+
+  /** Finish the recording and transcribe it. */
+  const stop = useCallback(() => {
+    if (recorderRef.current?.state === "recording") recorderRef.current.stop();
+  }, []);
+
+  /** Drop the recording — used when the message is sent while the mic is open. */
+  const cancel = useCallback(() => {
+    cancelledRef.current = true;
+    stop();
+  }, [stop]);
+
+  return { isListening, isTranscribing, start, stop, cancel, supported };
+}
+
+async function postForTranscript(wav: Uint8Array, language: string): Promise<string> {
+  const token = getAuthToken();
+  const res = await fetch(`/api/speech/transcribe?lang=${encodeURIComponent(language)}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "audio/wav",
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    },
+    body: wav as BodyInit,
+  });
+  const json = (await res.json().catch(() => null)) as { ok?: boolean; data?: { text: string }; error?: string } | null;
+  if (!res.ok || !json?.ok) throw new Error(json?.error ?? `HTTP ${res.status}`);
+  return json.data?.text ?? "";
+}

package/src/web/lib/api-tunnels.ts

@@ -19,3 +19,22 @@ export const tunnelsApi = {
   start: (port: number) => api.post<{ port: number; url: string }>("/api/tunnels", { port }),
   stop: (pid: number) => api.del(`/api/tunnels/${pid}`),
 };
+
+/**
+ * PPM's own public tunnel (`/api/tunnel`) — distinct from the registry above,
+ * which lists every cloudflared on the machine.
+ */
+export interface PublicTunnelStatus {
+  /** A tunnel is actually serving right now. */
+  active: boolean;
+  url: string | null;
+  localUrl: string | null;
+  /** The master switch. Absent on a server older than it, where it was always on. */
+  enabled?: boolean;
+}
+
+export const publicTunnelApi = {
+  status: () => api.get<PublicTunnelStatus>("/api/tunnel"),
+  setEnabled: (enabled: boolean) =>
+    api.post<{ enabled: boolean; reload: string }>("/api/tunnel/enabled", { enabled }),
+};

package/src/web/lib/branch-select-items.ts

@@ -0,0 +1,29 @@
+/**
+ * A repository's branches, as items for the searchable select.
+ *
+ * Local branches are listed before remote-tracking ones, under their own headings,
+ * because that is the order a choice is made in — and because a repository with a
+ * few dozen local branches routinely has hundreds of remote ones, and ungrouped the
+ * handful anyone is choosing between is lost among them. The label is the whole
+ * name, `remotes/origin/` included, so typing `origin` narrows to one remote.
+ */
+import { Cloud, GitBranch as GitBranchIcon } from "@/lib/icons";
+import type { SearchSelectItem } from "./search-select-rows";
+import type { GitBranch } from "../../types/git";
+
+function branchItem(branch: GitBranch): SearchSelectItem {
+  return {
+    value: branch.name,
+    label: branch.name,
+    group: branch.remote ? "Remote branches" : "Branches",
+    icon: branch.remote ? Cloud : GitBranchIcon,
+    hint: branch.current ? "current" : undefined,
+  };
+}
+
+export function branchItems(branches: GitBranch[]): SearchSelectItem[] {
+  return [
+    ...branches.filter((b) => !b.remote),
+    ...branches.filter((b) => b.remote),
+  ].map(branchItem);
+}

package/src/web/lib/cpu-graph-mode.ts

@@ -0,0 +1,90 @@
+/**
+ * Which CPU graph the Performance page draws — Mission Center's "Change Top
+ * Graph To" menu, ported.
+ *
+ * Pure and free of store imports on purpose: importing the settings store reads
+ * `localStorage` at module scope and throws under `bun:test`, so the parsing and
+ * the grid maths would be untestable if they lived beside the component.
+ */
+
+export const CPU_GRAPH_MODES = ["overall", "logical", "threads", "threads-stacked"] as const;
+export type CpuGraphMode = (typeof CPU_GRAPH_MODES)[number];
+
+export const CPU_GRAPH_LABELS: Record<CpuGraphMode, string> = {
+  overall: "Overall utilisation",
+  logical: "Logical processors",
+  threads: "All threads",
+  "threads-stacked": "All threads stacked",
+};
+
+/** A mode off localStorage is untrusted the same way one off the wire is. */
+export function parseCpuGraphMode(value: unknown): CpuGraphMode {
+  return CPU_GRAPH_MODES.includes(value as CpuGraphMode) ? (value as CpuGraphMode) : "overall";
+}
+
+/** Mission Center's second, full-width graph under the utilisation one. `none`
+ *  removes it rather than drawing an empty frame. */
+export const CPU_BOTTOM_GRAPHS = ["temperature", "power", "clock", "none"] as const;
+export type CpuBottomGraph = (typeof CPU_BOTTOM_GRAPHS)[number];
+
+export const CPU_BOTTOM_LABELS: Record<CpuBottomGraph, string> = {
+  temperature: "Temperature",
+  power: "Power draw",
+  clock: "Clock speed",
+  none: "None",
+};
+
+export function parseCpuBottomGraph(value: unknown): CpuBottomGraph {
+  return CPU_BOTTOM_GRAPHS.includes(value as CpuBottomGraph)
+    ? (value as CpuBottomGraph)
+    : "temperature";
+}
+
+/** Below this a cell is too narrow to read a curve in, so the grid drops a column
+ *  rather than shrinking past it. 24 threads at Mission Center's six columns needs
+ *  a ~700px pane; a floating window or a phone routinely has less. */
+export const MIN_CELL_PX = 84;
+
+export interface CoreGridLayout {
+  cols: number;
+  rows: number;
+}
+
+/**
+ * Mission Center lays the per-thread grid out as `rows = floor(sqrt(n))`, then
+ * fills each row — which is what puts a 24-thread i9 in 6 columns of 4 rather
+ * than the 5x5 a naive `ceil(sqrt(n))` would give.
+ *
+ * The width clamp is ours: that layout assumes a window as wide as the screen,
+ * and PPM draws this inside a resizable floating window and on a phone. Columns
+ * are capped by what fits, never by a breakpoint — the pane's own width is the
+ * only thing that knows whether six curves fit side by side.
+ */
+export function coreGridLayout(count: number, widthPx: number): CoreGridLayout {
+  if (count <= 0) return { cols: 0, rows: 0 };
+  const missionCenterCols = Math.ceil(count / Math.max(1, Math.floor(Math.sqrt(count))));
+  // A width of 0 is "not measured yet" (the element has not laid out), not "no
+  // room" — clamping to one column there would draw a 24-row column for a frame.
+  const fits = widthPx > 0 ? Math.max(1, Math.floor(widthPx / MIN_CELL_PX)) : missionCenterCols;
+  const cols = Math.min(missionCenterCols, fits);
+  return { cols, rows: Math.ceil(count / cols) };
+}
+
+/**
+ * How long the visible history window actually spans, for the "over 1 minute"
+ * caption Mission Center writes above each graph. Ours is read from the points
+ * themselves rather than assumed: PPM's window is 200 points at the server's own
+ * cadence, which is 2s on the full tier and 5s on the light one, so a fixed
+ * wording would be wrong on one of them and wrong again on a fresh window that
+ * has only collected a few seconds.
+ */
+export function historySpanLabel(timestamps: readonly number[]): string | undefined {
+  if (timestamps.length < 2) return undefined;
+  const first = timestamps[0]!;
+  const last = timestamps[timestamps.length - 1]!;
+  const seconds = Math.round((last - first) / 1000);
+  if (!Number.isFinite(seconds) || seconds <= 0) return undefined;
+  if (seconds < 90) return `over ${seconds} seconds`;
+  const minutes = Math.round(seconds / 60);
+  return minutes === 1 ? "over 1 minute" : `over ${minutes} minutes`;
+}

package/src/web/lib/format-bytes.ts

@@ -5,6 +5,20 @@ export function formatRam(mb: number): string {
   return mb < 1024 ? `${mb.toFixed(0)} MB` : `${(mb / 1024).toFixed(1)} GB`;
 }
 
+/** A plain byte count — capacities, and the since-boot totals on a device page. */
+export function formatBytes(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 0) return "—";
+  if (bytes < 1024) return `${bytes.toFixed(0)} B`;
+  const units = ["KB", "MB", "GB", "TB", "PB"];
+  let value = bytes / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit++;
+  }
+  return `${value.toFixed(value < 10 ? 1 : 0)} ${units[unit]}`;
+}
+
 /** Bytes/second → human-readable rate, 1 decimal past B/s. */
 export function formatBps(bytesPerSec: number): string {
   if (bytesPerSec < 1024) return `${bytesPerSec.toFixed(0)} B/s`;

package/src/web/lib/git-ref-picker.ts

@@ -0,0 +1,120 @@
+/**
+ * The decisions behind the branch picker, kept out of the component.
+ *
+ * Two of them are not presentation at all. `checkoutTarget` decides what git is
+ * actually asked to run, and `buildRows` decides what Enter lands on — both are
+ * worth a test, and importing the component to reach them would pull in the
+ * zustand stores, which read `localStorage` at module scope and throw under
+ * `bun:test`.
+ */
+import type { CheckoutMode, GitRef } from "../../types/git";
+
+/** The three items above the ref list, in VS Code's order. */
+export type PickerAction = "create" | "create-from" | "detach";
+
+export const PICKER_ACTIONS: { action: PickerAction; label: string }[] = [
+  { action: "create", label: "Create new branch..." },
+  { action: "create-from", label: "Create new branch from..." },
+  { action: "detach", label: "Checkout detached..." },
+];
+
+/** Group headers, and the order the groups appear in. */
+const GROUPS: { type: GitRef["type"]; label: string }[] = [
+  { type: "branch", label: "branches" },
+  { type: "remote", label: "remote branches" },
+  { type: "tag", label: "tags" },
+];
+
+export type PickerRow =
+  | { kind: "action"; action: PickerAction; label: string }
+  | { kind: "separator"; label: string }
+  | { kind: "ref"; ref: GitRef };
+
+function matchesRef(ref: GitRef, q: string): boolean {
+  return !q || ref.name.toLowerCase().includes(q) || ref.subject.toLowerCase().includes(q);
+}
+
+/**
+ * The visible rows for one query.
+ *
+ * A group header is emitted only when something survives the filter under it —
+ * a "tags" heading over nothing reads as a list that failed to load. The
+ * actions are filtered by their own labels, which is what VS Code's quick pick
+ * does to every item it is given; `actions: false` is the second stage, where
+ * the question is only which ref to branch from or detach at.
+ */
+export function buildRows(
+  refs: GitRef[],
+  query: string,
+  opts: { actions: boolean } = { actions: true },
+): PickerRow[] {
+  const q = query.trim().toLowerCase();
+  const rows: PickerRow[] = [];
+
+  if (opts.actions) {
+    for (const a of PICKER_ACTIONS) {
+      if (!q || a.label.toLowerCase().includes(q)) rows.push({ kind: "action", ...a });
+    }
+  }
+
+  for (const group of GROUPS) {
+    const matched = refs.filter((r) => r.type === group.type && matchesRef(r, q));
+    if (!matched.length) continue;
+    rows.push({ kind: "separator", label: group.label });
+    for (const ref of matched) rows.push({ kind: "ref", ref });
+  }
+
+  return rows;
+}
+
+/**
+ * The first row Enter may land on, or -1 when the filter matched nothing.
+ *
+ * Typed on the `kind` alone rather than on `PickerRow`, so the branch select in
+ * Branch Review keyboard-navigates its own rows with this same pair instead of
+ * a second copy of the wrap-and-skip-headers arithmetic.
+ */
+export function firstSelectable(rows: readonly { kind: string }[]): number {
+  return rows.findIndex((r) => r.kind !== "separator");
+}
+
+/** Arrow-key movement: wraps, and never stops on a group header. */
+export function moveSelection(rows: readonly { kind: string }[], current: number, step: 1 | -1): number {
+  const n = rows.length;
+  if (!n) return -1;
+  let idx = current;
+  for (let i = 0; i < n; i++) {
+    idx = (idx + step + n) % n;
+    if (rows[idx]!.kind !== "separator") return idx;
+  }
+  return -1;
+}
+
+/** `origin/feature/x` → `feature/x`. The remote name is the first segment and only the first. */
+export function localNameFor(remoteName: string): string {
+  const slash = remoteName.indexOf("/");
+  return slash < 0 ? remoteName : remoteName.slice(slash + 1);
+}
+
+/**
+ * What picking a ref actually has to run.
+ *
+ * A remote-tracking ref is not a branch: `git checkout origin/foo` lands on a
+ * **detached HEAD** at that commit, which looks like it worked right up until
+ * the first commit made on it belongs to no branch. `-t` is what creates the
+ * local branch that follows it — but `-t` *fails* when that local branch
+ * already exists, and checking the existing one out is what the user meant
+ * anyway. Deciding here rather than server-side is deliberate: the answer needs
+ * the whole ref list, which the picker already has and the route does not.
+ */
+export function checkoutTarget(ref: GitRef, refs: GitRef[]): { ref: string; mode: CheckoutMode } {
+  if (ref.type !== "remote") return { ref: ref.name, mode: "checkout" };
+  const local = localNameFor(ref.name);
+  const exists = refs.some((r) => r.type === "branch" && r.name === local);
+  return exists ? { ref: local, mode: "checkout" } : { ref: ref.name, mode: "track" };
+}
+
+/** The second line of a row: `thawngho · 7b758e3 · fix(NX-5832): stop retrying…` */
+export function refDetail(ref: GitRef): string {
+  return [ref.author, ref.shortHash, ref.subject].filter(Boolean).join(" · ");
+}

package/src/web/lib/lsp/lsp-client.ts

@@ -28,6 +28,10 @@ export interface LspMissingServer {
   id: string;
   displayName: string;
   installHint: string;
+  /** Whether PPM can install this one on *this host* — a toolchain-based install needs that toolchain. */
+  installable?: boolean;
+  /** What the install would use, so the dialog can say what pressing the button does. */
+  installWith?: "bun" | "go" | "rustup";
 }
 
 export type LspDocumentStatus =
@@ -132,6 +136,22 @@ export class LspConnection {
     return this.docs.get(path)?.status;
   }
 
+  /**
+   * Ask again for every document that had no server.
+   *
+   * What an install leaves to do: the file is already open, and closing and reopening the tab
+   * to pick up a server that has just appeared is exactly the step the button exists to remove.
+   * Only the documents with nothing serving them, so a tab that already has a server is never
+   * taken away from it.
+   */
+  retryUnavailable(): void {
+    for (const [path, entry] of this.docs) {
+      if (entry.status.state !== "unavailable") continue;
+      this.setStatus(path, { state: "opening" });
+      this.sendOpen(path);
+    }
+  }
+
   // ── Requests ────────────────────────────────────────────────────────────
 
   /**
@@ -309,6 +329,18 @@ export function acquireLspConnection(projectName: string): LspConnection {
   return connection;
 }
 
+/**
+ * `retryUnavailable` on every open connection.
+ *
+ * One install serves every project at once — one `bun add` puts the server where every session
+ * looks — and the editors of other projects are still mounted behind the tab pool, so asking
+ * only the project whose dialog was open would leave the others claiming a server is missing
+ * that is now installed.
+ */
+export function retryUnavailableLspDocuments(): void {
+  for (const entry of connections.values()) entry.connection.retryUnavailable();
+}
+
 /** True when that was the last holder, so the project has no editor open any more. */
 export function releaseLspConnection(projectName: string): boolean {
   const existing = connections.get(projectName);

package/src/web/lib/search-select-rows.ts

@@ -0,0 +1,55 @@
+/**
+ * The rows a searchable select shows for one query.
+ *
+ * Pure, and in `lib` rather than beside the component, because importing the
+ * component reaches the sheet's hooks, which want a DOM — the decisions here are
+ * testable without one.
+ *
+ * The match is a case-insensitive substring of the whole label, the same one the
+ * checkout quick pick makes. Not a prefix: the lists this serves are names that
+ * agree for most of their length — `fix/NX-5175-…` branches, `nxsys-backend-nx5833`
+ * checkouts — and the part anyone types is the part that differs.
+ *
+ * A heading is emitted only when something under it survived the filter, the rule
+ * `git-ref-picker.ts` follows too: a heading over nothing reads as a list that failed
+ * to load. Groups keep the order they first appear in over the *whole* list, so a
+ * filter that empties the first group does not reorder the rest.
+ */
+import type { ElementType } from "react";
+
+export interface SearchSelectItem {
+  value: string;
+  /** Shown on the row and on the trigger, and what the filter matches. */
+  label: string;
+  /** The heading this row is listed under. Items with none get no heading. */
+  group?: string;
+  icon?: ElementType;
+  /** Short muted text at the end of the row — `current`, say. */
+  hint?: string;
+  /** Tooltip, for when the label is a shortened form of something longer. */
+  title?: string;
+}
+
+export type SearchSelectRow =
+  | { kind: "separator"; label: string }
+  | { kind: "item"; item: SearchSelectItem };
+
+export function searchRows(items: SearchSelectItem[], query: string): SearchSelectRow[] {
+  const q = query.trim().toLowerCase();
+  const matched = q ? items.filter((i) => i.label.toLowerCase().includes(q)) : items;
+  const rows: SearchSelectRow[] = [];
+
+  for (const group of new Set(items.map((i) => i.group))) {
+    const inGroup = matched.filter((i) => i.group === group);
+    if (!inGroup.length) continue;
+    if (group !== undefined) rows.push({ kind: "separator", label: group });
+    for (const item of inGroup) rows.push({ kind: "item", item });
+  }
+
+  return rows;
+}
+
+/** Where a value sits in the rows, or -1 — what opens the list on the current choice. */
+export function rowIndexOf(rows: SearchSelectRow[], value: string): number {
+  return rows.findIndex((r) => r.kind === "item" && r.item.value === value);
+}

package/src/web/lib/temperature.ts

@@ -0,0 +1,27 @@
+/**
+ * Temperature display unit — Mission Center's one Preferences setting that changes
+ * what a number MEANS rather than how often it is fetched.
+ *
+ * Every collector reports Celsius, so this is purely a display conversion and the
+ * conversion stays here rather than in six detail panels. `undefined` survives
+ * untouched: the whole System Monitor treats it as "this host cannot measure
+ * that", and a missing sensor must never render as 32 °F.
+ */
+export type TempUnit = "c" | "f";
+
+export function toFahrenheit(celsius: number): number {
+  return celsius * 9 / 5 + 32;
+}
+
+/** A temperature ready to render, or undefined when there is nothing to show. */
+export function formatTemp(celsius: number | undefined, unit: TempUnit): string | undefined {
+  if (celsius === undefined || !Number.isFinite(celsius)) return undefined;
+  return unit === "f"
+    ? `${toFahrenheit(celsius).toFixed(1)} °F`
+    : `${celsius.toFixed(1)} °C`;
+}
+
+/** A value off localStorage is untrusted the same way one off the wire is. */
+export function parseTempUnit(value: unknown): TempUnit {
+  return value === "f" ? "f" : "c";
+}

package/src/web/lib/voice-wav.ts

@@ -0,0 +1,69 @@
+/**
+ * Turning what `MediaRecorder` produced into what whisper.cpp reads.
+ *
+ * The browser records Opus in WebM (Chrome), Opus in Ogg (Firefox) or AAC in
+ * MP4 (Safari); whisper.cpp reads wav, flac, mp3 and Vorbis-ogg — so none of
+ * them, and converting on the host would mean requiring ffmpeg there. The
+ * browser already has a decoder for its own recording, so the conversion
+ * happens here.
+ *
+ * `decodeAudioData` resamples to the context's rate, which is why the context
+ * is created at 16 kHz: that is Whisper's own rate, and it makes the upload a
+ * third of what 48 kHz would cost (32 KB per second of speech).
+ */
+
+export const WHISPER_SAMPLE_RATE = 16_000;
+
+/** Average the channels; Whisper takes mono and a stereo mic gains it nothing. */
+export function mixToMono(channels: Float32Array[]): Float32Array {
+  if (channels.length === 0) return new Float32Array(0);
+  if (channels.length === 1) return channels[0]!;
+  const length = channels[0]!.length;
+  const out = new Float32Array(length);
+  for (let i = 0; i < length; i++) {
+    let sum = 0;
+    for (const channel of channels) sum += channel[i] ?? 0;
+    out[i] = sum / channels.length;
+  }
+  return out;
+}
+
+/** 16-bit PCM WAV: a 44-byte header and the samples, clamped to [-1, 1). */
+export function encodeWavPcm16(samples: Float32Array, sampleRate: number): Uint8Array {
+  const buffer = new ArrayBuffer(44 + samples.length * 2);
+  const view = new DataView(buffer);
+  const ascii = (offset: number, text: string) => {
+    for (let i = 0; i < text.length; i++) view.setUint8(offset + i, text.charCodeAt(i));
+  };
+
+  ascii(0, "RIFF");
+  view.setUint32(4, 36 + samples.length * 2, true);
+  ascii(8, "WAVE");
+  ascii(12, "fmt ");
+  view.setUint32(16, 16, true); // PCM header size
+  view.setUint16(20, 1, true); // format: PCM
+  view.setUint16(22, 1, true); // channels: mono
+  view.setUint32(24, sampleRate, true);
+  view.setUint32(28, sampleRate * 2, true); // byte rate
+  view.setUint16(32, 2, true); // block align
+  view.setUint16(34, 16, true); // bits per sample
+  ascii(36, "data");
+  view.setUint32(40, samples.length * 2, true);
+
+  for (let i = 0; i < samples.length; i++) {
+    const clamped = Math.max(-1, Math.min(1, samples[i]!));
+    view.setInt16(44 + i * 2, clamped < 0 ? clamped * 0x8000 : clamped * 0x7fff, true);
+  }
+  return new Uint8Array(buffer);
+}
+
+/** Decode a recording and re-encode it as a 16 kHz mono WAV. */
+export async function recordingToWav(blob: Blob): Promise<Uint8Array> {
+  const ctx = new OfflineAudioContext(1, 1, WHISPER_SAMPLE_RATE);
+  const decoded = await ctx.decodeAudioData(await blob.arrayBuffer());
+  const channels: Float32Array[] = [];
+  for (let i = 0; i < decoded.numberOfChannels; i++) channels.push(decoded.getChannelData(i));
+  // Header takes the buffer's own rate: a browser that declines to resample
+  // still produces a correct file, and whisper.cpp resamples it on its side.
+  return encodeWavPcm16(mixToMono(channels), decoded.sampleRate);
+}