@moxxy/plugin-tts-local 0.28.0

package/dist/wav.js

@@ -0,0 +1,62 @@
+/**
+ * Minimal float32 → PCM16 mono WAV encoder.
+ *
+ * sherpa-onnx hands back `{ samples: Float32Array in [-1, 1], sampleRate }`.
+ * Read-aloud surfaces and channel voice replies want playable container bytes,
+ * so we wrap the samples in a canonical 44-byte RIFF/WAVE header + 16-bit PCM
+ * little-endian data. Kept dependency-free and self-contained (deliberately NOT
+ * imported from plugin-stt-whisper) and covered by golden tests — the header
+ * offsets are load-bearing.
+ */
+/** Bytes in the RIFF/WAVE header preceding the PCM data. */
+export const WAV_HEADER_BYTES = 44;
+function writeAscii(view, offset, text) {
+    for (let i = 0; i < text.length; i += 1)
+        view.setUint8(offset + i, text.charCodeAt(i));
+}
+/**
+ * Encode float samples as a mono 16-bit PCM WAV. `sampleRate` must be a
+ * positive integer (sherpa reports e.g. 22050). Samples are clamped to
+ * [-1, 1]; non-finite samples encode as silence.
+ */
+export function encodeWav(samples, sampleRate) {
+    if (!Number.isFinite(sampleRate) || sampleRate <= 0) {
+        throw new Error(`encodeWav: invalid sampleRate ${sampleRate}`);
+    }
+    const rate = Math.round(sampleRate);
+    const numSamples = samples.length;
+    const bytesPerSample = 2; // PCM16
+    const blockAlign = bytesPerSample; // mono
+    const byteRate = rate * blockAlign;
+    const dataSize = numSamples * bytesPerSample;
+    const buffer = new ArrayBuffer(WAV_HEADER_BYTES + dataSize);
+    const view = new DataView(buffer);
+    // RIFF chunk descriptor
+    writeAscii(view, 0, 'RIFF');
+    view.setUint32(4, 36 + dataSize, true); // ChunkSize = 4 + (8 + Subchunk1) + (8 + data)
+    writeAscii(view, 8, 'WAVE');
+    // fmt subchunk
+    writeAscii(view, 12, 'fmt ');
+    view.setUint32(16, 16, true); // Subchunk1Size for PCM
+    view.setUint16(20, 1, true); // AudioFormat = 1 (PCM)
+    view.setUint16(22, 1, true); // NumChannels = 1 (mono)
+    view.setUint32(24, rate, true); // SampleRate
+    view.setUint32(28, byteRate, true); // ByteRate
+    view.setUint16(32, blockAlign, true); // BlockAlign
+    view.setUint16(34, 16, true); // BitsPerSample
+    // data subchunk
+    writeAscii(view, 36, 'data');
+    view.setUint32(40, dataSize, true);
+    let offset = WAV_HEADER_BYTES;
+    for (let i = 0; i < numSamples; i += 1) {
+        const raw = samples[i];
+        const s = Number.isFinite(raw) ? Math.max(-1, Math.min(1, raw)) : 0;
+        // Asymmetric scaling so full-scale positive/negative map to the int16 range
+        // edges without overflow.
+        const int16 = s < 0 ? Math.round(s * 0x8000) : Math.round(s * 0x7fff);
+        view.setInt16(offset, int16, true);
+        offset += 2;
+    }
+    return new Uint8Array(buffer);
+}
+//# sourceMappingURL=wav.js.map

