@devaccel-labs/app-comments-toolbar 1.0.0 → 1.3.0

package/src/runtime/dictation-engine.ts

@@ -0,0 +1,616 @@
+/**
+ * One dictation take from a live microphone (ADR-APPC-010). The mic feeds a `Segmenter`; every piece it
+ * cuts is encoded and sent for transcription in order, one at a time, while the person keeps talking, so
+ * the words arrive a second or two after each pause. A piece that fails is retried, then held with its
+ * audio until the person retries or skips it; nothing after it is written out of order.
+ *
+ * A composer that can hold files may also keep the take itself: the same mic stream is recorded as compressed
+ * audio while it is transcribed, and handed over as one file when the take ends (see `DictationDeps.audio`).
+ */
+import { ApiError } from "./client.js";
+import { voiceRecordingName } from "./dictation-model.js";
+import {
+  encodeWav,
+  meterLevel,
+  microphoneError,
+  Resampler,
+  SAMPLE_RATE,
+  Segmenter,
+  type Piece,
+} from "./dictation.js";
+
+export { voiceRecordingName } from "./dictation-model.js";
+
+/** A take stops itself after this long. */
+export const MAX_TAKE_MS = 10 * 60_000;
+const RETRY_DELAYS_MS = [600, 1_500, 4_000];
+const REQUEST_TIMEOUT_MS = 25_000;
+/** Nothing above this from the mic for `SILENT_MIC_MS`: it is sending digital silence (muted, or the wrong device). */
+const SILENT_MIC_DB = -95;
+const SILENT_MIC_MS = 3_000;
+/** How often the piece still being spoken is re-read for the live preview, and the least audio worth it. */
+const PREVIEW_EVERY_MS = 1_200;
+const PREVIEW_MIN_SAMPLES = SAMPLE_RATE * 0.8;
+
+export type DictationPhase = "idle" | "starting" | "listening";
+
+export type DictationState = {
+  phase: DictationPhase;
+  /** Pieces cut and not yet written, including the one being transcribed. */
+  queued: number;
+  /** The first piece that couldn't be transcribed; everything after it waits. */
+  stalled: string | null;
+  /**
+   * Rough words for what was said and isn't written yet (needs `DictationDeps.preview`). Each piece's
+   * part is replaced by its final text when that is written.
+   */
+  preview: string;
+};
+
+export const idleDictation: DictationState = {
+  phase: "idle",
+  queued: 0,
+  stalled: null,
+  preview: "",
+};
+
+export type DictationDeps = {
+  transcribe(wav: Blob, prompt: string, signal: AbortSignal): Promise<string>;
+  /** The context sent with the next piece; read when it is sent, so it includes earlier pieces. */
+  prompt(): string;
+  write(text: string): void;
+  onState(state: DictationState): void;
+  /** Why a take stopped or never started, for the person to read. */
+  note(text: string): void;
+  /** Optional: a quick read of the piece still being spoken, shown as it grows. Failures are ignored. */
+  preview?(wav: Blob, prompt: string, signal: AbortSignal): Promise<string>;
+  /**
+   * Optional: the take as a voice recording, once it ends. Only composers that can attach files give this;
+   * the mic is then recorded alongside the transcription. Not called for a cancelled take.
+   */
+  audio?(file: File): void;
+  /** Whether to hand over the recording, read when the take ends so it can change mid-take. Default: yes. */
+  keepAudio?(): boolean;
+  /**
+   * Optional: a piece's final words with when they were spoken (`Date.now()` at the start of the piece, so a
+   * clip recording meanwhile can place them on its clock). Called right after `write`.
+   */
+  said?(text: string, spokenAt: number): void;
+};
+
+type Recording = { recorder: MediaRecorder; chunks: Blob[]; startedAt: number };
+
+type Capture = {
+  stream: MediaStream;
+  context: AudioContext;
+  nodes: AudioNode[];
+  startedAt: number;
+  limit: ReturnType<typeof setTimeout>;
+  recording: Recording | null;
+};
+
+/**
+ * `preview` is the live text that piece had when it was cut, shown until its final text is written. `spokenAt`
+ * is when the piece started (epoch ms), stamped at the cut by its length.
+ */
+type Waiting = { wav: Blob; seconds: number; preview: string; spokenAt: number };
+
+/** Only one box listens at a time; starting another stops this one. */
+let listening: Dictation | null = null;
+
+/** The AudioWorklet that hands the mic's samples to the page in ~2048-sample blocks. */
+const TAP = `class CsDictationTap extends AudioWorkletProcessor {
+  constructor() { super(); this.block = new Float32Array(2048); this.filled = 0; }
+  process(inputs) {
+    const channel = inputs[0] && inputs[0][0];
+    if (channel) for (let i = 0; i < channel.length; i++) {
+      this.block[this.filled++] = channel[i];
+      if (this.filled === this.block.length) {
+        this.port.postMessage(this.block, [this.block.buffer]);
+        this.block = new Float32Array(2048);
+        this.filled = 0;
+      }
+    }
+    return true;
+  }
+}
+registerProcessor("cs-dictation-tap", CsDictationTap);`;
+
+/** Compressed formats for the kept recording, best first. */
+const AUDIO_TYPES = ["audio/webm;codecs=opus", "audio/webm", "audio/mp4", "audio/ogg;codecs=opus"];
+/** A take shorter than this is a slip of the finger, not something worth attaching. */
+const MIN_RECORDING_MS = 1_000;
+
+function audioType(): string | null {
+  if (typeof MediaRecorder === "undefined") return null;
+  return AUDIO_TYPES.find((type) => MediaRecorder.isTypeSupported(type)) ?? null;
+}
+
+/** Whether this browser can keep a dictation take as a voice recording. */
+export function voiceRecordingSupported(): boolean {
+  return audioType() !== null;
+}
+
+/** Records the mic as compressed audio, or null when the browser can't or nobody wants it. */
+function startRecording(stream: MediaStream): Recording | null {
+  const type = audioType();
+  if (!type) return null;
+  try {
+    // Speech needs little: 32 kbps keeps a full 10-minute take near 2.4 MB, well under the 10 MB file cap.
+    const recorder = new MediaRecorder(stream, { mimeType: type, audioBitsPerSecond: 32_000 });
+    const recording: Recording = { recorder, chunks: [], startedAt: Date.now() };
+    recorder.addEventListener("dataavailable", (event: BlobEvent) => {
+      if (event.data.size > 0) recording.chunks.push(event.data);
+    });
+    recorder.start(1_000);
+    return recording;
+  } catch {
+    // The transcription still works without it.
+    return null;
+  }
+}
+
+/** Ends the recording and hands the file over, unless `deliver` is null (the take was dropped). */
+function finishRecording(recording: Recording, deliver: ((file: File) => void) | null) {
+  const { recorder, chunks, startedAt } = recording;
+  const done = () => {
+    if (!deliver || chunks.length === 0 || Date.now() - startedAt < MIN_RECORDING_MS) return;
+    const type = (recorder.mimeType || chunks[0]!.type || "audio/webm").split(";")[0]!.trim();
+    const blob = new Blob(chunks, { type });
+    deliver(new File([blob], voiceRecordingName(new Date(startedAt), type), { type }));
+  };
+  // The mic was unplugged: the recorder has already stopped and flushed.
+  if (recorder.state === "inactive") return done();
+  recorder.addEventListener("stop", done, { once: true });
+  try {
+    recorder.stop();
+  } catch {
+    // Already stopped by the track ending.
+  }
+}
+
+function audioContextClass(): typeof AudioContext | null {
+  if (typeof window === "undefined") return null;
+  const legacy: unknown = Reflect.get(window, "webkitAudioContext");
+  return (
+    window.AudioContext ?? (typeof legacy === "function" ? (legacy as typeof AudioContext) : null)
+  );
+}
+
+export function dictationSupported() {
+  return Boolean(
+    typeof navigator !== "undefined" &&
+    typeof navigator.mediaDevices?.getUserMedia === "function" &&
+    audioContextClass() &&
+    (typeof window === "undefined" || window.isSecureContext !== false),
+  );
+}
+
+/**
+ * The node that taps the mic. An AudioWorklet runs off the main thread, so a busy page can't drop audio;
+ * pages whose CSP blocks `blob:` scripts get the older ScriptProcessor, which works everywhere.
+ */
+async function tap(context: AudioContext, onSamples: (samples: Float32Array) => void) {
+  if (context.audioWorklet && typeof AudioWorkletNode !== "undefined") {
+    const url = URL.createObjectURL(new Blob([TAP], { type: "text/javascript" }));
+    try {
+      await context.audioWorklet.addModule(url);
+      const node = new AudioWorkletNode(context, "cs-dictation-tap", {
+        numberOfInputs: 1,
+        numberOfOutputs: 1,
+        channelCount: 1,
+        channelCountMode: "explicit",
+      });
+      node.port.onmessage = (event: MessageEvent<Float32Array>) => onSamples(event.data);
+      return node;
+    } catch {
+      // CSP or an old engine: fall through.
+    } finally {
+      URL.revokeObjectURL(url);
+    }
+  }
+  const node = context.createScriptProcessor(4096, 1, 1);
+  node.onaudioprocess = (event) => onSamples(event.inputBuffer.getChannelData(0).slice());
+  return node;
+}
+
+/** The site's microphone permission, where the browser exposes it. */
+async function microphonePermission(): Promise<PermissionState | null> {
+  try {
+    const status = await navigator.permissions?.query({ name: "microphone" });
+    return status?.state ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Whether the page's Permissions-Policy lets it use the mic, where the browser can say (Chromium). */
+function microphoneAllowedByPage(): boolean | null {
+  const policy: unknown =
+    Reflect.get(document, "permissionsPolicy") ?? Reflect.get(document, "featurePolicy");
+  const allows: unknown = policy ? Reflect.get(policy, "allowsFeature") : null;
+  if (typeof allows !== "function") return null;
+  try {
+    return Boolean(allows.call(policy, "microphone"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The browser's own answer, appended to a refusal so a screenshot shows which refusal it was: error name and
+ * text, the site permission, the page policy, and whether this is an app's built-in (Electron) browser.
+ */
+function refusalDetail(error: unknown, permission: PermissionState | null) {
+  const name = error instanceof Error || error instanceof DOMException ? error.name : "Error";
+  const message = error instanceof Error || error instanceof DOMException ? error.message : "";
+  const policy = microphoneAllowedByPage();
+  const parts = [
+    `${name}${message ? `: ${message}` : ""}`,
+    `site permission ${permission ?? "unknown"}`,
+    `page policy ${policy === null ? "unknown" : policy ? "allows" : "blocks"} mic`,
+    /\bElectron\//.test(navigator.userAgent) ? "Electron" : null,
+  ];
+  return parts.filter(Boolean).join(" · ");
+}
+
+function retryable(error: unknown) {
+  // fetch's TypeError (offline, DNS, a dropped connection) and our timeout are worth another go.
+  if (!(error instanceof ApiError)) return true;
+  if (fatal(error)) return false;
+  return error.status === 408 || error.status === 429 || error.status >= 500;
+}
+
+/** Errors that make every later piece fail too: stop listening rather than pile up audio. */
+function fatal(error: unknown) {
+  return (
+    error instanceof ApiError &&
+    (error.status === 401 ||
+      error.status === 403 ||
+      error.code === "dictation_unavailable" ||
+      error.code === "rate_limited")
+  );
+}
+
+function failureText(error: unknown) {
+  if (error instanceof ApiError) return error.message;
+  if (typeof navigator !== "undefined" && navigator.onLine === false)
+    return "You’re offline. Your words are kept and will be written when you’re back.";
+  return "Couldn’t reach the transcription service.";
+}
+
+function wait(ms: number, signal: AbortSignal) {
+  return new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(new DOMException("Aborted", "AbortError"));
+      },
+      { once: true },
+    );
+  });
+}
+
+export class Dictation {
+  private state: DictationState = idleDictation;
+  private capture: Capture | null = null;
+  private segmenter = new Segmenter();
+  private queue: Waiting[] = [];
+  private sending = false;
+  private stalled = false;
+  private abort = new AbortController();
+  /** Bumped by `cancel` and by every start, so an awaited step from an older take does nothing. */
+  private take = 0;
+  private previewTimer: ReturnType<typeof setInterval> | null = null;
+  private previewing = false;
+  /** Bumped when a piece is cut, so a preview of the old piece that lands late is dropped. */
+  private previewPiece = 0;
+  private previewedSamples = 0;
+  private live = "";
+  private readonly onOnline = () => {
+    if (this.stalled) this.retry();
+  };
+
+  /** Nothing is wired until `connect`: a take started before then writes nowhere. */
+  private deps: DictationDeps = {
+    transcribe: () => Promise.reject(new Error("Dictation isn’t connected.")),
+    prompt: () => "",
+    write: () => {},
+    onState: () => {},
+    note: () => {},
+  };
+
+  constructor(deps?: DictationDeps) {
+    if (deps) this.deps = deps;
+  }
+
+  /** Points the take at the latest callbacks; the React hook calls this after every render. */
+  connect(deps: DictationDeps) {
+    this.deps = deps;
+  }
+
+  get current() {
+    return this.state;
+  }
+
+  /** Live loudness (0–1), elapsed time and whether the mic seems dead, read by the meter every frame. */
+  meter() {
+    const capture = this.capture;
+    const elapsed = capture ? performance.now() - capture.startedAt : 0;
+    return {
+      level: capture ? meterLevel(this.segmenter.lastDb) : 0,
+      elapsedMs: elapsed,
+      silentMic:
+        Boolean(capture) && elapsed > SILENT_MIC_MS && this.segmenter.peakDb < SILENT_MIC_DB,
+    };
+  }
+
+  /**
+   * Must be called from the click or key press, so the browser lets the audio start. `recordVoice: false`
+   * skips the voice recording for this take (dictating over a screen recording, which has its own sound).
+   */
+  async start({ recordVoice = true }: { recordVoice?: boolean } = {}) {
+    if (this.state.phase !== "idle") return;
+    const AudioContextClass = audioContextClass();
+    if (!dictationSupported() || !AudioContextClass) {
+      this.deps.note(
+        "Dictation needs a secure (https) page in a browser that allows microphone access.",
+      );
+      return;
+    }
+    if (listening && listening !== this) listening.stop();
+    listening = this;
+    const take = ++this.take;
+    // Created inside the gesture: Safari only lets a context start from one.
+    const context = new AudioContextClass();
+    void context.resume().catch(() => {});
+    this.set({ phase: "starting" });
+    let stream: MediaStream;
+    try {
+      stream = await navigator.mediaDevices.getUserMedia({
+        audio: {
+          channelCount: 1,
+          echoCancellation: true,
+          noiseSuppression: true,
+          autoGainControl: true,
+        },
+      });
+    } catch (error) {
+      void context.close().catch(() => {});
+      if (take === this.take) {
+        this.set({ phase: "idle" });
+        const permission = await microphonePermission();
+        const detail = refusalDetail(error, permission);
+        // eslint-disable-next-line no-console -- the browser console is where a host page developer diagnoses a refused microphone.
+        console.warn("[app-comments] dictation: microphone refused", detail, error);
+        this.deps.note(
+          `${microphoneError(error, permission, navigator.userAgent, microphoneAllowedByPage())} (${detail})`,
+        );
+      }
+      if (listening === this) listening = null;
+      return;
+    }
+    if (take !== this.take) {
+      stream.getTracks().forEach((track) => track.stop());
+      void context.close().catch(() => {});
+      return;
+    }
+    try {
+      await context.resume();
+      const resampler = new Resampler(context.sampleRate);
+      this.segmenter = new Segmenter();
+      const source = context.createMediaStreamSource(stream);
+      const node = await tap(context, (samples) => {
+        if (take !== this.take || !this.capture) return;
+        for (const piece of this.segmenter.push(resampler.push(samples))) this.enqueue(piece);
+      });
+      if (take !== this.take) throw new DOMException("Cancelled", "AbortError");
+      // Silent output keeps the graph pulling audio in every browser without playing the mic back.
+      const mute = context.createGain();
+      mute.gain.value = 0;
+      source.connect(node);
+      node.connect(mute);
+      mute.connect(context.destination);
+      for (const track of stream.getAudioTracks())
+        track.addEventListener("ended", () => {
+          if (take === this.take) this.stop("The microphone disconnected.");
+        });
+      this.capture = {
+        stream,
+        context,
+        nodes: [source, node, mute],
+        recording: recordVoice && this.deps.audio ? startRecording(stream) : null,
+        startedAt: performance.now(),
+        limit: setTimeout(
+          () =>
+            this.stop(
+              "Dictation stopped at the 10-minute limit. What you said is kept; press the mic to keep going.",
+            ),
+          MAX_TAKE_MS,
+        ),
+      };
+      if (this.deps.preview)
+        this.previewTimer = setInterval(() => void this.refreshPreview(take), PREVIEW_EVERY_MS);
+      this.set({ phase: "listening" });
+    } catch (error) {
+      stream.getTracks().forEach((track) => track.stop());
+      void context.close().catch(() => {});
+      if (take === this.take) {
+        this.set({ phase: "idle" });
+        this.deps.note(microphoneError(error));
+        if (listening === this) listening = null;
+      }
+    }
+  }
+
+  /** Stops the mic. What was said is still sent and written, and the recording handed over. */
+  stop(note: string | null = null) {
+    this.endTake(true);
+    this.set({ phase: "idle" });
+    if (note) this.deps.note(note);
+  }
+
+  private endTake(keep: boolean) {
+    const capture = this.capture;
+    this.capture = null;
+    if (listening === this) listening = null;
+    if (this.previewTimer) clearInterval(this.previewTimer);
+    this.previewTimer = null;
+    if (capture) {
+      clearTimeout(capture.limit);
+      if (capture.recording) {
+        const deps = this.deps;
+        const wanted = keep && deps.audio && (deps.keepAudio?.() ?? true);
+        finishRecording(capture.recording, wanted ? (file) => deps.audio?.(file) : null);
+      }
+      const last = this.segmenter.flush();
+      if (last) this.enqueue(last);
+      for (const node of capture.nodes) node.disconnect();
+      capture.stream.getTracks().forEach((track) => track.stop());
+      void capture.context.close().catch(() => {});
+    } else if (this.state.phase === "starting") {
+      // The permission prompt is still up: abandon the take when it resolves.
+      this.take++;
+    }
+  }
+
+  /** Stops everything and drops what wasn't written yet: the box it was writing into is gone. */
+  cancel() {
+    this.take++;
+    this.endTake(false);
+    this.abort.abort();
+    this.abort = new AbortController();
+    this.queue = [];
+    this.live = "";
+    this.sending = false;
+    this.stalled = false;
+    window.removeEventListener("online", this.onOnline);
+    this.set({ ...idleDictation });
+  }
+
+  /** Tries the held piece again. */
+  retry() {
+    if (!this.stalled) return;
+    this.stalled = false;
+    window.removeEventListener("online", this.onOnline);
+    this.set({ stalled: null });
+    void this.drain();
+  }
+
+  /** Drops the held piece and carries on with the rest. */
+  skip() {
+    if (!this.stalled) return;
+    this.queue.shift();
+    this.retry();
+    this.set({ queued: this.queue.length, preview: this.previewText() });
+  }
+
+  /** Queues a cut piece for transcription. The mic tap calls this; so can a test, without a mic. */
+  enqueue(piece: Piece) {
+    this.queue.push({
+      wav: new Blob([encodeWav(piece.samples)], { type: "audio/wav" }),
+      seconds: piece.seconds,
+      preview: this.live,
+      spokenAt: Date.now() - piece.seconds * 1000,
+    });
+    this.live = "";
+    this.previewPiece++;
+    this.previewedSamples = 0;
+    this.set({ queued: this.queue.length, preview: this.previewText() });
+    void this.drain();
+  }
+
+  private async drain() {
+    if (this.sending || this.stalled) return;
+    this.sending = true;
+    const signal = this.abort.signal;
+    try {
+      while (this.queue.length && !this.stalled && !signal.aborted) {
+        const next = this.queue[0]!;
+        try {
+          const text = await this.send(next, signal);
+          if (signal.aborted) return;
+          this.queue.shift();
+          if (text) {
+            this.deps.write(text);
+            this.deps.said?.(text, next.spokenAt);
+          }
+          this.set({ queued: this.queue.length, preview: this.previewText() });
+        } catch (error) {
+          if (signal.aborted) return;
+          this.stalled = true;
+          if (fatal(error)) this.stop(failureText(error));
+          this.set({ stalled: failureText(error), queued: this.queue.length });
+          window.addEventListener("online", this.onOnline);
+        }
+      }
+    } finally {
+      if (!signal.aborted) this.sending = false;
+    }
+  }
+
+  private async send(piece: Waiting, signal: AbortSignal) {
+    for (let attempt = 0; ; attempt++) {
+      const timeout = new AbortController();
+      const timer = setTimeout(() => timeout.abort(), REQUEST_TIMEOUT_MS);
+      const abortRequest = () => timeout.abort();
+      signal.addEventListener("abort", abortRequest, { once: true });
+      try {
+        return await this.deps.transcribe(piece.wav, this.deps.prompt(), timeout.signal);
+      } catch (error) {
+        if (signal.aborted) throw error;
+        const delay = RETRY_DELAYS_MS[attempt];
+        if (delay === undefined || !retryable(error)) throw error;
+        await wait(delay, signal);
+      } finally {
+        clearTimeout(timer);
+        signal.removeEventListener("abort", abortRequest);
+      }
+    }
+  }
+
+  private previewText() {
+    return [...this.queue.map((piece) => piece.preview), this.live].filter(Boolean).join(" ");
+  }
+
+  /** Re-reads the piece still being spoken. Best-effort: a failed or late preview is dropped. */
+  private async refreshPreview(take: number) {
+    const preview = this.deps.preview;
+    if (!preview || this.previewing || take !== this.take || !this.capture) return;
+    const samples = this.segmenter.pending();
+    if (
+      !samples ||
+      samples.length < PREVIEW_MIN_SAMPLES ||
+      samples.length === this.previewedSamples
+    )
+      return;
+    this.previewedSamples = samples.length;
+    const piece = this.previewPiece;
+    const signal = this.abort.signal;
+    const timeout = new AbortController();
+    const timer = setTimeout(() => timeout.abort(), REQUEST_TIMEOUT_MS);
+    const abortRequest = () => timeout.abort();
+    signal.addEventListener("abort", abortRequest, { once: true });
+    this.previewing = true;
+    try {
+      const wav = new Blob([encodeWav(samples)], { type: "audio/wav" });
+      const text = await preview(wav, this.deps.prompt(), timeout.signal);
+      if (signal.aborted || piece !== this.previewPiece || take !== this.take) return;
+      this.live = text.trim();
+      this.set({ preview: this.previewText() });
+    } catch {
+      // The final text still comes from the cut piece.
+    } finally {
+      this.previewing = false;
+      clearTimeout(timer);
+      signal.removeEventListener("abort", abortRequest);
+    }
+  }
+
+  private set(patch: Partial<DictationState>) {
+    this.state = { ...this.state, ...patch };
+    this.deps.onState(this.state);
+  }
+}

package/src/runtime/dictation-model.ts

@@ -0,0 +1,79 @@
+/**
+ * Dictation's DOM-free parts that native dictation (m4a takes) shares with the web toolbar: the input meter,
+ * placing dictated words into the writing box, the context that helps the transcriber, and voice note names.
+ * Re-exported from `./dictation.ts` and `./dictation-engine.ts`.
+ */
+
+/**
+ * Where the dictation point moved to after someone edited the text it lives in. An edit wholly before it
+ * shifts it; an edit after it leaves it; an edit across it puts it at the end of the edit.
+ */
+export function rebaseAnchor(previous: string, next: string, anchor: number) {
+  if (previous === next) return Math.min(anchor, next.length);
+  let prefix = 0;
+  const shortest = Math.min(previous.length, next.length);
+  while (prefix < shortest && previous[prefix] === next[prefix]) prefix++;
+  let suffix = 0;
+  while (
+    suffix < shortest - prefix &&
+    previous[previous.length - 1 - suffix] === next[next.length - 1 - suffix]
+  )
+    suffix++;
+  if (anchor <= prefix) return anchor;
+  if (anchor >= previous.length - suffix) return anchor + next.length - previous.length;
+  return next.length - suffix;
+}
+
+/**
+ * `text` written into `value` at `at`, spaced like typing: a space before it unless it starts a line, a
+ * space after it unless punctuation follows, and a capital when it starts a sentence.
+ */
+export function insertDictated(value: string, at: number, text: string) {
+  const words = text.trim();
+  if (!words) return { value, caret: at };
+  const before = value.slice(0, at);
+  const after = value.slice(at);
+  const sentenceStart = !before.trim() || /[.!?]["')\]]?\s*$/.test(before) || /\n\s*$/.test(before);
+  const written = sentenceStart ? words.charAt(0).toUpperCase() + words.slice(1) : words;
+  const lead = before && !/\s$/.test(before) ? " " : "";
+  const trail = after && !/^[\s.,!?;:)]/.test(after) ? " " : "";
+  const inserted = `${lead}${written}${trail}`;
+  return {
+    value: `${before}${inserted}${after}`,
+    caret: before.length + lead.length + written.length,
+  };
+}
+
+/**
+ * Context for Whisper: the people who might be named, then the writing just before the dictation point.
+ * Both help it spell names and keep punctuation consistent across pieces.
+ */
+export function dictationPrompt(before: string, names: readonly string[]) {
+  const people = names.length ? `${names.slice(0, 20).join(", ")}.`.slice(0, 250) : "";
+  const recent = before.slice(-300).trim();
+  return [people, recent].filter(Boolean).join(" ");
+}
+
+export function decibels(samples: Float32Array) {
+  let sum = 0;
+  for (const sample of samples) sum += sample * sample;
+  const rms = Math.sqrt(sum / Math.max(1, samples.length));
+  return rms > 0 ? 20 * Math.log10(rms) : -100;
+}
+
+/** 0–1 for a meter: −60 dBFS and below is empty, −12 is full. */
+export function meterLevel(db: number) {
+  return Math.max(0, Math.min(1, (db + 60) / 48));
+}
+
+function two(value: number) {
+  return String(value).padStart(2, "0");
+}
+
+/** `voice-2026-10-31-13-56-37.webm`, after the screen recordings' `recording-…` names. */
+export function voiceRecordingName(at: Date, type: string): string {
+  const base = type.split(";")[0]!.trim();
+  const extension = base === "audio/mp4" ? "m4a" : base === "audio/ogg" ? "ogg" : "webm";
+  const stamp = `${at.getFullYear()}-${two(at.getMonth() + 1)}-${two(at.getDate())}-${two(at.getHours())}-${two(at.getMinutes())}-${two(at.getSeconds())}`;
+  return `voice-${stamp}.${extension}`;
+}