@forgeax/interface 0.6.0 → 0.7.0

package/dist/package/node/components/MenuBar/menubar-surface.js

@@ -17,7 +17,7 @@
  */
 import { useEffect, useRef } from 'react';
 import { useSurface } from '../../lib/surface.js';
-import { snapshotAllMenus } from '../../lib/menu-registry.js';
+import { projectApplicationMenus } from '../../lib/application-menu-projection.js';
 import { warmRecentGames } from '../../lib/recent-games.js';
 const MENUBAR_SCHEMA = {
     type: 'object',
@@ -42,7 +42,7 @@ function projectItem(item, t) {
         .filter((node) => node !== null);
     return {
         id: item.id,
-        label: t(item.labelKey),
+        label: item.label,
         kind: isSub ? 'submenu' : item.commandId ? 'command' : 'placeholder',
         ...(item.commandId ? { commandId: item.commandId } : {}),
         ...(item.args !== undefined ? { args: item.args } : {}),
@@ -53,9 +53,9 @@ function projectItem(item, t) {
         ...(children && children.length ? { children } : {}),
     };
 }
-export function projectMenuTree(t) {
+export function projectMenuTree(t, registry) {
     const out = {};
-    for (const [menu, defs] of Object.entries(snapshotAllMenus())) {
+    for (const [menu, defs] of Object.entries(projectApplicationMenus(registry.snapshot()))) {
         out[menu] = defs
             .map((def) => projectItem(def, t))
             .filter((node) => node !== null);
@@ -64,7 +64,7 @@ export function projectMenuTree(t) {
 }
 /** 在注册表里解析一个可执行菜单项:先静态(含 children 递归),再对动态子菜单
  *  求值按 id 或 label 匹配(动态项的 labelKey 就是显示名,如游戏名)。 */
-function resolveInvokable(target, t) {
+function resolveInvokable(target, t, registry) {
     /** 与 projectItem 同一条谓词:`when()` 为假 = 该项在界面上根本不存在。
      *  2026-08-06 探测:此前只有投影过滤 when(),解析器完全不看 —— 一个在 snapshot
      *  和 DOM 里都不存在的项仍可被 invoke 执行。人点不到的东西 AI 不能点,否则
@@ -89,7 +89,7 @@ function resolveInvokable(target, t) {
             return null;
         }
         return kids.filter(visible).find((kid) => (target.itemId && kid.id === target.itemId)
-            || (target.label && (kid.labelKey === target.label || t(kid.labelKey) === target.label))) ?? null;
+            || (target.label && (kid.label === target.label || kid.label === target.label))) ?? null;
     };
     const walk = (defs) => {
         for (const def of defs) {
@@ -99,7 +99,7 @@ function resolveInvokable(target, t) {
                 continue;
             if (target.itemId && def.id === target.itemId)
                 return def;
-            if (target.label && !target.itemId && t(def.labelKey) === target.label)
+            if (target.label && !target.itemId && def.label === target.label)
                 return def;
             if (def.children) {
                 const hit = walk(def.children);
@@ -114,7 +114,7 @@ function resolveInvokable(target, t) {
         }
         return null;
     };
-    for (const defs of Object.values(snapshotAllMenus())) {
+    for (const defs of Object.values(projectApplicationMenus(registry.snapshot()))) {
         const hit = walk(defs);
         if (hit)
             return hit;
@@ -123,10 +123,13 @@ function resolveInvokable(target, t) {
 }
 /** MenuBar 挂载时注册 host.menubar。menusRevision 传注册表快照对象,引用一变
  *  (注册表变更触发的重渲染)就重新投影 PUT。 */
-export function useMenubarSurface(menusRevision, t, execute, 
+export function useMenubarSurface(registry, t, execute, 
 /** 当前语言。**必须**由调用方传:`t` 的标识是模块级恒定的(见 i18n/index.ts
  *  的注释:列进依赖会造成无限重渲染),拿它当依赖 = 永不重投影。 */
 language) {
+    const menusRevision = registry.snapshot();
+    const registryRef = useRef(registry);
+    registryRef.current = registry;
     const executeRef = useRef(execute);
     executeRef.current = execute;
     const tRef = useRef(t);
@@ -135,7 +138,7 @@ language) {
         id: 'host.menubar',
         layer: 'host',
         schema: MENUBAR_SCHEMA,
-        initialSnapshot: { menus: projectMenuTree(t) },
+        initialSnapshot: { menus: projectMenuTree(t, registry) },
         actions: {
             invoke: {
                 id: 'invoke',
@@ -149,14 +152,14 @@ language) {
                 },
                 run: async (raw) => {
                     const target = (raw ?? {});
-                    let def = resolveInvokable(target, tRef.current);
+                    let def = resolveInvokable(target, tRef.current, registryRef.current);
                     if (!def) {
                         // 冷缓存(2026-08-06 外审 B6②):动态子项(最近游戏)只在人点开 File 下拉
                         // 或 Tauri 原生菜单构建时被预热;web 模式下人没点过 File,dynamicChildren()
                         // 恒空,AI 按 id/label 解析动态项必然 not found —— 桌面能用、web 不能用。
                         // AI 先到时主动预热一次再重解析,与人"点开就看见"对齐。
                         await warmRecentGames();
-                        def = resolveInvokable(target, tRef.current);
+                        def = resolveInvokable(target, tRef.current, registryRef.current);
                     }
                     if (!def)
                         throw new Error(`menu item not found: ${JSON.stringify(target)}`);
@@ -195,7 +198,7 @@ language) {
         },
     });
     useEffect(() => {
-        surface.setSnapshot({ menus: projectMenuTree(tRef.current) });
+        surface.setSnapshot({ menus: projectMenuTree(tRef.current, registry) });
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [menusRevision, language]);
 }

package/dist/package/node/core/app-shell/host.js

@@ -13,9 +13,9 @@ import { derivePanelRenderers } from './derive-panel-renderers.js';
 import { DEFAULT_PANEL_RENDERERS } from '../../components/DockShell/panelRenderers.js';
 import { installPageNavigation } from '../page-navigation.js';
 import { createContextualKeybindings } from '../contextual-keybindings.js';
-import { createApplicationShortcutRegistry } from '@forgeax/app-shell/application';
+import { createApplicationShortcutRegistry, createApplicationMenuRegistry } from '@forgeax/app-shell/application';
 const BUILT_IN_CAPS = [
-    'commands', 'keybindings', 'shortcuts', 'bus', 'storage', 'panels', 'panelActions', 'panelControls', 'contextKeys', 'pages',
+    'commands', 'keybindings', 'shortcuts', 'menus', 'bus', 'storage', 'panels', 'panelActions', 'panelControls', 'contextKeys', 'pages',
     'activities', 'resourceEditors',
 ];
 export function createAppHost(deps = {}) {
@@ -25,6 +25,7 @@ export function createAppHost(deps = {}) {
         caps.add(c);
     const commands = createCommandsRegistry();
     const shortcuts = createApplicationShortcutRegistry();
+    const menus = createApplicationMenuRegistry();
     const keybindings = createContextualKeybindings(commands, {
         onCommandError(error, commandId) {
             log.error(`[app-shell] keybinding command "${commandId}" failed`, error);
@@ -64,7 +65,7 @@ export function createAppHost(deps = {}) {
     const extensionFields = {};
     let activeSetup = null;
     const base = {
-        commands, keybindings, shortcuts, bus, storage, contextKeys,
+        commands, keybindings, shortcuts, menus, bus, storage, contextKeys,
         get panels() { return panelsSnapshot(); },
         panelActions,
         panelControls,
@@ -184,6 +185,7 @@ export function createAppHost(deps = {}) {
             await pageSession.dispose();
             keybindings.dispose();
             shortcuts.dispose();
+            menus.dispose();
             bus.destroy();
         },
     };

package/dist/package/node/core/extensions/builtin-menus.js

@@ -14,7 +14,7 @@
 // Mirrors the style of `builtin-commands.ts`: a single `AppExtension` whose
 // `setup(ctx)` calls the registrar for every item, collects the cleanups, and
 // returns a reverse-order cleanup runner.
-import { registerMenuItem } from '../../lib/menu-registry.js';
+import { t } from '../../i18n/index.js';
 import { isDockPanelVisible } from '@forgeax/app-shell/dock';
 import { useShellStore } from '../../store.js';
 import { getRecentGames } from '../../lib/recent-games.js';
@@ -28,10 +28,30 @@ const isVisible = (id) => () => isDockPanelVisible(id);
 // mounted, `chatpanelCollapsed` flips its collapsed state — invert for
 // "checked = visible".
 const isChatpanelOpen = () => !useShellStore.getState().chatpanelCollapsed;
+// Product section order is explicit, independent of extension activation order.
+const SECTION_ORDER = {
+    brand: { app: 10, about: 20 }, file: { game: 10, file: 20, io: 30, recent: 10 },
+    edit: { history: 10, clipboard: 20, find: 30, version: 40 },
+    window: { panels: 10, layout: 20 }, build: { run: 10, export: 20 },
+    select: { basic: 10, byCond: 20, view: 30 },
+    help: { docs: 10, resources: 20, app: 30, about: 40 },
+};
+function localizeMenu(def) {
+    const { labelKey, children, dynamicChildren, ...metadata } = def;
+    const groupOrder = SECTION_ORDER[def.menu]?.[def.group];
+    if (groupOrder === undefined)
+        throw new Error(`Missing menu section order: ${def.menu}/${def.group}`);
+    return {
+        ...metadata, groupOrder,
+        get label() { return t(labelKey); },
+        ...(children ? { children: children.map(localizeMenu) } : {}),
+        ...(dynamicChildren ? { dynamicChildren: () => dynamicChildren().map(localizeMenu) } : {}),
+    };
+}
 export const builtinMenusExtension = {
     id: 'builtin-menus',
     version: '1.0.0',
-    setup() {
+    setup({ host }) {
         const cleanups = [];
         // Every item to register — sorted by menu / group / order so the shape
         // reads top-to-bottom the way it renders. The registrar itself re-sorts
@@ -240,7 +260,7 @@ export const builtinMenusExtension = {
                 commandId: 'app.open_url', args: { url: 'https://www.apache.org/licenses/LICENSE-2.0' } },
         ];
         for (const def of items)
-            cleanups.push(registerMenuItem(def));
+            cleanups.push(host.menus.register(localizeMenu(def)));
         return () => {
             // Reverse order so first-registered is torn down last — same pattern
             // as builtin-commands.ts; `.slice()` clones the array so a repeat unload

package/dist/package/node/lib/application-menu-projection.js

@@ -0,0 +1,53 @@
+/** Product menu locations; contributions and their lifetime belong to the host. */
+const MENU_IDS = ['brand', 'file', 'edit', 'window', 'build', 'select', 'help', 'publish'];
+export function projectApplicationMenus(items) {
+    const result = {
+        brand: [], file: [], edit: [], window: [], build: [], select: [], help: [], publish: [],
+    };
+    for (const menu of MENU_IDS)
+        result[menu] = items.filter(item => item.menu === menu);
+    return result;
+}
+function serializeItem(item) {
+    if (item.when && !item.when())
+        return null;
+    const children = item.children?.length ? item.children : item.dynamicChildren?.();
+    const result = {
+        id: item.id,
+        // Already resolved by the owner, including live locale getters. Never
+        // reinterpret a contributor's literal label as an Interface locale key.
+        label: item.label,
+        enabled: item.enabled ? item.enabled() : children?.length ? true : !!item.commandId,
+    };
+    if (item.keybinding) {
+        result.accelerator = item.keybinding.split('+')
+            .map(part => part === 'Ctrl' ? 'CmdOrCtrl' : part).join('+');
+    }
+    if (item.danger)
+        result.danger = true;
+    if (children?.length) {
+        const projected = children.map(serializeItem).filter((child) => child !== null);
+        if (projected.length)
+            result.children = projected;
+    }
+    return result;
+}
+/** Pure native projection of the same immutable snapshot used by the web menu. */
+export function serializeApplicationMenusForNative(items) {
+    const menus = projectApplicationMenus(items);
+    return MENU_IDS.map(menu => {
+        const projected = [];
+        let previousGroup = null;
+        for (const item of menus[menu]) {
+            const native = serializeItem(item);
+            // Retain the existing bridge's hidden-row group boundary semantics.
+            if (native) {
+                if (previousGroup !== null && previousGroup !== item.group)
+                    native.separatorBefore = true;
+                projected.push(native);
+            }
+            previousGroup = item.group;
+        }
+        return { menu, items: projected };
+    });
+}

package/dist/package/node/lib/menu-registry.js

@@ -1,197 +1,3 @@
-/** menu-registry —— 顶部菜单栏的单一真值源 (SSOT for the menu bar).
- *
- *  一张注册表服务两个消费者 (压缩公理:消掉「Web 菜单和原生菜单是不是同一套?」):
- *    1. Web 端渲染器 (React) —— 通过 `snapshotMenu(...)` / `snapshotAllMenus()` + `onMenuChange`
- *       走 useSyncExternalStore 拿到当前菜单结构;
- *    2. Tauri 原生菜单桥接 —— 通过 `serializeMenusForNative(t)` 拿到已翻译、去函数、
- *       JSON 可序列化的原生菜单契约,一次性 build native menu / 每次注册表变化时 rebuild.
- *
- *  设计与 action-registry.ts 对齐 (模块级 Map 页级单例 + change listener):
- *    - 菜单项按 `menu`(顶层大类) + `group`(段落分组) + `order`(段内序) 三级组织;
- *    - 同 id 重复注册 = **替换** (幂等,HMR / StrictMode 双挂载安全,cleanup
- *      走身份检查避免误删);
- *    - 键位串遵循全仓 canonical combo 格式 (见 lib/global-shortcuts.ts `prettyCombo`),
- *      例:'Ctrl+S' / 'Ctrl+Shift+Z' / 'Ctrl+,'。Web 显示走 prettyCombo,原生菜单走
- *      `serializeMenusForNative` 内部的 accelerator 转换 (Ctrl→CmdOrCtrl,保留 Shift/Alt)。
- *
- *  分隔符策略 (评审):**注册者不显式发 separator sentinel** —— 只填 `group`,
- *  渲染器按 `snapshotMenu` 返回结果中相邻两项的 `group` 差异自行绘制分隔线;
- *  原生序列化则在 `serializeMenusForNative` 中把段边界翻成 `separatorBefore=true`。
- *  这样避免维护「三种分隔来源」(注册者手插 + 渲染器 + 原生桥)—— 一处派生 (§2 Derive)。
- */
-// ─── 注册表本体 (模块级 Map,页级单例) ────────────────────────────────────────
-const items = new Map();
-const changeListeners = new Set();
-function notifyChange() {
-    for (const cb of changeListeners) {
-        try {
-            cb();
-        }
-        catch {
-            /* listener 异常不传染 */
-        }
-    }
-}
-/** 注册一项菜单 —— 同 id 重复注册 = 替换 (幂等,HMR / StrictMode 双挂载安全)。
- *  返回 cleanup 函数;cleanup 幂等 (身份检查:仅当当前项仍是本次注册的 def
- *  才 delete,避免 A 注册→A 注销 后误删掉 B 的 same-id 覆盖)。
- *
- *  设计变更 (T7 集成):初版为 throw-on-duplicate,与 action-registry 的
- *  「替换即幂等」策略不一致 —— React StrictMode 会双执行 App.tsx 的
- *  bootstrapAppHost useEffect,两次 setup 并发跑到同一个模块级 Map 时必抛
- *  「duplicate menu item id」把整个菜单栏打空。改为 last-writer-wins 后
- *  两次 setup 都能顺利完成,先释放的 cleanup 通过身份检查不会误删,
- *  与 action-registry 的语义对齐 (§SSOT / 兄弟注册表一致性)。 */
-export function registerMenuItem(def) {
-    items.set(def.id, def);
-    notifyChange();
-    return () => {
-        if (items.get(def.id) === def) {
-            items.delete(def.id);
-            notifyChange();
-        }
-    };
-}
-/** 注册表变更订阅 —— 供 useSyncExternalStore / native bridge rebuild 消费。 */
-export function onMenuChange(listener) {
-    changeListeners.add(listener);
-    return () => {
-        changeListeners.delete(listener);
-    };
-}
-// ─── 派生视图:排序与快照 (SSOT 是 items Map;所有视图都是纯 derive) ─────────
-/** 排序规则:先按 group 的**首次出现顺序**分段,段内按 order 升序 (相同 order 用
- *  插入顺序破平局,稳定排序)。JS `Array.prototype.sort` 从 ES2019 起要求稳定,
- *  Bun/V8/JSC 均已合规,直接用即可。 */
-function sortMenuItems(list) {
-    const groupFirstIndex = new Map();
-    list.forEach((item, idx) => {
-        if (!groupFirstIndex.has(item.group))
-            groupFirstIndex.set(item.group, idx);
-    });
-    const decorated = list.map((item, idx) => ({ item, idx }));
-    decorated.sort((a, b) => {
-        const ga = groupFirstIndex.get(a.item.group);
-        const gb = groupFirstIndex.get(b.item.group);
-        if (ga !== gb)
-            return ga - gb;
-        if (a.item.order !== b.item.order)
-            return a.item.order - b.item.order;
-        return a.idx - b.idx; // 稳定破平局:插入顺序
-    });
-    return decorated.map((d) => d.item);
-}
-/** 取单个菜单的排序后条目 —— 渲染器直接消费。 */
-export function snapshotMenu(menu) {
-    const list = [];
-    for (const def of items.values()) {
-        if (def.menu === menu)
-            list.push(def);
-    }
-    return sortMenuItems(list);
-}
-const ALL_MENUS = ['brand', 'file', 'edit', 'window', 'build', 'select', 'help', 'publish'];
-/** 取所有菜单的排序后条目,按 MenuId 组织。 */
-export function snapshotAllMenus() {
-    const out = {};
-    for (const m of ALL_MENUS)
-        out[m] = snapshotMenu(m);
-    return out;
-}
-/** 键位串 → 原生 accelerator 转换。canonical 形如 'Ctrl+Shift+S';原生形 'CmdOrCtrl+Shift+S'
- *  (Tauri/Electron 通用惯例:Ctrl 走 CmdOrCtrl,让 macOS 走 ⌘、其它平台走 Ctrl)。 */
-function toNativeAccelerator(combo) {
-    return combo
-        .split('+')
-        .map((seg) => (seg === 'Ctrl' ? 'CmdOrCtrl' : seg))
-        .join('+');
-}
-/** 递归序列化一项 (含 children) —— 返回值必须完全无函数,可直接 JSON.stringify。 */
-function serializeItem(def, translate) {
-    if (def.when && !def.when())
-        return null; // 隐藏项直接 drop
-    // Static `children` OR a `dynamicChildren` derivation — both serialize the
-    // same way. dynamicChildren is evaluated at serialize time (native menu is
-    // rebuilt on every registry change, so it re-derives with the cache current
-    // at that moment). Web + native thus share one derivation (§Derive / §SSOT).
-    const childDefs = def.children && def.children.length > 0
-        ? def.children
-        : def.dynamicChildren
-            ? def.dynamicChildren()
-            : null;
-    // enabled: explicit predicate wins; a submenu opener (has children) defaults
-    // enabled even without a command; else `!!commandId`. Mirrors the web
-    // renderer's resolveEnabled so both bars agree on which items are clickable.
-    const enabledResolved = def.enabled
-        ? def.enabled()
-        : (childDefs && childDefs.length > 0)
-            ? true
-            : !!def.commandId;
-    const out = {
-        id: def.id,
-        label: translate(def.labelKey),
-        enabled: enabledResolved,
-    };
-    if (def.keybinding)
-        out.accelerator = toNativeAccelerator(def.keybinding);
-    if (def.danger)
-        out.danger = true;
-    if (childDefs && childDefs.length > 0) {
-        const kids = [];
-        for (const child of childDefs) {
-            const ser = serializeItem(child, translate);
-            if (ser)
-                kids.push(ser);
-        }
-        if (kids.length > 0)
-            out.children = kids;
-    }
-    return out;
-}
-/** 序列化全部菜单为原生契约 —— T5 (Tauri 桥) 的唯一入口。契约要点:
- *    - `when === false` 的项被 drop;
- *    - `enabled` 缺省时默认 = `!!commandId` (无命令 = 禁用);
- *    - `labelKey` 走 `translate` 翻译,函数不出墙;
- *    - `keybinding` 转 native accelerator (Ctrl→CmdOrCtrl,Shift/Alt 保留);
- *    - 段边界翻成 `separatorBefore=true` (每个菜单首项除外);
- *    - 输出**完全 JSON 可序列化** (JSON.stringify 无损 roundtrip,无函数残留)。 */
-export function serializeMenusForNative(translate) {
-    const out = [];
-    for (const menu of ALL_MENUS) {
-        const sorted = snapshotMenu(menu);
-        const serialized = [];
-        let prevGroup = null;
-        for (const def of sorted) {
-            const ser = serializeItem(def, translate);
-            if (!ser) {
-                // when=false 的项被 drop;下一项若换 group 依然按已见 group 判段边界。
-                prevGroup = def.group;
-                continue;
-            }
-            if (prevGroup !== null && def.group !== prevGroup)
-                ser.separatorBefore = true;
-            serialized.push(ser);
-            prevGroup = def.group;
-        }
-        out.push({ menu, items: serialized });
-    }
-    return out;
-}
-// ─── Vite HMR: preserve registrations across hot module swap ───────────────
-if (import.meta.hot) {
-    import.meta.hot.dispose((data) => {
-        data.menuItems = [...items.entries()];
-    });
-    const saved = import.meta.hot.data.menuItems;
-    if (saved) {
-        for (const [id, def] of saved)
-            items.set(id, def);
-        notifyChange();
-    }
-}
-// ─── 测试辅助 (生产代码不要调) ─────────────────────────────────────────────
-/** 清空注册表 —— 仅供单测 beforeEach 使用。 */
-export function __resetMenuRegistryForTest() {
-    items.clear();
-    changeListeners.clear();
-}
+// Interface-owned built-in menu descriptors and native wire types.
+// Runtime registration, ordering, subscriptions and disposal belong to host.menus.
+export {};

package/dist/package/node/lib/menu-registry.test-utils.js

@@ -0,0 +1,28 @@
+// Test data adapter only. Production readers receive their host registry.
+import { createApplicationMenuRegistry } from '@forgeax/app-shell/application';
+import { projectApplicationMenus, serializeApplicationMenusForNative } from './application-menu-projection.js';
+let menus = createApplicationMenuRegistry();
+let translate = (key) => key;
+export const getTestMenus = () => menus;
+export const setTestMenuTranslator = (next) => { translate = next; };
+function contribution(def) {
+    return {
+        ...def, groupOrder: 0,
+        get label() { return translate(def.labelKey); },
+        children: def.children?.map(contribution),
+        dynamicChildren: def.dynamicChildren ? () => def.dynamicChildren().map(contribution) : undefined,
+    };
+}
+export const registerMenuItem = (def) => menus.register(contribution(def));
+export const onMenuChange = (listener) => menus.subscribe(listener);
+export const snapshotMenu = (menu) => menus.snapshot(menu);
+export const snapshotAllMenus = () => projectApplicationMenus(menus.snapshot());
+export function serializeMenusForNative(t) {
+    translate = t;
+    return serializeApplicationMenusForNative(menus.snapshot());
+}
+export function __resetMenuRegistryForTest() {
+    menus.dispose();
+    menus = createApplicationMenuRegistry();
+    translate = key => key;
+}