internal(website): Reorganize Playground into editor/monaco/preview

[ntucker]

Requested by Nathaniel · project thread

Motivation

Before: the Playground folder mixed Monaco bootstrap, preview execution, editor UI and shared chrome at one level; monaco-init.ts was a 362-line side-effect module; the SSR / incremental-loading / mobile / crawler behaviors lived only in scattered comments, so a cleanup could drop one silently. Import completions offered files from every playground on the page, and unquoted path= metastrings were ignored.

After: the same behavior, organized by concern, with a Playground/README.md that lists every invariant (SSG markup, chunking and CDN hints, mobile/bot fallbacks, hidden Demo tabs, editor and preview behaviors) to check changes against. Import completions list only the current playground's files, and path=Todo.ts works like path="Todo.ts".

Solution

• monaco/: setup.ts (the side-effect entry: UA gate, resource hints, CDN loader, compiler options), typeLibs.ts (table-driven; same webpack chunk names, lazy-once data-client chunk, fetch and addExtraLib order), theme.ts, navigation.ts (cross-tab go-to-definition + import completions, now scoped per playground via siblingFilePaths), modelPath.ts (the /<id>/<path> URI scheme that used to be a cross-file comment), highlightSelections.ts (pure, tested), plus moved options, language, resourceHints, generated preloadManifest (generator path updated), useAutoHeight.
• editor/: InteractiveEditor (was PlaygroundMonacoEditor; Monaco on desktop, editable react-live on mobile/bots, client-only) and StaticEditor (the SSR/crawler/loading markup, previously duplicated). TextEditTab collapses its two branches into one. codeModel accepts quoted or bare path=.
• preview/: Preview, PreviewBlock, PreviewWrapper, StoreInspector, Tree, FixturePreview, transformCode, temporal join LivePreview/scope.
• userAgent.ts: one definition of the bot and mobile regexes; isGoogleBot → isBot (it matched every crawler).
• Kept for now (Nathaniel's call; Staff deletion request waived): PlaygroundEditor / PlaygroundLiveEditor entry points (now aliasing the new editor modules), DiffEditorChooser, the readOnly prop, and Playground/resources/.
• HooksPlayground reuses PlaygroundProps instead of a duplicate interface. raw-plugin.js warning filter now targets monaco/typeLibs.ts.

Verification

• yarn test --selectProjects ReactDOM --testPathPatterns website/src/components/Playground: 4 suites, 19 tests pass (new ones cover highlight selections, model paths, sibling files and bare path=); website typecheck and lint clean.
• Full docusaurus build on master and on the reorg: same 265 asset files with the same named chunks (PreviewWithScope, PreviewBlock, *DTS), no new warnings, and all 170 generated HTML pages identical after normalizing hashed class names and script tags (the one remaining diff is a build-time timestamp in a fixture).
• Adversarial review (Fable) of the full diff found no behavior regressions.

Follow-ups (own PRs)

• typeLibs.ts adds extra libs as declare globals { … }, which is not TypeScript syntax (declare global); needs an in-browser check that the fix adds no new diagnostics.
• Unused website files: website/ambientsource-plugin.js, website/src/components/useIntersectionObserver.tsx, website/src/components/Demo/Demo.module.css (pending Nathaniel's OK).

Dispositions for every review follow-up (folded, moved or rejected, with reasons): #4104 (comment)

🤖 Generated with Claude Code

https://claude.ai/code/session_015H36Yk4WBpytw9L7RRVCTK

---

Note

Medium Risk
Large structural refactor of hydration-sensitive playground and Monaco bootstrap code; behavior is intended to be unchanged but regressions in SSR, lazy loading, or editor navigation would affect every docs page with live examples.

Overview
Reorganizes the docs Playground by concern (editor/, monaco/, preview/) and documents SSR, chunking, mobile/bot, and hidden-tab invariants in Playground/README.md. The old monaco-init.ts and PlaygroundMonacoEditor are replaced by monaco/setup.ts plus smaller modules (typeLibs, theme, navigation, modelPath, highlightSelections) and InteractiveEditor with a shared StaticEditor for SSG/hydration placeholders.

Behavior tweaks: relative import completions use siblingFilePaths so only files in the same playground are offered; fence metastrings accept bare path= / title=; crawler detection is centralized as isBot in userAgent.ts (was isGoogleBot). HooksPlayground imports PlaygroundProps from Playground; webpack warning suppression and the Monaco preload generator point at the new monaco/ paths.

^{Reviewed by Cursor Bugbot for commit 5b856f4. Bugbot is set up for automated code reviews on this repo. Configure here.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 5b856f4

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

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

Project	Deployment	Actions	Updated
docs-site	Ready	Preview	Oct 4, 2026 4:09pm UTC

[ntucker]

The typecheck check (Vercel Preview Deployment workflow) fails on src/components/HomepageFeatures.tsx(80,5), a file this PR doesn't touch. The error comes from two copies of @types/react (@docusaurus/theme-common/node_modules/@types/react vs the root one) making the SVG module type incompatible with SvgComponent. The same check is red on the recent runs for #4059 and #4103, and I reproduced the identical three errors on a clean master checkout locally; there are no other typecheck errors with this PR's changes. No fix exists yet, so I'm not widening this PR for it; deduping @types/react (or loosening SvgComponent to accept the SVGR component type) would clear it.

---

Generated by Claude Code

[ntucker]

LGTM (+ FOLLOW_UP after merge). First Staff pass on cd885d85.

Behavior-neutral reorg checks out: monaco/ / editor/ / preview/ split preserves CDN hints, webpack chunk names (PreviewWithScope, PreviewBlock, *DTS, lazy-once data-client), UA gates (isBot / isMobileOrBot), hidden-Demo latch, SSR StaticEditor markup, and DiffEditor mobile/bot fallback. Alias removals (PlaygroundEditor, PlaygroundLiveEditor, DiffEditorChooser) and resources/ deletion look unused. TextEditTab collapse and HooksPlayground → shared PlaygroundProps are equivalent. New pure tests for highlightSelections / modelPath are real, not rubber stamps. README invariants are the right entropy hedge here.

Draft: Bugbot not required until Ready (Lead owns Ready after /simplify). Website typecheck red on HomepageFeatures.tsx is pre-existing on master (author note); not introduced here.

FOLLOW_UP (do not block merge)

1. monaco/typeLibs.ts: declare globals { … } is not valid TS (declare global). Same pre-existing bug the PR correctly left alone for neutrality — fix post-merge so React / NumberFlow / Temporal preview globals actually typecheck in Monaco.
2. Dead website files still present (called out in PR open questions): website/ambientsource-plugin.js, website/src/components/useIntersectionObserver.tsx, website/src/components/Demo/Demo.module.css — delete in a cleanup PR once unused is confirmed.
3. Optional later: fixtures never shown in row layout; import completions list models from every playground on the page; unquoted path= metastrings — all pre-existing, fine as separate PRs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.01%. Comparing base (f03332e) to head (5b856f4).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #4104      +/-   ##
==========================================
+ Coverage   97.93%   98.01%   +0.08%     
==========================================
  Files         158      160       +2     
  Lines        3095     3127      +32     
  Branches      619      622       +3     
==========================================
+ Hits         3031     3065      +34     
  Misses         18       18              
+ Partials       46       44       -2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[ntucker]

CHANGE_THIS_PR — tip cf2de88e restores dead code Staff already blessed deleting on cd885d85 (review). “Kept for future use (per review)” misreads that note: Staff said the removals looked unused, not that they should come back.

Please undo the mistaken restore:

1. Delete website/src/components/Playground/resources/ again (PlaceholderBaseResource.ts, TodoResource.ts). Still zero importers; README already says “currently unreferenced”; examples/Demo own their own copies. Dead sample code bitrots.

2. Delete DiffEditorChooser.tsx and have DiffEditor.tsx import DiffEditorMonaco directly (as on the Staff-reviewed tip). The chooser is a no-op alias; SSR/mobile/bot handling already lives inside DiffEditorMonaco.

3. Drop the unused readOnly prop on InteractiveEditor (and the editorOptions useMemo). No caller passes it; cd885d85 / the initial reorg commit already removed it as unused. Pass shared options through again.

PlaygroundLiveEditor can stay — InteractiveEditor actually uses it for the mobile/bot path. Optional polish (not required): EditorSurface can import InteractiveEditor directly instead of the PlaygroundEditor alias.

Hold merge until this lands and Bugbot is green on the tip.

[ntucker]

Lead Engineer: 82bf2d06 puts back the deletions Staff already accepted. Review: #4104 (review)

Why. cf2de88e restored dead Playground code and said it was "kept for future use." Nothing outside that code used it.

What was checked before deleting.

• website/src/components/Playground/resources/ (PlaceholderBaseResource.ts, TodoResource.ts) is only referenced inside that folder. Docs and examples have their own copies.
• DiffEditorChooser.tsx was only imported by DiffEditor.tsx. DiffEditor now imports DiffEditorMonaco directly, which is what it did before cf2de88e.
• readOnly existed only on InteractiveEditor. No caller passed it. The editorOptions memo that existed to spread readOnly onto the shared options is gone, and the editor passes options again.
• PlaygroundEditor.tsx was const PlaygroundEditor = InteractiveEditor. Staff allowed EditorSurface to import InteractiveEditor directly. After that switch nothing else imported the alias, so the alias file is deleted too. PlaygroundLiveEditor stays, because InteractiveEditor still uses it for the mobile and bot path.

Checks. A playground test command on this tree exited 0. The captured log only shows Running one project: ReactDOM, so I am not citing a suite count. Lint on the edited editor files exited 0. Not merging until Bugbot is green on 82bf2d06.

The PR description still has the "Kept for future use" bullet from cf2de88e. That sentence is now false. The pull-request update tool would not edit the human-written description.

[ntucker]

c529c24 reverts 82bf2d0. In the project thread, Nathaniel chose to keep PlaygroundEditor, DiffEditorChooser, the readOnly prop and Playground/resources/ for now, which overrides the deletion requested in review 5401577634. On c529c24, the website typecheck and lint pass, and all 17 Playground tests pass.

---

Generated by Claude Code

[ntucker]

Staff: CHANGE_THIS_PR

Tip c529c24 undoes the dead-code cleanup that was already landed on 82bf2d06. Please revert this restore and keep the simpler graph.

Undo (delete / rewire back)

1. Delete website/src/components/DiffEditorChooser.tsx and point DiffEditor.tsx at DiffEditorMonaco again (Chooser is an identity alias; only consumer is the rewired call site).
2. Delete website/src/components/Playground/PlaygroundEditor.tsx and import InteractiveEditor from EditorSurface again (same identity alias; the PlaygroundLiveEditor re-export is unused — InteractiveEditor already imports LiveEditor directly).
3. Delete website/src/components/Playground/resources/ (PlaceholderBaseResource.ts, TodoResource.ts) — no in-repo consumers; README already says "currently unreferenced".
4. Drop the unused readOnly prop (and the useMemo options merge) from InteractiveEditor — nothing passes it.

Keep

• PlaygroundLiveEditor — still used as the mobile/bot fallback inside InteractiveEditor.

PR-body "Nathaniel’s call / kept for now" is not an in-repo migration. If ownership wants to waive deletion of unused aliases/resources, that needs an explicit Grok Bot waive; Staff prefers deletion in this PR.

Prior FOLLOW_UPs unchanged (declare globals → declare global; dead ambientsource / useIntersectionObserver / Demo.module.css; optional row-fixtures / import-completions / unquoted path=).

[ntucker]

Staff Reviewer: Hold. Do not start the undo in #4104 (review).

Lead reports Nathaniel chose to keep PlaygroundEditor, DiffEditorChooser, the readOnly prop, and Playground/resources/ on c529c24. That change request stays open only until Grok Bot waives it or says to delete them. Not merging. The branch is still behind master.

[ntucker]

Staff Reviewer: Nathaniel waived the deletion. Keep DiffEditorChooser, PlaygroundEditor, Playground/resources/, and the unused readOnly prop on InteractiveEditor. #4104 (review) is waived, not an open change request. Do not delete them in this PR. Still not merging until he says to.

[ntucker]

Lead Engineer: Nathaniel waived the deletion request in #4104 (review).

Keep these, as the project thread already chose:

• DiffEditorChooser
• PlaygroundEditor
• website/src/components/Playground/resources/
• the unused readOnly prop on InteractiveEditor

Motivation: an explicit waive from Nathaniel, via Grok Bot, overrides Staff's preference to delete them in this PR. Findings that support keeping them are the project-thread restore at c529c24 and the PR body note that they are kept for now. Do not undo them.

This does not clear the merge. Bugbot and CI are already green on 1feb6b27, but merging still needs a separate go-ahead from Nathaniel. I am not merging.

[ntucker]

This comment follows up on every Staff review of this PR. No code changes are needed in this PR.

Review 5401440867: all FOLLOW_UPs stay as follow-ups

1. declare globals → declare global in monaco/typeLibs.ts. This changes which types Monaco sees in every playground. Two things could add new red squiggles: the inlined React .d.ts contains exports, and declare global only works in a module lib. Checking that needs a browser pass, which is out of scope for a behavior-neutral reorg.
2. website/ambientsource-plugin.js, useIntersectionObserver.tsx and Demo/Demo.module.css are still unused (grep finds no importers). This PR doesn't touch them, and Nathaniel wants dead code kept for now, so deleting them belongs in a separate cleanup PR.
3. Unshown row-layout fixtures, import completions across playgrounds, and unquoted path= are all pre-existing. Each should be its own PR.

Reviews 5401577634 and 5402268417: deletions waived
Per Nathaniel's waive, DiffEditorChooser, PlaygroundEditor, Playground/resources/ and readOnly stay. The head is up to date with master (1feb6b2), and CI and Bugbot are green.

All of the follow-ups above are now listed in the PR description.

---

Generated by Claude Code

[ntucker]

Where each follow-up from Staff, the adversarial review and my own notes ended up:

Folded into this PR (f5d3562)

• Import completions now list only the other files in the same playground, not every Monaco model on the page. The logic is in siblingFilePaths in monaco/modelPath.ts and is tested.
• Fence metastrings now accept unquoted path=a.ts. Three RestEndpoint.md editors (Todo.ts, method.ts, body.ts) were silently getting default.ts instead. Tested.
• The Playground README is now prettier-formatted. The useModelId comment and the DiffEditor chain are fixed (7bf8c88).

Moved to their own PRs

• declare globals → declare global in monaco/typeLibs.ts. It changes Monaco typings on every playground, so it needs a browser check that no new diagnostics appear.
• Deleting website/ambientsource-plugin.js, useIntersectionObserver.tsx and Demo/Demo.module.css. That PR will confirm with Nathaniel first, since he chose to keep unused files for now.

Rejected

• Fixtures in row layout: not shown on purpose. EditorSurface explicitly passes fixtureContent only in stacked layout, where there is room above the editor. The fixtures still drive the preview through MockResolver.
• Trailing ; after one declare module lib string: an empty statement with no effect on types.
• HooksPlayground reusing PlaygroundProps with optional groupId/row: types only. The runtime defaults are unchanged, and MDX callers are untyped.
• Deleting DiffEditorChooser, PlaygroundEditor, resources/ and readOnly: waived by Nathaniel.

Validation: 19 Playground tests pass, and the website typecheck and lint are clean.

---

Generated by Claude Code