Fix animate plugin whitespace handling in word splitting (especially inside links)

.changeset/loud-memes-move.md

@@ -0,0 +1,5 @@
+---
+"streamdown": minor
+---
+
+Fix word splitting logic to correctly merge whitespace with preceding tokens in animation pipeline

packages/streamdown/__tests__/animate.test.ts

@@ -6,6 +6,11 @@ import { animate, createAnimatePlugin } from "../lib/animate";
 
 const SPAN_GAP_RE = /<\/span>\s+<span/;
 const CODE_CONTENT_RE = /<code>([^<]*)<\/code>/;
+const LINK_PATTERN_RE =
+  /<a href="\/">\s*<span[^>]*>Hello <\/span><span[^>]*>world<\/span><\/a>/;
+
+const LINK_PATTERN_LEADING_SPACE_RE =
+  /<a href="\/"> <span[^>]*>Hello <\/span><span[^>]*>world<\/span><\/a>/;
 
 const processHtml = async (html: string, plugin = animate) => {
   const processor = unified()
@@ -281,4 +286,86 @@ describe("animate plugin", () => {
       expect(delays).toEqual([]);
     });
   });
+
+  describe("link whitespace behavior", () => {
+    it("should attach whitespace inside links", async () => {
+      const result = await processHtml(
+        '<a href="https://example.com">Hello world</a>'
+      );
+
+      expect(result).toContain(">Hello ");
+      expect(result).toContain(">world<");
+    });
+
+    it("should attach whitespace to the preceding animated word inside links", async () => {
+      const result = await processHtml('<a href="/">Hello world</a>');
+      expect(result).toMatch(LINK_PATTERN_RE);
+    });
+
+    it("should preserve whitespace between spans in normal text", async () => {
+      const result = await processHtml("<p>Hello world</p>");
+
+      expect(result).toMatch(SPAN_GAP_RE);
+    });
+
+    it("should preserve leading whitespace before the first animated link word", async () => {
+      const result = await processHtml('<a href="/"> Hello world</a>');
+      expect(result).toMatch(LINK_PATTERN_LEADING_SPACE_RE);
+    });
+
+    it("should keep character splitting unchanged inside links", async () => {
+      const plugin = createAnimatePlugin({ sep: "char" });
+      const result = await processHtml('<a href="/">Hi there</a>', plugin);
+      expect(result).toMatch(SPAN_GAP_RE);
+      expect(result).toContain(">H<");
+      expect(result).toContain(">i<");
+      expect(result).toContain(">t<");
+    });
+
+    it("should only modify whitespace inside links in mixed content", async () => {
+      const result = await processHtml(
+        '<p>Hello <a href="#">linked text</a> world</p>'
+      );
+
+      // normal text should still have gaps
+      expect(result).toContain(">Hello<");
+      expect(result).toContain(">world<");
+
+      // link should have merged whitespace
+      expect(result).toContain(">linked ");
+    });
+
+    it("should handle multiple links independently", async () => {
+      const result = await processHtml(
+        '<p><a href="#">first link</a> and <a href="#">second link</a></p>'
+      );
+
+      const linkMatches = (result.match(/data-sd-animate/g) || []).length;
+
+      expect(linkMatches).toBeGreaterThan(2);
+      expect(result).toContain(">first ");
+      expect(result).toContain(">second ");
+    });
+
+    it("should handle nested formatting inside links", async () => {
+      const result = await processHtml(
+        '<a href="#"><strong>Hello world</strong></a>'
+      );
+
+      expect(result).toContain(">Hello ");
+      expect(result).toContain(">world<");
+    });
+
+    it("should handle single-word links", async () => {
+      const result = await processHtml('<a href="#">Hello</a>');
+
+      expect(result).toContain(">Hello<");
+    });
+
+    it("should not affect skip tags like code", async () => {
+      const result = await processHtml("<code>Hello world</code>");
+
+      expect(result).not.toContain("data-sd-animate");
+    });
+  });
 });

packages/streamdown/lib/animate.ts

@@ -161,9 +161,29 @@ const processTextNode = (
   }
 
   const parts = config.sep === "char" ? splitByChar(text) : splitByWord(text);
+
+  const isInsideLink = ancestors.some(
+    (ancestor) => isElement(ancestor) && ancestor.tagName === "a"
+  );
+
+  let finalParts = parts;
+
+  if (config.sep === "word" && isInsideLink) {
+    const merged: string[] = [];
+
+    for (const part of parts) {
+      if (WHITESPACE_ONLY_RE.test(part) && merged.length > 0) {
+        merged[merged.length - 1] += part;
+      } else {
+        merged.push(part);
+      }
+    }
+
+    finalParts = merged;
+  }
   const prevLen = renderState.prevContentLength;
 
-  const nodes: (Element | Text)[] = parts.map((part) => {
+  const nodes: (Element | Text)[] = finalParts.map((part) => {
     const partStart = charCounter.count;
     charCounter.count += part.length;
     if (WHITESPACE_ONLY_RE.test(part)) {