@forgeax/interface 0.4.1

package/dist/package/node/components/MainArea/StandaloneExtensionIframe.js

@@ -0,0 +1,155 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Phase A3 — iframe-mounted page plugin.
+ *
+ * Renders the plugin's standalone dev server inside an iframe and wires it to
+ * the host RPC channel via `createExtensionPort` from `@forgeax/extension-platform/transport`. This
+ * is the new path that will eventually replace the import-tree-based
+ * `MAINAREA_PLUGIN_LOADERS` map. Today (A3) it's gated behind the
+ * `VITE_FX_USE_IFRAME=true` env flag and only kicks in when a plugin
+ * manifest declares `entry.standalone`.
+ *
+ * What we wire on the host side (interface):
+ *   - onChat       — plugin → composer text  (TODO B-phase: dispatch into store)
+ *   - onToolCall   — plugin → tool registry  (TODO B-phase: real registry)
+ *   - surface.subscribe — observe surface.expose for AgentsPanel
+ *   - setTheme    — pushed when light/dark or locale changes
+ */
+import { useCallback, useMemo } from 'react';
+import { getLocale, useTranslation } from '../../i18n/index.js';
+import { useShellStore } from '../../store.js';
+import { openExtensionPage } from '../../core/page-navigation.js';
+import { getSessionClient } from '../../store-parts/session-client.js';
+import { ExtensionIframeHost } from '../ExtensionHost/ExtensionIframeHost.js';
+import { usePanelRenderers } from '../DockShell/panelRenderers.js';
+export function buildIframeSrc(plugin, pane, slug) {
+    const sa = plugin.entry?.standalone;
+    if (!plugin.frontendUrl && !sa && !plugin.entry?.frontend)
+        return null;
+    // Explicit host-validated dev URLs win. Existing embedded/proxy/port modes
+    // remain for installed extensions and never infer a Toolkit registration.
+    // Four address modes:
+    //   1. embeddedAlso=true — plugin ships a built dist served by the host at
+    //      /extensions/<id>/. Prefer this when set: the studio doesn't launch the
+    //      plugin's own dev server, and declared `port` may collide with other
+    //      services (e.g. extension-character's 15173 collides with the engine).
+    //   2. anydev/cloud proxy mode — keep the browser on Studio's HTTPS origin and
+    //      let Vite proxy to the plugin's plain-HTTP dev server inside the container.
+    //   3. plugin declares `port` — use http://<host>:<port>/<readyProbe?>
+    //   4. plugin only declares `start` — fall back to /extensions/<id>/.
+    const shortId = plugin.id.replace(/^@[^/]+\//, '');
+    const encodedShortId = encodeURIComponent(shortId);
+    const embeddedSrc = `/extensions/${encodedShortId}/`;
+    let base;
+    if (plugin.frontendUrl)
+        base = plugin.frontendUrl;
+    else if (plugin.entry?.frontend || sa?.embeddedAlso === true)
+        base = embeddedSrc;
+    else if (import.meta.env.VITE_FORGEAX_STANDALONE_PROXY === '1') {
+        const probe = sa?.readyProbe ?? '/';
+        const path = probe.startsWith('/') ? probe : `/${probe}`;
+        base = `/__fx-plugin/${encodedShortId}${path}`;
+    }
+    else if (typeof sa?.port === 'number') {
+        const probe = sa.readyProbe ?? '/';
+        const path = probe.startsWith('/') ? probe : `/${probe}`;
+        // Match the parent page's protocol. When the Studio UI is served over HTTPS
+        // (FORGEAX_INTERFACE_HTTPS=1, e.g. remote-IP access) an `http://` iframe is
+        // blocked as mixed content. The plugin dev server must then also serve HTTPS
+        // (run.ts passes the studio .tls cert to its vite). Falls back to http://
+        // transparently when the parent is http.
+        base = `${window.location.protocol}//${window.location.hostname}:${sa.port}${path}`;
+    }
+    else
+        base = embeddedSrc;
+    // 多游戏：把当前 game slug 喂进 iframe URL，让 extension-scene 等"per-game data"
+    // 类型的插件能在自己空间里读出。其它插件忽略此参数即可。
+    const params = [];
+    if (pane)
+        params.push(`pane=${encodeURIComponent(pane)}`);
+    if (slug)
+        params.push(`slug=${encodeURIComponent(slug)}`);
+    params.push(`locale=${encodeURIComponent(getLocale())}`);
+    if (params.length === 0)
+        return base;
+    return base + (base.includes('?') ? '&' : '?') + params.join('&');
+}
+/** localStorage key the host writes the cross-page handoff payload to.
+ *  Same-origin so the target plugin iframe (e.g. extension-anim) can read it on boot
+ *  + via the 'storage' event. Mirrored constant lives in extension-anim's bridge. */
+const ANIM_HANDOFF_KEY = 'forgeax:anim-handoff';
+/** Resolve the target plugin's page tab id + flip the store so MainArea
+ *  takes over with the target plugin. Writes the handoff payload (charId/role/
+ *  slug) to localStorage first so the target iframe can pick it up. */
+function doNavigate(targetPluginId, payload) {
+    try {
+        if (payload && Object.keys(payload).length > 0) {
+            window.localStorage.setItem(ANIM_HANDOFF_KEY, JSON.stringify({ ...payload, targetPluginId, ts: Date.now() }));
+        }
+    }
+    catch {
+        /* localStorage unavailable (private mode) — target falls back to selector */
+    }
+    void openExtensionPage(targetPluginId);
+}
+export function StandaloneExtensionIframe({ plugin, pane, active = true, reloadNonce = 0 }) {
+    const { t } = useTranslation();
+    const { editor } = usePanelRenderers();
+    // STABLE cache key. Was `${version}-${Date.now()}` which defeated keep-alive:
+    // any iframe remount (re-parent / reconcile) recomputed Date.now() → new URL →
+    // a full cold reload that tore down the WebGPU ctx + WS + scroll on every
+    // panel/game switch. Now keyed only on identity (id + version) + an explicit
+    // reloadNonce, so the URL stays identical across switches and the browser
+    // reuses the live iframe. A deliberate reload bumps reloadNonce.
+    const iframeCacheKey = useMemo(() => `${plugin.version ?? 'dev'}-${reloadNonce}`, [plugin.id, plugin.version, reloadNonce]);
+    const effectiveSlug = useShellStore((s) => s.activeGameSlug);
+    const slugReady = useShellStore((s) => s.activeGameResolved);
+    const rawSrc = slugReady ? buildIframeSrc(plugin, pane, effectiveSlug) : null;
+    const src = rawSrc ? rawSrc + (rawSrc.includes('?') ? '&' : '?') + `fxv=${encodeURIComponent(iframeCacheKey)}` : null;
+    const handleNavigate = useCallback((targetPluginId, payload) => {
+        doNavigate(targetPluginId, payload);
+    }, []);
+    const handleChatPost = useCallback((e) => {
+        if (!e.text || !e.text.trim())
+            return;
+        if (e.attachments && e.attachments.length > 0 && import.meta.env.DEV) {
+            // eslint-disable-next-line no-console
+            console.warn('[plugin chat.post] attachments dropped (not yet supported):', plugin.id, e.attachments);
+        }
+        const st = useShellStore.getState();
+        const sid = st.activeSid;
+        if (!sid)
+            return;
+        const to = st.tabs.find((tb) => tb.sid === sid)?.agentId ?? undefined;
+        void getSessionClient().emitForgeaXMessage(sid, e.text, to ? { to } : {}).catch((err) => {
+            if (import.meta.env.DEV) {
+                // eslint-disable-next-line no-console
+                console.warn('[plugin chat.post] emit failed:', plugin.id, err);
+            }
+        });
+    }, [plugin.id]);
+    const handleToolCall = useCallback(async (call) => {
+        try {
+            const r = await fetch('/api/tools/call', {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({
+                    toolId: call.toolId,
+                    args: call.args ?? {},
+                    caller: { kind: 'extension', extensionId: plugin.id, instanceId: `standalone:${plugin.id}` },
+                }),
+            });
+            const body = (await r.json());
+            return body.ok
+                ? { ok: true, result: body.result }
+                : { ok: false, error: body.error ?? 'tool call failed' };
+        }
+        catch (e) {
+            return { ok: false, error: e.message };
+        }
+    }, [plugin.id]);
+    if (!src) {
+        return (_jsxs("div", { style: { padding: 20, color: '#888' }, children: [t('standaloneExtension.noEntryPrefix'), " ", _jsx("code", { children: plugin.id }), ' ', t('standaloneExtension.noEntryMiddle'), " ", _jsx("code", { children: "entry.standalone" }), ' ', t('standaloneExtension.noEntrySuffix')] }));
+    }
+    return (_jsx(ExtensionIframeHost, { extensionId: plugin.id, src: src, pane: pane, active: active, onNavigate: handleNavigate, onChatPost: handleChatPost, onEditorAssetImport: editor?.importAssetSource, onToolCall: handleToolCall, allowedOrigin: plugin.allowedOrigin, loadErrorText: (error) => t('standaloneExtension.iframeLoadFailed', { error }) }));
+}

package/dist/package/node/components/MainArea/SurfacePanels.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef } from 'react';
+import { SurfaceRegion } from '@forgeax/app-shell/react';
+import { setAnchor } from '../../lib/surfaceAnchors.js';
+// SurfaceAnchor — empty flex-fill placeholder that registers its element with the
+// anchor registry on mount and clears it on unmount. The keep-alive layer reads
+// this element's bounding rect to position the live (kept-alive) surface over it.
+function SurfaceAnchor({ kind }) {
+    const ref = useRef(null);
+    useEffect(() => {
+        setAnchor(kind, ref.current);
+        return () => setAnchor(kind, null);
+    }, [kind]);
+    return _jsx("div", { ref: ref, className: "surface-anchor", "data-surface-anchor": kind });
+}
+// ViewportPanel — combined edit+preview surface, renders the editor viewport anchor.
+// The keep-alive layer manages the actual surface rendering.
+export function ViewportPanel() {
+    return (_jsx(SurfaceRegion, { children: _jsx(SurfaceAnchor, { kind: "edit" }) }));
+}
+// Backward-compat aliases kept for existing consumers during migration.
+// These are thin wrappers around ViewportPanel; the old 'preview'/'edit' modes
+// should no longer be used (they map to 'viewport' via AppMode migration).
+export { ViewportPanel as EditPanel };
+export function PreviewPanel() {
+    return (_jsx(SurfaceRegion, { children: _jsx(SurfaceAnchor, { kind: "play" }) }));
+}

