@forgeax/interface 0.4.1

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

@@ -0,0 +1,201 @@
+/** host.menubar —— 菜单栏的双模态投影(dual-modality UI surface)。
+ *
+ * 发布两样东西。**目前这是唯一一个真正接入 surface 总线的界面** —— host.sidebar(rail)
+ * 至今没有发布者(见 docs/ai-native/pending-team-handoffs.md 的 H2),
+ * 不要把它当成现成范式去抄。要抄就抄这里:
+ *   1. snapshot = 菜单注册表的 JSON 安全树 —— AI 侧"静态功能表"的菜单分支。
+ *      结构(含"打开最近"这类子菜单)是静态的;dynamic=true 的子菜单内容
+ *      (最近游戏列表)在视觉展开时才求值,这个投影不展开它们。
+ *   2. `invoke` action = 执行一个菜单项,走与人点击**完全相同**的
+ *      `commands.execute(commandId, args)` —— MenuBar 的 onSelect 就是这一句。
+ *      AI 路径与人路径在同一个 handler 汇合,这正是 dual-modality 的意义;
+ *      也是页面外唯一正确的菜单执行入口(Radix 菜单项不响应合成 DOM 事件,
+ *      2026-08-04 实测 click / pointer 序列 / focus+Enter 全部无效)。
+ *
+ * 语言:label 用页面自己的 t() 翻译,所以永远和用户看到的 DOM 文本一致 ——
+ * 消费方按 label 做视觉遍历不会跨语言错位。
+ */
+import { useEffect, useRef } from 'react';
+import { useSurface } from '../../lib/surface';
+import { snapshotAllMenus } from '../../lib/menu-registry';
+import { warmRecentGames } from '../../lib/recent-games';
+const MENUBAR_SCHEMA = {
+    type: 'object',
+    properties: {
+        menus: {
+            type: 'object',
+            description: 'menu id → item tree. kind=submenu with dynamic=true resolves its children only when visually opened.',
+        },
+    },
+};
+function projectItem(item, t) {
+    try {
+        if (item.when && !item.when())
+            return null;
+    }
+    catch {
+        return null; // 谓词抛异常按隐藏处理,投影永不因单项而炸
+    }
+    const isSub = (item.children?.length ?? 0) > 0 || !!item.dynamicChildren;
+    const children = item.children
+        ?.map((child) => projectItem(child, t))
+        .filter((node) => node !== null);
+    return {
+        id: item.id,
+        label: t(item.labelKey),
+        kind: isSub ? 'submenu' : item.commandId ? 'command' : 'placeholder',
+        ...(item.commandId ? { commandId: item.commandId } : {}),
+        ...(item.args !== undefined ? { args: item.args } : {}),
+        ...(item.keybinding ? { keybinding: item.keybinding } : {}),
+        ...(item.dynamicChildren ? { dynamic: true } : {}),
+        ...(item.dynamicChildCommandId ? { childCommandId: item.dynamicChildCommandId } : {}),
+        ...(item.dynamicChildIdFromArg ? { childIdFromArg: item.dynamicChildIdFromArg } : {}),
+        ...(children && children.length ? { children } : {}),
+    };
+}
+export function projectMenuTree(t) {
+    const out = {};
+    for (const [menu, defs] of Object.entries(snapshotAllMenus())) {
+        out[menu] = defs
+            .map((def) => projectItem(def, t))
+            .filter((node) => node !== null);
+    }
+    return out;
+}
+/** 在注册表里解析一个可执行菜单项:先静态(含 children 递归),再对动态子菜单
+ *  求值按 id 或 label 匹配(动态项的 labelKey 就是显示名,如游戏名)。 */
+function resolveInvokable(target, t) {
+    /** 与 projectItem 同一条谓词:`when()` 为假 = 该项在界面上根本不存在。
+     *  2026-08-06 探测:此前只有投影过滤 when(),解析器完全不看 —— 一个在 snapshot
+     *  和 DOM 里都不存在的项仍可被 invoke 执行。人点不到的东西 AI 不能点,否则
+     *  "AI 走人的路"这条主张在隐藏项上直接失效。当前 builtin 菜单无人用 `when:`,
+     *  属于潜伏缺陷,但这是给别的团队照抄的模板,先堵上。 */
+    const visible = (def) => {
+        try {
+            return !def.when || def.when();
+        }
+        catch {
+            return false; // 谓词抛异常按隐藏处理,与 projectItem 一致
+        }
+    };
+    const matchDynamic = (parent) => {
+        if (!parent.dynamicChildren)
+            return null;
+        let kids = [];
+        try {
+            kids = parent.dynamicChildren();
+        }
+        catch {
+            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;
+    };
+    const walk = (defs) => {
+        for (const def of defs) {
+            // 隐藏项(含其整棵子树)按"界面上不存在"处理,不匹配也不递归 —— 与
+            // projectItem 的过滤同口径。
+            if (!visible(def))
+                continue;
+            if (target.itemId && def.id === target.itemId)
+                return def;
+            if (target.label && !target.itemId && t(def.labelKey) === target.label)
+                return def;
+            if (def.children) {
+                const hit = walk(def.children);
+                if (hit)
+                    return hit;
+            }
+            if (!target.parentId || def.id === target.parentId) {
+                const hit = matchDynamic(def);
+                if (hit)
+                    return hit;
+            }
+        }
+        return null;
+    };
+    for (const defs of Object.values(snapshotAllMenus())) {
+        const hit = walk(defs);
+        if (hit)
+            return hit;
+    }
+    return null;
+}
+/** MenuBar 挂载时注册 host.menubar。menusRevision 传注册表快照对象,引用一变
+ *  (注册表变更触发的重渲染)就重新投影 PUT。 */
+export function useMenubarSurface(menusRevision, t, execute, 
+/** 当前语言。**必须**由调用方传:`t` 的标识是模块级恒定的(见 i18n/index.ts
+ *  的注释:列进依赖会造成无限重渲染),拿它当依赖 = 永不重投影。 */
+language) {
+    const executeRef = useRef(execute);
+    executeRef.current = execute;
+    const tRef = useRef(t);
+    tRef.current = t;
+    const surface = useSurface({
+        id: 'host.menubar',
+        layer: 'host',
+        schema: MENUBAR_SCHEMA,
+        initialSnapshot: { menus: projectMenuTree(t) },
+        actions: {
+            invoke: {
+                id: 'invoke',
+                argsSchema: {
+                    type: 'object',
+                    properties: {
+                        itemId: { type: 'string', description: 'stable menu item id, e.g. file.save or file.openRecent.<slug>' },
+                        parentId: { type: 'string', description: 'submenu id to resolve dynamic children under, e.g. file.openRecent' },
+                        label: { type: 'string', description: 'visible label — used when the item is dynamic and its id is unknown' },
+                    },
+                },
+                run: async (raw) => {
+                    const target = (raw ?? {});
+                    let def = resolveInvokable(target, tRef.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);
+                    }
+                    if (!def)
+                        throw new Error(`menu item not found: ${JSON.stringify(target)}`);
+                    const enabled = def.enabled ? def.enabled() : !!def.commandId;
+                    if (!enabled || !def.commandId)
+                        throw new Error(`menu item "${def.id}" is disabled or has no command wired`);
+                    // 2026-08-06 外审 B6①:此前不等命令完成就同步返回 —— 命令的异步失败对 agent
+                    // 不可见,file.save 失败也会被 ack 成功,agent 随即向用户断言"已保存"。
+                    // 人路径 fire-and-forget 有理由(不卡下拉动画),AI 路径没有:await 到底,
+                    // 失败 → throw → ack ok=false,agent 拿到真实回执。
+                    //
+                    // 但"启动后才失败"必须与上面两个"根本没启动"的 throw 区分开(2026-08-06
+                    // 自探):上游咽喉把 ack ok=false 一律当"确定没执行"→ 回落无头路径再派一次,
+                    // 于是写了一半就抛错的 file.save、后置步骤失败的新建游戏都会**跑两次**,
+                    // 而 agent 被告知"一次都没跑"。带上 started 标记,让消费方能作终态处理。
+                    try {
+                        await executeRef.current(def.commandId, def.args);
+                    }
+                    catch (error) {
+                        const started = new Error(`menu command "${def.commandId}" may have started but failed: ${error?.message ?? String(error)}`
+                            + '(命令可能已经开始执行,不要重试、不要换路径重派。)');
+                        // 语义是"**可能**已开始",不是"确定已开始":`commands.execute` 也可能在真正
+                        // 调用 handler 之前就 reject(commandId 声明了却从未注册等),界面这一侧
+                        // **区分不了**。所以这是个保守信号 —— 宁可让上游少做一次,也不能让它回落
+                        // 重派把同一命令跑两次。方向是刻意选的,别改成"确认执行过才标"。
+                        // 机器判据走 ack 的结构化字段,文案只给人看 —— 文案重排不再静默改变语义
+                        // (2026-08-07 外审 N3)。
+                        started.started = true;
+                        throw started;
+                    }
+                    // 与人路径同形:两侧都给 { itemId, commandId }。`invoked` 是旧键,
+                    // 保留以免既有消费方(door 注解 / 行走协议的 steps)读空。
+                    return { itemId: def.id, commandId: def.commandId, invoked: def.id };
+                },
+            },
+        },
+    });
+    useEffect(() => {
+        surface.setSnapshot({ menus: projectMenuTree(tRef.current) });
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [menusRevision, language]);
+}

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

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

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

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

package/dist/package/browser/components/ModelPicker/useModelCatalog.d.ts

@@ -0,0 +1,22 @@
+import { type CatalogDriverMeta, type ModelCatalogEntry } from '../../lib/model-config';
+export interface ModelCatalogState {
+    models: ModelCatalogEntry[] | null;
+    /** 内核目录路径的回退链元数据(gateway 路径为 undefined)。 */
+    driver: CatalogDriverMeta | null;
+    error: string | null;
+    refresh: () => Promise<void>;
+}
+export declare function useModelCatalog(providerId?: string | null): ModelCatalogState;
+export declare function _resetModelCatalogCache(): void;
+/**
+ * Force-refresh every catalog the app currently holds — call after an LLM
+ * credential change (new key / base-url can change which models the proxy
+ * exposes, e.g. switching LiteLLM proxies). Refetches each known (providerId)
+ * tuple with `force` and pushes the fresh list to all mounted consumers via
+ * their subscriber callbacks, so the picker updates without a page reload.
+ *
+ * Covers both cached and actively-subscribed keys; nothing to refresh (no
+ * picker mounted yet) → no-op, the next mount fetches fresh anyway. The
+ * default gateway key ('gateway') maps back to `undefined` providerId.
+ */
+export declare function refreshAllModelCatalogs(): Promise<void>;

package/dist/package/browser/components/ModelPicker/useModelCatalog.js

@@ -0,0 +1,100 @@
+import { useEffect, useState } from 'react';
+import { listModelsWithMeta, } from '../../lib/model-config';
+// Window-level memo so Composer + TopBar + ModelLab share one fetch.
+// list_models hits ~/.forgeax/key/models.json + LiteLLM /v1/models with a 60s
+// TTL upstream, but the browser-side hop should still be deduped across the 3
+// surfaces that all mount at app boot.
+//
+// 缓存单位是整份 payload(models + driver 元数据):内核目录路径的空态/徽章
+// 需要 driver.source/error,不能在这一层丢掉。
+const cached = new Map();
+const inflight = new Map();
+const subscribers = new Map();
+function cacheKey(providerId) {
+    return providerId?.trim() || 'gateway';
+}
+function subscriberSet(key) {
+    let set = subscribers.get(key);
+    if (!set) {
+        set = new Set();
+        subscribers.set(key, set);
+    }
+    return set;
+}
+async function fetchOnce(providerId, force = false) {
+    const key = cacheKey(providerId);
+    const hit = cached.get(key);
+    if (hit && !force)
+        return hit;
+    const current = inflight.get(key);
+    if (current)
+        return current;
+    const next = (async () => {
+        try {
+            const payload = await listModelsWithMeta(providerId);
+            cached.set(key, payload);
+            for (const cb of subscriberSet(key))
+                cb(payload);
+            return payload;
+        }
+        finally {
+            inflight.delete(key);
+        }
+    })();
+    inflight.set(key, next);
+    return next;
+}
+export function useModelCatalog(providerId) {
+    const key = cacheKey(providerId);
+    const [payload, setPayload] = useState(cached.get(key) ?? null);
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        let cancelled = false;
+        const sub = (p) => { if (!cancelled)
+            setPayload(p); };
+        const subs = subscriberSet(key);
+        subs.add(sub);
+        const hit = cached.get(key);
+        if (hit)
+            setPayload(hit);
+        else {
+            fetchOnce(providerId)
+                .then((p) => { if (!cancelled) {
+                setPayload(p);
+                setError(null);
+            } })
+                .catch((e) => { if (!cancelled)
+                setError(e.message); });
+        }
+        return () => { cancelled = true; subs.delete(sub); };
+    }, [key, providerId]);
+    const refresh = async () => {
+        try {
+            await fetchOnce(providerId, true);
+            setError(null);
+        }
+        catch (e) {
+            setError(e.message);
+        }
+    };
+    return { models: payload?.models ?? null, driver: payload?.driver ?? null, error, refresh };
+}
+export function _resetModelCatalogCache() {
+    cached.clear();
+    inflight.clear();
+}
+/**
+ * Force-refresh every catalog the app currently holds — call after an LLM
+ * credential change (new key / base-url can change which models the proxy
+ * exposes, e.g. switching LiteLLM proxies). Refetches each known (providerId)
+ * tuple with `force` and pushes the fresh list to all mounted consumers via
+ * their subscriber callbacks, so the picker updates without a page reload.
+ *
+ * Covers both cached and actively-subscribed keys; nothing to refresh (no
+ * picker mounted yet) → no-op, the next mount fetches fresh anyway. The
+ * default gateway key ('gateway') maps back to `undefined` providerId.
+ */
+export async function refreshAllModelCatalogs() {
+    const keys = new Set([...cached.keys(), ...subscribers.keys()]);
+    await Promise.all([...keys].map((k) => fetchOnce(k === 'gateway' ? undefined : k, true).catch(() => ({ models: [] }))));
+}

