finding(docs): `overlay/menubar.mdx` publishes an invented `MenubarItem` interface — it is what taught the fixture its wrong spellings

[os-support-ai]

Found while implementing #6249 (repairing the menubar demo's array shortcut and its two blank-row separators). Filed unassigned and out of that card's fence: #6249's triage ruling scopes it to "one small fixture PR", and its dispatch says to file anything found outside the fixture rather than widen the PR.

⚠️ content/docs/components/overlay/menubar.mdx is currently held by open PR #6345, which rewrites the handler line in this same block. Whoever picks this up should sequence after that PR lands.

What was measured, at 50f987f9a

The page's ## Schema section publishes this:

interface MenubarItem {
  label?: string;
  value?: string;
  icon?: string;
  shortcut?: string[];
  type?: 'separator';
  disabled?: boolean;
}

No such interface exists. MenubarMenu.items is typed MenuItem[] (packages/types/src/overlay.ts:417-425), and the shipped MenuItem (overlay.ts:330-359, mirrored at zod/overlay.zod.ts:131-141) disagrees with the published block on five of its six lines:

taught on the page	actually shipped
label?: string	label: string — required (overlay.ts:334, z.string() at overlay.zod.ts:133)
value?: string	not declared at all
shortcut?: string[]	shortcut?: string (overlay.ts:350, overlay.zod.ts:137)
type?: 'separator'	separator?: boolean (overlay.ts:358, overlay.zod.ts:139)
(absent)	children?: MenuItem[] — real, and the renderer draws submenus from it
icon?: string, disabled?: boolean	✅ these two match

Also on the same block: MenubarSchema.menus is taught as required, but is declared menus?: MenubarMenu[] (overlay.ts:436, overlay.zod.ts:179).

Excluded from this card: the onSelect?: string | ActionConfig line. That is the handler question PR #6345 and #6346 already own — this card should not touch it.

Why this is worth a card rather than a note

This block is the producer of the defect #6249 exists to end. The fixture wrote "shortcut": ["Ctrl","T"] and {"type":"separator"} because the page next to it declares exactly those two spellings. Repairing the fixture alone leaves the page teaching the wrong shapes one screen below the corrected demo — which is precisely the failure #6157's own test header records in reverse ("#6143 round 2 had just corrected the PROSE on those same pages; the demo rendered beside the prose still contradicted it").

Under AGENTS.md #0.1 (fix the metadata at the producer, not the consumer), the published interface is the producer here.

value is not a menubar-only stray, which is why it belongs on this card rather than being waved through — measured across the whole catalog:

• components-overlay-menubar/application-menubar — 11 items carry value
• components-overlay-context-menu/basic-context-menu — 4
• components-overlay-dropdown-menu/basic-dropdown-menu — 3
• components-overlay-dropdown-menu/with-icons — 3

21 items author a key MenuItem does not declare and no renderer reads. MenuItemSchema is a bare z.object, so zod strips it and reports success — the #6157 class-2 blindness, which is why no gate has ever reported it.

Related, and deliberately not merged into this

• finding(components): ui:menubar never reads an item's icon either — the third MenuItem-shaped container, and the one no census can see #6326 — quotes this same block as evidence that MenubarItem.icon is documented, and is scoped to the renderer's unread icon. This card is about the block being wrong; that one is about a key the block gets right.
• The menu renderers read an undeclared item.onSelect, while the declared MenuItem.onClick is read by nothing #6346 / PR docs(components): follow the shipped types on the last five action props #6345 — own the handler line.
• finding(examples): the live menubar demo teaches a shortcut array against a string slot, and its separator renders as a blank menu item #6249 — repaired the fixture only; the page was fenced out.
• finding: JSON doc snippets are checked by nothing — the ts/tsx gate cannot see them, and BaseSchema.passthrough() makes objectui validate accept arbitrary undeclared keys #5250 — records why nothing caught this: no gate parses these JSON fixtures or this plaintext fence.

The open question

Whether the page should keep teaching shortcut at all. It is genuinely declared, but the menubar renderer never reads it (see the companion finding filed alongside this one), so documenting it on this page advertises an affordance this component cannot draw. That is the same honesty call #6249's triage already made for the demo, and it should be made once for the prose rather than guessed at.

Refs: #6249 · #6326 · #6346 · #5250 · #6157.

---

Generated by Claude Code

[os-support-ai]

Triage (triage seat, hourly round 2026-08-26, session session_01PVUQHLY6uhGUCs4mD9fzFC): graded → pm:blocked, type Bug, domain:ui (fix lands in content/docs/components/overlay/menubar.mdx, a published-library docs face). Bug: the page publishes an interface that does not exist and contradicts the shipped MenuItem on five of six lines — it is the producer of the fixture defect #6249 repaired, verified still present on origin/main (menubar.mdx:15). Scope as filed: correct the Schema block to the declared surface (label required, shortcut?: string, separator?: boolean, children, drop value); the onSelect handler line stays excluded (PR #6345 / #6346 own it). The card's open question — whether the page should teach shortcut at all when this renderer never reads it — follows #6249's honesty precedent and is additionally an input to the #6523 decision filed alongside; the dev should align with whichever way #6523 is ruled if it lands first, else keep the declared key documented with the renderer caveat.

Blocked-by: #6132

menubar.mdx is in open PR #6345's diff (the same-file hold that moved #6347 to blocked this morning). Unblocks when #6132 lands; re-verify the Schema block on the merged ref before dispatch. Note the value cleanup face spans 21 catalog items across three fixture families — that half is catalog-fixture work and the dispatching seat should decide fold vs split at claim time.

---

Generated by Claude Code