fix(deps): take fumadocs 16.15.15, which fixes bold text in a built portal

[sohail2721]

Fixes apimatic/apimatic-io#2260. Supersedes #384, which pinned the transitive dependency instead; close that one if this lands.

The bug

apimatic portal generate failed on generated/sdks/python.mdx with RangeError: Maximum call stack size exceeded, while quickstart on the same project was fine — quickstart ends at portal serve, a dev server, and never runs the production build.

Only Python failed because python.md is the only SDK doc carrying a **bold** (**identical method names**, in the async-client paragraph). csharp.md and typescript.md contain no ** at all. Nothing is Python-specific in principle: any bold in included SDK docs, or in user content, breaks the build.

Cause

mdast-util-to-markdown@2.1.3 (published 2026-09-27 09:31 UTC; the issue was filed at 15:01) moved emphasis handling off the strong handler onto a property of it:

strong.attention = attention                              // strong.js:8

phrasing checks for that property and, finding it, emits the markers and recurses into the node's children, which terminates. The handler is now only a fallback, and it does this:

export function strong(node, _, state, info) {
  return state.containerPhrasing({type: 'root', children: [node]}, info)   // strong.js:29
}                                                          //          ^^^^ the same node

fumadocs-core replaced every handler with a bare closure, copying no properties. .attention disappeared, the terminating branch was never taken, and the fallback handed the same node back forever:

phrasing → handle.attention? NO → state.handle(child) → fumadocs wrapper
  → strong → containerPhrasing({root, children:[THE SAME NODE]}) → phrasing → …

fumadocs-core@16.15.15 keeps the properties on the wrapper:

return Object.assign(wrapped, handler);

Reported upstream as fuma-nama/fumadocs#3604 — filed 15:03, closed 15:15, released 15:17.

What moves

fumadocs-ui peer-depends on fumadocs-core at exactly the same version, so both go 16.15.8 → 16.15.15. fumadocs-openapi@11.4.1 peers ^16.15.0 and fumadocs-mdx@15.4.0 peers ^16.15.3; neither needs to move.

Breaking changes, in patch releases

llms(source).index() became asynchronous, and that is why the second commit exists:

	16.15.8	16.15.15
index()	=> string	=> Promise<string>
indexNode()	=> string	=> Promise<string>

Without the fix, llms.txt was written as the literal text [object Promise]. renderIndex is now async and the route awaits it. Nothing here calls indexNode.

The export surface moved too:

package	change
fumadocs-core	./mcp added
fumadocs-ui	./components/toc/block added
fumadocs-ui	./components/ui/scroll-area removed

We import none of those, and the removed one is now an internal @radix-ui/react-scroll-area import, so nothing dangles. Underneath it is not a small bump: 24 of 91 core modules and 55 of 126 ui modules changed.

Release-age quarantine

pnpm-workspace.yaml sets minimumReleaseAge: 10080 (7 days), which would block 16.15.15 until about 2026-10-04. This adds the three packages to minimumReleaseAgeExclude rather than lowering the gate, so the policy still stands for everything else. The exemption should come out once those dates pass.

Worth saying plainly: that quarantine is the reason our lockfile never took 2.1.3 and our builds stayed green while user installs broke. It protects us and not them, because npm i -g has no such rule. That gap is worth addressing separately.

Verified

Built with the exact combination that was fatal — fumadocs 16.15.15 with mdast-util-to-markdown at 2.1.3:

• APIMATIC_E2E=1 npm test: 1468 passing, 0 failing, eslint clean
• apimatic portal generate succeeds: 7 pages, search index and llms-full.txt written
• a global install of the packed tarball resolves 16.15.15 + 2.1.3 with the fix present

Rendered output diffed against a 16.15.8 build of the same project, comparing the visible text of every page:

