@forgeax/interface 0.4.1

package/dist/package/browser/components/MenuBar/MenuBar.css

@@ -0,0 +1,186 @@
+/* MenuBar (T2) — Web menu bar rendered inside TopBar's `.tb-left`.
+   Sits before ProjectSwitcher, uses the same 12px font-size / secondary text
+   color idiom as the rest of TopBar. Under Tauri, only the brand row renders
+   (or nothing) — the OS draws the real menu bar. */
+
+.fx-menubar {
+  display: inline-flex;
+  align-items: center;
+  gap: 2px;
+  flex-shrink: 0;
+  height: 100%;
+}
+
+.fx-menubar-btn {
+  /* Full-bar-height cell: the hover/open highlight fills the whole menubar
+     height instead of a short chip. Only horizontal padding (9px); the label
+     stays vertically centred via align-items, so its position doesn't shift. */
+  display: inline-flex;
+  align-items: center;
+  height: 100%;
+  padding: 0 9px;
+  background: transparent;
+  border: none;
+  /* Square hover/open highlight (no 倒角) to match the flush, square-cornered
+     top bar + dock chrome. */
+  border-radius: 0;
+  color: var(--color-text-secondary);
+  font-size: 12px;
+  cursor: pointer;
+  flex-shrink: 0;
+  white-space: nowrap;
+  transition:
+    background var(--motion-duration-instant) var(--motion-ease-standard),
+    color var(--motion-duration-instant) var(--motion-ease-standard);
+}
+.fx-menubar-btn:hover {
+  /* Bumped from --color-interaction-hover (0.05) to the neutral-selected surface
+     (0.10) so the top-level pill highlight is legible against TopBar — the 0.05
+     overlay read as almost invisible here. */
+  background: var(--color-interaction-selected-neutral, var(--color-interaction-hover));
+  color: var(--color-text-primary);
+}
+/* Open menu (UE-style): the trigger whose panel is showing stays lit in the
+   brand theme colour, so it's obvious which top-level menu owns the open panel
+   even while you sweep the pointer across siblings. Placed after :hover so the
+   brand tint wins when the open trigger is also hovered. */
+.fx-menubar-btn[data-state="open"] {
+  background: var(--color-interaction-selected-brand);
+  color: var(--color-brand-primary);
+}
+
+/* Brand entry — mirrors the prototype `.mb-brand`: a glowing rounded mark plus
+   the product name in brand colour. Web only (desktop uses the native menu).
+   Placed after the base rule so its resting colour wins; :hover still lifts the
+   name to primary (like the prototype), while the mark keeps its own fill. */
+.fx-menubar-btn--brand {
+  gap: 5px;
+  color: var(--color-brand-primary);
+  font-weight: 600;
+}
+.fx-menubar-brand-mark {
+  display: grid;
+  place-items: center;
+  width: 18px;
+  height: 18px;
+  border-radius: 5px;
+  background: var(--color-brand-primary);
+  color: var(--color-text-on-bright-primary);
+  font-weight: 800;
+  font-size: 11px;
+  box-shadow: 0 0 12px rgba(212, 255, 72, 0.35);
+  flex-shrink: 0;
+}
+
+/* Dropdown content — mirrors the prototype's `.fe-ctx` floating panel
+   (5px padding, 9px radius). Rows lay out check / icon / label / keybinding. */
+.fx-menubar-content {
+  min-width: 200px;
+  padding: 5px;
+  border-radius: 9px;
+  background: var(--color-background-elevated, #242424);
+  color: var(--color-text-primary, #fff);
+  border: 1px solid var(--color-border-default, rgba(255, 255, 255, 0.1));
+  box-shadow: 0 12px 30px rgba(0, 0, 0, 0.48);
+}
+
+.fx-menubar-content .fx-menubar-item-check {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 14px;
+  min-width: 14px;
+  color: var(--color-text-primary);
+}
+.fx-menubar-content .fx-menubar-item-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 14px;
+  min-width: 14px;
+  /* No margin — the row's flex `gap` spaces the glyph from the label.
+     Prototype `.fe-ctx-item svg`: dim at rest, lifts to secondary on hover. */
+  color: var(--color-text-tertiary, rgba(255, 255, 255, 0.3));
+  flex-shrink: 0;
+}
+.fx-menubar-content .fx-menubar-item-icon svg {
+  width: 14px;
+  height: 14px;
+}
+.fx-menubar-content .fx-menubar-item-label {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.fx-menubar-content .fx-menubar-item-kbd {
+  margin-left: 24px;
+  font-family: var(--font-mono);
+  font-size: 10px;
+  letter-spacing: 0.02em;
+  color: var(--color-text-tertiary, rgba(255, 255, 255, 0.2));
+  flex-shrink: 0;
+}
+
+.fx-menubar-item--danger {
+  color: var(--destructive, #e05260);
+}
+
+/* Disabled rows (unsatisfied capabilities) show a not-allowed cursor. The shared
+   dropdown primitive sets `data-[disabled]:pointer-events-none`, which would
+   suppress the cursor entirely — so re-enable pointer events in the menubar
+   scope. Radix still blocks onSelect for disabled items, so no action fires.
+   Selector specificity (0,3,0) beats the primitive utility (0,2,0). */
+.fx-menubar-content .fx-menubar-item[data-disabled] {
+  pointer-events: auto;
+  cursor: not-allowed;
+}
+
+/* Dropdown rows aligned to the prototype's `.fe-ctx-item`: 6px/9px padding,
+   5px radius, 12px text. Scoped to `.fx-menubar-content` so the shared dropdown
+   primitive used elsewhere is untouched. Colour is split by kind so danger and
+   disabled rows keep their own treatment (see below). */
+.fx-menubar-content .fx-menubar-item {
+  gap: 9px;
+  /* Left padding trimmed vs right so the leading icon sits closer to the edge. */
+  padding: 6px 9px 6px 7px;
+  border-radius: 5px;
+  font-size: 12px;
+}
+.fx-menubar-content .fx-menubar-item:not(.fx-menubar-item--danger) {
+  color: var(--color-text-secondary);
+}
+
+/* Hover / keyboard-highlight (Radix moves focus to the pointed row). Normal rows
+   paint the neutral-selected surface with primary text; danger rows keep red on
+   a red tint (prototype `.fe-ctx-item.danger:hover`). `:not([data-disabled])`
+   leaves disabled rows greyed with no hover paint. `[data-state="open"]` covers
+   a SubTrigger whose submenu is open (e.g. 打开最近) — without it, the ui/dropdown
+   default `data-[state=open]:bg-accent` (brand-green) would leak through. */
+.fx-menubar-content .fx-menubar-item:not(.fx-menubar-item--danger):not([data-disabled]):hover,
+.fx-menubar-content .fx-menubar-item:not(.fx-menubar-item--danger):not([data-disabled]):focus,
+.fx-menubar-content .fx-menubar-item:not(.fx-menubar-item--danger):not([data-disabled])[data-highlighted],
+.fx-menubar-content .fx-menubar-item:not(.fx-menubar-item--danger):not([data-disabled])[data-state="open"] {
+  background: var(--color-interaction-selected-neutral, var(--color-interaction-hover));
+  color: var(--color-text-primary);
+}
+.fx-menubar-content .fx-menubar-item:not(.fx-menubar-item--danger):not([data-disabled]):hover .fx-menubar-item-icon,
+.fx-menubar-content .fx-menubar-item:not(.fx-menubar-item--danger):not([data-disabled]):focus .fx-menubar-item-icon,
+.fx-menubar-content .fx-menubar-item:not(.fx-menubar-item--danger):not([data-disabled])[data-highlighted] .fx-menubar-item-icon,
+.fx-menubar-content .fx-menubar-item:not(.fx-menubar-item--danger):not([data-disabled])[data-state="open"] .fx-menubar-item-icon {
+  color: var(--color-text-secondary);
+}
+.fx-menubar-content .fx-menubar-item--danger:not([data-disabled]):hover,
+.fx-menubar-content .fx-menubar-item--danger:not([data-disabled]):focus,
+.fx-menubar-content .fx-menubar-item--danger:not([data-disabled])[data-highlighted] {
+  background: rgba(242, 106, 106, 0.14);
+  color: var(--color-accent-error, var(--destructive, #e05260));
+}
+
+/* Group-boundary separator — prototype `.fe-ctx-sep`. */
+.fx-menubar-content [role="separator"] {
+  height: 1px;
+  margin: 4px 6px;
+  background: var(--color-divider-subtle, var(--color-border-subtle));
+}

package/dist/package/browser/components/MenuBar/MenuBar.d.ts

@@ -0,0 +1,27 @@
+import { type TFunction } from '../../i18n';
+import { type MenuId, type MenuItemDef } from '../../lib/menu-registry';
+import './MenuBar.css';
+/** 第三个参数 itemId 是**记账用**的稳定菜单项 id(如 file.save)。可选,所以
+ *  只传两参的既有调用点照常编译。为什么需要它:人机同账要求两侧记录形状一致 ——
+ *  AI 那路按 itemId 派发,人这路手上只有解析后的 commandId,不带上 itemId 的话
+ *  两条记录对不上号(help.shortcuts 与 overlay.open 是同一动作的两个名字),
+ *  比对"人和 AI 是不是做了同一件事"就得二次查菜单注册表。 */
+type Execute = (id: string, args?: unknown, itemId?: string) => void;
+interface TopMenuProps {
+    menu: MenuId;
+    items: MenuItemDef[];
+    t: TFunction;
+    execute: Execute;
+    /** Controlled open flag — the whole bar shares one "which menu is open"
+     *  value so sibling hover can steal the open panel (UE-style). */
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** Pointer-down claims ownership before Radix evaluates its controlled root. */
+    onTriggerPointerDown: (event: React.PointerEvent<HTMLButtonElement>) => void;
+    /** Pointer entered this trigger. The bar decides whether to switch the open
+     *  panel here (only when some OTHER menu is already open). */
+    onTriggerEnter: () => void;
+}
+export declare function TopMenu({ menu, items, t, execute, open, onOpenChange, onTriggerPointerDown, onTriggerEnter }: TopMenuProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function MenuBar(): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/package/browser/components/MenuBar/MenuBar.js

@@ -0,0 +1,286 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * MenuBar — Web renderer for the menu registry (T2).
+ *
+ * Subscribes to `lib/menu-registry` via `useSyncExternalStore` and renders
+ * top-level dropdowns for `file` / `edit` / `window` / `build` / `select` /
+ * `help` (in that order). `brand` renders first as a small app-menu dropdown.
+ * `publish` is intentionally excluded — TopBar already owns a Publish button.
+ *
+ * Platform guard: under Tauri the OS draws the real menu bar (T5's native
+ * bridge), so we render ONLY the brand entry (or nothing when brand is empty).
+ * On web we render the full bar.
+ *
+ * Commands: clicking a leaf item dispatches through the SAME accessor TopBar
+ * uses — `useHost().commands.execute(id, args)` (`useCommand<T>(id)` bakes the
+ * id into the callback, which doesn't fit here since ids are dynamic at click
+ * time; the underlying accessor is identical). This keeps keyboard shortcuts,
+ * command palette, and menu clicks on one entry.
+ */
+import { useCallback, useEffect, useState, useSyncExternalStore } from 'react';
+import { BookOpen, BoxSelect, Check, Clipboard, Clock, Code, Copy, FilePlus, FlipHorizontal2, Focus, FolderOpen, FolderSearch, Gamepad2, Github, Globe, GraduationCap, Hash, Info, Keyboard, LayoutGrid, Maximize, MessageCircle, Newspaper, Package, Pencil, Play, Redo2, RefreshCw, RotateCcw, Save, SaveAll, Scale, Scan, Scissors, ScrollText, Search, Settings, Shapes, Sparkles, Square, SquareDashed, Store, Trash2, Undo2, Upload, X, } from 'lucide-react';
+import { useTranslation } from '../../i18n';
+import { useHost } from '../../core/app-shell';
+import { useBrand } from '../../brand/BrandProvider';
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent, } from '../ui/dropdown-menu';
+import { onMenuChange, snapshotAllMenus, } from '../../lib/menu-registry';
+import { prettyCombo } from '../../lib/global-shortcuts';
+import { useMenubarSurface } from './menubar-surface';
+import { openMenuFromTriggerPointerDown } from './menubar-open-state';
+import { isTauri } from '../../lib/platform/runtime';
+import { captureFocusedTextEditTarget } from '../../lib/text-edit-actions';
+import { getRecentGamesRevision, subscribeRecentGames, warmRecentGames, } from '../../lib/recent-games';
+import { repairBuiltinMenusIfEmpty } from '../../lib/repair-builtin-menus';
+import './MenuBar.css';
+// Icon name → lucide component. Mirrors ContextMenu.tsx's MENU_ICONS pattern
+// (single-file lookup so an unknown name gracefully renders no icon rather
+// than crashing). Static import — never dynamic — so the bundle keeps only
+// the icons actually referenced from builtin-menus.ts.
+const MENU_ICONS = {
+    'book-open': BookOpen,
+    'box-select': BoxSelect,
+    clipboard: Clipboard,
+    clock: Clock,
+    code: Code,
+    copy: Copy,
+    'file-plus': FilePlus,
+    'flip-horizontal-2': FlipHorizontal2,
+    focus: Focus,
+    'folder-open': FolderOpen,
+    'folder-search': FolderSearch,
+    'gamepad-2': Gamepad2,
+    github: Github,
+    globe: Globe,
+    'graduation-cap': GraduationCap,
+    hash: Hash,
+    info: Info,
+    keyboard: Keyboard,
+    'layout-grid': LayoutGrid,
+    maximize: Maximize,
+    'message-circle': MessageCircle,
+    newspaper: Newspaper,
+    package: Package,
+    pencil: Pencil,
+    play: Play,
+    'redo-2': Redo2,
+    'refresh-cw': RefreshCw,
+    'rotate-ccw': RotateCcw,
+    save: Save,
+    'save-all': SaveAll,
+    scale: Scale,
+    scan: Scan,
+    scissors: Scissors,
+    'scroll-text': ScrollText,
+    search: Search,
+    settings: Settings,
+    shapes: Shapes,
+    sparkles: Sparkles,
+    square: Square,
+    'square-dashed': SquareDashed,
+    store: Store,
+    'trash-2': Trash2,
+    'undo-2': Undo2,
+    upload: Upload,
+    x: X,
+};
+// ── snapshot cache (stable identity across getSnapshot calls) ────────────
+// snapshotAllMenus() computes a fresh object each call; useSyncExternalStore
+// requires that repeated getSnapshot() reads return the SAME identity until
+// the store actually changes, else React re-renders on every read (potential
+// infinite loop). Module-level cache + a single change-listener keeps identity
+// stable between registrations. Registry lives as long as this module, so a
+// single unbound listener at import time is fine (no cleanup handle needed).
+let cachedSnapshot = snapshotAllMenus();
+onMenuChange(() => { cachedSnapshot = snapshotAllMenus(); });
+function getSnapshot() {
+    return cachedSnapshot;
+}
+// SSR/server snapshot — stable identity across calls. This app is a pure
+// client build, so this branch never actually fires; providing it satisfies
+// the useSyncExternalStore contract and future-proofs against SSR.
+const EMPTY_SNAPSHOT = Object.freeze({
+    brand: [], file: [], edit: [], window: [], build: [], select: [], help: [], publish: [],
+});
+function getServerSnapshot() {
+    return EMPTY_SNAPSHOT;
+}
+function subscribe(cb) {
+    return onMenuChange(cb);
+}
+// Top-level dropdowns rendered on web, in order. `publish` is excluded (TopBar
+// owns the Publish CTA at the far right); `brand` renders separately at the
+// far left.
+const TOP_MENUS = [
+    'file', 'edit', 'window', 'build', 'select', 'help',
+];
+/** Compute the resolved enabled flag for one item.
+ *  - Explicit `enabled()` always wins.
+ *  - Items with children (static or dynamic) default to enabled (a submenu
+ *    opener needs no cmd).
+ *  - Leaf items default to `!!commandId` (no command = no-op = disabled). */
+function resolveEnabled(item) {
+    if (item.enabled)
+        return item.enabled();
+    if ((item.children && item.children.length > 0) || item.dynamicChildren)
+        return true;
+    return !!item.commandId;
+}
+function MenuItemRow({ item, t, execute }) {
+    // when=false items are hidden entirely (caller also skips their separator).
+    if (item.when && !item.when())
+        return null;
+    const enabled = resolveEnabled(item);
+    const label = t(item.labelKey);
+    const combo = item.keybinding ? prettyCombo(item.keybinding) : '';
+    const checked = item.checked ? item.checked() : false;
+    const hasStaticChildren = !!item.children && item.children.length > 0;
+    const hasChildren = hasStaticChildren || !!item.dynamicChildren;
+    const dangerCls = item.danger ? 'fx-menubar-item--danger text-destructive focus:text-destructive' : '';
+    // Left glyph — a SINGLE slot, like the prototype's `.fe-ctx-item`: a checkable
+    // item shows its check state there, every other item shows its icon. Rendering
+    // both a check column AND an icon would reserve an empty column that shoves the
+    // icon right, so we pick one. Unknown / missing icon name renders nothing.
+    const Icon = item.icon ? MENU_ICONS[item.icon] : undefined;
+    const iconNode = Icon
+        ? _jsx("span", { className: "fx-menubar-item-icon", "aria-hidden": "true", children: _jsx(Icon, { size: 14 }) })
+        : null;
+    const leftNode = item.checked
+        ? (_jsx("span", { className: "fx-menubar-item-check", "aria-hidden": "true", children: checked ? _jsx(Check, { size: 12 }) : null }))
+        : iconNode;
+    if (hasChildren) {
+        // Dynamic children are evaluated fresh on each render of the SubContent.
+        // Radix mounts SubContent lazily (on hover-open) and unmounts on close, so
+        // `item.dynamicChildren()` runs at open-time — the caller must have the data
+        // ready synchronously (see file-menu game-list prefetch). Empty result → a
+        // single disabled "no recent" placeholder so the submenu never looks broken.
+        const kids = hasStaticChildren ? item.children : item.dynamicChildren();
+        return (_jsxs(DropdownMenuSub, { children: [_jsxs(DropdownMenuSubTrigger, { disabled: !enabled, className: ['fx-menubar-item', dangerCls].filter(Boolean).join(' '), children: [leftNode, _jsx("span", { className: "fx-menubar-item-label", children: label })] }), _jsx(DropdownMenuSubContent, { className: "fx-menubar-content", children: kids.length > 0
+                        ? renderMenuChildren(kids, t, execute)
+                        : (_jsx(DropdownMenuItem, { disabled: true, className: "fx-menubar-item", children: _jsx("span", { className: "fx-menubar-item-label", children: t('menu.file.openRecentEmpty') }) })) })] }));
+    }
+    // Leaf. Disabled leaves render as text-only rows: greyed, no click handler,
+    // still showing label + keybinding. Radix `disabled` prop applies pointer-
+    // events-none + opacity via the ui/dropdown-menu component styling.
+    return (_jsxs(DropdownMenuItem, { disabled: !enabled, className: ['fx-menubar-item', dangerCls].filter(Boolean).join(' '), onSelect: (e) => {
+            if (!enabled || !item.commandId) {
+                e.preventDefault();
+                return;
+            }
+            execute(item.commandId, item.args, item.id);
+        }, children: [leftNode, _jsx("span", { className: "fx-menubar-item-label", children: label }), combo && _jsx("span", { className: "fx-menubar-item-kbd", children: combo })] }));
+}
+/** Walk a sorted item list, inserting a `DropdownMenuSeparator` at each
+ *  group boundary. Boundary rule mirrors `serializeMenusForNative` in the
+ *  registry: `prevGroup` is updated even for hidden items so the separator
+ *  policy stays identical between the two renderers (§SSOT / §Derive). */
+function renderMenuChildren(items, t, execute) {
+    const rows = [];
+    let prevGroup = null;
+    for (const it of items) {
+        const hidden = it.when ? !it.when() : false;
+        if (!hidden && prevGroup !== null && it.group !== prevGroup) {
+            rows.push(_jsx(DropdownMenuSeparator, {}, `sep-${it.id}`));
+        }
+        if (!hidden) {
+            rows.push(_jsx(MenuItemRow, { item: it, t: t, execute: execute }, it.id));
+        }
+        prevGroup = it.group;
+    }
+    return rows;
+}
+export function TopMenu({ menu, items, t, execute, open, onOpenChange, onTriggerPointerDown, onTriggerEnter }) {
+    const brand = useBrand();
+    // The async warm completes after File has rendered. Subscribe so an
+    // already-open recent submenu replaces its empty placeholder immediately.
+    useSyncExternalStore(subscribeRecentGames, getRecentGamesRevision, getRecentGamesRevision);
+    if (items.length === 0)
+        return null;
+    const isBrand = menu === 'brand';
+    // Top-level titles are fixed labels (`menubar.<menu>`). If i18n hasn't been
+    // populated yet (T3 owns that), `t()` falls back to returning the key so we
+    // don't crash — we just show "menubar.file" in place of "File" until T3.
+    const titleKey = `menubar.${menu}`;
+    return (_jsxs(DropdownMenu, { open: open, onOpenChange: onOpenChange, modal: false, children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsx("button", { type: "button", className: isBrand ? 'fx-menubar-btn fx-menubar-btn--brand no-motion-lift' : 'fx-menubar-btn no-motion-lift', "data-menu": menu, onPointerDown: (event) => {
+                        if (menu === 'edit' || menu === 'select') {
+                            captureFocusedTextEditTarget(event.currentTarget.ownerDocument);
+                        }
+                        onTriggerPointerDown(event);
+                    }, onPointerEnter: onTriggerEnter, children: isBrand ? (_jsxs(_Fragment, { children: [_jsx("span", { className: "fx-menubar-brand-mark", "aria-hidden": "true", children: brand.product.name.charAt(0).toUpperCase() }), _jsx("span", { className: "fx-menubar-brand-name", children: brand.product.name })] })) : (t(titleKey)) }) }), _jsx(DropdownMenuContent, { align: "start", sideOffset: 4, className: "fx-menubar-content", children: renderMenuChildren(items, t, execute) })] }));
+}
+// ── Public component ─────────────────────────────────────────────────────
+export function MenuBar() {
+    // StrictMode dispose / Vite HMR can leave the registry empty while chrome
+    // stays mounted — repair synchronously so the first render sees menus.
+    repairBuiltinMenusIfEmpty();
+    const { t, i18n } = useTranslation();
+    const menus = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+    const host = useHost();
+    // Same command bus TopBar uses. Fire-and-forget: menu clicks never await
+    // the command result — that would block dropdown-close animation.
+    // 纯执行,不记账。AI 经 host.menubar.invoke 走的就是这一个 —— 它那一路已经由
+    // dispatchToSurface 记了 source:'ai',这里再补一次会变成同一次操作在账本里既是
+    // ai 又是 user(而 /dispatched 端点无条件打 source:'user',分不出调用方)。
+    const execute = useCallback((id, args) => { void host.commands.execute(id, args); }, [host]);
+    // 人点菜单项才走这个:先补账再执行。人机同账的语义是"同一条 handler、只用 source
+    // 区分",所以记账必须挂在**人这条调用点**上,不能挂在两路共用的 execute 里。
+    // 两侧统一记 { itemId, commandId } —— 不统一的话账本里 AI 记 itemId、人记
+    // commandId,同一个动作两种名字,离线比对还得回查注册表(2026-08-05 实测)。
+    // fire-and-forget,失败静默(账本是观测面,不是功能依赖)。
+    const executeFromClick = useCallback((id, args, itemId) => {
+        void fetch('/api/bus/ui/surfaces/host.menubar/dispatched', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ action: 'invoke', args: { itemId, commandId: id, args } }),
+        }).catch(() => { });
+        execute(id, args);
+    }, [execute]);
+    // AI 面(host.menubar.invoke)的执行器:**await 命令本体** —— 命令失败要变成
+    // ack ok=false,agent 才不会把失败说成"已完成"(2026-08-06 外审 B6①:此前同步
+    // 返回,file.save 失败也被 ack 成功)。人点击仍走上面的 fire-and-forget(不卡
+    // 下拉动画);两者只差等不等结果,handler 是同一个 commands.execute。
+    const executeForSurface = useCallback((id, args) => Promise.resolve(host.commands.execute(id, args)), [host]);
+    // Dual-modality projection: publish the menu tree + an `invoke` action that
+    // runs the SAME execute a human click runs. Must sit before the isTauri()
+    // early return (hooks rule); the registry stays the SSOT either way.
+    // 传 i18n.language 而不是 t:`t` 是模块级恒定标识(i18n/index.ts 刻意如此,
+    // 免得列进依赖数组造成无限重渲染),用它当依赖等于永不重投影 —— 切语言后 DOM
+    // 变了、snapshot 还是旧语言,AI 按 label 导航与用户所见错位(2026-08-06 探测)。
+    useMenubarSurface(menus, t, executeForSurface, i18n.language);
+    // One shared "which top-level menu is open" value for the whole bar. This is
+    // what makes it behave like a native/UE menu bar rather than N unrelated
+    // dropdowns: only one panel is open at a time, and once ANY panel is open,
+    // pointer-entering a sibling trigger steals the open state to it (see
+    // `handleTriggerEnter`). `null` = closed bar (idle: hover just highlights,
+    // it does NOT open — matching UE, where you must click to arm the bar).
+    const [openMenu, setOpenMenu] = useState(null);
+    // File owns a dynamic 打开最近 submenu backed by an async game list. Warm the
+    // cache whenever File becomes the open menu — via click OR hover-steal — so
+    // `getRecentGames()` is populated by the time the user reaches the submenu.
+    useEffect(() => {
+        if (openMenu === 'file')
+            void warmRecentGames();
+    }, [openMenu]);
+    const handleOpenChange = useCallback((menu) => (isOpen) => {
+        // Radix fires (false) on the previously-open menu when we steal focus to
+        // a sibling; only honour a close if THIS menu is still the current one,
+        // else the steal would immediately re-close the bar.
+        setOpenMenu((cur) => (isOpen ? menu : cur === menu ? null : cur));
+    }, []);
+    const handleTriggerEnter = useCallback((menu) => () => {
+        // Steal the open panel to the hovered trigger, but only while the bar is
+        // already armed (some other menu open). Idle hover must not auto-open.
+        setOpenMenu((cur) => (cur !== null && cur !== menu ? menu : cur));
+    }, []);
+    const handleTriggerPointerDown = useCallback((menu) => (event) => {
+        setOpenMenu((cur) => openMenuFromTriggerPointerDown(cur, menu, event.nativeEvent));
+    }, []);
+    // Under Tauri the OS native menu is the SSOT for the whole menu bar (T5
+    // bridge) — brand/app menu included — so the HTML bar renders nothing at all
+    // (no brand chip, no dropdowns). The trailing divider goes with it.
+    if (isTauri())
+        return null;
+    return (_jsxs(_Fragment, { children: [_jsxs("div", { className: "fx-menubar", children: [menus.brand.length > 0 && (_jsx(TopMenu, { menu: "brand", items: menus.brand, t: t, 
+                        // 人点击走 executeFromClick(先补账再执行),不是共用的 execute ——
+                        // 人机同账靠的就是记账挂在人这条调用点上。main 新加的悬停切换 props 照收。
+                        execute: executeFromClick, open: openMenu === 'brand', onOpenChange: handleOpenChange('brand'), onTriggerPointerDown: handleTriggerPointerDown('brand'), onTriggerEnter: handleTriggerEnter('brand') })), TOP_MENUS.map((m) => (_jsx(TopMenu, { menu: m, items: menus[m], t: t, execute: executeFromClick, open: openMenu === m, onOpenChange: handleOpenChange(m), onTriggerPointerDown: handleTriggerPointerDown(m), onTriggerEnter: handleTriggerEnter(m) }, m)))] }), _jsx("span", { className: "tb-divider", "aria-hidden": "true" })] }));
+}

