@forgeax/interface 0.4.1

package/dist/package/browser/lib/logSink.js

@@ -0,0 +1,128 @@
+/**
+ * logSink — best-effort persistence of the in-memory observe/debug streams
+ * (Console / Network / Info) to disk via `POST /api/logs`.
+ *
+ * Why: those three streams live only in the browser store (cap 500, in-memory),
+ * so a refresh / crash / closed tab loses them — useless for after-the-fact
+ * debugging. This sink mirrors every entry to `.forgeax/logs/<stream>.jsonl`
+ * on the server (size-rotated there).
+ *
+ * Contract: `recordLog(stream, entry)` is fire-and-forget and NEVER throws into
+ * its caller (the store mutators) — logging must not break the UI. Entries are
+ * batched and flushed on a short debounce, when a queue gets large, or when the
+ * tab is hidden / unloaded (sendBeacon) so the last buffer survives a close.
+ */
+// Per-page-load correlation id, stamped onto every POST so the three client
+// streams (console/network/info) of ONE browser session can be joined on disk
+// (and matched against a session's window in the server log). Minted once.
+const SESSION_ID = (() => {
+    try {
+        const c = globalThis.crypto;
+        if (c?.randomUUID)
+            return c.randomUUID();
+    }
+    catch { /* no crypto */ }
+    return `sid-${Date.now().toString(36)}-${Math.floor(Math.random() * 1e9).toString(36)}`;
+})();
+const QUEUES = { console: [], network: [], info: [] };
+const FLUSH_MS = 2000;
+const MAX_QUEUE = 100; // flush immediately past this to bound memory + payload size
+let timer = null;
+// Disk-write dedup: a per-frame error flood (e.g. a RAF-loop console.error at
+// 60Hz) would otherwise write 60 identical lines/sec. Collapse consecutive
+// identical entries within a window onto a single queued record + `repeat` count.
+// (The in-memory store's collapseEntries only folds the UI view, not disk.)
+const DEDUP_WINDOW_MS = 1000;
+const lastSig = {
+    console: null, network: null, info: null,
+};
+function sigOf(entry) {
+    if (!entry || typeof entry !== 'object')
+        return String(entry);
+    const { ts: _ts, id: _id, repeat: _r, ...rest } = entry;
+    void _ts;
+    void _id;
+    void _r;
+    try {
+        return JSON.stringify(rest);
+    }
+    catch {
+        return '';
+    }
+}
+function schedule() {
+    if (timer)
+        return;
+    timer = setTimeout(() => { timer = null; void flushAll(); }, FLUSH_MS);
+}
+async function flushStream(stream) {
+    const entries = QUEUES[stream];
+    if (entries.length === 0)
+        return;
+    // Detach the current batch up front so concurrent recordLog calls queue into
+    // a fresh array (and we don't double-send on failure).
+    QUEUES[stream] = [];
+    lastSig[stream] = null; // post-flush dups start a fresh record (don't bump a sent one)
+    try {
+        await fetch('/api/logs', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ stream, entries, sessionId: SESSION_ID }),
+            keepalive: true,
+        });
+    }
+    catch {
+        // Drop on failure rather than retry — an unreachable server shouldn't grow
+        // an unbounded in-memory backlog. The store still has the live entries.
+    }
+}
+async function flushAll() {
+    await Promise.all(Object.keys(QUEUES).map(flushStream));
+}
+export function recordLog(stream, entry) {
+    try {
+        const now = Date.now();
+        const sig = sigOf(entry);
+        const last = lastSig[stream];
+        if (last && last.sig === sig && now - last.ts < DEDUP_WINDOW_MS) {
+            // Identical flood within the window → bump `repeat` on the queued record
+            // instead of pushing a duplicate line.
+            last.entry.repeat = (typeof last.entry.repeat === 'number' ? last.entry.repeat : 1) + 1;
+            last.ts = now;
+            return;
+        }
+        const rec = (entry && typeof entry === 'object')
+            ? entry
+            : { value: entry };
+        const q = QUEUES[stream];
+        q.push(rec);
+        lastSig[stream] = { sig, ts: now, entry: rec };
+        if (q.length >= MAX_QUEUE)
+            void flushStream(stream);
+        else
+            schedule();
+    }
+    catch { /* never throw into the UI */ }
+}
+// Flush via sendBeacon on tab hide / unload — fetch() may be cancelled mid-flight
+// when the document is tearing down, but a beacon is guaranteed-delivered.
+if (typeof window !== 'undefined') {
+    const beaconFlush = () => {
+        for (const stream of Object.keys(QUEUES)) {
+            const entries = QUEUES[stream];
+            if (entries.length === 0)
+                continue;
+            QUEUES[stream] = [];
+            try {
+                const blob = new Blob([JSON.stringify({ stream, entries, sessionId: SESSION_ID })], { type: 'application/json' });
+                navigator.sendBeacon('/api/logs', blob);
+            }
+            catch { /* ignore */ }
+        }
+    };
+    window.addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'hidden')
+            beaconFlush();
+    });
+    window.addEventListener('pagehide', beaconFlush);
+}

