Shadcn Base Migration Progress

Goal

Continue the docs restart from docs/plans/2026-05-23-shadcn-docs-restart-comparison.md: move apps/www toward the upstream shadcn/Fumadocs base while preserving Plate docs content, registry docs, API MDX, CN docs, MCP, and Plate Plus hooks.

Current Slice

Status: thirty-ninth slice complete

Make Fumadocs metadata/pageTree the docs navigation authority.
Move sidebar and pager reads off direct docsConfig runtime access.
Replace command menu docs search with Fumadocs search API.
Keep docsConfig only as a temporary migration overlay until labels, CN titles, and non-content registry/app links live in Fumadocs metadata or registry docs source.
Replace Plate's old LLM copy/view buttons with the upstream-style copy-page dropdown and .md markdown route model.
Remove the old Plate theme/customizer shell surface called out for deletion in the comparison doc.
Route visible registry install commands through the @plate/* namespace configured by components.json.
Route generated Plate registry self-dependencies through @plate/*, while preserving local-file template sync.
Upgrade the docs app to the upstream shadcn v4 package and validate Plate registry source against the v4 schema contract.
Move the shared app shell toward upstream's data-slot="layout" structure with layout-owned footer behavior and centered page headers.
Move root runtime providers and global CSS closer to upstream's provider stack, while keeping Plate's required DnD/Jotai/editor runtime.
Align header, mobile nav, and command-menu fallback links with upstream's Fumadocs-aware header behavior while preserving Plate product links.
Include Fumadocs meta.json in the docs registry export and remove old docsConfig-driven docs-registry generation scaffolding.
Move runtime docs navigation overlays out of docsConfig and into committed Fumadocs-adjacent metadata.
Move Plate docs content under the upstream-style content/docs/** Fumadocs source root.
Move category grid/breadcrumb metadata out of runtime docsConfig imports and add CN app-only docs routes for localized category links.
Remove the public-shaped /api/registry/[name] highlighted-source route and dead v0 open button residue.
Remove public /dev debug routes from the docs app restart surface.
Move docs route parity checks off docsConfig and onto committed Fumadocs metadata pages.
Add the upstream-style /view/[name] block preview renderer and route default block iframes through it.
Add a Plate /init bootstrap route that follows the shadcn registry:base contract, plus the upstream-style /init.md markdown rewrite.
Remove the legacy Pages Router /api/components endpoint and stale tracing for the deleted /api/registry/[name] route.
Promote committed content/docs/meta.json to the only docs navigation metadata source by deleting the old docsConfig sync generator and TS nav config.
Remove stale create/project/theme state from the public homepage preview path: delete unused project add hooks/components, delete unused theme registry preview wrapper, drop the old customizer radius from shared install config, and remove lift-mode state from the playground preview.
Collapse the duplicated English/CN docs catch-all route implementation into one locale-aware Fumadocs/registry page renderer, localize registry-related docs links through the same helper, and remove stale // SYNC markers from retained public docs surfaces.
Clean up DocsNav after the pageTree cutover: remove route-prefix hacks, direct DOM active-item queries, and timeout-based scrolling; keep active/filter section state derived from Fumadocs metadata and localized href helpers.
Remove the leftover public e2e-examples route group from the restarted docs app surface.
Remove the ignored app-local React 18 resolutions block from apps/www/package.json so the docs app package metadata matches the React 19 shadcn base instead of emitting stale pnpm warnings.
Remove stale template tooling that still installs Plate registry items through raw localhost URLs instead of the configured @plate shadcn namespace.
Align DocsCopyPage with the upstream copy-page grouped-button/dropdown/popover model while preserving Plate-specific LLM, Markdown, and GitHub actions and making clipboard failures non-fatal.
Delete unreferenced template helper scripts that still mutate templates/** between localhost and production registry URLs or initialize Plate from a localhost registry URL.
Remove the commented shadcn block-request CTA residue from the retained Plate editors page.
Remove Contentlayer residue from repo tooling, agent docs, lint ignores, and the Bun lockfile so the Fumadocs cutover is reflected outside apps/www runtime source too.
Update docs-authoring agent rules to point at the committed content/docs/** source root so future docs work does not reintroduce old root-content paths.
Delete the unreferenced local registry test harness that still installed registry items through raw http://localhost:3000/rd/* URLs.
Remove two remaining active-source TODO/FIXME residues by wiring Excalidraw component metadata to its existing demo and making the media preview download control functional.
Add the upstream-style RSS route and metadata alternate using Plate's generated release index as the feed source.
Align the BlockViewer code surface with upstream shadcn's tokenized code viewer styling while preserving Plate registry install controls.
Keep lazy code-view source loading for bandwidth, but rename it from /api/registry/[name] to /api/registry-source/[name] so it is not confused with the public registry contract.

Findings

Contentlayer removal and Fumadocs source loading are already complete.
docsConfig no longer exists in active source. It was first isolated from runtime reads, then removed after content/docs/meta.json took over pages, labels, CN titles, sections, category tabs, and category grids.
Fumadocs supports root meta.json with pages, links, and separators; links can represent app-only and registry-derived docs routes.
The content layout now lives under content/docs/**, with root pages plus folders such as (guides), (plugins), api, components, examples, installation, migration, and releases.
CN routes can keep using English metadata because DocsNav applies locale labels and href prefixing.
Fumadocs search maps i18n locale names into Orama tokenizer languages. Plate's cn locale must be mapped explicitly to a supported tokenizer.
The upstream .md model maps /docs/*.md through a hidden /llm/* route. Plate now mirrors that for /docs/*.md and /cn/docs/*.md, while keeping canonical https://platejs.org source URLs in copied markdown.
The old Plate theme/customizer surface was only reachable from the English and CN home pages. Removing those entrypoints made themes.css, lib/themes.ts, ThemeCustomizer, theme selectors, theme copy-code helpers, useThemesConfig, the unused drawer component, and the vaul dependency dead.
Template components.json files and tooling/scripts/update-template.sh already use @plate as the Plate registry entrypoint. The remaining raw URL drift is in user-facing docs, block preview, MCP, and metadata command text.
Raw /r/* URLs are still the right shape for resolvable registry content links, LLM context, and v0 URLs. User install commands should prefer npx shadcn@latest add @plate/{name}.
Upstream shadcn v4 resolves namespaced registryDependencies such as @custom/custom-component through configured registries. Plate can use the same contract for its own generated self-dependencies instead of emitting public https://platejs.org/r/*.json dependencies.
Local template sync must rewrite @plate/{name} back to {name}.json, because update-template.sh --local intentionally feeds shadcn local-file mode from a prepared JSON mirror.
The upstream shadcn v4 registry schema is exported from shadcn/schema; shadcn/registry is no longer the schema/type authority. Plate registry source and builders now use the v4 schema entrypoint.
The full local registry build is still CI-owned, so this slice adds a source-only registry contract check to www typecheck instead of running build:registry locally.
Upstream owns the app shell shape through data-slot="layout", a layout-level footer, centered PageHeader, and footer visibility controlled by route descendants such as data-slot="docs".
Plate's English and CN home pages previously owned their own footers and action-row layout, which kept the old fork shell alive even after the theme/customizer removal.
Upstream's root app uses group/body, a top-level tooltip provider, and a d theme shortcut in the theme provider. Plate still needs Jotai and DnD for retained editor surfaces, so the provider restart should add upstream behavior around those retained providers rather than deleting them.
apps/www/src/app/globals.css still carried old sync markers for custom scrollbar, prose, and duplicate MDX pretty-code styles. The current shadcn-style pretty-code rules already target the active generated attributes, so the marked fallback CSS can be removed after browser-checking code blocks.
Upstream exposes /rss.xml and advertises it through root metadata alternates. Plate already has a generated release index, so the correct rebrand is a release feed instead of shadcn changelog content.
BlockViewerCode still used a hard-coded zinc-950/zinc-900 dark shell after the app's pretty-code and code-surface tokens moved to upstream-style bg-code/text-code-foreground. That makes the code tab visually diverge from both light mode and upstream shadcn.
highlight-code.ts also generated Shiki HTML with a single dark theme and inline dark background, so fixing only the BlockViewer shell left the right-side code pane black. The highlighter has to emit light/dark token styles and transparent pre backgrounds.
The upstream-style centered PageHeader is not correct for Plate's retained homepage/editor marketing surfaces. Those pages should keep Plate's original left-aligned hero rhythm.
Upstream keeps mobile nav visible until the lg breakpoint and lets the header pass Fumadocs page-tree data into mobile/search surfaces. Plate still needs its own product links, but those links should use the same locale href handling as docs page-tree links.
Plate's mobile nav rendered the Fumadocs-derived tree but did not localize visible titles or hrefs at click time. On /cn, the mobile menu could point users back to English routes.
Plate's command-menu fallback link groups also used raw titles and hrefs. Fumadocs search owns indexed docs results, but fallback nav groups still need locale-safe labels and links.
hrefWithLocale must be safe for /, existing /cn links, hash links, and absolute external URLs. Prefixing every href blindly is how external links and CN homepage links get subtly broken.
build-docs-registry.mts still had a half-removed docsConfig/pathMap/meta generation path. The active export scanned Fumadocs content, but it did not publish the committed content/docs/meta.json, so an installed docs registry missed the navigation authority that the app now relies on.
The docs registry should export docs-meta as a normal shadcn v4 registry item and make the aggregate docs item depend on @plate/docs-meta. Generating a sidecar docs-meta.json outside the registry dependency graph would preserve the old installer workaround instead of using upstream namespace resolution.
docs-page-tree.ts still imported docsConfig/docsMap at runtime after pageTree adoption. That kept the old TS nav graph on the hot path for labels, CN titles, and keywords even though content/docs/meta.json already owns ordering.
The comparison doc still called out root content/** as a remaining divergence from upstream. Moving the source root to content/docs/** is the direct fix; keeping defineDocs({ dir: '../../content' }) after adding metadata would be half a migration, and that's how these forks rot.
Category grid pages and the breadcrumb switcher still pulled docsConfig through docs-utils, even after sidebar, pager, and command menu moved to Fumadocs metadata. That kept old TS nav data in the browser bundle.
Localizing app-only category links exposes a route parity requirement: if /docs/components, /docs/examples, /docs/plugins, /docs/api, or special example routes are part of the CN nav, explicit /cn/docs/... app routes need to exist because Fumadocs source fallback cannot invent those pages.
BlockViewer still lazy-fetched highlighted source from /api/registry/[name] when switching to code view. That preserved an extra Plate-only API route after registry pages already had server-side access to full registry source data.
The old OpenInV0Button file was dead code, and BlockViewer still carried a commented v0 toolbar block. The comparison doc calls out v0 as discard-all; keeping the corpse around is how it comes back.
apps/www/src/app/dev/** was still a public Next route group with markdown streaming, custom type, and table performance playgrounds. The comparison doc explicitly says dev/debug routes do not belong in the restarted public docs app.
check-docs-source-parity.mts still used docsConfig.sidebarNav for route parity after runtime navigation moved to Fumadocs metadata. That made the verification path prove the old TS nav graph rather than the committed content/docs/meta.json page list.
apps/www/scripts/capture-registry.mts already captured screenshots from /view/{block}, but the app only shipped /blocks/{name} preview routes. Adding /view/[name] aligns the generated screenshot path and BlockViewer iframe target with upstream's preview-renderer split while keeping /blocks/[name] as a compatibility route.
Upstream /init is not a generic components.json endpoint; it returns a shadcn registry:base item whose config is merged into components.json. Plate should use that same contract for bootstrap, not invent a Plate-only installer shape.
Plate's useful init surface is narrow: configure the public @plate registry namespace and install @plate/editor-basic. The v0/create flow stays discarded.
The MCP docs still had @platejs in the components.json snippet even though templates, visible commands, and generated registry dependencies now use @plate.
apps/www/src/pages/api/components.* was the last Pages Router endpoint in the docs app. It served a single stale Button JSON snapshot, had no repo references beyond its own import, and has no equivalent in upstream ../ui/apps/v4.
apps/www/next.config.ts still traced assets for /api/registry/[name] after that App Router endpoint was deleted. Keeping tracing for a deleted route is harmless until it isn't; it advertises an API surface the restarted app intentionally removed.
content/docs/meta.json now carries 265 Fumadocs page entries, 257 _plate.items overlays, localized section labels, category switcher metadata, and category groups. The old sync-docs-meta.mts generator was no longer needed as a transitional bridge.
Keeping docsConfig after runtime navigation, parity, and registry docs export all read committed Fumadocs metadata would recreate the exact competing-source problem the migration plan warned about. The metadata file is now edited as source, like upstream shadcn content/docs/**/meta.json.
Plate registry examples can include enough source files that shadcn's eager highlighted-source model is wasteful for users who never open the Code tab. The final compromise is lazy source hydration through /api/registry-source/[name], scoped to docs code-view payloads only. Public registry installs remain /r, /rd, @plate/*, and /init.
The comparison doc calls out create/v0/project/theme surfaces as discard-all unless they directly serve Plate's kept product routes. ProjectAddButton, useProject, ThemeComponent, and useLiftMode had no active consumers after the preview/view/init cleanup. The homepage playground only needed the preview shell and package-manager install config, not project storage, lift-mode storage, or customizer radius storage.
/cn/docs/[[...slug]] still duplicated the English docs catch-all route logic after the Fumadocs i18n cutover. That duplication made registry fallback pages, related-doc links, metadata, and pager behavior easy to drift between locales.
The docs catch-all route should keep thin Next route files per locale, but route discovery, metadata generation, Fumadocs page rendering, registry fallback rendering, related docs, and highlighted source loading belong in one shared server helper parameterized by locale.
Old // SYNC comments in retained app-shell, docs, editors, block viewer, and block listing files no longer represented actionable migration work. Leaving stale sync markers in kept surfaces makes future audits noisier than the code.
DocsNav still carried old client-side migration residue after docsConfig removal: a local /cn prefix regex, active-link DOM queries, and a delayed setTimeout scroll. The Fumadocs-era sidebar can use the same normalizeDocsHref, getLocalizedNavTitle, and hrefWithLocale helpers as the rest of docs navigation.
Filtering the docs sidebar needs an explicit fallback open section. If the current route is not part of the filtered result set, keeping the old accordion value leaves all matches hidden.
CN docs currently have no physical .cn.mdx files, so the CN sidebar should reuse the English pageTree and let DocsNav apply CN labels and /cn/docs/* hrefs. Reading the cn pageTree directly can leave the active route without an open section.
apps/www/src/app/(app)/e2e-examples/** was an unlinked public route group containing only a PlateController test/demo page. It had no active source references and belongs with test fixtures, not the restarted public docs app.
apps/www/package.json still carried an ignored resolutions block pinning react and react-dom to React 18 even though the docs app, root package, and upstream shadcn v4 app use React 19. pnpm warned on every install that the field did not take effect, so keeping it only preserved stale fork metadata.
tooling/scripts/add-ai.sh still called missing pre-registry.sh/post-registry.sh scripts and installed editor-ai from http://localhost:3000/rd/editor-ai. The supported template sync path is tooling/scripts/update-template.sh, and template install smoke tests should exercise the configured @plate registry namespace instead of requiring a local docs server.
DocsCopyPage had already replaced the old LLMCopyButton/ViewOptions surface, but its implementation still used the thinner Plate dropdown instead of upstream's grouped copy-page control. Browser verification also exposed that useCopyToClipboard left navigator.clipboard.writeText(...) rejections unhandled when the document is not focused.
tooling/scripts/pre-basic.sh, pre-ai.sh, post-basic.sh, post-ai.sh, init-plate-template.sh, init-plate.sh, and init2.sh had no active callers and preserved the old workflow of hand-mutating template components.json files or initializing Plate from http://localhost:3000/r. Keeping them contradicted the shadcn v4 namespace contract now owned by components.json, update-template.sh, and prepare-local-template-registry.mjs.
EditorDescription still carried a commented upstream shadcn block-request CTA pointing at shadcn-ui/ui discussions. The editors page is a retained Plate product surface; dead upstream product links should be deleted instead of preserved in comments.
apps/www package metadata and pnpm-lock.yaml no longer referenced Contentlayer, but root bun.lock, vendor update exclusions, reinstall cleanup targets, generated agent instructions, and lint ignores still carried contentlayer2, next-contentlayer2, or .contentlayer. A hard Fumadocs cutover should not keep those maintenance hooks alive.
docs-creator is a real authoring source of truth, not harmless prose. Its baseline docs list still pointed at old root content/** paths after the content-root migration, so future docs work could follow stale instructions even though active runtime source was clean.
apps/www/src/test-registry.mts was not referenced by any package script or caller, but it still encoded the old workflow of installing registry items by raw localhost /rd URLs. Keeping a dead harness around is worse than no harness: it teaches the wrong shadcn install contract.
excalidraw-node already had a real excalidraw-demo registry example and docs pages, but the component registry metadata still carried a commented FIXME instead of listing the demo.
MediaPreviewDialog rendered a download icon button with no handler. A visible no-op toolbar control is worse than omission; it should either work or disappear.

Verification Plan

Run pnpm --filter www build:source.
Run pnpm --filter www typecheck.
Run pnpm lint:fix.
If a browser-visible sidebar/search change is left in a runnable state this turn, verify via Browser Use before claiming full UI completion.
If a browser-visible app-shell/homepage change is left in a runnable state this turn, verify / and /cn render without the discarded theme/customizer surface.
If provider or global CSS changes affect the root shell, verify body/layout markers, footer visibility, theme shortcut behavior, and at least one docs page with code blocks.
If header or mobile navigation changes, verify English and CN mobile menus, external Plate Plus behavior, command-menu fallback routing, and desktop breakpoint visibility.
If docs registry export changes, verify createDocsRegistry() through check-docs-source-parity.mts, verify source registry normalization, and run www typecheck.
If docs nav metadata changes, regenerate content/docs/meta.json, verify the parity script asserts the metadata overlay, and run www typecheck.
If the docs source root changes, verify build:source, docs source parity, docs registry source paths, and English/CN rendered routes.
If category grid or breadcrumb metadata changes, verify content/docs/meta.json carries _plate.categoryGroups and _plate.docSections, run docs source parity, and smoke /cn/docs/components, /cn/docs/plugins, /cn/docs/examples, /cn/docs/api, plus app-only special example routes.
If block/source preview loading changes, verify the lazy /api/registry-source/[name] route returns highlighted files, run www typecheck, and smoke at least one block/code-view surface.
If public debug routes are removed, verify /dev and /dev/table-perf are no longer routable while docs/home routes still render.
If route parity changes, verify check-docs-source-parity.mts reads content/docs/meta.json pages and run www typecheck.
If block preview routing changes, verify /view/[name], /blocks/[name], and a registry docs page that embeds BlockViewer.
If init/bootstrap routing changes, verify /init returns a valid registry:base item, /init.md rewrites to markdown instructions, /init/v0 is absent, and MCP docs use @plate.
If legacy API cleanup changes routes, verify /api/components and /api/registry/[name] are absent while /api/registry-source/[name], /init, docs pages, and block previews still render.
If docs metadata authority changes, verify no active source imports docsConfig, run docs source parity, and smoke English/CN docs navigation surfaces.
If homepage preview state cleanup changes client components, verify no active imports remain for removed hooks/components, run www typecheck and lint, and smoke / plus /cn if a dev server is available.
If docs catch-all route logic changes, verify English and CN MDX docs, English and CN registry fallback docs, editors, view preview, and deleted legacy APIs.
If DocsNav client state changes, Browser-verify active links, filter results, localized placeholders, localized CN hrefs, and empty console error/warn logs.
If public e2e/demo routes are removed, verify /e2e-examples/plate-controller is no longer routable while docs and editor surfaces still render.
If package metadata cleanup changes apps/www/package.json, run pnpm install and verify the stale app-local resolutions warning is gone, then run www typecheck, lint, and the PR gate.
If template tooling changes, verify shell scripts with bash -n, verify root package metadata with pnpm install, run pnpm lint:fix, and run the PR gate. Do not run template generation or manually edit templates/**.
If copy-page UI changes, verify DocsCopyPage on a real docs page with Browser Use: grouped buttons render, menu links point to Markdown/ChatGPT/Claude/GitHub with noopener noreferrer, copy click does not emit console or server errors, then run www typecheck, lint, and the PR gate.
If .agents/rules/** changes, run pnpm install to sync generated agent docs, then verify stale migration residues are absent from active agent/source files.
If an unreferenced registry smoke/test harness is removed, verify no package script or source reference remains, run www typecheck, lint, and the PR gate.

Progress Log

2026-05-24: Loaded comparison artifact and prior solution notes. Selected navigation/search/pageTree as the next aligned migration slice.
2026-05-24: Added Fumadocs meta.json generated from the current docsConfig nav, added apps/www/scripts/sync-docs-meta.mts, and added sync:docs-meta.
2026-05-24: Added apps/www/src/lib/docs-page-tree.ts so sidebar and pager read Fumadocs pageTree with docsConfig only as a migration overlay for labels/CN titles.
2026-05-24: Rewired English and CN docs layouts to pass pageTree-derived nav into DocsNav.
2026-05-24: Rewired English and CN docs pages to pass pageTree-derived neighbours into DocContent; deleted the old components/pager.tsx docsConfig pager.
2026-05-24: Replaced command-menu docs search with Fumadocs useDocsSearch and added /api/search.
2026-05-24: Mapped search locale cn to Orama's english tokenizer to prevent runtime search crashes.
2026-05-24: Verification passed: pnpm install, pnpm --filter www build:source, pnpm --filter www typecheck, pnpm lint:fix.
2026-05-24: Browser Use passed on http://localhost:3100/docs and http://localhost:3100/cn/docs/table: sidebar groups render from meta/pageTree, pager next link appears, command search returns Fumadocs results, and browser error/warning logs are empty after the fix.
2026-05-24: Replaced old LLMCopyButton and ViewOptions docs UI with DocsCopyPage, added /llm and /cn/llm markdown routes, and rewrote /docs/*.md plus /cn/docs/*.md to those routes.
2026-05-24: Verification passed for the LLM slice: pnpm lint:fix, pnpm --filter www typecheck, and Browser Use on http://localhost:3100/docs, http://localhost:3100/docs.md, and http://localhost:3100/cn/docs/table.md with empty browser error/warning logs.
2026-05-24: Removed the old home-page Themes button and customizer drawer from English and CN home pages; deleted the old theme library, generated theme CSS import, customizer/theme selector components, theme copy helper, useThemesConfig, unused drawer component, and vaul.
2026-05-24: Verification passed for the theme cleanup slice: pnpm install, pnpm --filter www build:source, pnpm --filter www typecheck, pnpm lint:fix, and Puppeteer smoke on http://localhost:3100/ plus http://localhost:3100/cn. The smoke confirmed the new descriptions render, Themes/Customizer text and buttons are absent, and meaningful browser logs are empty. Four manifest CORS log lines were ignored because the dev server ran on port 3100 while the manifest URL points at the default localhost origin.
2026-05-24: Added apps/www/src/lib/registry-install.ts and rewired visible registry install commands in component installation, component source, MCP setup, block preview toolbar, block viewer toolbar, and block metadata to use @plate/* namespace commands instead of raw registry URLs. Added a real DialogDescription to the MCP dialog after the smoke surfaced Radix's missing-description warning.
2026-05-24: Verification passed for the registry install command slice: pnpm install, pnpm --filter www build:source, pnpm --filter www typecheck, pnpm lint:fix, rerun pnpm --filter www typecheck, rerun pnpm --filter www typecheck after the MCP dialog warning fix, and Puppeteer smoke on http://localhost:3100/docs/components/table-node, http://localhost:3100/docs/table, http://localhost:3100/blocks/playground, and http://localhost:3100/blocks/editor-basic. The smoke confirmed visible install commands, MCP setup command, and metadata descriptions use @plate/*, no raw localhost registry URL remains in those surfaces, and the MCP dialog warning is gone.
2026-05-24: Added docs/solutions/developer-experience/2026-05-24-shadcn-registry-install-commands-should-use-configured-namespaces.md through the ce-compound closeout. Final PR gate passed with pnpm check after one earlier test:slowest threshold failure was isolated as local load by a clean standalone pnpm test:slowest rerun.
2026-05-24: Added apps/www/scripts/registry-dependencies.mts so build-registry.mts and build-docs-registry.mts emit @plate/* for Plate self-dependencies while preserving @shadcn/*, direct URLs, and local path specifiers. Updated docs source parity to assert @plate/table-docs and @plate/docs.
2026-05-24: Updated tooling/scripts/prepare-local-template-registry.mjs to rewrite @plate/* dependencies back to local {name}.json dependencies for update-template.sh --local.
2026-05-24: Verification passed for the registry dependency namespace slice: pnpm install, pnpm --filter www build:source, bun test apps/www/scripts/registry-dependencies.test.mts, a temp-directory smoke of tooling/scripts/prepare-local-template-registry.mjs, pnpm --filter www typecheck, and pnpm lint:fix.
2026-05-24: Upgraded apps/www from [email protected] to [email protected], moved registry schema/type imports from shadcn/registry to shadcn/schema, and validated build-registry.mts plus build-docs-registry.mts through v4 registrySchema.parse.
2026-05-24: Added apps/www/scripts/check-registry-source.mts to validate Plate's authored registry composition against the shadcn v4 schema and assert normalized registry dependencies use resolver-safe specifiers.
2026-05-24: Verification passed for the shadcn v4 schema slice: pnpm install, pnpm --filter www exec tsx --tsconfig ./scripts/tsconfig.scripts.json scripts/check-registry-source.mts, pnpm --filter www exec tsx --tsconfig ./scripts/tsconfig.scripts.json scripts/check-docs-source-parity.mts, bun test apps/www/scripts/registry-dependencies.test.mts, pnpm --filter www build:source, pnpm --filter www typecheck, and pnpm lint:fix.
2026-05-24: Added docs/solutions/developer-experience/2026-05-24-shadcn-v4-registry-schema-needs-source-only-validation.md through the ce-compound closeout.
2026-05-24: Added a shared AppShell for (app) and /cn routes using upstream's data-slot="layout" wrapper, moved footer ownership from home pages into the layout, and updated SiteFooter to hide on docs/designer descendants.
2026-05-24: Updated PageHeader, English home, CN home, and editors intro toward upstream's centered page-header/action composition while preserving Plate copy and product CTAs.
2026-05-24: Browser smoke caught that body-level footer hiding did not hide on /docs; fixed it by also targeting the nearer group/layout shell.
2026-05-24: Verification passed for the app-shell slice: pnpm install, pnpm --filter www build:source, pnpm --filter www typecheck, pnpm lint:fix, and a local Chrome smoke on http://localhost:3100/, http://localhost:3100/cn, and http://localhost:3100/docs. The smoke confirmed each route has one data-slot="layout" shell, English/CN home pages expose one footer, docs keeps the layout footer hidden, search/header render, and browser errors/warnings are empty.
2026-05-24: Added docs/solutions/developer-experience/2026-05-24-shadcn-app-shell-footer-visibility-needs-nearest-layout-group.md through the ce-compound closeout.
2026-05-24: Updated the root app shell provider layer with upstream-style group/body, a top-level tooltip provider, and the upstream d theme shortcut while preserving Plate's Jotai and DnD providers.
2026-05-24: Removed the old globals.css blocks explicitly marked remove after sync for custom scrollbar, custom prose, and duplicate MDX pretty-code fallback styling.
2026-05-24: Verification passed for the provider/CSS slice: pnpm install, pnpm --filter www build:source, pnpm --filter www typecheck, pnpm lint:fix, and local Chrome smoke on http://localhost:3100/, http://localhost:3100/docs, http://localhost:3100/docs/migration/slate-to-plate, and http://localhost:3100/cn/docs/migration/slate-to-plate. The smoke confirmed group/body, one layout shell, home footer visible, docs footers hidden, d theme shortcut toggling, visible code blocks on English/CN docs pages, and empty browser error/warning logs.
2026-05-24: Updated hrefWithLocale to avoid double-prefixing /cn, keep external/hash hrefs untouched, and map CN home to /cn.
2026-05-24: Updated SiteHeader, Logo, and MainNav toward upstream's lg desktop breakpoint and removed the old commented header fork.
2026-05-24: Updated MobileNav to localize top links, page-tree group titles, page-tree hrefs, and external Plate Plus behavior from the current locale.
2026-05-24: Updated CommandMenu fallback links/groups to use localized titles and locale-safe hrefs while keeping Fumadocs search as the docs-search source.
2026-05-24: Verification passed for the header/mobile-nav slice: pnpm install, pnpm --filter www build:source, pnpm --filter www typecheck, pnpm lint:fix, and local Chrome smoke on http://localhost:3100/, http://localhost:3100/cn, and http://localhost:3100/docs. The smoke confirmed English mobile links, CN mobile links, CN page-tree links, Plate Plus external target, CN command-menu routing to /cn/docs, one docs layout shell, hidden docs footer, desktop mobile-menu invisibility, and no meaningful browser logs after filtering the known dev-port manifest CORS noise.
2026-05-24: Added docs/solutions/developer-experience/2026-05-24-shadcn-header-nav-needs-locale-safe-client-links.md through the ce-compound closeout.
2026-05-24: Added a docs-meta registry item that publishes Fumadocs meta.json to content/docs/plate/meta.json, made the aggregate docs registry item depend on @plate/docs-meta, and extended docs source parity checks to assert the meta export.
2026-05-24: Removed the dead docsConfig/pathMap/meta-generation scaffolding from build-docs-registry.mts; docs registry export now follows the committed Fumadocs metadata instead of a stale TS-nav shadow path.
2026-05-24: Verification passed for the docs registry meta slice: pnpm --filter www exec tsx --tsconfig ./scripts/tsconfig.scripts.json scripts/check-docs-source-parity.mts, pnpm --filter www exec tsx --tsconfig ./scripts/tsconfig.scripts.json scripts/check-registry-source.mts, pnpm --filter www typecheck, pnpm lint:fix, and a final pnpm --filter www typecheck rerun after cleanup.
2026-05-24: Added docs/solutions/developer-experience/2026-05-24-fumadocs-docs-registry-exports-need-meta-item.md through the ce-compound closeout.
2026-05-24: Started the runtime nav-overlay slice: sync-docs-meta.mts now writes _plate.sections and _plate.items into Fumadocs meta.json; docs-page-tree.ts and the EN/CN docs page metadata fallback read those overlays from content/docs/meta.json instead of importing docsConfig/docsMap.
2026-05-24: Verification passed for the runtime nav-overlay slice: pnpm --filter www sync:docs-meta, pnpm --filter www typecheck, pnpm lint:fix, and a final pnpm --filter www typecheck rerun after formatting. The typecheck includes build:source, docs parity, registry source validation, app TS, and package integration TS.
2026-05-24: Browser Use was not exposed by the current tool registry after two lookup attempts. Fallback HTTP smoke passed on http://localhost:3100/docs/plugin-shortcuts and http://localhost:3100/cn/docs/plugin-shortcuts, confirming data-slot="docs" plus English and CN page titles/text. A standalone tsx import smoke of docs-page-tree.ts failed on Fumadocs' fumadocs-core/server package export and was not used as evidence.
2026-05-24: Started the content-root slice: moved Plate docs content from root content/** to content/docs/**, updated Fumadocs defineDocs, docs meta read/write paths, docs registry source root, and parity assertions to use content/docs.
2026-05-24: Verification passed for the content-root slice: pnpm install, pnpm --filter www sync:docs-meta, pnpm --filter www build:source, pnpm --filter www exec tsx --tsconfig ./scripts/tsconfig.scripts.json scripts/check-docs-source-parity.mts, pnpm --filter www exec tsx --tsconfig ./scripts/tsconfig.scripts.json scripts/check-registry-source.mts, pnpm --filter www typecheck, and pnpm lint:fix.
2026-05-24: Browser Use was still unavailable from the tool registry. Fallback HTTP smoke passed on http://localhost:3100/docs/plugin-shortcuts, http://localhost:3100/cn/docs/table, http://localhost:3100/docs/plugin-shortcuts.md, and /api/search?query=table, confirming stable English docs, CN docs, markdown route, and Fumadocs search after the source-root move.
2026-05-24: PR gate passed with pnpm check after the content-root move.
2026-05-24: Started the category metadata slice: sync-docs-meta.mts now writes _plate.docSections and _plate.categoryGroups into content/docs/meta.json; runtime category grid, breadcrumb switcher, docs page category detection, and Slate-to-HTML special page metadata read from docs-nav-metadata instead of docs-utils.
2026-05-24: Deleted apps/www/src/config/docs-utils.ts; remaining docsConfig reads outside registry source are limited to metadata generation and parity scripts.
2026-05-24: Added CN app-only docs routes for /cn/docs/api, /cn/docs/components, /cn/docs/examples, /cn/docs/plugins, /cn/docs/examples/slate-to-html, and /cn/docs/examples/server-side, matching the localized links emitted by CN nav.
2026-05-24: Verification passed for the category metadata/CN route slice: pnpm install, pnpm --filter www sync:docs-meta, pnpm --filter www build:source, pnpm --filter www exec tsx --tsconfig ./scripts/tsconfig.scripts.json scripts/check-docs-source-parity.mts, pnpm --filter www typecheck, pnpm lint:fix, and final pnpm --filter www typecheck. Browser Use was unavailable from tool discovery; fallback HTTP smoke passed for /cn/docs/components, /cn/docs/plugins, /cn/docs/examples, /cn/docs/api, /cn/docs/examples/slate-to-html, and /cn/docs/examples/server-side on localhost:3100.
2026-05-24: Started the static block-source slice: BlockViewer no longer fetches /api/registry/[name]; docs/block callers now pass registry items with full file content so highlighted files are available without a client-side registry API.
2026-05-24: Deleted apps/www/src/app/api/registry/[name]/route.ts, deleted dead OpenInV0Button, and removed the commented v0 toolbar block from BlockViewer.
2026-05-24: Verification passed for the static block-source slice: pnpm --filter www typecheck, pnpm lint:fix, and final pnpm --filter www typecheck. Browser Use was unavailable from tool discovery; fallback HTTP smoke passed for /docs/components/table-node, /blocks/editor-basic, and /docs/examples/slate-to-html, and confirmed /api/registry/editor-basic returns 404.
2026-05-24: Deleted public /dev debug routes from apps/www/src/app/dev/**; historical benchmark docs may still mention /dev/table-perf, but the public docs app no longer ships that route.
2026-05-24: Verification passed for the public debug-route cleanup slice: pnpm --filter www typecheck, pnpm lint:fix, and fallback HTTP smoke on localhost:3100 confirming / and /docs return 200 while /dev and /dev/table-perf return 404.
2026-05-24: Started the route-parity metadata slice: check-docs-source-parity.mts now reads route parity from committed content/docs/meta.json pages links instead of importing docsConfig.
2026-05-24: Verification passed for the route-parity metadata slice: pnpm --filter www exec tsx --tsconfig ./scripts/tsconfig.scripts.json scripts/check-docs-source-parity.mts, pnpm install, pnpm --filter www build:source, pnpm --filter www typecheck, pnpm lint:fix, and PR gate pnpm check.
2026-05-24: Started the block preview route slice: extracted shared block preview page rendering, added /view/[name], kept /blocks/[name] on the same renderer, and switched default BlockViewer iframe/fullscreen targets to /view/[name].
2026-05-24: Verification passed for the block preview route slice: pnpm --filter www typecheck, pnpm lint:fix, a final pnpm --filter www typecheck, and fallback HTTP smoke on localhost:3100 confirming /view/editor-basic, /blocks/editor-basic, and /docs/components/table-node all return 200 with no dev-server errors. Browser Use was unavailable from tool discovery.
2026-05-24: Started the Plate init bootstrap slice: added /init as a shadcn registry:base item for the @plate registry and @plate/editor-basic, added /init/md plus /init.md rewrite, and fixed the stale @platejs MCP docs snippets.
2026-05-24: Verification passed for the Plate init bootstrap slice: bun test apps/www/src/lib/plate-init.test.ts, pnpm install, pnpm --filter www typecheck, pnpm lint:fix, fallback HTTP smoke on localhost:3101 confirming /init, /init.md, /init/md, /init/v0, and EN/CN MCP docs, and final PR gate pnpm check. Browser Use was unavailable from tool discovery.
2026-05-24: Added docs/solutions/developer-experience/2026-05-24-plate-init-routes-should-return-shadcn-registry-base-items.md through the ce-compound closeout.
2026-05-24: Started the legacy Pages API cleanup slice: deleted apps/www/src/pages/api/components.* and removed stale output tracing for the already-deleted /api/registry/[name] route.
2026-05-24: Verification passed for the legacy Pages API cleanup slice: pnpm install, pnpm --filter www typecheck, pnpm lint:fix, fallback HTTP smoke on localhost:3102 confirming /api/components and /api/registry/editor-basic return 404 while /init, /init.md, /docs/components/table-node, /view/editor-basic, and /blocks/editor-basic return 200, and PR gate pnpm check. Browser Use was unavailable from tool discovery. The first dev-server smoke exposed local disk pressure from a 12G .next cache; deleting that generated cache restored 13G free space before pnpm check.
2026-05-24: Started the docs metadata authority cleanup slice: removed sync:docs-meta, deleted apps/www/scripts/sync-docs-meta.mts, and deleted the old docsConfig/nav generator files. Active docs navigation metadata now lives in committed content/docs/meta.json.
2026-05-24: Verification passed for the docs metadata authority cleanup slice: pnpm install, pnpm --filter www typecheck, pnpm lint:fix, active-source rg confirms no docsConfig/sync-docs-meta references remain, and fallback HTTP smoke on localhost:3103 confirmed /docs, /cn/docs/table, /docs/plugin-shortcuts, /docs/components, /cn/docs/components, /docs/examples, /cn/docs/examples, and /api/search?query=table. Browser Use was unavailable from tool discovery. The dev smoke again filled local .next cache; deleting the generated cache restored free disk space before final PR gate.
2026-05-24: ce-compound closeout updated docs/solutions/developer-experience/2026-05-24-fumadocs-page-tree-search-needs-locale-safe-metadata.md with the final generator-removal rule instead of creating a duplicate learning.
2026-05-24: Started the create/project/theme residue cleanup slice: deleted ProjectAddButton, useProject, ThemeComponent, ThemeWrapper, and useLiftMode; simplified the homepage playground preview around the retained preview shell; removed old customizer radius state from useConfig; and pruned unused theme/color/lift tracking event names.
2026-05-24: Verification passed for the create/project/theme residue cleanup slice: active-source rg confirms the deleted hooks/components/events have no consumers, pnpm install, pnpm --filter www typecheck, pnpm lint:fix, fallback HTTP smoke on localhost:3104 confirmed /, /cn, /blocks/playground, and /view/editor-basic return 200 while the deleted legacy APIs remain 404, and PR gate pnpm check. Browser Use was unavailable from tool discovery. The dev smoke filled local .next cache again; deleting that generated cache restored free disk space before the final gate.
2026-05-24: ce-compound closeout updated docs/solutions/best-practices/2026-05-23-shadcn-docs-restart-comparison.md with the orphaned create/project/theme state cleanup rule instead of creating a duplicate learning.
2026-05-24: Started the docs route de-duplication slice: extracted a shared locale-aware doc-page.tsx renderer for English and CN docs catch-all routes, kept route files as thin Next exports, and localized registry fallback related-doc routes through the shared helper.
2026-05-24: Removed stale // SYNC markers and old commented block whitelist residue from retained public app-shell/docs/editors/block-viewer surfaces.
2026-05-24: Verification passed for the docs route de-duplication slice: pnpm install, pnpm --filter www typecheck, pnpm lint:fix, final pnpm --filter www typecheck, and fallback HTTP smoke on localhost:3105 confirmed /, /cn, /docs/plugin-shortcuts, /cn/docs/table, /docs/components/table-node, /cn/docs/components/table-node, /editors, and /view/editor-basic return 200 while /api/registry/editor-basic and /api/components remain 404. Browser Use was unavailable from tool discovery. The dev smoke again filled .next cache and logged No space left on device; stopping the dev server and deleting generated apps/www/.next restored enough disk for non-dev gates.
2026-05-24: Started the DocsNav cleanup slice: removed the local CN prefix regex, direct active-link DOM query, delayed timeout scroll, and keyword-stripping filter copy from the client sidebar.
2026-05-24: Fixed docs sidebar filter state to open the first filtered section when the current route is not in the filtered result set, and changed the CN docs layout to reuse the English pageTree because CN docs currently rely on English MDX fallback plus localized metadata.
2026-05-24: Verification passed for the DocsNav cleanup slice: pnpm install, pnpm lint:fix, pnpm --filter www typecheck, rerun pnpm lint:fix, rerun pnpm --filter www typecheck, and Browser Use on localhost:3106 confirming /docs/plugin-shortcuts active nav, English filter results, /cn/docs/table active nav, /cn/docs/* filtered links, localized placeholders, and empty browser error/warn logs. Dev-server cache again consumed several GB; stopping the server and deleting generated apps/www/.next restored local disk headroom.
2026-05-24: Started the public e2e route cleanup slice: deleted the unlinked apps/www/src/app/(app)/e2e-examples/** route group so the restarted docs app no longer ships the PlateController test/demo page as public product surface.
2026-05-24: Verification passed for the public e2e route cleanup slice: pnpm install, pnpm --filter www typecheck, pnpm lint:fix, final pnpm --filter www typecheck, Browser Use on localhost:3107 confirming /cn/docs/table, /editors, /view/editor-basic, and the removed /e2e-examples/plate-controller 404 page, plus HTTP status smoke confirming /e2e-examples/plate-controller returns 404 while retained docs/editor/view routes return 200. The first browser navigation hit a cold dev compile timeout; warming the routes and retrying verified the pages. Dev server was stopped and generated apps/www/.next was deleted after the smoke.
2026-05-24: Started the package metadata cleanup slice: removed the ignored React 18 resolutions block from apps/www/package.json; the docs app now relies on its explicit React 19 dependencies and the workspace root metadata instead of a stale, non-effective override.
2026-05-24: Verification passed for the package metadata cleanup slice: pnpm install no longer emits the ignored app-local resolutions warning, pnpm --filter www typecheck passed, and pnpm lint:fix passed with no fixes applied.
2026-05-24: Started the stale template tooling cleanup slice: deleted the broken tooling/scripts/add-ai.sh helper and changed templates:test to install @plate/editor-ai through the shadcn namespace configured in components.json, not a local /rd URL.
2026-05-24: Verification passed for the template tooling cleanup slice: exact old-localhost residue search only finds the intentional updated templates:test script, package.json parses, retained template shell scripts pass bash -n, pnpm install passed with an unchanged lockfile, pnpm lint:fix passed with no fixes applied, and PR gate pnpm check passed.
2026-05-24: Started the copy-page alignment slice: updated DocsCopyPage to use upstream's grouped button, desktop dropdown, and mobile popover structure while retaining Plate's Markdown, ChatGPT, Claude, and GitHub actions and keeping v0 discarded.
2026-05-24: Browser Use on localhost:3108/docs/plugin-shortcuts verified one copy button, one options button, four expected menu links with noopener noreferrer, and no browser warnings/errors. The first copy click exposed an unhandled clipboard rejection when the document was unfocused; useCopyToClipboard now catches failed writes and only shows success toasts after successful writes. A repeat Browser Use copy click produced no browser or server errors.
2026-05-24: Started the stale template helper deletion slice: deleted the unreferenced localhost registry init scripts and pre/post template URL mutation scripts so retained template tooling flows through update-template.sh and the configured @plate namespace.
2026-05-24: Verification passed for the stale template helper deletion slice: retained shell scripts pass bash -n, active tooling search has no init-plate*/init2/pre-post helper references and no http://localhost:3000/r or /rd template install residue, pnpm install passed, pnpm lint:fix passed with no fixes applied, and PR gate pnpm check passed.
2026-05-24: Started the editors CTA residue cleanup slice: removed the commented shadcn-ui block-request button from EditorDescription, leaving the retained Plate editors page with only the active Plate browse CTA.
2026-05-24: Verification passed for the editors CTA residue cleanup slice: active source search has no shadcn-ui, blocks-request, or Request a block residue under apps/www/src; pnpm install, pnpm --filter www typecheck, pnpm lint:fix, and PR gate pnpm check passed.
2026-05-24: Started the Contentlayer tooling residue cleanup slice: removed contentlayer2 and next-contentlayer2 from vendor update exclusions, removed .contentlayer from reinstall/lint ignore lists, updated the docs-creator verification rule to use Fumadocs source generation, and prepared the root Bun lockfile for regeneration.
2026-05-24: Verification passed for the Contentlayer tooling residue cleanup slice: bun install --lockfile-only regenerated bun.lock without Contentlayer packages; pnpm install synced generated agent docs; active tooling/package/lock search has no Contentlayer residue; retained shell scripts pass bash -n; pnpm --filter www typecheck and pnpm lint:fix passed.
2026-05-24: Started the docs-authoring source-root cleanup slice: updated .agents/rules/docs-creator.mdc baseline paths from old root content/** to committed content/docs/**.
2026-05-24: pnpm install synced generated docs-creator skill output and Fumadocs source files; active source search now has no old root docs path, Contentlayer, docsConfig, or sync-docs-meta residue.
2026-05-24: Verification passed for the docs-authoring source-root cleanup slice: pnpm install, active-source residue search, pnpm lint:fix, and PR gate pnpm check passed.
2026-05-24: Started the stale local registry smoke cleanup slice: deleted unreferenced apps/www/src/test-registry.mts and its unused apps/www/scripts/test-registry-config.json config because the script still installed items through raw localhost /rd URLs instead of the configured @plate namespace.
2026-05-24: Verification passed for the stale local registry smoke cleanup slice: reference search now finds only the migration plan notes, old raw localhost registry install residue is limited to intentional local dev config and backwards-compatibility tests, pnpm --filter www typecheck passed, and pnpm lint:fix passed.
2026-05-24: Started the active TODO/FIXME residue cleanup slice: excalidraw-node now advertises its existing excalidraw-demo, and MediaPreviewDialog now downloads the current preview image instead of showing a no-op download button.
2026-05-24: Verification passed for the active TODO/FIXME residue cleanup slice: registry source check now asserts excalidraw-node exposes excalidraw-demo; active-source residue search no longer finds the Excalidraw FIXME or media-preview download TODO; pnpm --filter www typecheck passed; pnpm lint:fix passed with no fixes applied.
2026-05-24: First PR gate attempt failed on React Compiler preserve-manual-memoization after the download handler used an unnecessary useCallback; removing the manual memo fixed the lint issue. Final verification passed with pnpm --filter www typecheck and full PR gate pnpm lint:fix && pnpm check.
2026-05-24: Started the RSS parity slice: added /rss.xml as a static RSS route backed by Plate's generated release index and advertised it through root metadata alternates.
2026-05-24: The first RSS route smoke used top-level await in tsx -e, which fails under the script tsconfig's CJS output. Re-running the same smoke as an async IIFE passed.
2026-05-24: Verification passed for the RSS parity slice: pnpm install, pnpm --filter www typecheck, pnpm lint:fix, direct RSS route smoke confirming application/rss+xml; charset=utf-8, Plate Releases, and release items, plus full PR gate pnpm check.
2026-05-25: Started the BlockViewer code visual alignment slice: replacing hard-coded dark code-tab styling with upstream tokenized code, figure, file-tree, and copy-button surfaces while keeping Plate's dependency install dropdown and server-provided highlighted source.
2026-05-25: Verification passed for the BlockViewer code visual alignment slice: pnpm install, pnpm --filter www typecheck, and pnpm lint:fix passed. Browser Use on existing localhost:3001/docs/components/table-node clicked the Code tab and confirmed the code shell uses bg-code text-code-foreground, the pretty-code figure exists, the file tree exists, dependency/copy controls use tokenized button classes, no scoped zinc-*/old fragment nodes remain, and browser error/warn logs are empty. Browser screenshot capture hit a Page.captureScreenshot timeout, so DOM/style inspection was used as the browser evidence.
2026-05-25: Follow-up fixed the right-side code pane by changing highlight-code.ts from single dark Shiki output to light/dark themes with transparent pre backgrounds and per-file language detection. Browser Use on localhost:3001/editors verified the AI editor Code tab now computes the code pre background as transparent over the bg-code shell.
2026-05-25: Follow-up restored the original left-aligned hero style by reverting shared PageHeader spacing/typography/actions to Plate's pre-centering layout and moving EditorDescription back to items-start.
2026-05-28: Renamed the lazy code-view route from /api/registry/[name] to /api/registry-source/[name], updated BlockViewer, output tracing, and route tests, and recorded the final bandwidth-driven decision: keep lazy source loading, but do not expose it as the public registry API.