switchroom 0.21.8 → 0.21.9

package/telegram-plugin/format.ts

@@ -735,9 +735,12 @@ export function normalizePunctuation(text: string): string {
   // The dash rewrite runs per line so blockquote lines can be exempted:
   // `>` blockquotes are reserved for VERBATIM quoted text, and rewriting an
   // author's ` — ` to `, ` inside a quotation would corrupt what they quoted.
-  // The expandable-blockquote opener `**>` is a blockquote line too even though
-  // isBlockquoteLine (which keys on a leading `>`) doesn't catch the `**`
-  // prefix, so exempt it explicitly. Code spans and link hrefs stay masked
+  // A line opening with the LEGACY `**>` expandable-quote marker is a
+  // blockquote line too (the render path no longer emits `**>` — it is
+  // MarkdownV2-only syntax, see render.ts renderBlockquote — but legacy agent
+  // output still contains it and parse.ts repairs it into a real quote), so
+  // exempt it explicitly even though isBlockquoteLine (which keys on a leading
+  // `>`) doesn't catch the `**` prefix. Code spans and link hrefs stay masked
   // throughout, so their dashes are already protected on every line.
   const rewriteDashes = (line: string): string =>
     line
@@ -1414,7 +1417,12 @@ const INLINE_SPAN_PATTERNS: readonly RegExp[] = [
   /\*\*[^*\n]+\*\*/g, // bold
   /__[^_\n]+__/g, // underline
   /(?<![\w*])_[^_\n]+_(?![\w*])/g, // italic (snake_case-guarded)
-  /\[[^\]\n]*\]\([^)\n]*\)/g, // link [label](href)
+  // link `[label](href)` — and, via the optional leading `!`, Telegram's
+  // inline-entity form `![22:45 tomorrow](tg://time?unix=…&format=…)` /
+  // `![](tg://emoji?id=…)`. Without the `!?` the protected span would start at
+  // the `[`, so a cut could land in the one-character gap and strand the `!`
+  // on the previous chunk — silently demoting a date_time entity to a link.
+  /!?\[[^\]\n]*\]\([^)\n]*\)/g,
   /~~[^~\n]+~~/g, // strikethrough
   /\|\|[^|\n]+\|\|/g, // spoiler
 ]

package/telegram-plugin/package.json

@@ -31,7 +31,7 @@
     "@secretlint/core": "^12.2.0",
     "@secretlint/secretlint-rule-preset-recommend": "^12.2.0",
     "@xterm/headless": "^6.0.0",
-    "grammy": "^1.44",
+    "grammy": "^1.45",
     "mdast-util-from-markdown": "^2.0.2",
     "mdast-util-gfm": "^3.0.0",
     "micromark-extension-gfm": "^3.0.0",

package/telegram-plugin/render/code-segments.ts

