fix: 🐛 defer HTML entity decoding to leaf renderers

User-typed text in mrkdwn payloads contains Slack-escaped `<`, `>`, `&`
chars as `&lt;`, `&gt;`, `&amp;`. Decoding these in `text_object.tsx`
BEFORE markdown_parser was incorrect: a literal `<@u123>` typed by a
user (delivered as `&lt;@u123&gt;`) decoded to `<@u123>` and got
tokenized as a real user mention, firing `hooks.user` and producing a
chip when Slack itself would render literal `<@u123>` text.

Slack's own renderer tokenizes the raw payload first and decodes
entities only at render time — confirmed empirically in section/mrkdwn
side-by-side. This change matches that:

- Remove entity decoding from text_object.tsx.
- Decode in the leaf renderers that emit user-visible text: Text, HTML,
  InlineCode (and its plain-code path), the fenced Code element, and
  Link (for the href; label children go through Text).
- New tests cover escaped `<@u123>`, `<#C123>`, `<!here>` staying
  literal, `&amp;` `&lt;` `&gt;` decoding in plain text, and entity
  decoding inside inline and fenced code.

The `&gt;` → "> " trailing-space hack (which existed to make blockquote
detection survive entity escaping) is removed. Slack itself does not
render blockquotes in section/mrkdwn, so user-typed `> quote` (delivered
as `&gt; quote`) no longer renders as a blockquote — which better
matches Slack's behavior.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: programad

.changeset/fix-mrkdwn-directives.md

@@ -2,4 +2,4 @@
 "slack-blocks-to-jsx": patch
 ---
 
-Resolve Slack directive atoms (`<@U…>`, `<#C…>`, `<!subteam^…>`, `<!channel|here|everyone>`, `<!date^…>`) in `section`/`mrkdwn` text and other mrkdwn-typed text. Directives now fire the same hooks as the `rich_text` path. `verbatim: true` matches Slack's empirical behavior — it suppresses bare-form `@here` / `@channel` / `@everyone` interpolation but is otherwise a no-op (markdown sugar, code spans, angle-bracket URLs, and structured `<!…>` directives all render the same in both modes). `&amp;` is now decoded alongside `&gt;` / `&lt;` so escaped ampersands don't leak into hrefs or visible text.
+Resolve Slack directive atoms (`<@U…>`, `<#C…>`, `<!subteam^…>`, `<!channel|here|everyone>`, `<!date^…>`) in `section`/`mrkdwn` text and other mrkdwn-typed text. Directives now fire the same hooks as the `rich_text` path. `verbatim: true` matches Slack's empirical behavior — it suppresses bare-form `@here` / `@channel` / `@everyone` interpolation but is otherwise a no-op (markdown sugar, code spans, angle-bracket URLs, and structured `<!…>` directives all render the same in both modes). HTML entity decoding (`&lt;`, `&gt;`, `&amp;`) is deferred from input pre-processing to leaf renderers, so escaped sequences like `&lt;@U123&gt;` (user typed `<@U123>` literally) stay literal instead of being incorrectly resolved as a user mention — matching Slack's renderer.

src/components/composition_objects/text_object.tsx

@@ -12,22 +12,19 @@ export const TextObject = (props: TextObjectProps) => {
   const { className = "" } = props;
   const { channels, users, hooks } = useGlobalData();
 
-  // Order matters: decode `>` and `<` before `&` so a literal escaped `>`
-  // (which arrives as `>`) doesn't get double-decoded.
-  // The `>` → `"> "` trailing space is intentional — it keeps blockquote line detection
-  // (`^>` in parser.tsx) working when Slack escapes the `>` of a quote line.
-  const parsed = text.replace(/&gt;/g, "> ").replace(/&lt;/g, "<").replace(/&amp;/g, "&");
-
+  // HTML entity decoding is deferred to the leaf renderers (Text, HTML, InlineCode, Code,
+  // Link) so escaped sequences like `&lt;@U123&gt;` (user typed `<@U123>` literally) don't
+  // get tokenized as directives. See decode_entities.ts.
   if (type === "plain_text")
     return (
       <div className={className + " dark:text-dark-text-primary"}>
-        {markdown_parser(parsed, { markdown: false, verbatim, users, channels, hooks })}
+        {markdown_parser(text, { markdown: false, verbatim, users, channels, hooks })}
       </div>
     );
 
   return (
     <div className={className + " dark:text-dark-text-primary"}>
-      {markdown_parser(parsed, { markdown: true, verbatim, users, channels, hooks })}
+      {markdown_parser(text, { markdown: true, verbatim, users, channels, hooks })}
     </div>
   );
 };