package/dist/wav.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wav.js","sourceRoot":"","sources":["../src/wav.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@moxxy/plugin-tts-local",
+  "version": "0.28.0",
+  "description": "Fully local, on-device text-to-speech Synthesizer for moxxy. Runs Piper voices (English + Polish) via sherpa-onnx in a forked sidecar process; voice models download once on first use from sherpa-onnx's pinned releases (sha256-verified). No API key, no network at synthesis time. Plugs into the session SynthesizerRegistry — desktop read-aloud, the TUI, and channel voice replies consume it transparently.",
+  "keywords": [
+    "moxxy",
+    "agent",
+    "tts",
+    "text-to-speech",
+    "offline",
+    "on-device",
+    "piper",
+    "sherpa-onnx",
+    "synthesizer"
+  ],
+  "homepage": "https://moxxy.ai",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "packages/plugin-tts-local"
+  },
+  "author": "Michal Makowski <michal.makowski97@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "moxxy": {
+    "plugin": {
+      "entry": "./dist/index.js",
+      "kind": "synthesizer"
+    }
+  },
+  "dependencies": {
+    "sherpa-onnx-node": "^1.13.3",
+    "@moxxy/model-fetch": "0.1.0",
+    "@moxxy/sdk": "0.28.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "@moxxy/tsconfig": "0.0.0",
+    "@moxxy/vitest-preset": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/src/host-client.test.ts

@@ -0,0 +1,196 @@
+import { describe, expect, it } from 'vitest';
+import { HostClient, type ChildHandle, type ForkLike } from './host-client.js';
+import type { HostReply, HostRequest } from './host-protocol.js';
+
+/** A controllable fake sidecar: records sent requests + kill, and lets the test
+ *  drive `message`/`exit`/`error` back to the client. */
+class FakeChild implements ChildHandle {
+  readonly sent: HostRequest[] = [];
+  killed = false;
+  private readonly listeners: Record<string, Array<(...a: unknown[]) => void>> = {
+    message: [],
+    exit: [],
+    error: [],
+  };
+
+  send(message: unknown): boolean {
+    this.sent.push(message as HostRequest);
+    return true;
+  }
+  on(event: string, listener: (...args: unknown[]) => void): this {
+    this.listeners[event]!.push(listener);
+    return this;
+  }
+  kill(): boolean {
+    this.killed = true;
+    return true;
+  }
+
+  private emit(event: string, ...args: unknown[]): void {
+    for (const cb of [...this.listeners[event]!]) cb(...args);
+  }
+  /** Reply to the last request the client sent. */
+  replyOk(samples: number[], sampleRate = 22050): void {
+    this.replyOkTo(this.sent.at(-1)!.id, samples, sampleRate);
+  }
+  /** Reply to a specific request id (drives out-of-order correlation tests). */
+  replyOkTo(id: number, samples: number[], sampleRate = 22050): void {
+    this.emit('message', { id, ok: true, samples: new Float32Array(samples), sampleRate } satisfies HostReply);
+  }
+  replyErr(kind: 'init' | 'runtime', message: string): void {
+    const id = this.sent.at(-1)!.id;
+    this.emit('message', { id, ok: false, error: { kind, message } } satisfies HostReply);
+  }
+  crash(code = 1): void {
+    this.emit('exit', code, null);
+  }
+  errorOut(message: string): void {
+    this.emit('error', new Error(message));
+  }
+}
+
+/** A fork factory handing out a fixed list of children, tracking call count. */
+function forkFactory(children: FakeChild[]): { fork: ForkLike; calls: () => number } {
+  let n = 0;
+  const fork: ForkLike = () => {
+    const child = children[n];
+    n += 1;
+    if (!child) throw new Error(`unexpected fork #${n}`);
+    return child;
+  };
+  return { fork, calls: () => n };
+}
+
+const REQ = {
+  voiceKey: '/m/model.onnx',
+  model: '/m/model.onnx',
+  tokens: '/m/tokens.txt',
+  dataDir: '/m/espeak-ng-data',
+  numThreads: 2,
+  provider: 'cpu',
+  text: 'hello',
+  sid: 0,
+  speed: 1,
+};
+
+const tick = (): Promise<void> => new Promise((r) => setTimeout(r, 0));
+
+describe('HostClient', () => {
+  it('does not fork until the first synthesize (lazy spawn)', async () => {
+    const child = new FakeChild();
+    const { fork, calls } = forkFactory([child]);
+    const host = new HostClient({ hostPath: '/x/sidecar.js', env: {}, forkImpl: fork });
+    expect(calls()).toBe(0);
+    const p = host.synthesize(REQ);
+    await tick();
+    expect(calls()).toBe(1);
+    child.replyOk([0.5, -0.5], 16000);
+    await expect(p).resolves.toEqual({ samples: new Float32Array([0.5, -0.5]), sampleRate: 16000 });
+    host.shutdown();
+  });
+
+  it('correlates replies by id and reuses one child across calls', async () => {
+    const child = new FakeChild();
+    const { fork, calls } = forkFactory([child]);
+    const host = new HostClient({ hostPath: '/x/sidecar.js', env: {}, forkImpl: fork });
+
+    const p1 = host.synthesize({ ...REQ, text: 'one' });
+    await tick();
+    const p2 = host.synthesize({ ...REQ, text: 'two' });
+    await tick();
+    // Two distinct ids were sent to the same child.
+    expect(child.sent.map((m) => m.id)).toEqual([1, 2]);
+    expect(calls()).toBe(1);
+    // Reply out of order — id correlation must still settle each promise.
+    child.replyOkTo(2, [2]);
+    child.replyOkTo(1, [1]);
+    await expect(p1).resolves.toMatchObject({ samples: new Float32Array([1]) });
+    await expect(p2).resolves.toMatchObject({ samples: new Float32Array([2]) });
+    host.shutdown();
+  });
+
+  it('rejects a synthesis error reply', async () => {
+    const child = new FakeChild();
+    const { fork } = forkFactory([child]);
+    const host = new HostClient({ hostPath: '/x/sidecar.js', env: {}, forkImpl: fork });
+    const p = host.synthesize(REQ);
+    await tick();
+    child.replyErr('runtime', 'boom');
+    await expect(p).rejects.toThrow(/runtime error: boom/);
+    host.shutdown();
+  });
+
+  it('restarts the sidecar once on a crash and completes on the fresh child', async () => {
+    const first = new FakeChild();
+    const second = new FakeChild();
+    const { fork, calls } = forkFactory([first, second]);
+    const host = new HostClient({ hostPath: '/x/sidecar.js', env: {}, forkImpl: fork });
+
+    const p = host.synthesize(REQ);
+    await tick();
+    expect(calls()).toBe(1);
+    first.crash(139); // dies with the request in flight
+    await tick();
+    // A fresh child was spawned for the retry.
+    expect(calls()).toBe(2);
+    second.replyOk([0.25], 8000);
+    await expect(p).resolves.toEqual({ samples: new Float32Array([0.25]), sampleRate: 8000 });
+    host.shutdown();
+  });
+
+  it('gives up after a second consecutive crash', async () => {
+    const first = new FakeChild();
+    const second = new FakeChild();
+    const { fork } = forkFactory([first, second]);
+    const host = new HostClient({ hostPath: '/x/sidecar.js', env: {}, forkImpl: fork });
+    const p = host.synthesize(REQ);
+    await tick();
+    first.crash();
+    await tick();
+    second.crash();
+    await expect(p).rejects.toThrow(/sidecar exited/);
+    host.shutdown();
+  });
+
+  it('treats a spawn error as a crash', async () => {
+    const child = new FakeChild();
+    const second = new FakeChild();
+    const { fork } = forkFactory([child, second]);
+    const host = new HostClient({ hostPath: '/x/sidecar.js', env: {}, forkImpl: fork });
+    const p = host.synthesize(REQ);
+    await tick();
+    child.errorOut('ENOENT node');
+    await tick();
+    second.replyOk([1]);
+    await expect(p).resolves.toMatchObject({ samples: new Float32Array([1]) });
+    host.shutdown();
+  });
+
+  it('times out a hung synthesis and kills the child', async () => {
+    const child = new FakeChild();
+    const { fork } = forkFactory([child]);
+    const host = new HostClient({
+      hostPath: '/x/sidecar.js',
+      env: {},
+      forkImpl: fork,
+      requestTimeoutMs: 10,
+    });
+    const p = host.synthesize(REQ);
+    await expect(p).rejects.toThrow(/timed out/);
+    expect(child.killed).toBe(true);
+    host.shutdown();
+  });
+
+  it('shutdown kills the child and rejects in-flight requests', async () => {
+    const child = new FakeChild();
+    const { fork } = forkFactory([child]);
+    const host = new HostClient({ hostPath: '/x/sidecar.js', env: {}, forkImpl: fork });
+    const p = host.synthesize(REQ);
+    await tick();
+    host.shutdown();
+    expect(child.killed).toBe(true);
+    await expect(p).rejects.toThrow(/shut down/);
+    // Further calls fail fast.
+    await expect(host.synthesize(REQ)).rejects.toThrow(/shut down/);
+  });
+});

package/src/host-client.ts

@@ -0,0 +1,205 @@
+/**
+ * Parent-side manager for the sherpa sidecar: lazy-spawn on first synthesize,
+ * a correlated request/reply protocol over the fork IPC channel, restart-once
+ * on a crash, and a clean shutdown. The `fork` itself is injectable (a
+ * {@link ForkLike}) so tests drive the whole protocol against a fake child with
+ * no real process.
+ */
+
+import { fork } from 'node:child_process';
+
+import type { HostReply, HostRequest } from './host-protocol.js';
+
+/** The minimal child-process surface the client drives — satisfied by a real
+ *  `ChildProcess` and by a test fake. */
+export interface ChildHandle {
+  send(message: unknown): boolean;
+  on(event: 'message', listener: (message: unknown) => void): this;
+  on(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;
+  on(event: 'error', listener: (err: Error) => void): this;
+  kill(signal?: NodeJS.Signals): boolean;
+}
+
+/** Fork the sidecar with the given env overrides. Injectable for tests. */
+export type ForkLike = (modulePath: string, env: NodeJS.ProcessEnv) => ChildHandle;
+
+/** Default fork: advanced serialization (Float32Array round-trip), an IPC
+ *  channel, and inherited std streams so sherpa's own diagnostics reach the
+ *  runner log. `env` already carries the platform loader-path var. */
+export const defaultFork: ForkLike = (modulePath, env) =>
+  fork(modulePath, [], {
+    serialization: 'advanced',
+    env,
+    execArgv: [],
+    stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
+  }) as unknown as ChildHandle;
+
+export interface HostClientOptions {
+  /** Absolute path to the built sidecar (`dist/sidecar.js`). */
+  readonly hostPath: string;
+  /** Env the child is forked with (platform loader path merged over process.env). */
+  readonly env: NodeJS.ProcessEnv;
+  /** Injected fork (tests). Defaults to {@link defaultFork}. */
+  readonly forkImpl?: ForkLike;
+  /** Per-request deadline. Default 120s (a long read-aloud on CPU). */
+  readonly requestTimeoutMs?: number;
+  /** Optional diagnostic sink. */
+  readonly log?: (msg: string) => void;
+}
+
+/** The slice of a host the synthesizer depends on — lets tests swap a fake. */
+export interface HostClientLike {
+  synthesize(
+    req: Omit<HostRequest, 'id' | 'type'>,
+  ): Promise<{ samples: Float32Array; sampleRate: number }>;
+  shutdown(): void;
+}
+
+/** Raised when the sidecar dies with a request in flight; drives the one retry. */
+export class HostCrashError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'HostCrashError';
+  }
+}
+
+interface Pending {
+  readonly resolve: (r: { samples: Float32Array; sampleRate: number }) => void;
+  readonly reject: (err: Error) => void;
+  timer: ReturnType<typeof setTimeout> | null;
+}
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+export class HostClient implements HostClientLike {
+  private readonly hostPath: string;
+  private readonly env: NodeJS.ProcessEnv;
+  private readonly forkImpl: ForkLike;
+  private readonly timeoutMs: number;
+  private readonly log: (msg: string) => void;
+
+  private child: ChildHandle | null = null;
+  private readonly pending = new Map<number, Pending>();
+  private nextId = 1;
+  private disposed = false;
+
+  constructor(opts: HostClientOptions) {
+    this.hostPath = opts.hostPath;
+    this.env = opts.env;
+    this.forkImpl = opts.forkImpl ?? defaultFork;
+    this.timeoutMs = opts.requestTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.log = opts.log ?? (() => {});
+  }
+
+  /** Synthesize, restarting the sidecar ONCE if it crashes mid-request. */
+  async synthesize(
+    req: Omit<HostRequest, 'id' | 'type'>,
+  ): Promise<{ samples: Float32Array; sampleRate: number }> {
+    try {
+      return await this.send(req);
+    } catch (err) {
+      if (err instanceof HostCrashError && !this.disposed) {
+        this.log(`tts-local: sherpa sidecar crashed (${err.message}) — restarting once`);
+        return await this.send(req); // a second crash propagates
+      }
+      throw err;
+    }
+  }
+
+  private send(
+    req: Omit<HostRequest, 'id' | 'type'>,
+  ): Promise<{ samples: Float32Array; sampleRate: number }> {
+    if (this.disposed) return Promise.reject(new Error('tts-local host is shut down'));
+    const child = this.ensureChild();
+    const id = this.nextId++;
+    const message: HostRequest = { ...req, id, type: 'synthesize' };
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        // A hung synthesis is unrecoverable for this child — reset it so the
+        // next call starts fresh.
+        this.killChild();
+        reject(new Error(`tts-local synthesis timed out after ${this.timeoutMs} ms`));
+      }, this.timeoutMs);
+      timer.unref?.();
+      this.pending.set(id, { resolve, reject, timer });
+      try {
+        child.send(message);
+      } catch (err) {
+        this.settle(id, () =>
+          reject(err instanceof Error ? err : new Error(String(err))),
+        );
+      }
+    });
+  }
+
+  private ensureChild(): ChildHandle {
+    if (this.child) return this.child;
+    const child = this.forkImpl(this.hostPath, this.env);
+    this.child = child;
+    child.on('message', (msg: unknown) => this.onMessage(msg));
+    child.on('exit', (code, signal) => this.onExit(code, signal));
+    child.on('error', (err) => this.onError(err));
+    return child;
+  }
+
+  private onMessage(msg: unknown): void {
+    const reply = msg as HostReply;
+    if (!reply || typeof reply !== 'object' || typeof reply.id !== 'number') return;
+    const p = this.pending.get(reply.id);
+    if (!p) return;
+    this.settle(reply.id, () => {
+      if (reply.ok) p.resolve({ samples: reply.samples, sampleRate: reply.sampleRate });
+      else p.reject(new Error(`tts-local sidecar ${reply.error.kind} error: ${reply.error.message}`));
+    });
+  }
+
+  private onExit(code: number | null, signal: NodeJS.Signals | null): void {
+    this.child = null;
+    if (this.pending.size === 0) return;
+    const why = `sidecar exited (code=${code ?? 'null'}, signal=${signal ?? 'null'})`;
+    this.rejectAll(new HostCrashError(why));
+  }
+
+  private onError(err: Error): void {
+    this.child = null;
+    this.rejectAll(new HostCrashError(`sidecar spawn/runtime error: ${err.message}`));
+  }
+
+  /** Resolve/reject one pending request, clearing its timer and map entry. */
+  private settle(id: number, run: () => void): void {
+    const p = this.pending.get(id);
+    if (!p) return;
+    if (p.timer) clearTimeout(p.timer);
+    this.pending.delete(id);
+    run();
+  }
+
+  private rejectAll(err: Error): void {
+    for (const [id, p] of this.pending) {
+      if (p.timer) clearTimeout(p.timer);
+      this.pending.delete(id);
+      p.reject(err);
+    }
+  }
+
+  private killChild(): void {
+    const child = this.child;
+    this.child = null;
+    if (child) {
+      try {
+        child.kill('SIGKILL');
+      } catch {
+        /* already gone */
+      }
+    }
+  }
+
+  /** Kill the sidecar and fail any in-flight requests. Idempotent. */
+  shutdown(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.rejectAll(new Error('tts-local host shut down'));
+    this.killChild();
+  }
+}