@@ -73,6 +73,13 @@ export function splitCodeSegments(text: string): Segment[] {
 //   • bare autolinked URLs — `http(s)://…` and `www.…` runs Telegram auto-links.
 //   • GFM table rows — a table's structural pipes / empty cells (`|a||b|`) must
 //     survive; escaping inside a real table row corrupts the table.
+//   • inline-math `$…$` spans — Telegram's rich GFM parser typesets a `$…$`
+//     pair as a real mathematical_expression node (wire-verified 2026-08-13).
+//     A COMPACT span (whitespace-free inner run that is not a bare currency
+//     amount, e.g. `$x^2+y^2$`) is intentional math and must reach the wire
+//     byte-identical: no guard may escape its `$`, `^`, `_`, `*`, or `+`.
+//     Currency-shaped inners (`$5M-$`) are NOT protected, so the dollar-math
+//     guard still breaks accidental `$5M … $10M` currency pairs (#3252).
 // Everything else is prose and stays fully guarded. This is the sibling of the
 // code-span skip: a PROTECTED segment (`code: true`) is emitted verbatim.
 //
@@ -93,6 +100,19 @@ function isTableCandidateLine(line: string): boolean {
   return /^\s*\|/.test(line);
 }
 
+/** A compact `$…$` inline-math pair: opening `$`, a whitespace-free inner run
+ *  with no nested `$`, closing `$`. Anchored — tested at the scanner's current
+ *  position only. */
+const COMPACT_MATH_PAIR = /^\$([^\s$]+)\$/;
+
+/** A currency-shaped inner run: digits plus amount punctuation and magnitude
+ *  suffix letters only (`5M-`, `0.5`, `10,000`, `5+`). Such a run between two
+ *  `$` is a pair of ADJACENT currency amounts (`$5M-$10M`), not math — it must
+ *  stay guardable so the dollar-math guard can break the accidental pair. A
+ *  run containing any other character (`x^2+y^2`, `\alpha`, `a_b`) is treated
+ *  as intentional math and protected. */
+const CURRENCY_SHAPED_INNER = /^[0-9.,+\-kKmMbB]+$/;
+
 /** Find the [start, end) char ranges (relative to `text`) of GFM table blocks —
  *  maximal runs of 2+ consecutive `|`-leading lines that contain a delimiter
  *  row. Each returned range spans whole lines INCLUDING their trailing newline,
@@ -185,6 +205,19 @@ function splitProseProtected(text: string): Segment[] {
         continue;
       }
     }
+    // 4. Compact inline-math pair `$…$` — a supported Telegram construct
+    //    (mathematical_expression, wire-verified 2026-08-13) that must reach
+    //    the wire verbatim. Currency-shaped inners are NOT math (they are two
+    //    adjacent amounts like `$5M-$10M`) and stay guardable.
+    if (ch === "$") {
+      const m = COMPACT_MATH_PAIR.exec(text.slice(i));
+      if (m && !CURRENCY_SHAPED_INNER.test(m[1])) {
+        const end = i + m[0].length;
+        pushProtected(i, end);
+        i = end;
+        continue;
+      }
+    }
     i++;
   }
   if (plainStart < text.length) out.push({ code: false, text: text.slice(plainStart) });
@@ -193,10 +226,11 @@ function splitProseProtected(text: string): Segment[] {
 
 /** Split rendered markdown into prose / protected segments where a PROTECTED
  *  (`code: true`) segment is any content a guard must emit verbatim: code spans,
- *  fenced code blocks, markdown link destinations, bare autolinks, and GFM
- *  table rows. This is the link/table-aware superset of `splitCodeSegments` that
- *  all four #3252 guards route through. Prose segments (`code: false`) remain
- *  guardable (including a link's `[label]` text). Deterministic, linear-time. */
+ *  fenced code blocks, markdown link destinations, bare autolinks, GFM table
+ *  rows, and compact `$…$` inline-math spans. This is the link/table/math-aware
+ *  superset of `splitCodeSegments` that all the #3252 guards route through.
+ *  Prose segments (`code: false`) remain guardable (including a link's
+ *  `[label]` text). Deterministic, linear-time. */
 export function splitProtectedSegments(text: string): Segment[] {
   const out: Segment[] = [];
   for (const seg of splitCodeSegments(text)) {

package/telegram-plugin/render/dollar-math-guard.ts

@@ -29,6 +29,20 @@
 // a `$…$` pair if only the leading-`$digit` token is escaped — so we escape the
 // lot once the currency signal + 2-dollar threshold are met.
 //
+// ── INTENTIONAL math is exempt (wire-verified 2026-08-13) ─────────────────
+// Telegram's rich path renders a `$…$` pair as a native mathematical_expression
+// node, and intentional math (`$x^2+y^2$`) must reach the wire byte-identical —
+// an escaped `\$x^2+y^2\$` destroys a SUPPORTED construct. The discrimination
+// lives in `splitProtectedSegments` (code-segments.ts): a COMPACT math span
+// (whitespace-free inner, not currency-shaped) is a protected segment, so this
+// guard neither counts its `$`s toward the 2+ threshold nor escapes them.
+// Currency amounts always sit next to whitespace/prose (`$5M and $10M`) or have
+// a digits-and-punctuation-only inner (`$5M-$10M`), so #3252-class accidental
+// pairs remain fully guarded. Known residual: a SPACED math span (`$a + b$`)
+// is indistinguishable from currency prose and is not exempted — it is escaped
+// when the message also carries a currency signal, rendering as literal text
+// (legible, not broken).
+//
 // Idempotent (F5): the escape uses a negative-lookbehind (`(?<!\\)\$`) so an
 // already-escaped `\$` is never doubled to `\\$`. Running the guard twice (e.g.
 // the streaming path renders then this wrapper re-wraps) is a strict no-op the
@@ -100,7 +114,8 @@ const UNESCAPED_DOLLAR = /(?<!\\)\$/g;
  * them is digit-adjacent (a currency signal). When armed, EVERY unescaped prose
  * `$` is backslash-escaped so no two `$` can pair into a math span — this is
  * what closes the F3 trailing-`$` / `$.50` false-negatives. Code spans / fenced
- * blocks are never touched. Idempotent (F5) and deterministic.
+ * blocks AND compact intentional-math `$…$` spans (protected segments, see
+ * code-segments.ts) are never touched. Idempotent (F5) and deterministic.
  */
 export function guardDollarMath(text: string): string {
   if (!text.includes("$")) return text;

package/telegram-plugin/render/ir.ts

@@ -30,11 +30,21 @@
 //     highlight -> `==…==`  (Bot API 10.1 marked entity)
 //     code      -> `` `…` ``
 //     link      -> `[…](…)`
+//     tg-entity -> `![…](tg://…)`  (Bot API date_time / custom-emoji entity)
+//     raw       -> source bytes verbatim (never escaped) — footnote markers
+//                  `[^1]` and definition lines `[^1]: …`, which Telegram's
+//                  rich parser renders natively and escapeMarkdown would break
 //
 //   Block
 //     paragraph      -> children joined; blocks separated by "\n\n"
 //     heading        -> `#`…`######` line
-//     blockquote     -> `> …` (expandable === true -> `**> …` expandable blockquote)
+//     blockquote     -> `> …` on every line. `expandable === true` records that
+//                       the SOURCE carried the legacy `**> ` marker, but it is
+//                       NOT a distinct wire style: `**>` is MarkdownV2-only
+//                       syntax that the rich markdown path renders as literal
+//                       text (wire-verified 2026-08-13), so the renderer
+//                       degrades it to a plain quote. Authors wanting a real
+//                       collapsible use `<details><summary>…</summary>…</details>`.
 //     code-block     -> ```` ```lang … ``` ````
 //     list           -> line-per-item with `-`/`1.` markers
 //     thematic-break -> `---` thematic break
@@ -109,6 +119,40 @@ export interface LinkNode extends Pos {
   children: Inline[];
 }
 
+/** A Telegram rich-markdown INLINE entity written in mdast IMAGE position.
+ *  The "Rich Markdown style" grammar (https://core.telegram.org/bots/api,
+ *  quoted in `reference/telegram-formatting-guide.md`) lists exactly two:
+ *
+ *    ![](tg://emoji?id=5368324170671202286)                  custom emoji
+ *    ![22:45 tomorrow](tg://time?unix=1647531900&format=wDT) date_time
+ *
+ *  (the `date_time` MessageEntity is Bot API 9.5, March 1 2026; the rich-message
+ *  `RichTextDateTime` class is 10.1, June 11 2026 — both in the Bot API
+ *  changelog.) `parse.ts` folds ONLY those two `tg:` hrefs into this node;
+ *  every other image url keeps the historical demote-to-`plain` fallback,
+ *  because an http(s) `![](…)` is a Telegram MEDIA block — "Media can be
+ *  specified only as a separate block" (same doc) — not an inline entity, and
+ *  switchroom does not emit media blocks.
+ *
+ *  `label` is the DECODED alternative text (mdast `image.alt`, empty for the
+ *  emoji form); `href` is the `tg:` URL. Both are re-escaped on render, same
+ *  as `LinkNode`. */
+export interface TgEntityNode extends Pos {
+  type: "tg-entity";
+  label: string;
+  href: string;
+}
+
+/** Verbatim wire passthrough: the node's SOURCE bytes are already the exact
+ *  syntax Telegram's rich parser expects, so the renderer must emit them
+ *  unescaped (escapeMarkdown would corrupt them). Used for GFM footnote
+ *  reference markers (`[^1]`) and footnote definition lines (`[^1]: …`) —
+ *  both natively supported on the rich path (wire-verified 2026-08-13). */
+export interface RawNode extends Pos {
+  type: "raw";
+  text: string;
+}
+
 export type Inline =
   | PlainNode
   | BoldNode
@@ -118,7 +162,9 @@ export type Inline =
   | SpoilerNode
   | HighlightNode
   | CodeNode
-  | LinkNode;
+  | LinkNode
+  | TgEntityNode
+  | RawNode;
 
 // ---------------------------------------------------------------------------
 // Block nodes
@@ -139,7 +185,11 @@ export interface HeadingNode extends Pos {
 export interface BlockquoteNode extends Pos {
   type: "blockquote";
   children: Block[];
-  /** Telegram <blockquote expandable>. Always false in Increment 1 — see parse.ts. */
+  /** True when the source carried the LEGACY switchroom `**> ` expandable
+   *  marker (see parse.ts markExpandableQuotes). Records authoring intent
+   *  only: `**>` is MarkdownV2 syntax with no rich-markdown equivalent
+   *  (wire-verified 2026-08-13), so the renderer emits a plain `> ` quote
+   *  either way. */
   expandable: boolean;
 }
 

package/telegram-plugin/render/parse.ts

@@ -37,12 +37,18 @@
 //   own reading of the delimiters.
 //
 // Blockquote expandable handling:
-//   The IR carries `expandable: boolean` for Telegram's expandable blockquote
-//   (Bot API 10.1). GFM has no expandable marker; the switchroom render path
-//   emits `**> ` on the FIRST line of an expandable quote (`render.ts` /
-//   `reference/telegram-formatting-guide.md`). micromark does NOT understand
-//   `**> ` as a blockquote — the leading `**` makes the line a paragraph with
-//   an unclosed strong-emphasis run — so this module pre-transforms each
+//   The IR carries `expandable: boolean` for the LEGACY switchroom `**> `
+//   expandable-quote encoding. `**>` was believed to be the Bot API 10.1
+//   expandable-blockquote marker; wire probes (2026-08-13) proved it is
+//   MarkdownV2-only syntax that the rich markdown path renders as LITERAL
+//   `**>` text, so `render.ts` no longer emits it — an expandable node renders
+//   as a plain `> ` quote. Recognition here is kept as INPUT REPAIR: agent
+//   output (and Hindsight memories) trained on the old floor card still
+//   contains `**> ` quotes, and without this rewrite such a line would reach
+//   the wire as a broken literal-`**>` paragraph. micromark does NOT
+//   understand `**> ` as a blockquote — the leading `**` makes the line a
+//   paragraph with an unclosed strong-emphasis run — so this module
+//   pre-transforms each
 //   `**>` marker into a plain `  >` marker of IDENTICAL length (`**` → two
 //   spaces) before handing the text to mdast. Length preservation keeps every
 //   UTF-16 source offset (and therefore the never-lose-text round-trip
@@ -90,15 +96,35 @@ function slice(source: string, node: MdastNode): string {
   return source.slice(start, end);
 }
 
-/** The Bot API 10.1 expandable-blockquote marker: `**>` at the very start of
- *  a line (column 0). This is exactly what the render path emits
- *  (`render.ts` writes `**> ` on the first line of an expandable quote; see
- *  `reference/telegram-formatting-guide.md`). Matching only at column 0 keeps
+/** The LEGACY switchroom expandable-blockquote marker: `**>` at the very
+ *  start of a line (column 0). The render path no longer emits it (it is
+ *  MarkdownV2-only syntax, not rich markdown — see `render.ts`
+ *  renderBlockquote), but it is still RECOGNISED on input so a legacy `**> `
+ *  line is repaired into a real blockquote instead of shipping as literal
+ *  `**>` text. Matching only at column 0 keeps
  *  the length-preserving rewrite (`**` → two spaces) inside CommonMark's
  *  3-space blockquote-indent budget — allowing leading indent here would push
  *  the rewritten `  >` past 3 spaces and turn it into an indented code block. */
 const EXPANDABLE_MARKER_RE = /^\*\*>/;
 
+/** The `tg:` hrefs Telegram's "Rich Markdown style" grammar accepts in IMAGE
+ *  position — `![label](tg://…)`. Exactly two are documented
+ *  (https://core.telegram.org/bots/api): `tg://emoji?id=…` (custom emoji) and
+ *  `tg://time?unix=…[&format=…]` (the `date_time` entity). Deliberately an
+ *  ALLOWLIST rather than a bare `tg:` scheme test: an undocumented `tg://…` in
+ *  image position is not known-good syntax, and demoting it to literal text
+ *  (the historical behaviour) is safer than shipping a construct Telegram may
+ *  parse-reject. */
+const TG_INLINE_ENTITY_HREFS = ["tg://emoji", "tg://time"] as const;
+
+/** True when an mdast `image` url is one of the documented inline `tg:`
+ *  entities. Scheme/host comparison is case-insensitive (URLs are), but the
+ *  ORIGINAL href is what gets re-emitted — we never rewrite the author's bytes. */
+function isTgInlineEntityHref(href: string): boolean {
+  const h = href.toLowerCase();
+  return TG_INLINE_ENTITY_HREFS.some((base) => h === base || h.startsWith(`${base}?`));
+}
+
 /** Pre-transform expandable-blockquote markers so mdast can parse them as
  *  ordinary blockquotes, WITHOUT shifting any source offset. Each line that
  *  opens with `**>` has its two `*` characters replaced by two spaces
@@ -170,8 +196,30 @@ function foldInline(node: PhrasingContent, source: string): Inline {
         children: foldInlineChildren(node, source),
         ...pos(node),
       };
-    // Not in the palette (break, image, html, footnoteReference, …): keep the
-    // raw source text so no content is lost.
+    case "image": {
+      // GFM's image syntax doubles as Telegram's INLINE-entity syntax:
+      // `![22:45 tomorrow](tg://time?unix=…&format=…)` (date_time) and
+      // `![](tg://emoji?id=…)` (custom emoji). Fold those two into a
+      // `tg-entity` node so the renderer re-emits the construct verbatim
+      // instead of escaping the brackets to literal text. Every OTHER image
+      // url — notably the http(s) MEDIA forms, which Telegram accepts only as
+      // a SEPARATE block — falls through to the demote-to-`plain` default
+      // below, unchanged.
+      if (isTgInlineEntityHref(node.url)) {
+        return { type: "tg-entity", label: node.alt ?? "", href: node.url, ...pos(node) };
+      }
+      return { type: "plain", text: slice(source, node), ...pos(node) };
+    }
+    // GFM footnote reference marker (`[^1]`): natively supported by Telegram's
+    // rich markdown path (wire-verified 2026-08-13 — renders as the full
+    // superscript + anchor + reference_link machinery). The source bytes ARE
+    // the wire syntax, so fold to a `raw` node the renderer emits verbatim;
+    // a `plain` node would be escapeMarkdown'd (`\[^1\]`) and break the
+    // construct on the wire.
+    case "footnoteReference":
+      return { type: "raw", text: slice(source, node), ...pos(node) };
+    // Not in the palette (break, non-`tg:` image, html, …): keep the raw
+    // source text so no content is lost.
     default:
       return { type: "plain", text: slice(source, node), ...pos(node) };
   }
@@ -332,8 +380,19 @@ function foldBlock(
         ...pos(node),
       };
     }
-    // Not in the palette (html, definition, footnoteDefinition, …): degrade to
-    // a paragraph carrying the raw source slice so no content is dropped.
+    // GFM footnote DEFINITION (`[^1]: body`): natively supported on the wire
+    // (2026-08-13 probe — pairs with the reference marker into footer/anchor
+    // nodes). Emit the raw source slice VERBATIM via a `raw` inline: a `plain`
+    // fold would escapeMarkdown the `[`/`]` (`\[^1\]: body`) and orphan the
+    // reference.
+    case "footnoteDefinition":
+      return {
+        type: "paragraph",
+        children: [{ type: "raw", text: slice(source, node), ...pos(node) }],
+        ...pos(node),
+      };
+    // Not in the palette (html, definition, …): degrade to a paragraph
+    // carrying the raw source slice so no content is dropped.
     default:
       return {
         type: "paragraph",

package/telegram-plugin/render/render.ts

@@ -16,10 +16,11 @@
 // "HTML" }`. There is no HTML anywhere on the current outbound path (see
 // `reference/telegram-formatting-guide.md`). This renderer therefore targets
 // the ACTUAL contract: GFM markdown with the Bot API 10.1 extensions
-// documented in the formatting guide (expandable blockquote via `**> `,
-// spoiler via `||…||`, GFM pipe tables, etc). This module is NOT wired into
-// the live send path yet — that is a later increment, per the RFC's phased
-// rollout (rich rendering stays gated off by default until then).
+// documented in the formatting guide (spoiler via `||…||`, GFM pipe tables,
+// `<details>` collapsibles passed through as HTML, etc). NOTE: `**> ` is NOT
+// part of that contract — it is MarkdownV2-only syntax the rich path renders
+// as literal text (wire-verified 2026-08-13); this renderer no longer emits
+// it anywhere (see renderBlockquote).
 //
 // Round-trip note: `parse.ts` folds inline text (`PlainNode.text`,
 // `CodeNode.text`, `code-block` `text`, link `href`) into DECODED strings —
@@ -59,6 +60,14 @@ interface InlineCtx {
   inTableCell?: boolean;
 }
 
+/** Collapse any whitespace run containing a newline down to a single space.
+ *  Used for a `tg-entity` label: `![` … `]` must stay on ONE line or the
+ *  construct is not an entity any more. mdast decodes a soft line break inside
+ *  the alt text to a literal `\n`, which is exactly the case this flattens. */
+function collapseLabelBreaks(label: string): string {
+  return label.replace(/[ \t]*\r?\n[ \t\r\n]*/g, " ");
+}
+
 function renderInline(node: Inline, ctx: InlineCtx = {}): string {
   switch (node.type) {
     case "plain":
@@ -91,6 +100,25 @@ function renderInline(node: Inline, ctx: InlineCtx = {}): string {
       // Escape the href so a literal `)` in the URL can't terminate the
       // destination early and break the link (F3).
       return `[${renderInlineChildren(node.children, ctx)}](${escapeLinkHref(node.href)})`;
+    case "tg-entity":
+      // `![label](tg://time?unix=…&format=…)` / `![](tg://emoji?id=…)`.
+      // The label is PROSE (the alternative text Telegram shows when it can't
+      // render the entity), so it is escaped exactly like a `plain` node —
+      // without that, a label containing `]` or a formatting delimiter
+      // (`![see [22:45]](tg://time?…)`) closes the label early and smuggles
+      // raw bracket syntax past the renderer. A newline inside the label would
+      // split the construct across lines, so runs of whitespace spanning one
+      // are collapsed to a single space first. The href gets the same
+      // `escapeLinkHref` treatment a link's does (a no-op for the paren-free
+      // `tg:` URLs in practice, load-bearing if one ever carries a `)`).
+      return `![${escapeMarkdown(collapseLabelBreaks(node.label))}](${escapeLinkHref(node.href)})`;
+    case "raw":
+      // Verbatim wire passthrough — the source bytes ARE the wire syntax
+      // (footnote reference markers `[^1]` / definition lines `[^1]: …`,
+      // which Telegram's rich parser renders natively; escapeMarkdown would
+      // escape their `[`/`]` and break the construct — the exact bug this
+      // node type exists to prevent).
+      return node.text;
     default: {
       // Exhaustiveness guard — the IR union is closed; a new variant must be
       // handled above rather than silently dropped.
@@ -118,17 +146,20 @@ function prefixLines(text: string, prefix: string): string {
 
 function renderBlockquote(node: BlockquoteNode): string {
   const inner = renderBlocks(node.children);
-  // Bot API 10.1 expandable blockquote: `**> ` on the first quoted line.
-  // Plain blockquote: `> ` on every line.
-  if (node.expandable) {
-    const lines = inner.split("\n");
-    return lines
-      .map((line, i) => {
-        const marker = i === 0 ? "**> " : "> ";
-        return line.length > 0 ? `${marker}${line}` : marker.trimEnd();
-      })
-      .join("\n");
-  }
+  // Always a plain `> ` blockquote — including for `expandable: true` nodes.
+  //
+  // This renderer USED to emit `**> ` on the first line of an expandable
+  // quote, believing it to be the Bot API 10.1 expandable-blockquote marker.
+  // That belief was falsified by raw sendRichMessage wire probes (2026-08-13):
+  // `**>` is MarkdownV2 syntax; the rich markdown path renders it as a LITERAL
+  // `**> …` paragraph followed by a detached plain quote. The `expandable`
+  // flag is retained on the IR (parse.ts still repairs legacy `**>` input into
+  // a real blockquote instead of letting the literal `**>` reach the wire),
+  // but it is NOT a distinct wire style — the faithful degradation is a plain
+  // quote, which shows the full content. An author who wants a genuine
+  // collapsible writes `<details><summary>…</summary>…</details>`, which the
+  // rich path renders natively (typed `details` node, wire-verified) and which
+  // passes through this pipeline verbatim.
   return prefixLines(inner, "> ");
 }
 
@@ -299,6 +330,13 @@ export const SUPPORTED_INLINE = [
   "highlight",
   "code",
   "link",
+  // `![…](tg://time?…)` / `![…](tg://emoji?id=…)` — the two inline `tg:`
+  // entities in Telegram's Rich Markdown grammar. Emitted verbatim (label and
+  // href re-escaped); any OTHER image url stays a `plain` node.
+  "tg-entity",
+  // Verbatim passthrough for constructs whose SOURCE bytes are the wire syntax
+  // (footnote markers/definitions). Never escaped, never rewritten.
+  "raw",
 ] as const;
 
 export const SUPPORTED_BLOCK = [

package/telegram-plugin/render/unsupported-token-guard.ts

@@ -3,44 +3,55 @@
 //
 // ── Root cause ───────────────────────────────────────────────────────────
 // Assistant replies are composed by a model that habitually emits constructs
-// from OTHER surfaces (GitHub / Obsidian / LaTeX): caret highlight/superscript
-// `^…^`, footnote markers `[^1]`, and HTML `<details><summary>` collapsibles.
-// None of these are part of Telegram's rich markdown; they degrade to literal
-// carets, stray `[^1]`, and raw `<details>` tags on the reader's screen — the
-// worst kind of consistency failure (a broken glyph in chat). The resident
-// floor card tells the model not to emit them, but prompt discipline is not a
-// guarantee. This guard makes the repair deterministic at send time.
+// from OTHER surfaces (GitHub / Obsidian / LaTeX). Most of them turn out to be
+// natively supported by Telegram's rich markdown path (wire-verified
+// 2026-08-13 by sending raw `sendRichMessage` probes and reading back the
+// echoed `rich_message.blocks`):
+//   • `<details open><summary>S</summary>…</details>` → a real typed
+//     `details` node (native collapsible) — SUPPORTED, must pass through.
+//   • `$x^2+y^2$` → a `mathematical_expression` node — SUPPORTED (and
+//     protected from the sibling guards via `splitProtectedSegments`'s
+//     compact-math-span rule; see code-segments.ts).
+//   • footnotes `claim[^1]` + `[^1]: body` → full superscript/anchor/
+//     reference_link/footer machinery — SUPPORTED, must pass through.
+//   • `<sub>`/`<sup>`/`<u>`, `<aside>…<cite>…</cite></aside>`, `tg://time`
+//     links, `- [ ]` task lists — all SUPPORTED, never touched here.
+// (An earlier revision of this guard "repaired" `<details>` into a `**> `
+// expandable blockquote and deleted footnote reference markers. Both repairs
+// were built on a false belief: `**>` is MarkdownV2 syntax that the rich
+// markdown path renders as LITERAL `**>` paragraph text — the probe proved the
+// conversion turned a SUPPORTED construct into an UNSUPPORTED one. That logic
+// is deleted, not gated.)
+//
+// What genuinely does NOT render and still needs repair: the caret
+// highlight/superscript shorthand `^…^`. Telegram's rich markdown has no caret
+// syntax — the carets render literally on the reader's screen. The resident
+// floor card tells the model to use `<sup>…</sup>` instead, but prompt
+// discipline is not a guarantee; this guard makes the repair deterministic at
+// send time.
 //
 // ── What it repairs (deterministic, pure string transform) ─────────────────
-//   • `<details><summary>Title</summary>body</details>` → a Telegram EXPANDABLE
-//     blockquote (`**> Title` first line + `> …` continuation) — the native
-//     equivalent of a collapsible. `<details>` without a `<summary>` folds the
-//     whole body into an expandable blockquote. Any orphan `<details>` /
-//     `</details>` / `<summary>` tags left over are stripped.
-//   • `^highlight^` / `x^2^` caret pairs → the inner text, carets removed
-//     (Telegram has no highlight/superscript; the carets render literally).
-//   • Footnote reference markers `[^id]` → removed (Telegram has no footnotes).
-//     A footnote DEFINITION line `[^id]: …` is left alone (the `]:` lookahead).
+//   • `^highlight^` / `x^2^` caret pairs → the inner text, carets removed.
 //
 // ── What it deliberately does NOT touch ────────────────────────────────────
-//   • `$…$` math: already neutralised deterministically upstream by
-//     `guardDollarMath` (it backslash-escapes `$` so the pair can never typeset
-//     as math — the reader sees literal `$`). Re-processing `$` here would
-//     double-process and risk corrupting currency prose, so this guard leaves
-//     `$` untouched by design. Math repair is COVERED, just in the sibling guard.
+//   • `$…$` math: a compact math span is PROTECTED upstream (a `code: true`
+//     segment from `splitProtectedSegments`), and accidental currency `$` is
+//     owned by `guardDollarMath` (disjoint char set).
 //   • `~sub~` tilde pairs: the strikethrough/tilde trigger is owned by
 //     `guardAccidentalInlinePairs` (disjoint char set). This guard never
 //     inspects or inserts `~`.
 //   • `__underline__`: renders as BOLD in Telegram — legible, not broken — so it
 //     is left as-is (the floor card asks the model to avoid it, but there is no
 //     glyph-level failure to repair).
+//   • footnote markers `[^id]` / definitions `[^id]: …`: natively supported,
+//     pass through verbatim. (The caret regex below can never touch them: the
+//     `]` / `:` break the alphanumeric-only inner run.)
 //
-// Code spans / fenced blocks / link destinations / table rows are emitted
-// verbatim (shared `splitProtectedSegments`). A strict no-op for any body
-// without one of these tokens, and idempotent (running twice is a no-op the
-// second time — a repaired blockquote contains no `<details>`, a stripped caret
-// pair contains no `^`). Safe to compose once per send alongside the #3252
-// accidental-formatting guards.
+// Code spans / fenced blocks / link destinations / math spans / table rows are
+// emitted verbatim (shared `splitProtectedSegments`). A strict no-op for any
+// body without a caret pair, and idempotent (a stripped caret pair contains no
+// `^`). Safe to compose once per send alongside the #3252 accidental-formatting
+// guards.
 
 import { splitProtectedSegments } from "./code-segments.js";
 
@@ -56,69 +67,23 @@ import { splitProtectedSegments } from "./code-segments.js";
  *  permissive inner run the first two carets of `a^2+b^2=c^2` pair up (`^2+b^`)
  *  and get stripped, mangling the math; requiring the inner run to be pure
  *  alphanumerics means `^2+b^` never matches (the `+` breaks the run), so
- *  `a^2+b^2=c^2`, `2^8`, and `x^n` all pass through untouched. */
+ *  `a^2+b^2=c^2`, `2^8`, and `x^n` all pass through untouched. It also keeps
+ *  the guard off footnote markers `[^1]` (the `]` breaks the run). */
 const CARET_PAIR = /\^([A-Za-z0-9]+)\^/g;
 
-/** Footnote reference marker `[^id]` where the id is a short alphanumeric run
- *  (`[^1]`, `[^note]`, `[^ref]`) NOT immediately followed by `:` (which would
- *  make it a footnote DEFINITION line we leave intact). Removed entirely.
- *  Requiring the id to be 1–10 ALPHANUMERIC chars keeps this off regex-ish
- *  literals like `[^/]`, `[^\s]`, `[^-a-z]`, whose bodies contain punctuation
- *  and so never match. In-prose subscript-ish `array[^i]` outside a code span
- *  is a rare theoretical false positive (an `i` id matches); code spans are
- *  masked upstream by splitProtectedSegments so real code is safe, and prose
- *  that writes a literal `[^i]` reads as footnote noise anyway. */
-const FOOTNOTE_MARKER = /\[\^[A-Za-z0-9]{1,10}\](?!:)/g;
-
-/** `<details>…</details>` with an optional leading `<summary>…</summary>`.
- *  Dot-all via `[\s\S]`; non-greedy so adjacent blocks don't merge. */
-const DETAILS_BLOCK =
-  /<details[^>]*>\s*(?:<summary[^>]*>([\s\S]*?)<\/summary>)?([\s\S]*?)<\/details>/gi;
-
-/** Orphan collapsible tags left after DETAILS_BLOCK (malformed / unpaired). */
-const ORPHAN_TAGS = /<\/?(?:details|summary)[^>]*>/gi;
-
-/** Fold `title` + `body` into a Telegram expandable blockquote: the first
- *  emitted line carries the `**> ` marker (switchroom's expandable-blockquote
- *  encoding — see parse.ts), every subsequent line a plain `> `. */
-function toExpandableBlockquote(title: string, body: string): string {
-  const lines: string[] = [];
-  const t = title.trim();
-  if (t) lines.push(t);
-  for (const raw of body.split("\n")) {
-    const line = raw.trimEnd();
-    // Collapse leading/trailing blank lines but keep interior structure.
-    if (line.trim() === "" && lines.length === 0) continue;
-    lines.push(line);
-  }
-  // Trim trailing blanks.
-  while (lines.length > 0 && lines[lines.length - 1].trim() === "") lines.pop();
-  if (lines.length === 0) return "";
-  return lines
-    .map((line, i) => (i === 0 ? `**> ${line}` : `> ${line}`))
-    .join("\n");
-}
-
 /** Repair unsupported tokens in a single PROSE segment. */
 function repairProse(text: string): string {
-  let out = text;
-  out = out.replace(DETAILS_BLOCK, (_m, summary: string | undefined, body: string) =>
-    toExpandableBlockquote(summary ?? "", body ?? ""),
-  );
-  out = out.replace(ORPHAN_TAGS, "");
-  out = out.replace(CARET_PAIR, (_m, inner: string) => inner);
-  out = out.replace(FOOTNOTE_MARKER, "");
-  return out;
+  return text.replace(CARET_PAIR, (_m, inner: string) => inner);
 }
 
 /**
- * Neutralise Telegram-unrenderable tokens (`<details>`, `^…^`, `[^1]`) on the
- * FINAL rendered rich-markdown string. Code / links / tables are verbatim.
+ * Neutralise Telegram-unrenderable caret pairs (`^…^`) on the FINAL rendered
+ * rich-markdown string. Code / links / math spans / tables are verbatim.
  * Deterministic, idempotent, and a strict no-op absent any target token.
  */
 export function guardUnsupportedTokens(text: string): string {
-  // Cheap pre-check: nothing to do unless a target trigger char is present.
-  if (!/[\^]|<details|<\/details|<summary/i.test(text)) return text;
+  // Cheap pre-check: nothing to do unless a caret is present at all.
+  if (!text.includes("^")) return text;
   return splitProtectedSegments(text)
     .map((seg) => (seg.code ? seg.text : repairProse(seg.text)))
     .join("");