stitchkit 0.95.1 → 0.95.2

package/CHANGELOG.md

@@ -15,6 +15,32 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.95.2] — 2026-09-23
+
+### Added
+
+- `stitchkit/voice` (new, browser **and** server, evolving, no dependencies) — the
+  mechanics of a live voice conversation with an agent that applications were each
+  carrying a copy of:
+  - **`SentenceCutter`** — `next(text, final)` cuts a reply into finished sentences
+    while it streams, so a voice starts on the first one; not at `3.5`, `т. е.` or an
+    ellipsis before lowercase, never inside a fenced code block; `reset()` starts a
+    new turn.
+  - **`speakableText(markdown)`** — what a reader sees, without Markdown delimiters,
+    link and image addresses, bare addresses, fenced code blocks or tables.
+  - **`SpeechQueue<Prepared>({ prepare, play, lookahead, onError, discard })`** —
+    speaks sentences in order and synthesises up to `lookahead` (default 1) while one
+    plays, so a synthesiser that returns whole clips leaves no gap between sentences;
+    `close()` finishes what is queued, `cancel()` aborts the playing sentence and every
+    synthesis in flight and settles `done` at once; a failed sentence is reported and
+    skipped.
+  - **`LIVE_VOICE_PHASES` / `LiveVoicePhase`** — `opening`, `idle`, `hearing`,
+    `thinking`, `speaking`.
+
+  Migration for an application with its own copy: import these four from
+  `stitchkit/voice` and delete the copy. A sequential queue over a streaming
+  synthesiser is `lookahead: 0`.
+
 ## [0.95.1] — 2026-09-23
 
 ### Added

package/dist/entrypoints/voice.d.ts

@@ -0,0 +1,6 @@
+/** Isomorphic primitives of a live voice conversation: sentences, speakable text, speech queue. */
+export { LIVE_VOICE_PHASES, type LiveVoicePhase } from '../voice/phases.js';
+export { SentenceCutter } from '../voice/sentences.js';
+export { speakableText } from '../voice/speakable.js';
+export { SpeechQueue, type SpeechQueueOptions } from '../voice/speech-queue.js';
+//# sourceMappingURL=voice.d.ts.map

package/dist/entrypoints/voice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice.d.ts","sourceRoot":"","sources":["../../src/entrypoints/voice.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,OAAO,EAAE,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/entrypoints/voice.js

