switchroom 0.16.22 → 0.16.24

package/telegram-plugin/format.ts

@@ -1,557 +1,53 @@
 /**
- * Telegram-flavored markdown→HTML rendering and chunking.
- *
- * Extracted from server.ts so tests can import these helpers without
- * triggering the bot startup side effects (env loading, token check,
- * grammy instantiation). server.ts re-exports the public API for
- * backwards compatibility with any external callers.
- *
- * Three pieces:
- *   - markdownToHtml + isLikelyTelegramHtml: convert model output to
- *     Telegram-safe HTML, preserving any embedded whitelisted Telegram
- *     HTML tags so the model can mix markdown bold with raw <b>/<i>/<a>.
- *   - splitHtmlChunks: split a long HTML message into <=4096-char chunks
- *     that preserve open/close tag balance and don't bisect HTML entities.
- *   - escapeHtml: the three-char escape used everywhere.
- */
-
-/**
- * Telegram-supported HTML tags. Anything outside this set is either
- * unrecognized (Telegram strips it) or actively dangerous (the API
- * rejects the message). Source: https://core.telegram.org/bots/api#html-style
- */
-export const TELEGRAM_HTML_TAGS = new Set([
-  'b', 'strong',
-  'i', 'em',
-  'u', 'ins',
-  's', 'strike', 'del',
-  'span', // requires class="tg-spoiler"
-  'tg-spoiler',
-  'a',
-  'tg-emoji',
-  'code',
-  'pre',
-  'blockquote',
-])
-
-/**
- * Heuristic: does this look like already-rendered Telegram HTML rather
- * than markdown waiting to be converted?
- *
- * Returns true when ALL the tags we find are recognized Telegram HTML
- * tags AND there's at least one of them AND the text doesn't also have
- * markdown-only syntax (** for bold, [text](url) for links). This is
- * conservative: if the model wrote `<div>foo</div>` (not Telegram HTML),
- * we treat it as markdown and escape it. If the model wrote `<b>foo</b>`,
- * we trust it.
- *
- * Critical: we strip markdown code spans and fenced code blocks BEFORE
- * scanning for tags, because the model frequently writes things like
- * `\`<b>tag</b>\`` (an inline code example showing literal HTML). Without
- * the strip, the heuristic would see `<b>` inside the code span and
- * misclassify the whole text as raw HTML.
- */
-export function isLikelyTelegramHtml(text: string): boolean {
-  // Strip fenced code blocks first (greedy, cross-line)
-  let scanText = text.replace(/```[\s\S]*?```/g, '')
-  // Then strip inline code spans (single backticks, no newlines)
-  scanText = scanText.replace(/`[^`\n]+`/g, '')
-
-  // If the stripped text contains markdown-only syntax (**bold**,
-  // [text](url), or markdown headings), the caller is writing markdown
-  // even if they ALSO sprinkled some <b> tags in. Treat as markdown.
-  if (/\*\*[^\n*]+\*\*/.test(scanText)) return false
-  if (/\[[^\]]+\]\([^)]+\)/.test(scanText)) return false
-  if (/^#{1,6}\s+/m.test(scanText)) return false
-
-  // Now count remaining HTML tags
-  const tagMatches = scanText.matchAll(/<\/?([a-z][a-z0-9-]*)\b[^>]*>/gi)
-  let count = 0
-  for (const m of tagMatches) {
-    const tag = m[1].toLowerCase()
-    if (!TELEGRAM_HTML_TAGS.has(tag)) {
-      // Found an unsupported tag — caller didn't intend Telegram HTML
-      return false
-    }
-    count++
-  }
-  return count > 0
-}
-
-// ---------------------------------------------------------------------------
-// Markdown table → Telegram HTML
-// ---------------------------------------------------------------------------
-
-/**
- * Parse a contiguous block of lines as a markdown table.
- *
- * A valid markdown table requires:
- *   - A header row:    | col | col |   (leading/trailing pipes optional)
- *   - A separator row: | --- | --- |   (cells are only dashes, colons, spaces)
- *   - At least one data row.
- *
- * The separator row is the discriminating signal — it prevents plain prose
- * lines that happen to contain a pipe (e.g. `echo foo | bar`) from being
- * mistaken for tables.
- *
- * Returns null when the block is not a valid table.
- */
-function parseMarkdownTable(lines: string[]): { headers: string[]; rows: string[][] } | null {
-  if (lines.length < 3) return null
-
-  // Separator line: cells contain only dashes, colons, and spaces.
-  const sepRe = /^\|?(?:[ \t]*:?-+:?[ \t]*\|)+[ \t]*:?-*:?[ \t]*\|?$/
-  // A pipe-delimited row: must contain at least one |
-  const rowRe = /\|/
-
-  // Find the separator line index (must be index 1 in this block)
-  if (!sepRe.test(lines[1].trim())) return null
-  // Double-check: the header row must also look like a table row
-  if (!rowRe.test(lines[0])) return null
-  // Must have at least one data row
-  if (lines.length < 3 || !rowRe.test(lines[2])) return null
-
-  const splitRow = (line: string): string[] =>
-    line
-      .replace(/^\|/, '')
-      .replace(/\|$/, '')
-      .split('|')
-      .map(c => c.trim())
-
-  const headers = splitRow(lines[0])
-  const rows: string[][] = []
-  for (let i = 2; i < lines.length; i++) {
-    if (!rowRe.test(lines[i])) break
-    rows.push(splitRow(lines[i]))
-  }
-
-  if (rows.length === 0) return null
-  return { headers, rows }
-}
-
-/**
- * Render a parsed markdown table as Telegram-compatible HTML.
- *
- * Branch rules:
- *   - ≤3 columns AND ≤6 rows → bullet list:
- *       Each row is one bullet. First column in <b>; subsequent columns
- *       appended as " — value".
- *   - otherwise → <pre> block with padded columns.
- */
-function renderTable(headers: string[], rows: string[][]): string {
-  const colCount = headers.length
-  const rowCount = rows.length
-
-  if (colCount <= 3 && rowCount <= 6) {
-    // Bullet list rendering
-    const bullets = rows.map(row => {
-      // Normalise row length to match header count (guard empty cells)
-      const cells = headers.map((_, i) => (row[i] ?? '').trim())
-      const key = escapeHtml(cells[0] || '—')
-      const rest = cells
-        .slice(1)
-        .filter(v => v !== '')
-        .map(v => ` — ${escapeHtml(v)}`)
-        .join('')
-      return `• <b>${key}</b>${rest}`
-    })
-    // Prepend header names as a label line when there are 2+ columns
-    const headerLine =
-      colCount >= 2
-        ? `<b>${headers.map(h => escapeHtml(h)).join(' / ')}</b>\n`
-        : ''
-    return headerLine + bullets.join('\n')
-  }
-
-  // Pre-block with padded columns
-  // Compute column widths across headers + all rows
-  const allRows = [headers, ...rows]
-  const widths = headers.map((_, ci) =>
-    Math.max(...allRows.map(r => (r[ci] ?? '').length))
-  )
-  const pad = (s: string, w: number) => s + ' '.repeat(Math.max(0, w - s.length))
-
-  const formatRow = (r: string[]) =>
-    headers.map((_, ci) => pad(r[ci] ?? '', widths[ci])).join('  ')
-
-  const sepLine = widths.map(w => '-'.repeat(w)).join('  ')
-
-  const lines = [
-    formatRow(headers),
-    sepLine,
-    ...rows.map(r => formatRow(r)),
-  ]
-  return `<pre>${escapeHtml(lines.join('\n'))}</pre>`
-}
-
-/**
- * Replace markdown table blocks in `text` with rendered HTML, storing the
- * rendered output in `store` and emitting `placeholderPrefix<n>\x00` tokens
- * so the rest of the pipeline does not re-process them.
- *
- * Tables are identified by their separator line (`| --- |`) which prevents
- * plain prose containing a pipe (e.g. `echo foo | bar`) from being mistaken
- * for a table. Fenced code blocks are extracted before this runs, so
- * table-looking rows inside ``` blocks are already protected.
- */
-function extractMarkdownTables(
-  text: string,
-  store: string[],
-  placeholderPrefix: string,
-): string {
-  const inputLines = text.split('\n')
-  const outputLines: string[] = []
-  let i = 0
-
-  while (i < inputLines.length) {
-    const line = inputLines[i]
-    if (!line.includes('|')) {
-      outputLines.push(line)
-      i++
-      continue
-    }
-
-    // Collect a run of pipe-containing lines as a candidate block
-    let j = i
-    while (j < inputLines.length && inputLines[j].includes('|')) {
-      j++
-    }
-    const block = inputLines.slice(i, j)
-
-    const parsed = parseMarkdownTable(block)
-    if (parsed) {
-      const tableLineCount = 2 + parsed.rows.length
-      const remainder = block.slice(tableLineCount)
-      const idx = store.length
-      store.push(renderTable(parsed.headers, parsed.rows))
-      outputLines.push(`${placeholderPrefix}${idx}\x00`)
-      for (const r of remainder) outputLines.push(r)
-      i = j
-    } else {
-      for (const b of block) outputLines.push(b)
-      i = j
-    }
-  }
-
-  return outputLines.join('\n')
-}
-
-/**
- * Convert markdown to Telegram-compatible HTML.
- * Handles bold, italic, code, code blocks, strikethrough, links.
- * Escapes HTML entities in plain text. Wraps file references in <code>.
- * Preserves embedded whitelisted Telegram HTML tags so the model can
- * mix markdown and raw HTML in the same message.
- */
-export function markdownToHtml(text: string): string {
-  // Smart pass-through: if the input is already valid Telegram HTML
-  // (every tag is in the supported list), trust the caller and return
-  // it unchanged.
-  if (isLikelyTelegramHtml(text)) {
-    return text
-  }
-
-  // First, extract code blocks and inline code to protect them from other transforms.
-  const codeBlocks: string[] = []
-  const BLOCK_PH = '\x00CODEBLOCK'
-  const INLINE_PH = '\x00CODEINLINE'
-
-  // Tables are extracted after code blocks so that table-looking rows inside
-  // fenced code blocks are already parked in codeBlocks placeholders and
-  // won't be touched. Rendered table HTML is stored alongside codeBlocks and
-  // uses the same placeholder so restoration happens in a single pass.
-  const TABLE_PH = '\x00TABLEBLOCK'
-
-  // Code blocks: ```lang\ncode\n```
-  let result = text.replace(/```(\w*)\n([\s\S]*?)```/g, (_m, lang: string, code: string) => {
-    const escaped = escapeHtml(code.replace(/\n$/, ''))
-    const cls = lang ? ` class="language-${lang}"` : ''
-    const idx = codeBlocks.length
-    codeBlocks.push(`<pre><code${cls}>${escaped}</code></pre>`)
-    return `${BLOCK_PH}${idx}\x00`
-  })
-
-  // Extract markdown tables after fenced code blocks are parked. Rendered
-  // HTML is stored in codeBlocks (shared store); TABLE_PH is a distinct
-  // prefix so the two restore regexes below can target each independently.
-  result = extractMarkdownTables(result, codeBlocks, TABLE_PH)
-
-  // Convert markdown headings (# / ## / ### ...) to bold lines on their
-  // own. Telegram has no <h1> tag, and rendering ## as plain text leaves
-  // ugly hash marks in the message.
-  result = result.replace(/^(#{1,6})\s+(.+?)\s*$/gm, (_m, _hashes, title: string) => {
-    return `**${title}**`
-  })
-
-  // Inline code: `code`
-  const inlineCodes: string[] = []
-  result = result.replace(/`([^`\n]+)`/g, (_m, code: string) => {
-    const idx = inlineCodes.length
-    inlineCodes.push(`<code>${escapeHtml(code)}</code>`)
-    return `${INLINE_PH}${idx}\x00`
-  })
-
-  // Telegram HTML tag pass-through. Extract any opening/closing tag
-  // whose name is in the whitelist into placeholders. The TEXT BETWEEN
-  // tags still flows through escapeHtml and the markdown conversions
-  // below, so `<b>**bold**</b>` and `<b>plain</b>` both work. Tags are
-  // restored verbatim at the very end.
-  const htmlTags: string[] = []
-  const HTMLTAG_PH = '\x00HTMLTAG'
-  const tagNamePattern = Array.from(TELEGRAM_HTML_TAGS).join('|')
-  const htmlTagRe = new RegExp(`</?(?:${tagNamePattern})\\b[^>]*>`, 'gi')
-  result = result.replace(htmlTagRe, (match: string) => {
-    const idx = htmlTags.length
-    htmlTags.push(match)
-    return `${HTMLTAG_PH}${idx}\x00`
-  })
-
-  // Escape HTML entities in remaining plain text
-  result = escapeHtml(result)
-
-  // Bold: **text** (must come before italic)
-  result = result.replace(/\*\*(.+?)\*\*/g, '<b>$1</b>')
-
-  // Italic: *text* (single asterisk, not preceded by another *)
-  result = result.replace(/(?<!\*)\*(?!\*)(.+?)(?<!\*)\*(?!\*)/g, '<i>$1</i>')
-
-  // Italic: _text_ (underscore form). Lookarounds guard snake_case,
-  // __double__, and word-internal underscores. Emoji codepoints are not
-  // \w, so emoji-leading/trailing italics like `_📥 queued_` work correctly.
-  result = result.replace(/(?<![\w_])_(?!_)([^_\n]+?)_(?![\w_])/g, '<i>$1</i>')
-
-  // Strikethrough: ~~text~~
-  result = result.replace(/~~(.+?)~~/g, '<s>$1</s>')
-
-  // Restore inline-code, code-block, and table-block placeholders ONLY
-  // AFTER bold/italic/strike have run. If the inline-code placeholder
-  // is restored before italic, an inline-code span containing asterisks
-  // (e.g. `\`size_t *p\``) gets matched by the italic regex on the
-  // restored `<code>...*p</code>` buffer and produces invalid HTML
-  // that Telegram rejects with 400 Bad Request — sending the caller
-  // into a `format: text` fallback for the rest of the chunk. Same
-  // fault class for code blocks containing `**` literals. See #415.
-  result = result.replace(new RegExp(`${escapeHtml(BLOCK_PH)}(\\d+)${escapeHtml('\x00')}`, 'g'), (_m, idx) => codeBlocks[Number(idx)])
-  result = result.replace(new RegExp(`${escapeHtml(TABLE_PH)}(\\d+)${escapeHtml('\x00')}`, 'g'), (_m, idx) => codeBlocks[Number(idx)])
-  result = result.replace(new RegExp(`${escapeHtml(INLINE_PH)}(\\d+)${escapeHtml('\x00')}`, 'g'), (_m, idx) => inlineCodes[Number(idx)])
-
-  // Links: [text](url). Two safety requirements here:
-  //
-  //  1. URL scheme allowlist. Unrestricted href accepts `javascript:` and
-  //     `data:` URIs; Telegram historically renders tg:// links directly
-  //     (opening another bot) which is a phishing primitive. Anything not
-  //     in the allowlist falls back to `#`.
-  //
-  //  2. Escape the URL before interpolating into the attribute. The HTML
-  //     tag extraction above parks whitelisted tags in \x00HTMLTAG<n>\x00
-  //     placeholders that get restored AFTER this replace. Without escaping
-  //     the href value, an adversarial `[text](x"></a><a href="evil">)` in
-  //     model output produces two <a> tags after placeholder restoration —
-  //     the second hijacks the visible link target. escapeAttr covers both
-  //     the placeholder-restoration attack and plain `"` breakout.
-  const ALLOWED_LINK_SCHEMES = /^(?:https?|mailto|tel|tg):/i
-  result = result.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_m, linkText: string, url: string) => {
-    const safe = ALLOWED_LINK_SCHEMES.test(url.trim()) ? url.trim() : '#'
-    return `<a href="${escapeHtml(safe)}">${linkText}</a>`
-  })
-
-  // File references: wrap filename.ext patterns in <code> tags.
-  // Lookbehind excludes `>` so we don't double-wrap filenames that are
-  // already inside a restored inline-code placeholder like
-  // `<code>settings.json</code>`. Without this, the regex matched the
-  // filename character immediately after the `>` of the opening <code>
-  // tag and re-wrapped it, producing `<code><code>settings.json</code></code>`.
-  result = result.replace(/(?<![<\/\w>])(\b[\w][\w.-]*\.(?:ts|js|py|rs|go|json|yaml|yml|toml|md|txt|sh|bash|zsh|css|html|xml|sql|env|cfg|conf|ini|log|csv|tsx|jsx|vue|svelte|rb|java|kt|swift|c|cpp|h|hpp|zig|asm|wasm|lock|mod|sum)\b)(?![^<]*>)/g, '<code>$1</code>')
-
-  // Restore preserved Telegram HTML tags (must run last so the file-ref
-  // regex above doesn't accidentally match characters inside our placeholders).
-  result = result.replace(new RegExp(`${escapeHtml(HTMLTAG_PH)}(\\d+)${escapeHtml('\x00')}`, 'g'), (_m, idx) => htmlTags[Number(idx)])
-
-  return result
-}
-
-export function escapeHtml(text: string): string {
-  // Also escape `"` so callers that interpolate into HTML attribute values
-  // don't need a second helper. Safe for tag-content use too.
-  return text
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-}
-
-/**
- * Last-resort renderer: turn (possibly malformed) Telegram HTML into
- * readable plain text. Used by the gateway's send/edit path when
- * Telegram rejects a chunk with a 400 "can't parse entities" /
- * "unsupported start tag" — i.e. our HTML prevention (markdownToHtml +
- * sanitizeForTelegram + splitHtmlChunks) let something through anyway.
- *
- * The caller resends the result with `parse_mode` UNSET, so the output
- * is literal text — we intentionally do NOT re-escape `< > &`. The goal
- * is "the agent's answer lands unformatted" instead of "the answer
- * silently vanishes" (visibility + always-on).
- *
- * Transforms, in order:
- *  1. `<a href="u">label</a>` → `label (u)` (or just `u` when label is
- *     empty or equals the href). href/label are themselves stripped +
- *     entity-decoded so we never emit nested markup.
- *  2. Block / break boundaries → newline: `<br>`, `</p>`, `</div>`,
- *     `</li>`, `</blockquote>`, `</pre>`. (These aren't Telegram-
- *     supported tags, but a markdown→HTML slip that emits one is a
- *     prime cause of the parse reject we're recovering from.)
- *  3. Strip every remaining tag.
- *  4. Decode the standard HTML entities Telegram uses.
- *  5. Collapse 3+ blank lines to 2; trim trailing per-line whitespace.
+ * Telegram rich-message formatting helpers.
+ *
+ * Since the Bot API 10.1 migration (#2669) every outbound message goes
+ * through `sendRichMessage` / `editMessageText({ markdown })` with raw GFM
+ * markdown. The old markdown→HTML engine, the HTML sanitizer, and the
+ * MarkdownV2 escaper are all gone — there is exactly ONE rendering path.
+ *
+ * What lives here now:
+ *   - repairEscapedWhitespace: format-agnostic repair of LLM-side JSON
+ *     escape bungles (literal `\n` etc.). Applied to raw text BEFORE it is
+ *     handed to the rich-message path.
+ *   - escapeMarkdown: escape GFM-special characters in DYNAMIC content
+ *     (filenames, user input, ids) so they render literally inside a
+ *     hand-built markdown card instead of being interpreted as formatting.
+ *   - splitMarkdownChunks: split a long markdown body into <=maxLen chunks
+ *     at safe boundaries (never mid code-fence, never mid table row),
+ *     defaulting maxLen to the rich-message cap of 32768.
+ *   - RICH_MESSAGE_MAX_CHARS: the rich-text wire cap (32768).
  */