package/dist/package/browser/lib/lucide-icon.d.ts

@@ -0,0 +1,5 @@
+import { type LucideIcon } from 'lucide-react';
+/** Resolve only explicit Lucide declarations; emoji and arbitrary text are invalid. */
+export declare function declaredLucideIcon(name?: string): LucideIcon | undefined;
+/** Missing or invalid declarations receive the neutral product fallback. */
+export declare function lucideIconOrBox(name?: string): LucideIcon;

package/dist/package/browser/lib/lucide-icon.js

@@ -0,0 +1,20 @@
+import { Box, icons as LucideIcons, } from 'lucide-react';
+/** kebab / snake / spaced → Lucide registry PascalCase key. */
+function toPascalCase(name) {
+    return name
+        .trim()
+        .split(/[-_\s]+/)
+        .filter(Boolean)
+        .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+        .join('');
+}
+/** Resolve only explicit Lucide declarations; emoji and arbitrary text are invalid. */
+export function declaredLucideIcon(name) {
+    if (!name || !/^[A-Za-z][A-Za-z0-9_\-\s]*$/.test(name.trim()))
+        return undefined;
+    return LucideIcons[toPascalCase(name)];
+}
+/** Missing or invalid declarations receive the neutral product fallback. */
+export function lucideIconOrBox(name) {
+    return declaredLucideIcon(name) ?? Box;
+}

package/dist/package/browser/lib/menu-registry.d.ts

