From 4b65e8d1747ded0a3fc5d578cd6c6f31ea0a8c6a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 30 Aug 2026 02:45:21 +0000
Subject: [PATCH] docs(core): app-schema Global Actions snippet imports
 AppMenuItem, not the overlay MenuItem
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`import type { MenuItem } from '@object-ui/types'` resolves to the overlay
union (overlay.ts, re-exported bare from the barrel), but `AppAction.items`
is declared inside app.ts and so resolves to that file's own legacy
navigation-item `MenuItem`, which the barrel re-exports renamed as
`AppMenuItem` precisely to avoid this collision.

The two are mutually incompatible, not just differently named: the overlay
union declares `type?: never` on both arms, so the `{ "type": "separator" }`
item documented elsewhere on the same page is refused by the type the
snippet named.

Note: `MenuItem as AppMenuItem` does NOT fix this — that imports the bare
(overlay) export and renames it locally. `AppMenuItem` is already the
barrel's export name.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013hfmP9hoMd3dJwTh85J4yB
---
 .changeset/6692-app-schema-menuitem-import.md | 25 +++++++++++++++++++
 content/docs/core/app-schema.mdx              |  7 ++++--
 2 files changed, 30 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/6692-app-schema-menuitem-import.md

diff --git a/.changeset/6692-app-schema-menuitem-import.md b/.changeset/6692-app-schema-menuitem-import.md
new file mode 100644
index 0000000000..9b89dc297a
--- /dev/null
+++ b/.changeset/6692-app-schema-menuitem-import.md
@@ -0,0 +1,25 @@
+---
+---
+
+Docs-only fix: `content/docs/core/app-schema.mdx`'s "Global Actions" snippet imported the
+wrong same-named `MenuItem`. `import type { MenuItem } from '@object-ui/types'` resolves to
+the **overlay** union (`overlay.ts`, re-exported bare at `index.ts:255`) — the type behind
+`ui:dropdown-menu`/`ui:context-menu`/`ui:menubar`. But `AppAction.items` (`app.ts:728`) is
+declared inside `app.ts`, so it resolves to that file's own legacy navigation-item
+`MenuItem` (`app.ts:461` — `type`/`path`/`href`/`badge`/`hidden`), which the barrel
+re-exports renamed as `AppMenuItem` (`index.ts:59`) precisely to avoid this collision. The
+snippet now imports `AppMenuItem`, so a reader compiles against the shape the field really
+has.
+
+The two types are mutually incompatible, not merely differently named: the overlay union
+declares `type?: never` on both arms (dividers are `{ separator: true }` since
+objectui#6523), so the `{ "type": "separator" }` item the same page documents is *refused*
+by the type the snippet used to name.
+
+⚠️ Note for anyone re-reading the original finding: `import type { MenuItem as AppMenuItem }`
+does **not** fix this. That spelling imports the bare (overlay) export and only renames it
+locally, leaving the defect in place while looking repaired. `AppMenuItem` is already the
+barrel's export name, so the correct import is `import type { AppMenuItem }`.
+
+No published behaviour changes; no gate flips red→green (the snippet is a bare type
+reference, so it compiled either way).
diff --git a/content/docs/core/app-schema.mdx b/content/docs/core/app-schema.mdx
index 3a8d64acc9..af1ee5c261 100644
--- a/content/docs/core/app-schema.mdx
+++ b/content/docs/core/app-schema.mdx
@@ -142,7 +142,10 @@ interface MenuItem {
 The `actions` property defines global toolbar buttons:
 
 ```ts
-import type { MenuItem } from '@object-ui/types';
+// `AppAction.items` uses the navigation-item shape documented under "Navigation
+// Menu" above, which the barrel exports as `AppMenuItem`. The bare `MenuItem`
+// export is the unrelated overlay menu type used by `ui:dropdown-menu`.
+import type { AppMenuItem } from '@object-ui/types';
 
 interface AppAction {
   type: 'button' | 'dropdown' | 'user';
@@ -151,7 +154,7 @@ interface AppAction {
   onClick?: string;
   avatar?: string;        // For type='user'
   description?: string;   // For type='user'
-  items?: MenuItem[];     // For type='dropdown' or 'user'
+  items?: AppMenuItem[];  // For type='dropdown' or 'user'
   shortcut?: string;      // Keyboard shortcut
   variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link';
   size?: 'default' | 'sm' | 'lg' | 'icon';