package/dist/package/browser/components/MenuBar/index.d.ts

@@ -0,0 +1 @@
+export { MenuBar } from './MenuBar';

package/dist/package/browser/components/MenuBar/index.js

@@ -0,0 +1 @@
+export { MenuBar } from './MenuBar';

package/dist/package/browser/components/MenuBar/menubar-open-state.d.ts

@@ -0,0 +1,8 @@
+import type { MenuId } from '../../lib/menu-registry';
+/**
+ * A top-level trigger must claim the shared menubar state on pointer-down.
+ * Radix still owns the matching open/close notification; this eager claim
+ * prevents the controlled roots from dropping the first pointer interaction
+ * while ownership moves between independent DropdownMenu roots.
+ */
+export declare function openMenuFromTriggerPointerDown(current: MenuId | null, menu: MenuId, event: Pick<PointerEvent, 'button' | 'ctrlKey'>): MenuId | null;

package/dist/package/browser/components/MenuBar/menubar-open-state.js

@@ -0,0 +1,11 @@
+/**
+ * A top-level trigger must claim the shared menubar state on pointer-down.
+ * Radix still owns the matching open/close notification; this eager claim
+ * prevents the controlled roots from dropping the first pointer interaction
+ * while ownership moves between independent DropdownMenu roots.
+ */
+export function openMenuFromTriggerPointerDown(current, menu, event) {
+    // Match Radix Trigger's own activation gate. In particular, Ctrl+click is a
+    // context-menu gesture on macOS and secondary buttons must not arm the bar.
+    return event.button === 0 && !event.ctrlKey ? menu : current;
+}