@@ -0,0 +1,113 @@
+/** 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)。
+ */
+/** 菜单顶层大类。品牌菜单 (brand) 在 macOS 原生菜单里通常对应 app 菜单,由 T5 决定放置策略。 */
+export type MenuId = 'brand' | 'file' | 'edit' | 'window' | 'build' | 'select' | 'help' | 'publish';
+export interface MenuItemDef {
+    /** 稳定唯一 id,例:'file.save' / 'window.toggle_chat'。重复注册会抛错。 */
+    id: string;
+    /** 归属菜单顶层大类。 */
+    menu: MenuId;
+    /** 分组键 —— 菜单内的段落分组;渲染器/原生桥根据相邻项的 group 差异插入分隔符。 */
+    group: string;
+    /** 段内排序 (升序)。同 order 用插入顺序破平局 (稳定排序)。 */
+    order: number;
+    /** i18n key —— 渲染时经 `t(labelKey)` 翻译;`serializeMenusForNative` 由调用方
+     *  传入的 `translate` fn 完成翻译,进而不把函数塞进原生契约。 */
+    labelKey: string;
+    /** lucide 图标名 (仅 Web 端渲染;原生菜单不带 icon)。 */
+    icon?: string;
+    /** 要执行的 command bus id;省略 = 该项为**纯文本禁用项** (占位/说明/未来功能)。 */
+    commandId?: string;
+    /** 派发命令时透传给 `commands.execute(commandId, args)` 的参数。 */
+    args?: unknown;
+    /** 键位组合 (canonical),例:'Ctrl+S'。Web 用 prettyCombo 显示,原生转为 accelerator。 */
+    keybinding?: string;
+    /** 动态子菜单的**事实**(供投影/门对账消费,不是行为指南):
+     *  所有动态子项共用的 commandId(如「打开最近」的每一行都是 game.pick)。 */
+    dynamicChildCommandId?: string;
+    /** 动态子项 id 的构成事实:`\${本项id}.\${args[该键]}`(如 file.openRecent.<slug>)。
+     *  有了它,外部调用方无需展开动态列表就能按参数定位到具体子项。 */
+    dynamicChildIdFromArg?: string;
+    /** 可见性谓词 —— 返回 false 时该项从菜单中**隐藏** (原生序列化时直接 drop)。 */
+    when?: () => boolean;
+    /** 显式启用谓词 —— 缺省时默认为 `!!commandId` (无命令则不可点)。 */
+    enabled?: () => boolean;
+    /** 复选态谓词 (Window 面板 toggle 类)。 */
+    checked?: () => boolean;
+    /** 危险/破坏性样式标记 (仅 Web 视觉;原生透传但由平台决定是否使用)。 */
+    danger?: boolean;
+    /** 子菜单 (例:File → Open Recent → ...;Select → By Type → ...)。 */
+    children?: MenuItemDef[];
+    /** 动态子菜单派生器 —— 渲染器在 submenu 展开时同步求值,返回运行时派生的子项
+     *  (例:File → 打开最近 → 按 mtime 排序的最近游戏列表)。与静态 `children`
+     *  互斥优先:声明了本项即视为可展开的 submenu,展开时才求值 (SSOT 仍是注册表,
+     *  子项是纯 derive)。求值必须同步 (数据源需在展开前预取/缓存);仅 Web 端消费,
+     *  原生序列化不含动态子项 (native 菜单结构在 build 时固化)。 */
+    dynamicChildren?: () => MenuItemDef[];
+}
+/** 注册一项菜单 —— 同 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 declare function registerMenuItem(def: MenuItemDef): () => void;
+/** 注册表变更订阅 —— 供 useSyncExternalStore / native bridge rebuild 消费。 */
+export declare function onMenuChange(listener: () => void): () => void;
+/** 取单个菜单的排序后条目 —— 渲染器直接消费。 */
+export declare function snapshotMenu(menu: MenuId): MenuItemDef[];
+/** 取所有菜单的排序后条目,按 MenuId 组织。 */
+export declare function snapshotAllMenus(): Record<MenuId, MenuItemDef[]>;
+export interface NativeMenuItem {
+    /** 对应 MenuItemDef.id。 */
+    id: string;
+    /** **已翻译**的显示文本 (调用方传入的 `translate` fn 完成)。 */
+    label: string;
+    /** 原生 accelerator 字符串,例:'CmdOrCtrl+S' / 'CmdOrCtrl+Shift+Z'。无键位则省略。 */
+    accelerator?: string;
+    /** 已解析的启用态 (when 已 drop 掉隐藏项;enabled 默认 = !!commandId)。 */
+    enabled: boolean;
+    /** 破坏性样式提示 (原样透传,由平台决定是否使用)。 */
+    danger?: boolean;
+    /** 当前项是**新段的第一项**时为 true (菜单内首项除外),原生桥据此插分隔符。 */
+    separatorBefore?: boolean;
+    /** 子菜单 (递归应用同样的翻译/序列化规则)。 */
+    children?: NativeMenuItem[];
+}
+export interface NativeMenu {
+    menu: MenuId;
+    items: NativeMenuItem[];
+}
+/** 序列化全部菜单为原生契约 —— T5 (Tauri 桥) 的唯一入口。契约要点:
+ *    - `when === false` 的项被 drop;
+ *    - `enabled` 缺省时默认 = `!!commandId` (无命令 = 禁用);
+ *    - `labelKey` 走 `translate` 翻译,函数不出墙;
+ *    - `keybinding` 转 native accelerator (Ctrl→CmdOrCtrl,Shift/Alt 保留);
+ *    - 段边界翻成 `separatorBefore=true` (每个菜单首项除外);
+ *    - 输出**完全 JSON 可序列化** (JSON.stringify 无损 roundtrip,无函数残留)。 */
+export declare function serializeMenusForNative(translate: (key: string) => string): NativeMenu[];
+/** 清空注册表 —— 仅供单测 beforeEach 使用。 */
+export declare function __resetMenuRegistryForTest(): void;

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

