switchroom 0.21.8 → 0.21.10

package/telegram-plugin/tests/render/parse.test.ts

@@ -218,17 +218,21 @@ describe("parse: nested inline", () => {
 });
 
 describe("parse: unsupported construct fallback", () => {
-  it("degrades a raw HTML block to plain text without dropping content", () => {
-    // Raw HTML blocks (mdast `html`) are outside the palette; they must
-    // survive as plain source text.
+  it("degrades an UNRECOGNISED raw HTML block to its content, markup dropped", () => {
+    // Raw HTML blocks (mdast `html`) are outside the palette. An unrecognised
+    // tag is NOT passed through verbatim: nothing establishes that Telegram's
+    // rich parser accepts `<div>`, and `isParseEntitiesError` (rich-send.ts)
+    // shows the wire can 400 with `unsupported start tag` — whose fallback
+    // resends the body as PLAIN TEXT, putting literal `<div class="x">` on the
+    // reader's screen. Degrade by type: markup dropped, content kept.
     const md = "<div class=\"x\">raw</div>";
     const doc = parse(md);
     const block = doc.blocks[0] as any;
     expect(block.type).toBe("paragraph");
     const plain = block.children[0];
     expect(plain.type).toBe("plain");
-    expect(plain.text).toBe(md);
-    expect(md.slice(plain.start, plain.end)).toBe(md);
+    expect(plain.text).toBe("raw");
+    expect(md.slice(plain.start, plain.end)).toBe("raw");
   });
 });
 
@@ -336,7 +340,7 @@ describe("parse: nested lists", () => {
   });
 });
 
