Diagram Markdown output should use its fallback instead of UI and SVG text

[MohamedH1998]

Problem

Nimbus diagrams produce noisy, misleading Markdown when rendered HTML is converted by Markdown for Agents. Diagram controls and SVG labels are concatenated instead of being replaced by a plain-language fallback.

For example:

Choose an instance identity to send a request

ABReset

RequestWORKERRequestWORKERDURABLE OBJECTAROUTEHOOKSSLEEP...

This is specific to Nimbus diagrams, not a request for generic MDX component transformation.

Existing API gap

DiagramProps declares fallback?: string in @cloudflare/nimbus-docs/react, but DiagramRoot does not destructure or render the prop. The browser therefore renders only the interactive .diagram-render subtree, and HTML-to-Markdown conversion extracts its controls and SVG text.

Expected behavior

• HTML continues to show the interactive diagram.
• Markdown output for a Nimbus Diagram contains only its plain-language fallback.
• Toolbar labels, live status text, duplicated responsive SVG content, and SVG node labels are omitted from Markdown.
• The existing fallback prop is implemented and documented for this purpose, or replaced with an equivalent diagram-specific API.

Example

<Diagram
  label="A request routing through a Worker and Durable Object"
  fallback="A request flows from the client to the Worker, through a Durable Object, and then to the Container."
>
  <InteractiveDiagram />
</Diagram>

The Markdown representation should be only:

A request flows from the client to the Worker, through a Durable Object, and then to the Container.

Version

Observed with @cloudflare/nimbus-docs 0.11.0.

[sansynx]

I checked DiagramRoot on current main and confirmed that the fallback prop is declared but never rendered. Before working on the markup, is there a supported way to tell Markdown for Agents to replace a subtree with fallback text? I couldn't find that contract in the conversion docs, and I don't want to hide the interactive diagram from assistive technology just to affect Markdown output

[MohamedH1998]

yeah that's a fair point @sansynx - will give this some thought