@@ -0,0 +1,197 @@
+/** 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();
+}

package/dist/package/browser/lib/model-config.d.ts

@@ -0,0 +1,89 @@
+export interface ModelCatalogEntry {
+    id: string;
+    /** ModelSpec 字段透传 —— 调用方按需用 */
+    input?: string[];
+    reasoning?: boolean;
+    contextWindow?: number;
+    maxOutput?: number;
+    defaultTemperature?: number;
+    /** loadModelsCatalog 兜底字段（盘上条目不规整时附原 raw） */
+    spec?: unknown;
+    /** 元数据来源(与 `live` 正交):'disk' = 命中 ~/.forgeax/key/models.json 的富元
+     *  数据;'live' = 只在 /v1/models 上、用默认 spec 兜底;'driver' = rented CLI
+     *  driver catalog。UI 不再据 disk/live 加徽章。 */
+    source?: 'disk' | 'live' | 'driver';
+    /** 该 id 当前是否由 live proxy 提供。live 权威时整份列表统一为 true(offline 回退
+     *  到盘时统一 false)——UI 的 live 徽章据此「要么全有要么全无」,不再让有本地元数
+     *  据的行看起来像非 live。 */
+    live?: boolean;
+    /** Present when source='driver'. Keeps rented-CLI catalogs separate from gateway models. */
+    driverId?: string;
+    /** Human-facing label for the driver group. */
+    driverLabel?: string;
+    /** Rented CLIs report token usage but no local $ cost metering. */
+    costMetering?: 'none' | 'gateway';
+    /** 用户在 Settings → Models 里隐藏的模型不会出现在 Composer 单选下拉里。
+     *  inline (Settings) + multi (ModelLab) 仍展示全量,通过眼睛 icon 切换。 */
+    hidden?: boolean;
+}
+export interface AgentModelState {
+    sid: string;
+    agentPath: string;
+    /** chain[0] ?? null —— UI 只想拿"当前生效哪个"读它 */
+    selected: string | null;
+    /** 永远归一成 string[]（盘上是 string 也展开成 1 元数组） */
+    chain: string[];
+    /** 盘上原值（string | string[] | null）—— 想区分"用户写了啥"用它 */
+    raw: string | string[] | null;
+}
+/** Catalog 来自 `~/.forgeax/key/models.json`（disk）与 LiteLLM `/v1/models`（live）
+ *  的合并：live 权威时展示集合即 live 那份，disk 只静默补元数据。
+ *  返回顺序由 server 端按「强度」排好（claude 族最前 → 版本号降序 → tier），
+ *  前端不再二次排序，直接平铺渲染。providerId 非空时返回对应内核的
+ *  driver-scoped catalog。 */
+export declare function listModels(providerId?: string | null): Promise<ModelCatalogEntry[]>;
+/** 内核目录回退链(env → kernel.listModels → last-known → static → none)
+ *  的命中层元数据。UI 用它渲染空态("目录不可用",而不是假列表)和
+ *  「缓存/预置」徽章。gateway 路径(providerId 为空)没有这段。 */
+export interface CatalogDriverMeta {
+    id: string;
+    source: 'env' | 'kernel' | 'last-known' | 'static' | 'none' | string;
+    error?: string;
+    ids: number;
+    cached?: boolean;
+}
+export interface ModelCatalogWithMeta {
+    models: ModelCatalogEntry[];
+    driver?: CatalogDriverMeta;
+}
+/** listModels + driver 元数据透传(内核目录路径需要;见 CatalogDriverMeta)。 */
+export declare function listModelsWithMeta(providerId?: string | null): Promise<ModelCatalogWithMeta>;
+/** Full `list_models` payload including the live-probe summary. Use this when
+ *  connectivity must NOT treat disk-only fallback as success (onboarding). */
+export declare function listModelsWithLive(providerId?: string | null): Promise<{
+    models: ModelCatalogEntry[];
+    live: {
+        source: string;
+        error?: string;
+        ids: number;
+    };
+}>;
+/** 读 agent.json::models.model —— **不**经 AGENT_DEFAULTS deep-merge，
+ *  能区分"用户没配"（chain=[]、raw=null）和"显式空 chain"（chain=[]、raw=[]）。 */
+export declare function getAgentModel(sid: string, agentPath: string): Promise<AgentModelState>;
+/** 写 agent.json models.model = string[]（单模型也写成 ["MODEL"]）。
+ *  已 running 的 agent server 端会自动 controlAgent("restart") 重读盘。 */
+export declare function setAgentModels(sid: string, agentPath: string, models: string[]): Promise<{
+    selected: string;
+    chain: string[];
+    restarted: boolean;
+}>;
+/** Toggle a model's "show in Composer picker" visibility. Persists to
+ *  ~/.forgeax/key/models-hidden.json on the server side. Caller should refresh
+ *  the catalog (useModelCatalog.refresh) after a successful toggle so the
+ *  single-mode dropdown re-filters. */
+export declare function setModelHidden(id: string, hidden: boolean): Promise<{
+    id: string;
+    hidden: boolean;
+    totalHidden: number;
+}>;

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