package/dist/package/browser/components/Onboarding/ConnectModelPrompt.d.ts

@@ -0,0 +1,2 @@
+import './Onboarding.css';
+export declare function ConnectModelPrompt(): import("react/jsx-runtime").JSX.Element | null;

package/dist/package/browser/components/Onboarding/ConnectModelPrompt.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// ConnectModelPrompt — the first-chat interceptor (design §11). Mounted once at
+// the app root; dormant until the chat composer fires APP_EVENTS.openConnectPrompt
+// because the product-injected readiness service reported no usable model path.
+//
+// It offers the two connectable sources, framed as "connect to send the message
+// you just typed":
+//   API Key  → deep-link into Settings › Providers (user pastes a key there).
+//   Local CLI→ deep-link into Settings › Providers.
+//
+// Kept intentionally thin: it owns presentation only. The Chat composer that
+// opened it owns the pending text, readiness interception, and resume.
+import { useCallback, useEffect, useState } from 'react';
+import { installCustomEventObservation } from '@forgeax/app-shell/react';
+import { useTranslation } from '../../i18n';
+import { useShellStore } from '../../store';
+import { APP_EVENTS } from '../../lib/storageKeys';
+import './Onboarding.css';
+export function ConnectModelPrompt() {
+    const { t } = useTranslation();
+    const [open, setOpen] = useState(false);
+    const openOverlay = useShellStore((s) => s.openOverlay);
+    useEffect(() => {
+        const onOpen = () => setOpen(true);
+        const disposeOpenPromptObservation = installCustomEventObservation({
+            target: window,
+            eventType: APP_EVENTS.openConnectPrompt,
+            onEvent: onOpen,
+        });
+        return disposeOpenPromptObservation;
+    }, []);
+    const gotoProviders = useCallback(() => {
+        setOpen(false);
+        openOverlay('settings', 'providers');
+    }, [openOverlay]);
+    if (!open)
+        return null;
+    return (_jsx("div", { className: "fx-ob-modal-scrim", style: { zIndex: 99998 }, onClick: (e) => { if (e.target === e.currentTarget)
+            setOpen(false); }, children: _jsx("div", { className: "fx-ob-modal", role: "dialog", "aria-modal": "true", children: _jsxs("div", { className: "fx-ob-modal-inner", children: [_jsxs("div", { className: "fx-ob-stack fx-ob-gap6", children: [_jsx("h2", { className: "fx-ob-h2", children: t('onboarding.nudge.connectTitle') }), _jsx("div", { className: "fx-ob-sec", children: t('onboarding.nudge.connectSub') })] }), _jsxs("div", { className: "fx-ob-stack fx-ob-gap8", children: [_jsx("button", { className: "fx-ob-btn fx-ob-btn-primary fx-ob-btn-block", onClick: gotoProviders, children: t('onboarding.nudge.connectKey') }), _jsx("button", { className: "fx-ob-btn fx-ob-btn-secondary fx-ob-btn-block", onClick: gotoProviders, children: t('onboarding.nudge.connectCli') })] }), _jsx("div", { className: "fx-ob-row", style: { justifyContent: 'center' }, children: _jsx("button", { className: "fx-ob-btn fx-ob-btn-ghost", onClick: () => setOpen(false), children: t('onboarding.nudge.connectCancel') }) })] }) }) }));
+}

