@chatpanel/gateway 0.6.49 → 0.6.51

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chatpanel/gateway",
-  "version": "0.6.49",
-  "description": "Local privacy gateway \u2014 redacts PII out of OpenAI/Anthropic API traffic before it reaches a model, then restores it in the reply. Point opencode, codex, aider, Claude Code, etc. at it.",
+  "version": "0.6.51",
+  "description": "Local privacy gateway — redacts PII out of OpenAI/Anthropic API traffic before it reaches a model, then restores it in the reply. Point opencode, codex, aider, Claude Code, etc. at it.",
   "type": "module",
   "bin": {
     "chatpanel-gateway": "bin/chatpanel-gateway.js"
@@ -29,7 +29,8 @@
   "dependencies": {
     "@chatpanel/pii": "^0.4.0",
     "@huggingface/transformers": "^4.2.0",
-    "onnxruntime-web": "1.26.0-dev.20260416-b7804b056c"
+    "onnxruntime-web": "1.26.0-dev.20260416-b7804b056c",
+    "phonemizer": "^1.2.1"
   },
   "homepage": "https://chatpanel.net",
   "repository": {

package/src/config.js

@@ -106,6 +106,30 @@ const DEFAULTS = {
     diarize: true,
   },
 
+  // Local text-to-speech (read-aloud / voice out) — Kokoro via the same in-process
+  // ONNX engine and model dir as NER/STT (tts-engine.js). No autostart, same reason
+  // as stt: the model downloads on FIRST synthesis, never on gateway boot.
+  tts: {
+    enabled: true,
+    // 'local' = Kokoro in this process, nothing leaves the machine (the default).
+    // 'openai' | 'elevenlabs' = a remote voice. Auth is passed through from the
+    // client as everywhere else here; no key is stored. See src/tts-remote.js for
+    // why remote synthesis redacts by default and what that costs.
+    provider: 'local',
+    model: 'onnx-community/Kokoro-82M-v1.0-ONNX',
+    voice: 'af_heart',
+    allowDownload: true,
+    remote: {
+      baseUrl: '',   // '' = the provider's own default endpoint
+      model: '',
+      voice: '',
+      // Redact before the text leaves this machine. Audio cannot be un-redacted,
+      // so this genuinely means the voice says "PERSON_1" — set false only if you
+      // accept sending real values to the vendor.
+      redact: true,
+    },
+  },
+
   // Log one line per request (method, tokens redacted) without any raw values.
   logRequests: true,
 

package/src/model-runtime.js

@@ -0,0 +1,37 @@
+// Which ONNX runtime is active, and what precision it can actually load.
+//
+// This is a fact about the RUNTIME, not about any one speech stage, so it lives in
+// its own module rather than inside whichever engine needed it first. The voice
+// pipeline's rule is that a stage never imports another stage (docs/voice-pipeline.md
+// "Composable pipeline"), and stt-engine and tts-engine both have to answer this —
+// so neither can own it.
+//
+//   • native onnxruntime-node (the npm gateway) loads the small, fast `q8`
+//     (_quantized) exports — best size + speed.
+//   • onnxruntime-web WASM (the standalone binary — SAME wasm on macOS/Windows/
+//     Linux, so this is inherently cross-platform) CANNOT load the block-quantized
+//     exports (q8/int8/uint8 → MatMulNBits "missing scale"; fp16 → graph error);
+//     of the loadable ones only `fp32` is fast enough for real-time (q4/bnb4 are
+//     ~8× slower). Verified empirically against the bundled ORT-web build.
+//
+// The binary entry sets __CHATPANEL_WASM_PATHS__, so that global tells us which
+// runtime we're on. A model may override the choice via `dtype` in its catalog.
+export function runtimeDtype() {
+  return globalThis.__CHATPANEL_WASM_PATHS__ ? 'fp32' : 'q8';
+}
+
+// 'native' (npm, fast quantized) | 'wasm' (binary, slow fp32). The extension
+// surfaces this so users on the slow WASM build know the native gateway is faster.
+export function runtimeName() {
+  return globalThis.__CHATPANEL_WASM_PATHS__ ? 'wasm' : 'native';
+}
+
+// transformers.js dtype → the ONNX filename suffix it loads. A presence check must
+// target the EXACT file the current runtime will fetch — otherwise a q8 install
+// (native) looks "present" to the WASM runtime, which actually needs the fp32 file,
+// and the offline load fails. Checking the real target makes a runtime switch
+// re-download rather than fail.
+export const DTYPE_SUFFIX = {
+  fp32: '', q8: '_quantized', int8: '_int8', uint8: '_uint8',
+  fp16: '_fp16', q4: '_q4', bnb4: '_bnb4', q4f16: '_q4f16',
+};

package/src/server.js

@@ -39,6 +39,9 @@ import * as sttEngine from './stt-engine.js';
 import * as diarizeEngine from './diarize-engine.js';
 import { MODEL_CATALOG, isKnownModel, isValidCustomModelId } from './models.js';
 import { STT_MODEL_CATALOG, isKnownSttModel, isValidCustomSttId, DEFAULT_STT_MODEL, STT_DTYPES, isValidDtype } from './stt-models.js';
+import * as ttsEngine from './tts-engine.js';
+import { TTS_MODEL_CATALOG, TTS_VOICES, isKnownTtsModel, isValidCustomTtsId, isKnownVoice, isValidVoiceId, DEFAULT_TTS_MODEL, DEFAULT_TTS_VOICE, TTS_DTYPES, isValidTtsDtype, MAX_TTS_CHARS } from './tts-models.js';
+import { ttsDestination, synthesizeRemote, isValidRemoteVoice } from './tts-remote.js';
 import { resolvePro, checkQuota, consume, usage } from './freegate.js';
 import { publicConfig, applyConfigPatch, applyNerModelSelection, persistConfig, configPath } from './configstore.js';
 import { resolveDestination, aggregateModelsAsync, listDestinations } from './router.js';
@@ -49,7 +52,7 @@ import * as openai from './openai.js';
 import * as responses from './responses.js';
 import * as anthropic from './anthropic.js';
 
-export const VERSION = '0.6.49';
+export const VERSION = '0.6.51';
 
 // WARM search tier — SQLite + FTS5 record store (falls back to an encrypted-JSON
 // store if SQLite can't load), fed by the extension's ingest sync + backup-ingest.
@@ -583,11 +586,15 @@ export function createGateway(cfg = loadConfig()) {
       // to auto-detect local dictation. `enabled` reflects config; the model only
       // downloads on first use, so state may be 'off' while still available.
       const stt = sttEngine.health();
+      const tts = ttsEngine.health();
       return sendJson(res, 200, {
         ok: true, version: VERSION, backend: cfg.backend, tier: cfg.redaction.tier,
         // `runtime` = 'native' (npm, fast quantized) | 'wasm' (binary, slow fp32) —
         // the extension uses it to advise the far-faster native gateway.
         stt: { enabled: cfg.stt?.enabled !== false, state: stt.state, ready: stt.ok, model: stt.model || cfg.stt?.model || DEFAULT_STT_MODEL, runtime: stt.runtime, dtype: stt.dtype },
+        // `tts` is ADDITIVE the same way: an older extension ignores it, a newer
+        // one uses it to offer local read-aloud instead of browser speech.
+        tts: { enabled: cfg.tts?.enabled !== false, state: tts.state, ready: tts.ok, model: tts.model || cfg.tts?.model || DEFAULT_TTS_MODEL, voice: cfg.tts?.voice || DEFAULT_TTS_VOICE, runtime: tts.runtime, dtype: tts.dtype },
       });
     }
 
@@ -958,6 +965,123 @@ export function createGateway(cfg = loadConfig()) {
         return sendJson(res, 202, { accepted: true, active: diarizeEngine.DIARIZE_MODEL, state: diarizeEngine.state(), progress: diarizeEngine.progress() });
       }
     }
+    // --- Local text-to-speech (voice out). Kokoro runs IN-PROCESS (tts-engine.js),
+    // so audio is synthesized on this machine and never leaves it. Phase 4 of
+    // docs/voice-pipeline.md. Model manager first, then synthesis.
+    if (pathname === '/tts/models') {
+      if (req.method === 'GET') {
+        const active = ttsEngine.health().model || cfg.tts?.model || DEFAULT_TTS_MODEL;
+        const available = /** @type {any[]} */ (TTS_MODEL_CATALOG.map((m) => ({ ...m, installed: ttsEngine.modelOnDisk(m.id) })));
+        if (active && !available.some((m) => m.id === active)) {
+          available.push({ id: active, label: active, lang: '—', tier: 'custom', custom: true, installed: ttsEngine.modelOnDisk(active), note: 'Custom model (from Hugging Face).' });
+        }
+        return sendJson(res, 200, {
+          active,
+          state: ttsEngine.state(),
+          progress: ttsEngine.progress(),
+          available,
+          voice: cfg.tts?.voice || DEFAULT_TTS_VOICE,
+          // Each voice is a separate ~500 KB style bank, so `installed` is per-voice.
+          voices: TTS_VOICES.map((v) => ({ ...v, installed: ttsEngine.voiceOnDisk(v.id, active) })),
+          dtype: cfg.tts?.dtype || 'auto',
+          loadedDtype: ttsEngine.health().dtype,
+          runtime: ttsEngine.health().runtime,
+          dtypes: TTS_DTYPES,
+        });
+      }
+      if (req.method === 'POST') {
+        let body = null;
+        try { body = JSON.parse((await readBody(req, cfg.maxBodyBytes)).toString('utf8')); } catch { body = null; }
+        const id = body && typeof body.id === 'string' ? body.id.trim() : null;
+        if (id && !(isKnownTtsModel(id) || isValidCustomTtsId(id))) return sendJson(res, 400, { error: { message: 'unknown or invalid model id', type: 'bad_model' } });
+        // A voice id becomes a filename, so it is checked against the catalog AND
+        // its shape before it is ever persisted.
+        const voice = body && typeof body.voice === 'string' ? body.voice.trim() : null;
+        if (voice && !(isKnownVoice(voice) && isValidVoiceId(voice))) return sendJson(res, 400, { error: { message: 'unknown or invalid voice', type: 'bad_voice' } });
+        const dtype = body && typeof body.dtype === 'string' && isValidTtsDtype(body.dtype) ? body.dtype : undefined;
+        if (!cfg.tts) cfg.tts = { enabled: true, model: DEFAULT_TTS_MODEL, voice: DEFAULT_TTS_VOICE, allowDownload: true };
+        if (id) cfg.tts.model = id;
+        if (voice) cfg.tts.voice = voice;
+        if (dtype) cfg.tts.dtype = dtype === 'auto' ? null : dtype;
+        try { persistConfig(cfg, configPath()); } catch { /* best effort */ }
+        if (id) ttsEngine.setModel(id, { onLog: (m) => console.log(m), dtype: dtype || cfg.tts.dtype || 'auto' });
+        return sendJson(res, 202, { accepted: true, active: cfg.tts.model, voice: cfg.tts.voice, dtype: cfg.tts.dtype || 'auto', state: ttsEngine.state(), progress: ttsEngine.progress() });
+      }
+    }
+
+    // POST /tts — { text, voice?, speed? } → audio/wav — and its OpenAI-compatible
+    // twin POST /v1/audio/speech ({ input, voice, speed, response_format }), so any
+    // OpenAI client or tunnel can drive local speech with no ChatPanel-specific code.
+    // Both go through ONE handler: two routes must never drift into two behaviours.
+    //
+    // Deliberately NOT redacted. Every other stage in the voice pipeline redacts at
+    // the model-send chokepoint because the text is about to leave the machine;
+    // synthesis is local, so there is nothing to protect it from — and reading
+    // "[[PERSON_1]]" aloud to the person who wrote it is a bug, not privacy.
+    if ((pathname === '/tts' || pathname === '/v1/audio/speech') && req.method === 'POST') {
+      if (cfg.tts?.enabled === false) return sendJson(res, 503, { error: { message: 'tts is disabled in gateway config', type: 'tts_disabled' } });
+      let body = null;
+      try { body = JSON.parse((await readBody(req, cfg.maxBodyBytes)).toString('utf8')); } catch { body = null; }
+      // `input` is OpenAI's field name, `text` is ours — accept either on both routes.
+      const text = body && typeof (body.input ?? body.text) === 'string' ? String(body.input ?? body.text).trim() : '';
+      if (!text) return sendJson(res, 400, { error: { message: 'text is required', type: 'bad_request' } });
+      if (text.length > MAX_TTS_CHARS) return sendJson(res, 413, { error: { message: `text too long (max ${MAX_TTS_CHARS} chars)`, type: 'too_long' } });
+      const speed = Number.isFinite(body.speed) ? Math.min(2, Math.max(0.5, body.speed)) : 1;
+      const dest = ttsDestination(cfg);
+      // A remote destination has its own voice namespace (an ElevenLabs voice id is
+      // not a Kokoro one), so the local catalog check would reject every valid id.
+      const rawVoice = body && typeof body.voice === 'string' && body.voice.trim() ? body.voice.trim() : null;
+      const voice = rawVoice || (dest ? dest.voice : (cfg.tts?.voice || DEFAULT_TTS_VOICE));
+      const voiceOk = dest ? isValidRemoteVoice(voice) : (isKnownVoice(voice) && isValidVoiceId(voice));
+      if (!voiceOk) return sendJson(res, 400, { error: { message: 'unknown or invalid voice', type: 'bad_voice' } });
+      // We synthesize WAV only. Say so rather than returning WAV bytes under an mp3
+      // content-type — a client that trusts the header would play noise.
+      const fmt = body && typeof body.response_format === 'string' ? body.response_format.toLowerCase() : 'wav';
+      if (fmt !== 'wav' && fmt !== 'pcm') return sendJson(res, 400, { error: { message: `unsupported response_format "${fmt}" — this gateway synthesizes wav`, type: 'bad_format' } });
+      try {
+        // Remote destination: the caller's own auth goes upstream, the text is
+        // redacted first unless this destination explicitly opted out, and the
+        // vendor's own audio format is passed straight through rather than
+        // re-wrapped — we did not synthesize it and must not claim its container.
+        if (dest) {
+          const { audio, contentType, redacted } = await synthesizeRemote({
+            dest, text, voice, speed,
+            auth: req.headers.authorization || req.headers['xi-api-key'] || '',
+            redaction: cfg.redaction,
+            isPro: await resolvePro(cfg.pro?.entitlementToken),
+          });
+          res.writeHead(200, {
+            'Content-Type': contentType,
+            'Content-Length': String(audio.length),
+            'Cache-Control': 'no-store',
+            // Say what actually left. A caller that asked for privacy can verify it,
+            // and one that turned it off can see that it is off.
+            'X-Tts-Provider': dest.kind,
+            'X-Tts-Redacted': String(redacted),
+          });
+          return res.end(audio);
+        }
+        const ok = await ttsEngine.ready({
+          onLog: (m) => console.log(m),
+          allowDownload: cfg.tts?.allowDownload !== false,
+          model: cfg.tts?.model || DEFAULT_TTS_MODEL,
+          dtype: cfg.tts?.dtype || 'auto',
+        });
+        if (!ok) return sendJson(res, 503, { error: { message: ttsEngine.health().error || 'tts model not ready', type: 'tts_unavailable' } });
+        const pcm = await ttsEngine.synth(text, { voice, speed });
+        const out = fmt === 'pcm' ? Buffer.from(new Float32Array(pcm).buffer) : ttsEngine.toWav(pcm);
+        res.writeHead(200, {
+          'Content-Type': fmt === 'pcm' ? 'application/octet-stream' : 'audio/wav',
+          'Content-Length': String(out.length),
+          'Cache-Control': 'no-store',
+          'X-Tts-Sample-Rate': String(ttsEngine.SAMPLE_RATE),
+        });
+        return res.end(out);
+      } catch (e) {
+        return sendJson(res, 500, { error: { message: e.message, type: 'tts_failed' } });
+      }
+    }
+
     if (pathname === '/stt/sessions' && req.method === 'POST') {
       if (cfg.stt?.enabled === false) return sendJson(res, 403, { error: { message: 'STT disabled in gateway config', type: 'stt_disabled' } });
       let body = null;

package/src/stt-engine.js

@@ -20,6 +20,7 @@ import { join } from 'node:path';
 import { existsSync, readdirSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { ensureLib, modelRoot } from './ner-engine.js';
+import { runtimeDtype, runtimeName, DTYPE_SUFFIX } from './model-runtime.js';
 import { verifyModelWeights } from './model-integrity.js';
 import { DEFAULT_STT_MODEL, isEnglishOnly, sttModelDtype, isKnownSttModel, sttModelEngine } from './stt-models.js';
 import * as parakeet from './parakeet-engine.js';
@@ -27,27 +28,10 @@ import * as diarize from './diarize-engine.js';
 
 export const SAMPLE_RATE = 16000; // fixed wire contract: 16 kHz mono Float32 PCM
 
-// The right whisper quantization depends on the ONNX RUNTIME, not the OS:
-//   • native onnxruntime-node (the npm gateway) loads the small, fast `q8`
-//     (_quantized) exports — best size + speed.
-//   • onnxruntime-web WASM (the standalone binary — SAME wasm on macOS/Windows/
-//     Linux, so this is inherently cross-platform) CANNOT load the block-quantized
-//     exports (q8/int8/uint8 → MatMulNBits "missing scale"; fp16 → graph error);
-//     of the loadable ones only `fp32` is fast enough for real-time (q4/bnb4 are
-//     ~8× slower). Verified empirically against the bundled ORT-web build.
-// The binary entry sets __CHATPANEL_WASM_PATHS__, so that global tells us which
-// runtime we're on. A model may override via `dtype` in the STT catalog.
-export function runtimeDtype() {
-  return globalThis.__CHATPANEL_WASM_PATHS__ ? 'fp32' : 'q8';
-}
-
-// Which ONNX runtime is active: the standalone binary uses onnxruntime-web WASM
-// (fp32-only, single-thread — ~10× slower); the npm package uses onnxruntime-node
-// (native, quantized q8). The extension surfaces this so users on the slow WASM
-// build know the native gateway is far faster.
-export function runtimeName() {
-  return globalThis.__CHATPANEL_WASM_PATHS__ ? 'wasm' : 'native';
-}
+// runtimeDtype / runtimeName moved to model-runtime.js — the WASM binary's fp32-only
+// constraint is a property of the runtime, and tts-engine needs the same answer.
+// Re-exported here so this module's public API is unchanged for existing callers.
+export { runtimeDtype, runtimeName };
 
 let _state = 'off';        // 'off' | 'loading' | 'downloading' | 'ready' | 'error'
 let _model = null;         // active model id
@@ -57,15 +41,6 @@ let _initPromise = null;   // single-flight init
 let _progress = null;      // { model, file, pct } while downloading, else null
 let _dtype = null;         // the quantization actually loaded (fp32 on WASM, q8 native)
 
-// transformers.js dtype → the ONNX filename suffix it loads. Presence must check
-// the EXACT file the current runtime will fetch — otherwise a q8 install (native)
-// looks "present" to the WASM runtime, which actually needs the fp32 file, and the
-// offline load fails. Checking the real target makes a runtime switch re-download.
-const DTYPE_SUFFIX = {
-  fp32: '', q8: '_quantized', int8: '_int8', uint8: '_uint8',
-  fp16: '_fp16', q4: '_q4', bnb4: '_bnb4', q4f16: '_q4f16',
-};
-
 export function modelOnDisk(modelId = _model || DEFAULT_STT_MODEL, dtype = sttModelDtype(modelId) || runtimeDtype()) {
   // Transducer models (parakeet) have a different file layout + engine — delegate.
   if (sttModelEngine(modelId) === 'parakeet-tdt') return parakeet.parakeetOnDisk(modelId, parakeet.parakeetDtype(dtype));

package/src/tts-engine.js

@@ -0,0 +1,300 @@
+// Local text-to-speech — Kokoro (StyleTTS2-family) via the same in-process ONNX
+// engine, model root and download plumbing as NER and STT. Phase 4 of
+// docs/voice-pipeline.md: "voice out".
+//
+// Why this drives the model directly instead of using `kokoro-js`: that package
+// depends on @huggingface/transformers ^3.5.1 and the gateway pins ^4.2.0, so
+// adding it would nest a SECOND transformers install — a second ONNX runtime in a
+// binary whose build script (scripts/build.mjs) exists specifically to control
+// which runtime ships. transformers 4.2 has StyleTextToSpeech2Model built in, so
+// the model loads on the pinned version and the only thing kokoro-js was really
+// providing — grapheme→phoneme — comes from `phonemizer` (zero dependencies, a
+// pure-JS espeak-ng, so it survives Bun --compile).
+//
+// Privacy: synthesis is entirely local. Nothing is sent anywhere, which is why the
+// route speaks RESTORED text rather than redacted text — see the /tts handler.
+//
+// This module owns ONE concern: text in, PCM out. Streaming, routing and redaction
+// live at the server/route layer, because a pipeline stage never imports another
+// stage.
+
+import { join } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, statSync } from 'node:fs';
+import { ensureLib, modelRoot } from './ner-engine.js';
+import { runtimeDtype, runtimeName, DTYPE_SUFFIX } from './model-runtime.js';
+import {
+  DEFAULT_TTS_MODEL, DEFAULT_TTS_VOICE, STYLE_DIM, MAX_PHONEME_TOKENS,
+  ttsModelDtype, isKnownTtsModel, isValidVoiceId, voiceLang,
+} from './tts-models.js';
+
+export const SAMPLE_RATE = 24000; // Kokoro's output rate — fixed by the model
+
+let _state = 'off';       // 'off' | 'loading' | 'downloading' | 'ready' | 'error'
+let _model = null;
+let _net = null;          // StyleTextToSpeech2Model
+let _tok = null;          // phoneme tokenizer
+let _dtype = null;
+let _err = null;
+let _progress = null;
+let _initPromise = null;
+const _voices = new Map(); // voice id → Float32Array style bank
+
+export function state() { return _state; }
+export function isReady() { return _state === 'ready' && !!_net; }
+export function progress() { return _progress; }
+
+export function health() {
+  return { configured: _state !== 'off', ok: isReady(), state: _state, model: _model, dtype: _dtype, runtime: runtimeName(), error: _err };
+}
+
+export function modelDir(modelId) {
+  return join(modelRoot(), ...String(modelId).split('/'));
+}
+
+// Present = the EXACT ONNX file this runtime will load, plus the tokenizer. Both
+// non-empty: a truncated download must not read as installed.
+export function modelOnDisk(modelId = _model || DEFAULT_TTS_MODEL, dtype = ttsModelDtype(modelId) || runtimeDtype()) {
+  const dir = modelDir(modelId);
+  const suffix = DTYPE_SUFFIX[dtype] ?? '';
+  const need = [join(dir, 'onnx', `model${suffix}.onnx`), join(dir, 'tokenizer.json')];
+  try {
+    return need.every((p) => existsSync(p) && statSync(p).size > 0);
+  } catch { return false; }
+}
+
+// A voice is a separate ~500 KB style bank (voices/<id>.bin), not part of the model
+// download, so it is fetched and checked on its own.
+export function voiceOnDisk(voice, modelId = _model || DEFAULT_TTS_MODEL) {
+  if (!isValidVoiceId(voice)) return false;
+  const p = join(modelDir(modelId), 'voices', `${voice}.bin`);
+  try { return existsSync(p) && statSync(p).size > 0; } catch { return false; }
+}
+
+export function init(cfg = {}) {
+  const tts = cfg.tts || {};
+  if (tts.enabled === false) { _state = 'off'; return; }
+  _model = tts.model || DEFAULT_TTS_MODEL;
+  // No autostart, same as STT: the model downloads on FIRST synthesis, never on
+  // gateway boot — a 90-330 MB fetch must not be a side effect of starting up.
+}
+
+async function loadModel(modelId, { log = () => {}, allowDownload = true, dtype: dtypeOverride = null } = {}) {
+  const prevNet = _net, prevModel = _model;
+  let lib;
+  try {
+    lib = await ensureLib();
+  } catch (e) {
+    _state = 'error'; _err = `engine load failed: ${e.message}`;
+    log(`[tts] transformers.js not available (${e.message}) — read-aloud falls back to browser speech`);
+    return false;
+  }
+
+  const chosen = dtypeOverride && dtypeOverride !== 'auto' ? dtypeOverride : null;
+  const dtype = chosen || ttsModelDtype(modelId) || runtimeDtype();
+  const haveLocal = modelOnDisk(modelId, dtype);
+  lib.env.allowRemoteModels = haveLocal ? false : !!allowDownload;
+  if (!haveLocal && !allowDownload) {
+    _state = 'error'; _err = 'model not on disk and downloads disabled';
+    log(`[tts] model ${modelId} not installed and downloads disabled`);
+    return false;
+  }
+
+  // ensureLib points remoteHost at the private dl.chatpanel.net mirror, which
+  // carries the NER and STT models but NOT the TTS ones yet (it 403s on them), so
+  // every TTS fetch goes to Hugging Face for now — curated and custom alike. Once
+  // the mirror carries them, narrow this back to `!isKnownTtsModel(modelId)` the
+  // way stt-engine does, and curated downloads move to the mirror with no other
+  // change. Voice banks (loadVoice) fetch from HF for the same reason.
+  const prevHost = lib.env.remoteHost;
+  const mirrored = false; // ← flip when dl.chatpanel.net mirrors the TTS models
+  if (!haveLocal && (!mirrored || !isKnownTtsModel(modelId))) {
+    try { lib.env.remoteHost = 'https://huggingface.co/'; } catch { /* optional */ }
+  }
+
+  _state = haveLocal ? 'loading' : 'downloading';
+  if (!haveLocal) { _progress = { model: modelId, file: null, pct: 0 }; log(`[tts] downloading voice model ${modelId} (one-time)…`); }
+
+  try {
+    // The extra classes ensureLib doesn't return. Module resolution is cached, so
+    // this is the SAME transformers instance ensureLib already configured (env,
+    // cacheDir, wasm paths) — importing it here keeps ner-engine free of TTS.
+    const tf = await import('@huggingface/transformers');
+    const [net, tok] = await Promise.all([
+      tf.StyleTextToSpeech2Model.from_pretrained(modelId, {
+        dtype,
+        progress_callback: (p) => {
+          if (p?.status === 'progress' && p.file) _progress = { model: modelId, file: p.file, pct: Math.round(p.progress || 0) };
+        },
+      }),
+      tf.AutoTokenizer.from_pretrained(modelId),
+    ]);
+    _net = net; _tok = tok; _model = modelId; _dtype = dtype;
+    _state = 'ready'; _err = null; _progress = null;
+    log(`[tts] ready — model ${modelId} @ ${dtype} (${runtimeName()}, offline) — local speech active`);
+    return true;
+  } catch (e) {
+    // A failed SWITCH keeps the previous working model, same as ner/stt.
+    _net = prevNet; _model = prevModel;
+    _state = prevNet ? 'ready' : 'error';
+    _err = e.message; _progress = null;
+    log(`[tts] model load failed (${e.message})`);
+    return false;
+  } finally {
+    try { lib.env.remoteHost = prevHost; } catch { /* optional */ }
+  }
+}
+
+export async function setModel(modelId, { onLog = () => {}, allowDownload = true, dtype = 'auto' } = {}) {
+  const want = dtype && dtype !== 'auto' ? dtype : (ttsModelDtype(modelId) || runtimeDtype());
+  if (modelId === _model && isReady() && _dtype === want) return true;
+  _initPromise = loadModel(modelId, { log: onLog, allowDownload, dtype });
+  return _initPromise;
+}
+
+export async function ready({ onLog = () => {}, allowDownload = true, model = null, dtype = 'auto' } = {}) {
+  if (isReady()) return true;
+  if (_initPromise) return _initPromise;
+  return setModel(model || _model || DEFAULT_TTS_MODEL, { onLog, allowDownload, dtype });
+}
+
+// ── voices ───────────────────────────────────────────────────────────────────────
+// voices/<id>.bin is a flat Float32 bank of MAX+1 style vectors — one per possible
+// token count — so the row is selected by the length of THIS utterance.
+async function loadVoice(voice, { allowDownload = true, log = () => {} } = {}) {
+  if (!isValidVoiceId(voice)) throw new Error(`invalid voice id: ${voice}`);
+  const cached = _voices.get(voice);
+  if (cached) return cached;
+  const dir = join(modelDir(_model || DEFAULT_TTS_MODEL), 'voices');
+  const dest = join(dir, `${voice}.bin`);
+  if (!(existsSync(dest) && statSync(dest).size > 0)) {
+    if (!allowDownload) throw new Error(`voice ${voice} not on disk and downloads disabled`);
+    mkdirSync(dir, { recursive: true });
+    const url = `https://huggingface.co/${_model || DEFAULT_TTS_MODEL}/resolve/main/voices/${voice}.bin`;
+    const res = await fetch(url, { redirect: 'follow' });
+    if (!res.ok) throw new Error(`fetch voice ${voice} → HTTP ${res.status}`);
+    // .part then rename, so an interrupted fetch never looks complete.
+    const tmp = `${dest}.part`;
+    writeFileSync(tmp, Buffer.from(await res.arrayBuffer()));
+    renameSync(tmp, dest);
+    log(`[tts] fetched voice ${voice}`);
+  }
+  const buf = readFileSync(dest);
+  const bank = new Float32Array(buf.buffer, buf.byteOffset, Math.floor(buf.byteLength / 4));
+  _voices.set(voice, bank);
+  return bank;
+}
+
+// ── text → speech ────────────────────────────────────────────────────────────────
+// Kokoro accepts at most MAX_PHONEME_TOKENS per forward pass and SILENTLY drops
+// whatever does not fit — the failure is "it stopped reading halfway", with no
+// error. So every returned part must be bounded, not merely usually bounded.
+//
+// Boundaries are tried in descending order of how natural the pause sounds:
+// sentence → clause → word → (last resort) a hard slice. Falling through to the
+// next one only happens when the previous left a part still over the limit, so
+// ordinary prose splits where a listener expects a breath.
+export function splitSentences(text, maxChars = 300) {
+  const bound = (s, seps) => {
+    if (s.length <= maxChars) return [s];
+    if (!seps.length) {
+      // A single unbroken run longer than the window (a URL, a base64 blob).
+      // Slicing it is ugly to listen to, but losing its tail is worse.
+      const out = [];
+      for (let i = 0; i < s.length; i += maxChars) out.push(s.slice(i, i + maxChars).trim());
+      return out.filter(Boolean);
+    }
+    const [sep, ...rest] = seps;
+    const out = [];
+    let buf = '';
+    for (const piece of s.split(sep)) {
+      const p = piece.trim();
+      if (!p) continue;
+      const cand = buf ? `${buf} ${p}` : p;
+      if (cand.length > maxChars && buf) { out.push(...bound(buf, rest)); buf = p; }
+      else buf = cand;
+    }
+    if (buf) out.push(...bound(buf, rest));
+    return out;
+  };
+
+  const parts = [];
+  for (const raw of String(text).split(/(?<=[.!?])\s+|\n{2,}/)) {
+    const s = raw.trim();
+    if (s) parts.push(...bound(s, [/(?<=[,;:])\s+/, /\s+/]));
+  }
+  return parts;
+}
+
+/**
+ * Synthesize ONE chunk. Returns 24 kHz mono Float32 PCM.
+ * @param {string} text @param {{voice?: string, speed?: number}} [opts]
+ */
+export async function synthChunk(text, { voice = DEFAULT_TTS_VOICE, speed = 1 } = {}) {
+  if (!isReady()) throw new Error('tts model not ready');
+  const { phonemize } = await import('phonemizer');
+  const tf = await import('@huggingface/transformers');
+
+  // G2P follows the VOICE, not the request — an American voice reading British
+  // phonemes is audibly wrong.
+  const phonemes = (await phonemize(String(text), voiceLang(voice))).join(' ');
+  const { input_ids } = _tok(phonemes, { truncation: true });
+
+  const bank = await loadVoice(voice);
+  // One style row per token count; clamp so a long chunk still picks a valid row.
+  const n = Math.min(Math.max(input_ids.dims.at(-1) - 2, 0), Math.floor(bank.length / STYLE_DIM) - 1);
+  const style = bank.slice(n * STYLE_DIM, n * STYLE_DIM + STYLE_DIM);
+
+  const out = await _net({
+    input_ids,
+    style: new tf.Tensor('float32', style, [1, STYLE_DIM]),
+    speed: new tf.Tensor('float32', [speed], [1]),
+  });
+  return out.waveform.data;
+}
+
+/** Synthesize arbitrary-length text, chunk by chunk. `onChunk` sees each as it lands. */
+export async function synth(text, { voice = DEFAULT_TTS_VOICE, speed = 1, onChunk = null } = {}) {
+  const chunks = splitSentences(text);
+  const out = [];
+  for (const c of chunks) {
+    const pcm = await synthChunk(c, { voice, speed });
+    out.push(pcm);
+    onChunk?.(pcm);
+  }
+  if (out.length === 1) return out[0];
+  const total = out.reduce((n, a) => n + a.length, 0);
+  const merged = new Float32Array(total);
+  let at = 0;
+  for (const a of out) { merged.set(a, at); at += a.length; }
+  return merged;
+}
+
+// ── WAV ──────────────────────────────────────────────────────────────────────────
+// 16-bit PCM WAV: what every <audio> element and every OS player accepts without a
+// codec. Float32 → int16 with clamping (a value outside [-1,1] wraps and clicks).
+export function toWav(pcm, sampleRate = SAMPLE_RATE) {
+  const buf = Buffer.alloc(44 + pcm.length * 2);
+  buf.write('RIFF', 0);
+  buf.writeUInt32LE(36 + pcm.length * 2, 4);
+  buf.write('WAVE', 8);
+  buf.write('fmt ', 12);
+  buf.writeUInt32LE(16, 16);          // PCM chunk size
+  buf.writeUInt16LE(1, 20);           // format = PCM
+  buf.writeUInt16LE(1, 22);           // channels = mono
+  buf.writeUInt32LE(sampleRate, 24);
+  buf.writeUInt32LE(sampleRate * 2, 28); // byte rate
+  buf.writeUInt16LE(2, 32);           // block align
+  buf.writeUInt16LE(16, 34);          // bits per sample
+  buf.write('data', 36);
+  buf.writeUInt32LE(pcm.length * 2, 40);
+  for (let i = 0; i < pcm.length; i++) {
+    const s = Math.max(-1, Math.min(1, pcm[i]));
+    buf.writeInt16LE(Math.round(s * 32767), 44 + i * 2);
+  }
+  return buf;
+}
+
+export function _reset() {
+  _state = 'off'; _model = null; _net = null; _tok = null; _dtype = null;
+  _err = null; _progress = null; _initPromise = null; _voices.clear();
+}

package/src/tts-models.js

@@ -0,0 +1,138 @@
+// Catalog of text-to-speech models the gateway can run — Phase 4 of the voice
+// pipeline (docs/voice-pipeline.md), the "voice out" counterpart to stt-models.js.
+// Same engine family (ONNX via transformers.js), same model root, same download
+// plumbing, same picker shape — so the Gateway tab renders it like the STT list.
+//
+// Why Kokoro and not the piper-class voices the design doc originally named: piper
+// phonemizes through `piper-phonemize`, a NATIVE espeak-ng binding, and the
+// standalone binary is a Bun --compile artifact that cannot carry native addons
+// (it is why scripts/build.mjs stubs onnxruntime-node and sharp). Kokoro's G2P is
+// the pure-JS `phonemizer` package — zero dependencies — so it is the one that
+// actually runs on BOTH delivery channels. It is also Apache-2.0, 82M params, and
+// ships fp32 + quantized ONNX exports, which is exactly the dual-runtime split
+// model-runtime.js already encodes.
+//
+// Adding a model: it must expose `onnx/model{suffix}.onnx` and a tokenizer, and be
+// driveable by a transformers.js class (Kokoro = StyleTextToSpeech2Model). Verify
+// it loads on BOTH runtimes (native q8 + WASM fp32) before listing it.
+
+export const DEFAULT_TTS_MODEL = 'onnx-community/Kokoro-82M-v1.0-ONNX';
+export const DEFAULT_TTS_VOICE = 'af_heart';
+
+// Style-vector width in a voices/*.bin file, and the max token window a single
+// forward pass accepts. Both are properties of the Kokoro export, and the engine
+// needs them to slice the voice and to chunk long text.
+export const STYLE_DIM = 256;
+export const MAX_PHONEME_TOKENS = 510;
+
+// Upper bound on one /tts request. Long text is CHUNKED rather than rejected, so
+// this is not a model limit — it is a fairness limit: synthesis is single-engine
+// and roughly realtime, so an unbounded body would hold it for minutes.
+export const MAX_TTS_CHARS = 5000;
+
+export const TTS_MODEL_CATALOG = [
+  {
+    id: 'onnx-community/Kokoro-82M-v1.0-ONNX',
+    label: 'Kokoro 82M (v1.0)',
+    lang: 'English (US/UK)',
+    tier: 'balanced',
+    arch: 'style-tts2',
+    approxMB: 330,  // fp32 on WASM; ~90 on native q8
+    ramMB: 600,
+    sampleRate: 24000,
+    note: 'Apache-2.0, 82M params. Natural voices at ~5× realtime on CPU. The default.',
+  },
+];
+
+// Voice prefix → the language phonemizer must use for G2P. First letter = language,
+// second = gender (f/m). Only the English families are listed: the other Kokoro
+// voices (es/fr/hi/it/ja/pt/zh) need misaki-class G2P, which has no dependency-free
+// JS port — shipping them against an English phonemizer would produce confident
+// gibberish, which is worse than not offering them.
+const VOICE_LANG = { a: 'en-us', b: 'en-gb' };
+
+// `grade` is Kokoro's own published quality rating for the voice. Ordered best-first
+// so the picker's default ordering is already the useful one.
+export const TTS_VOICES = [
+  { id: 'af_heart',    label: 'Heart (US, female)',    lang: 'en-us', gender: 'female', grade: 'A'  },
+  { id: 'af_bella',    label: 'Bella (US, female)',    lang: 'en-us', gender: 'female', grade: 'A-' },
+  { id: 'bf_emma',     label: 'Emma (UK, female)',     lang: 'en-gb', gender: 'female', grade: 'B-' },
+  { id: 'af_nicole',   label: 'Nicole (US, female)',   lang: 'en-us', gender: 'female', grade: 'B-', note: 'Recorded close-mic — best on headphones.' },
+  { id: 'af_aoede',    label: 'Aoede (US, female)',    lang: 'en-us', gender: 'female', grade: 'C+' },
+  { id: 'af_kore',     label: 'Kore (US, female)',     lang: 'en-us', gender: 'female', grade: 'C+' },
+  { id: 'af_sarah',    label: 'Sarah (US, female)',    lang: 'en-us', gender: 'female', grade: 'C+' },
+  { id: 'am_michael',  label: 'Michael (US, male)',    lang: 'en-us', gender: 'male',   grade: 'C+' },
+  { id: 'am_fenrir',   label: 'Fenrir (US, male)',     lang: 'en-us', gender: 'male',   grade: 'C+' },
+  { id: 'am_puck',     label: 'Puck (US, male)',       lang: 'en-us', gender: 'male',   grade: 'C+' },
+  { id: 'af_nova',     label: 'Nova (US, female)',     lang: 'en-us', gender: 'female', grade: 'C'  },
+  { id: 'af_alloy',    label: 'Alloy (US, female)',    lang: 'en-us', gender: 'female', grade: 'C'  },
+  { id: 'bf_isabella', label: 'Isabella (UK, female)', lang: 'en-gb', gender: 'female', grade: 'C'  },
+  { id: 'bm_george',   label: 'George (UK, male)',     lang: 'en-gb', gender: 'male',   grade: 'C'  },
+  { id: 'bm_fable',    label: 'Fable (UK, male)',      lang: 'en-gb', gender: 'male',   grade: 'C'  },
+];
+
+// Which engine drives a model — the same dispatch seam stt-models.js has for
+// 'whisper' (transformers.js pipeline) vs 'parakeet-tdt' (raw onnxruntime, its own
+// decode loop). 'style-tts2' = Kokoro through transformers.js.
+//
+// The seam exists because the obvious second engine is already on the table:
+// Kyutai's Pocket TTS (MIT code, CC-BY-4.0 weights, ~100M params, streams a first
+// chunk in ~200 ms, six languages, and — unlike Kokoro — CLONES a voice from a
+// sample). It is not listed here because it is not implemented: its ONNX form is a
+// five-graph bundle (text_conditioner + flow_lm_main + flow_lm_flow + mimi
+// encoder/decoder) needing a hand-written flow-matching decode loop, from a
+// THIRD-PARTY re-export of a gated checkpoint. That is a parakeet-engine-sized
+// piece of work, not a catalog entry — so the seam is here and the engine is not.
+export function ttsModelEngine(id) {
+  return ttsModel(id)?.engine || 'style-tts2';
+}
+
+export function ttsModel(id) {
+  return TTS_MODEL_CATALOG.find((m) => m.id === id) || null;
+}
+export function isKnownTtsModel(id) {
+  return TTS_MODEL_CATALOG.some((m) => m.id === id);
+}
+export function ttsModelDtype(id) {
+  return ttsModel(id)?.dtype || null;
+}
+export function ttsVoice(id) {
+  return TTS_VOICES.find((v) => v.id === id) || null;
+}
+export function isKnownVoice(id) {
+  return TTS_VOICES.some((v) => v.id === id);
+}
+
+// A voice id becomes a FILENAME (voices/<id>.bin) and a phonemizer language lookup,
+// so it is validated by shape as well as by catalog membership — belt and braces
+// against a traversal reaching the fetch/join even if the catalog check is ever
+// refactored away. Kokoro ids are strictly `<lang><gender>_<name>`.
+export function isValidVoiceId(id) {
+  return /^[a-z]{2}_[a-z0-9]+$/.test(String(id || ''));
+}
+
+// The phonemizer language for a voice — an American voice reading British phonemes
+// (or vice versa) is audibly wrong, so G2P follows the voice, not the request.
+export function voiceLang(id) {
+  return VOICE_LANG[String(id || '')[0]] || 'en-us';
+}
+
+// Same strict `org/name` shape as isValidCustomSttId — no traversal.
+export function isValidCustomTtsId(id) {
+  const s = String(id || '');
+  return /^[A-Za-z0-9][\w.-]*\/[\w.-]+$/.test(s) && !s.includes('..');
+}
+
+// Selectable precisions. Same ids as the STT picker (they are transformers.js
+// dtypes, not a whisper concept) but the notes are about synthesis speed.
+export const TTS_DTYPES = [
+  { id: 'auto', label: 'Auto (recommended)', note: 'q8 on the native gateway, fp32 on the WASM binary.' },
+  { id: 'q8', label: 'q8 — fast, balanced', note: 'Int8. Best speed/quality trade-off (native default).' },
+  { id: 'q4', label: 'q4 — smallest & fastest', note: '4-bit. Least memory; audibly rougher.' },
+  { id: 'fp16', label: 'fp16 — more accurate', note: 'Half precision. Larger, a bit slower.' },
+  { id: 'fp32', label: 'fp32 — best quality (slow)', note: 'Full precision. The only one that loads on the WASM binary.' },
+];
+
+export function isValidTtsDtype(d) {
+  return TTS_DTYPES.some((x) => x.id === d);
+}

package/src/tts-remote.js

@@ -0,0 +1,109 @@
+// Remote text-to-speech destinations — ElevenLabs, OpenAI, or anything that speaks
+// the OpenAI /audio/speech shape (Groq, a local server, an OpenAI-compatible proxy).
+//
+// TWO RULES, and they are the whole reason this is a separate module from
+// tts-engine.js rather than a branch inside it.
+//
+// 1. NO KEY LIVES HERE. config.js says it outright — "the gateway forwards the
+//    CLIENT's own auth header upstream (it stores no provider keys)" — and a TTS
+//    destination is not the place to break that. The caller sends its own
+//    Authorization (or xi-api-key) and we pass it through. Config holds the ROUTE.
+//
+// 2. THE PRIVACY DECISION INVERTS. Local synthesis speaks restored text because the
+//    words never leave the machine; there is nothing to protect them from. The
+//    moment the destination is remote, the text IS leaving, to a vendor, and every
+//    other egress in this gateway is redacted first. So remote synthesis redacts by
+//    default.
+//
+//    That trade is real and cannot be papered over: audio cannot be un-redacted the
+//    way a text completion can, so a redacted remote voice literally says
+//    "PERSON_1". The honest options are (a) placeholders spoken aloud, or (b) real
+//    PII sent to a vendor — and the user picks, per destination, with `redact`. The
+//    default is the safe one and the choice is logged via onEgress, so sending real
+//    names to ElevenLabs is something someone DID, not something that happened.
+
+import { secureFetch } from './secure-fetch.js';
+import { redactSegments, segment } from './redact.js';
+
+export const TTS_PROVIDERS = ['local', 'openai', 'elevenlabs'];
+
+export function isValidTtsProvider(p) {
+  return TTS_PROVIDERS.includes(String(p || ''));
+}
+
+/** The configured destination, or null when synthesis is local (the default). */
+export function ttsDestination(cfg = {}) {
+  const t = cfg.tts || {};
+  const kind = t.provider || 'local';
+  if (kind === 'local' || !isValidTtsProvider(kind)) return null;
+  const r = t.remote || {};
+  return {
+    kind,
+    baseUrl: String(r.baseUrl || (kind === 'elevenlabs' ? 'https://api.elevenlabs.io/v1' : 'https://api.openai.com/v1')).replace(/\/+$/, ''),
+    model: r.model || (kind === 'elevenlabs' ? 'eleven_multilingual_v2' : 'tts-1'),
+    voice: r.voice || (kind === 'elevenlabs' ? '21m00Tcm4TlvDq8ikWAM' : 'alloy'),
+    // Undefined means "not set", which must read as ON — an absent flag is never
+    // permission to send someone's name to a vendor.
+    redact: r.redact !== false,
+  };
+}
+
+// A remote voice id lands in a URL PATH for ElevenLabs, so it is shape-checked
+// rather than trusted: no slashes, no traversal, no query smuggling.
+export function isValidRemoteVoice(v) {
+  return /^[A-Za-z0-9_-]{1,64}$/.test(String(v || ''));
+}
+
+/**
+ * Synthesize remotely. Returns { audio: Buffer, contentType, redacted } — `redacted`
+ * is the count of values replaced, so the caller can report what actually left.
+ *
+ * @param {{dest: any, text: string, voice?: string, speed?: number, auth?: string,
+ *          redaction?: any, isPro?: boolean, onEgress?: Function, fetchImpl?: Function}} opts
+ */
+export async function synthesizeRemote({ dest, text, voice, speed = 1, auth, redaction, isPro = true, onEgress = null, fetchImpl = null } = {}) {
+  if (!dest) throw new Error('no remote TTS destination configured');
+  const pick = voice || dest.voice;
+  if (!isValidRemoteVoice(pick)) throw new Error(`invalid remote voice id: ${pick}`);
+
+  // Redact BEFORE anything is built, so there is no path where the raw string
+  // reaches a request body by accident.
+  let out = String(text);
+  let redacted = 0;
+  if (dest.redact && redaction) {
+    const box = { text: out };
+    const r = await redactSegments([segment(() => box.text, (v) => { box.text = v; })], redaction, { isPro, onEgress });
+    out = box.text;
+    redacted = r?.count || 0;
+  }
+
+  const fetcher = fetchImpl || secureFetch;
+  const headers = { 'Content-Type': 'application/json' };
+  let url, body;
+  if (dest.kind === 'elevenlabs') {
+    url = `${dest.baseUrl}/text-to-speech/${encodeURIComponent(pick)}`;
+    body = { text: out, model_id: dest.model };
+    // ElevenLabs uses its own header. Accept either form from the caller so a
+    // generic OpenAI client can drive it too.
+    const key = stripBearer(auth);
+    if (key) headers['xi-api-key'] = key;
+  } else {
+    url = `${dest.baseUrl}/audio/speech`;
+    body = { model: dest.model, input: out, voice: pick, response_format: 'wav', speed };
+    if (auth) headers.Authorization = auth.startsWith('Bearer ') ? auth : `Bearer ${auth}`;
+  }
+
+  const res = await fetcher(url, { method: 'POST', headers, body: JSON.stringify(body) });
+  if (!res.ok) {
+    let detail = `HTTP ${res.status}`;
+    try { detail = (await res.text()).slice(0, 300) || detail; } catch { /* no body */ }
+    throw new Error(`remote tts failed: ${detail}`);
+  }
+  const audio = Buffer.from(await res.arrayBuffer());
+  return { audio, contentType: res.headers.get('content-type') || 'audio/mpeg', redacted };
+}
+
+function stripBearer(a) {
+  const s = String(a || '').trim();
+  return s.toLowerCase().startsWith('bearer ') ? s.slice(7).trim() : s;
+}