• same 9 pages, llms-full.txt byte-identical
• zero words removed on any page
• the 1856 added words are not content. 16.15.15 moves the heading and code-block copy-button labels out of aria-label into an sr-only span, so Copy, Anchor, Link and Text now live in the text layer. The buttons already existed, nothing became visible, and a heading's textContent now reads InstallationCopy Anchor Link. The search index, the TOC and the Markdown twins come from the MDX AST and carry none of it — measured as 0 occurrences in api/search.json, llms.txt, llms-full.txt and sdks/*.md

What is not covered

The render diff is one project (three SDK languages, one spec, a plugin page). A portal with richer content — versioned docs, deeper navigation, more MDX components — has not been compared. Given that a patch release silently changed a return type to a promise, a second look before merge is worth the time.

🤖 Generated with Claude Code

[sohail2721]

Second verification, on a much richer portal

The earlier render diff was a 7-page project. Repeated it on a 123-page one — a Twilio Conversations portal: an 856 KB OpenAPI document, 14 hand-written Markdown pages across guides/, recipes/ and sample-apps/, 176 bold markers (the construct that caused the bug), 64 headings, 76 code fences, 7 tables, blockquotes, images and 37 links, plus SDK pages for three languages and a plugin page.

Built the same project twice — dev at fumadocs 16.15.8, this branch at 16.15.15 — and compared the visible text of every page:

	result
pages	125, identical set
pages changed	122
words removed	0
words added	1856
distinct words added	Copy (698), Anchor (460), Link (460), Text (238)
llms.txt	byte-identical, 20,672 bytes
llms-full.txt	2 lines differ

Every addition is a copy-to-clipboard label on a heading or code block. Nothing was lost on any page.

The two llms-full.txt lines are an improvement, not a regression:

- ::: </Accordion>
+ :::
+ </Accordion>

A ::: directive terminator belongs on its own line; emitting it followed by a JSX close tag on the same line was malformed.

llms.txt being byte-identical also confirms the async fix in the second commit works against the real 16.15.15 — it is the file that was otherwise written as the literal [object Promise].

APIMATIC_E2E=1 npm test against genuine 16.15.15: 1468 passing, eslint clean.

Correction to the earlier numbers

My first run of this comparison was invalid and I want that on the record: after switching back to this branch I had pushed and packed without re-running pnpm install, so node_modules still held the previous branch's 16.15.8 while package.json declared 16.15.15. I was reading the declared version, not the installed one, and comparing 16.15.8 against itself. The numbers above are from builds where the installed version was verified directly. The local test figure quoted earlier in this PR had the same flaw; the run above does not.

[saeedjamshaid]

Please correct the description, since it is the record of what this bump changed:

• The API-change table misses the one change that needed code: llms(source).index() now returns a promise, which 6e16ecc handles in llms.server.ts and llms[.]txt.ts.
• "No content changed" and "new copy-to-clipboard buttons" aren't accurate. The heading and code-block buttons already existed. 16.15.15 moves their label from aria-label into an sr-only span inside the element, so every heading's text now ends in "Copy Anchor Link" (for example, <h2 id="installation"> reads InstallationCopy Anchor Link), and code blocks gain "Copy Text".

[saeedjamshaid]

In 16.15.15, ViewOptionsPopover builds the "Read {url}" prompt from window.location.href unless a pageUrl prop is passed. 16.15.8 used new URL(pathname, window.location.origin). We don't pass pageUrl (portal-template/src/routes/$.tsx:145), so a reader's query string and hash, such as tracking or preview parameters, now go to ChatGPT, Claude and the other vendors. Please pass a pageUrl built from origin and path so only those are sent, as before.

[saeedjamshaid]

Still open: #382 moved the popover to portal-template/src/components/page-header.tsx:18, and it still renders <ViewOptionsPopover markdownUrl={markdownUrl} /> with no pageUrl, so the prompt still carries the reader's full URL, query string and hash included.

[saeedjamshaid]

