From fca12a89d64490b9f1f32e7adacc72a38d79d430 Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Thu, 15 Oct 2026 16:08:55 +0200
Subject: [PATCH] fix(markdown): normalize inline HTML before rendering

---
 docs/markdown-renderer.md                     |  2 +-
 packages/app/src/components/markdown/html.ts  | 87 +++++++++++++++++++
 .../src/components/markdown/renderer.test.ts  | 46 ++++++++++
 .../app/src/components/markdown/source.ts     |  2 +
 4 files changed, 136 insertions(+), 1 deletion(-)
 create mode 100644 packages/app/src/components/markdown/html.ts

diff --git a/docs/markdown-renderer.md b/docs/markdown-renderer.md
index be74ab25d3..d934a8a98e 100644
--- a/docs/markdown-renderer.md
+++ b/docs/markdown-renderer.md
@@ -14,7 +14,7 @@ Resolve workspace image paths over the existing session RPC, then give the libra
 
 The pinned nightly has the same React Native package and core source trees as upstream commit `73ac5085eb1fdc743973b3473d4dba65abad5261`. Compatibility was checked with React Native 0.81.5. Native dependencies must be rebuilt when changing the highlighting configuration; JavaScript refresh cannot enable compiled grammars.
 
-Math and video are disabled. Task lists and admonitions are enabled; task checkboxes are read-only. Source adaptation spaces adjacent empty GFM table delimiters before escaping prose spoiler delimiters and decodes entity text before the engine can discard it. Code spans and fences keep their literal source. HTML and details collapsibles have no custom renderer.
+Math and video are disabled. Task lists and admonitions are enabled; task checkboxes are read-only. Source adaptation spaces adjacent empty GFM table delimiters before escaping prose spoiler delimiters and decodes entity text before the engine can discard it. Code spans and fences keep their literal source. Comment HTML is normalized to Markdown before parsing; details show their summary and body expanded.
 
 Mermaid fences use the existing isolated diagram runtime and fullscreen viewer. Web dispatches them through the library’s code-block override. Native has no block-renderer hook, so the renderer extracts only Mermaid fences and places the existing WebView host between library-rendered segments. This is the only block exception; selection stops at a diagram boundary. Streaming keeps the last valid diagram visible while the next revision renders.
 
diff --git a/packages/app/src/components/markdown/html.ts b/packages/app/src/components/markdown/html.ts
new file mode 100644
index 0000000000..464c65d729
--- /dev/null
+++ b/packages/app/src/components/markdown/html.ts
@@ -0,0 +1,87 @@
+import { Parser } from "htmlparser2";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { decodeString } from "micromark-util-decode-string";
+import type { Nodes } from "mdast";
+
+const ATTRIBUTE = String.raw`\s+[A-Za-z_:][\w.:-]*(?:\s*=\s*(?:[^\s"'=<>\x60]+|'[^']*'|"[^"]*"))?`;
+const TAG = String.raw`<(?:[A-Za-z][A-Za-z0-9-]*(?:${ATTRIBUTE})*\s*\/?|\/[A-Za-z][A-Za-z0-9-]*\s*)>`;
+const HTML = new RegExp(
+  String.raw`(?<!\\)(?:<!--[\s\S]*?-->|<code\b[^>]*>[\s\S]*?<\/code\s*>|${TAG})`,
+  "gi",
+);
+const EMPHASIS: Readonly<Record<string, string>> = { b: "**", strong: "**", i: "*", em: "*" };
+
+/** Convert comment HTML to Markdown while preserving the original spelling of code. */
+export function normalizeMarkdownHtml(source: string): string {
+  if (!source.includes("<")) return source;
+  const codeRanges: { start: number; end: number }[] = [];
+  // Disable HTML parsing so code inside <details> remains visible to the Markdown parser.
+  const tree = fromMarkdown(source, {
+    extensions: [{ disable: { null: ["htmlFlow", "htmlText"] } }],
+  });
+  function protectCode(node: Nodes) {
+    if (node.type === "code" || node.type === "inlineCode") {
+      const start = node.position?.start.offset;
+      const end = node.position?.end.offset;
+      if (start !== undefined && end !== undefined) codeRanges.push({ start, end });
+    } else if ("children" in node) node.children.forEach(protectCode);
+  }
+  protectCode(tree);
+  const links: (string | undefined)[] = [];
+  return source.replace(HTML, (raw: string, offset: number) => {
+    if (codeRanges.some(({ start, end }) => offset >= start && offset < end)) return raw;
+    if (raw.startsWith("<!--")) return "";
+    const code = /^<code\b[^>]*>([\s\S]*?)<\/code\s*>$/i.exec(raw);
+    if (code)
+      return inlineCode(
+        code[1].replace(/&(?:#(?:[xX][\da-fA-F]+|\d+)|[a-zA-Z][a-zA-Z\d]+);/g, (entity) =>
+          decodeString(entity),
+        ),
+      );
+    const closing = raw.startsWith("</");
+    const name = /^<\/?([\w-]+)/.exec(raw)?.[1].toLowerCase() ?? "";
+    if (EMPHASIS[name]) return EMPHASIS[name];
+    if (name === "br") return closing ? "" : "  \n";
+    if (name === "summary") return closing ? "**\n\n" : "**";
+    if (name === "details")
+      return (closing ? offset + raw.length === source.length : offset === 0) ? "" : "\n\n";
+    if (name === "a") return markdownAnchor(raw, closing, links);
+    if (name === "img" && !closing) {
+      const { src, alt = "" } = attributes(raw);
+      return src ? `![${alt.replace(/[[\]\\]/g, "\\$&")}](<${markdownUrl(src)}>)` : alt;
+    }
+    return "";
+  });
+}
+
+function attributes(tag: string): Record<string, string> {
+  let result: Record<string, string> = {};
+  const parser = new Parser({
+    onopentag: (_name, value) => {
+      result = value;
+    },
+  });
+  parser.end(tag);
+  return result;
+}
+
+function markdownUrl(url: string): string {
+  return url.replace(/[<>\r\n]/g, (character) => encodeURIComponent(character));
+}
+
+function inlineCode(content: string): string {
+  const runs = content.match(/`+/g) ?? [];
+  const marker = "`".repeat(Math.max(0, ...runs.map((run) => run.length)) + 1);
+  const padding = content.startsWith("`") || content.endsWith("`") ? " " : "";
+  return `${marker}${padding}${content}${padding}${marker}`;
+}
+
+function markdownAnchor(raw: string, closing: boolean, links: (string | undefined)[]): string {
+  if (closing) {
+    const href = links.pop();
+    return href === undefined ? "" : `](<${markdownUrl(href)}>)`;
+  }
+  const { href } = attributes(raw);
+  links.push(href);
+  return href === undefined ? "" : "[";
+}
diff --git a/packages/app/src/components/markdown/renderer.test.ts b/packages/app/src/components/markdown/renderer.test.ts
index 3d0c9b9843..2ccf9c88ea 100644
--- a/packages/app/src/components/markdown/renderer.test.ts
+++ b/packages/app/src/components/markdown/renderer.test.ts
@@ -202,3 +202,49 @@ it.each([darkTheme, lightTheme])("supplies the theme selection colour to the ren
     theme.colors.terminal.selectionBackground,
   );
 });
