perf: per-word blur-fade-in for streaming markdown

Replace the per-block fade-in (which fired only once per paragraph at
mount, then text grew silently inside) with a per-word blur-fade-in.

Mechanism:
- rehypeSplitWordsForFade walks the HAST tree and wraps each
  whitespace-bounded word in <span class="sd-word">. Skips inside
  <pre>/<code>/KaTeX/Mermaid subtrees so code, math, and diagrams
  stay structurally intact.
- MarkdownCore swaps in this rehype plugin only while
  parseIncompleteMarkdown=true (i.e., during streaming) — completed/
  static markdown still renders without word spans (no extra DOM weight).
- globals.css replaces the per-block keyframes with sd-word-blur-in
  (filter: blur(6px) → blur(0), opacity 0 → 1, 500ms ease-out).
  Still gated on [data-streaming="true"] and prefers-reduced-motion.

Why per-word
- The user reported the prior per-block effect was invisible in
  thinking blocks (which are typically a single paragraph — block
  fade-in fires once at mount, then text grows silently inside the
  same <p>). Per-word also animates inside an already-mounted block:
  each new whitespace boundary mounts a fresh span and triggers a
  fade for that word and only that word.
- Stable identity at every word position: as text grows from "Hel" →
  "Hello", react-markdown reconciles the same span in place; only
  fresh whitespace boundaries mount new spans. Completed words stay
  static while only new words fade in.

Tests
- New rehypeSplitWordsForFade.test.ts covers the core invariants:
  word/whitespace tokenization, partial trailing word, empty input,
  pre/code skip, KaTeX skip, recursion into inline (<strong>/<em>).

Author: ammar-agent

src/browser/features/Messages/MarkdownCore.tsx

@@ -12,6 +12,7 @@ import "katex/dist/katex.min.css";
 import { normalizeMarkdown } from "./MarkdownStyles";
 import { markdownComponents } from "./MarkdownComponents";
 import { INTERNAL_INLINE_SKILL_HREF_PREFIX, remarkInlineSkillLinks } from "./inlineSkillMarkdown";
+import { rehypeSplitWordsForFade } from "./rehypeSplitWordsForFade";
 
 interface MarkdownCoreProps {
   content: string;
@@ -102,7 +103,7 @@ const sanitizeSchema = {
   },
 };
 
