From c2c77c26e16e64e53cc5a9c7f299a9daef83b1e0 Mon Sep 17 00:00:00 2001
From: GeneralJerel <85066839+GeneralJerel@users.noreply.github.com>
Date: Wed, 24 Jun 2026 10:51:00 -0700
Subject: [PATCH] Fix glossary auto-linker nesting buttons (hydration error)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

remark-glossary wraps each matched term in a <GlossaryTerm>, which
renders a <button> (popover trigger). When a term matched mid-sentence
(non-empty leading text), the visitor returned a bare SKIP after
splicing, so unist-util-visit descended into the just-created
GlossaryTerm and re-wrapped a shorter contained term (e.g. "agent"
inside "agent runtime"). That nests a <button> in a <button> — invalid
HTML that throws a React hydration error.

Guard the text visitor so it never re-processes text already inside a
GlossaryTerm. Trailing text after a wrapped term is still scanned, so
term coverage is unchanged.

Add tests/remark-glossary.test.ts with a fixture glossary covering the
nested-term case (fails before this change) and confirming terms are
still linked.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 lib/remark-glossary.ts              | 11 +++++
 tests/fixtures/glossary-nesting.mdx |  9 ++++
 tests/remark-glossary.test.ts       | 66 +++++++++++++++++++++++++++++
 3 files changed, 86 insertions(+)
 create mode 100644 tests/fixtures/glossary-nesting.mdx
 create mode 100644 tests/remark-glossary.test.ts

diff --git a/lib/remark-glossary.ts b/lib/remark-glossary.ts
index 3b87950e6..95e7fec7f 100644
--- a/lib/remark-glossary.ts
+++ b/lib/remark-glossary.ts
@@ -78,6 +78,17 @@ export function remarkGlossary(options: RemarkGlossaryOptions) {
             return SKIP;
           }
 
+          // Skip text already inside a GlossaryTerm we inserted. After a term
+          // is wrapped mid-sentence the visitor descends into the new node;
+          // re-wrapping a shorter term here nests a <button> inside a
+          // <button> (invalid HTML that triggers a React hydration error).
+          if (
+            parent.type === "mdxJsxTextElement" &&
+            parent.name === "GlossaryTerm"
+          ) {
+            return SKIP;
+          }
+
           const markedTerms =
             markedTermsPerParagraph.get(paragraphNode) || new Set();
           let text = textNode.value;
diff --git a/tests/fixtures/glossary-nesting.mdx b/tests/fixtures/glossary-nesting.mdx
new file mode 100644
index 000000000..26dd5baf9
--- /dev/null
+++ b/tests/fixtures/glossary-nesting.mdx
@@ -0,0 +1,9 @@
+## Glossary
+
+### agent runtime
+
+The runtime that hosts and runs an agent.
+
+### agent
+
+An autonomous program that pursues a goal.
diff --git a/tests/remark-glossary.test.ts b/tests/remark-glossary.test.ts
new file mode 100644
index 000000000..19f8bac44
--- /dev/null
+++ b/tests/remark-glossary.test.ts
@@ -0,0 +1,66 @@
+import type { Root } from "mdast";
+import { visit } from "unist-util-visit";
+import { describe, expect, test } from "vitest";
+import { remarkGlossary } from "@/lib/remark-glossary";
+
+// A fixture glossary where one term ("agent runtime") contains a shorter
+// term ("agent"). When the longer term is matched mid-sentence, the plugin
+// must NOT then wrap "agent" inside the GlossaryTerm it just created —
+// GlossaryTerm renders a <button>, and a button inside a button is invalid
+// HTML that triggers a React hydration error.
+const GLOSSARY_FIXTURE = "tests/fixtures/glossary-nesting.mdx";
+
+type JsxNode = { type: string; name?: string };
+
+function buildParagraph(text: string): Root {
+  return {
+    type: "root",
+    children: [
+      { type: "paragraph", children: [{ type: "text", value: text }] },
+    ],
+  } as Root;
+}
+
+function countGlossaryTerms(tree: Root): { total: number; nested: number } {
+  let total = 0;
+  let nested = 0;
+  visit(tree, (node) => {
+    const outer = node as JsxNode;
+    if (outer.type === "mdxJsxTextElement" && outer.name === "GlossaryTerm") {
+      total += 1;
+      visit(node, (descendant) => {
+        if (descendant === node) {
+          return;
+        }
+        const inner = descendant as JsxNode;
+        if (
+          inner.type === "mdxJsxTextElement" &&
+          inner.name === "GlossaryTerm"
+        ) {
+          nested += 1;
+        }
+      });
+    }
+  });
+  return { total, nested };
+}
+
+describe("remarkGlossary", () => {
+  test("links a glossary term that appears mid-sentence", () => {
+    const tree = buildParagraph("Use the agent runtime here.");
+    remarkGlossary({ glossaryPath: GLOSSARY_FIXTURE })(tree, {
+      history: ["/tmp/test-page.mdx"],
+    });
+    const { total } = countGlossaryTerms(tree);
+    expect(total).toBeGreaterThan(0);
+  });
+
+  test("never nests one GlossaryTerm inside another (no button-in-button)", () => {
+    const tree = buildParagraph("Use the agent runtime here.");
+    remarkGlossary({ glossaryPath: GLOSSARY_FIXTURE })(tree, {
+      history: ["/tmp/test-page.mdx"],
+    });
+    const { nested } = countGlossaryTerms(tree);
+    expect(nested).toBe(0);
+  });
+});