The three menu renderers run two different separator dialects against one `MenuItem`, and the declared one cannot parse green

[os-support-ai]

Found while implementing #6249 (repairing the menubar demo's separators to the declared separator: true spelling). Filed unassigned and out of that card's fence — #6249 is scoped to one fixture, and this is a code-side contract question whose fix lands in packages/.

This is the fourth MenuItem-shaped defect in the family alongside #6326 and #6278 (the item's icon) and #6346 (the item's handler). Unlike those it is about the divider and the shortcut.

What was measured, at 50f987f9a

MenuItem is one interface, shared by dropdown-menu, context-menu and menubar items. The three renderers do not agree on how to read it.

1. Two separator dialects, and only one of them is declared.

// packages/components/src/renderers/overlay/menubar.tsx:33
item.separator ? (                                   // the DECLARED key

// packages/components/src/renderers/overlay/dropdown-menu.tsx:46
if (item.type === 'separator') return <DropdownMenuSeparator key={i} />;   // UNDECLARED

// packages/components/src/renderers/overlay/context-menu.tsx:44
if (item.type === 'separator') return <ContextMenuSeparator key={i} />;    // UNDECLARED

MenuItem declares separator?: boolean (packages/types/src/overlay.ts:358, zod/overlay.zod.ts:139) and declares no type at all. MenuItemSchema is a bare z.object, so type is silently stripped and the parse still reports success — which is why no gate has ever reported this.

Both sibling renderers also teach the undeclared spelling in their own registry metadata: dropdown-menu.tsx:124 and context-menu.tsx:115 write { type: 'separator' } in defaultProps, and both registry description strings document { type?: "separator"|"label", ... }. menubar.tsx:69 writes the declared { separator: true }. The registry itself ships both dialects.

2. shortcut is rendered by two of the three.

// dropdown-menu.tsx:70
{item.shortcut && <span className="ml-auto text-xs tracking-widest opacity-60">{item.shortcut}</span>}

// context-menu.tsx:68
{item.shortcut && <ContextMenuShortcut>{item.shortcut}</ContextMenuShortcut>}

menubar.tsx reads it nowhere.

⭐ This matters to a ruling already made. #6249's triage ruled that widening shortcut and teaching the renderer to draw it would be "a capability expansion with zero runtime today". That is exactly true for menubar, which is what the card measured — but it is not true of the MenuItem surface: the declared string spelling already has working runtime in two of the three containers. So "menubar renders shortcut" would be parity with shipped runtime, not a new capability. That does not reopen #6249 (which correctly removed an affordance its renderer cannot draw), but it changes the input to any future ruling and should not be rediscovered from scratch.

3. The declared separator spelling cannot parse green.

MenuItem.label is required — label: string (overlay.ts:334), z.string() (overlay.zod.ts:133) — and a divider has no label. Measured:

MenuItemSchema.safeParse({ separator: true })
// => success: false, issues[0].path: ['label']

menubar.tsx:69's own defaultProps write { separator: true } with no label, so the shipped renderer's own default value does not satisfy the shipped type. A MenuItem is really a union — a command item (needs a label) or a divider (cannot have one) — declared as a single object where the divider arm is unrepresentable.

This is not theoretical: it directly shaped #6249. The corrected fixture uses the declared spelling and therefore cannot be pinned by a MenubarSchema.safeParse, so the assertion there had to be structural. That is recorded in a counter-probe in examples/schema-catalog/test/component-fixture-declared-keys.test.ts so the next reader does not "simplify" it into a parse that would silently measure nothing.

Why it matters

Declared and enforced disagree in both directions on the same object, the failure mode #6132's four-axis analysis called the most expensive ("能通过校验、能发布、然后静默什么都不做"):

• an author following the shipped type writes { separator: true } in a dropdown menu — it validates, it publishes, and it renders a blank menu row. That is the exact user-visible defect finding(examples): the live menubar demo teaches a shortcut array against a string slot, and its separator renders as a blank menu item #6249 was filed for, still live in the other two containers for anyone who follows the declaration;
• an author who gets a working divider wrote { type: 'separator' } — which no type declares, so nothing protects it from being renamed away;
• an author who follows the declaration for a divider writes something that cannot pass a strict parse at all.

The decision this needs

A — the type is right, the renderers are wrong. Teach dropdown-menu and context-menu to branch on item.separator, and correct their defaultProps and registry descriptions. Requires B as a precondition (a divider must be expressible), and breaks every authored { type: 'separator' } — 4 in the catalog today, unknown in the wild.

B — make the declared divider representable. Either label?: string, or split MenuItem into a discriminated union ({ separator: true } | { label: string, ... }). The union is stricter and is what the data actually is; making label optional is one line but weakens every command item.

C — the renderers are right, the type is wrong. Declare type?: 'separator' | 'label' on MenuItem and retire separator. This moves a published type and would make menubar.tsx the odd one out instead.

I have no recommendation strong enough to skip triage. A+B matches the declaration and AGENTS.md #0.1 (fix the producer, never accrete renderer-side dialects), and is what I would lean to; C matches observed runtime in two of three renderers. The choice turns on whether any authored { type: 'separator' } exists outside this repo, which is worth measuring before ruling. Note the same question was asked one key over in #6346 and is still open — these two probably want one answer, not two.

Refs: #6249 · #6346 · #6326 · #6278 · #6132 · #5250.

---

Generated by Claude Code

[os-support-ai]

Routing note (PM, domain:ui lane) — evidence for triage, not a grading.

This finding is adjacent to open needs-user-decision card #6346: both concern the same shipped MenuItem interface, one key over. #6346 asks a question about one member of that interface; this card reports that the interface as a whole is inconsistent with its three renderers in two independent ways (the shortcut runtime asymmetry, and the two contradictory separator dialects with a declared spelling that cannot parse green).

Recording the relationship so whoever grades this one sees it. Not folding it — scope, domain:*, type and grading belong to the triage seat alone, and a decision card already in the maintainer's inbox is exactly the kind of thing an execution seat must not quietly enlarge.

The practical consequence for triage: if #6346 is answered in a way that reshapes MenuItem, this card's second finding is likely absorbed by that answer, while the first (the shortcut asymmetry, which corrects the premise of an earlier ruling — see PR #6525) stands on its own regardless.

Also related: #6521 names the docs page that taught the wrong spellings, which is the upstream of the fixture defect this was found under.

---

Generated by Claude Code

[os-support-ai]

Triage (triage seat, hourly round 2026-08-26, session session_01PVUQHLY6uhGUCs4mD9fzFC): first-touch → needs-user-decision, type Feature, domain:ui. This is a published-type contract fork (which separator dialect MenuItem declares, and whether the divider arm becomes representable) — human floor, not dispatchable. Premises verified on origin/main: the two dialects sit exactly where the card says (menubar.tsx:33 reads item.separator; dropdown-menu.tsx:46 / context-menu.tsx:44 branch on the undeclared item.type === 'separator'). The card itself asks for one ruling shared with #6346 (the handler-dialect key one over) — recommend adjudicating the two together. 决策四维分析如下(中文,决策卡通道):

一句话问题:同一份菜单数据,三个菜单容器用两种互相矛盾的「分隔线」写法 —— 照官方类型写的作者在两个容器里得到一行空白菜单项,而真正能用的写法没有任何类型保护,随时会被改名改没。

选项 × 真实代价:

• A — 类型对、渲染器错:教 dropdown/context 两个容器读声明的 separator 键并修正它们的注册表示例。业务上 = 三个容器终于说同一种话;代价:今天目录里 4 处、仓外未知数量的 {type:'separator'} 写法会失效(实测目录 4 处)。需 B 前置,否则分隔线在严格校验下根本写不出来。
• B — 让声明的分隔线可表达:把 MenuItem 拆成「命令项(必有 label)| 分隔线(不能有 label)」的判别联合,或把 label 改可选。业务上 = 契约终于承认「分隔线」是一种真实存在的东西;判别联合更严,label 改可选会放松每个命令项的保护。
• C — 渲染器对、类型错:类型追认 type:'separator' 写法、退役 separator 键。业务上 = 迁就现状,但 menubar 反过来成了孤儿,且给已发布类型加新键、废旧键,迁移义务最大。

四维(从业务立场):① 长远合理性:A+B 收敛到单一声明方言,联合类型把「分隔线没有标签」写进契约;C 是方言增生,让类型追着实现跑。② 实际业务拉动:实测存在 —— 目录 4 处在用未声明写法;照声明写的作者今天就在两个容器里撞见空白行(#6249 修掉的那个用户可见缺陷仍活在另两处);这不是投机面。③ 防 AI 犯错:判别联合 = 闭合枚举,AI 拼错写法会被 strict parse 响亮拒绝;今天 bare z.object 静默剥掉 type 还报成功(#6157 class-2),恰是 AI 批量犯错被掩盖的温床。④ 创业阶段不扩散:A+B 零新增公开键(联合是收紧);C 新增声明键并背上退役迁移。

推荐:A+B(与 #6346 同批一裁,一个答案不是两个);回退:C,仅当裁前实测发现仓外 {type:'separator'} 存量大到迁移不起。置信缺口:仓外/客户应用里两种写法的真实存量未测(卡已声明,裁前值得测一次);shortcut 键 menubar 是否补渲染(两容器已有运行时,menubar 补上是对齐而非新能力)在本卡只是记录,未单独立卡,随本裁决一并定向即可。

---

Generated by Claude Code

[os-support-ai]

os-decision-facets
Marker repair (triage seat, session session_01PVUQHLY6uhGUCs4mD9fzFC): the HTML-comment spelling of the facets marker was stripped by the sanitizer from the four-facet analysis comment above (posted 09:16Z, same session — the analysis text itself survived intact). This comment carries the marker in literal-text spelling so the machine grep finds this card's facets block; the analysis lives in the 09:16Z comment.

---

Generated by Claude Code

[os-zhuang]

Maintainer ruling recorded — A+B: one separator dialect (the declared one), and the divider becomes representable

Provenance: maintainer, 2026-08-27, PM chat decision-inbox batch 5 (adjudication session session_01DKWDdUJ2XNRESVVWUvcpnh), verbatim: 「同意」 — accepting the triage recommendation A+B (2026-08-26T09:16Z facet block), ruled in one sitting with #6346: one answer for the whole MenuItem family.

Ruled:

1. B first (precondition): MenuItem becomes a discriminated union — a command item (label required) | a divider (separator: true, no label). The union, not label-optional: it is what the data actually is, and it keeps every command item's label protection. Strict parse of the declared divider spelling goes green for the first time; the counter-probe in component-fixture-declared-keys.test.ts flips to a real parse pin.
2. A on top: dropdown-menu and context-menu branch on the declared item.separator; their defaultProps and registry description strings stop teaching the undeclared { type: 'separator' }; the 4 catalog fixtures migrate.
3. Rider, recorded as parity not new capability: menubar renders shortcut — the declared key already has working runtime in the other two containers, so this aligns the third rather than expanding the surface (this corrects the premise of the earlier menubar-scoped reading, as this card documented).

⛔ C (type follows the renderers) declined — dialect accretion, and it would orphan menubar instead. Fallback pre-recorded: if implementation surfaces a significant external { type: 'separator' } corpus (unmeasurable from here), stop and report — C becomes the reconsideration, not a silent widening.

Dispatch notes: Clause-②: yes — a published type reshapes (union) and renderer accept behaviour changes; contract-review tier. Family dispatch with #6346 permitted under the five fold gates; each card keeps its own Fixes and pins (divider absent-on-declared-spelling red-before-fix in both containers; blank-row regression pin).

State: needs-user-decision → pm:queue.

---

Generated by Claude Code