-const REHYPE_PLUGINS: Pluggable[] = [
+const REHYPE_PLUGINS_BASE: Pluggable[] = [
   rehypeRaw, // Parse HTML elements first
   [rehypeSanitize, sanitizeSchema], // Sanitize HTML to prevent XSS (strips dangerous elements/attributes)
   [
@@ -123,6 +124,12 @@ const REHYPE_PLUGINS: Pluggable[] = [
   [rehypeKatex, { errorColor: "var(--color-muted-foreground)" }], // Render math
 ];
 
+// Streaming variant: also splits each whitespace-bounded word into a
+// `<span class="sd-word">` so the per-word blur-fade-in CSS rule fires once per
+// new word at mount. Order matters: rehypeKatex must run BEFORE the splitter so
+// .katex subtrees are tagged and excluded.
+const REHYPE_PLUGINS_STREAMING: Pluggable[] = [...REHYPE_PLUGINS_BASE, rehypeSplitWordsForFade];
+
 /**
  * Core markdown rendering component that handles all markdown processing.
  * This is the single source of truth for markdown configuration.
@@ -139,7 +146,7 @@ export const MarkdownCore = React.memo<MarkdownCoreProps>(
         <Streamdown
           components={markdownComponents}
           remarkPlugins={preserveLineBreaks ? REMARK_PLUGINS_WITH_BREAKS : REMARK_PLUGINS}
-          rehypePlugins={REHYPE_PLUGINS}
+          rehypePlugins={parseIncompleteMarkdown ? REHYPE_PLUGINS_STREAMING : REHYPE_PLUGINS_BASE}
           parseIncompleteMarkdown={parseIncompleteMarkdown}
           // Use "static" mode for completed content to bypass useTransition() deferral.
           // After ORPC migration, async event boundaries let React deprioritize transitions indefinitely.

src/browser/features/Messages/rehypeSplitWordsForFade.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, test } from "bun:test";
+import type { Element, Root } from "hast";
+import { transformWordsForFade } from "./rehypeSplitWordsForFade";
+
+// Drive the transform function directly on a synthetic HAST tree (bypassing
+// the unified pipeline). The plugin's transformer is a pure synchronous walk,
+// so this keeps the test hermetic and avoids spinning up rehype just to exercise
+// node walking + text splitting.
+function runPlugin(tree: Root): Root {
+  transformWordsForFade(tree);
+  return tree;
+}
+
+function p(...children: Element["children"]): Element {
+  return { type: "element", tagName: "p", properties: {}, children };
+}
+
+function root(...children: Root["children"]): Root {
+  return { type: "root", children };
+}
+
+describe("rehypeSplitWordsForFade", () => {
+  test("wraps each whitespace-bounded word in a sd-word span", () => {
+    const tree = root(p({ type: "text", value: "Hello world foo" }));
+    runPlugin(tree);
+    const para = tree.children[0] as Element;
+    expect(para.children).toHaveLength(5); // word, space, word, space, word
+    const types = para.children.map((c) =>
+      c.type === "element"
+        ? `<${c.tagName}.${(c.properties?.className as string[]).join(",")}>`
+        : c.value
+    );
+    expect(types).toEqual(["<span.sd-word>", " ", "<span.sd-word>", " ", "<span.sd-word>"]);
+  });
+
+  test("preserves whitespace runs as plain text (no spans)", () => {
+    const tree = root(p({ type: "text", value: "a  \n  b" }));
+    runPlugin(tree);
+    const para = tree.children[0] as Element;
+    // [span("a"), text("  \n  "), span("b")]
+    expect(para.children).toHaveLength(3);
+    expect((para.children[0] as Element).tagName).toBe("span");
+    expect(para.children[1].type).toBe("text");
+    expect(para.children[2].type).toBe("element");
+  });
+
+  test("partial trailing word (no whitespace yet) is still wrapped", () => {
+    // Mid-stream: text node is "Hel" with nothing after it. Should still wrap
+    // so React reconciles the same span as it grows to "Hello".
+    const tree = root(p({ type: "text", value: "Hel" }));
+    runPlugin(tree);
+    const para = tree.children[0] as Element;
+    expect(para.children).toHaveLength(1);
+    expect((para.children[0] as Element).tagName).toBe("span");
+    expect(((para.children[0] as Element).children[0] as { value: string }).value).toBe("Hel");
+  });
+
+  test("empty text nodes produce no children", () => {
+    const tree = root(p({ type: "text", value: "" }));
+    runPlugin(tree);
+    const para = tree.children[0] as Element;
+    expect(para.children).toEqual([]);
+  });
+
+  test("does not split inside <pre> / <code> subtrees", () => {
+    // <pre><code>foo bar</code></pre> — must remain a single text node.
+    const codeBlock: Element = {
+      type: "element",
+      tagName: "pre",
+      properties: {},
+      children: [
+        {
+          type: "element",
+          tagName: "code",
+          properties: {},
+          children: [{ type: "text", value: "foo bar" }],
+        },
+      ],
+    };
+    const tree = root(codeBlock);
+    runPlugin(tree);
+    const pre = tree.children[0] as Element;
+    const code = pre.children[0] as Element;
+    expect(code.children).toHaveLength(1);
+    expect(code.children[0].type).toBe("text");
+    expect((code.children[0] as { value: string }).value).toBe("foo bar");
+  });
+
+  test("does not split inside KaTeX subtrees (class includes 'katex')", () => {
+    // KaTeX renders as <span class="katex"> with complex inner spans containing
+    // single-character text nodes. Splitting them would corrupt math layout.
+    const katexNode: Element = {
+      type: "element",
+      tagName: "span",
+      properties: { className: ["katex"] },
+      children: [{ type: "text", value: "x = y + z" }],
+    };
+    const tree = root(p(katexNode));
+    runPlugin(tree);
+    const para = tree.children[0] as Element;
+    const katex = para.children[0] as Element;
+    // Inner text untouched.
+    expect(katex.children).toHaveLength(1);
+    expect(katex.children[0].type).toBe("text");
+    expect((katex.children[0] as { value: string }).value).toBe("x = y + z");
+  });
+
+  test("recurses into inline elements like <strong> and <em>", () => {
+    // <p>hello <strong>brave new</strong> world</p>
+    const strong: Element = {
+      type: "element",
+      tagName: "strong",
+      properties: {},
+      children: [{ type: "text", value: "brave new" }],
+    };
+    const tree = root(
+      p({ type: "text", value: "hello " }, strong, { type: "text", value: " world" })
+    );
+    runPlugin(tree);
+    const para = tree.children[0] as Element;
+
+    // Outer paragraph: split "hello " → [span("hello"), " "], then <strong> child
+    // (its inner "brave new" should be split inside it), then split " world"
+    // → [" ", span("world")].
+    const outer = para.children;
+    // Quick shape check: strong should be at some index, and its inner text
+    // should be wrapped in word spans.
+    const strongChild = outer.find(
+      (c) => c.type === "element" && c.tagName === "strong"
+    ) as Element;
+    expect(strongChild).toBeDefined();
+    expect(strongChild.children).toHaveLength(3); // span("brave"), " ", span("new")
+    expect((strongChild.children[0] as Element).tagName).toBe("span");
+    expect((strongChild.children[2] as Element).tagName).toBe("span");
+  });
+});

src/browser/features/Messages/rehypeSplitWordsForFade.ts

@@ -0,0 +1,116 @@
+import type { Element, ElementContent, Root, RootContent, Text } from "hast";
+import type { Plugin } from "unified";
+
+/**
+ * Rehype plugin: wrap each whitespace-bounded word in a `<span class="sd-word">`
+ * inside the rendered markdown HAST. When paired with the per-word blur-fade-in
+ * CSS rule in `globals.css`, this gives a soft word-by-word reveal during
+ * streaming — including inside an already-mounted paragraph or thinking block,
+ * which is the case the per-block fade-in alone could not address.
+ *
+ * Stable identity: as text grows ("Hel" → "Hello"), the same `<span>` is
+ * reconciled in place by react-markdown — no remount, no re-animation. Only
+ * when a fresh whitespace boundary is crossed does a new `<span>` mount, which
+ * is when the CSS animation fires. That's the behavior we want.
+ *
+ * Skip rules:
+ *  - Inside `<pre>` or `<code>` — code keeps its own monospaced/static feel.
+ *  - Inside KaTeX subtrees (class contains "katex") — splitting math breaks
+ *    glyph metrics. KaTeX output is generated by rehypeKatex and tagged with
+ *    that class, so this plugin must run AFTER rehypeKatex in the pipeline.
+ *  - Inside Mermaid `<svg>` (handled implicitly: SVG namespace nodes are
+ *    structural; we only split text *children* of HTML elements).
+ *  - Inside `<script>`/`<style>` — sanitize already strips these but we guard
+ *    defensively.
+ */
+
+const SKIP_TAGS = new Set(["pre", "code", "script", "style"]);
+const SKIP_CLASS_SUBSTRINGS = ["katex", "mermaid"];
+
+function hasSkipClass(node: Element): boolean {
+  const cls = node.properties?.className;
+  if (!Array.isArray(cls)) return false;
+  for (const entry of cls) {
+    const s = String(entry);
+    for (const needle of SKIP_CLASS_SUBSTRINGS) {
+      if (s.includes(needle)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Split a text string into a sequence of HAST children:
+ *   "Hello  world" → [<span>Hello</span>, "  ", <span>world</span>]
+ *
+ * Whitespace runs stay as plain Text nodes so layout (line wrapping, justify,
+ * etc.) is unchanged. Empty input is a no-op.
+ */
+function splitTextIntoWordSpans(value: string): ElementContent[] {
+  if (value.length === 0) return [];
+  const out: ElementContent[] = [];
+  // Match non-whitespace runs OR whitespace runs. Together this tokenizes the
+  // entire string with no gaps.
+  const re = /(\S+)|(\s+)/g;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(value)) !== null) {
+    const word = match[1];
+    const ws = match[2];
+    if (word !== undefined) {
+      const span: Element = {
+        type: "element",
+        tagName: "span",
+        properties: { className: ["sd-word"] },
+        children: [{ type: "text", value: word } satisfies Text],
+      };
+      out.push(span);
+    } else if (ws !== undefined) {
+      out.push({ type: "text", value: ws });
+    }
+  }
+  return out;
+}
+
+function isElement(node: ElementContent | RootContent): node is Element {
+  return node.type === "element";
+}
+
+function isText(node: ElementContent | RootContent): node is Text {
+  return node.type === "text";
+}
+
+function transformChildren(parent: { children: ElementContent[] | RootContent[] }): void {
+  // Re-allocate `children` so we can replace single text nodes with a sequence.
+  const next: ElementContent[] = [];
+  for (const child of parent.children as ElementContent[]) {
+    if (isText(child)) {
+      next.push(...splitTextIntoWordSpans(child.value));
+      continue;
+    }
+    if (isElement(child)) {
+      if (SKIP_TAGS.has(child.tagName) || hasSkipClass(child)) {
+        next.push(child); // do not descend
+        continue;
+      }
+      transformChildren(child);
+      next.push(child);
+      continue;
+    }
+    next.push(child);
+  }
+  parent.children = next;
+}
+
+/**
+ * Standalone transform function. Exported separately from the plugin wrapper
+ * so unit tests can drive it directly without spinning up a unified processor.
+ */
+export function transformWordsForFade(tree: Root): void {
+  transformChildren(tree);
+}
+
+export const rehypeSplitWordsForFade: Plugin<[], Root> = () => {
+  return (tree) => {
+    transformWordsForFade(tree);
+  };
+};

src/browser/styles/globals.css

@@ -1542,57 +1542,46 @@ code {
   white-space: normal;
 }
 
-/* Per-block fade-in for streaming content.
+/* Per-word blur-fade-in for streaming markdown content.
  *
- * Streamdown gives us per-block element identity for free: each top-level
- * markdown block (paragraph, heading, list, fence, blockquote, table, hr) is
- * keyed by its index inside Streamdown's render and reconciled in place when
- * its content grows. So a CSS animation on a freshly-mounted child fires
- * exactly once per new top-level block — never for text appended inside a
- * still-open block. This gives users the "line-by-line fade-in" feel without
- * any JS bookkeeping.
+ * Each whitespace-bounded word in a streaming message is wrapped in
+ * `<span class="sd-word">` by `rehypeSplitWordsForFade` (see MarkdownCore).
+ * On mount, each span animates from `filter: blur(6px); opacity: 0` to its
+ * final state — giving the soft per-word reveal users associate with modern
+ * AI chat transcripts (Grok, flowtoken, etc.).
+ *
+ * Why per-word, not per-block:
+ *  - Per-block fired once per paragraph at mount, then text grew silently
+ *    inside. Reasoning/thinking blocks are typically one big paragraph, so the
+ *    effect was invisible there.
+ *  - Per-word also animates inside an already-mounted paragraph: each new
+ *    whitespace boundary mounts a fresh span → animation fires once for that
+ *    word and only that word. Stable identity at every word position keeps
+ *    completed words static while only new words fade in.
  *
  * Gating:
- *  - data-streaming="true" is set by TypewriterMarkdown only while isStreaming.
- *    Historical/replay messages render without the attribute and skip the rule.
- *  - prefers-reduced-motion: no-preference scopes the rule to users who haven't
- *    asked for reduced motion. Reduced-motion users see instant rendering.
+ *  - `[data-streaming="true"]` is set by TypewriterMarkdown only on LIVE
+ *    streams (not replay, not completed). Historical transcripts render
+ *    without the attribute and skip the rule entirely.
+ *  - `prefers-reduced-motion: no-preference` honors accessibility settings:
+ *    users who request reduced motion see instant rendering.
  *
- * Selector scope:
- *  - Block-level descendants only — explicitly enumerated. Inline elements
- *    (<strong>/<em>/<a>) are intentionally excluded because parseIncompleteMarkdown
- *    can transiently insert/remove them mid-stream as remend repairs unterminated
- *    tokens, which would over-fire the animation and look glitchy.
- *  - `> X` for top-level blocks; bare `li` so list items inside any (possibly
- *    nested) <ul>/<ol> still animate as they arrive.
- */
-@keyframes stream-block-fade-in {
+ * `<pre>`/`<code>`/KaTeX/Mermaid subtrees are excluded by the rehype plugin,
+ * so this rule never matches inside them. */
+@keyframes sd-word-blur-in {
   from {
+    filter: blur(6px);
     opacity: 0;
-    transform: translateY(2px);
   }
   to {
+    filter: blur(0);
     opacity: 1;
-    transform: translateY(0);
   }
 }
 
 @media (prefers-reduced-motion: no-preference) {
-  .markdown-content[data-streaming="true"] .streamdown-root > p,
-  .markdown-content[data-streaming="true"] .streamdown-root > h1,
-  .markdown-content[data-streaming="true"] .streamdown-root > h2,
-  .markdown-content[data-streaming="true"] .streamdown-root > h3,
-  .markdown-content[data-streaming="true"] .streamdown-root > h4,
-  .markdown-content[data-streaming="true"] .streamdown-root > h5,
-  .markdown-content[data-streaming="true"] .streamdown-root > h6,
-  .markdown-content[data-streaming="true"] .streamdown-root > ul,
-  .markdown-content[data-streaming="true"] .streamdown-root > ol,
-  .markdown-content[data-streaming="true"] .streamdown-root > blockquote,
-  .markdown-content[data-streaming="true"] .streamdown-root > pre,
-  .markdown-content[data-streaming="true"] .streamdown-root > hr,
-  .markdown-content[data-streaming="true"] .streamdown-root > table,
-  .markdown-content[data-streaming="true"] .streamdown-root li {
-    animation: stream-block-fade-in 180ms ease-out;
+  .markdown-content[data-streaming="true"] .sd-word {
+    animation: sd-word-blur-in 500ms ease-out;
   }
 }