@@ -0,0 +1,72 @@
+// @desc Frontend client for `builtin/commands/models.ts` —— list / get / set
+//
+// 三个 helper 一律走 `/api/commands/*` 走 transport.ts 的 `{ args }` 协议。统一在
+// 这里抛 server 端的 `result.error`，调用方只需 try/catch 即可。
+//
+// 与 `lib/forgeax-bridge.ts:listSessionAgents` 同款套路（POST query+args）。
+async function callQuery(name, args) {
+    const r = await fetch(`/api/commands/${name}/query`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ args }),
+    });
+    // transport.ts 在 result.ok=false 时仍返 500 + body —— 都按 json 解析。
+    const j = (await r.json());
+    if (!j.result?.ok)
+        throw new Error(j.result?.error ?? `${name} failed (HTTP ${r.status})`);
+    return j.result.data;
+}
+async function callExecute(name, args) {
+    const r = await fetch(`/api/commands/${name}/execute`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ args }),
+    });
+    const j = (await r.json());
+    if (!j.result?.ok)
+        throw new Error(j.result?.error ?? `${name} failed (HTTP ${r.status})`);
+    return j.result.data;
+}
+/** Catalog 来自 `~/.forgeax/key/models.json`（disk）与 LiteLLM `/v1/models`（live）
+ *  的合并：live 权威时展示集合即 live 那份，disk 只静默补元数据。
+ *  返回顺序由 server 端按「强度」排好（claude 族最前 → 版本号降序 → tier），
+ *  前端不再二次排序，直接平铺渲染。providerId 非空时返回对应内核的
+ *  driver-scoped catalog。 */
+export async function listModels(providerId) {
+    return (await listModelsWithMeta(providerId)).models;
+}
+/** listModels + driver 元数据透传(内核目录路径需要;见 CatalogDriverMeta)。 */
+export async function listModelsWithMeta(providerId) {
+    const args = providerId ? [providerId] : [];
+    const data = await callQuery("list_models", args);
+    return { models: data.models ?? [], driver: data.driver };
+}
+/** Full `list_models` payload including the live-probe summary. Use this when
+ *  connectivity must NOT treat disk-only fallback as success (onboarding). */
+export async function listModelsWithLive(providerId) {
+    const args = providerId ? [providerId] : [];
+    const data = await callQuery("list_models", args);
+    return {
+        models: data.models ?? [],
+        live: data.live ?? { source: "disabled", ids: 0 },
+    };
+}
+/** 读 agent.json::models.model —— **不**经 AGENT_DEFAULTS deep-merge，
+ *  能区分"用户没配"（chain=[]、raw=null）和"显式空 chain"（chain=[]、raw=[]）。 */
+export async function getAgentModel(sid, agentPath) {
+    return callQuery("get_agent_model", [sid, agentPath]);
+}
+/** 写 agent.json models.model = string[]（单模型也写成 ["MODEL"]）。
+ *  已 running 的 agent server 端会自动 controlAgent("restart") 重读盘。 */
+export async function setAgentModels(sid, agentPath, models) {
+    if (models.length === 0)
+        throw new Error("setAgentModels: at least one model required");
+    return callExecute("set_agent_models", [sid, agentPath, ...models]);
+}
+/** Toggle a model's "show in Composer picker" visibility. Persists to
+ *  ~/.forgeax/key/models-hidden.json on the server side. Caller should refresh
+ *  the catalog (useModelCatalog.refresh) after a successful toggle so the
+ *  single-mode dropdown re-filters. */
+export async function setModelHidden(id, hidden) {
+    return callExecute("set_model_hidden", [id, hidden ? "1" : "0"]);
+}

package/dist/package/browser/lib/model-prefs.d.ts

@@ -0,0 +1,5 @@
+/** The model the user last hand-picked for this provider, or null if none. */
+export declare function getLastModel(catalogProviderId: string | null): string | null;
+/** Record a HAND-PICKED model for this provider (called from the composer's
+ *  model picker onChange — never from a provider-switch reset). */
+export declare function recordLastModel(catalogProviderId: string | null, modelId: string): void;