@forgeax/interface 0.4.1

package/dist/package/browser/lib/model-prefs.js

@@ -0,0 +1,53 @@
+// Per-provider "last hand-picked model" memory.
+//
+// Two distinct gestures land on different defaults, and conflating them was the
+// reported bug:
+//   • Switching PROVIDER is a deliberate "give me this provider's default" — the
+//     active-session reset policy belongs to Chat. We do NOT record that here.
+//   • Creating a NEW SESSION should resume "where I left off" for the current
+//     provider — the model the user last HAND-PICKED in the composer. Only the
+//     manual pick writes here; new sessions read it to seed their agent model.
+//
+// Keyed by catalog-provider id: a CLI driver id (claude-code / codex / …) or
+// 'forgeax' for the native gateway path (catalogProviderId === null).
+import { STORAGE_KEYS } from './storageKeys';
+function storageKey() {
+    return STORAGE_KEYS.lastModelByProvider;
+}
+function providerKey(catalogProviderId) {
+    return catalogProviderId && catalogProviderId !== 'forgeax' ? catalogProviderId : 'forgeax';
+}
+function readMap() {
+    try {
+        const raw = localStorage.getItem(storageKey());
+        if (!raw)
+            return {};
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+/** The model the user last hand-picked for this provider, or null if none. */
+export function getLastModel(catalogProviderId) {
+    const v = readMap()[providerKey(catalogProviderId)];
+    return typeof v === 'string' && v.length > 0 ? v : null;
+}
+/** Record a HAND-PICKED model for this provider (called from the composer's
+ *  model picker onChange — never from a provider-switch reset). */
+export function recordLastModel(catalogProviderId, modelId) {
+    if (!modelId)
+        return;
+    try {
+        const map = readMap();
+        map[providerKey(catalogProviderId)] = modelId;
+        localStorage.setItem(storageKey(), JSON.stringify(map));
+    }
+    catch {
+        /* ignore (private mode / SSR) */
+    }
+}

package/dist/package/browser/lib/model-route/index.d.ts

@@ -0,0 +1,81 @@
+import { type ModelCatalogEntry } from '../model-config';
+/** Closed union of model sources the UI can present + switch between. */
+export type ModelSource = 
+/** BYO OpenAI-compatible key — native path, FORGEAX_MODEL=<vendor id>. */
+{
+    kind: 'api-key';
+    model: string;
+}
+/** Local CLI driver — providerOverride=<id>. */
+ | {
+    kind: 'cli';
+    providerId: string;
+};
+/**
+ * The UI-facing "active source" identifier: 'api-key' | <cli-id> | null
+ * (nothing set).
+ */
+export type ActiveSourceId = 'api-key' | string | null;
+/**
+ * Derive the active source id purely from the two runtime inputs. Kept a pure
+ * function so it can be unit-tested and reused by both the Providers panel and
+ * the onboarding readiness gate.
+ */
+export declare function deriveActiveSource(providerOverride: string | null, forgeaxModel: string | null): ActiveSourceId;
+/**
+ * Switch the active model source. Writes the two underlying pieces of state
+ * atomically-enough (env then override) so the derived active source lands on
+ * the requested value. Returns once persisted.
+ *
+ *  - api-key → providerOverride=null + FORGEAX_MODEL=<vendor id> (env keys are
+ *              saved separately via the Providers EnvFields)
+ *  - cli     → providerOverride=<id> (FORGEAX_MODEL untouched — the driver owns
+ *              its own model selection)
+ */
+export declare function applyModelRoute(source: ModelSource): Promise<void>;
+/** The catalog provider id currently in effect, derived from providerOverride. */
+export declare function currentCatalogProvider(providerOverride: string | null): string | null;
+/** Preserve the last explicit user pick when it still belongs to this catalog;
+ * otherwise use the provider's first visible/default entry. */
+export declare function preferredCatalogModel(catalog: readonly ModelCatalogEntry[], remembered: string | null): string | undefined;
+/** Model seeding policy for a newly scaffolded session. Native sessions only
+ * override their scaffold default when the user has an applicable remembered
+ * pick; CLI sessions must always land on a model from that driver's catalog. */
+export declare function initialSessionCatalogModel(catalog: readonly ModelCatalogEntry[], catalogProviderId: string | null, remembered: string | null): string | undefined;
+/**
+ * Reset EVERY open session's agent model to a catalog's default.
+ *
+ * `providerOverride` is GLOBAL (one value for the whole app), so switching it
+ * re-routes ALL sessions through the new provider — but each session's
+ * agent.json still pins the OLD provider's model id, which may not exist in the
+ * new provider's catalog. The product requirement is therefore: switching the
+ * provider in Settings resets the current model of ALL active sessions to the
+ * new provider's default (not just the focused one). We compute the default
+ * once (provider-scoped) and write it into each open tab's agent.json. Returns
+ * the model set + how many sessions were updated, or null when nothing to do.
+ */
+export declare function resetOpenSessionsModelToProviderDefault(catalogProviderId: string | null): Promise<{
+    selected: string;
+    count: number;
+} | null>;
+/**
+ * On SESSION SWITCH: conform the switched-to session's model to the currently
+ * ACTIVE provider (Settings › Providers is the single global provider setting;
+ * the in-chat switcher is hidden). "Does this session's provider match the
+ * active provider?" is answered by CATALOG MEMBERSHIP — a session whose
+ * agent.json model isn't in the active provider's catalog was last touched
+ * under a DIFFERENT provider (e.g. switching game loads that game's disk
+ * sessions, which the last provider-switch reset never reached).
+ *
+ *   • mismatch → snap the session's model to this provider's last HAND-PICKED
+ *     model (model-prefs), else its catalog default (first non-hidden);
+ *   • match (model already in the active catalog) → leave it untouched
+ *     ("同 provider 就不管").
+ *
+ * Best-effort + returns null on no-op: an empty catalog, a missing model, or
+ * any IO failure must never block the session switch. Returns the model set on
+ * a mismatch so the caller can repaint immediately if it wants.
+ */
+export declare function reconcileSessionModelToActiveProvider(sid: string, agentPath: string): Promise<{
+    selected: string;
+} | null>;

package/dist/package/browser/lib/model-route/index.js

@@ -0,0 +1,175 @@
+// ActiveModelRoute — the single source of truth for "which model source is the
+// chat actually using right now", and the one place that mutation flows through.
+//
+// Design §12 (adopted revisions) calls for a closed-union ActiveModelRoute from
+// which `providerOverride` is DERIVED rather than a second hand-maintained
+// field. In this codebase the runtime routing is already decided by two pieces
+// of existing state — we do NOT add a third:
+//
+//   1. store.providerOverride (per-session): null → native forgeax path
+//      (POST /api/sessions/:sid/messages); non-null → a CLI driver via
+//      /api/cli/chat (claude-code / codex / cursor-agent / codebuddy).
+//   2. .env FORGEAX_MODEL: which model the native path resolves (auto-resolver
+//      routes by id prefix — claude-* → Anthropic, gpt-* → OpenAI, …).
+//
+// So the "active source" the Providers panel + onboarding show is a pure
+// DERIVATION over (providerOverride, FORGEAX_MODEL), and switching source is a
+// single `applyModelRoute` that writes both consistently. No ghost field.
+import { useShellStore } from '../../store';
+import { getAgentModel, listModels, setAgentModels } from '../model-config';
+import { getLastModel } from '../model-prefs';
+const RE_OPENAI = /^(gpt-|o[1-9]|codex-)/i;
+/**
+ * Derive the active source id purely from the two runtime inputs. Kept a pure
+ * function so it can be unit-tested and reused by both the Providers panel and
+ * the onboarding readiness gate.
+ */
+export function deriveActiveSource(providerOverride, forgeaxModel) {
+    // A CLI override always wins — the chat is routed through /api/cli/chat.
+    if (providerOverride && providerOverride !== 'forgeax') {
+        return providerOverride;
+    }
+    // Native path: the model id tells us the source.
+    const m = (forgeaxModel ?? '').trim();
+    if (m && RE_OPENAI.test(m))
+        return 'api-key';
+    // Any native model (claude-*/gemini-*/proxy) — still the "api-key" bucket from
+    // the Providers UI's perspective (BYO credential).
+    if (m)
+        return 'api-key';
+    return null;
+}
+async function patchEnv(patch) {
+    const r = await fetch('/api/settings/env', {
+        method: 'PUT',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(patch),
+    });
+    const j = (await r.json().catch(() => null));
+    if (!r.ok || !j?.ok) {
+        throw new Error(j?.error ?? `HTTP ${r.status}`);
+    }
+}
+/**
+ * Switch the active model source. Writes the two underlying pieces of state
+ * atomically-enough (env then override) so the derived active source lands on
+ * the requested value. Returns once persisted.
+ *
+ *  - api-key → providerOverride=null + FORGEAX_MODEL=<vendor id> (env keys are
+ *              saved separately via the Providers EnvFields)
+ *  - cli     → providerOverride=<id> (FORGEAX_MODEL untouched — the driver owns
+ *              its own model selection)
+ */
+export async function applyModelRoute(source) {
+    const setProviderOverride = useShellStore.getState().setProviderOverride;
+    switch (source.kind) {
+        case 'api-key':
+            await patchEnv({ FORGEAX_MODEL: source.model });
+            setProviderOverride(null);
+            return;
+        case 'cli':
+            setProviderOverride(source.providerId);
+            return;
+    }
+}
+/** The catalog provider id currently in effect, derived from providerOverride. */
+export function currentCatalogProvider(providerOverride) {
+    return providerOverride && providerOverride !== 'forgeax' ? providerOverride : null;
+}
+/** Preserve the last explicit user pick when it still belongs to this catalog;
+ * otherwise use the provider's first visible/default entry. */
+export function preferredCatalogModel(catalog, remembered) {
+    if (remembered && catalog.some((model) => model.id === remembered && !model.hidden)) {
+        return remembered;
+    }
+    return catalog.find((model) => !model.hidden)?.id ?? catalog[0]?.id;
+}
+/** Model seeding policy for a newly scaffolded session. Native sessions only
+ * override their scaffold default when the user has an applicable remembered
+ * pick; CLI sessions must always land on a model from that driver's catalog. */
+export function initialSessionCatalogModel(catalog, catalogProviderId, remembered) {
+    const rememberedEntry = remembered
+        ? catalog.find((model) => model.id === remembered && !model.hidden)
+        : undefined;
+    if (rememberedEntry)
+        return rememberedEntry.id;
+    return catalogProviderId ? preferredCatalogModel(catalog, null) : undefined;
+}
+/**
+ * Reset EVERY open session's agent model to a catalog's default.
+ *
+ * `providerOverride` is GLOBAL (one value for the whole app), so switching it
+ * re-routes ALL sessions through the new provider — but each session's
+ * agent.json still pins the OLD provider's model id, which may not exist in the
+ * new provider's catalog. The product requirement is therefore: switching the
+ * provider in Settings resets the current model of ALL active sessions to the
+ * new provider's default (not just the focused one). We compute the default
+ * once (provider-scoped) and write it into each open tab's agent.json. Returns
+ * the model set + how many sessions were updated, or null when nothing to do.
+ */
+export async function resetOpenSessionsModelToProviderDefault(catalogProviderId) {
+    const st = useShellStore.getState();
+    const targets = st.tabs
+        .map((t) => ({ sid: t.sid, agentPath: t.agentId }))
+        .filter((x) => !!x.sid && !!x.agentPath);
+    if (targets.length === 0)
+        return null;
+    const catalog = await listModels(catalogProviderId);
+    const nextModel = catalog.find((m) => !m.hidden)?.id ?? catalog[0]?.id;
+    if (!nextModel)
+        return null;
+    let count = 0;
+    for (const { sid, agentPath } of targets) {
+        try {
+            await setAgentModels(sid, agentPath, [nextModel]);
+            count++;
+        }
+        catch (e) {
+            // Best-effort per session — one bad agent.json must not abort the rest.
+            console.warn('[model-route] reset session model failed', { sid, agentPath, err: e });
+        }
+    }
+    return count > 0 ? { selected: nextModel, count } : null;
+}
+/**
+ * On SESSION SWITCH: conform the switched-to session's model to the currently
+ * ACTIVE provider (Settings › Providers is the single global provider setting;
+ * the in-chat switcher is hidden). "Does this session's provider match the
+ * active provider?" is answered by CATALOG MEMBERSHIP — a session whose
+ * agent.json model isn't in the active provider's catalog was last touched
+ * under a DIFFERENT provider (e.g. switching game loads that game's disk
+ * sessions, which the last provider-switch reset never reached).
+ *
+ *   • mismatch → snap the session's model to this provider's last HAND-PICKED
+ *     model (model-prefs), else its catalog default (first non-hidden);
+ *   • match (model already in the active catalog) → leave it untouched
+ *     ("同 provider 就不管").
+ *
+ * Best-effort + returns null on no-op: an empty catalog, a missing model, or
+ * any IO failure must never block the session switch. Returns the model set on
+ * a mismatch so the caller can repaint immediately if it wants.
+ */
+export async function reconcileSessionModelToActiveProvider(sid, agentPath) {
+    const catalogProviderId = currentCatalogProvider(useShellStore.getState().providerOverride);
+    const catalog = await listModels(catalogProviderId).catch(() => null);
+    if (!catalog || catalog.length === 0)
+        return null;
+    const cur = await getAgentModel(sid, agentPath).catch(() => null);
+    const currentId = cur?.selected ?? null;
+    // Same provider — the session's model is a member of the active catalog. Leave it.
+    if (currentId && catalog.some((m) => m.id === currentId))
+        return null;
+    // Mismatch — prefer this provider's last hand-picked model, else its default.
+    const remembered = getLastModel(catalogProviderId);
+    const next = preferredCatalogModel(catalog, remembered);
+    if (!next)
+        return null;
+    try {
+        await setAgentModels(sid, agentPath, [next]);
+        return { selected: next };
+    }
+    catch (e) {
+        console.warn('[model-route] reconcile session model failed', { sid, agentPath, err: e });
+        return null;
+    }
+}

package/dist/package/browser/lib/narrative-copilot.d.ts

@@ -0,0 +1,20 @@
+/** 叙事工坊「完成即重唤醒」闭环（END 侧）。
+ *
+ *  背景：剧情师 Kotone 是一问一答的 agent —— 用它跑叙事管线时，它在**启动那一轮**里
+ *  讲完选型、调 `narrative:start-pipeline`（秒回 runId）后这一轮就结束、随即静默。管线在
+ *  后台跑几分钟，跑完是个**后台事件**，没人唤醒 Kotone，于是用户若不再开口就永远等不到
+ *  「完成总结」。
+ *
+ *  本模块补上这一环：监听 Kotone 调用 start-pipeline，轮询叙事后端直到该 run 进入终态，
+ *  然后给 Kotone（事件 emitter）投一条 user_input 系统提示，触发它产出完成总结。
+ *
+ *  为什么放前端、靠 history 轮询：
+ *  - `hook:toolResult` 事件**不带工具返回值**，前端拿不到 runId；但叙事后端同源暴露
+ *    `/api/narrative/history`（带 status），且后端强制单实例 run，所以「当前在跑的那条」
+ *    就是 Kotone 刚起的。
+ *  - 前端是同时连着「agent 会话(WS)」和「叙事后端(REST)」的唯一协调者；放后端要跨进程。
+ *
+ *  START 侧（左栏回填 + 中间预览直播）由 extension-narrative viz 的 useAutoAttach 自包含完成，
+ *  不在本模块职责内。 */
+/** Boot 时调一次（main.tsx）。按 key 注册，HMR 重载会覆盖旧 handler。 */
+export declare function subscribeNarrativeCopilot(): void;

package/dist/package/browser/lib/narrative-copilot.js

@@ -0,0 +1,105 @@
+/** 叙事工坊「完成即重唤醒」闭环（END 侧）。
+ *
+ *  背景：剧情师 Kotone 是一问一答的 agent —— 用它跑叙事管线时，它在**启动那一轮**里
+ *  讲完选型、调 `narrative:start-pipeline`（秒回 runId）后这一轮就结束、随即静默。管线在
+ *  后台跑几分钟，跑完是个**后台事件**，没人唤醒 Kotone，于是用户若不再开口就永远等不到
+ *  「完成总结」。
+ *
+ *  本模块补上这一环：监听 Kotone 调用 start-pipeline，轮询叙事后端直到该 run 进入终态，
+ *  然后给 Kotone（事件 emitter）投一条 user_input 系统提示，触发它产出完成总结。
+ *
+ *  为什么放前端、靠 history 轮询：
+ *  - `hook:toolResult` 事件**不带工具返回值**，前端拿不到 runId；但叙事后端同源暴露
+ *    `/api/narrative/history`（带 status），且后端强制单实例 run，所以「当前在跑的那条」
+ *    就是 Kotone 刚起的。
+ *  - 前端是同时连着「agent 会话(WS)」和「叙事后端(REST)」的唯一协调者；放后端要跨进程。
+ *
+ *  START 侧（左栏回填 + 中间预览直播）由 extension-narrative viz 的 useAutoAttach 自包含完成，
+ *  不在本模块职责内。 */
+import { getSessionClient } from '../store-parts/session-client';
+const START_TOOL = 'narrative:start-pipeline';
+const POLL_MS = 5_000;
+/** 安全上限：超过则放弃 watch（避免 zombie run 让定时器永生）。 */
+const MAX_WATCH_MS = 40 * 60 * 1_000;
+/** 同一 (sid::agent) 同时只跑一个 watcher，避免重复唤醒。 */
+const activeWatchers = new Set();
+async function fetchNarrativeHistory() {
+    try {
+        const r = await fetch('/api/narrative/history');
+        if (!r.ok)
+            return [];
+        const j = (await r.json());
+        return Array.isArray(j) ? j : [];
+    }
+    catch {
+        return [];
+    }
+}
+function watchRunToCompletion(sid, agent) {
+    const watcherKey = `${sid}::${agent}`;
+    if (activeWatchers.has(watcherKey))
+        return; // 已在 watch（同一 agent 连点不重复起）
+    activeWatchers.add(watcherKey);
+    const startedAt = Date.now();
+    // 记住「我们确实看到过它在跑」的那条 run —— 只有见过 running 才认它真起来了，
+    // 避免 toolCall 后 run 尚未起来就误判「已结束」。
+    let seenRunningKey = null;
+    const stop = () => {
+        window.clearInterval(timer);
+        activeWatchers.delete(watcherKey);
+    };
+    const timer = window.setInterval(() => {
+        void (async () => {
+            if (Date.now() - startedAt > MAX_WATCH_MS) {
+                stop();
+                return;
+            }
+            const history = await fetchNarrativeHistory();
+            if (history.length === 0)
+                return;
+            const running = history.find((e) => e.status === 'running' && !!e.id);
+            if (running) {
+                seenRunningKey = running.key;
+                return;
+            }
+            // 没有 running 了。若我们之前见过它在跑 → 判定结束，取它的终态去唤醒。
+            if (seenRunningKey) {
+                const entry = history.find((e) => e.key === seenRunningKey);
+                const status = entry?.status ?? 'completed';
+                stop();
+                await nudgeKotone(sid, agent, seenRunningKey, status);
+            }
+            // 还没见过 running（run 尚未起来 / 起得很快已结束）—— 继续等到超时为止。
+        })();
+    }, POLL_MS);
+}
+async function nudgeKotone(sid, agent, runKey, status) {
+    const completed = status === 'completed';
+    const content = completed
+        ? `【叙事工坊 · 系统通知】你刚启动的管线已完成（输出目录：${runKey}）。请用 narrative:get-run-status / narrative:get-story-tree / narrative:read-file 看一下产出，按你剧情师的视角给用户一段完成总结：跑了哪些环节、产出是什么、是否符合用户需求（默认符合，明显跑偏才指出并建议 narrative:regenerate-step）。`
+        : `【叙事工坊 · 系统通知】你刚启动的管线已结束，状态为「${status}」（输出目录：${runKey}）。请用 narrative:get-run-status 看一下停在哪一步、为什么，给用户一句说明并建议下一步（narrative:resume-pipeline 续跑 / 重新启动等）。`;
+    await getSessionClient().emitForgeaXMessage(sid, content, {
+        to: agent,
+        type: 'user_input',
+        // session-stream 据此把它渲染成「叙事工坊」系统来信行，而非伪装成用户气泡。
+        payload: { narrativeAutoNudge: true, runKey, runStatus: status },
+    }).catch(() => {
+        /* 唤醒失败静默 —— 用户仍可手动追问，不阻塞主流程 */
+    });
+}
+/** Boot 时调一次（main.tsx）。按 key 注册，HMR 重载会覆盖旧 handler。 */
+export function subscribeNarrativeCopilot() {
+    getSessionClient().onSessionEvent('narrative-copilot', (e) => {
+        const ev = e.event;
+        if (!ev || ev.type !== 'hook:toolCall')
+            return;
+        const payload = ev.payload;
+        const toolName = payload.name ?? payload.toolCall?.name;
+        if (toolName !== START_TOOL)
+            return;
+        const agent = e.emitterId;
+        if (!agent)
+            return;
+        watchRunToCompletion(e.sid, agent);
+    });
+}

package/dist/package/browser/lib/native-menu-bridge.d.ts

@@ -0,0 +1,37 @@
+/** native-menu-bridge —— Tauri 原生菜单桥 (T5).
+ *
+ *  角色:把 web 端 menu-registry 的 SSOT 快照喂给原生菜单栏,把原生点击回吐给
+ *  command bus。**两个方向都在这里**,让 Rust 侧完全不碰业务逻辑 (Rust 只做:
+ *  JSON → Menu / id → emit)。压缩公理:菜单栏一处真源,web/native 都由它派生。
+ *
+ *  典型时序:
+ *    1. 应用启动完成、boot 完毕后,App.tsx 调 `initNativeMenuBridge(...)`;
+ *    2. 桥内:
+ *         a. serializeMenusForNative(t)  取全量菜单契约
+ *         b. 顶层塞 title = t('menubar.<menu>')  Rust 不做 i18n
+ *         c. invoke('set_app_menu', { payload })  Rust 建 Menu 并挂到 app
+ *         d. listen('menu:invoke', ...)          原生点击 → command bus
+ *         e. onMenuChange(rebuild)               后续注册表变 → 重新 push
+ *    3. 浏览器形态 (isTauri()===false) 全 no-op,零回归。
+ *
+ *  ⚠️ Rust 侧收到的 payload 结构与 menu-registry.ts 的 `NativeMenu` 一致,
+ *  但额外带一个可选 `title` —— 我们在这里补上,契约扩展在桥内闭环,不动 T1。
+ */
+/** 派发接口:与 host.commands.execute 兼容,fire-and-forget。 */
+export type MenuExecute = (id: string, args?: unknown) => void | Promise<unknown>;
+export interface InitNativeMenuBridgeOptions {
+    /** 命令派发器 —— 通常是 (id, args) => host.commands.execute(id, args)。 */
+    execute: MenuExecute;
+    /** i18n 翻译器 —— 通常是 useTranslation().t。 */
+    translate: (key: string) => string;
+}
+/** 打一条链路追踪。同时走 console 和 Rust stderr —— release 的 .app 关掉了
+ *  tauri 的 `devtools` feature,webview console 在那里够不着,只有转发到
+ *  Rust 才能和 on_menu_event / set_app_menu 的日志汇在同一个流里比对时序。
+ *
+ *  导出给链路下游(命令落地后的 UI 环节)复用,让"事件没到"与"命令跑了但界面
+ *  没出来"在同一个流里可区分。sink 未装上前只进 console。 */
+export declare function fxTrace(line: string): void;
+/** Public entry —— App.tsx 在 boot 完成后调用一次。返回 Promise 让调用方能
+ *  await (不必须);浏览器形态立刻 resolve()。 */
+export declare function initNativeMenuBridge(opts: InitNativeMenuBridgeOptions): Promise<void>;

package/dist/package/browser/lib/native-menu-bridge.js

@@ -0,0 +1,151 @@
+/** native-menu-bridge —— Tauri 原生菜单桥 (T5).
+ *
+ *  角色:把 web 端 menu-registry 的 SSOT 快照喂给原生菜单栏,把原生点击回吐给
+ *  command bus。**两个方向都在这里**,让 Rust 侧完全不碰业务逻辑 (Rust 只做:
+ *  JSON → Menu / id → emit)。压缩公理:菜单栏一处真源,web/native 都由它派生。
+ *
+ *  典型时序:
+ *    1. 应用启动完成、boot 完毕后,App.tsx 调 `initNativeMenuBridge(...)`;
+ *    2. 桥内:
+ *         a. serializeMenusForNative(t)  取全量菜单契约
+ *         b. 顶层塞 title = t('menubar.<menu>')  Rust 不做 i18n
+ *         c. invoke('set_app_menu', { payload })  Rust 建 Menu 并挂到 app
+ *         d. listen('menu:invoke', ...)          原生点击 → command bus
+ *         e. onMenuChange(rebuild)               后续注册表变 → 重新 push
+ *    3. 浏览器形态 (isTauri()===false) 全 no-op,零回归。
+ *
+ *  ⚠️ Rust 侧收到的 payload 结构与 menu-registry.ts 的 `NativeMenu` 一致,
+ *  但额外带一个可选 `title` —— 我们在这里补上,契约扩展在桥内闭环,不动 T1。
+ */
+import { isTauri } from './platform/runtime';
+import { warmRecentGames } from './recent-games';
+import { onMenuChange, serializeMenusForNative, snapshotAllMenus, } from './menu-registry';
+// ─── Menu id → command lookup (原生点击回吐用) ─────────────────────────────
+/** 展平所有菜单项 (含 children),建 id → def 的索引,供 menu:invoke 回吐时 O(1)
+ *  查表。不缓存:每次点击都 fresh 一遍,让 when/enabled 变化立刻生效;菜单量级
+ *  几十项,遍历开销可忽略。 */
+function findMenuItemById(id) {
+    const all = snapshotAllMenus();
+    for (const menuId of Object.keys(all)) {
+        const found = findInList(all[menuId], id);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+function findInList(list, id) {
+    for (const item of list) {
+        if (item.id === id)
+            return item;
+        // Recurse into static children AND dynamic ones — a native click on a
+        // dynamically-derived row (e.g. a recent game under 打开最近) must resolve
+        // to its def so its commandId + args get dispatched. dynamicChildren is
+        // re-derived here (cache current at click time), matching what was pushed.
+        const kids = item.children && item.children.length > 0
+            ? item.children
+            : item.dynamicChildren
+                ? item.dynamicChildren()
+                : null;
+        if (kids && kids.length > 0) {
+            const nested = findInList(kids, id);
+            if (nested)
+                return nested;
+        }
+    }
+    return undefined;
+}
+// ─── Trace (定位链路用) ───────────────────────────────────────────────────
+/** Rust 侧 `fx_trace` 的句柄,init 拿到 invoke 后装上。 */
+let traceSink = null;
+/** 打一条链路追踪。同时走 console 和 Rust stderr —— release 的 .app 关掉了
+ *  tauri 的 `devtools` feature,webview console 在那里够不着,只有转发到
+ *  Rust 才能和 on_menu_event / set_app_menu 的日志汇在同一个流里比对时序。
+ *
+ *  导出给链路下游(命令落地后的 UI 环节)复用,让"事件没到"与"命令跑了但界面
+ *  没出来"在同一个流里可区分。sink 未装上前只进 console。 */
+export function fxTrace(line) {
+    console.debug('[fx-trace]', line);
+    traceSink?.(line);
+}
+/** 模块内简称。 */
+const trace = fxTrace;
+// ─── Push (registry → native) ─────────────────────────────────────────────
+/** 把当前注册表快照推给 Rust。失败时 warn 但不抛 —— 菜单更新失败不该让 boot
+ *  炸掉;下次 onMenuChange 会重试。 */
+async function pushMenusToNative(invoke, translate) {
+    // Warm the recent-games cache so 打开最近's dynamicChildren serialize with a
+    // current list. Web warms on File-dropdown open; native has no such hook, so
+    // we warm here before every rebuild. Failures leave the last cache intact.
+    trace('push: warmRecentGames…');
+    await warmRecentGames();
+    trace('push: warmRecentGames done, serializing…');
+    const raw = serializeMenusForNative(translate);
+    // 补顶层 title —— 与 MenuBar.tsx 的 `t('menubar.${menu}')` 保持一致。
+    const payload = raw.map((m) => ({
+        ...m,
+        title: translate(`menubar.${m.menu}`),
+    }));
+    const fileIds = raw.find((m) => m.menu === 'file')?.items.map((i) => i.id) ?? [];
+    trace(`push: serialized menus=${payload.length} file.items=[${fileIds.join(',')}]`);
+    try {
+        await invoke('set_app_menu', { payload });
+        trace('push: set_app_menu resolved');
+    }
+    catch (err) {
+        trace(`push: set_app_menu REJECTED ${err?.message ?? String(err)}`);
+        console.warn('[native-menu-bridge] set_app_menu failed:', err?.message ?? err);
+    }
+}
+// ─── Init (唯一对外入口) ────────────────────────────────────────────────
+/** 幂等标记:StrictMode 双 invoke / boot 双路径都可能重入 init,原生只该被安装一次。
+ *  一旦装上:后续调用直接返回。 */
+let installed = false;
+/** Public entry —— App.tsx 在 boot 完成后调用一次。返回 Promise 让调用方能
+ *  await (不必须);浏览器形态立刻 resolve()。 */
+export async function initNativeMenuBridge(opts) {
+    if (!isTauri())
+        return; // web 形态 no-op
+    if (installed)
+        return;
+    installed = true;
+    const { translate } = opts;
+    // 懒加载 Tauri API —— 与 runtime.ts 的其它加载器同风格,避免把 chunk 塞进 web bundle。
+    const [{ invoke }, eventMod] = await Promise.all([
+        import('@tauri-apps/api/core'),
+        import('@tauri-apps/api/event'),
+    ]);
+    traceSink = (line) => { void invoke('fx_trace', { line }).catch(() => { }); };
+    trace('init: tauri api loaded, starting first push…');
+    // 1. 原生点击回吐 —— Rust 侧 on_menu_event emit 'menu:invoke' { id },
+    //    我们查注册表拿到 commandId + args,派发到 command bus。
+    //    先注册监听器再做首次 push:首次 push 会预热 listGames,若接口卡住,
+    //    旧菜单仍能响应点击,不会出现"菜单显示但点击无反应"的窗口。
+    await eventMod.listen('menu:invoke', (ev) => {
+        const id = ev.payload?.id;
+        trace(`recv: menu:invoke id=${String(id)}`);
+        if (!id)
+            return;
+        const def = findMenuItemById(id);
+        if (!def) {
+            // 原生菜单栏比 web 快照晚一拍时可能出现;下次 push 会对齐。
+            trace(`recv: id=${id} NOT FOUND in registry — dropped`);
+            console.warn('[native-menu-bridge] menu:invoke for unknown id:', id);
+            return;
+        }
+        if (!def.commandId) {
+            trace(`recv: id=${id} has no commandId (placeholder) — dropped`);
+            return; // 纯文本占位项,无命令。
+        }
+        trace(`dispatch: id=${id} → command '${def.commandId}' args=${JSON.stringify(def.args ?? null)}`);
+        void Promise.resolve(opts.execute(def.commandId, def.args)).then((r) => trace(`dispatch: '${def.commandId}' resolved ${JSON.stringify(r ?? null)}`), (e) => trace(`dispatch: '${def.commandId}' REJECTED ${e?.message ?? String(e)}`));
+    });
+    trace('init: menu:invoke listener registered — bridge live before first push');
+    // 2. 注册表变动 —— 后续 register/unregister/when 切换都会触发 rebuild。
+    //    在 change 时直接 fire-and-forget push;失败已在 pushMenusToNative 内吞。
+    onMenuChange(() => {
+        void pushMenusToNative(invoke, translate);
+    });
+    // 3. 首次推送 —— 让原生菜单栏与当前注册表对齐。
+    await pushMenusToNative(invoke, translate);
+    trace('init: first push returned');
+}

package/dist/package/browser/lib/page-tab-icons.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Unified Lucide mapping for open document tabs — the SSOT for "what icon does
+ * this page show". Uses one pure, react-free resolver so the tab strip and
+ * overflow menu never drift on icon
+ * semantics. Follow `DESIGN-SYSTEM.md` §icon rules — no ad-hoc
+ * per-file lucide imports, no emoji.
+ */
+import { type LucideIcon } from 'lucide-react';
+import type { ResourceDescriptor } from '@forgeax/types';
+/** Coarse content family a page belongs to — the axis icons key off. */
+export type PageKind = 'scene' | 'model' | 'image' | 'audio' | 'font' | 'pack' | 'code' | 'doc' | 'config' | 'plugin';
+/** Derive the content family from a resource path, else from the page type id. */
+export declare function pageKindOf(input: {
+    typeId: string;
+    resource?: ResourceDescriptor;
+}): PageKind;
+/** Resolve the Lucide icon for a page. Never returns undefined. */
+export declare function iconForPage(input: {
+    typeId: string;
+    resource?: ResourceDescriptor;
+}): LucideIcon;