src/utils/markdown_parser/__tests__/directives.test.tsx

@@ -201,6 +201,56 @@ describe("escaped entities", () => {
     expect(anchor!.getAttribute("href")).toBe("https://example.test/?a=1&b=2");
     expect(anchor!.textContent).toBe("report");
   });
+
+  // Slack escapes literal `<`, `>`, `&` in user-typed text. If the user typed `<@U123>`
+  // literally (not as a directive), Slack delivers `&lt;@U123&gt;` in the payload. Our
+  // renderer must keep this as literal text — NOT resolve it as a user mention. Slack's
+  // own renderer behaves the same way (empirically verified — the "escaped" row in the PR
+  // description's side-by-side stays as literal `<@U123>`).
+  it("does NOT resolve a user-typed escaped directive as a mention", () => {
+    const user = vi.fn();
+    const { container } = renderMrkdwn(`escaped: &lt;@U123&gt;`, false, {
+      hooks: { user },
+      data: { users: [{ id: "U123", name: "alice" }] },
+    });
+    expect(user).not.toHaveBeenCalled();
+    expect(container.textContent).toContain("<@U123>");
+  });
+
+  it("does NOT resolve a user-typed escaped channel mention", () => {
+    const channel = vi.fn();
+    const { container } = renderMrkdwn(`escaped: &lt;#C123&gt;`, false, {
+      hooks: { channel },
+      data: { channels: [{ id: "C123", name: "general" }] },
+    });
+    expect(channel).not.toHaveBeenCalled();
+    expect(container.textContent).toContain("<#C123>");
+  });
+
+  it("does NOT resolve a user-typed escaped broadcast", () => {
+    const atHere = vi.fn();
+    const { container } = renderMrkdwn(`escaped: &lt;!here&gt;`, false, {
+      hooks: { atHere },
+    });
+    expect(atHere).not.toHaveBeenCalled();
+    expect(container.textContent).toContain("<!here>");
+  });
+
+  it("decodes escaped entities in plain text rendering", () => {
+    const { container } = renderMrkdwn(`a &amp; b &lt; c &gt; d`, false);
+    expect(container.textContent).toContain("a & b < c > d");
+  });
+
+  it("decodes escaped entities inside inline code", () => {
+    const { container } = renderMrkdwn("`&lt;script&gt;alert(1)&lt;/script&gt;`", false);
+    expect(container.querySelector("code")?.textContent).toBe("<script>alert(1)</script>");
+  });
+
+  it("decodes escaped entities inside fenced code", () => {
+    const { container } = renderMrkdwn("```\n&lt;script&gt;\n```", false);
+    const code = container.querySelector("code");
+    expect(code?.textContent).toContain("<script>");
+  });
 });
 
 describe("regression — non-directive markdown", () => {

src/utils/markdown_parser/decode_entities.ts

@@ -0,0 +1,11 @@
+// Slack escapes literal `&`, `<`, `>` in user-typed text as `&amp;`, `&lt;`, `&gt;` before the
+// mrkdwn payload reaches us. We MUST decode them for display, but only at render time —
+// decoding earlier would let escaped sequences like `&lt;@U123&gt;` (which a user typed
+// literally) get tokenized as a real `<@U123>` user mention. Slack's own renderer behaves the
+// same way: it tokenizes the raw payload first and decodes entities only when emitting text.
+//
+// Order matters: decode `&lt;` and `&gt;` first, then `&amp;`. If a literal `&gt;` was itself
+// escaped (it arrives as `&amp;gt;`), this order keeps it as `&gt;` instead of double-decoding
+// to `>`.
+export const decodeEntities = (s: string): string =>
+  s.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");

src/utils/markdown_parser/elements/code.tsx

@@ -1,3 +1,4 @@
+import { decodeEntities } from "../decode_entities";
 import { CodeElement } from "../types";
 
 type Props = {
@@ -7,5 +8,5 @@ type Props = {
 export const Code = (props: Props) => {
   const { element } = props;
 
-  return <code className="slack_code block p-2 text-xs whitespace-pre-wrap break-words rounded-[3px] border border-black-primary/[0.13] dark:border-dark-code-border bg-black-primary/[0.04] dark:bg-dark-code-bg dark:text-dark-text-primary w-full my-1 font-mono">{element.value}</code>;
+  return <code className="slack_code block p-2 text-xs whitespace-pre-wrap break-words rounded-[3px] border border-black-primary/[0.13] dark:border-dark-code-border bg-black-primary/[0.04] dark:bg-dark-code-bg dark:text-dark-text-primary w-full my-1 font-mono">{decodeEntities(element.value)}</code>;
 };

src/utils/markdown_parser/sub_elements/html.tsx

@@ -1,3 +1,4 @@
+import { decodeEntities } from "../decode_entities";
 import { HTMLSubElement } from "../types";
 
 type Props = {
@@ -6,13 +7,14 @@ type Props = {
 
 export const HTML = (props: Props) => {
   const { element } = props;
+  const value = decodeEntities(element.value);
 
-  if (!element.value) return <span>{element.value}</span>;
-  if (element.value === " ") return <span>&nbsp;</span>;
+  if (!value) return <span>{value}</span>;
+  if (value === " ") return <span>&nbsp;</span>;
 
   return (
     <span>
-      {element.value.split("LBKS").map((line, index) => {
+      {value.split("LBKS").map((line, index) => {
         if (line === "") {
           return <span key={index} className="block h-2"></span>;
         }

src/utils/markdown_parser/sub_elements/inline_code.tsx

@@ -1,4 +1,5 @@
 import { ReactNode } from "react";
+import { decodeEntities } from "../decode_entities";
 import { InlineCodeSubElement } from "../types";
 
 type Props = {
@@ -62,7 +63,8 @@ function parseInlineCodeValue(value: string): ParsedPart[] {
 
 export const InlineCode = (props: Props) => {
   const { element } = props;
-  const parts = parseInlineCodeValue(element.value);
+  const value = decodeEntities(element.value);
+  const parts = parseInlineCodeValue(value);
 
   // If the entire value is just a single link, render without code wrapper
   const firstPart = parts[0];
@@ -83,7 +85,7 @@ export const InlineCode = (props: Props) => {
   if (parts.every((part) => part.type === "text")) {
     return (
       <code className="slack_code_inline inline-block px-1 text-xs whitespace-pre-wrap break-words rounded-[3px] border border-black-primary/[0.13] dark:border-dark-code-border bg-black-primary/[0.04] dark:bg-dark-code-bg text-red-primary dark:text-dark-text-primary font-mono">
-        {element.value}
+        {value}
       </code>
     );
   }

src/utils/markdown_parser/sub_elements/link.tsx

@@ -1,4 +1,5 @@
 import { useGlobalData } from "../../../store";
+import { decodeEntities } from "../decode_entities";
 import { LinkSubElement } from "../types";
 import { Delete } from "./delete";
 import { Emphasis } from "./emphasis";
@@ -13,12 +14,13 @@ type Props = {
 export const Link = (props: Props) => {
   const { element } = props;
   const { hooks } = useGlobalData();
+  const href = decodeEntities(element.url);
 
   if (hooks.link) {
     return (
       <>
         {hooks.link({
-          href: element.url,
+          href,
           children: (
             <>
               {element.children.map((child, i) => {
@@ -38,7 +40,7 @@ export const Link = (props: Props) => {
   }
 
   return (
-    <a href={element.url} className="slack_link">
+    <a href={href} className="slack_link">
       {element.children.map((child, i) => {
         if (child.type === "delete") return <Delete key={i} element={child} />;
         if (child.type === "emphasis") return <Emphasis key={i} element={child} />;

src/utils/markdown_parser/sub_elements/text.tsx

@@ -1,3 +1,4 @@
+import { decodeEntities } from "../decode_entities";
 import { TextSubElement } from "../types";
 
 type Props = {
@@ -6,13 +7,14 @@ type Props = {
 
 export const Text = (props: Props) => {
   const { element } = props;
+  const value = decodeEntities(element.value);
 
-  if (!element.value) return <span>{element.value}</span>;
-  if (element.value === " ") return <span>&nbsp;</span>;
+  if (!value) return <span>{value}</span>;
+  if (value === " ") return <span>&nbsp;</span>;
 
   return (
     <span>
-      {element.value.split("LBKS").map((line, index) => {
+      {value.split("LBKS").map((line, index) => {
         if (line === "") {
           return <span key={index} className="block h-2"></span>;
         }