fix: isolate docs pages that embed a WebContainer example

[AlemTuzlak]

WebContainer needs COOP/COEP so the page is cross-origin isolated. The Examples tab already sends those headers. Tutorial docs pages did not, so a ::client-example embed on /ai/latest/docs/tutorials/basic-chat failed with "WebContainer requires cross-origin isolation."

This PR reads the markdown for ::client-example comments. If the example boots a WebContainer, the docs page gets the same isolation headers as the Examples tab.

Testing

1. Commands run. pnpm exec tsx --test tests/docs-embed-headers.test.ts passed.
2. Manual test. Open /ai/latest/docs/tutorials/basic-chat after deploy. window.crossOriginIsolated should be true. The live sandbox should boot.
3. How this PR makes testing easy. Unit tests cover a real comment, a page with no comment, and a bad slug.

Risk / rollback

COEP credentialless can affect third-party scripts on those docs pages only. Revert this PR to restore cache-only headers. Other docs pages are unchanged.

Summary by CodeRabbit

• Bug Fixes

  • Improved documentation pages with embedded client examples that use an interactive runtime, helping them load and operate correctly.
  • Added safeguards so unsupported or malformed embedded examples do not affect documentation page behavior.

• Tests

  • Added coverage for embedded runtime headers, standard documentation pages, and invalid example configurations.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: ff81a330-0e33-4a73-9eaf-0e97b73f9ff5

📥 Commits

Reviewing files that changed from the base of the PR and between 55c5a3b and d0bb085.

📒 Files selected for processing (4)

• src/routes/_library/$libraryId/$version.docs.$.tsx
• src/routes/_library/$libraryId/$version.docs.framework.$framework.$.tsx
• src/utils/docs-embed-headers.ts
• tests/docs-embed-headers.test.ts

Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds a helper that detects WebContainer client examples in documentation content. Both documentation routes use the helper to add runtime headers alongside cache headers. Tests cover matching, missing, and rejected examples.

Changes

Documentation embed runtime handling

Layer / File(s)	Summary
Runtime header detection and validation src/utils/docs-embed-headers.ts, tests/docs-embed-headers.test.ts	getDocsEmbedRuntimeHeaders parses ::client-example comments and returns WebContainer headers for matching configurations. Tests cover valid, absent, and rejected examples.
Documentation route response headers src/routes/_library/$libraryId/$version.docs.$.tsx, src/routes/_library/$libraryId/$version.docs.framework.$framework.$.tsx	Both routes merge content- and version-dependent embed headers with existing documentation cache headers.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Suggested reviewers: tannerlinsley

Merge Risk: ⚪ Minimal · up to d0bb0

The documentation header handling is ready to merge with normal checks.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding isolation headers to documentation pages that embed WebContainer examples.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 4 files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}