-export function telegramHtmlToPlainText(html: string): string {
-  const decodeEntities = (s: string): string =>
-    s
-      .replace(/&amp;/g, '&')
-      .replace(/&lt;/g, '<')
-      .replace(/&gt;/g, '>')
-      .replace(/&quot;/g, '"')
-      .replace(/&#0*39;|&#x0*27;|&apos;/gi, "'")
-      .replace(/&nbsp;/g, ' ')
-      .replace(/&#(\d+);/g, (_m, d: string) => {
-        const cp = Number(d)
-        return Number.isFinite(cp) && cp > 0 && cp <= 0x10ffff
-          ? String.fromCodePoint(cp)
-          : _m
-      })
-      .replace(/&#x([0-9a-fA-F]+);/g, (_m, h: string) => {
-        const cp = parseInt(h, 16)
-        return Number.isFinite(cp) && cp > 0 && cp <= 0x10ffff
-          ? String.fromCodePoint(cp)
-          : _m
-      })
-
-  const stripTags = (s: string): string =>
-    decodeEntities(
-      s
-        .replace(/<\s*br\s*\/?\s*>/gi, '\n')
-        .replace(/<\/\s*(?:p|div|li|blockquote|pre|h[1-6])\s*>/gi, '\n')
-        .replace(/<[^>]*>/g, ''),
-    )
-
-  // 1. Anchors → "label (href)". Handle double/single/unquoted href.
-  const withPlainLinks = html.replace(
-    /<a\b[^>]*\bhref\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))[^>]*>([\s\S]*?)<\/a>/gi,
-    (_m, dq: string | undefined, sq: string | undefined, uq: string | undefined, label: string) => {
-      const href = decodeEntities((dq ?? sq ?? uq ?? '').trim())
-      const text = stripTags(label).trim()
-      if (!href) return text
-      return !text || text === href ? href : `${text} (${href})`
-    },
-  )
-
-  return stripTags(withPlainLinks)
-    .replace(/[ \t]+$/gm, '')
-    .replace(/\n{3,}/g, '\n\n')
-    .trim()
-}
-
-// ---------------------------------------------------------------------------
-// Output sanitizer — enforces fleet-wide Telegram formatting invariants
-// ---------------------------------------------------------------------------
 
 /**
- * Normalize outbound Telegram HTML text against well-known invariants.
- *
- * Runs AFTER markdownToHtml, just before the text is sent to the Bot API.
- * Conservative by design: only rewrites things that are universally wrong;
- * leaves semantic decisions (where to bold, link choice, list-vs-prose) to
- * the agent.
- *
- * Rules applied (in order):
- *  1. Strip markdown heading markers (`## Foo` → `<b>Foo</b>\n\n`).
- *     Headings that survived the markdown→HTML pass (e.g. when the input
- *     was already HTML and passed through isLikelyTelegramHtml) would render
- *     as ugly `## Foo` plain text. Convert to bold + blank line.
- *  2. Flatten nested bullet indentation: `\n  - sub` → `\n· sub`.
- *  3. Collapse 3+ consecutive blank lines to exactly 2.
- *  4. Strip trailing whitespace on each line.
- *  5. Ensure `<` `>` `&` inside `<code>` and `<pre>` blocks are
- *     HTML-escaped (idempotent: won't double-escape existing `&amp;` etc.).
- *
- * The function is idempotent: sanitize(sanitize(x)) === sanitize(x).
- * Content inside `<code>` / `<pre>` blocks is excluded from rules 1–4.
+ * Rich-message wire cap. Bot API 10.1 rich messages allow up to 32768
+ * UTF-8 characters (JSDoc-only in @grammyjs/types; no exported constant,
+ * so we hard-code it). The legacy plain-text `sendMessage`/`editMessageText`
+ * cap of 4096 does NOT apply on the rich path.
  */
