switchroom 0.16.29 → 0.16.46

package/telegram-plugin/uat/uat-driver.test.ts

@@ -0,0 +1,297 @@
+import { describe, expect, it } from "bun:test";
+import { decodeRichMessage } from "./driver.js";
+
+/**
+ * Direct unit tests for `decodeRichMessage` — the Bot API 10.1 rich-message
+ * decoder in the MTProto UAT driver. These are HOSTED (no live Telegram, no
+ * driver session): they feed hand-built Instant-View page trees whose shapes
+ * are grounded 1:1 against `@mtcute/tl@223.0.0` (the TL layer mtcute 0.30
+ * ships) and assert the flat `{ text, entities }` the decoder produces.
+ *
+ * They are the CI-verifiable floor under the live render scenario
+ * (`scenarios/jtbd-rich-formatting-render-dm.test.ts`), which can only run on
+ * the gated uat-host. If Telegram's real GFM parser ever emits a shape these
+ * fixtures don't model, the live scenario catches it; these tests pin the
+ * decoder's behavior for the shapes we DO model so a decoder regression reds
+ * in ordinary CI without needing the runner.
+ *
+ * TL shape sources (all from `@mtcute/tl@223.0.0` index.d.ts):
+ *   RichText:  textPlain{text:string} · textConcat{texts:RichText[]} ·
+ *              textBold/Italic/Underline/Strike/Fixed{text:RichText} ·
+ *              textUrl{text:RichText,url:string} · textEmail{text,email} ·
+ *              textMarked{text:RichText}  (no textSpoiler exists → spoiler)
+ *   PageBlock: pageBlockParagraph{text} · pageBlockPreformatted{text,language}
+ *              · pageBlockHeader/Subheader{text} · pageBlockBlockquote/
+ *              Pullquote{text,caption} · pageBlockList{items:PageListItem[]} ·
+ *              pageBlockOrderedList{items:PageListOrderedItem[]} ·
+ *              pageBlockTable{title,rows:PageTableRow[]} · pageBlockDivider
+ *   Items:     pageListItemText{text} · pageListItemBlocks{blocks} ·
+ *              pageListOrderedItemText{num,text} ·
+ *              pageListOrderedItemBlocks{num,blocks}
+ *   Table:     pageTableRow{cells:PageTableCell[]} ·
+ *              pageTableCell{header?,text?:RichText}
+ */
+
+// ── RichText builders (grounded shapes) ─────────────────────────────────────
+const plain = (text: string) => ({ _: "textPlain", text });
+const concat = (...texts: unknown[]) => ({ _: "textConcat", texts });
+const bold = (text: unknown) => ({ _: "textBold", text });
+const italic = (text: unknown) => ({ _: "textItalic", text });
+const underline = (text: unknown) => ({ _: "textUnderline", text });
+const strike = (text: unknown) => ({ _: "textStrike", text });
+const fixed = (text: unknown) => ({ _: "textFixed", text });
+const marked = (text: unknown) => ({ _: "textMarked", text }); // → spoiler
+const url = (text: unknown, u: string) => ({ _: "textUrl", text, url: u });
+const email = (text: unknown, e: string) => ({ _: "textEmail", text, email: e });
+
+// ── PageBlock builders ──────────────────────────────────────────────────────
+const para = (text: unknown) => ({ _: "pageBlockParagraph", text });
+const pre = (text: unknown, language = "") => ({
+  _: "pageBlockPreformatted",
+  text,
+  language,
+});
+const header = (text: unknown) => ({ _: "pageBlockHeader", text });
+const subheader = (text: unknown) => ({ _: "pageBlockSubheader", text });
+const blockquote = (text: unknown, caption: unknown = { _: "textEmpty" }) => ({
+  _: "pageBlockBlockquote",
+  text,
+  caption,
+});
+const list = (...items: unknown[]) => ({ _: "pageBlockList", items });
+const orderedList = (...items: unknown[]) => ({
+  _: "pageBlockOrderedList",
+  items,
+});
+const table = (title: unknown, rows: unknown[]) => ({
+  _: "pageBlockTable",
+  title,
+  rows,
+});
+const divider = () => ({ _: "pageBlockDivider" });
+
+const itemText = (text: unknown) => ({ _: "pageListItemText", text });
+const ordItemText = (num: string, text: unknown) => ({
+  _: "pageListOrderedItemText",
+  num,
+  text,
+});
+const row = (...cells: unknown[]) => ({ _: "pageTableRow", cells });
+const cell = (text: unknown, header = false) => ({
+  _: "pageTableCell",
+  ...(header ? { header: true } : {}),
+  text,
+});
+
+const rich = (...blocks: unknown[]) => ({ _: "richMessage", blocks });
+
+// A convenience matcher — find the single entity of a kind.
+const entOf = (
+  r: { entities: Array<{ kind: string }> },
+  kind: string,
+) => r.entities.filter((e) => e.kind === kind);
+
+describe("decodeRichMessage — non-rich guards", () => {
+  it("returns null for a non-richMessage value", () => {
+    expect(decodeRichMessage(undefined)).toBeNull();
+    expect(decodeRichMessage(null)).toBeNull();
+    expect(decodeRichMessage({ _: "message", blocks: [] })).toBeNull();
+    expect(decodeRichMessage({ _: "richMessage" })).toBeNull(); // no blocks[]
+  });
+
+  it("decodes an empty block list to empty output", () => {
+    expect(decodeRichMessage(rich())).toEqual({ text: "", entities: [] });
+  });
+});
+
+describe("decodeRichMessage — inline RichText marks (existing coverage)", () => {
+  it("bold / italic / code with exact spans", () => {
+    const r = decodeRichMessage(
+      rich(
+        para(
+          concat(
+            plain("a "),
+            bold(plain("bold")),
+            plain(" "),
+            italic(plain("it")),
+            plain(" "),
+            fixed(plain("code")),
+          ),
+        ),
+      ),
+    )!;
+    expect(r.text).toBe("a bold it code");
+    expect(entOf(r, "bold")[0]).toMatchObject({ offset: 2, length: 4, text: "bold" });
+    expect(entOf(r, "italic")[0]).toMatchObject({ text: "it" });
+    expect(entOf(r, "code")[0]).toMatchObject({ text: "code" });
+  });
+
+  it("text_link carries the destination url; email classified", () => {
+    const r = decodeRichMessage(
+      rich(
+        para(
+          concat(
+            url(plain("repo"), "https://example.com/x"),
+            plain(" "),
+            email(plain("a@b.com"), "a@b.com"),
+          ),
+        ),
+      ),
+    )!;
+    expect(entOf(r, "text_link")[0]).toMatchObject({
+      text: "repo",
+      url: "https://example.com/x",
+    });
+    expect(entOf(r, "email")[0]).toMatchObject({ text: "a@b.com" });
+  });
+
+  it("pageBlockPreformatted → a single pre entity with language", () => {
+    const r = decodeRichMessage(rich(pre(plain('echo "hi"'), "bash")))!;
+    expect(r.text).toBe('echo "hi"');
+    expect(entOf(r, "pre")[0]).toMatchObject({
+      offset: 0,
+      length: 9,
+      language: "bash",
+    });
+  });
+});
+
+describe("decodeRichMessage — strikethrough / underline / spoiler marks", () => {
+  it("textStrike → strikethrough, textUnderline → underline", () => {
+    const r = decodeRichMessage(
+      rich(para(concat(strike(plain("gone")), plain(" "), underline(plain("keep"))))),
+    )!;
+    expect(r.text).toBe("gone keep");
+    expect(entOf(r, "strikethrough")[0]).toMatchObject({ text: "gone", offset: 0 });
+    expect(entOf(r, "underline")[0]).toMatchObject({ text: "keep", offset: 5 });
+  });
+
+  it("textMarked → spoiler (TL 223 has no textSpoiler)", () => {
+    const r = decodeRichMessage(rich(para(concat(plain("psst "), marked(plain("secret"))))))!;
+    expect(r.text).toBe("psst secret");
+    expect(entOf(r, "spoiler")[0]).toMatchObject({ text: "secret", offset: 5 });
+  });
+});
+
+describe("decodeRichMessage — headings", () => {
+  it("pageBlockHeader / Subheader render as bold over the line", () => {
+    const r = decodeRichMessage(
+      rich(header(plain("Title")), subheader(plain("Sub")), para(plain("body"))),
+    )!;
+    expect(r.text).toBe("Title\nSub\nbody");
+    const bolds = entOf(r, "bold");
+    expect(bolds.map((e) => e.text).sort()).toEqual(["Sub", "Title"]);
+    expect(bolds.find((e) => e.text === "Title")).toMatchObject({ offset: 0, length: 5 });
+  });
+});
+
+describe("decodeRichMessage — blockquotes", () => {
+  it("pageBlockBlockquote → blockquote entity over the body", () => {
+    const r = decodeRichMessage(rich(blockquote(plain("quoted line"))))!;
+    expect(r.text).toBe("quoted line");
+    expect(entOf(r, "blockquote")[0]).toMatchObject({
+      offset: 0,
+      length: 11,
+      text: "quoted line",
+    });
+  });
+
+  it("blockquote caption follows on its own line, unstyled", () => {
+    const r = decodeRichMessage(rich(blockquote(plain("body"), plain("— src"))))!;
+    expect(r.text).toBe("body\n— src");
+    expect(entOf(r, "blockquote")[0]).toMatchObject({ text: "body" });
+    // caption is not part of the blockquote span
+    expect(entOf(r, "blockquote")[0].length).toBe(4);
+  });
+});
+
+describe("decodeRichMessage — lists", () => {
+  it("unordered list → bulleted lines, inline marks preserved", () => {
+    const r = decodeRichMessage(
+      rich(list(itemText(plain("first")), itemText(bold(plain("second"))))),
+    )!;
+    expect(r.text).toBe("• first\n• second");
+    expect(entOf(r, "bold")[0]).toMatchObject({ text: "second" });
+  });
+
+  it("ordered list → numbered lines using the wire .num label", () => {
+    const r = decodeRichMessage(
+      rich(
+        orderedList(
+          ordItemText("1", plain("alpha")),
+          ordItemText("2", plain("beta")),
+        ),
+      ),
+    )!;
+    expect(r.text).toBe("1. alpha\n2. beta");
+  });
+});
+
+describe("decodeRichMessage — tables", () => {
+  it("table rows join with ' | ', header cells emit bold", () => {
+    const r = decodeRichMessage(
+      rich(
+        table({ _: "textEmpty" }, [
+          row(cell(plain("H1"), true), cell(plain("H2"), true)),
+          row(cell(plain("a")), cell(plain("b"))),
+        ]),
+      ),
+    )!;
+    expect(r.text).toBe("H1 | H2\na | b");
+    const bolds = entOf(r, "bold").map((e) => e.text).sort();
+    expect(bolds).toEqual(["H1", "H2"]);
+    // body cells are not bold
+    expect(entOf(r, "bold").some((e) => e.text === "a")).toBe(false);
+  });
+
+  it("table title renders on its own line above the rows", () => {
+    const r = decodeRichMessage(
+      rich(table(plain("Scores"), [row(cell(plain("x")), cell(plain("y")))])),
+    )!;
+    expect(r.text).toBe("Scores\nx | y");
+  });
+});
+
+describe("decodeRichMessage — divider", () => {
+  it("pageBlockDivider → a literal rule line, no entity", () => {
+    const r = decodeRichMessage(rich(para(plain("above")), divider(), para(plain("below"))))!;
+    expect(r.text).toBe("above\n———\nbelow");
+    expect(r.entities).toEqual([]);
+  });
+});
+
+describe("decodeRichMessage — full torture tree (offsets stay UTF-16 correct)", () => {
+  it("mixed blocks decode with coherent offsets across the whole body", () => {
+    const r = decodeRichMessage(
+      rich(
+        header(plain("Report")),
+        para(
+          concat(
+            bold(plain("bold")),
+            plain(" "),
+            italic(plain("it")),
+            plain(" "),
+            strike(plain("old")),
+            plain(" "),
+            marked(plain("spoil")),
+          ),
+        ),
+        blockquote(plain("a wise quote")),
+        list(itemText(plain("one")), itemText(plain("two"))),
+        orderedList(ordItemText("1", plain("step"))),
+        divider(),
+        pre(plain("code()"), "js"),
+      ),
+    )!;
+    // Every entity's recorded text must equal the slice at its offset —
+    // the invariant that proves offset bookkeeping is coherent.
+    for (const e of r.entities) {
+      expect(r.text.slice(e.offset, e.offset + e.length)).toBe(e.text);
+    }
+    // Sanity on the kinds present.
+    const kinds = new Set(r.entities.map((e) => e.kind));
+    for (const k of ["bold", "italic", "strikethrough", "spoiler", "blockquote", "pre"]) {
+      expect(kinds.has(k)).toBe(true);
+    }
+  });
+});

