fix(docs): Prevent CSSStyleSheet error in mermaid diagrams

[sentry]

DESCRIBE YOUR PR

Tell us what you're changing and why. If your PR resolves an issue, please link it so it closes automatically.

This PR addresses an issue where Mermaid diagrams would crash in certain in-app browsers (e.g., Google iOS app on iPad iOS 16.7.16).

Problem:
Mermaid.js (v11.15.0) attempts to use the new CSSStyleSheet() constructor (Constructable Stylesheets API) to build theme CSS. This API is not consistently supported across all WebViews, even if the underlying OS version (iOS 16.4+) theoretically supports it in the main browser (Safari). When new CSSStyleSheet() throws a TypeError: Illegal constructor, it results in an unhandled error, crashing the diagram rendering and breaking the page for the user.

Solution:

1. Feature Detection: Added a try/catch block around new CSSStyleSheet() at the beginning of the renderMermaid function in src/components/mermaid.tsx. If the constructor throws, the function now returns early, preventing the crash in unsupported environments.
2. Defense-in-Depth: Wrapped the mermaid.run() calls in a try/catch block to gracefully handle any other potential rendering failures from Mermaid.
3. Graceful Fallback: In case of a rendering failure (either from the feature detection or mermaid.run()), setDoneRendering(true) is still called. This ensures that the CSS responsible for hiding the duplicate .dark or .light mermaid block is applied, leaving a single, readable raw diagram source as a fallback for the user.

This change improves the robustness of Mermaid diagram rendering on the docs site, preventing crashes and providing a better user experience in less capable browser environments.

IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs to go live.

• Urgent deadline (GA date, etc.):
• Other deadline:
• None: Not urgent, can wait up to 1 week+

SLA

• Teamwork makes the dream work, so please add a reviewer to your PRs.
• Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it.
  Thanks in advance for your help!

PRE-MERGE CHECKLIST

Make sure you've checked the following before merging your changes:

• Checked Vercel preview for correctness, including links
• PR was reviewed and approved by any necessary SMEs (subject matter experts)
• PR was reviewed and approved by a member of the Sentry docs team

LEGAL BOILERPLATE

Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms.

EXTRA RESOURCES

• Sentry Docs contributor guide

Fixes DOCS-B2J

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
develop-docs	Ready	Preview	Aug 13, 2026 3:16pm
sentry-docs	Ready	Preview	Aug 13, 2026 3:16pm

[sergical]

good job seer