package/dist/package/browser/components/Onboarding/Onboarding.css

@@ -0,0 +1,232 @@
+/* Onboarding — faithful port of first-run-onboarding-prototype. Scoped under
+   .fx-ob-overlay so the class names can't collide with the shell. Tokens map to
+   the brand palette (lime accent) with hard fallbacks so it renders correctly
+   even before theme tokens resolve. */
+
+.fx-ob-overlay {
+  --ob-accent: var(--primary, #d4ff48);
+  /* Bright lime fill → black text. Must use design-system on-bright token
+     (not the nonexistent --on-primary) so hover/active stay readable. */
+  --ob-on-accent: var(--color-text-on-bright-primary, #000000);
+  --ob-bg-chrome: #141414;
+  --ob-bg-editor: #181818;
+  --ob-text: var(--text-primary, #e8e8e8);
+  --ob-text-2: rgba(232, 232, 232, 0.62);
+  --ob-text-3: rgba(232, 232, 232, 0.40);
+  --ob-text-4: rgba(232, 232, 232, 0.26);
+  --ob-fill-1: rgba(232, 232, 232, 0.14);
+  --ob-fill-2: rgba(232, 232, 232, 0.10);
+  --ob-fill-3: rgba(232, 232, 232, 0.06);
+  --ob-fill-4: rgba(232, 232, 232, 0.035);
+  --ob-stroke-1: rgba(232, 232, 232, 0.20);
+  --ob-stroke-2: rgba(232, 232, 232, 0.12);
+  --ob-stroke-3: rgba(232, 232, 232, 0.08);
+  --ob-ok: #3fa266;
+  --ob-ok-bg: rgba(63, 162, 102, 0.14);
+  --ob-warn: #e0a44a;
+  --ob-warn-bg: rgba(224, 164, 74, 0.13);
+  --ob-info-bg: rgba(89, 156, 231, 0.12);
+  --ob-err-bg: rgba(224, 74, 90, 0.14);
+
+  position: fixed;
+  inset: 0;
+  z-index: var(--z-toplevel, 99999);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 24px;
+  background: rgba(10, 10, 15, 0.82);
+  color: var(--ob-text);
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Microsoft YaHei', Helvetica, Arial, sans-serif;
+  font-size: 14px;
+  line-height: 1.5;
+  animation: fx-ob-fade 0.15s ease-out;
+}
+
+.fx-ob-card-shell { width: min(720px, 96vw); max-height: 92vh; overflow: auto; }
+
+.fx-ob-strip { display: flex; align-items: center; gap: 6px; flex-wrap: wrap; margin-bottom: 10px; }
+.fx-ob-dot { width: 8px; height: 8px; border-radius: 50%; background: var(--ob-fill-2); }
+.fx-ob-dot.active { background: var(--ob-accent); }
+.fx-ob-dot.passed { background: var(--ob-text-3); }
+.fx-ob-lbl { font-size: 12px; color: var(--ob-text-3); }
+.fx-ob-lbl.active { color: var(--ob-text); font-weight: 600; }
+.fx-ob-bar { width: 18px; height: 1px; background: var(--ob-stroke-3); }
+
+.fx-ob-frame { border: 1px solid var(--ob-stroke-2); border-radius: 10px; overflow: hidden; background: var(--ob-bg-chrome); }
+.fx-ob-frame-body { padding: 20px; background: var(--ob-bg-editor); }
+
+.fx-ob-h2 { font-size: 18px; font-weight: 620; margin: 0 0 2px; }
+.fx-ob-h3 { font-size: 15px; font-weight: 600; margin: 0 0 2px; }
+.fx-ob-sec { color: var(--ob-text-2); }
+.fx-ob-muted { color: var(--ob-text-3); }
+.fx-ob-small { font-size: 12px; }
+.fx-ob-tiny { font-size: 11px; }
+
+.fx-ob-stack { display: flex; flex-direction: column; }
+.fx-ob-row { display: flex; align-items: center; gap: 8px; }
+.fx-ob-grow { flex: 1; }
+.fx-ob-gap6 > * + * { margin-top: 6px; }
+.fx-ob-gap8 > * + * { margin-top: 8px; }
+.fx-ob-gap10 > * + * { margin-top: 10px; }
+.fx-ob-gap12 > * + * { margin-top: 12px; }
+.fx-ob-gap14 > * + * { margin-top: 14px; }
+.fx-ob-divider { height: 1px; background: var(--ob-stroke-3); margin: 4px 0; }
+
+.fx-ob-pill {
+  display: inline-flex; align-items: center; gap: 4px; padding: 3px 9px; border-radius: 999px;
+  font-size: 12px; border: 1px solid var(--ob-stroke-2); background: transparent; color: var(--ob-text-2);
+  cursor: pointer; user-select: none;
+}
+.fx-ob-pill.active { background: var(--ob-fill-1); color: var(--ob-text); border-color: var(--ob-stroke-1); }
+.fx-ob-pill.sm { padding: 1px 7px; font-size: 11px; }
+.fx-ob-pill.static { cursor: default; }
+
+.fx-ob-btn {
+  display: inline-flex; align-items: center; justify-content: center; gap: 6px; padding: 6px 12px;
+  border-radius: 7px; font-size: 13px; font-weight: 500; border: 1px solid var(--ob-stroke-1);
+  background: transparent; color: var(--ob-text); cursor: pointer;
+}
+.fx-ob-btn:disabled { opacity: 0.45; cursor: not-allowed; }
+/* Color contract matches .tb-modal-btn.primary; weight stays 500 (base), not 600. */
+.fx-ob-btn-primary {
+  background: var(--ob-accent);
+  color: var(--ob-on-accent);
+  border: none;
+}
+.fx-ob-btn-primary:hover:not(:disabled),
+.fx-ob-btn-primary:active:not(:disabled),
+.fx-ob-btn-primary:focus-visible:not(:disabled) {
+  background: var(--color-brand-primary-hover, var(--ob-accent));
+  color: var(--ob-on-accent);
+}
+/* Busy/disabled lime CTA: never fade the whole control with opacity — black text
+   and lime fill both go translucent and composite into the same muddy green. */
+.fx-ob-btn-primary:disabled,
+.fx-ob-btn-primary:disabled:hover {
+  opacity: 1;
+  cursor: not-allowed;
+  background: color-mix(in srgb, var(--ob-accent) 42%, var(--ob-bg-editor));
+  color: var(--ob-on-accent);
+}
+.fx-ob-btn-secondary { background: var(--ob-fill-2); color: var(--ob-text); }
+.fx-ob-btn-secondary:hover:not(:disabled) {
+  background: var(--ob-fill-1);
+  color: var(--ob-text);
+}
+.fx-ob-btn-ghost { background: transparent; border-color: transparent; color: var(--ob-text-3); }
+.fx-ob-btn-ghost:hover:not(:disabled) { color: var(--ob-text-2); }
+.fx-ob-btn-block { width: 100%; }
+
+/* Match the connect panel's Select trigger (shadcn h-9 / rounded-md / shadow-sm
+   / transparent bg / focus ring) so the API-key inputs and the CLI dropdown read
+   as one consistent control family. */
+.fx-ob-input {
+  width: 100%; height: 36px; padding: 8px 12px; border-radius: 6px; border: 1px solid var(--ob-stroke-1);
+  background: transparent; color: var(--ob-text); font-size: 14px; outline: none;
+  box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
+  transition: border-color 0.15s, box-shadow 0.15s;
+}
+.fx-ob-input::placeholder { color: var(--ob-text-4, #888); }
+.fx-ob-input:focus { border-color: var(--ob-accent); box-shadow: 0 0 0 1px var(--ob-accent); }
+
+.fx-ob-card { border: 1px solid var(--ob-stroke-2); border-radius: 9px; background: var(--ob-fill-4); overflow: hidden; }
+.fx-ob-card.sel { border-color: var(--ob-accent); }
+/* The overflow:hidden above makes a card's flex auto-minimum resolve to 0, so inside a
+   height-capped .fx-ob-stack (existing-games list, TemplateModal rows) enough rows would
+   shrink to ~0 instead of overflowing into the scrollbar. Rows must never absorb overflow. */
+.fx-ob-stack > .fx-ob-card { flex-shrink: 0; }
+.fx-ob-connect-card { cursor: pointer; }
+.fx-ob-connect-card:focus { outline: none; }
+.fx-ob-connect-card:focus-visible { box-shadow: inset 0 0 0 1px var(--ob-accent); }
+.fx-ob-connect-title { font-weight: 600; font-size: 14px; line-height: 1.4; }
+.fx-ob-connect-card .fx-ob-input,
+.fx-ob-connect-card button { cursor: auto; }
+.fx-ob-card-ch { display: flex; align-items: center; justify-content: space-between; padding: 7px 11px; font-size: 12px; color: var(--ob-text-2); border-bottom: 1px solid var(--ob-stroke-3); }
+.fx-ob-card-cb { padding: 11px; }
+.fx-ob-grid2 { display: grid; grid-template-columns: 1fr 1fr; gap: 12px; }
+.fx-ob-grid3 { display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 12px; }
+
+/* Project-step cards (新建 / 示例模板 / 打开目录): equal-height columns with the
+   action button pinned to the bottom. The description reserves a fixed 3-line box
+   so cards with shorter copy don't sit their "选择" button higher than the row's
+   tallest card — the reported button-misalignment. Scoped to the grids so the
+   TemplateModal's clickable .fx-ob-card rows are untouched. */
+.fx-ob-grid2 > .fx-ob-card,
+.fx-ob-grid3 > .fx-ob-card { display: flex; flex-direction: column; }
+.fx-ob-grid2 > .fx-ob-card > .fx-ob-card-cb,
+.fx-ob-grid3 > .fx-ob-card > .fx-ob-card-cb { flex: 1; display: flex; flex-direction: column; }
+.fx-ob-grid2 > .fx-ob-card .fx-ob-card-cb > .fx-ob-stack,
+.fx-ob-grid3 > .fx-ob-card .fx-ob-card-cb > .fx-ob-stack { flex: 1; }
+.fx-ob-grid2 > .fx-ob-card .fx-ob-card-cb .fx-ob-small.fx-ob-sec,
+.fx-ob-grid3 > .fx-ob-card .fx-ob-card-cb .fx-ob-small.fx-ob-sec { min-height: calc(1.5em * 3.5); }
+.fx-ob-grid2 > .fx-ob-card .fx-ob-card-cb .fx-ob-btn-block,
+.fx-ob-grid3 > .fx-ob-card .fx-ob-card-cb .fx-ob-btn-block { margin-top: auto; }
+
+.fx-ob-panel { border: 1px solid var(--ob-stroke-3); border-radius: 8px; padding: 12px; }
+
+.fx-ob-callout { border-radius: 8px; padding: 9px 11px; font-size: 13px; }
+.fx-ob-callout.ok { background: var(--ob-ok-bg); color: #a8dcbf; }
+.fx-ob-callout.warn { background: var(--ob-warn-bg); color: #e9c993; }
+.fx-ob-callout.info { background: var(--ob-info-bg); color: #bcd8f6; }
+.fx-ob-callout.err { background: var(--ob-err-bg); color: #eaa6ae; }
+.fx-ob-callout .t { font-weight: 600; display: block; margin-bottom: 2px; color: var(--ob-text); }
+.fx-ob-callout a { color: #87c3ff; }
+
+/* In-flight project init feedback: spinner + message so the server-side game
+   copy (new / template / open) reads as active work, not a frozen UI. */
+.fx-ob-busy { display: flex; align-items: center; gap: 9px; }
+.fx-ob-spinner {
+  flex: none;
+  width: 15px; height: 15px;
+  border: 2px solid rgba(188, 216, 246, 0.28);
+  border-top-color: #bcd8f6;
+  border-radius: 50%;
+  animation: fx-ob-spin 0.7s linear infinite;
+}
+@keyframes fx-ob-spin { to { transform: rotate(360deg); } }
+
+/* nested modal (template picker / connect prompt) */
+.fx-ob-modal-scrim {
+  /* Re-declare the --ob-* palette here too: ConnectModelPrompt renders a bare
+     .fx-ob-modal-scrim at the app root (no .fx-ob-overlay ancestor), so without
+     this the tokens don't cascade and the modal renders unstyled (transparent
+     bg / invisible borders). Keep in sync with the .fx-ob-overlay block above. */
+  --ob-accent: var(--primary, #d4ff48);
+  --ob-on-accent: var(--on-primary, #12161c);
+  --ob-bg-chrome: #141414;
+  --ob-bg-editor: #181818;
+  --ob-text: var(--text-primary, #e8e8e8);
+  --ob-text-2: rgba(232, 232, 232, 0.62);
+  --ob-text-3: rgba(232, 232, 232, 0.40);
+  --ob-text-4: rgba(232, 232, 232, 0.26);
+  --ob-fill-1: rgba(232, 232, 232, 0.14);
+  --ob-fill-2: rgba(232, 232, 232, 0.10);
+  --ob-fill-3: rgba(232, 232, 232, 0.06);
+  --ob-fill-4: rgba(232, 232, 232, 0.035);
+  --ob-stroke-1: rgba(232, 232, 232, 0.20);
+  --ob-stroke-2: rgba(232, 232, 232, 0.12);
+  --ob-stroke-3: rgba(232, 232, 232, 0.08);
+  --ob-ok: #3fa266;
+  --ob-ok-bg: rgba(63, 162, 102, 0.14);
+  --ob-warn: #e0a44a;
+  --ob-warn-bg: rgba(224, 164, 74, 0.13);
+  --ob-info-bg: rgba(89, 156, 231, 0.12);
+  --ob-err-bg: rgba(224, 74, 90, 0.14);
+  color: var(--ob-text);
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Microsoft YaHei', Helvetica, Arial, sans-serif;
+  font-size: 14px;
+  line-height: 1.5;
+  position: fixed; inset: 0; background: rgba(0, 0, 0, 0.55); z-index: 1; display: flex; align-items: center; justify-content: center; padding: 20px;
+}
+.fx-ob-modal { max-width: 460px; width: 100%; background: var(--ob-bg-chrome); border: 1px solid var(--ob-stroke-1); border-radius: 10px; overflow: hidden; }
+.fx-ob-modal-inner { padding: 16px; display: flex; flex-direction: column; gap: 12px; }
+
+/* first-chat nudge coach floating near the composer */
+.fx-ob-nudge {
+  position: fixed; z-index: var(--z-toplevel, 99999); max-width: 300px;
+  background: var(--ob-bg-chrome); border: 1px solid var(--ob-accent); border-radius: 10px; padding: 12px;
+  box-shadow: 0 12px 32px rgba(0, 0, 0, 0.5);
+}
+
+@keyframes fx-ob-fade { from { opacity: 0; } to { opacity: 1; } }

package/dist/package/browser/components/Onboarding/OnboardingController.d.ts

@@ -0,0 +1,10 @@
+import { useTranslation } from '../../i18n';
+import '../TopBar/FsBrowser.css';
+import '../TopBar/TopBar.css';
+import './Onboarding.css';
+export interface OnboardingControllerProps {
+    /** Product assemblies may disable the shell coach-mark tour while retaining setup. */
+    tourEnabled?: boolean;
+}
+export declare function OnboardingController({ tourEnabled }?: OnboardingControllerProps): import("react/jsx-runtime").JSX.Element | null;
+export type TFn = ReturnType<typeof useTranslation>['t'];