package/dist/package/browser/components/MenuBar/menubar-surface.d.ts

@@ -0,0 +1,30 @@
+import type { TFunction } from '../../i18n';
+export interface MenuTreeNode {
+    id: string;
+    label: string;
+    /** command = 可执行叶子;submenu = 可展开;placeholder = 未接线的禁用占位。 */
+    kind: 'command' | 'submenu' | 'placeholder';
+    /** 叶子背后的命令 id —— 让"某个 catalog action 有没有可见的门"变成可对账的问题
+     *  (ui_invoke 的返回体用它反查可见路径)。 */
+    commandId?: string;
+    keybinding?: string;
+    /** 派发给 commands.execute 的参数 —— 等价性对账用(同 commandId 且同 args 才算同一能力)。 */
+    args?: unknown;
+    /** 子菜单内容在展开时运行时求值(如最近游戏列表)——树里只标不展。 */
+    dynamic?: boolean;
+    /** 动态子项共用的 commandId / 子项 id 构成规则 —— 见 MenuItemDef 同名字段。 */
+    childCommandId?: string;
+    childIdFromArg?: string;
+    children?: MenuTreeNode[];
+}
+/** AI 路径的执行器**必须返回 promise**:run 会 await 它,命令失败 → throw →
+ *  ack ok=false。人路径的 fire-and-forget 版本(不卡下拉动画)不在此签名内。 */
+type Execute = (commandId: string, args?: unknown) => Promise<unknown>;
+export declare function projectMenuTree(t: TFunction): Record<string, MenuTreeNode[]>;
+/** MenuBar 挂载时注册 host.menubar。menusRevision 传注册表快照对象,引用一变
+ *  (注册表变更触发的重渲染)就重新投影 PUT。 */
+export declare function useMenubarSurface(menusRevision: unknown, t: TFunction, execute: Execute, 
+/** 当前语言。**必须**由调用方传:`t` 的标识是模块级恒定的(见 i18n/index.ts
+ *  的注释:列进依赖会造成无限重渲染),拿它当依赖 = 永不重投影。 */
+language?: string): void;
+export {};