package/telegram-plugin/voice-normalize-text.ts

@@ -0,0 +1,340 @@
+/**
+ * Speech normalization for OUTBOUND voice replies (voice-out).
+ *
+ * The problem: the agent's reply is Markdown-flavoured text. A TTS engine
+ * (Kokoro sidecar or OpenAI) reads it LITERALLY — so `~about 3`, `**bold**`,
+ * `` `code` ``, `# Heading`, `[label](https://…)`, and code fences all get
+ * spoken as "tilde", "asterisk asterisk", "backtick", "hash", or the raw URL
+ * read character-by-character. That is exactly the operator feedback: the
+ * voice is good but it pronounces the markup.
+ *
+ * `normalizeForSpeech` is a PURE string→string pass applied to the reply text
+ * BEFORE it is handed to any TTS engine. It replaces the older, partial
+ * `stripMarkdown` pass on the voice-out path (that one left `~`, code fences,
+ * tables, and arrows leaking through). It is deliberately conservative: the
+ * goal is natural prose, not aggressive rewriting — when in doubt it leaves
+ * real words alone.
+ *
+ * Documented behavioural choices (the "sensible defaults" the task allows):
+ *   - Inline code (`` `x` ``): the backticks are dropped, the CONTENT is
+ *     kept and spoken. Short inline code is usually a word/identifier the
+ *     listener wants to hear.
+ *   - Fenced code blocks (``` … ```): DROPPED entirely and replaced with a
+ *     short spoken placeholder ("(code block omitted)"). Reading a block of
+ *     code aloud is noise; a listener on a bike can't act on it anyway.
+ *   - Links `[text](url)`: spoken as just `text`; the URL is dropped. A bare
+ *     autolink `<https://…>` or a raw URL is replaced with "a link" so the
+ *     engine never spells out a URL character-by-character.
+ *   - `~` is DROPPED (not read as "tilde", not expanded to "about") — it is
+ *     ambiguous (strikethrough marker vs. approx) and dropping is the safest
+ *     choice that never mangles a real word.
+ *   - `->` / `=>` / `→` become the spoken word "to".
+ *   - A tiny, well-tested set of trivially-safe abbreviations is expanded
+ *     ("e.g." → "for example", "i.e." → "that is", "etc." → "and so on",
+ *     "vs" → "versus", "approx" → "approximately", "w/" → "with").
+ *     Anything ambiguous is left alone.
+ *
+ * Phase 2 pre-TTS naturalization (all conservative, number/token-guarded):
+ *   - Emoji & pictographs are dropped entirely (TTS would read their long
+ *     CLDR names); `:shortcode:` forms are dropped too. Whitespace collapses.
+ *   - Numbers, units & symbols are spoken: `%` → "percent", `$5.50` → "five
+ *     dollars fifty", `12x`/`12×` → "twelve times", `°C` → "degrees",
+ *     unit suffixes (`500ms`, `2h`, `10KB`, `100k`) expand to words, and the
+ *     `& + =` glue symbols become "and / plus / equals".
+ *   - A curated acronym set (CI, PR, API, URL, GPU, CPU, TTS, STT, HTTP,
+ *     JSON, SQL, UI) is spelled letter-by-letter; word-style acronyms
+ *     (NASA) are left alone.
+ *   - Clear time / date patterns: `12:45` → "twelve forty-five", ISO
+ *     `2026-07-01` → "July first two thousand twenty-six".
+ * Every phase-2 pass is guarded to fire only on a clear number+token so real
+ * identifiers (`my_var`, `class5`, `my5thing`) pass through untouched.
+ */
+
+/** Replace a fenced code block with a spoken placeholder. */
+const CODE_BLOCK_PLACEHOLDER = 'code block omitted'
+
+// ---------------------------------------------------------------------------
+// Number → words helpers (small, deterministic, English cardinal only).
+// Used by the numbers/units pass. Supports 0..999_999_999 which is far more
+// than any realistic spoken quantity; larger inputs are left as digits so we
+// never emit a wrong or truncated reading.
+// ---------------------------------------------------------------------------
+const ONES = [
+  'zero', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight',
+  'nine', 'ten', 'eleven', 'twelve', 'thirteen', 'fourteen', 'fifteen',
+  'sixteen', 'seventeen', 'eighteen', 'nineteen',
+]
+const TENS = [
+  '', '', 'twenty', 'thirty', 'forty', 'fifty', 'sixty', 'seventy', 'eighty',
+  'ninety',
+]
+
+/** Cardinal words for 0..999. */
+function belowThousand(n: number): string {
+  if (n < 20) return ONES[n]
+  if (n < 100) {
+    const t = TENS[Math.floor(n / 10)]
+    const o = n % 10
+    return o ? `${t}-${ONES[o]}` : t
+  }
+  const h = `${ONES[Math.floor(n / 100)]} hundred`
+  const rest = n % 100
+  return rest ? `${h} ${belowThousand(rest)}` : h
+}
+
+/** Cardinal words for a non-negative integer, or null if out of range. */
+function numberToWords(n: number): string | null {
+  if (!Number.isInteger(n) || n < 0 || n > 999_999_999) return null
+  if (n === 0) return 'zero'
+  const parts: string[] = []
+  const millions = Math.floor(n / 1_000_000)
+  const thousands = Math.floor((n % 1_000_000) / 1000)
+  const rest = n % 1000
+  if (millions) parts.push(`${belowThousand(millions)} million`)
+  if (thousands) parts.push(`${belowThousand(thousands)} thousand`)
+  if (rest) parts.push(belowThousand(rest))
+  return parts.join(' ')
+}
+
+/** Ordinal words for 1..31 (used for spoken dates). */
+const ORDINALS: Record<number, string> = {
+  1: 'first', 2: 'second', 3: 'third', 4: 'fourth', 5: 'fifth', 6: 'sixth',
+  7: 'seventh', 8: 'eighth', 9: 'ninth', 10: 'tenth', 11: 'eleventh',
+  12: 'twelfth', 13: 'thirteenth', 14: 'fourteenth', 15: 'fifteenth',
+  16: 'sixteenth', 17: 'seventeenth', 18: 'eighteenth', 19: 'nineteenth',
+  20: 'twentieth', 21: 'twenty-first', 22: 'twenty-second',
+  23: 'twenty-third', 24: 'twenty-fourth', 25: 'twenty-fifth',
+  26: 'twenty-sixth', 27: 'twenty-seventh', 28: 'twenty-eighth',
+  29: 'twenty-ninth', 30: 'thirtieth', 31: 'thirty-first',
+}
+
+const MONTHS = [
+  '', 'January', 'February', 'March', 'April', 'May', 'June', 'July',
+  'August', 'September', 'October', 'November', 'December',
+]
+
+/** Spoken form for a 4-digit year (e.g. 2026 → "two thousand twenty six"). */
+function yearToWords(y: number): string | null {
+  if (y < 1000 || y > 9999) return null
+  // 2000..2099 read as "two thousand …" which is the realistic range for
+  // these timestamps and reads naturally for TTS.
+  if (y >= 2000 && y < 2100) {
+    const lo = y % 100
+    const base = 'two thousand'
+    return lo ? `${base} ${belowThousand(lo)}` : base
+  }
+  // Generic "nineteen eighty-four" style for other centuries.
+  const hi = Math.floor(y / 100)
+  const lo = y % 100
+  const hiW = belowThousand(hi)
+  if (lo === 0) return `${hiW} hundred`
+  return `${hiW} ${belowThousand(lo)}`
+}
+
+/** Spoken minutes for a time-of-day (e.g. 45 → "forty-five", 5 → "oh five"). */
+function minutesToWords(mm: number): string {
+  if (mm === 0) return "o'clock"
+  if (mm < 10) return `oh ${ONES[mm]}`
+  return belowThousand(mm)
+}
+
+/** Number-unit suffixes: token suffix → { singular, plural } spoken unit. */
+const UNIT_MAP: Record<string, { s: string; p: string }> = {
+  ms: { s: 'millisecond', p: 'milliseconds' },
+  s: { s: 'second', p: 'seconds' },
+  sec: { s: 'second', p: 'seconds' },
+  min: { s: 'minute', p: 'minutes' },
+  m: { s: 'minute', p: 'minutes' },
+  h: { s: 'hour', p: 'hours' },
+  hr: { s: 'hour', p: 'hours' },
+  d: { s: 'day', p: 'days' },
+  kb: { s: 'kilobyte', p: 'kilobytes' },
+  mb: { s: 'megabyte', p: 'megabytes' },
+  gb: { s: 'gigabyte', p: 'gigabytes' },
+  tb: { s: 'terabyte', p: 'terabytes' },
+}
+
+/** Curated initialisms spoken letter-by-letter. Uppercase keys only. */
+const ACRONYMS = new Set([
+  'CI', 'PR', 'API', 'URL', 'GPU', 'CPU', 'TTS', 'STT', 'HTTP', 'JSON',
+  'SQL', 'UI',
+])
+
+/**
+ * Convert a Markdown/plain reply into clean text for a TTS engine.
+ * Pure and deterministic — same input always yields the same output.
+ */
+export function normalizeForSpeech(input: string): string {
+  if (!input) return ''
+  let s = input.replace(/\r\n?/g, '\n')
+
+  // 0. Emoji & pictographs → dropped entirely, then whitespace collapsed.
+  //    TTS reads an emoji as its long CLDR name ("grinning face"), which is
+  //    noise. We also drop `:shortcode:` forms so nothing is read as
+  //    "colon rocket colon". The shortcode form is matched narrowly
+  //    (:word: with letters/digits/_/- ) so real colon usage survives.
+  s = s.replace(
+    /[\u{1F000}-\u{1FAFF}\u{1F1E6}-\u{1F1FF}\u{2600}-\u{27BF}\u{2B00}-\u{2BFF}\u{FE00}-\u{FE0F}\u{200D}\u{2B50}\u{3030}\u{303D}\u{3297}\u{3299}\u{24C2}]/gu,
+    '',
+  )
+  s = s.replace(/:([a-z0-9][a-z0-9_+-]*):/gi, ' ')
+
+  // 1. Fenced code blocks first (```lang … ``` or ~~~ … ~~~) — drop the
+  //    whole block before any inline processing can see its contents.
+  s = s.replace(/(^|\n)[ \t]*(`{3,}|~{3,})[^\n]*\n[\s\S]*?\n[ \t]*\2[ \t]*(?=\n|$)/g, `$1${CODE_BLOCK_PLACEHOLDER}.`)
+  // An unterminated fence (opening ``` with no close) — drop to end.
+  s = s.replace(/(^|\n)[ \t]*(`{3,}|~{3,})[^\n]*\n[\s\S]*$/g, `$1${CODE_BLOCK_PLACEHOLDER}.`)
+
+  // 2. Images ![alt](url) → alt text (or drop when alt is empty).
+  s = s.replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
+
+  // 3. Links [text](url) → text ; drop the URL entirely.
+  s = s.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+
+  // 4. Autolinks <https://…> and bare URLs → "a link" (never spell a URL).
+  s = s.replace(/<https?:\/\/[^>\s]+>/gi, 'a link')
+  s = s.replace(/\bhttps?:\/\/[^\s)]+/gi, 'a link')
+
+  // 5. Inline code `x` → x (keep content, drop backticks). Run before the
+  //    generic backtick sweep so paired spans are handled cleanly.
+  s = s.replace(/`([^`\n]+)`/g, '$1')
+  // Any residual backticks → drop.
+  s = s.replace(/`/g, '')
+
+  // 6. Emphasis markers. Paired forms first (longest marker first), then
+  //    strip residual markup-by-construction doubles. A LONE `*` or `_` in
+  //    the middle of maths/words is left alone (see step 11).
+  s = s.replace(/\*\*\*(.+?)\*\*\*/g, '$1')
+  s = s.replace(/___(.+?)___/g, '$1')
+  s = s.replace(/\*\*(.+?)\*\*/g, '$1')
+  s = s.replace(/__(.+?)__/g, '$1')
+  s = s.replace(/\*(.+?)\*/g, '$1')
+  s = s.replace(/(?<![A-Za-z0-9])_(.+?)_(?![A-Za-z0-9])/g, '$1')
+  // Strikethrough ~~text~~ → text.
+  s = s.replace(/~~(.+?)~~/g, '$1')
+
+  // 7. Leading block markup, per line: headings, blockquotes, list markers.
+  //    List bullets/numbers become a natural sentence pause rather than a
+  //    spoken "dash" / "1 dot".
+  s = s.replace(/^[ \t]{0,3}#{1,6}[ \t]+/gm, '')
+  s = s.replace(/^[ \t]{0,3}>[ \t]?/gm, '')
+  s = s.replace(/^[ \t]{0,3}[-*+][ \t]+/gm, '')
+  s = s.replace(/^[ \t]{0,3}\d+[.)][ \t]+/gm, '')
+
+  // 8. Horizontal rules (---, ___, ***) on their own line → drop.
+  s = s.replace(/^[ \t]{0,3}([-_*])\1{2,}[ \t]*$/gm, '')
+
+  // 9. Table syntax: drop pipes and separator rows so tables read as prose.
+  s = s.replace(/^[ \t]*\|?[ \t]*:?-{2,}:?[ \t]*(\|[ \t]*:?-{2,}:?[ \t]*)+\|?[ \t]*$/gm, '')
+  s = s.replace(/\|/g, ' ')
+
+  // 10. Arrows → the spoken word "to".
+  s = s.replace(/[=-]>/g, ' to ')
+  s = s.replace(/[→⇒]/g, ' to ')
+
+  // 11. Stray tildes (approx / leftover markers) → drop. Ambiguous; dropping
+  //     is the safe choice that never mangles a real word.
+  s = s.replace(/~/g, '')
+
+  // 12. Trivially-safe abbreviation expansions (case-insensitive, only at a
+  //     word boundary followed by space/comma). Kept minimal on purpose.
+  s = s.replace(/\be\.g\.,?/gi, 'for example,')
+  s = s.replace(/\bi\.e\.,?/gi, 'that is,')
+  s = s.replace(/\betc\./gi, 'and so on')
+  s = s.replace(/\bapprox\.?(?=\s|$)/gi, 'approximately')
+  s = s.replace(/\bvs\.?(?=\s|$)/gi, 'versus')
+  s = s.replace(/\bw\/(?=\s)/gi, 'with ')
+
+  // 13. Dates & times (clear patterns only, run before the numbers pass so
+  //     the colon in HH:MM and the hyphens in ISO dates are consumed here).
+  //     ISO date YYYY-MM-DD → "Month Dayth Year".
+  s = s.replace(/\b(\d{4})-(\d{2})-(\d{2})\b/g, (m, y, mo, da) => {
+    const year = Number(y)
+    const month = Number(mo)
+    const day = Number(da)
+    if (month < 1 || month > 12 || day < 1 || day > 31) return m
+    const yw = yearToWords(year)
+    const ord = ORDINALS[day]
+    if (!yw || !ord) return m
+    return `${MONTHS[month]} ${ord} ${yw}`
+  })
+  //     Clock time HH:MM (24h ok) → spoken. Guarded by word boundaries so a
+  //     ratio like "3:2" or a bare number isn't caught (needs 2-digit MM).
+  s = s.replace(/\b([01]?\d|2[0-3]):([0-5]\d)\b/g, (m, hh, mm) => {
+    const h = Number(hh)
+    const min = Number(mm)
+    const hw = belowThousand(h)
+    if (min === 0) return `${hw} o'clock`
+    return `${hw} ${minutesToWords(min)}`
+  })
+
+  // 14. Numbers, units & symbols → spoken words. Each sub-pass is guarded so
+  //     it only fires on a clear number+token, never mid-word.
+  //     Currency: $5 / $5.50 → "five dollars" / "five dollars fifty".
+  s = s.replace(/\$(\d{1,9})(?:\.(\d{2}))?\b/g, (m, dollars, cents) => {
+    const dw = numberToWords(Number(dollars))
+    if (!dw) return m
+    const noun = Number(dollars) === 1 && !cents ? 'dollar' : 'dollars'
+    if (cents && cents !== '00') {
+      const cw = numberToWords(Number(cents))
+      return `${dw} ${noun} ${cw}`
+    }
+    return `${dw} ${noun}`
+  })
+  //     Percent sign → " percent".
+  s = s.replace(/(\d)\s*%/g, '$1 percent')
+  //     Temperature °C / °F → "degrees".
+  s = s.replace(/°\s*[CF]\b/g, ' degrees')
+  s = s.replace(/°/g, ' degrees')
+  //     Multiplier NN× / NNx → "NN times" (x only when glued to a number).
+  s = s.replace(/\b(\d{1,9})\s*[×x](?![a-z0-9])/gi, (m, n) => {
+    const w = numberToWords(Number(n))
+    return w ? `${w} times` : m
+  })
+  //     "100k" shorthand → "one hundred thousand" (k as thousands multiplier).
+  s = s.replace(/\b(\d{1,6})k\b/gi, (m, n) => {
+    const w = numberToWords(Number(n) * 1000)
+    return w ? w : m
+  })
+  //     Number + unit suffix → "<number> <unit>" (e.g. 500ms, 2h, 10KB).
+  //     Only when the suffix is a known unit glued directly to the number and
+  //     bounded by a non-letter (so "my5thing" / "class5" are never touched).
+  s = s.replace(
+    /\b(\d{1,9})(ms|sec|min|kb|mb|gb|tb|hr|s|m|h|d)(?![a-z])/gi,
+    (m, num, unitRaw) => {
+      const unit = UNIT_MAP[unitRaw.toLowerCase()]
+      if (!unit) return m
+      const n = Number(num)
+      const w = numberToWords(n)
+      if (!w) return m
+      return `${w} ${n === 1 ? unit.s : unit.p}`
+    },
+  )
+  //     Symbols between tokens: standalone & → and, + → plus, = → equals.
+  s = s.replace(/(\S)\s*\+\s*(\S)/g, '$1 plus $2')
+  s = s.replace(/\s=\s/g, ' equals ')
+  s = s.replace(/(\s)&(\s)/g, '$1and$2')
+  s = s.replace(/(\w)&(\w)/g, '$1 and $2')
+
+  // 15. Acronyms → letter-by-letter for a curated set of initialisms. Only a
+  //     standalone all-caps token that exactly matches the map is expanded;
+  //     word-style acronyms (NASA) and sub-tokens of larger words are left.
+  s = s.replace(/\b[A-Z]{2,5}\b/g, (tok) =>
+    ACRONYMS.has(tok) ? tok.split('').join(' ') : tok,
+  )
+
+  // 16. Collapse excessive punctuation the engine would over-emphasise.
+  s = s.replace(/([!?.]){2,}/g, '$1')
+
+  // 17. Whitespace → sentence flow. Blank lines become a sentence break so
+  //     paragraphs don't run together; everything else collapses to a single
+  //     space.
+  s = s.replace(/[ \t]*\n[ \t]*\n[ \t]*/g, '. ')
+  s = s.replace(/\s*\n\s*/g, ' ')
+  s = s.replace(/[ \t]{2,}/g, ' ')
+  // Tidy artifacts from the paragraph→". " substitution (". ." → ". ").
+  s = s.replace(/\.\s*\.(\s|$)/g, '.$1')
+  s = s.replace(/\s+([,.!?;:])/g, '$1')
+
+  return s.trim()
+}