-describe("expandable blockquote (Bot API 10.1 `**>` marker)", () => {
+describe("expandable blockquote (LEGACY switchroom `**>` marker — input repair only)", () => {
   it("parses a single-line `**>` quote into an expandable blockquote", () => {
     const md = "**> a collapsible line";
     const doc = parse(md);
@@ -374,10 +378,10 @@ describe("expandable blockquote (Bot API 10.1 `**>` marker)", () => {
   });
 
   it("only recognises the marker at column 0 (leading indent is not expandable)", () => {
-    // The renderer only ever emits `**>` at column 0; a leading-indented
-    // variant is deliberately NOT treated as an expandable quote (matching it
-    // would push the length-preserving rewrite past the 3-space blockquote
-    // budget into indented-code-block territory).
+    // The legacy encoding only ever placed `**>` at column 0; a
+    // leading-indented variant is deliberately NOT treated as an expandable
+    // quote (matching it would push the length-preserving rewrite past the
+    // 3-space blockquote budget into indented-code-block territory).
     const md = "   **> indented";
     const doc = parse(md);
     const bq = doc.blocks[0] as any;
@@ -391,3 +395,28 @@ describe("expandable blockquote (Bot API 10.1 `**>` marker)", () => {
     expect(doc.blocks[0].type).toBe("paragraph");
   });
 });
+
+describe("footnotes fold to verbatim `raw` nodes (native Telegram construct)", () => {
+  it("a footnote reference marker folds to a raw inline carrying its source bytes", () => {
+    // GFM only recognises a reference when a matching definition exists in
+    // the document (a lone `[^n1]` is ordinary text).
+    const doc = parse("claim[^n1] more\n\n[^n1]: body");
+    const para = doc.blocks[0] as Extract<Block, { type: "paragraph" }>;
+    const raw = para.children.find((c: Inline) => c.type === "raw") as
+      | Extract<Inline, { type: "raw" }>
+      | undefined;
+    expect(raw).toBeDefined();
+    expect(raw!.text).toBe("[^n1]");
+  });
+
+  it("a footnote definition folds to a paragraph with one raw inline (verbatim slice)", () => {
+    const doc = parse("[^n1]: body text");
+    const para = doc.blocks[0] as Extract<Block, { type: "paragraph" }>;
+    expect(para.type).toBe("paragraph");
+    expect(para.children).toHaveLength(1);
+    expect(para.children[0].type).toBe("raw");
+    expect((para.children[0] as Extract<Inline, { type: "raw" }>).text).toBe(
+      "[^n1]: body text",
+    );
+  });
+});

package/telegram-plugin/tests/render/render.test.ts

@@ -195,7 +195,10 @@ describe("render: block palette", () => {
   it("plain blockquote", () => {
     expect(render(parse("> quoted line"))).toBe("> quoted line");
   });
-  it("expandable blockquote uses **> on the first line", () => {
+  it("expandable IR flag renders as a PLAIN quote — the retired `**>` marker is never emitted", () => {
+    // `**>` is MarkdownV2-only syntax; the rich markdown path renders it as
+    // LITERAL `**>` text (wire-proved 2026-08-13 via raw sendRichMessage
+    // probes), so the renderer degrades an expandable node to a plain quote.
     const doc: Document = {
       blocks: [
         {
@@ -214,9 +217,10 @@ describe("render: block palette", () => {
         },
       ],
     };
-    expect(render(doc)).toBe("**> hidden gem");
+    expect(render(doc)).toBe("> hidden gem");
+    expect(render(doc)).not.toContain("**>");
   });
-  it("multi-line expandable blockquote continues with a plain > marker", () => {
+  it("multi-line expandable blockquote renders every line with a plain > marker", () => {
     const doc: Document = {
       blocks: [
         {
@@ -242,8 +246,9 @@ describe("render: block palette", () => {
       ],
     };
     const out = render(doc);
+    expect(out).not.toContain("**>");
     const lines = out.split("\n");
-    expect(lines[0]).toBe("**> line one");
+    expect(lines[0]).toBe("> line one");
     for (const line of lines.slice(1)) {
       expect(line.startsWith("> ") || line === ">").toBe(true);
     }

package/telegram-plugin/tests/render/rich-render.test.ts

@@ -5,6 +5,7 @@ import {
   renderOutbound,
   maybeRenderOutbound,
 } from "../../render/rich-render.js";
+import { guardAccidentalFormatting } from "../../rich-send.js";
 
 describe("parseRichRenderEnabled", () => {
   it("defaults ON when unset (escape hatch, not opt-in)", () => {
@@ -52,8 +53,10 @@ describe("maybeRenderOutbound", () => {
   it("default (env unset) routes through parse -> renderSafe", () => {
     const r = maybeRenderOutbound("**> collapsible", {} as NodeJS.ProcessEnv);
     expect(r.mode).toBe("markdown");
-    // The expandable blockquote round-trips back to the `**> ` marker.
-    expect(r.text).toContain("**> ");
+    // The legacy expandable marker is REPAIRED to a plain quote: `**>` is
+    // MarkdownV2-only syntax the rich path renders as literal text
+    // (wire-proved 2026-08-13), so the renderer must never re-emit it.
+    expect(r.text).toBe("> collapsible");
   });
 
   it("default preserves plain prose through the round-trip", () => {
@@ -84,15 +87,53 @@ describe("maybeRenderOutbound", () => {
       SWITCHROOM_RICH_RENDER: "maybe",
     } as NodeJS.ProcessEnv);
     expect(r.mode).toBe("markdown");
-    expect(r.text).toContain("**> ");
+    expect(r.text).toBe("> collapsible");
   });
 });
 
 describe("renderOutbound (flag-independent)", () => {
-  it("renders an expandable blockquote round-trip end to end", () => {
+  it("repairs a legacy `**>` quote to a plain quote end to end", () => {
     const r = renderOutbound("**> hidden line one\n> hidden line two");
     expect(r.mode).toBe("markdown");
-    expect(r.text.split("\n")[0]).toMatch(/^\*\*> /);
+    // One coherent quote, no retired marker: on the pre-fix renderer the
+    // first line came back as `**> hidden line one`, which Telegram rendered
+    // as LITERAL `**>` paragraph text (wire-proved 2026-08-13).
+    expect(r.text).not.toContain("**>");
+    expect(r.text.split("\n")[0]).toBe("> hidden line one");
+    expect(r.text).toContain("> hidden line two");
+  });
+
+  it("passes native constructs through: <details>, $math$, footnotes", () => {
+    // Wire-verified natives (2026-08-13) must survive parse -> renderSafe
+    // BYTE-IDENTICAL. On the pre-fix pipeline the footnote case failed:
+    // escapeMarkdown turned `[^n1]` into `\[^n1\]`, breaking the construct.
+    const details =
+      "<details open><summary>S</summary>\n\nbody\n\n</details>";
+    expect(renderOutbound(details).text).toBe(details);
+
+    const math = "inline $x^2+y^2$ done";
+    expect(renderOutbound(math).text).toBe(math);
+
+    const footnotes = "claim[^n1] more\n\n[^n1]: body text";
+    expect(renderOutbound(footnotes).text).toBe(footnotes);
+  });
+
+  it("a tg:// inline entity and a footnote survive TOGETHER in one message", () => {
+    // Cross-feature composition (#4683 x #4685): the `tg-entity` fold (mdast
+    // image position) and the footnote `raw` fold (footnoteReference /
+    // footnoteDefinition) land in the SAME foldInline/foldBlock walk — this
+    // pins that neither eats the other. On #4683 alone the footnote came back
+    // as `claim\[^n1\]`; on #4685 alone (pre-rebase) the entity came back as
+    // `!\[now\](tg://time?unix\=…)` literal text.
+    const combined =
+      "meet at ![now](tg://time?unix=1755000000&format=wDT) as promised[^n1]\n\n[^n1]: agreed yesterday";
+    expect(renderOutbound(combined).text).toBe(combined);
+
+    // Same pair inside ONE paragraph plus the guard seam on top: the composed
+    // wire body (renderOutbound then the richMessage guard, i.e. the full
+    // streamed send path) is still byte-identical.
+    const guarded = guardAccidentalFormatting(renderOutbound(combined).text);
+    expect(guarded).toBe(combined);
   });
 
   it("falls back to plain mode for oversized atomic content", () => {

package/telegram-plugin/tests/render/tg-entity.test.ts

@@ -0,0 +1,242 @@
+// Telegram inline `tg:` entities in mdast IMAGE position survive the whole
+// outbound pipeline.
+//
+// Bot API grammar (https://core.telegram.org/bots/api, "Rich Markdown style"):
+//
+//   ![](tg://emoji?id=5368324170671202286)                    custom emoji
+//   ![22:45 tomorrow](tg://time?unix=1647531900&format=wDT)   date_time
+//
+// (the `date_time` MessageEntity landed in Bot API 9.5, 2026-03-01; the
+// rich-message `RichTextDateTime` class in 10.1, 2026-06-11 — Bot API
+// changelog.) grammy 1.44.0 speaks 10.1, so the wire has accepted this since
+// #2669 — but the RENDER path escaped the brackets to literal text, so the
+// syntax was dead on the streamed send path.
+//
+// Two DISTINCT outbound surfaces are pinned here, because they do not share a
+// pipeline:
+//   - the STREAMED path (stream-controller.ts:272) → `renderOutboundChunks` →
+//     `parse → renderSafe`. This is the surface the escaping bug lived on.
+//   - the REPLY-TOOL path (outbound-send-path.ts) → `computeReplyChunks` →
+//     `richMessage()`, which NEVER runs the renderer — only the
+//     accidental-formatting guards. It was already correct; these tests pin it
+//     so a future guard can't silently start eating the syntax.
+
+import { describe, it, expect } from "vitest";
+import { parse } from "../../render/parse.js";
+import { renderSafe, SUPPORTED_INLINE } from "../../render/render.js";
+import { renderOutboundChunks } from "../../render/rich-render.js";
+import { guardAccidentalFormatting, richMessage } from "../../rich-send.js";
+import { computeReplyChunks } from "../../gateway/outbound-send-path.js";
+import { splitMarkdownChunks, RICH_MESSAGE_MAX_CHARS } from "../../format.js";
+import type { Inline } from "../../render/ir.js";
+
+/** The doc's own date_time example, verbatim. */
+const DATE_TIME = "![22:45 tomorrow](tg://time?unix=1647531900&format=wDT)";
+/** The doc's own custom-emoji example, verbatim (empty label). */
+const EMOJI = "![](tg://emoji?id=5368324170671202286)";
+
+/** parse → renderSafe, the streamed path's core. */
+const roundTrip = (md: string): string => renderSafe(parse(md), md).text;
+
+/** Flatten every inline node in the rendered IR of `md`. */
+function inlines(md: string): Inline[] {
+  const out: Inline[] = [];
+  const walk = (n: Inline): void => {
+    out.push(n);
+    for (const c of (n as { children?: Inline[] }).children ?? []) walk(c);
+  };
+  for (const b of parse(md).blocks) {
+    for (const n of (b as { children?: Inline[] }).children ?? []) walk(n);
+  }
+  return out;
+}
+
+describe("tg:// inline entities: parse → renderSafe round-trip", () => {
+  // THE bug this PR fixes: at HEAD the image node demoted to `plain` and
+  // `escapeMarkdown` backslash-escaped `[`, `]` and `=`, shipping
+  // `!\[22:45 tomorrow\](tg://time?unix\=…&format\=wDT)` — literal text, no
+  // entity. Byte-exact preservation is the whole contract.
+  it("preserves a date_time entity byte-exact", () => {
+    const body = `Meeting at ${DATE_TIME} sharp.`;
+    expect(roundTrip(body)).toBe(body);
+  });
+
+  it("preserves the empty-label custom-emoji entity byte-exact", () => {
+    expect(roundTrip(`hi ${EMOJI} there`)).toBe(`hi ${EMOJI} there`);
+  });
+
+  it("preserves a date_time entity with no `format` parameter", () => {
+    const body = "![22:45 tomorrow](tg://time?unix=1647531900)";
+    expect(roundTrip(body)).toBe(body);
+  });
+
+  it("folds the entity into a `tg-entity` IR node, not `plain`", () => {
+    const node = inlines(`x ${DATE_TIME}`).find((n) => n.type === "tg-entity");
+    expect(node).toMatchObject({
+      type: "tg-entity",
+      label: "22:45 tomorrow",
+      href: "tg://time?unix=1647531900&format=wDT",
+    });
+  });
+
+  it("survives inside a blockquote, a heading, a list item and a table cell", () => {
+    for (const body of [
+      `> when: ${DATE_TIME}`,
+      `## Due ${DATE_TIME}`,
+      `- due ${DATE_TIME}`,
+      `| when | who |\n| --- | --- |\n| ${DATE_TIME} | me |`,
+    ]) {
+      expect(roundTrip(body)).toContain(DATE_TIME);
+    }
+  });
+
+  it("matches the `tg:` href case-insensitively (URL schemes are)", () => {
+    const body = "![t](TG://Time?unix=1647531900)";
+    // Folded as an entity, and the author's ORIGINAL bytes are re-emitted —
+    // the parser never rewrites the href.
+    expect(inlines(body).some((n) => n.type === "tg-entity")).toBe(true);
+    expect(roundTrip(body)).toBe(body);
+  });
+
+  it("lists `tg-entity` in the renderer's construct allowlist", () => {
+    expect(SUPPORTED_INLINE).toContain("tg-entity");
+  });
+});
+
+describe("tg:// inline entities: label escaping (no bracket breakout)", () => {
+  // A model-authored label carrying `]` would close the label early and
+  // smuggle raw bracket syntax past the renderer if the label were re-emitted
+  // undecorated. It is prose, so it gets `escapeMarkdown` exactly like a
+  // `plain` node.
+  it("escapes brackets in the label instead of letting them close it early", () => {
+    const out = roundTrip("![see [22:45]](tg://time?unix=1&format=t)");
+    expect(out).toBe("![see \\[22:45\\]](tg://time?unix=1&format=t)");
+    // No BARE `]` before the destination — the only unescaped one closes the label.
+    expect(out.slice(0, out.indexOf("](")).includes("\\]")).toBe(true);
+  });
+
+  it("escapes emphasis delimiters in the label", () => {
+    expect(roundTrip("![a*b_c~d](tg://time?unix=1&format=t)")).toBe(
+      "![a\\*b\\_c\\~d](tg://time?unix=1&format=t)",
+    );
+  });
+
+  it("collapses a soft line break in the label so the construct stays on one line", () => {
+    const out = roundTrip("![22:45\ntomorrow](tg://time?unix=1&format=t)");
+    expect(out).toBe("![22:45 tomorrow](tg://time?unix=1&format=t)");
+    expect(out).not.toContain("\n");
+  });
+});
+
+describe("tg:// inline entities: no regression of the image demotion", () => {
+  // Deliberate, unchanged: an http(s) `![](…)` is a Telegram MEDIA block —
+  // "Media can be specified only as a separate block" (Rich Markdown style) —
+  // not an inline entity, and switchroom emits no media blocks. It keeps
+  // degrading to escaped literal text.
+  it("still degrades an http(s) image link to escaped plain text", () => {
+    expect(roundTrip("![alt](https://x.example/y.png)")).toBe(
+      "!\\[alt\\](https://x.example/y.png)",
+    );
+  });
+
+  it("still degrades an UNDOCUMENTED tg:// image href to escaped plain text", () => {
+    // The allowlist is deliberate: only `tg://time` and `tg://emoji` are
+    // documented in image position, so anything else stays literal rather than
+    // shipping syntax Telegram may parse-reject.
+    expect(roundTrip("![t](tg://photo?id=1)")).toBe("!\\[t\\](tg://photo?id\\=1)");
+    expect(roundTrip("![t](tg://user?id=1)")).toBe("!\\[t\\](tg://user?id\\=1)");
+  });
+
+  it("leaves an ordinary `[label](tg://user?id=…)` mention link alone", () => {
+    const body = "ping [Ken](tg://user?id=123456789)";
+    expect(roundTrip(body)).toBe(body);
+  });
+});
+
+describe("tg:// inline entities: code context stays literal", () => {
+  it("keeps the syntax verbatim inside an inline code span", () => {
+    const body = "use `![22:45](tg://time?unix=1&format=t)` for that";
+    expect(roundTrip(body)).toBe(body);
+    // and it is a `code` node, NOT a folded entity
+    expect(inlines(body).some((n) => n.type === "tg-entity")).toBe(false);
+  });
+
+  it("keeps the syntax verbatim inside a fenced code block", () => {
+    const body = "```\n![22:45](tg://time?unix=1&format=t)\n```";
+    expect(roundTrip(body)).toBe(body);
+    expect(inlines(body).some((n) => n.type === "tg-entity")).toBe(false);
+  });
+});
+
+describe("tg:// inline entities: the accidental-formatting guards are a no-op", () => {
+  // `guardAccidentalFormatting` is the universal seam (installed as a grammy
+  // API transformer in shared/bot-runtime.ts), so it runs over EVERY outbound
+  // body — rendered or hand-built card alike. Its documented trigger set
+  // (`_ * > . ~ == || $ #`) does not intersect this syntax, but nothing
+  // asserted that until now.
+  const bodies = [
+    `Meeting at ${DATE_TIME} sharp.`,
+    `${DATE_TIME} at the very start of the line`,
+    EMOJI,
+    `- due ${DATE_TIME}\n- and ${DATE_TIME}`,
+    `> when: ${DATE_TIME}`,
+    `| when |\n| --- |\n| ${DATE_TIME} |`,
+    "![see \\[22:45\\]](tg://time?unix=1&format=t)",
+  ];
+
+  it("leaves every tg:// entity body byte-identical", () => {
+    for (const body of bodies) expect(guardAccidentalFormatting(body)).toBe(body);
+  });
+
+  it("is idempotent over the rendered form too", () => {
+    for (const body of bodies) {
+      const rendered = roundTrip(body);
+      expect(guardAccidentalFormatting(rendered)).toBe(rendered);
+    }
+  });
+});
+
+describe("tg:// inline entities: live outbound seams", () => {
+  it("survives the STREAMED seam (renderOutboundChunks)", () => {
+    const body = `Standup starts ${DATE_TIME}.`;
+    const pieces = renderOutboundChunks(body);
+    expect(pieces).toHaveLength(1);
+    expect(pieces[0].mode).toBe("markdown");
+    expect(pieces[0].text).toBe(body);
+  });
+
+  it("survives the REPLY-TOOL seam (computeReplyChunks → richMessage)", () => {
+    // This surface never touches the renderer — it is guards-only. Pinned so a
+    // future guard cannot start escaping the syntax unnoticed.
+    const body = `Standup starts ${DATE_TIME}.`;
+    const chunks = computeReplyChunks({
+      effectiveText: body,
+      literalText: false,
+      limit: RICH_MESSAGE_MAX_CHARS,
+      chunkMode: "length",
+    });
+    expect(chunks.map((c) => richMessage(c).markdown).join("")).toContain(DATE_TIME);
+  });
+});
+
+describe("tg:// inline entities: chunk boundaries never bisect the construct", () => {
+  // `INLINE_SPAN_PATTERNS`' link pattern used to start at the `[`, leaving the
+  // leading `!` outside the protected span: a cut inside the construct
+  // retreated only to the `[`, stranding `!` on the previous chunk and
+  // silently demoting a date_time entity to an ordinary link.
+  it("keeps a cap-straddling date_time entity whole in one chunk", () => {
+    const body = `${"x".repeat(80)} ${DATE_TIME}`;
+    const chunks = splitMarkdownChunks(body, 110);
+    expect(chunks.length).toBeGreaterThan(1);
+    // Exactly one chunk carries the entity, whole.
+    expect(chunks.filter((c) => c.includes(DATE_TIME))).toHaveLength(1);
+    // And no chunk ends on the stranded `!`.
+    for (const c of chunks) expect(c.endsWith("!")).toBe(false);
+  });
+
+  it("still keeps an ordinary link whole (unchanged behaviour)", () => {
+    const link = "[a fairly long link label here](https://example.com/some/path)";
+    const chunks = splitMarkdownChunks(`${"x".repeat(80)} ${link}`, 110);
+    expect(chunks.filter((c) => c.includes(link))).toHaveLength(1);
+  });
+});

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

@@ -3,44 +3,61 @@ import { guardUnsupportedTokens } from "../../render/unsupported-token-guard.js"
 import { richMessage } from "../../rich-send.js";
 
 describe("guardUnsupportedTokens — deterministic send-time repair", () => {
-  it("folds <details><summary> into a Telegram expandable blockquote", () => {
+  // ── Natively-supported constructs pass through BYTE-IDENTICAL ────────────
+  // Wire-verified 2026-08-13: raw sendRichMessage probes showed `<details>`,
+  // footnotes, `<sub>`/`<sup>`/`<u>`, `<aside>`, `tg://time` and task lists
+  // all parse into real typed nodes on Telegram's rich markdown path. An
+  // earlier revision of this guard "repaired" `<details>` into a `**> `
+  // expandable blockquote (MarkdownV2-only syntax that renders as LITERAL
+  // `**>` text on this path) and deleted footnote markers — both conversions
+  // destroyed supported constructs and are deleted. These tests would FAIL on
+  // the old guard.
+  it("passes a <details><summary> block through untouched (native construct)", () => {
     const input =
-      "Here is the trace:\n<details><summary>Stack trace</summary>\nline 1\nline 2\n</details>\ndone";
-    const out = guardUnsupportedTokens(input);
-    // Anti-tautology: the raw HTML tags MUST be gone from the wire body.
-    expect(out).not.toContain("<details>");
-    expect(out).not.toContain("</details>");
-    expect(out).not.toContain("<summary>");
-    // Summary becomes the expandable-blockquote first line (`**> ` marker).
-    expect(out).toContain("**> Stack trace");
-    // Body lines become plain `> ` continuation lines.
-    expect(out).toContain("> line 1");
-    expect(out).toContain("> line 2");
+      "Here is the trace:\n<details open><summary>Stack trace</summary>\n\nline 1\nline 2\n\n</details>\ndone";
+    expect(guardUnsupportedTokens(input)).toBe(input);
   });
 
-  it("folds a <details> without a <summary> into an expandable blockquote", () => {
-    const out = guardUnsupportedTokens("<details>hidden body text</details>");
-    expect(out).not.toContain("<details");
-    expect(out).toContain("**> hidden body text");
+  it("passes a <details> without a <summary> through untouched", () => {
+    const input = "<details>hidden body text</details>";
+    expect(guardUnsupportedTokens(input)).toBe(input);
   });
 
-  it("strips caret highlight / superscript pairs to their inner text", () => {
-    expect(guardUnsupportedTokens("energy is x^2^ joules")).toBe(
-      "energy is x2 joules",
-    );
-    expect(guardUnsupportedTokens("a ^highlighted^ word")).toBe(
-      "a highlighted word",
+  it("never converts <details> into the retired `**>` marker", () => {
+    const out = guardUnsupportedTokens(
+      "<details><summary>More</summary>\nbody\n</details>",
     );
+    expect(out).not.toContain("**>");
+    expect(out).toContain("<details>");
   });
 
-  it("removes footnote reference markers but keeps definition lines", () => {
+  it("keeps footnote reference markers AND definition lines (native construct)", () => {
     expect(guardUnsupportedTokens("see the note[^1] here")).toBe(
-      "see the note here",
+      "see the note[^1] here",
     );
-    // A `[^1]:` definition line is left intact (the negative lookahead).
     expect(guardUnsupportedTokens("[^1]: the definition")).toBe(
       "[^1]: the definition",
     );
+    // Alphanumeric ids too — the pair renders as real footnote machinery.
+    expect(guardUnsupportedTokens("claim[^note] holds\n\n[^note]: body")).toBe(
+      "claim[^note] holds\n\n[^note]: body",
+    );
+  });
+
+  it("passes <sub>/<sup>/<u>/<aside> HTML tags through untouched", () => {
+    const input =
+      "H<sub>2</sub>O and x<sup>2</sup> and <u>under</u>\n<aside>pull\n<cite>credit</cite></aside>";
+    expect(guardUnsupportedTokens(input)).toBe(input);
+  });
+
+  // ── The one genuinely-unsupported token: caret pairs ─────────────────────
+  it("strips caret highlight / superscript pairs to their inner text", () => {
+    expect(guardUnsupportedTokens("energy is x^2^ joules")).toBe(
+      "energy is x2 joules",
+    );
+    expect(guardUnsupportedTokens("a ^highlighted^ word")).toBe(
+      "a highlighted word",
+    );
   });
 
   it("leaves unpaired carets scattered across prose intact (no interior space)", () => {
@@ -71,27 +88,18 @@ describe("guardUnsupportedTokens — deterministic send-time repair", () => {
     expect(guardUnsupportedTokens("x^2^ metres")).toBe("x2 metres");
   });
 
-  it("repairs alphanumeric footnote markers, not just numeric", () => {
-    // POLISH-4: widened from digits-only so `[^note]`/`[^ref]` no longer ship
-    // as literal bracket noise. Each would survive UNTOUCHED on origin/main.
-    expect(guardUnsupportedTokens("see the note[^note] here")).toBe(
-      "see the note here",
-    );
-    expect(guardUnsupportedTokens("as shown[^ref] above")).toBe(
-      "as shown above",
-    );
-    expect(guardUnsupportedTokens("point[^fn1] made")).toBe("point made");
-    // A single-letter id is a footnote too.
-    expect(guardUnsupportedTokens("claim[^a] holds")).toBe("claim holds");
-    // Definition lines with an alphanumeric id are still left intact (`(?!:)`).
-    expect(guardUnsupportedTokens("[^note]: the definition")).toBe(
-      "[^note]: the definition",
-    );
+  it("never strips carets inside a $…$ math span (protected segment)", () => {
+    // `$x^2y^2$` contains an alphanumeric-only caret pair (`^2y^`) that the
+    // caret regex WOULD strip in bare prose — but the compact math span is a
+    // protected segment (code-segments.ts), so the wire bytes survive intact
+    // for Telegram to typeset as a mathematical_expression node.
+    const math = "inline $x^2y^2$ done";
+    expect(guardUnsupportedTokens(math)).toBe(math);
   });
 
   it("leaves regex-literal negated char classes intact", () => {
-    // Real negated char classes contain punctuation / ranges / escapes, so the
-    // alphanumeric-only id requirement excludes them — these stay verbatim.
+    // The guard no longer touches `[^…]` at all (footnotes are supported),
+    // so every negated-char-class shape survives verbatim.
     expect(guardUnsupportedTokens("use [^/] to match")).toBe(
       "use [^/] to match",
     );
@@ -99,23 +107,14 @@ describe("guardUnsupportedTokens — deterministic send-time repair", () => {
       "strip [^a-z] chars",
     );
     expect(guardUnsupportedTokens('match [^"] here')).toBe('match [^"] here');
-    // Accepted tradeoff (task POLISH-4): a PURE-alphanumeric negated class in
-    // BARE prose like `array[^index]` is now treated as a footnote and stripped.
-    // This is rare — regex/index literals in real prose live in code spans,
-    // which splitProtectedSegments masks (see code-span test below).
-    expect(guardUnsupportedTokens("array[^index] lookup")).toBe("array lookup");
-    // …but inside a code span the same literal is untouched.
+    expect(guardUnsupportedTokens("array[^index] lookup")).toBe(
+      "array[^index] lookup",
+    );
     expect(guardUnsupportedTokens("`array[^index]` lookup")).toBe(
       "`array[^index]` lookup",
     );
   });
 
-  it("repairs a real numeric footnote marker", () => {
-    expect(guardUnsupportedTokens("see the note[^1] here")).toBe(
-      "see the note here",
-    );
-  });
-
   it("is a strict no-op for clean markdown (no target tokens)", () => {
     const clean =
       "**Answer:** the `config.yaml` file. See [docs](https://example.com/x).";
@@ -139,18 +138,19 @@ describe("guardUnsupportedTokens — deterministic send-time repair", () => {
     expect(guardUnsupportedTokens(once)).toBe(once);
   });
 
-  it("OUTCOME: the composed richMessage wire body has unsupported tokens repaired", () => {
-    // End-to-end through the real send-path composition. This is the
-    // anti-tautology anchor: without guardUnsupportedTokens wired into
-    // guardAccidentalFormatting, the raw `<details>` / `^` / `[^1]` tokens would
-    // reach the wire and this assertion would FAIL.
+  it("OUTCOME: the composed richMessage wire body preserves supported constructs and repairs carets", () => {
+    // End-to-end through the real send-path composition (the FULL
+    // guardAccidentalFormatting pipeline). This is the anti-tautology anchor:
+    // on the pre-fix pipeline, `<details>` was folded into the unsupported
+    // `**>` marker and `[^1]` was deleted — every assertion below would FAIL.
     const { markdown } = richMessage(
-      "note[^1]\n<details><summary>More</summary>\ndetail line\n</details>\nx^2^",
+      "note[^1]\n<details><summary>More</summary>\ndetail line\n</details>\nx^2^\n\n[^1]: the note",
     );
-    expect(markdown).not.toContain("<details>");
-    expect(markdown).not.toContain("[^1]");
-    expect(markdown).toContain("**> More");
-    expect(markdown).toContain("> detail line");
-    expect(markdown).toContain("x2");
+    expect(markdown).toContain("<details><summary>More</summary>");
+    expect(markdown).toContain("</details>");
+    expect(markdown).toContain("note[^1]");
+    expect(markdown).toContain("[^1]: the note");
+    expect(markdown).not.toContain("**>");
+    expect(markdown).toContain("x2"); // caret pair repaired
   });
 });