dexterm-cli 0.1.1 → 0.1.3

package/dist/packages/voice/src/tts/piper.js

@@ -0,0 +1,449 @@
+// Piper neural TTS engine (task-1408, task-1416). Piper is a free, local, no-key neural text-to-speech
+// engine (rhasspy/piper, MIT) that sounds markedly better than espeak-ng or the built-in macOS voices.
+// It is the PREFERRED speech-out engine EVERYWHERE it is installed — on macOS (via the managed Python
+// runtime, `dexterm voice setup`) as well as off macOS (via the prebuilt binary) — with `say`/espeak-ng
+// kept as the fallback chain (see engines.ts). Verified in Docker on Linux (task-1397/task-1408) and via
+// the managed venv on an Intel Mac (task-1416): the en_GB-alan-medium voice writes a valid, non-silent
+// 22.05 kHz WAV that whisper.cpp transcribes almost word-for-word.
+//
+// Two runtimes, one engine:
+//   - macOS (managed): a private virtualenv at `~/.dexterm/piper/venv` with `pip install piper-tts`. The
+//     prebuilt macOS tarball from rhasspy is broken (it needs a libespeak-ng dylib it does not bundle),
+//     so we run `<venv>/bin/python -m piper` instead. Built by `dexterm voice setup`.
+//   - Linux/Windows: the prebuilt `piper` binary extracted into `~/.dexterm/piper/` (or on PATH).
+//
+// It carries the SAME contract as the macOS `say` and espeak engines:
+//   - text is SANITISED (sanitizeSpeech strips `[[…]]`, control chars, a leading `-`, caps length)
+//   - text is delivered on STDIN, never as an argv word
+//   - a new speak() cleanly INTERRUPTS the current one — one queue, never two voices at once
+//   - the voice is fixed by the downloaded MODEL, never by a macOS voice name (so config.voice.name,
+//     which on a Mac is e.g. "Eddy (English (UK))", is NEVER passed verbatim to Piper)
+//
+// Latency (task-1416): loading the 63 MB model into onnxruntime dominates first-audio (~1.4–4 s cold,
+// load-dependent), so we keep a pre-warmed STANDBY process that has already loaded the model and primed
+// onnxruntime. speak() ADOPTS the standby, feeds it the reply SENTENCE BY SENTENCE (each line is a
+// separate utterance → a separate WAV), plays those WAVs in order as they land, and spawns a fresh
+// standby in the background for the next reply. So the first word starts ~0.3–0.5 s after an answer lands
+// instead of waiting on a cold model load. stop() kills the adopted synth process AND the player.
+//
+// Piper has no audio output of its own: it synthesises WAVs, which we play through the platform player
+// (afplay on macOS; aplay / paplay / ffplay off macOS — detected and reported by the doctor). Containers
+// have no audio device, so real playback is unverified there; synthesis-to-file IS verified (synthToFile
+// + whisper), and macOS playback via afplay is verified on a real Mac (task-1416).
+import { spawn } from 'node:child_process';
+import { existsSync, mkdtempSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { sanitizeSpeech } from "./voices.js";
+import { splitSentences } from "../summary.js";
+/** The Piper voice dexterm defaults to: a British male, medium quality (local, no key). */
+export const DEFAULT_PIPER_VOICE = 'en_GB-alan-medium';
+/** `~/.dexterm`, honouring the DEXTERM_HOME override (tests point it at a temp dir) — matches @dexterm/custom. */
+function dextermHomeDir() {
+    const h = process.env.DEXTERM_HOME;
+    return h && h.trim() ? h : join(homedir(), '.dexterm');
+}
+/** Where the downloaded Piper voice model lives (see `dexterm voice download piper-voice`). */
+export const PIPER_MODEL = process.env.DEXTERM_PIPER_MODEL
+    || join(dextermHomeDir(), 'models', `${DEFAULT_PIPER_VOICE}.onnx`);
+/** The managed Python interpreter built by `dexterm voice setup` (macOS). */
+export function managedVenvPython(home = dextermHomeDir()) {
+    const bin = process.platform === 'win32' ? join('Scripts', 'python.exe') : join('bin', 'python');
+    return join(home, 'piper', 'venv', bin);
+}
+/** Audio players we can hand a WAV to, best-first. afplay ships with macOS; the rest are the Linux/Windows set. */
+export const PIPER_PLAYERS = process.platform === 'darwin'
+    ? ['afplay', 'ffplay']
+    : ['aplay', 'paplay', 'ffplay'];
+function which(bin) {
+    if (!bin)
+        return null;
+    if (bin.includes('/') || bin.includes('\\'))
+        return existsSync(bin) ? bin : null;
+    const sep = process.platform === 'win32' ? ';' : ':';
+    for (const p of (process.env.PATH ?? '').split(sep)) {
+        if (!p)
+            continue;
+        if (existsSync(join(p, bin)))
+            return join(p, bin);
+        if (process.platform === 'win32' && existsSync(join(p, `${bin}.exe`)))
+            return join(p, `${bin}.exe`);
+    }
+    return null;
+}
+/**
+ * Resolve the Piper binary (native-binary runtime only). Kept for the off-macOS doctor/status that only
+ * ever ship the prebuilt binary. Looks at an explicit override, the dexterm-local install, then PATH.
+ * NOTE: Debian's `apt install piper` is an UNRELATED gaming-mouse tool, so the doctor steers users to the
+ * rhasspy prebuilt release rather than apt; a wrong `piper` on PATH simply fails to synth and voice
+ * degrades to text (it never crashes).
+ */
+export function resolvePiperBin() {
+    return which(process.env.DEXTERM_PIPER_BIN || '')
+        || which(join(dextermHomeDir(), 'piper', 'piper'))
+        || which('piper');
+}
+/**
+ * Resolve the Piper RUNTIME for this machine, best-first:
+ *   1. DEXTERM_PIPER_BIN — an explicit binary (also the test seam).
+ *   2. DEXTERM_PIPER_PYTHON — an explicit `python` to run `-m piper` (test seam for the managed path).
+ *   3. the managed venv python (`~/.dexterm/piper/venv/bin/python`) — built by `dexterm voice setup`.
+ *   4. the dexterm-local prebuilt binary (`~/.dexterm/piper/piper`) or `piper` on PATH.
+ * Returns null when none is installed (voice degrades to the next engine, never crashes).
+ */
+export function resolvePiperRuntime() {
+    const binOverride = which(process.env.DEXTERM_PIPER_BIN || '');
+    if (binOverride)
+        return { cmd: binOverride, prefix: [], kind: 'binary' };
+    const pyOverride = process.env.DEXTERM_PIPER_PYTHON;
+    if (pyOverride && existsSync(pyOverride))
+        return { cmd: pyOverride, prefix: ['-m', 'piper'], kind: 'python' };
+    const venv = managedVenvPython();
+    if (existsSync(venv))
+        return { cmd: venv, prefix: ['-m', 'piper'], kind: 'python' };
+    const localBin = which(join(dextermHomeDir(), 'piper', 'piper'));
+    if (localBin)
+        return { cmd: localBin, prefix: [], kind: 'binary' };
+    const pathBin = which('piper');
+    if (pathBin)
+        return { cmd: pathBin, prefix: [], kind: 'binary' };
+    return null;
+}
+/** The player that will play Piper's WAV, or null when none is installed. */
+export function pickPlayer() {
+    const override = process.env.DEXTERM_AUDIO_PLAYER;
+    if (override)
+        return which(override) ? override : null;
+    for (const p of PIPER_PLAYERS)
+        if (which(p))
+            return p;
+    return null;
+}
+/** Argv to play a finished WAV through the given player (quiet, exits on end, no window). */
+function playerArgs(player, wav) {
+    const base = player.replace(/\.exe$/i, '').split(/[\\/]/).pop() ?? player;
+    switch (base) {
+        case 'afplay': return [wav];
+        case 'ffplay': return ['-nodisp', '-autoexit', '-loglevel', 'quiet', wav];
+        case 'paplay': return [wav];
+        case 'aplay':
+        default: return ['-q', wav];
+    }
+}
+/** Map a words-per-minute rate to Piper's --length_scale (lower rate → slower → larger scale). */
+function lengthScaleFor(rate) {
+    if (typeof rate !== 'number' || !(rate > 0))
+        return undefined;
+    return Math.max(0.5, Math.min(2, 190 / rate));
+}
+/** WAV basenames in a dir, oldest-first (Piper names them by an increasing timestamp). */
+function listWavs(dir) {
+    let names;
+    try {
+        names = readdirSync(dir).filter((f) => f.endsWith('.wav'));
+    }
+    catch {
+        return [];
+    }
+    return names.sort((a, b) => {
+        try {
+            return statSync(join(dir, a)).mtimeMs - statSync(join(dir, b)).mtimeMs || a.localeCompare(b);
+        }
+        catch {
+            return a.localeCompare(b);
+        }
+    });
+}
+/** Sanitise, then split into one line per sentence for sentence-by-sentence streaming (never empty lines). */
+function splitForSpeech(text) {
+    const safe = sanitizeSpeech(text);
+    if (!safe)
+        return [];
+    const parts = splitSentences(safe).map((s) => s.trim()).filter(Boolean);
+    return parts.length ? parts : [safe];
+}
+export class PiperTts {
+    name = 'piper';
+    label = 'Piper (neural, local, no key)';
+    model;
+    /** The utterance currently playing. A new speak() stops it first, so there is only ever one. */
+    current = null;
+    /** A pre-warmed process waiting to be adopted by the next speak() (task-1416 latency). */
+    standby = null;
+    /** Every live warm process, so dispose() can never leak one. */
+    live = new Set();
+    constructor(model = PIPER_MODEL) { this.model = model; }
+    /** The voice id this engine speaks with (the model basename), for the status line. */
+    get voiceName() { return DEFAULT_PIPER_VOICE; }
+    /** True when Piper can speak ALOUD here: a runtime, the voice model and a player are all present. */
+    async available() {
+        return resolvePiperRuntime() !== null && existsSync(this.model) && pickPlayer() !== null;
+    }
+    /** True when Piper can SYNTHESISE here (runtime + model) even with no audio device (used for the proof). */
+    canSynth() {
+        return resolvePiperRuntime() !== null && existsSync(this.model);
+    }
+    /** Piper's voice is the model; there is no per-machine installed-voice list to cycle. */
+    async listVoices() { return [DEFAULT_PIPER_VOICE]; }
+    /**
+     * Synthesise `text` to a WAV at `outPath`. Resolves on success, rejects on a missing runtime/model or a
+     * non-zero exit. This is the engine's testable, audio-device-free core — the Docker proof and the unit
+     * tests drive it directly. The text is sanitised and delivered on stdin, exactly as speak() does.
+     */
+    synthToFile(text, outPath, opts = {}) {
+        const runtime = resolvePiperRuntime();
+        const safe = sanitizeSpeech(text);
+        return new Promise((resolve, reject) => {
+            if (!runtime) {
+                reject(new Error('piper runtime not found'));
+                return;
+            }
+            const args = [...runtime.prefix, '--model', this.model, '--output_file', outPath];
+            if (typeof opts.lengthScale === 'number' && Number.isFinite(opts.lengthScale)) {
+                args.push('--length_scale', String(opts.lengthScale)); // >1 = slower speech
+            }
+            let child;
+            try {
+                child = spawn(runtime.cmd, args, { stdio: ['pipe', 'ignore', 'pipe'] });
+            }
+            catch (e) {
+                reject(e);
+                return;
+            }
+            let err = '';
+            child.stderr?.on('data', (d) => { err += d; });
+            child.stdin?.on('error', () => { });
+            // Piper reads one line of text from stdin; the sanitiser already collapsed newlines to one line.
+            try {
+                child.stdin?.end(safe + '\n');
+            }
+            catch { /* child gone */ }
+            child.on('error', reject);
+            child.on('close', (code) => code === 0
+                ? resolve()
+                : reject(new Error(`piper exit ${code}: ${err.slice(-200)}`)));
+        });
+    }
+    /**
+     * Pre-load the model into a standby process so the first reply starts speaking quickly. Safe to call
+     * repeatedly and before anything is spoken (the controller calls it when voice is enabled). No-op when
+     * Piper is not installed here or a standby for this rate already exists.
+     */
+    warmup(rate) {
+        const scale = lengthScaleFor(rate);
+        if (this.standby && !this.standby.disposed && this.standby.scale === scale)
+            return;
+        if (this.standby) {
+            this.standby.dispose();
+            this.standby = null;
+        }
+        this.standby = this.spawnWarm(scale);
+    }
+    /** Spawn a warm process in output-dir mode and prime the model with one discarded utterance. */
+    spawnWarm(scale) {
+        const runtime = resolvePiperRuntime();
+        if (!runtime || !existsSync(this.model))
+            return null;
+        const dir = mkdtempSync(join(tmpdir(), 'dexterm-piper-'));
+        const args = [...runtime.prefix, '--model', this.model, '--output_dir', dir];
+        if (scale !== undefined)
+            args.push('--length_scale', String(scale));
+        let child;
+        try {
+            child = spawn(runtime.cmd, args, { stdio: ['pipe', 'ignore', 'ignore'] });
+        }
+        catch {
+            try {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            catch { /* ignore */ }
+            return null;
+        }
+        const seen = new Set();
+        const warm = {
+            child, dir, seen, scale, disposed: false,
+            ready: new Promise((resolve, reject) => {
+                const poll = setInterval(() => {
+                    if (warm.disposed) {
+                        clearInterval(poll);
+                        return;
+                    }
+                    for (const f of listWavs(dir))
+                        if (!seen.has(f)) {
+                            seen.add(f);
+                            clearInterval(poll);
+                            resolve();
+                            return;
+                        }
+                }, 20);
+                child.on('error', () => { clearInterval(poll); reject(new Error('piper warm process error')); });
+                child.on('close', () => { clearInterval(poll); reject(new Error('piper warm process exited')); });
+            }),
+            dispose: () => {
+                if (warm.disposed)
+                    return;
+                warm.disposed = true;
+                this.live.delete(warm);
+                try {
+                    child.kill('SIGTERM');
+                }
+                catch { /* already gone */ }
+                try {
+                    rmSync(dir, { recursive: true, force: true });
+                }
+                catch { /* ignore */ }
+            },
+        };
+        this.live.add(warm);
+        // Swallow the rejection so a dead warm process never becomes an unhandled rejection; adopters await it.
+        warm.ready.catch(() => { });
+        // A short priming utterance makes onnxruntime load the model now; its WAV lands in `seen` and is never
+        // played. stdin stays OPEN so speak() can adopt this process and feed the real sentences.
+        try {
+            child.stdin?.on('error', () => { });
+            child.stdin?.write('ready\n');
+        }
+        catch { /* child gone */ }
+        return warm;
+    }
+    /** Take the standby if it matches the rate; otherwise discard it and spawn a fresh warm process. */
+    takeWarm(scale) {
+        if (this.standby && !this.standby.disposed && this.standby.scale === scale) {
+            const w = this.standby;
+            this.standby = null;
+            return w;
+        }
+        if (this.standby) {
+            this.standby.dispose();
+            this.standby = null;
+        }
+        return this.spawnWarm(scale);
+    }
+    speak(text, opts = {}) {
+        this.stopCurrent(); // single queue: never two speakers at once
+        const player = pickPlayer();
+        const scale = lengthScaleFor(opts.rate);
+        const sentences = splitForSpeech(text);
+        let stopped = false;
+        let resolve;
+        const done = new Promise((r) => { resolve = r; });
+        let warm = null;
+        let playing = null;
+        const cleanup = () => { if (warm) {
+            warm.dispose();
+            warm = null;
+        } };
+        const settle = () => {
+            if (stopped)
+                return;
+            stopped = true;
+            if (this.current === handle)
+                this.current = null;
+            try {
+                playing?.kill('SIGTERM');
+            }
+            catch { /* ignore */ }
+            cleanup();
+            resolve();
+        };
+        const handle = { done, stop: settle };
+        this.current = handle;
+        // Nothing to say, or we cannot play aloud → degrade to text (resolve, never throw).
+        if (!player || sentences.length === 0 || !this.canSynth()) {
+            queueMicrotask(settle);
+            return handle;
+        }
+        // Adopt a warm process for the right rate (respawn if the rate changed), then refill the standby.
+        warm = this.takeWarm(scale);
+        if (!warm) {
+            queueMicrotask(settle);
+            return handle;
+        } // no runtime/model → text
+        this.standby = this.spawnWarm(scale); // keep one warm for the NEXT reply
+        const queue = [];
+        let synthClosed = false;
+        let firstFired = false;
+        const adopted = warm;
+        const startPlayback = () => {
+            const poll = setInterval(() => {
+                if (stopped) {
+                    clearInterval(poll);
+                    return;
+                }
+                for (const f of listWavs(adopted.dir))
+                    if (!adopted.seen.has(f)) {
+                        adopted.seen.add(f);
+                        queue.push(join(adopted.dir, f));
+                    }
+            }, 20);
+            adopted.child.on('close', () => { synthClosed = true; });
+            const playNext = () => {
+                if (stopped) {
+                    clearInterval(poll);
+                    return;
+                }
+                // A WAV is safe to play once a LATER one exists or the synth has exited (so it is fully written).
+                const ready = queue.length > 1 || (queue.length === 1 && synthClosed);
+                if (!ready) {
+                    if (synthClosed && queue.length === 0) {
+                        clearInterval(poll);
+                        settle();
+                        return;
+                    }
+                    setTimeout(playNext, 20);
+                    return;
+                }
+                const wav = queue.shift();
+                try {
+                    playing = spawn(player, playerArgs(player, wav), { stdio: 'ignore' });
+                    playing.on('spawn', () => { if (!stopped && !firstFired) {
+                        firstFired = true;
+                        opts.onFirstAudio?.();
+                    } });
+                    playing.on('error', () => { if (!stopped)
+                        setTimeout(playNext, 0); });
+                    playing.on('close', () => { if (!stopped)
+                        setTimeout(playNext, 0); });
+                }
+                catch {
+                    if (!stopped)
+                        setTimeout(playNext, 0);
+                }
+            };
+            playNext();
+        };
+        adopted.ready.then(() => {
+            if (stopped)
+                return;
+            // Feed the reply one sentence per line; end stdin so the process exits after the last WAV.
+            try {
+                for (const s of sentences)
+                    adopted.child.stdin?.write(s + '\n');
+                adopted.child.stdin?.end();
+            }
+            catch {
+                settle();
+                return;
+            }
+            startPlayback();
+        }).catch(settle); // the warm process died before it was ready → degrade to text
+        return handle;
+    }
+    stopCurrent() {
+        const h = this.current;
+        if (h) {
+            this.current = null;
+            try {
+                h.stop();
+            }
+            catch { /* ignore */ }
+        }
+    }
+    /** Release the standby and any live warm processes (called when voice is disabled). */
+    dispose() {
+        this.stopCurrent();
+        for (const w of [...this.live])
+            w.dispose();
+        this.standby = null;
+    }
+}

package/dist/packages/voice/src/tts/say.js

@@ -1,15 +1,30 @@
-// macOS `say` TTS engine (task-1282). `say` ships with macOS, needs no key and no network, so it is
-// the free/portable default (SPEC: macOS say first). It streams to the audio device as it synthesises,
-// so time-to-first-audio is close to process spawn. speak() is interruptible via stop() (SIGTERM to
-// the child), which is how a key or the user starting to talk cuts a reply short.
+// macOS `say` TTS engine (task-1282, hardened task-1393). `say` ships with macOS, needs no key and no
+// network, so it is the free/portable default (SPEC: macOS say first). It streams to the audio device,
+// so time-to-first-audio is close to process spawn. speak() is interruptible via stop() (SIGTERM to the
+// child), which is how a key or the user starting to talk cuts a reply short.
+//
+// task-1393 hardening:
+//   - text is SANITISED (no `[[…]]` embedded commands, no leading-`-` flag, addresses shortened, capped)
+//   - text is delivered on STDIN (`say -f -`), never as the last argv word
+//   - a new speak() cleanly INTERRUPTS the current one, so two `say` processes never overlap (one queue)
+//   - the voice is always EXPLICIT (resolved to a deep British male upstream); it never falls back to the
+//     machine's system voice
 import { spawn } from 'node:child_process';
 import { execFile } from 'node:child_process';
+import { parseSayVoices, sanitizeSpeech } from "./voices.js";
 export const SAY_BIN = process.env.DEXTERM_SAY_BIN || 'say';
+/** Consistent speaking rate (words-per-minute-ish) for every reply path. Brisk by default (task-1411:
+ * the old delivery was reported "way too slow"); the user can nudge it live with < / > or set voice.rate. */
+export const DEFAULT_RATE = 205;
 export class SayTts {
     name = 'say';
     label = 'macOS say (built-in, no key)';
     defaultVoice;
+    /** The utterance currently playing. A new speak() stops it first, so there is only ever one. */
+    current = null;
     constructor(defaultVoice) { this.defaultVoice = defaultVoice; }
+    /** The resolved default voice this engine speaks with — used to seed the controller / status line. */
+    get voiceName() { return this.defaultVoice; }
     async available() {
         if (process.platform !== 'darwin')
             return false;
@@ -23,22 +38,12 @@ export class SayTts {
             }
         });
     }
-    /** Parse `say -v '?'`: each line is "Name            en_US    # sample text". */
-    async listVoices() {
+    /** Installed voices with their locale. Robust against the single-space padding on long voice names. */
+    async listVoicesDetailed() {
         return new Promise((resolve) => {
             try {
                 execFile(SAY_BIN, ['-v', '?'], { timeout: 5000, maxBuffer: 1 << 20 }, (err, stdout) => {
-                    if (err || !stdout) {
-                        resolve([]);
-                        return;
-                    }
-                    const names = [];
-                    for (const line of stdout.split('\n')) {
-                        const m = line.match(/^(.+?)\s{2,}[a-z]{2}(?:[_-][A-Za-z]+)?\s/);
-                        if (m)
-                            names.push(m[1].trim());
-                    }
-                    resolve(names);
+                    resolve(err || !stdout ? [] : parseSayVoices(stdout));
                 });
             }
             catch {
@@ -46,45 +51,64 @@ export class SayTts {
             }
         });
     }
+    /** Selectable voice names (the TtsEngine contract). */
+    async listVoices() {
+        return (await this.listVoicesDetailed()).map((v) => v.name);
+    }
     speak(text, opts = {}) {
+        // One queue: cut off whatever is playing so two `say` processes never overlap (clean interrupt).
+        this.stopCurrent();
         const voice = opts.voice ?? this.defaultVoice;
-        const rate = opts.rate ?? 190;
+        const rate = opts.rate ?? DEFAULT_RATE;
+        // Sanitise the UNTRUSTED text first, then prepend our own TRUSTED pitch command. Order matters: the
+        // sanitiser strips any `[[…]]` the text tried to smuggle, so only our validated `[[pbas N]]` survives.
+        let safe = sanitizeSpeech(text);
+        if (typeof opts.pitch === 'number' && Number.isFinite(opts.pitch)) {
+            const pbas = Math.max(0, Math.min(100, Math.round(opts.pitch)));
+            safe = `[[pbas ${pbas}]] ${safe}`;
+        }
         const args = [];
         if (voice)
             args.push('-v', voice);
-        args.push('-r', String(rate), text);
+        args.push('-r', String(rate));
+        args.push('-f', '-'); // read the utterance from stdin — the text is NEVER an argv word
         let child = null;
         let stopped = false;
         let resolve;
         const done = new Promise((r) => { resolve = r; });
+        const finish = () => { if (!stopped) {
+            stopped = true;
+            if (this.current === handle)
+                this.current = null;
+            resolve();
+        } };
         try {
-            child = spawn(SAY_BIN, args, { stdio: 'ignore' });
-            // `say` has no first-sample hook; the spawn event is the closest honest lower bound and is what
-            // the latency table reports as "first spoken word" for this engine.
+            child = spawn(SAY_BIN, args, { stdio: ['pipe', 'ignore', 'ignore'] });
+            // Nothing is spoken until stdin is closed; write the sanitised text and end it.
+            child.stdin?.on('error', () => { });
+            try {
+                child.stdin?.end(safe);
+            }
+            catch { /* child gone */ }
+            // `say` has no first-sample hook; the spawn event is the closest honest lower bound and is what the
+            // latency table reports as "first spoken word" for this engine.
             child.on('spawn', () => { if (!stopped)
                 opts.onFirstAudio?.(); });
-            child.on('error', () => { if (!stopped) {
-                stopped = true;
-                resolve();
-            } });
-            child.on('close', () => { if (!stopped) {
-                stopped = true;
-                resolve();
-            } });
+            child.on('error', finish);
+            child.on('close', finish);
         }
         catch {
             // No `say` on this machine: resolve immediately so the caller degrades to text.
-            queueMicrotask(() => { if (!stopped) {
-                stopped = true;
-                resolve();
-            } });
+            queueMicrotask(finish);
         }
-        return {
+        const handle = {
             done,
             stop: () => {
                 if (stopped)
                     return;
                 stopped = true;
+                if (this.current === handle)
+                    this.current = null;
                 try {
                     child?.kill('SIGTERM');
                 }
@@ -92,5 +116,18 @@ export class SayTts {
                 resolve();
             },
         };
+        this.current = handle;
+        return handle;
+    }
+    /** Stop the currently-playing utterance, if any. */
+    stopCurrent() {
+        const h = this.current;
+        if (h) {
+            this.current = null;
+            try {
+                h.stop();
+            }
+            catch { /* ignore */ }
+        }
     }
 }