package/src/host-protocol.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createMessageHandler,
+  type HostRequest,
+  type SherpaModule,
+  type SherpaOfflineTts,
+} from './host-protocol.js';
+
+function req(over: Partial<HostRequest> = {}): HostRequest {
+  return {
+    id: 1,
+    type: 'synthesize',
+    voiceKey: '/models/en/model.onnx',
+    model: '/models/en/model.onnx',
+    tokens: '/models/en/tokens.txt',
+    dataDir: '/models/en/espeak-ng-data',
+    numThreads: 2,
+    provider: 'cpu',
+    text: 'hello',
+    sid: 0,
+    speed: 1,
+    ...over,
+  };
+}
+
+/** A fake sherpa module recording how many OfflineTts instances + generate
+ *  calls it saw, with configurable behaviour. */
+function fakeSherpa(opts: {
+  onGenerate?: (args: { text: string; sid: number; speed: number }) => {
+    samples: Float32Array;
+    sampleRate: number;
+  };
+  throwOnConstruct?: boolean;
+  throwOnGenerate?: boolean;
+} = {}): { module: SherpaModule; constructed: number; generated: number; lastConfig: unknown } {
+  const state = { constructed: 0, generated: 0, lastConfig: undefined as unknown };
+  class FakeTts implements SherpaOfflineTts {
+    constructor(config: unknown) {
+      if (opts.throwOnConstruct) throw new Error('addon failed to load libonnxruntime.dylib');
+      state.constructed += 1;
+      state.lastConfig = config;
+    }
+    async generateAsync(args: { text: string; sid: number; speed: number }): Promise<{
+      samples: Float32Array;
+      sampleRate: number;
+    }> {
+      state.generated += 1;
+      if (opts.throwOnGenerate) throw new Error('generate blew up');
+      return opts.onGenerate?.(args) ?? { samples: new Float32Array([0.1, 0.2]), sampleRate: 22050 };
+    }
+  }
+  return {
+    module: { OfflineTts: FakeTts as unknown as SherpaModule['OfflineTts'] },
+    get constructed() {
+      return state.constructed;
+    },
+    get generated() {
+      return state.generated;
+    },
+    get lastConfig() {
+      return state.lastConfig;
+    },
+  };
+}
+
+describe('createMessageHandler', () => {
+  it('synthesizes and returns samples + sampleRate', async () => {
+    const s = fakeSherpa({ onGenerate: () => ({ samples: new Float32Array([1, -1]), sampleRate: 16000 }) });
+    const handle = createMessageHandler(() => s.module);
+    const reply = await handle(req({ id: 7, text: 'hi', speed: 1.25 }));
+    expect(reply).toMatchObject({ id: 7, ok: true, sampleRate: 16000 });
+    if (reply.ok) expect(Array.from(reply.samples)).toEqual([1, -1]);
+  });
+
+  it('passes the vits model config through to sherpa', async () => {
+    const s = fakeSherpa();
+    const handle = createMessageHandler(() => s.module);
+    await handle(req());
+    expect(s.lastConfig).toMatchObject({
+      model: {
+        vits: { model: '/models/en/model.onnx', tokens: '/models/en/tokens.txt', dataDir: '/models/en/espeak-ng-data' },
+        numThreads: 2,
+        provider: 'cpu',
+      },
+      maxNumSentences: 1,
+    });
+  });
+
+  it('caches one OfflineTts per voiceKey (loads the model once)', async () => {
+    const s = fakeSherpa();
+    let loads = 0;
+    const handle = createMessageHandler(() => {
+      loads += 1;
+      return s.module;
+    });
+    await handle(req({ id: 1 }));
+    await handle(req({ id: 2 }));
+    await handle(req({ id: 3, voiceKey: '/models/pl/model.onnx', model: '/models/pl/model.onnx' }));
+    expect(loads).toBe(1); // module loaded once
+    expect(s.constructed).toBe(2); // one OfflineTts per distinct voiceKey
+    expect(s.generated).toBe(3);
+  });
+
+  it('classifies a load/construct failure as an init error', async () => {
+    const s = fakeSherpa({ throwOnConstruct: true });
+    const handle = createMessageHandler(() => s.module);
+    const reply = await handle(req());
+    expect(reply.ok).toBe(false);
+    if (!reply.ok) expect(reply.error.kind).toBe('init');
+  });
+
+  it('classifies a load-time throw as an init error', async () => {
+    const handle = createMessageHandler(() => {
+      throw new Error('cannot find module sherpa-onnx-node');
+    });
+    const reply = await handle(req());
+    expect(reply.ok).toBe(false);
+    if (!reply.ok) expect(reply.error.kind).toBe('init');
+  });
+
+  it('classifies a synthesis failure as a runtime error', async () => {
+    const s = fakeSherpa({ throwOnGenerate: true });
+    const handle = createMessageHandler(() => s.module);
+    const reply = await handle(req());
+    expect(reply.ok).toBe(false);
+    if (!reply.ok) expect(reply.error.kind).toBe('runtime');
+  });
+});