@sohail2721 this is the last open point from my review, and it isn't in your "Still open" list, so flagging it again. On 5ab53eb, portal-template/src/components/page-header.tsx:18 still renders <ViewOptionsPopover markdownUrl={markdownUrl} /> without pageUrl, so the prompt sent to the AI vendors carries the reader's query string and hash.

[sohail2721]

Both addressed — thank you, the second one in particular found something neither the pin nor this bump was accounting for.

lucide-react duplicate

Confirmed, and it is this branch that introduced it:

	wants	our pin 1.43.0
fumadocs-ui@16.15.8	^1.39.0	satisfies — one copy
fumadocs-ui@16.15.15	^1.47.0	does not — two copies

Pinned to 1.47.0 rather than 1.48.0: 1.48.0 is 4 days old and would need a third minimumReleaseAgeExclude entry, while 1.47.0 is 11 days old and satisfies ^1.47.0 on its own.

That alone left fumadocs-openapi and @fumadocs/api-docs still resolving 1.43.0, so pnpm dedupe followed. The lockfile now holds exactly one lucide-react, 1.47.0, with no edge pointing anywhere else. Dedupe also collapsed a duplicate yaml, settling it on 2.9.1 — inside the ^2.8.0 already declared, and disclosed here since it is not a fumadocs change.

Emphasis coverage

Added your line to SDK_DOCS and a test reading it back from sdks/typescript.md, llms-full.txt and the rendered page.

It behaves exactly as you said:

• this branch — passes
• dev's dependencies, same test — fails: expected '# TypeScript SDK…' to include 'Use **identical method names**…'

And your ** is right. Isolating the serializer at each version:

wrapper drops .peek (16.15.8)   "Use **identical method names**, **(identical)** and *`code`* here."
wrapper keeps .peek (16.15.15)  "Use **identical method names**, **(identical)** and *`code`* here."

