@forgeax/interface 0.4.1

package/dist/package/browser/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/browser/lib/panel-tab-icons.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 { type LucideIcon } from 'lucide-react';
+/** Normalize a dock panel id to its bare form (drop the `ep:` editor prefix). */
+export declare function barePanelId(id: string): string;
+/**
+ * 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 declare function iconForDockPanel(id: string): LucideIcon;

package/dist/package/browser/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/browser/lib/passive-feedback.d.ts

@@ -0,0 +1,50 @@
+export declare const PASSIVE_FEEDBACK_EVENT = "forgeax:passive-feedback";
+export declare const PASSIVE_FEEDBACK_RECOVERED_EVENT = "forgeax:passive-feedback-recovered";
+export type PassiveFeedbackPlacement = 'corner' | 'center' | 'chat';
+export type PassiveFeedbackRecovery = {
+    kind: 'none';
+} | {
+    kind: 'command';
+    commandId: string;
+} | {
+    kind: 'reload-page';
+};
+/** Identifies the turn that produced a per-attempt passive feedback card. */
+export interface PassiveFeedbackScope {
+    sid?: string;
+    agentId?: string;
+}
+export interface PassiveFeedbackSignal {
+    code: string;
+    message: string;
+    source?: string;
+    ts?: number;
+    scope?: PassiveFeedbackScope;
+}
+export interface PassiveFeedbackIncident {
+    exceptionKey: string;
+    titleKey: string;
+    actionKey: string;
+    summary: string;
+    stack?: string;
+    placement: PassiveFeedbackPlacement;
+    recovery: PassiveFeedbackRecovery;
+    scope?: PassiveFeedbackScope;
+}
+export interface PassiveFeedbackResolution {
+    exceptionKey: string;
+    scope?: PassiveFeedbackScope;
+}
+export interface PassiveFeedbackClassifier {
+    ingest(signal: PassiveFeedbackSignal): PassiveFeedbackIncident | null;
+}
+export declare function createPassiveFeedbackClassifier(): PassiveFeedbackClassifier;
+export declare function reportPassiveFeedbackSignal(signal: PassiveFeedbackSignal): void;
+/**
+ * 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 declare function matchesPassiveFeedbackScope(incidentScope: PassiveFeedbackScope | undefined, resolutionScope: PassiveFeedbackScope | undefined): boolean;
+export declare function reportPassiveFeedbackRecovery(resolution: PassiveFeedbackResolution): void;

package/dist/package/browser/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/browser/lib/perception-stream.d.ts

@@ -0,0 +1,27 @@
+/** 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). */
+/** Shape carried on the `forgeax:perception-query` CustomEvent detail. */
+export interface PerceptionQueryDetail {
+    sid: string;
+    reqId: string;
+    kind: 'world' | 'frame';
+    query?: unknown;
+}
+export declare const PERCEPTION_QUERY_EVENT = "forgeax:perception-query";
+/** Wired in main.tsx alongside the other stream subscriptions. Idempotent —
+ *  same handler key, HMR-safe. */
+export declare function subscribePerceptionStream(): void;

package/dist/package/browser/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';
+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/browser/lib/platform/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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, type PlatformRuntime, } from './runtime';
+export { getShellAdapter, type ShellAdapter } from './shell-adapter';
+export { getWindowManager } from './window-manager';
+export { getSurfaceWindowingController, VIEWPORT_CARRIER_WILL_DETACH, } from './surface-windowing';
+export { useFloatingSurfaces } from './use-surface-windowing';
+export { type WindowManager, type DetachWindowOptions, } from '@forgeax/app-shell/window';
+export { type DetachedWindowCapability, type DetachedWindowTarget, type SurfaceDescriptor, type SurfaceKind, type SurfacePane, surfaceKey, surfaceWindowLabel, encodeSurfaceQuery, decodeSurfaceFromLocation, } from '@forgeax/app-shell/window';
+export { type DetachedViewportCarrierKind, encodeSurfaceWindowQuery, surfaceWindowUrl, } from './surface';

package/dist/package/browser/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';
+export { getShellAdapter } from './shell-adapter';
+export { getWindowManager } from './window-manager';
+export { getSurfaceWindowingController, VIEWPORT_CARRIER_WILL_DETACH, } from './surface-windowing';
+export { useFloatingSurfaces } from './use-surface-windowing';
+export { surfaceKey, surfaceWindowLabel, encodeSurfaceQuery, decodeSurfaceFromLocation, } from '@forgeax/app-shell/window';
+export { encodeSurfaceWindowQuery, surfaceWindowUrl, } from './surface';

package/dist/package/browser/lib/platform/runtime.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 type PlatformRuntime = 'tauri' | 'web';
+export declare function isTauri(): boolean;
+export declare function platformRuntime(): PlatformRuntime;
+type WebviewWindowMod = typeof import('@tauri-apps/api/webviewWindow');
+type EventMod = typeof import('@tauri-apps/api/event');
+type WindowMod = typeof import('@tauri-apps/api/window');
+export declare function loadWebviewWindowApi(): Promise<WebviewWindowMod | null>;
+export declare function loadEventApi(): Promise<EventMod | null>;
+export declare function loadWindowApi(): Promise<WindowMod | null>;
+export {};

package/dist/package/browser/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/browser/lib/platform/shell-adapter.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 { type PlatformRuntime } from './runtime';
+export interface ShellAdapter {
+    readonly runtime: PlatformRuntime;
+    isTauri(): boolean;
+    /** 'macos' | 'windows' | 'linux' | 'browser'. */
+    getPlatform(): Promise<string>;
+    /** Begin an OS window drag (for custom/decoration-less title bars). */
+    startDragging(): Promise<void>;
+    minimizeWindow(): Promise<void>;
+    toggleMaximizeWindow(): Promise<void>;
+    closeWindow(): Promise<void>;
+    setAlwaysOnTop(onTop: boolean): Promise<void>;
+}
+export declare function getShellAdapter(): ShellAdapter;

package/dist/package/browser/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';
+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/browser/lib/platform/surface-windowing.d.ts

@@ -0,0 +1,4 @@
+import { createSurfaceWindowingController } from '@forgeax/app-shell/window';
+export declare const VIEWPORT_CARRIER_WILL_DETACH: "forgeax:viewport-carrier-will-detach";
+/** Product adapter: App Shell owns state/transactions; Interface owns this event. */
+export declare function getSurfaceWindowingController(): ReturnType<typeof createSurfaceWindowingController>;

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

@@ -0,0 +1,16 @@
+import { createSurfaceWindowingController } from '@forgeax/app-shell/window';
+import { getWindowManager } from './window-manager';
+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/browser/lib/platform/surface.d.ts

@@ -0,0 +1,13 @@
+import { type SurfaceDescriptor } from '@forgeax/app-shell/window';
+export { decodeSurfaceFromLocation, encodeSurfaceQuery, surfaceKey, surfaceWindowLabel, type DetachedWindowCapability, type DetachedWindowTarget, type SurfaceDescriptor, type SurfaceKind, type SurfacePane, } from '@forgeax/app-shell/window';
+export type DetachedViewportCarrierKind = 'browser-page' | 'tauri-webview';
+/** Add the fenced Runtime identity only to the Viewport surface. Business panels remain ordinary shell pages. */
+export declare function encodeSurfaceWindowQuery(d: SurfaceDescriptor, carrierKind: DetachedViewportCarrierKind, generation?: number, hostOrigin?: string): string;
+/** 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 declare function surfaceWindowUrl(d: SurfaceDescriptor, carrierKind: DetachedViewportCarrierKind, currentHref?: string, generation?: number): string;