@@ -0,0 +1,221 @@
+// src/voice/phases.ts
+var LIVE_VOICE_PHASES = [
+  "opening",
+  "idle",
+  "hearing",
+  "thinking",
+  "speaking"
+];
+// src/voice/sentences.ts
+var TERMINAL = /[.!?…]/;
+var CLOSING = /["»”)]/;
+var ENDS_SENTENCE = /[.!?…]+["»”)]*$/;
+var OPENER = /^[\p{Lu}\p{N}"«“(—–-]/u;
+var NEXT_WORD = /^\s+(\S)/u;
+
+class SentenceCutter {
+  said = 0;
+  next(text, final) {
+    const sentences = [];
+    let start = this.said;
+    let fence = fenceFrom(text, this.said);
+    for (let index = this.said;index < text.length; index += 1) {
+      if (index >= fence.end)
+        fence = fenceFrom(text, index);
+      if (index >= fence.start && index < fence.end)
+        continue;
+      if (!isBoundary(text, index, start))
+        continue;
+      const sentence = text.slice(start, index + 1).trim();
+      if (sentence !== "")
+        sentences.push(sentence);
+      start = index + 1;
+    }
+    this.said = start;
+    if (final) {
+      const rest = text.slice(start).trim();
+      if (rest !== "")
+        sentences.push(rest);
+      this.said = text.length;
+    }
+    return sentences;
+  }
+  reset() {
+    this.said = 0;
+  }
+}
+function isBoundary(text, index, start) {
+  const char = text[index] ?? "";
+  if (char === `
+` && text[index + 1] === `
+`)
+    return true;
+  if (!TERMINAL.test(char) && !CLOSING.test(char))
+    return false;
+  const following = text[index + 1] ?? "";
+  if (TERMINAL.test(following) || CLOSING.test(following))
+    return false;
+  if (!ENDS_SENTENCE.test(text.slice(start, index + 1)))
+    return false;
+  const next = text.slice(index + 1, index + 64).match(NEXT_WORD);
+  return next !== null && OPENER.test(next[1] ?? "");
+}
+function fenceFrom(text, from) {
+  const open = text.indexOf("```", from);
+  if (open === -1)
+    return { start: text.length, end: text.length };
+  const close = text.indexOf("```", open + 3);
+  return { start: open, end: close === -1 ? text.length : close + 3 };
+}
+// src/voice/speakable.ts
+var FENCED_BLOCK = /^[ \t]*(```|~~~)[^\n]*\n[\s\S]*?(?:^[ \t]*\1[^\n]*$|(?![\s\S]))/gm;
+var TABLE_ROW = /^[ \t]*\|.*$/gm;
+var THEMATIC_BREAK = /^[ \t]*([-*_])(?:[ \t]*\1){2,}[ \t]*$/gm;
+var IMAGE = /!\[[^\]]*\]\((?:<[^>]*>|[^)])*\)/g;
+var LINK = /\[([^\]]+)\]\((?:<[^>]*>|[^)])*\)/g;
+var REFERENCE_LINK = /\[([^\]]+)\]\[[^\]]*\]/g;
+var LINK_DEFINITION = /^[ \t]{0,3}\[[^\]]+\]:[ \t]*\S+.*$/gm;
+var AUTOLINK = /<(?:https?|mailto):[^>\s]*>/g;
+var BARE_URL = /\bhttps?:\/\/[^\s<>()]+/g;
+var HTML_TAG = /<\/?[A-Za-z][^>]*>/g;
+var LINE_MARKER = /^[ \t]{0,3}(?:#{1,6}[ \t]+|>[ \t]?|[-*+][ \t]+(?:\[[ xX]\][ \t]+)?)/gm;
+function speakableText(markdown) {
+  return markdown.replace(FENCED_BLOCK, " ").replace(TABLE_ROW, " ").replace(THEMATIC_BREAK, " ").replace(LINK_DEFINITION, " ").replace(IMAGE, "").replace(LINK, "$1").replace(REFERENCE_LINK, "$1").replace(AUTOLINK, "").replace(BARE_URL, "").replace(HTML_TAG, "").replace(LINE_MARKER, "").replace(/\*\*([^*]+)\*\*/g, "$1").replace(/__([^_]+)__/g, "$1").replace(/~~([^~]+)~~/g, "$1").replace(/(^|[^\p{L}\p{N}*])\*([^*\s][^*]*?)\*(?![\p{L}\p{N}*])/gu, "$1$2").replace(/(^|[^\p{L}\p{N}_])_([^_\s][^_]*?)_(?![\p{L}\p{N}_])/gu, "$1$2").replace(/`([^`]+)`/g, "$1").replace(/\s+/g, " ").replace(/ ([.,!?;:…])/g, "$1").trim();
+}
+// src/voice/speech-queue.ts
+var CANCELLED = Symbol("cancelled");
+function settle(run) {
+  return Promise.resolve().then(run).then((value) => ({ ok: true, value }), (error) => ({ ok: false, error }));
+}
+
+class SpeechQueue {
+  options;
+  done;
+  lookahead;
+  pending = [];
+  ahead = [];
+  current = null;
+  playing = false;
+  closed = false;
+  cancelled = false;
+  wake = null;
+  stop;
+  stopped = new Promise((resolve) => {
+    this.stop = resolve;
+  });
+  constructor(options) {
+    this.options = options;
+    const lookahead = options.lookahead ?? 1;
+    if (!Number.isInteger(lookahead) || lookahead < 0) {
+      throw new RangeError(`lookahead must be a non-negative integer, got ${lookahead}`);
+    }
+    this.lookahead = lookahead;
+    this.done = this.run();
+  }
+  get isCancelled() {
+    return this.cancelled;
+  }
+  get isSpeaking() {
+    return this.playing;
+  }
+  push(text) {
+    if (this.closed || this.cancelled || text.trim() === "")
+      return;
+    this.pending.push(text);
+    this.fill();
+    this.notify();
+  }
+  close() {
+    this.closed = true;
+    this.notify();
+  }
+  cancel() {
+    if (this.cancelled)
+      return;
+    this.cancelled = true;
+    this.closed = true;
+    this.pending.length = 0;
+    const unplayed = this.ahead.splice(0);
+    if (this.current && !this.playing)
+      unplayed.push(this.current);
+    this.current?.controller.abort();
+    for (const slot of unplayed) {
+      slot.controller.abort();
+      slot.result.then((outcome) => {
+        if (outcome.ok)
+          this.release(outcome.value);
+      });
+    }
+    this.stop(CANCELLED);
+    this.notify();
+  }
+  notify() {
+    this.wake?.();
+  }
+  fill() {
+    const capacity = this.lookahead + 1 - (this.current ? 1 : 0);
+    while (!this.cancelled && this.ahead.length < capacity && this.pending.length > 0) {
+      const text = this.pending.shift();
+      const controller = new AbortController;
+      this.ahead.push({
+        text,
+        controller,
+        result: settle(() => this.options.prepare(text, controller.signal))
+      });
+    }
+  }
+  async run() {
+    while (!this.cancelled) {
+      this.fill();
+      const slot = this.ahead.shift();
+      if (!slot) {
+        if (this.closed)
+          return;
+        await new Promise((resolve) => {
+          this.wake = resolve;
+        });
+        this.wake = null;
+        continue;
+      }
+      this.current = slot;
+      try {
+        const prepared = await Promise.race([slot.result, this.stopped]);
+        if (prepared === CANCELLED)
+          return;
+        if (!prepared.ok) {
+          this.report(prepared.error, slot.text);
+          continue;
+        }
+        this.playing = true;
+        this.fill();
+        const played = await Promise.race([
+          settle(() => this.options.play(prepared.value, slot.controller.signal)),
+          this.stopped
+        ]);
+        if (played === CANCELLED)
+          return;
+        if (!played.ok)
+          this.report(played.error, slot.text);
+      } finally {
+        this.playing = false;
+        this.current = null;
+      }
+    }
+  }
+  report(error, text) {
+    try {
+      this.options.onError?.(error, text);
+    } catch {}
+  }
+  release(prepared) {
+    try {
+      this.options.discard?.(prepared);
+    } catch {}
+  }
+}
+export {
+  speakableText,
+  SpeechQueue,
+  SentenceCutter,
+  LIVE_VOICE_PHASES
+};

package/dist/voice/phases.d.ts

@@ -0,0 +1,4 @@
+/** The phases of a live voice conversation, one vocabulary for every side of it. */
+export declare const LIVE_VOICE_PHASES: readonly ['opening', 'idle', 'hearing', 'thinking', 'speaking'];
+export type LiveVoicePhase = (typeof LIVE_VOICE_PHASES)[number];
+//# sourceMappingURL=phases.d.ts.map

package/dist/voice/phases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phases.d.ts","sourceRoot":"","sources":["../../src/voice/phases.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,YAC5B,SAAS,EACT,MAAM,EACN,SAAS,EACT,UAAU,EACV,UAAU,CACF,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/voice/sentences.d.ts

@@ -0,0 +1,8 @@
+export declare class SentenceCutter {
+    private said;
+    /** The sentences finished since the previous call; with `final`, the rest of the turn too. */
+    next(text: string, final: boolean): string[];
+    /** Start a new turn. */
+    reset(): void;
+}
+//# sourceMappingURL=sentences.d.ts.map

package/dist/voice/sentences.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sentences.d.ts","sourceRoot":"","sources":["../../src/voice/sentences.ts"],"names":[],"mappings":"AAkBA,qBAAa,cAAc;IACzB,OAAO,CAAC,IAAI,CAAK;IAEjB,8FAA8F;IAC9F,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAmB3C;IAED,wBAAwB;IACxB,KAAK,IAAI,IAAI,CAEZ;CACF"}

package/dist/voice/speakable.d.ts

@@ -0,0 +1,2 @@
+export declare function speakableText(markdown: string): string;
+//# sourceMappingURL=speakable.d.ts.map

package/dist/voice/speakable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"speakable.d.ts","sourceRoot":"","sources":["../../src/voice/speakable.ts"],"names":[],"mappings":"AAiBA,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAsBtD"}

package/dist/voice/speech-queue.d.ts

@@ -0,0 +1,42 @@
+export interface SpeechQueueOptions<Prepared> {
+    /** Synthesise one sentence. Aborted when the queue is cancelled. */
+    prepare: (text: string, signal: AbortSignal) => Promise<Prepared>;
+    /** Play one prepared sentence to its end. Aborted when the queue is cancelled. */
+    play: (prepared: Prepared, signal: AbortSignal) => Promise<void>;
+    /** Sentences prepared ahead of the one playing. Default 1; 0 prepares only after playing. */
+    lookahead?: number;
+    /** A sentence that failed to prepare or play is skipped; the queue goes on. */
+    onError?: (error: unknown, text: string) => void;
+    /** A prepared sentence that will never play — cancelled — to release what it holds. */
+    discard?: (prepared: Prepared) => void;
+}
+export declare class SpeechQueue<Prepared> {
+    private readonly options;
+    readonly done: Promise<void>;
+    private readonly lookahead;
+    private readonly pending;
+    private readonly ahead;
+    private current;
+    private playing;
+    private closed;
+    private cancelled;
+    private wake;
+    private stop;
+    private readonly stopped;
+    constructor(options: SpeechQueueOptions<Prepared>);
+    get isCancelled(): boolean;
+    get isSpeaking(): boolean;
+    /** Add one sentence. Blank text and anything after `close` or `cancel` is ignored. */
+    push(text: string): void;
+    /** The turn is over: say what is queued, then finish. */
+    close(): void;
+    /** Interrupted: abort the sentence playing and every synthesis, drop the rest. */
+    cancel(): void;
+    private notify;
+    /** Start synthesis up to the lookahead: the sentence playing or next, plus `lookahead`. */
+    private fill;
+    private run;
+    private report;
+    private release;
+}
+//# sourceMappingURL=speech-queue.d.ts.map

package/dist/voice/speech-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"speech-queue.d.ts","sourceRoot":"","sources":["../../src/voice/speech-queue.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,kBAAkB,CAAC,QAAQ;IAC1C,oEAAoE;IACpE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAClE,kFAAkF;IAClF,IAAI,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,6FAA6F;IAC7F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,uFAAuF;IACvF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;CACxC;AAqBD,qBAAa,WAAW,CAAC,QAAQ;IAenB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAdpC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwB;IAC9C,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,IAAI,CAA6B;IACzC,OAAO,CAAC,IAAI,CAAqC;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAErB;IAEH,YAA6B,OAAO,EAAE,kBAAkB,CAAC,QAAQ,CAAC,EAOjE;IAED,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,sFAAsF;IACtF,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAKvB;IAED,yDAAyD;IACzD,KAAK,IAAI,IAAI,CAGZ;IAED,kFAAkF;IAClF,MAAM,IAAI,IAAI,CAgBb;IAED,OAAO,CAAC,MAAM;IAId,2FAA2F;IAC3F,OAAO,CAAC,IAAI;YAaE,GAAG;IAmCjB,OAAO,CAAC,MAAM;IAQd,OAAO,CAAC,OAAO;CAOhB"}

package/llms/stitchkit.txt

@@ -73,6 +73,7 @@ own, recorded as an ADR.
 | `stitchkit/tracking` | browser **and** server | evolving | visitor-tracking mechanics — `createTrackingClient`, the tab-shared outbox, the page-leave beacon, attribution, the contract factory; no event vocabulary, no React |
 | `stitchkit/tracking/server` | server (Bun or Node) | evolving | the decisions a tracking backend makes — dispositions, visit lease over an application-owned store, active intervals, presence; no database |
 | `stitchkit/release` | browser **and** server | evolving | a page follows the release it was built for — `createReleaseMarker` on the server, `createReleaseWatcher` in the browser, the `X-Build-Id` header and a socket event between them |
+| `stitchkit/voice` | browser **and** server | evolving | the mechanics of a live voice reply — `SentenceCutter`, `speakableText`, a `SpeechQueue` that synthesises ahead and stops on interruption, the conversation phases |
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |

package/llms/voice.txt

@@ -0,0 +1,106 @@
+# stitchkit/voice — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: Guide: Voice  (docs/guide/voice.md) · API reference: `stitchkit/voice`  (docs/api/reference.md)
+
+==============================================================================
+# Guide: Voice  (docs/guide/voice.md)
+==============================================================================
+
+# Voice
+
+A live voice conversation with an agent repeats the same mechanics in every application
+that has one: the reply is cut into sentences while the model is still writing it, each
+sentence is stripped down to what can be said aloud, and a queue speaks them in order — and
+stops at once when the listener interrupts. `stitchkit/voice` is those mechanics, the same in
+the browser and on Bun or Node, with no dependencies. It is **evolving**.
+
+Speech recognition, synthesis providers, the microphone and the player stay with the
+application: the queue takes them as two functions.
+
+## Sentences while the reply streams
+
+```ts
+import { SentenceCutter, SpeechQueue, speakableText } from 'stitchkit/voice'
+
+const cutter = new SentenceCutter()
+
+for await (const text of reply) {           // the whole reply so far, on every chunk
+  for (const sentence of cutter.next(text, false)) say(sentence)
+}
+for (const sentence of cutter.next(finalText, true)) say(sentence) // the rest of the turn
+cutter.reset()                              // the next turn starts from zero
+```
+
+A sentence ends at `. ! ? …` (with any closing quote or bracket) followed by whitespace and a
+capital letter, a digit or an opening mark, or at a blank line between paragraphs. `3.5`,
+`т. е. так` and `e.g. this` are not cut; the end of the text is not the end of a sentence
+until `final`; nothing is cut inside a fenced code block, even one that is still open.
+
+## What is said
+
+`speakableText(markdown)` keeps what a reader sees and drops what cannot be said: headings,
+emphasis and list markers lose their delimiters, a link keeps its text and loses its
+address, and images, bare addresses, fenced code blocks and tables are dropped whole. It does
+not summarise. A sentence that was only code becomes `''`, and the queue ignores blank text.
+
+## Speaking in order, synthesising ahead
+
+```ts
+const queue = new SpeechQueue<Blob>({
+  prepare: (text, signal) => synthesise(text, { signal }),  // the whole clip
+  play: (clip, signal) => player.play(clip, { signal }),    // resolves when it has played
+  lookahead: 1,                                             // the default
+  onError: (error, text) => log.warn('sentence skipped', { error, text }),
+  discard: (clip) => release(clip),                         // prepared, never played
+})
+
+const say = (sentence: string) => queue.push(speakableText(sentence))
+
+// the turn is over: say what is queued, then `done` settles
+queue.close()
+// the listener interrupted: the playing sentence and every synthesis are aborted
+queue.cancel()
+await queue.done
+```
+
+While one sentence plays, up to `lookahead` more are already synthesising, so a synthesiser
+that returns the whole clip does not leave a gap the length of its synthesis between two
+sentences. `lookahead: 0` synthesises each sentence only after the previous one played.
+
+A sentence that fails to synthesise or to play is reported to `onError` and skipped; the
+queue goes on. `cancel()` aborts the signal of the sentence playing and of every synthesis in
+flight, drops the rest, calls `discard` for every clip that was prepared and will not play,
+and settles `done` without waiting for a `play` that ignores its signal. `isSpeaking` and
+`isCancelled` say where the queue is.
+
+## Phases
+
+```ts
+import { LIVE_VOICE_PHASES, type LiveVoicePhase } from 'stitchkit/voice'
+// 'opening' | 'idle' | 'hearing' | 'thinking' | 'speaking'
+```
+
+One vocabulary for every side of the conversation — the server that runs the agent and the
+page that shows the microphone — so a phase sent over the wire means the same on both ends.
+
+==============================================================================
+# API reference: `stitchkit/voice`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/voice`
+
+Isomorphic, dependency-free mechanics of a live voice conversation. Recognition, synthesis
+providers, the microphone and the player remain application-owned. See the
+[voice guide](../guide/voice.md).
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `SentenceCutter` | class | `next(text, final)` returns the sentences finished since the previous call of the reply streamed so far — never inside a fenced code block, never at `3.5` or `т. е.`; `reset()` starts a new turn |
+| `speakableText` | function | the visible text of Markdown without delimiters, link and image addresses, bare addresses, fenced code blocks or tables |
+| `SpeechQueue` / `SpeechQueueOptions` | class / _type_ | speak sentences in order with `lookahead` (default 1) synthesised while one plays; `close()` finishes the queue, `cancel()` aborts the playing sentence and every synthesis; a failed sentence is reported to `onError` and skipped |
+| `LIVE_VOICE_PHASES` / `LiveVoicePhase` | constant / _type_ | `opening`, `idle`, `hearing`, `thinking`, `speaking` |
+
+---

package/llms-full.txt

@@ -64,6 +64,7 @@ own, recorded as an ADR.
 | `stitchkit/tracking` | browser **and** server | evolving | visitor-tracking mechanics — `createTrackingClient`, the tab-shared outbox, the page-leave beacon, attribution, the contract factory; no event vocabulary, no React |
 | `stitchkit/tracking/server` | server (Bun or Node) | evolving | the decisions a tracking backend makes — dispositions, visit lease over an application-owned store, active intervals, presence; no database |
 | `stitchkit/release` | browser **and** server | evolving | a page follows the release it was built for — `createReleaseMarker` on the server, `createReleaseWatcher` in the browser, the `X-Build-Id` header and a socket event between them |
+| `stitchkit/voice` | browser **and** server | evolving | the mechanics of a live voice reply — `SentenceCutter`, `speakableText`, a `SpeechQueue` that synthesises ahead and stops on interruption, the conversation phases |
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
@@ -12633,6 +12634,88 @@ session query with `cache`; the generic starter does not invent a `getSession`
 endpoint or cookie vocabulary.
 
 
+==============================================================================
+# Guide: Voice  (docs/guide/voice.md)
+==============================================================================
+
+# Voice
+
+A live voice conversation with an agent repeats the same mechanics in every application
+that has one: the reply is cut into sentences while the model is still writing it, each
+sentence is stripped down to what can be said aloud, and a queue speaks them in order — and
+stops at once when the listener interrupts. `stitchkit/voice` is those mechanics, the same in
+the browser and on Bun or Node, with no dependencies. It is **evolving**.
+
+Speech recognition, synthesis providers, the microphone and the player stay with the
+application: the queue takes them as two functions.
+
+## Sentences while the reply streams
+
+```ts
+import { SentenceCutter, SpeechQueue, speakableText } from 'stitchkit/voice'
+
+const cutter = new SentenceCutter()
+
+for await (const text of reply) {           // the whole reply so far, on every chunk
+  for (const sentence of cutter.next(text, false)) say(sentence)
+}
+for (const sentence of cutter.next(finalText, true)) say(sentence) // the rest of the turn
+cutter.reset()                              // the next turn starts from zero
+```
+
+A sentence ends at `. ! ? …` (with any closing quote or bracket) followed by whitespace and a
+capital letter, a digit or an opening mark, or at a blank line between paragraphs. `3.5`,
+`т. е. так` and `e.g. this` are not cut; the end of the text is not the end of a sentence
+until `final`; nothing is cut inside a fenced code block, even one that is still open.
+
+## What is said
+
+`speakableText(markdown)` keeps what a reader sees and drops what cannot be said: headings,
+emphasis and list markers lose their delimiters, a link keeps its text and loses its
+address, and images, bare addresses, fenced code blocks and tables are dropped whole. It does
+not summarise. A sentence that was only code becomes `''`, and the queue ignores blank text.
+
+## Speaking in order, synthesising ahead
+
+```ts
+const queue = new SpeechQueue<Blob>({
+  prepare: (text, signal) => synthesise(text, { signal }),  // the whole clip
+  play: (clip, signal) => player.play(clip, { signal }),    // resolves when it has played
+  lookahead: 1,                                             // the default
+  onError: (error, text) => log.warn('sentence skipped', { error, text }),
+  discard: (clip) => release(clip),                         // prepared, never played
+})
+
+const say = (sentence: string) => queue.push(speakableText(sentence))
+
+// the turn is over: say what is queued, then `done` settles
+queue.close()
+// the listener interrupted: the playing sentence and every synthesis are aborted
+queue.cancel()
+await queue.done
+```
+
+While one sentence plays, up to `lookahead` more are already synthesising, so a synthesiser
+that returns the whole clip does not leave a gap the length of its synthesis between two
+sentences. `lookahead: 0` synthesises each sentence only after the previous one played.
+
+A sentence that fails to synthesise or to play is reported to `onError` and skipped; the
+queue goes on. `cancel()` aborts the signal of the sentence playing and of every synthesis in
+flight, drops the rest, calls `discard` for every clip that was prepared and will not play,
+and settles `done` without waiting for a `play` that ignores its signal. `isSpeaking` and
+`isCancelled` say where the queue is.
+
+## Phases
+
+```ts
+import { LIVE_VOICE_PHASES, type LiveVoicePhase } from 'stitchkit/voice'
+// 'opening' | 'idle' | 'hearing' | 'thinking' | 'speaking'
+```
+
+One vocabulary for every side of the conversation — the server that runs the agent and the
+page that shows the microphone — so a phase sent over the wire means the same on both ends.
+
+
 ==============================================================================
 # Guide: GeoIP  (docs/guide/geo.md)
 ==============================================================================
@@ -18300,6 +18383,21 @@ signal stay with the application. → ADR 0167 — [guide](../guide/release.md)
 
 ---
 
+## `stitchkit/voice`
+
+Isomorphic, dependency-free mechanics of a live voice conversation. Recognition, synthesis
+providers, the microphone and the player remain application-owned. See the
+[voice guide](../guide/voice.md).
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `SentenceCutter` | class | `next(text, final)` returns the sentences finished since the previous call of the reply streamed so far — never inside a fenced code block, never at `3.5` or `т. е.`; `reset()` starts a new turn |
+| `speakableText` | function | the visible text of Markdown without delimiters, link and image addresses, bare addresses, fenced code blocks or tables |
+| `SpeechQueue` / `SpeechQueueOptions` | class / _type_ | speak sentences in order with `lookahead` (default 1) synthesised while one plays; `close()` finishes the queue, `cancel()` aborts the playing sentence and every synthesis; a failed sentence is reported to `onError` and skipped |
+| `LIVE_VOICE_PHASES` / `LiveVoicePhase` | constant / _type_ | `opening`, `idle`, `hearing`, `thinking`, `speaking` |
+
+---
+
 ## `stitchkit/geo`
 
 Server-only managed GeoIP generations. Applications own database acquisition,

package/llms.txt

@@ -9,7 +9,7 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
 Load the slice for each entrypoint your code imports — `import … from 'stitchkit/server'` → `llms/server.txt`; the root `stitchkit` import → `llms/stitchkit.txt`. A slice holds that entrypoint's API reference section and the guide pages whose home it is; every guide lives in exactly one slice, and a slice that needs another's guide names it under "Also read". Each file is at most 50.0 KB; a longer one continues in numbered parts, each naming the next at its top. Moving across versions: load `llms/upgrading.txt` and the range slices it lists between your version and the target. `llms-full.txt` inlines everything; it is far larger than a context window, so do not read it whole.
 
 ## Entrypoint slices
-- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 15.3 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 35.0 KB → [llms/stitchkit.3.txt](llms/stitchkit.3.txt) 14.2 KB
+- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 15.5 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 35.0 KB → [llms/stitchkit.3.txt](llms/stitchkit.3.txt) 14.2 KB
 - **stitchkit/live**: [llms/live.txt](llms/live.txt) 21.2 KB
 - **stitchkit/react**: [llms/react.txt](llms/react.txt) 8.6 KB
 - **stitchkit/tools**: [llms/tools.txt](llms/tools.txt) 44.9 KB → [llms/tools.2.txt](llms/tools.2.txt) 26.3 KB → [llms/tools.3.txt](llms/tools.3.txt) 25.4 KB
@@ -44,6 +44,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/release**: [llms/release.txt](llms/release.txt) 8.9 KB
 - **stitchkit/tracking/server**: [llms/tracking-server.txt](llms/tracking-server.txt) 2.5 KB
 - **stitchkit/geo**: [llms/geo.txt](llms/geo.txt) 4.3 KB
+- **stitchkit/voice**: [llms/voice.txt](llms/voice.txt) 5.2 KB
 - **stitchkit/oauth**: [llms/oauth.txt](llms/oauth.txt) 6.7 KB
 - **stitchkit/google**: [llms/google.txt](llms/google.txt) 1.4 KB
 - **stitchkit/declaration**: [llms/declaration.txt](llms/declaration.txt) 16.0 KB
@@ -78,6 +79,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - [Multi-tenant](https://github.com/max-listov/stitchkit/blob/master/docs/guide/multi-tenant.md): a /tenants/:id/… scenario end-to-end — scopePrefixes, scoped client, extend
 - [Frontend integrations](https://github.com/max-listov/stitchkit/blob/master/docs/guide/frontend-integrations.md): React Router resource routes and a separate Vite development proxy
 - [React Query policy](https://github.com/max-listov/stitchkit/blob/master/docs/guide/react.md): request-local SSR clients, a browser singleton and ApiError retry rules
+- [Voice](https://github.com/max-listov/stitchkit/blob/master/docs/guide/voice.md): stitchkit/voice — sentences cut while a reply streams, the text a voice reads, a speech queue that synthesises ahead and stops on interruption
 - [GeoIP](https://github.com/max-listov/stitchkit/blob/master/docs/guide/geo.md): stitchkit/geo — a server-only managed reader, three observable states and last-known-good generation reloads
 - [Upgrading](https://github.com/max-listov/stitchkit/blob/master/docs/guide/upgrading.md): moving a project across stitchkit versions; how breaking changes are marked
 - [Project declaration](https://github.com/max-listov/stitchkit/blob/master/docs/guide/declaration.md): the optional machine-readable statement a repository makes about itself — identity, roles, build, requirements, release steps and the names of the values a deployment supplies

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.95.1",
+  "version": "0.95.2",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",
@@ -190,6 +190,10 @@
       "types": "./dist/entrypoints/geo.d.ts",
       "import": "./dist/entrypoints/geo.js"
     },
+    "./voice": {
+      "types": "./dist/entrypoints/voice.d.ts",
+      "import": "./dist/entrypoints/voice.js"
+    },
     "./oauth": {
       "types": "./dist/entrypoints/oauth.d.ts",
       "import": "./dist/entrypoints/oauth.js"