package/dist/package/node/components/MainArea/TelemetryViewer.js

@@ -0,0 +1,116 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo, useState } from 'react';
+import { useShellStore } from '../../store.js';
+
+// TelemetryViewer — a dock panel for the observability (trace + log) feed.
+//
+// One store slice (`telemetry`) carries BOTH node-produced records (WS
+// `{type:'telemetry'}`) and iframe-produced ones (postMessage
+// `{type:'VAG_TELEMETRY'}`); see store.ts pushTelemetry. This viewer splits by
+// `kind`:
+//   - spans → a per-trace waterfall (nested by parentSpanId, bars positioned by
+//     startTs and sized by duration; provisional spans render as「ongoing」).
+//   - logs  → a newest-first stream with a level filter.
+// 见 .claude/docs/架构设计/forgeax-os/可观测性-trace-log-v3-B档-并行执行计划-2026-06-24.md §C Track UI。
+const LOG_LEVELS = ['debug', 'info', 'warn', 'error'];
+/** Group spans by traceId and order each trace's spans into a depth-tagged DFS
+ *  list (root spans first, children nested under their parentSpanId). Spans with
+ *  an unknown / absent parent are treated as roots so nothing is dropped. */
+export function buildTraces(spans) {
+    // Latest record per spanId wins (onEnd `final` overrides the onStart
+    // `provisional`, both share the same spanId).
+    const bySpanId = new Map();
+    for (const s of spans)
+        bySpanId.set(s.spanId, s);
+    const latest = [...bySpanId.values()];
+    const byTrace = new Map();
+    for (const s of latest) {
+        const arr = byTrace.get(s.traceId) ?? [];
+        arr.push(s);
+        byTrace.set(s.traceId, arr);
+    }
+    const trees = [];
+    for (const [traceId, list] of byTrace) {
+        const ids = new Set(list.map((s) => s.spanId));
+        const children = new Map();
+        const roots = [];
+        for (const s of list) {
+            if (s.parentSpanId && ids.has(s.parentSpanId)) {
+                const arr = children.get(s.parentSpanId) ?? [];
+                arr.push(s);
+                children.set(s.parentSpanId, arr);
+            }
+            else {
+                roots.push(s);
+            }
+        }
+        const sortByStart = (a, b) => a.startTs - b.startTs;
+        roots.sort(sortByStart);
+        for (const arr of children.values())
+            arr.sort(sortByStart);
+        const rows = [];
+        const walk = (s, depth) => {
+            rows.push({ span: s, depth });
+            for (const c of children.get(s.spanId) ?? [])
+                walk(c, depth + 1);
+        };
+        for (const r of roots)
+            walk(r, 0);
+        let t0 = Infinity;
+        let t1 = -Infinity;
+        const now = Date.now();
+        for (const s of list) {
+            t0 = Math.min(t0, s.startTs);
+            t1 = Math.max(t1, s.endTs ?? now); // provisional → extend to now
+        }
+        trees.push({ traceId, t0, t1, rows });
+    }
+    // Newest trace first (by its earliest span).
+    trees.sort((a, b) => b.t0 - a.t0);
+    return trees;
+}
+export function fmtDur(ms) {
+    if (ms < 1)
+        return '<1ms';
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    return `${(ms / 1000).toFixed(2)}s`;
+}
+export function SpanBar({ span, depth, t0, t1 }) {
+    const span0 = span.startTs;
+    const span1 = span.endTs ?? Date.now();
+    const total = Math.max(1, t1 - t0);
+    const leftPct = ((span0 - t0) / total) * 100;
+    const widthPct = Math.max(0.5, ((span1 - span0) / total) * 100);
+    const dur = (span.endTs ?? span1) - span0;
+    const isErr = span.status?.code === 'error';
+    const cls = ['tv-span-bar', isErr ? 'tv-span-bar--error' : '', span.provisional || span.endTs == null ? 'tv-span-bar--ongoing' : '']
+        .filter(Boolean)
+        .join(' ');
+    const who = span.agentId ? `${span.agentId}` : span.sid ?? '';
+    return (_jsxs("div", { className: "tv-span-row", children: [_jsxs("div", { className: "tv-span-label", style: { paddingLeft: depth * 12 }, title: `${span.name} · ${span.spanId}`, children: [_jsx("span", { className: "tv-span-name", children: span.name }), _jsxs("span", { className: "tv-span-meta", children: [fmtDur(dur), span.endTs == null ? '…' : '', who ? ` · ${who}` : ''] })] }), _jsx("div", { className: "tv-span-track", children: _jsx("div", { className: cls, style: { left: `${leftPct}%`, width: `${widthPct}%` } }) })] }));
+}
+/** 日志按 level 过滤(`'all'` = 不过滤)+ 按 ts 新→旧排序。纯函数,可独立单测。 */
+export function filterAndSortLogs(logs, level) {
+    const filtered = level === 'all' ? logs : logs.filter((l) => l.level === level);
+    return [...filtered].sort((a, b) => b.ts - a.ts);
+}
+/** store-connected 容器:读 telemetry slice + clear,委托给纯展示组件 {@link TelemetryView}。 */
+export function TelemetryViewer() {
+    const telemetry = useShellStore((s) => s.telemetry);
+    const clearTelemetry = useShellStore((s) => s.clearTelemetry);
+    return _jsx(TelemetryView, { telemetry: telemetry, onClear: clearTelemetry });
+}
+/** 纯展示组件(prop 驱动,不读 store)—— 便于 renderToStaticMarkup 注入 seeded 数据单测。 */
+export function TelemetryView({ telemetry, onClear }) {
+    const [levelFilter, setLevelFilter] = useState('all');
+    const spans = useMemo(() => telemetry.filter((r) => r.kind === 'span'), [telemetry]);
+    const logs = useMemo(() => telemetry.filter((r) => r.kind === 'log'), [telemetry]);
+    const traces = useMemo(() => buildTraces(spans), [spans]);
+    const visibleLogs = useMemo(() => filterAndSortLogs(logs, levelFilter), [logs, levelFilter]);
+    return (_jsxs("div", { className: "tv-panel", children: [_jsxs("div", { className: "tv-bar", children: [_jsxs("span", { className: "tv-title", children: ["Telemetry", telemetry.length ? ` · ${spans.length} span / ${logs.length} log` : ''] }), telemetry.length > 0 && (_jsx("button", { type: "button", className: "tv-clear", onClick: () => onClear(), title: "clear telemetry", children: "clear" }))] }), _jsxs("div", { className: "tv-section tv-traces thin-scrollbar", children: [traces.length === 0 && _jsx("div", { className: "tv-empty", children: "no spans yet" }), traces.map((tr) => (_jsxs("div", { className: "tv-trace", children: [_jsxs("div", { className: "tv-trace-head", title: tr.traceId, children: [_jsx("span", { className: "tv-trace-id", children: tr.traceId.slice(0, 12) }), _jsx("span", { className: "tv-trace-dur", children: fmtDur(tr.t1 - tr.t0) }), _jsxs("span", { className: "tv-trace-count", children: [tr.rows.length, " spans"] })] }), tr.rows.map(({ span, depth }) => (_jsx(SpanBar, { span: span, depth: depth, t0: tr.t0, t1: tr.t1 }, span.spanId)))] }, tr.traceId)))] }), _jsxs("div", { className: "tv-logbar", children: [_jsx("span", { className: "tv-logbar-title", children: "Logs" }), _jsxs("div", { className: "tv-filters", children: [_jsx("button", { type: "button", className: `tv-filter ${levelFilter === 'all' ? 'tv-filter--on' : ''}`, onClick: () => setLevelFilter('all'), children: "all" }), LOG_LEVELS.map((lv) => (_jsx("button", { type: "button", className: `tv-filter tv-filter--${lv} ${levelFilter === lv ? 'tv-filter--on' : ''}`, onClick: () => setLevelFilter(lv), children: lv }, lv)))] })] }), _jsxs("div", { className: "tv-section tv-logs thin-scrollbar", children: [visibleLogs.length === 0 && _jsx("div", { className: "tv-empty", children: "no logs" }), visibleLogs.map((l, i) => {
+                        const d = new Date(l.ts);
+                        const stamp = `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}:${String(d.getSeconds()).padStart(2, '0')}`;
+                        return (_jsxs("div", { className: `tv-log-row tv-log--${l.level}`, children: [_jsx("span", { className: "tv-log-time", children: stamp }), _jsx("span", { className: `tv-log-level tv-log-level--${l.level}`, children: l.level }), _jsx("span", { className: "tv-log-msg", children: l.msg }), l.traceId && _jsx("span", { className: "tv-log-trace", title: l.traceId, children: l.traceId.slice(0, 8) })] }, `${l.ts}-${i}`));
+                    })] })] }));
+}

package/dist/package/node/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/index.js';
+import { useHost } from '../../core/app-shell/index.js';
+import { useBrand } from '../../brand/BrandProvider.js';
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent, } from '../ui/dropdown-menu.js';
+import { onMenuChange, snapshotAllMenus, } from '../../lib/menu-registry.js';
+import { prettyCombo } from '../../lib/global-shortcuts.js';
+import { useMenubarSurface } from './menubar-surface.js';
+import { openMenuFromTriggerPointerDown } from './menubar-open-state.js';
+import { isTauri } from '../../lib/platform/runtime.js';
+import { captureFocusedTextEditTarget } from '../../lib/text-edit-actions.js';
+import { getRecentGamesRevision, subscribeRecentGames, warmRecentGames, } from '../../lib/recent-games.js';
+import { repairBuiltinMenusIfEmpty } from '../../lib/repair-builtin-menus.js';
+
+// 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/node/components/MenuBar/index.js

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

package/dist/package/node/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;
+}