Console renders `nav:menu` / `global:search` / `global:notifications` / `app:launcher` as "Component Placeholder" — four spec-declared PageComponentType members with no renderer

[huangyiirene]

Four page-component types that @objectstack/spec declares as first-class, no-props members of PageComponentType have no renderer in the console: each one draws the literal scaffold text Component Placeholder with its own type name above it, on the page where an author placed it.

Measured in a real browser against a running app — not read off source. Downstream tracking card: objectstack-ai/hotcrm#734 (half 1).

Environment

• @objectstack/* 17.1.0 (every package in the app pinned to it; nothing bumped for the measurement)
• App: HotCRM at objectstack-ai/hotcrm@f685136, served by objectstack dev -p 4001, seed data loaded on first boot
• Browser: Chromium 1194 via Playwright, admin-authenticated as the seeded dev admin (admin@objectos.ai), viewport 1600×1200
• Node 22.22.2, pnpm 10.33.0

Reproduction

Sign in to the console as an admin and open, in the published app:

/_console/apps/app.objectstack.hotcrm/page/sales_home_page
/_console/apps/app.objectstack.hotcrm/page/app_launcher_page
/_console/apps/app.objectstack.hotcrm/page/utility_bar_page

What renders

All five component instances across the three pages draw the placeholder. Each is a dashed-outline box containing a document-with-question-mark glyph, the component type in monospace, and the caption Component Placeholder:

Page	Component	Renders
sales_home_page	nav:menu (inside the Quick Create card)	⛔ nav:menu / Component Placeholder
app_launcher_page	global:search	⛔ global:search / Component Placeholder
app_launcher_page	app:launcher	⛔ app:launcher / Component Placeholder
utility_bar_page	global:notifications	⛔ global:notifications / Component Placeholder
utility_bar_page	global:search	⛔ global:search / Component Placeholder

Occurrences of the literal string Component Placeholder in document.body.innerText: 1 on sales_home_page, 2 on app_launcher_page, 2 on utility_bar_page.

Verbatim innerText from the app_launcher_page main region:

Central hub for accessing all applications
global:search
Component Placeholder
App Launcher
Select an app to get started
app:launcher
Component Placeholder

and from utility_bar_page:

Utility Bar
Quick access utility bar with floating tools
global:notifications
Component Placeholder
Quick Notes
global:search
Component Placeholder

This is not a page-framework failure — the same pages render everything else correctly. On sales_home_page the four object-metric KPI cards pull real figures (Revenue (Won) 1,290,000.00 / Deals Won 8 / Pipeline Value 3,775,000.00 / Open Leads 21), the embedded list views return 21 / 10 / 6 real rows, and page:header draws. Only these four component types fall through to the placeholder.

Why this is a platform gap and not app metadata using a wrong spelling

All four are named members of the PageComponentType enum shipped in @objectstack/spec@17.1.0, and each has a deliberate no-props row in ComponentPropsMap:

dist/ui/index.d.ts:

readonly 'app:launcher': z.ZodObject<{}, z.core.$strict>;
readonly 'nav:menu': z.ZodObject<{}, z.core.$strict>;
readonly 'global:search': z.ZodObject<{}, z.core.$strict>;
readonly 'global:notifications': z.ZodObject<{}, z.core.$strict>;

dist/ui/index.js:

"app:launcher": emptyProps("app:launcher"),
"nav:menu": emptyProps("nav:menu"),
"global:search": emptyProps("global:search"),
"global:notifications": emptyProps("global:notifications"),

where emptyProps builds a strict, intentionally empty props object whose own history string is explicit that the emptiness is the point:

var emptyProps = (type) => strictObject(
 {
 surface: `this \`${type}\` component`,
 history: `\`${type}\` declares no props at all. ${PROPS_HISTORY}`,
 guidanceSets: COMPONENT_LEVEL_GUIDANCE
 },
 {}
);

So the app is using the spec's sanctioned spelling, with the exact props shape the spec prescribes (properties: {}), and objectstack validate passes clean on all three pages. The metadata is right; the renderer is missing.

Impact

An end user who reaches any of these pages sees developer scaffolding. app_launcher_page and utility_bar_page are, between them, entirely placeholder plus one empty card — there is no non-scaffold content on either page. Any app that composes a launcher, a global search box, a notifications panel or a nav menu from the spec's own vocabulary gets the same result.

Ask

Either implement renderers for the four types, or — if they are not intended to be author-placeable on a page — make that explicit in the spec and in validate so the failure lands at author time rather than in front of a user. Shipping them as first-class enum members with prescribed props and no renderer is the state that produces this report.

Notes for whoever picks this up

• Screenshots of all five placeholder instances were captured during the measurement and are archived on the downstream card, [17.0-rc2验收] sales_home_page / app_launcher_page / utility_bar_page 多个组件渲染为「Component Placeholder」,首页欢迎语用户名插值为空 hotcrm#734.
• ⚠️ The downstream app metadata is deliberately being left untouched: these three pages are currently the only reproduction of this gap, so "fixing" them app-side would delete the evidence rather than the defect.
• Adjacent but separate, and not part of this report: page:card components declaring a title and no body render as titled empty boxes (Quick Notes on utility_bar_page, Recent Items / Today's Schedule on sales_home_page). That is a container with nothing to draw, not a missing renderer.
• Small spec-accuracy note while looking: PageComponentSchema.type is a z.ZodUnion<[z.ZodEnum<{…}>, z.ZodString]>, so despite being an enumerated vocabulary it accepts arbitrary strings at parse time. That is why an unimplemented type reaches the renderer as a plain string and lands on the placeholder branch rather than being rejected. It does not weaken anything above — the four names are declared members with declared props — but it is likely relevant to any fix that wants author-time rejection.

[os-trump]

Triage: needs-user-decision + domain:spec,type Feature —— 双向都在人工地板上:实现四个 renderer 是功能新增,从 spec 撤声明是删除已发布能力,均非座位可裁。浏览器实测证据完备(hotcrm#734 下游卡带截图),元数据用的是 spec 认可拼写且 objectstack validate 全绿。

选项

• A — 实现四个 renderer(objectui 侧:nav:menu / global:search / global:notifications / app:launcher)。四个都是真实产品面(启动器、全局搜索、通知、导航),但工作量为四个独立组件,且各自需要平台数据源(通知流、搜索后端)。可分期:先做有数据源支撑的。
• B — 从 PageComponentType 撤这四个成员(ADR-0087 通道),validate 在作者期响亮拒绝。删除已发布 enum 成员,hotcrm 三页元数据须同步改。
• C — 保留声明 + validate 作者期警告「declared but not yet rendered」,不撤不实现。最便宜,但延续「能通过校验、能发布、然后渲染成脚手架」的状态,与 declared=enforced 原则冲突。

推荐:A 的分期形态(先 app:launcher + nav:menu 这两个纯元数据驱动、无外部数据源依赖的;global:search/global:notifications 视平台侧数据源就绪度定),同时 B 兜底:凡近期不打算实现的成员按 B 撤。附注:正文尾部的 spec 精度观察(PageComponentSchema.type 的 union 对任意 string 放行,导致未实现类型走到 placeholder 而非被拒)无论 A/B 都值得随裁决一并处置。

<!-- os-decision-facets -->

轴	读数
① 实际业务需求	实测成立:hotcrm 两个页面除 placeholder 外几乎无内容,终端用户直接看到开发脚手架;启动器/搜索/通知是标准产品面
② 项目长远合理性	声明为一等 enum 成员 + 规定 props 形状却无渲染器,是 declared≠enforced 的教科书形;A 兑现声明,B 收回声明,C 延续裂缝
③ 防 AI 写错	最贵的失败形:AI 作者用 spec 词表组页,校验全绿,渲染成脚手架且无任何报错;A/B 都消除该形,C 仅降级为警告
④ 创业阶段不扩散	A 是四个组件的真实工作量,分期可控;B 零实现成本但砍掉标准产品面的声明;纯增量最小的是 C 但它不闭合缺口

Triage seat session session_01TMpU2R7qfDGR8rHKBay9uJ。

---

Generated by Claude Code

[os-steve]

Maintainer ruling recorded — A, phased; B for any member not planned within the horizon

Provenance: maintainer, 2026-08-26, live PM chat (decision-inbox batch 3, session session_01JANH3y7qe3MD8aLaLXci8N), verbatim: 「其他接受你的建议」 — accepting the presented recommendation.

• Phase 1: implement renderers for app:launcher and nav:menu — the two purely metadata-driven members with no external data-source dependency. Landing is objectui's console; the spec seat decomposes contract-first (parent card + per-repo sub-issues with Blocked-by:) per the standing cross-repo split.
• Phase 2: global:search / global:notifications — read platform data-source readiness FIRST; a member with no data-source plan inside the horizon is retired per B (ADR-0087 channel, author-time loud rejection) rather than left as a declared-unrendered trap.
• Rides with the ruling: the spec-accuracy note from the card's tail — PageComponentSchema.type's union accepts arbitrary strings at parse time, which is why an unimplemented type reaches the renderer as a plain string; the author-time rejection half gets handled alongside whichever phase touches the enum.
• The reproduction pages in hotcrm stay untouched until a renderer lands (they are the only evidence).

State: needs-user-decision → pm:queue (domain:spec stands; spec seat owns the decomposition).

---

Generated by Claude Code