Worth drawing out, because it changes what this PR is: dev corrupts emphasis today. Any bold or italic in SDK docs already reaches sdks/*.md and llms-full.txt with * in place of the markers — silently, in the files the AI page actions and llms.txt consumers read. The stack overflow in #2260 was the same dropped-properties defect becoming fatal once 2.1.3 made .attention load-bearing; .peek had been dropped all along and was merely disfiguring the output.

So this is not only a fix for a build that fails — it is a fix for output that was already wrong.

APIMATIC_E2E=1 npm test: 1469 passing, eslint clean.

[sohail2721]

Merged dev in (5ab53eb) and re-verified. The branch was three commits behind, and one of them mattered.

Why it needed re-verifying

dev had moved on since this branched from d71d23f:

#383	stop printing an operation's raw description under its title
#386	render a request body in a media type Fumadocs has no adapter for
#382	offer the page actions on API reference pages

All three touch portal-template/, and #386 is a workaround for a Fumadocs limitation — exactly the kind of code a Fumadocs bump can invalidate, if 16.15.15 now ships the adapter it compensates for or changes the shape it hooks into. Everything verified earlier in this PR was measured against a base that no longer existed.

The merge was clean; test/e2e/portal-build.test.ts auto-merged despite both sides editing it.

Re-verified on the merge

APIMATIC_E2E=1 npm test: 1475 passing (up from 1469 — dev's new cases), eslint clean, build clean.

#386's workaround specifically, on 16.15.15:

mediaAdapters
  ✔ sends text and a file as the reader entered them
  ✔ sends an object the playground built from the schema as JSON
  ✔ names each type the way Fumadocs looks it up

Plus the page actions from #382, and the emphasis test, all passing together.

Render diff, redone against the new dev

Same 123-page Twilio portal, built from this merge and from dev at 22f4873:

pages	125, identical set
changed	122
words removed	0
words added	1856 — Copy (698), Anchor (460), Link (460), Text (238)
llms.txt	byte-identical, 20,672 bytes
llms-full.txt	the same 2 lines, ::: moved onto its own line

Unchanged from the earlier measurement, now against a base that exists. The additions are still only copy-button labels.

Still open

• CI is running on the merge; ubuntu passed before the merge, the rest are in flight.
• This needs an approving review — reviewDecision is REVIEW_REQUIRED.
• The minimumReleaseAgeExclude entries should come out after 2026-10-04.
• fix(deps): pin mdast-util-to-markdown, which a published install lets drift #384 is redundant if this lands.
• Not covered by any of the above: the icons. lucide-react moved 1.43.0 → 1.47.0, and the template draws ChevronRight, Code, Download and Package from it. The builds prove those still exist; whether any was redrawn is a visual question a text diff cannot answer, and worth a glance at a built portal before merging.

[saeedjamshaid]

Following up on the description point from my review: the new llms().index() section and dropping "no content changed" cover most of it. One part is left. The Verified section still calls Copy, Anchor, Link and Text labels on new copy-to-clipboard buttons. Those buttons were already there: 16.15.15 moves their label from aria-label into an sr-only span, so every heading's text now ends in "Copy Anchor Link" (<h2 id="installation"> reads InstallationCopy Anchor Link), and code blocks gain "Copy Text".

[sohail2721]

You are right, and the correction is bigger than the wording — thank you for not letting it stand.

I verified the component. 16.15.8 put the label on the button:

jsx("button", { "aria-label": t("Copy Anchor Link", …), children: <LinkIcon/> })

16.15.15 moves it inside as real markup, and adds aria-live:

jsxs("button", { "aria-live": "polite", children: [<LinkIcon/>,
  jsx("span", { className: "sr-only", children: isChecked ? t("Copied Anchor Link") : t("Copy Anchor Link") })] })

So the button was always there, and what changed is where its label lives. The rendered heading is now:

<h2 id="installation" class="group/heading …">
  <a data-card="" href="#installation">Installation</a>
  <button aria-live="polite" …>[icon]<span class="sr-only">Copy Anchor Link</span></button>
</h2>

Its textContent is InstallationCopy Anchor Link, exactly as you said. My diff read extracted text, so it counted those spans and I reported them as new buttons. Wrong on both counts — nothing was added, and nothing is visible.

The upstream reason looks deliberate rather than accidental: an aria-label never announces its own change, so the Copy → Copied transition was silent. An aria-live region with real text announces it. The cost is that the heading's accessible name now absorbs the button's label.

Where it does and does not reach

Since "every heading's text now ends in Copy Anchor Link" could plausibly leak into what we index and export, I measured rather than assumed, on a built portal:

api/search.json	0 occurrences
llms.txt, llms-full.txt, sdks/*.md	0
TOC entry for #installation	"Installation"
the heading's own <a>	"Installation"
sr-only spans on the page	5, one per heading

Everything built from the MDX AST — the search index, the TOC, the Markdown twins — is untouched. The change is confined to the rendered DOM's accessible text. Visually nothing moves, because sr-only is visually hidden.

So the honest summary of that 1856-word delta: not one word of content was added or removed. It is the same labels, relocated from an attribute into the text layer, and my diffing method could not tell those apart. I have corrected the Verified section to say so.

Two consequences worth keeping in view, neither blocking:

• A screen reader reading the heading now hears the button's label as part of it.
• Anything asserting on a heading's textContent will see the suffix. Nothing in our suite does today, but it is a trap for whoever writes such a test next.

[saeedjamshaid]

On the icons question in your last "Still open" list: I compared every icon between lucide-react 1.43.0 and 1.47.0. 17 changed shape, and none of them is among the icons imported by the template (ChevronRight, Code, Download, Package), fumadocs-ui 16.15.15, fumadocs-openapi or @fumadocs/api-docs. Aliases such as Edit → square-pen were followed to their real files. No icon the portal draws was redrawn, so that one needs no visual check.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[github-actions]

🎉 This PR is included in version 2.0.0-beta.1 🎉

The release is available on:

• npm package (@beta dist-tag)
• GitHub release

Your semantic-release bot 📦🚀