[Floating-Y]

Why

The shared entry loaded Home charts and every document body on unrelated routes. Standalone Block previews also imported the listing's Code panel and highlighter. Document previews mounted examples and fetched source even when far below the viewport.

What changes

• Merge the latest dev commit 2e025cf (Tool Steps state/focus preservation), retaining all six review fixes.

• Lazy-load Home and the document renderer. Keep the catalog, layout and component directory separate from individual section/slug JSON bodies.

• Split standalone BlockView from the listing, preserving theme, image fallback and Toaster behavior.

• Activate document previews within a 300px viewport margin and keep activated examples mounted. Fetch ordinary source on activation; skip raw source for hideCode previews.

• Show failed example-source and installation-source requests inside their own code areas. Document-body failures retain the document error boundary.

• Declare Chart's reserved minimum height in its document preview rather than in the generic component.

• Correct hash positioning when previews above the target change size. Stop correction when the reader scrolls, touches, clicks or uses the keyboard; clean up on navigation and unmount.

• Keep unique-key/slug assertions and stale-page cleanup in document generation. Update the contributor documentation accordingly.

• Remove the unrelated Windows compatibility changes and the standalone HTML behavior-check page from this PR. Windows compatibility is left for separate work.

Validation

Current revision: 16f4263 (merged dev 2e025cf).

• GitHub CI #146 passed for this revision.

• Ubuntu, Node 22.23.4: locked dependency installation completed with npm ci --prefer-offline --no-audit.

• node --test scripts/block-metadata.test.mjs: 8 passed.

• npm run docs: 76 documents generated. git diff --exit-code registry.json, npm run typecheck and npm run build passed.

• Windows: typecheck passed. Chrome behavior checks ran against the merged source.

• Chrome, dark and light: deliberately returned HTTP 500 for Button example source and Manual installation source. Both errors stayed local; the document and live example remained. A failed document body still showed the document error page, and client-side navigation recovered.

• Chrome at 506px width, with browser scroll anchoring disabled: delayed Chart loading grew the preceding preview from 406px to 434px. The target heading remained at 112.34px from the viewport top. A separate run confirmed that reader scrolling stops correction.

• Preview input values and expanded code survived scrolling away and back. Browser back navigation to a hash and fallback without IntersectionObserver passed. Chart hideCode made no raw-source request.

• Tool Steps in both themes: running-to-done and running-to-error retained the same button node, focus and expanded details; multi-call groups toggled correctly. A separate mount confirmed that the same call ID preserves state and a different ID starts closed.

• /dev/examples: 389/389 mounted, 0 failed in each theme.

• git diff --check passed. No test harness or dependency was added to the repository.

Safari and physical devices were not tested. Existing nativeButton and value/defaultValue development warnings remain outside this change.

[WaylandYang]

Thanks for this — splitting the docs into per-page bodies, lazy-loading Home/DocPage and mounting previews near the viewport is a direction we want, and the write-up of what you checked is very thorough. A few things before we can take it:

1. Please split out the Windows changes. CRLF normalization in build-docs.mjs and running the registry CLI via node_modules/shadcn/dist/index.js are unrelated to loading boundaries. The latter also depends on a private path inside the shadcn package that can move in any release; if we do this, resolve the package's bin instead. A separate small PR is easier to review and revert.
2. No per-example special case in ComponentPreview. name === "chart-demo" && "h-[404px]" puts one example's layout into the generic preview. If the chart needs reserved height, give it a minimum height where its preview is declared (its className in the page) or in the example itself.
3. scripts/check-component-preview.html. The repository deliberately has no unit tests and CI doesn't run this page, so it would go stale. Please drop it from this PR; the behaviours it covers are well described in the PR text.
4. The read-back in build-docs.mjs. Writing every file and then re-reading and deep-comparing it against what was just written is more machinery than the risk warrants. Keeping the unique-key/slug assertions and the stale-file cleanup is enough.
5. A failed source fetch takes down the whole page. useSource now throws into DocErrorBoundary, so one failed ?raw request replaces the entire document with "Unable to load this document". Please keep that failure local to the code panel (e.g. an inline message there) and reserve the document boundary for the body itself.
6. Anchors with placeholders. Placeholders reserve 208px while real previews are often taller, so on a direct #hash link previews just above the target activate and push it down. Browsers without scroll anchoring (Safari in particular) will land in the wrong place. Please check this outside Chrome, or re-scroll to the target once the previews around it have settled.

Happy to look again once these are in. Thanks!

[Floating-Y]

Thanks @WaylandYang — all six points have been addressed in 42c379f:

1. Windows changes: removed the CRLF normalization, Windows path handling and direct shadcn/dist/index.js invocation from this PR. Windows compatibility is left for separate work.
2. Chart layout: removed the chart-demo special case from ComponentPreview. Its reserved minimum height is now declared in content/components/chart.mdx.
3. Standalone check page: deleted scripts/check-component-preview.html.
4. Generator read-back: removed the write/read/deep-compare pass. Unique-key and slug assertions plus stale-page cleanup remain; both contributor guides now describe that behavior.
5. Source failures: useSource returns an error state instead of throwing. Both preview source and Manual installation source show an inline error in their own code area, while the document and live example remain. Document-body failures still use the document error boundary.
6. Hash positioning: a ResizeObserver watches previews preceding the target heading and repositions the target as their heights change. Correction stops on reader interaction and is cleaned up on navigation/unmount.

Validation for this revision:

• CI #145 passed: all 8 metadata tests, document generation, registry consistency, typecheck and production build. The local Ubuntu checks also passed, generating 76 documents.
• Chrome in both themes: deliberately failed the Button example-source and Manual-source requests with HTTP 500. Both errors stayed local, with the document and example intact. Document-body failure and client-side navigation recovery also passed.
• At 506px width with browser scroll anchoring disabled, delayed Chart loading grew the preceding preview from 406px to 434px; the heading stayed at 112.34px from the viewport top. A separate run confirmed that scrolling stops correction.
• Input values and expanded code survived scrolling away/back. Back navigation to a hash, the fallback without IntersectionObserver and hideCode source suppression passed.
• /dev/examples: 389/389 mounted, 0 failed in each theme. git diff --check passed.

Safari and physical devices were not tested; the anchor check above exercises the correction with Chrome's native scroll anchoring disabled. The PR description has been updated with these results.

Could you take another look when you have a chance? Thanks!

[WaylandYang]

Thanks, this is in good shape now. All six points are addressed, and I checked the revision here as well:

• npm ci, npm run docs (registry unchanged), npm run typecheck, npm run build all pass. The entry chunk goes from 1,277 kB to 521 kB (339 kB to 166 kB gzipped).
• /dev/examples: 389/389 mounted, 0 failed, dark and light.
• An inactive preview reserves the same height as an active one (383 px vs 382 px on the Button page), so ordinary pages do not shift at all.
• Anchors, with overflow-anchor: none forced: a client-side navigation to /docs/components/chart#component lets the chart preview grow from 406 to 431 px, which pushes the heading down, and the observer brings it back to its scroll-margin. After a real wheel event the correction stops, as intended.

One note, not blocking: chart.mdx now reserves min-h-[404px] at every width where upstream had it at lg: only. The demo is taller than that on a phone anyway, so nothing shows, but it is a change to a shadcn/ui page beyond what was needed; if you would rather keep lg:, the observer handles the small screens.

Merging. Thanks for the careful work and the write-ups.