Fix glossary auto-linker nesting buttons (hydration error)

[jerelvelarde]

What this PR does

Fixes a bug in the glossary auto-linker (lib/remark-glossary.ts) that produces a <button> nested inside a <button> — invalid HTML that throws a React hydration error in the browser.

Root cause

remarkGlossary wraps each matched glossary term in a <GlossaryTerm>, which renders a <button> (the popover trigger). The text visitor matches a term, splices [before, <GlossaryTerm>, after] into the parent's children, and returns a bare SKIP.

When the term is matched mid-sentence (non-empty leading text), SKIP lands unist-util-visit on the newly-inserted <GlossaryTerm> node and descends into it. Its inner text is then re-scanned, and a shorter term contained in the matched text gets wrapped again — e.g. agent inside agent runtime — nesting one GlossaryTerm (button) inside another.

This only triggers when a multi-word term that contains a shorter term appears mid-sentence, which is why most pages don't hit it but a term-dense page can hit it several times.

The fix

Guard the text visitor so it never re-processes text already inside a GlossaryTerm it just inserted:

if (parent.type === "mdxJsxTextElement" && parent.name === "GlossaryTerm") {
  return SKIP;
}

This preserves existing behavior (trailing text after a wrapped term is still scanned for other terms) and only prevents the invalid nesting.

Test

Adds tests/remark-glossary.test.ts with a fixture glossary (tests/fixtures/glossary-nesting.mdx) where agent runtime contains agent. Two cases:

• a glossary term that appears mid-sentence is still linked;
• no GlossaryTerm is ever nested inside another.

The second test fails on the current code (reproduces the bug) and passes with the fix. Full suite stays green.

Surfaced while adding a term-dense framework guide (the reciprocal of CopilotKit/CopilotKit#5514); filing the infra fix separately so that PR stays scoped to docs content. Verified via the unit test — a live-render check was impractical because next dev --webpack was crash-prone in my environment (Node 24 vs the repo's Node 22), so please confirm in CI / a normal dev run.

cc @thierrypdamiba

🤖 Generated with Claude Code

[vercel]

@jerelvelarde is attempting to deploy a commit to the Arcade AI Team on Vercel.

A member of the Team first needs to authorize it.