refactor: 🔧 simplify verbatim handling to match Slack's empirical behavior

Empirically tested in Slack's section/mrkdwn renderer (side-by-side
Block Kit Builder, both verbatim modes). Findings:

- Verbatim:true does NOT suppress markdown formatting (`*bold*`,
  `_italic_`, `~strike~`, `` `code` ``) — Slack renders these the same
  in both modes.
- Verbatim:true does NOT suppress code spans or angle-bracket URLs.
- The ONE thing verbatim:true does suppress in section/mrkdwn (that
  affects this library) is bare-form `@here` / `@channel` / `@everyone`
  (without the `<!…>` brackets). Slack interpolates them as chips in
  verbatim:false and renders them as plain text in verbatim:true.

Implementation changes:
- Drop the separate "split by directive boundaries, render rest as
  literal text" verbatim path. Both modes now flow through the same
  pipeline.
- Build two yozora parser instances. The verbatim instance constructs
  SlackBroadcastTokenizer with `matchTypedBroadcast: false` so bare
  `@here` etc. stay as plain text. Bracket-form `<!here>` etc. still
  resolve in both modes.
- Delete `directives.tsx` (no longer needed). Inline DIRECTIVE_PATTERN
  helpers into `preparse.ts`.

Tests:
- Flip the two tests that asserted the wrong verbatim behavior
  ("does NOT bold *text* in verbatim" → "renders *bold* in verbatim
  (matches Slack)", same for `<URL>` autolinking).
- Rename code-span suppression block to call out the known divergence
  (Slack resolves directives inside code spans; this library doesn't —
  tracked as a follow-up since it needs custom tokenization).
- Add per-broadcast-target tests for the new typed-broadcast suppression.
- Add a DOM-equality test confirming verbatim and non-verbatim produce
  identical output for non-typed-broadcast content.

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 in both `verbatim: true` and `verbatim: false` modes. Code-span content stays literal (directives inside `` `…` `` or ` ```…``` ` are not resolved). `&amp;` is now decoded alongside the existing `&gt;` / `&lt;` decoding so link `href`s and visible text don't leak literal `&amp;`.
+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.

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

@@ -162,7 +162,13 @@ describe("date directives", () => {
   });
 });
 
