@forgeax/interface 0.4.1

package/dist/package/node/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.js';
+import { warmRecentGames } from './recent-games.js';
+import { onMenuChange, serializeMenusForNative, snapshotAllMenus, } from './menu-registry.js';
+// ─── 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/node/lib/page-tab-icons.js

@@ -0,0 +1,64 @@
+/**
+ * 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 { Box, Clapperboard, File, FileCode2, FileText, Image, Music, Package, Puzzle, Settings2, Type, } from 'lucide-react';
+const ICON_BY_KIND = {
+    scene: Clapperboard,
+    model: Box,
+    image: Image,
+    audio: Music,
+    font: Type,
+    pack: Package,
+    code: FileCode2,
+    doc: FileText,
+    config: Settings2,
+    plugin: Puzzle,
+};
+const EXT_KIND = [
+    [['ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs', 'py'], 'code'],
+    [['md', 'markdown', 'txt'], 'doc'],
+    [['png', 'jpg', 'jpeg', 'webp', 'gif', 'svg', 'ico', 'hdr'], 'image'],
+    [['mp3', 'wav', 'ogg', 'flac', 'aac', 'm4a', 'opus'], 'audio'],
+    [['glb', 'gltf', 'fbx'], 'model'],
+    [['ttf', 'otf', 'woff2'], 'font'],
+];
+/** Derive the content family from a resource path, else from the page type id. */
+export function pageKindOf(input) {
+    const path = (input.resource?.displayPath ?? input.resource?.uri ?? '').toLowerCase();
+    if (path) {
+        if (path.endsWith('.scene.json'))
+            return 'scene';
+        if (path.endsWith('.pack.json'))
+            return path.includes('scene') ? 'scene' : 'pack';
+        const ext = path.split(/[?#]/u, 1)[0]?.split('.').pop() ?? '';
+        for (const [exts, kind] of EXT_KIND)
+            if (exts.includes(ext))
+                return kind;
+        if (path.endsWith('forge.json') || path.endsWith('package.json'))
+            return 'config';
+    }
+    const id = input.typeId.toLowerCase();
+    for (const kind of Object.keys(ICON_BY_KIND)) {
+        if (id.includes(kind))
+            return kind;
+    }
+    if (id.includes('scene') || id.includes('level'))
+        return 'scene';
+    if (id.includes('extension') || id.includes('plugin'))
+        return 'plugin';
+    return 'config';
+}
+/** Resolve the Lucide icon for a page. Never returns undefined. */
+export function iconForPage(input) {
+    const path = (input.resource?.displayPath ?? input.resource?.uri ?? '').toLowerCase();
+    const kind = pageKindOf(input);
+    // A resource-less, unclassifiable page falls back to a neutral file glyph
+    // rather than a misleading "config" icon.
+    if (!path && kind === 'config' && !input.typeId.toLowerCase().includes('config'))
+        return File;
+    return ICON_BY_KIND[kind];
+}

package/dist/package/node/lib/panel-tab-icons.js

@@ -0,0 +1,49 @@
+/**
+ * Unified Lucide mapping for dockview panel tabs — the SSOT for "what icon does
+ * this dock panel show". Mirrors the `iconForPage` pattern: one pure, react-free
+ * resolver keyed by the bare panel id, so the dock
+ * tab, the layout menu, and the in-panel header never drift on icon semantics.
+ * Follow `DESIGN-SYSTEM.md` §icon rules — no ad-hoc per-file lucide imports in
+ * consumers, no emoji.
+ *
+ * Panel ids come in two shapes: static/injected ids (`viewport`, `chat`, …) and
+ * editor ids that dockview prefixes with `ep:` (`ep:hierarchy`). Callers may pass
+ * either — the `ep:` prefix is stripped before lookup.
+ */
+import { Activity, Bell, Bot, Box, Flag, FolderTree, Grid3x3, History, Info, LayoutDashboard, ListChecks, ListTree, MessageSquare, Monitor, Package, Puzzle, Rocket, SlidersHorizontal, SquareTerminal, Wrench, } from 'lucide-react';
+/** Bare-panel-id → Lucide glyph. Keys are ids WITHOUT the `ep:` dock prefix. */
+const ICON_BY_PANEL = {
+    // interface static panels (panelRegistry.tsx)
+    tools: Wrench,
+    main: LayoutDashboard,
+    viewport: Monitor,
+    chat: MessageSquare,
+    agents: Bot,
+    files: FolderTree,
+    console: SquareTerminal,
+    telemetry: Activity,
+    info: Info,
+    checkpoints: Flag,
+    events: Bell,
+    // editor business panels (EDITOR_PANELS, injected as ep:*)
+    hierarchy: ListTree,
+    inspector: SlidersHorizontal,
+    assets: Package,
+    history: History,
+    capabilities: Puzzle,
+    launcher: Rocket,
+    'asset-properties': ListChecks,
+    'mesh-slots': Grid3x3,
+};
+/** Normalize a dock panel id to its bare form (drop the `ep:` editor prefix). */
+export function barePanelId(id) {
+    return id.startsWith('ep:') ? id.slice(3) : id;
+}
+/**
+ * Resolve the Lucide icon for a dock panel id. Never returns undefined — an
+ * unmapped id (page-mode document panels, marketplace-injected page panels)
+ * falls back to a neutral `Box` glyph rather than nothing.
+ */
+export function iconForDockPanel(id) {
+    return ICON_BY_PANEL[barePanelId(id)] ?? Box;
+}

package/dist/package/node/lib/passive-feedback.js

@@ -0,0 +1,171 @@
+export const PASSIVE_FEEDBACK_EVENT = 'forgeax:passive-feedback';
+export const PASSIVE_FEEDBACK_RECOVERED_EVENT = 'forgeax:passive-feedback-recovered';
+const PRESETS = [
+    {
+        exceptionKey: 'save-failure',
+        codes: ['save-serialization-failed', 'save-write-failed', 'save-pack-validation-failed'],
+        titleKey: 'feedback.passive.incidents.save',
+        actionKey: 'feedback.passive.actions.retrySave',
+        placement: 'center',
+        recovery: { kind: 'command', commandId: 'editor.save' },
+    },
+    {
+        exceptionKey: 'play-failure',
+        codes: ['play-assemble-failed', 'play-save-failed', 'play-bootstrap-failed'],
+        titleKey: 'feedback.passive.incidents.play',
+        actionKey: 'feedback.passive.actions.retryPlay',
+        placement: 'center',
+        recovery: { kind: 'command', commandId: 'editor.play' },
+    },
+    {
+        exceptionKey: 'gpu-device-lost',
+        codes: ['device-lost', 'context-lost', 'webgpu-init-failed'],
+        titleKey: 'feedback.passive.incidents.gpu',
+        actionKey: 'feedback.passive.actions.reloadPreview',
+        placement: 'center',
+        recovery: { kind: 'command', commandId: 'editor.restartPreview' },
+    },
+    {
+        exceptionKey: 'renderer-crash',
+        codes: [
+            'renderer-process-terminated',
+            'renderer-crash',
+            'renderer-error',
+            'renderer-not-ready',
+            'renderer-provenance-unavailable',
+            'app-system-update-failed',
+        ],
+        titleKey: 'feedback.passive.incidents.renderer',
+        actionKey: 'feedback.passive.actions.restartRenderer',
+        placement: 'center',
+        recovery: { kind: 'command', commandId: 'editor.restartPreview' },
+    },
+    {
+        exceptionKey: 'runtime-disconnected',
+        codes: ['runtime-unavailable', 'runtime-disconnected', 'viewport-runtime-disconnected'],
+        titleKey: 'feedback.passive.incidents.runtime',
+        actionKey: 'feedback.passive.actions.reconnectRuntime',
+        placement: 'center',
+        recovery: { kind: 'command', commandId: 'editor.restartPreview' },
+    },
+    {
+        exceptionKey: 'agent-unresponsive',
+        codes: ['ui.stall', 'agent_crash', 'agent-crash'],
+        titleKey: 'feedback.passive.incidents.agent',
+        actionKey: 'feedback.passive.actions.reconnectAgent',
+        placement: 'chat',
+        recovery: { kind: 'command', commandId: 'session.reconnect' },
+    },
+    {
+        exceptionKey: 'main-thread-stall',
+        codes: ['main-thread-stall'],
+        titleKey: 'feedback.passive.incidents.mainThread',
+        actionKey: 'feedback.passive.actions.feedbackContinue',
+        placement: 'corner',
+        recovery: { kind: 'none' },
+    },
+    {
+        exceptionKey: 'build-failures',
+        codes: ['vite:error', 'build-failed', 'build-error'],
+        titleKey: 'feedback.passive.incidents.build',
+        actionKey: 'feedback.passive.actions.retryBuild',
+        placement: 'corner',
+        recovery: { kind: 'command', commandId: 'editor.restartPreview' },
+        threshold: 3,
+        withinMs: 30_000,
+    },
+    {
+        exceptionKey: 'uncaught-errors',
+        codes: ['window-error', 'unhandled-rejection'],
+        titleKey: 'feedback.passive.incidents.uncaught',
+        actionKey: 'feedback.passive.actions.reloadStudio',
+        placement: 'corner',
+        recovery: { kind: 'reload-page' },
+        threshold: 3,
+        withinMs: 10_000,
+    },
+];
+function matchesPreset(preset, signal) {
+    const code = signal.code.trim().toLowerCase();
+    const message = signal.message.toLowerCase();
+    if (preset.codes.some((candidate) => code === candidate || message.includes(candidate)))
+        return true;
+    // Production errors are structured families, not a closed list. Keep the
+    // document's canonical codes above while accepting concrete owner variants.
+    if (preset.exceptionKey === 'save-failure') {
+        return /^save-[a-z0-9-]*(?:failed|failure)$/.test(code);
+    }
+    if (preset.exceptionKey === 'play-failure') {
+        return /^play-[a-z0-9-]*failed$/.test(code);
+    }
+    if (preset.exceptionKey === 'renderer-crash') {
+        return /^renderer-[a-z0-9-]*(?:failed|failure|error|crash|terminated|unavailable)$/.test(code);
+    }
+    if (preset.exceptionKey === 'runtime-disconnected') {
+        return /^(?:viewport-)?runtime-[a-z0-9-]*(?:disconnected|unavailable|unreachable)$/.test(code);
+    }
+    if (preset.exceptionKey === 'build-failures') {
+        return code === 'vag-console' && /^\[vite build\]/i.test(signal.message.trim());
+    }
+    return false;
+}
+function diagnosticParts(message) {
+    const lines = message.split('\n').map((line) => line.trim()).filter(Boolean);
+    const summary = lines[0] || message.trim() || 'Unknown failure';
+    return lines.length > 1 ? { summary, stack: lines.join('\n') } : { summary };
+}
+export function createPassiveFeedbackClassifier() {
+    const occurrences = new Map();
+    return {
+        ingest(signal) {
+            const preset = PRESETS.find((candidate) => matchesPreset(candidate, signal));
+            if (!preset)
+                return null;
+            const now = signal.ts ?? Date.now();
+            const threshold = preset.threshold ?? 1;
+            if (threshold > 1) {
+                const since = now - (preset.withinMs ?? 10_000);
+                const recent = [...(occurrences.get(preset.exceptionKey) ?? []), now]
+                    .filter((ts) => ts >= since);
+                occurrences.set(preset.exceptionKey, recent);
+                if (recent.length < threshold)
+                    return null;
+                occurrences.set(preset.exceptionKey, []);
+            }
+            return {
+                exceptionKey: preset.exceptionKey,
+                titleKey: preset.titleKey,
+                actionKey: preset.actionKey,
+                placement: preset.placement,
+                recovery: preset.recovery,
+                ...(signal.scope ? { scope: { ...signal.scope } } : {}),
+                ...diagnosticParts(signal.message),
+            };
+        },
+    };
+}
+export function reportPassiveFeedbackSignal(signal) {
+    if (typeof window === 'undefined')
+        return;
+    window.dispatchEvent(new CustomEvent(PASSIVE_FEEDBACK_EVENT, { detail: signal }));
+}
+/**
+ * Resolves a previously reported incident without conflating two agents or
+ * sessions that happen to share the same exception key. A missing resolution
+ * scope intentionally means "all scopes" for callers that only have a global
+ * recovery fact.
+ */
+export function matchesPassiveFeedbackScope(incidentScope, resolutionScope) {
+    if (!resolutionScope)
+        return true;
+    if (resolutionScope.sid !== undefined && resolutionScope.sid !== incidentScope?.sid)
+        return false;
+    if (resolutionScope.agentId !== undefined && resolutionScope.agentId !== incidentScope?.agentId)
+        return false;
+    return true;
+}
+export function reportPassiveFeedbackRecovery(resolution) {
+    if (typeof window === 'undefined')
+        return;
+    window.dispatchEvent(new CustomEvent(PASSIVE_FEEDBACK_RECOVERED_EVENT, { detail: resolution }));
+}

package/dist/package/node/lib/perception-stream.js

@@ -0,0 +1,42 @@
+/** perception-stream — interface side of the感知接地 (R5/M8) take-data round-trip.
+ *
+ *  The orchestration layer (server) asks the running game for ground truth via
+ *  the `query_world` / `capture_frame` tools. That HTTP-回打 `/:sid/perception-query`,
+ *  which publishes a `perception:query` event onto the session EventBus → WS.
+ *
+ *  This module is the interface seam (mirrors lib/file-activity-stream.ts): it
+ *  subscribes to `onSessionEvent`, picks `perception:query`, and re-emits it as a
+ *  DOM `CustomEvent('forgeax:perception-query')`. The preview surface
+ *  (PlaySurface, editor submodule) owns the game iframe + the reply POST, so it
+ *  listens for that window event and does the postMessage → reply. Keeping the
+ *  relay on `window` decouples the editor surface from interface internals (it
+ *  never imports forgeax-bridge).
+ *
+ *  These events have no chat representation — session-stream's dispatch skips
+ *  `perception:*` (so they're never rendered as system messages). */
+import { getSessionClient } from '../store-parts/session-client.js';
+export const PERCEPTION_QUERY_EVENT = 'forgeax:perception-query';
+function dispatchPerception(evt) {
+    if (evt.event.type !== 'perception:query')
+        return;
+    const p = evt.event.payload;
+    if (typeof p.reqId !== 'string')
+        return;
+    const detail = {
+        sid: evt.sid,
+        reqId: p.reqId,
+        kind: p.kind === 'frame' ? 'frame' : 'world',
+        query: p.query,
+    };
+    try {
+        window.dispatchEvent(new CustomEvent(PERCEPTION_QUERY_EVENT, { detail }));
+    }
+    catch {
+        /* SSR / no window — ignore */
+    }
+}
+/** Wired in main.tsx alongside the other stream subscriptions. Idempotent —
+ *  same handler key, HMR-safe. */
+export function subscribePerceptionStream() {
+    getSessionClient().onSessionEvent('perception', dispatchPerception);
+}

package/dist/package/node/lib/platform/index.js

@@ -0,0 +1,13 @@
+/**
+ * Platform layer — the single seam between the platform-agnostic React app and
+ * the host it runs in (Tauri desktop shell vs plain browser / web-server form).
+ *
+ * Import from here, never reach into '@tauri-apps/*' directly from components.
+ */
+export { isTauri, platformRuntime, } from './runtime.js';
+export { getShellAdapter } from './shell-adapter.js';
+export { getWindowManager } from './window-manager.js';
+export { getSurfaceWindowingController, VIEWPORT_CARRIER_WILL_DETACH, } from './surface-windowing.js';
+export { useFloatingSurfaces } from './use-surface-windowing.js';
+export { surfaceKey, surfaceWindowLabel, encodeSurfaceQuery, decodeSurfaceFromLocation, } from '@forgeax/app-shell/window';
+export { encodeSurfaceWindowQuery, surfaceWindowUrl, } from './surface.js';

package/dist/package/node/lib/platform/runtime.js

@@ -0,0 +1,42 @@
+/**
+ * Runtime detection — is this code running inside the Tauri desktop shell, or
+ * a plain browser (the web-server form, e.g. http://9.208:18920)?
+ *
+ * 这是"一套代码,两种形态"的开关。检测方式与 gameclaw_pet 的 ShellAdapter
+ * 一致:Tauri 会在 webview 里注入 `__TAURI_INTERNALS__`。所有原生能力
+ * (窗口控制、托盘、多窗口)都 gate 在 `isTauri()` 之后,浏览器形态全 no-op,
+ * 现有 web 流程零回归。
+ *
+ * Tauri 的 JS API 通过**动态 import** 懒加载:浏览器形态永远不会走到那些
+ * 分支,所以那个 chunk 永远不会被 fetch,纯 web bundle 无额外成本。
+ */
+export function isTauri() {
+    return typeof window !== 'undefined' && '__TAURI_INTERNALS__' in window;
+}
+export function platformRuntime() {
+    return isTauri() ? 'tauri' : 'web';
+}
+let _webviewWindow = null;
+let _event = null;
+let _window = null;
+export async function loadWebviewWindowApi() {
+    if (!isTauri())
+        return null;
+    if (!_webviewWindow)
+        _webviewWindow = await import('@tauri-apps/api/webviewWindow');
+    return _webviewWindow;
+}
+export async function loadEventApi() {
+    if (!isTauri())
+        return null;
+    if (!_event)
+        _event = await import('@tauri-apps/api/event');
+    return _event;
+}
+export async function loadWindowApi() {
+    if (!isTauri())
+        return null;
+    if (!_window)
+        _window = await import('@tauri-apps/api/window');
+    return _window;
+}

package/dist/package/node/lib/platform/shell-adapter.js

@@ -0,0 +1,74 @@
+/**
+ * ShellAdapter — OS-window / shell capabilities, abstracted over the two
+ * runtimes. Mirrors gameclaw_pet/src/shell/ShellAdapter.ts: the React app only
+ * ever talks to this interface, so the SAME components run unchanged in the
+ * browser (web-server form, every method a no-op) and inside Tauri (real
+ * native calls).
+ *
+ * Keep this surface small and capability-oriented — add a method only when a
+ * component actually needs it, and always provide a sane browser fallback.
+ */
+import { isTauri, platformRuntime, loadWebviewWindowApi, loadWindowApi, } from './runtime.js';
+let _adapter = null;
+export function getShellAdapter() {
+    if (!_adapter)
+        _adapter = isTauri() ? createTauriAdapter() : createBrowserAdapter();
+    return _adapter;
+}
+function createTauriAdapter() {
+    return {
+        runtime: 'tauri',
+        isTauri: () => true,
+        async getPlatform() {
+            try {
+                const os = await import('@tauri-apps/plugin-os');
+                return os.platform();
+            }
+            catch {
+                return 'unknown';
+            }
+        },
+        async startDragging() {
+            const mod = await loadWebviewWindowApi();
+            await mod?.getCurrentWebviewWindow().startDragging();
+        },
+        async minimizeWindow() {
+            const mod = await loadWebviewWindowApi();
+            await mod?.getCurrentWebviewWindow().minimize();
+        },
+        async toggleMaximizeWindow() {
+            const mod = await loadWebviewWindowApi();
+            await mod?.getCurrentWebviewWindow().toggleMaximize();
+        },
+        async closeWindow() {
+            const mod = await loadWebviewWindowApi();
+            await mod?.getCurrentWebviewWindow().close();
+        },
+        async setAlwaysOnTop(onTop) {
+            const mod = await loadWindowApi();
+            const wvMod = await loadWebviewWindowApi();
+            // setAlwaysOnTop lives on the Window handle in tauri 2.
+            if (wvMod)
+                await wvMod.getCurrentWebviewWindow().setAlwaysOnTop(onTop);
+            else
+                void mod;
+        },
+    };
+}
+function createBrowserAdapter() {
+    // Every native op is a no-op in the browser; the web app behaves exactly as
+    // it does today (the user manages the browser window themselves).
+    const noop = async () => { };
+    return {
+        runtime: platformRuntime(),
+        isTauri: () => false,
+        async getPlatform() {
+            return 'browser';
+        },
+        startDragging: noop,
+        minimizeWindow: noop,
+        toggleMaximizeWindow: noop,
+        closeWindow: noop,
+        setAlwaysOnTop: noop,
+    };
+}

package/dist/package/node/lib/platform/surface-windowing.js

@@ -0,0 +1,16 @@
+import { createSurfaceWindowingController } from '@forgeax/app-shell/window';
+import { getWindowManager } from './window-manager.js';
+export const VIEWPORT_CARRIER_WILL_DETACH = 'forgeax:viewport-carrier-will-detach';
+let controller;
+/** Product adapter: App Shell owns state/transactions; Interface owns this event. */
+export function getSurfaceWindowingController() {
+    controller ??= createSurfaceWindowingController({
+        manager: getWindowManager(),
+        beforeDetach: (surface) => {
+            if (surface.kind === 'panel' && surface.id === 'viewport') {
+                window.dispatchEvent(new CustomEvent(VIEWPORT_CARRIER_WILL_DETACH));
+            }
+        },
+    });
+    return controller;
+}

package/dist/package/node/lib/platform/surface.js

@@ -0,0 +1,27 @@
+import { encodeSurfaceQuery, } from '@forgeax/app-shell/window';
+export { decodeSurfaceFromLocation, encodeSurfaceQuery, surfaceKey, surfaceWindowLabel, } from '@forgeax/app-shell/window';
+/** Add the fenced Runtime identity only to the Viewport surface. Business panels remain ordinary shell pages. */
+export function encodeSurfaceWindowQuery(d, carrierKind, generation = Date.now(), hostOrigin = typeof window !== 'undefined' ? window.location.origin : 'http://localhost') {
+    const params = new URLSearchParams(encodeSurfaceQuery(d));
+    if (d.kind === 'panel' && (d.id === 'viewport' || d.id === 'edit' || d.id === 'preview')) {
+        params.set('runtimeId', 'edit-runtime');
+        params.set('runtimeGeneration', String(generation));
+        params.set('carrierId', `${carrierKind}-${generation}`);
+        params.set('carrierKind', carrierKind);
+        params.set('hostOrigin', hostOrigin);
+    }
+    return params.toString();
+}
+/** Build the carrier URL from the page that owns the Runtime lease.
+ *
+ * Tauri treats a relative `index.html?...` URL as a bundled app asset even when
+ * the main WebView was navigated to a remote sidecar. Keeping the current
+ * origin and pathname makes the detached WebView load the same frontend and
+ * preserves same-origin Runtime transport.
+ */
+export function surfaceWindowUrl(d, carrierKind, currentHref = typeof window !== 'undefined' ? window.location.href : 'http://localhost/', generation = Date.now()) {
+    const url = new URL(currentHref);
+    url.search = encodeSurfaceWindowQuery(d, carrierKind, generation, url.origin);
+    url.hash = '';
+    return url.href;
+}

package/dist/package/node/lib/platform/use-surface-windowing.js

@@ -0,0 +1,6 @@
+import { useSyncExternalStore } from 'react';
+import { getSurfaceWindowingController } from './surface-windowing.js';
+export function useFloatingSurfaces() {
+    const controller = getSurfaceWindowingController();
+    return useSyncExternalStore(controller.onChange, controller.snapshot, controller.snapshot);
+}