-export function sanitizeForTelegram(text: string): string {
-  // ── Phase 1: extract <code> and <pre> blocks so rules 1-4 don't touch them.
-  //
-  // We capture the full tag with its content so we can round-trip correctly.
-  // Placeholders are non-printing control sequences that cannot appear in
-  // normal text.
-  const CODE_PH = '\x00SANCODE'
-  const PRE_PH = '\x00SANPRE'
-  const codeSegments: string[] = []
-  const preSegments: string[] = []
-
-  // Extract <pre>...</pre> blocks first (they may contain <code> inside).
-  let result = text.replace(/<pre>([\s\S]*?)<\/pre>/gi, (_m, inner: string) => {
-    const idx = preSegments.length
-    // Rule 5: escape unescaped < > & inside pre blocks.
-    preSegments.push(`<pre>${escapeUnescapedEntities(inner)}</pre>`)
-    return `${PRE_PH}${idx}\x00`
-  })
-
-  // Extract standalone <code>...</code> blocks (not nested inside <pre>).
-  result = result.replace(/<code([^>]*)>([\s\S]*?)<\/code>/gi, (_m, attrs: string, inner: string) => {
-    const idx = codeSegments.length
-    // Rule 5: escape unescaped < > & inside code spans.
-    codeSegments.push(`<code${attrs}>${escapeUnescapedEntities(inner)}</code>`)
-    return `${CODE_PH}${idx}\x00`
-  })
-
-  // ── Phase 2: apply text-level rules to the remaining (non-code) content.
-
-  // Rule 1: strip markdown heading markers that survived markdown→HTML pass.
-  // Matches lines starting with one or more `#` followed by a space.
-  // Preserves the heading text as bold + trailing blank line.
-  result = result.replace(/^(#{1,6}) +(.+?)\s*$/gm, (_m, _hashes, title: string) => {
-    return `<b>${title}</b>\n`
-  })
-
-  // Rule 2: flatten nested bullet indentation.
-  // Matches lines with a tab OR 2+ spaces at the start followed by - or *.
-  // A single tab is treated as sufficient indentation (standard 4-space equiv).
-  // Converts to a middle-dot bullet so the sub-detail survives as readable text.
-  result = result.replace(/^(?:\t+[ \t]*|[ \t]{2,})[*-] /gm, '· ')
-
-  // Rule 4: strip trailing whitespace on each line.
-  result = result.replace(/[ \t]+$/gm, '')
-
-  // Rule 3: collapse 3+ consecutive blank lines to exactly 2.
-  // A "blank line" is a line that contains only optional whitespace (already
-  // stripped above, but let's be safe).
-  result = result.replace(/(\n[ \t]*){3,}/g, '\n\n')
-
-  // ── Phase 3: restore placeholders.
-  result = result.replace(new RegExp(`${CODE_PH}(\\d+)\x00`, 'g'), (_m, idx) => codeSegments[Number(idx)])
-  result = result.replace(new RegExp(`${PRE_PH}(\\d+)\x00`, 'g'), (_m, idx) => preSegments[Number(idx)])
-
-  return result
-}
+export const RICH_MESSAGE_MAX_CHARS = 32768
 
 /**
- * Escape `<`, `>`, and `&` characters that are NOT already part of an HTML
- * entity or tag. Used inside `<code>` and `<pre>` content to correct
- * unescaped characters without double-escaping existing `&amp;`, `&lt;`, etc.
- *
- * Strategy: we walk the string and escape `&` only when it is not the start
- * of a valid entity (`&name;` or `&#digits;` or `&#xhex;`). We always escape
- * bare `<` and `>` because they cannot appear literally inside code content
- * that is correct Telegram HTML.
+ * Escape the GFM-markdown special characters so a dynamic value
+ * (a filename, an id, arbitrary user text) renders LITERALLY inside a
+ * hand-built markdown card instead of being parsed as formatting.
+ *
+ * Used wherever the old HTML cards called `escapeHtml(value)` while
+ * interpolating into `<b>…</b>` / `<code>…</code>`. The markdown
+ * equivalent is `**${escapeMarkdown(value)}**` / `` `${value}` `` (code
+ * spans don't need escaping — backtick content is literal).
+ *
+ * Escapes only the characters that trigger INLINE formatting in
+ * rich-markdown — backslash, `` ` ``, `*`, `_`, `~`, `=`, `[`, `]`, `|`.
+ * Deliberately does NOT escape `.` `-` `+` `#` `(` `)` `{` `}` `!` `>`:
+ * those are only meaningful at line-start (headings, lists, quotes) or in
+ * link/structure context, and escaping them mid-word (filenames like
+ * `foo.ts`, versions like `v1.2-rc`, URLs) would litter the output with
+ * visible backslashes. The backslash is escaped first so we never
+ * double-escape.
  */
