apps/site: Playground 未注册 layout 组件(输入 `page-header` 得红色错误面板);`transpilePackages` 还列着两个非依赖包

[yinlianghui]

发现于 #3787 的实现与实测(PR:claude/issue-3786-3787-pageheader-docs-demo),不在该 PR 处理 —— 那一单的验收面是 catalog 示例的三个渲染宿主,这一条是剩下的第四个宿主 + 一处配置漂移。

现象一:Playground 少一个注册宿主

文档站有 4 个 SchemaRenderer 宿主:

apps/site/app/components/InteractiveDemo.tsx
apps/site/app/components/LiveSplitDemo.tsx
apps/site/app/components/SchemaThumbnail.tsx
apps/site/app/playground/page.tsx

#3787 的 PR 给前三个(渲染 catalog 示例的那三个)加了 registerLayoutBlocks,因为 @object-ui/layout 此前根本不是 apps/site 的依赖,page-header 会渲染成红色 Unknown component type(OBJUI-001)。第四个 —— Playground —— 渲染的是用户手输的 schema,不在那次验收面内,所以没动:今天在 Playground 里敲一个 page-header(或 app-shell / sidebar-nav)仍然得到同一块红面板,尽管文档站现在已经依赖并能渲染它们了。

page-header 的占位符也接不住:packages/components/src/renderers/placeholders.tsx:82 里 'page:header', 'page-header' 属于 opt-in 的 PROTOCOL_COMPONENTS,不在 eager 注册的 PALETTE_PLACEHOLDER_BLOCKS 里,而 registerPlaceholders() 只有 apps/console 调。

建议:Playground 也 import ./components/registerLayoutBlocks(一行),或把注册提到一个所有宿主共用的更高位置。顺带值得一起想清楚的是,Playground 该覆盖的组件面到哪为止 —— 它现在也没有 plugin-detail(所以 record:* 全渲染不出),而 PluginLoader 那套按需加载只服务 MDX 页面。

现象二:transpilePackages 列着非依赖包

apps/site/next.config.mjs 的 transpilePackages 里有两个不是 apps/site 依赖、也没有任何代码 import 的包:

• @object-ui/i18n
• @object-ui/plugin-aggrid

apps/site/node_modules/@object-ui/ 下没有它们的 symlink(pnpm 严格 linker),所以这两项不做任何事。@object-ui/layout 在 #3787 之前也是这个状态 —— 列在 transpilePackages 里、但既非依赖也无 import,看着像已经支持、实际渲染是红面板;那次是靠浏览器实测才发现的。这类「配置声明了、依赖图里没有」的条目正好是让人误判能力已就位的东西。

建议:删掉这两项,或补齐依赖(取决于是否真想在站内渲染它们)。

参考位置

• apps/site/app/playground/page.tsx(第四个渲染宿主)
• apps/site/app/components/registerLayoutBlocks.ts(docs/examples: PageHeader 文档页的唯一 live demo(layout-page-header/pageheader-with-actions)手搓 div,完全不用 page-header #3787 新增,含理由)
• apps/site/next.config.mjs(transpilePackages)
• packages/components/src/renderers/placeholders.tsx:82、:118-121

关联:#3787(发现于此)

[os-zhuang]

Findings-round grading: promoted — finding removed, pm:queue added.

• Why promoted: concrete, user-visible gap with a one-line core fix — the docs-site Playground renders a red OBJUI-001 panel for components the site now depends on and documents (the fourth SchemaRenderer host missed by docs/examples: PageHeader 文档页的唯一 live demo(layout-page-header/pageheader-with-actions)手搓 div,完全不用 page-header #3787's scoped fix), plus a measured config-hygiene half (two transpilePackages entries that are not dependencies and do nothing — the exact "looks supported, renders red" trap that bit @object-ui/layout before docs/examples: PageHeader 文档页的唯一 live demo(layout-page-header/pageheader-with-actions)手搓 div,完全不用 page-header #3787). Anchored, measured, no product call for the minimal fix.
• Scope note for the claimant: the "how far should Playground's component coverage go" question (plugin-detail, record:*) is real but severable — fix the layout-registration gap and the two dead config entries; widening Playground coverage beyond that is a separate card if wanted.
• Premise check: fresh filing (01:08Z) measured during docs/examples: PageHeader 文档页的唯一 live demo(layout-page-header/pageheader-with-actions)手搓 div,完全不用 page-header #3787's browser verification; registerLayoutBlocks.ts exists on origin/main @ 50fa376 and the Playground page does not import it.
• Dedup: no shadow card; packages/layout: sideEffects: false contradicts the load-time registerLayout() — a side-effect-only import can be tree-shaken away #3899 (held this round) is the packaging-declaration face of the same registration model — related, different fix.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[os-project-manager]

Release board: target:v17 applied — class ④, a documented layout component typed into the shipped docs-site Playground renders a red Unknown component type (OBJUI-001) panel, which is a follow-the-docs-and-fail first-hour experience. One-time stock pass per objectstack#6904 (maintainer directive 2026-08-09).

---

Generated by Claude Code