-describe("code-span suppression", () => {
+// KNOWN DIVERGENCE FROM SLACK: Slack's own renderer resolves directives that appear inside
+// inline code (`` `<@U…>` ``) — empirically confirmed in Slack's section/mrkdwn rendering.
+// This library currently keeps them literal (CommonMark-style code-span opacity), which is
+// what most React/markdown consumers expect. Resolving directives inside code spans is
+// tracked as a follow-up; it requires either a custom inline-code tokenizer or an AST-walk
+// after yozora parse.
+describe("code-span suppression (known divergence from Slack)", () => {
   it("does not fire hooks.user for directives inside inline code (non-verbatim)", () => {
     const user = vi.fn();
     const { container } = renderMrkdwn("Try \\`<@U123>\\`".replace(/\\`/g, "`"), false, {
@@ -208,22 +214,103 @@ describe("regression — non-directive markdown", () => {
     expect(container.querySelector("code")?.textContent).toBe("code");
   });
 
-  it("does NOT bold *text* in verbatim mode (renders literal)", () => {
+  // Verbatim is effectively a no-op in Slack's renderer (empirically verified — see PR
+  // description). Markdown formatting, code spans, directives, and angle-bracket URLs all
+  // render the same in both modes. Slack only suppresses bare-URL autolinking in verbatim
+  // mode, which this library doesn't do in either mode anyway.
+
+  it("renders *bold* in verbatim mode (matches Slack)", () => {
     const { container } = renderMrkdwn(`Hi *bold* world`, true);
-    expect(container.querySelector("strong")).toBeNull();
-    expect(container.textContent).toContain("*bold*");
+    expect(container.querySelector("strong")?.textContent).toBe("bold");
   });
 
-  it("auto-links bare URLs in non-verbatim", () => {
+  it("renders <URL> as a link in non-verbatim", () => {
     const { container } = renderMrkdwn(`Visit <https://example.com>`, false);
     const anchor = container.querySelector("a");
     expect(anchor?.getAttribute("href")).toBe("https://example.com");
   });
 
-  it("does NOT auto-link bare URLs in verbatim", () => {
+  it("renders <URL> as a link in verbatim too (matches Slack)", () => {
     const { container } = renderMrkdwn(`Visit <https://example.com>`, true);
-    expect(container.querySelector("a")).toBeNull();
-    expect(container.textContent).toContain("<https://example.com>");
+    const anchor = container.querySelector("a");
+    expect(anchor?.getAttribute("href")).toBe("https://example.com");
+  });
+
+  it("renders <URL|label> as a link in verbatim too (matches Slack)", () => {
+    const { container } = renderMrkdwn(`Visit <https://example.com|click>`, true);
+    const anchor = container.querySelector("a");
+    expect(anchor?.getAttribute("href")).toBe("https://example.com");
+    expect(anchor?.textContent).toBe("click");
+  });
+
+  it("renders inline code in verbatim too", () => {
+    const { container } = renderMrkdwn("Try `code`", true);
+    expect(container.querySelector("code")?.textContent).toBe("code");
+  });
+});
+
+describe("typed-broadcast suppression in verbatim mode (matches Slack)", () => {
+  // Slack renders bare `@here` / `@channel` / `@everyone` (without `<!…>` brackets) as chips
+  // in verbatim:false and as plain text in verbatim:true. This is the only verbatim difference
+  // this library cares about — empirically verified against Slack's section/mrkdwn renderer.
+
+  it("fires hooks.atHere for typed @here in non-verbatim", () => {
+    const atHere = vi.fn(() => <span data-testid="h">@here</span>);
+    const { getByTestId } = renderMrkdwn(`Hello @here folks`, false, { hooks: { atHere } });
+    expect(atHere).toHaveBeenCalledTimes(1);
+    expect(getByTestId("h")).toBeInTheDocument();
+  });
+
+  it("does NOT fire hooks.atHere for typed @here in verbatim", () => {
+    const atHere = vi.fn();
+    const { container } = renderMrkdwn(`Hello @here folks`, true, { hooks: { atHere } });
+    expect(atHere).not.toHaveBeenCalled();
+    expect(container.textContent).toContain("@here");
+  });
+
+  it("still fires hooks.atHere for bracket-form <!here> in verbatim", () => {
+    const atHere = vi.fn(() => <span data-testid="h">@here</span>);
+    const { getByTestId } = renderMrkdwn(`Hello <!here> folks`, true, { hooks: { atHere } });
+    expect(atHere).toHaveBeenCalledTimes(1);
+    expect(getByTestId("h")).toBeInTheDocument();
+  });
+
+  it("does NOT fire hooks.atChannel for typed @channel in verbatim", () => {
+    const atChannel = vi.fn();
+    renderMrkdwn(`@channel`, true, { hooks: { atChannel } });
+    expect(atChannel).not.toHaveBeenCalled();
+  });
+
+  it("does NOT fire hooks.atEveryone for typed @everyone in verbatim", () => {
+    const atEveryone = vi.fn();
+    renderMrkdwn(`@everyone`, true, { hooks: { atEveryone } });
+    expect(atEveryone).not.toHaveBeenCalled();
+  });
+});
+
+describe("verbatim and non-verbatim render identically (except typed broadcasts)", () => {
+  const payload =
+    "broadcasts: <!here> <!channel> <!everyone>\n" +
+    "date: <!date^1717000000^{date_pretty}|May 29>\n" +
+    "sugar: *bold* _italic_ ~strike~ `code`\n" +
+    "url angle: <https://example.com>\n" +
+    "url angle+label: <https://example.com|click>";
+
+  it("produces identical DOM markup for the same payload", () => {
+    const hooks = {
+      atHere: () => <span data-testid="here">@here</span>,
+      atChannel: () => <span data-testid="channel">@channel</span>,
+      atEveryone: () => <span data-testid="everyone">@everyone</span>,
+      date: () => <span data-testid="date">date</span>,
+    };
+    const a = renderMrkdwn(payload, true, { hooks });
+    const verbatimHtml = a.container.innerHTML;
+    a.unmount();
+
+    const b = renderMrkdwn(payload, false, { hooks });
+    const nonVerbatimHtml = b.container.innerHTML;
+
+    expect(verbatimHtml).toBe(nonVerbatimHtml);
   });
 });
 

src/utils/markdown_parser/directives.tsx

@@ -1,7 +1,6 @@
 import YozoraParser from "@yozora/parser";
 import { ReactNode } from "react";
 import { GlobalStore } from "../../store";
-import { renderTextWithDirectives } from "./directives";
 import { Blockquote, Code, Paragraph } from "./elements";
 import { maskProtectedRegions } from "./preparse";
 import {
@@ -14,23 +13,37 @@ import {
 } from "./tokenizers";
 import { MarkdownElement } from "./types";
 
-const parser = new YozoraParser()
-  .unmountTokenizer("@yozora/tokenizer-list")
-  // Slack directives like `<!subteam^S1|@team>` and `<@U1|name>` contain `@` chars in their
-  // fallback labels. Yozora's autolink tokenizers misread these as email autolinks and steal
-  // them from our directive tokenizers. Disable both — bare URL autolinking is already handled
-  // upstream by the `<X>` / `<X|Y>` regex rewrites that produce `[url](url)` markdown links.
-  .unmountTokenizer("@yozora/tokenizer-autolink")
-  .unmountTokenizer("@yozora/tokenizer-autolink-extension")
-  .useTokenizer(new SlackUserMentionTokenizer())
-  .useTokenizer(new SlackChannelMentionTokenizer())
-  .useTokenizer(new SlackUserGroupMentionTokenizer())
-  .useTokenizer(new SlackBroadcastTokenizer())
-  .useTokenizer(new SlackDateTokenizer())
-  .useTokenizer(new SlackEmojiTokenizer());
+// Slack directives like `<!subteam^S1|@team>` and `<@U1|name>` contain `@` chars in their
+// fallback labels. Yozora's autolink tokenizers misread these as email autolinks and steal
+// them from our directive tokenizers. Disable both — bare URL autolinking is already handled
+// upstream by the `<X>` / `<X|Y>` regex rewrites that produce `[url](url)` markdown links.
+const buildParser = (matchTypedBroadcast: boolean) =>
+  new YozoraParser()
+    .unmountTokenizer("@yozora/tokenizer-list")
+    .unmountTokenizer("@yozora/tokenizer-autolink")
+    .unmountTokenizer("@yozora/tokenizer-autolink-extension")
+    .useTokenizer(new SlackUserMentionTokenizer())
+    .useTokenizer(new SlackChannelMentionTokenizer())
+    .useTokenizer(new SlackUserGroupMentionTokenizer())
+    .useTokenizer(new SlackBroadcastTokenizer({ matchTypedBroadcast }))
+    .useTokenizer(new SlackDateTokenizer())
+    .useTokenizer(new SlackEmojiTokenizer());
+
+// Slack's `verbatim` flag is effectively a no-op in section/mrkdwn rendering EXCEPT for one
+// case: it suppresses interpolation of typed-out `@here` / `@channel` / `@everyone` (without
+// the `<!…>` brackets). Empirically verified — see PR description for the side-by-side. We
+// honor that by using a parser without the bare-form broadcast match in verbatim mode.
+const parserDefault = buildParser(true);
+const parserVerbatim = buildParser(false);
 
 type Options = {
   markdown: boolean;
+  // In Slack's renderer, `verbatim` only changes two things in section/mrkdwn (empirically
+  // verified): it suppresses bare-URL autolinking, and it suppresses interpolation of bare
+  // `@here` / `@channel` / `@everyone`. Everything else — directives in `<…>` form, markdown
+  // sugar, code spans, angle-bracket URLs — renders identically in both modes. This library
+  // doesn't autolink bare URLs in either mode, so the only thing we gate on `verbatim` is the
+  // bare-broadcast tokenizer match.
   verbatim: boolean;
   users: GlobalStore["users"];
   channels: GlobalStore["channels"];
@@ -49,24 +62,6 @@ function isValidURL(string: string) {
 export const markdown_parser = (markdown: string, options: Options): ReactNode => {
   if (!markdown) return null;
 
-  // In verbatim mode, Slack semantics say markdown formatting (`*bold*`, `_italic_`, `~strike~`,
-  // bare URLs, code spans) should render as literal text, but Slack-formed directives are atoms
-  // that must still resolve through hooks. Split the text by directive boundaries and render
-  // each segment, preserving newlines as <br/>s.
-  if (options.verbatim) {
-    const segments = renderTextWithDirectives(markdown);
-    return (
-      <div>
-        {segments.map((segment, i) => {
-          if (typeof segment === "string") {
-            return renderVerbatimText(segment, i);
-          }
-          return segment;
-        })}
-      </div>
-    );
-  }
-
   let text_string = markdown;
 
   // Normalize fenced code so yozora can recognize ``` blocks.
@@ -112,7 +107,7 @@ export const markdown_parser = (markdown: string, options: Options): ReactNode =
   // sees their native shape. Directive tokenizers will tokenize them at parse time.
   text_string = mask.restore(text_string);
 
-  const parsed_data = parser.parse(text_string);
+  const parsed_data = (options.verbatim ? parserVerbatim : parserDefault).parse(text_string);
 
   const elements = parsed_data.children as unknown as MarkdownElement[];
 
@@ -129,14 +124,3 @@ export const markdown_parser = (markdown: string, options: Options): ReactNode =
     </div>
   );
 };
-
-const renderVerbatimText = (text: string, baseKey: number): ReactNode => {
-  if (!text.includes("\n")) return text;
-  const lines = text.split("\n");
-  const out: ReactNode[] = [];
-  lines.forEach((line, idx) => {
-    if (idx > 0) out.push(<br key={`br-${baseKey}-${idx}`} />);
-    if (line) out.push(line);
-  });
-  return <span key={`v-${baseKey}`}>{out}</span>;
-};

src/utils/markdown_parser/parser.tsx

@@ -1,12 +1,30 @@
-import { DIRECTIVE_PATTERN_GLOBAL } from "./directives";
-
 const PLACEHOLDER_OPEN = "";
 const PLACEHOLDER_CLOSE = "";
 const PLACEHOLDER_PATTERN = new RegExp(`${PLACEHOLDER_OPEN}([0-9a-z]+)${PLACEHOLDER_CLOSE}`, "g");
 
 const FENCED_CODE = /```\n[\s\S]*?\n```/g;
 const INLINE_CODE = /`[^`\n]+`/g;
 
+// Slack-formed directive atoms. Pre-masked before the URL-rewrite regex pass so it cannot
+// mangle their interiors (defense in depth: `isValidURL` happens to leave directives alone
+// today, but the protection is incidental, not deliberate).
+const DIRECTIVE_USER = /<@[^|>\s]+(?:\|[^>]*)?>/;
+const DIRECTIVE_CHANNEL = /<#[^|>\s]+(?:\|[^>]*)?>/;
+const DIRECTIVE_USERGROUP = /<!subteam\^[^|>\s]+(?:\|[^>]*)?>/;
+const DIRECTIVE_BROADCAST = /<!(?:here|channel|everyone)>/;
+const DIRECTIVE_DATE = /<!date\^[^>]+>/;
+
+const DIRECTIVE_PATTERN_GLOBAL = new RegExp(
+  [
+    DIRECTIVE_USER.source,
+    DIRECTIVE_CHANNEL.source,
+    DIRECTIVE_USERGROUP.source,
+    DIRECTIVE_BROADCAST.source,
+    DIRECTIVE_DATE.source,
+  ].join("|"),
+  "g",
+);
+
 type Mask = {
   masked: string;
   restore: (input: string) => string;