-function escapeUnescapedEntities(inner: string): string {
-  // Escape bare & first: replace & that is NOT followed by a valid entity
-  // pattern. A valid entity is: &[a-zA-Z][a-zA-Z0-9]*; or &#[0-9]+; or &#x[0-9a-fA-F]+;
-  let out = inner.replace(/&(?!(?:[a-zA-Z][a-zA-Z0-9]*|#[0-9]+|#x[0-9a-fA-F]+);)/g, '&amp;')
-  // Escape bare < and > (they should never appear literally in code content)
-  out = out.replace(/</g, '&lt;')
-  out = out.replace(/>/g, '&gt;')
-  return out
+export function escapeMarkdown(text: string): string {
+  return text.replace(/([\\`*_~=\[\]|])/g, '\\$1')
 }
 
 /**
@@ -596,8 +92,8 @@ export function repairEscapedWhitespace(text: string): string {
   // inline span and expose the block's interior.
   //
   // Inline code uses `[^\`\n]+` (one or more non-backtick, non-newline chars)
-  // matching the same definition that markdownToHtml uses, so the masked regions
-  // are consistent with what the downstream pipeline treats as code.
+  // matching the same definition the chunker uses, so the masked regions are
+  // consistent with what the downstream pipeline treats as code.
   const codeMasks: string[] = []
 
   const masked = text
@@ -608,7 +104,7 @@ export function repairEscapedWhitespace(text: string): string {
       return `${CODE_MASK_PH}${idx}\x00`
     })
     // Inline code spans: at least one character between backticks, no embedded
-    // backtick or newline (matches markdownToHtml's /`([^`\n]+)`/ definition).
+    // backtick or newline.
     .replace(/`[^`\n]+`/g, (m) => {
       const idx = codeMasks.length
       codeMasks.push(m)
@@ -631,19 +127,33 @@ export function repairEscapedWhitespace(text: string): string {
 }
 
 // ---------------------------------------------------------------------------
-// Smart HTML chunking — preserves open/close tag boundaries
+// Markdown-aware chunking — never bisects a code fence or a table row
 // ---------------------------------------------------------------------------
 
 /**
- * Split HTML text into chunks that fit within maxLen, preserving tag integrity.
- * At split boundaries, open tags are closed and reopened in the next chunk.
- * Prefers splitting at \n\n, then \n, then spaces.
+ * Split a markdown body into chunks that each fit within `maxLen`.
+ *
+ * The rich-message path is raw GFM markdown, so chunk boundaries must not
+ * land inside a fenced code block (``` … ```) or in the middle of a table
+ * row — either produces a chunk Telegram renders wrong (an unterminated
+ * fence swallows the next chunk's text, a half table row drops cells).
+ *
+ * Strategy:
+ *   1. If the whole body fits, return it as one chunk.
+ *   2. Otherwise pick the largest safe cut <= maxLen, preferring a blank
+ *      line, then a single newline, then a space. The cut is then nudged
+ *      so it never falls inside an open fenced block or inside a line that
+ *      is part of a table (a line containing `|`).
+ *   3. An unsplittable region (a single code fence longer than maxLen) is
+ *      emitted whole rather than spun on forever — Telegram will reject an
+ *      oversized message, which is a louder, debuggable failure than an
+ *      infinite loop.
  */
-export function splitHtmlChunks(html: string, maxLen = 4000): string[] {
-  if (html.length <= maxLen) return [html]
+export function splitMarkdownChunks(text: string, maxLen = RICH_MESSAGE_MAX_CHARS): string[] {
+  if (text.length <= maxLen) return [text]
 
   const chunks: string[] = []
-  let rest = html
+  let rest = text
 
   while (rest.length > 0) {
     if (rest.length <= maxLen) {
@@ -651,7 +161,6 @@ export function splitHtmlChunks(html: string, maxLen = 4000): string[] {
       break
     }
 
-    // Find a good split point
     let cut = maxLen
     const paraIdx = rest.lastIndexOf('\n\n', maxLen)
     const lineIdx = rest.lastIndexOf('\n', maxLen)
@@ -665,129 +174,59 @@ export function splitHtmlChunks(html: string, maxLen = 4000): string[] {
       cut = spaceIdx
     }
 
-    // Defense-in-depth: refuse to split inside an HTML entity (&amp;,
-    // &lt;, &#x1f4a9;). If the cut would land mid-entity, back up to
-    // before the `&`. Telegram rejects messages with broken entities.
-    cut = backOffEntity(rest, cut)
-    // Same idea for a bisected tag: if the cut lands inside `<...>` (or
-    // between `<` and its closing `>`), back up to before the `<`.
-    // Otherwise we'd emit a chunk ending in `<a` or `<a href="..` which
-    // Telegram rejects outright.
-    cut = backOffOpenTag(rest, cut)
-    // Pathological: the tag-back-off retreated to 0 because `rest`
-    // begins with a tag and the nearest space we picked landed inside
-    // that tag. Fall back to the hard maxLen cut — that position lives
-    // in content past the opening tag (since the tag itself is at the
-    // start) so it won't bisect anything, and we make forward progress.
+    // Back off so the cut doesn't fall inside an open ``` fence.
+    cut = backOffOpenFence(rest, cut)
+    // Back off so the cut doesn't bisect a table row (a line with `|`).
+    cut = backOffTableRow(rest, cut)
+
     if (cut <= 0) {
-      cut = Math.min(maxLen, rest.length)
-      cut = backOffOpenTag(rest, cut)
-      // If even the maxLen cut bisects a tag, emit the whole remainder
-      // as one chunk rather than spin forever. Telegram will reject
-      // a 4k+ message before it rejects a split one, but this only
-      // fires on genuinely malformed input.
-      if (cut <= 0) cut = rest.length
+      // Could not find a safe boundary below maxLen — the region is one
+      // indivisible block (e.g. a single huge fenced block). Emit the
+      // whole remainder rather than loop forever.
+      chunks.push(rest)
+      break
     }
 
-    let segment = rest.slice(0, cut)
+    chunks.push(rest.slice(0, cut))
     rest = rest.slice(cut).replace(/^\n+/, '')
-
-    // Track open tags in this segment — we keep the FULL opening tag
-    // string (including attributes) so we can reopen `<a href="...">`
-    // in the next chunk without dropping the href.
-    const openTags = getOpenTags(segment)
-
-    // Close any open tags at the end of this chunk (by tag name)
-    for (let i = openTags.length - 1; i >= 0; i--) {
-      segment += `</${openTags[i].name}>`
-    }
-    chunks.push(segment)
-
-    // Reopen tags at the start of the next chunk, preserving attrs
-    if (rest.length > 0 && openTags.length > 0) {
-      const reopenPrefix = openTags.map(t => t.openTag).join('')
-      rest = reopenPrefix + rest
-    }
   }
 
   return chunks
 }
 
 /**
- * If `cut` lies inside an HTML entity (a `&...;` sequence), back it up to
- * just before the `&` so the chunk boundary doesn't bisect the entity.
+ * Count fenced-code delimiters (``` at line start) up to `cut`. If the
+ * count is odd, the cut lands inside an open fence — retreat to just before
+ * the opening fence so the boundary sits between complete blocks.
  */
-function backOffEntity(text: string, cut: number): number {
+function backOffOpenFence(text: string, cut: number): number {
   if (cut <= 0 || cut >= text.length) return cut
-  // Look backward up to 10 chars for an unterminated entity
-  const lookback = Math.max(0, cut - 10)
-  for (let i = cut - 1; i >= lookback; i--) {
-    const ch = text[i]
-    if (ch === ';') return cut // entity already closed before cut → safe
-    if (ch === '&') {
-      const closeIdx = text.indexOf(';', cut)
-      if (closeIdx !== -1 && closeIdx - i <= 10) {
-        // The entity spans the cut — back up to just before the `&`
-        return i
-      }
-      return cut
-    }
+  const before = text.slice(0, cut)
+  const fences = before.match(/^```/gm)
+  if (fences == null || fences.length % 2 === 0) return cut
+  // Odd number of fences → inside an open block. Find the opening fence and
+  // cut just before it (so the whole fenced block goes to the next chunk).
+  const lastFence = before.lastIndexOf('\n```')
+  if (lastFence <= 0) {
+    // Fence opens at the very start of `before` — can't retreat past it.
+    return 0
   }
-  return cut
+  return lastFence
 }
 
 /**
- * If `cut` lands inside an HTML tag (between `<` and the next `>`), back
- * up to before the `<`. Telegram rejects messages that contain a stray
- * `<` without a matching `>` (e.g. chunk ending `<a href="..`).
+ * If the cut lands on a line that contains a `|` (a markdown table row),
+ * retreat to the start of that line so we never emit a half table row.
  */
-function backOffOpenTag(text: string, cut: number): number {
+function backOffTableRow(text: string, cut: number): number {
   if (cut <= 0 || cut >= text.length) return cut
-  // Scan backward for the nearest `<` or `>` before the cut. If we hit
-  // `>` first the cut is outside any tag → safe. If we hit `<` first,
-  // check whether its closing `>` lies at or after the cut → bisected.
-  for (let i = cut - 1; i >= 0; i--) {
-    const ch = text[i]
-    if (ch === '>') return cut
-    if (ch === '<') {
-      const closeIdx = text.indexOf('>', i)
-      if (closeIdx >= cut) return i
-      return cut
-    }
+  const lineStart = text.lastIndexOf('\n', cut - 1) + 1
+  const nextNl = text.indexOf('\n', cut)
+  const lineEnd = nextNl === -1 ? text.length : nextNl
+  const line = text.slice(lineStart, lineEnd)
+  if (line.includes('|')) {
+    // Cut at the line start so the whole row moves to the next chunk.
+    return lineStart > 0 ? lineStart - 1 : 0
   }
   return cut
 }
-
-/** A tag still open at the end of a fragment. */
-interface OpenTag {
-  name: string       // lowercase tag name, e.g. "a", "tg-spoiler"
-  openTag: string    // full opening string with attrs, e.g. `<a href="...">`
-}
-
-/** Parse an HTML fragment and return the list of tags still open at the end. */
-function getOpenTags(html: string): OpenTag[] {
-  const tagStack: OpenTag[] = []
-  // Allow hyphens in tag names so `tg-spoiler` and `tg-emoji` parse as a
-  // single tag rather than `tg` plus stray text.
-  const tagRe = /<(\/?)([a-z][a-z0-9-]*)\b[^>]*>/gi
-  let m: RegExpExecArray | null
-  while ((m = tagRe.exec(html)) !== null) {
-    const full = m[0]
-    const isClosing = m[1] === '/'
-    const tagName = m[2].toLowerCase()
-    if (isClosing) {
-      // Closing tag — pop the most recent matching entry off the stack
-      for (let i = tagStack.length - 1; i >= 0; i--) {
-        if (tagStack[i].name === tagName) {
-          tagStack.splice(i, 1)
-          break
-        }
-      }
-    } else if (!full.endsWith('/>')) {
-      // Opening tag (not self-closing) — remember the full open string
-      // so reopen in the next chunk preserves attributes.
-      tagStack.push({ name: tagName, openTag: full })
-    }
-  }
-  return tagStack
-}