+
+describe("GitHub comment HTML normalization", () => {
+  it.each([
+    [
+      '<img alt="P1" src="https://example.com/p1.svg" align="top">',
+      "![P1](<https://example.com/p1.svg>)",
+    ],
+    ['<a href="https://example.com/review">▶</a>', "[▶](<https://example.com/review>)"],
+    ["Before<br>After<br/>End", "Before  \nAfter  \nEnd"],
+    ["<b>bold</b> and <strong>strong</strong>", "**bold** and **strong**"],
+    ["<i>italic</i> and <em>emphasis</em>", "*italic* and *emphasis*"],
+    ["Use <code>const n = 1</code>.", "Use `const n = 1`."],
+    ["H<sub>2</sub>O and x<sup>2</sup>", "H2O and x2"],
+    [
+      "<details><summary>Review details</summary>Body **stays**.</details>",
+      "**Review details**\n\nBody **stays**.",
+    ],
+    ["Before<!-- private -->After", "BeforeAfter"],
+    ["<div><span>Keep the content</span></div>", "Keep the content"],
+    [
+      '<a href="https://example.com"><strong>Review</strong></a>',
+      "[**Review**](<https://example.com>)",
+    ],
+    ['`<img src="literal.png">` and <b>bold</b>', '`<img src="literal.png">` and **bold**'],
+    [
+      '```html\n<img src="literal.png">\n```\n\n<b>bold</b>',
+      '```html\n<img src="literal.png">\n```\n\n**bold**',
+    ],
+    ['~~~html\n<a href="literal">link</a>\n~~~', '~~~html\n<a href="literal">link</a>\n~~~'],
+    [
+      '<details><summary>Code</summary>\n\n```html\n<img src="literal.png">\n```\n</details>',
+      '**Code**\n\n\n\n```html\n<img src="literal.png">\n```\n',
+    ],
+    [
+      "<https://example.com> and <user@example.com>",
+      "<https://example.com> and <user@example.com>",
+    ],
+  ])("normalizes %s without changing code", (source, expected) => {
+    expect(prepareMarkdownSource(source).render()).toBe(expected);
+  });
+});
+
+it("preserves backslashes and decodes entities inside HTML code", () => {
+  const source = String.raw`<code>\*literal\* &lt;img&gt;</code>`;
+  expect(prepareMarkdownSource(source).render()).toBe("`" + String.raw`\*literal\* <img>` + "`");
+});
diff --git a/packages/app/src/components/markdown/source.ts b/packages/app/src/components/markdown/source.ts
index da220c0753..cf81511860 100644
--- a/packages/app/src/components/markdown/source.ts
+++ b/packages/app/src/components/markdown/source.ts
@@ -1,3 +1,4 @@
+import { normalizeMarkdownHtml } from "./html";
 import { gfmTable } from "micromark-extension-gfm-table";
 import { gfmTableFromMarkdown } from "mdast-util-gfm-table";
 import type { AssistantFileLinkSource } from "@/assistant-file-links";
@@ -49,6 +50,7 @@ function workspaceHoverTitle(link: Link, markup: string, workspaceRoot?: string)
 
 /** Preserve source spelling; adapt workspace images, spoiler delimiters, and entity text. */
 export function prepareMarkdownSource(source: string, workspaceRoot?: string) {
+  source = normalizeMarkdownHtml(source);
   const images: MarkdownImage[] = [];
   let tree: Root | undefined;
   const getTree = () =>