@forgeax/interface 0.4.1

package/dist/package/node/main.js

@@ -0,0 +1,157 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+
+// Relative import (not the '@forgeax/design' workspace alias): design lives
+// INSIDE this package (packages/design), and a workspace member depending on
+// its own nested member trips bun 1.3.14's --frozen-lockfile graph check
+// (install/frozen disagree → CI frozen gate永远红). Same precedent as
+// tailwind.config.ts. Root-workspace consumers (studio) keep the alias.
+import { applyTheme } from '../packages/design/theme.js';
+import { initI18n } from './i18n/index.js';
+import { App } from './App.js';
+// Dark-only today; dual-marks data-theme + .dark so tokens.css selectors and
+// Tailwind's `dark:` variant stay in lockstep. A light skin later only adds
+// token overrides — no .tsx change. index.html already sets these for no-flash;
+// this keeps it correct if the attribute is ever cleared.
+applyTheme('dark');
+// Restore the persisted UI language before first paint. English is the default
+// (source of truth); other languages are a user-facing overlay.
+initI18n();
+import { initAegis } from './lib/aegis.js';
+import { BrandProvider } from './brand/index.js';
+import { ErrorBoundary } from './components/ErrorBoundary.js';
+import { bootStageEntry } from './boot/driver.js';
+import { bootBroadcast } from './boot/broadcast.js';
+import { isTrustedMessageOrigin } from './lib/trustedOrigins.js';
+import { subscribeNarrativeCopilot } from './lib/narrative-copilot.js';
+import { subscribeFileActivityStream } from './lib/file-activity-stream.js';
+import { subscribePerceptionStream } from './lib/perception-stream.js';
+import { bootUiBridge } from './lib/ui-bridge.js';
+import { syncBrowserPrefsFromServer, startBrowserPrefsSync } from './lib/browser-prefs-sync.js';
+import { setCurrentProject } from './lib/project-context.js';
+import { getStudioProjectClient, hasStudioDomainClients, useShellStore } from './store.js';
+import { installWindowMessageObservation } from '@forgeax/app-shell/react';
+import { decodeSurfaceFromLocation } from '@forgeax/app-shell/window';
+import { getSurfaceWindowingController, getWindowManager, isTauri } from './lib/platform/index.js';
+import { DetachedSurface } from './components/DetachedSurface.js';
+import { installHealthBridge } from './components/StatusBar/healthBridge.js';
+import { beginAppBoot, appBootSpan, endAppBoot } from './lib/trace.js';
+import { hasSessionClient } from './store-parts/session-client.js';
+// Boot Aegis (Galileo) front-end monitoring first, before any heavy boot work,
+// so early throws are captured. Inert unless VITE_AEGIS_* is configured (PROD,
+// or dev with VITE_AEGIS_DEV=1). MUST sit after all imports — Vite dev keeps
+// source statement order, so a call placed above its import never binds.
+initAegis();
+const rootEl = document.getElementById('root');
+if (!rootEl)
+    throw new Error('#root missing');
+// Desktop (WKWebView) renders the ambient scene-fx layer far more expensively
+// than Chrome: animated large-radius blur + a rotating conic-gradient keep the
+// compositor busy even when the UI is idle (a primary source of desktop jank /
+// fans spinning). Mark the document so scene-fx.css drops the infinite
+// animations and lightens the blur on desktop; the web form keeps the full look.
+if (isTauri())
+    document.documentElement.dataset.perf = 'lite';
+// fps / cow-survivor first-person mode pointer-lock bridge for Tauri.
+// WKWebView denies the web Pointer Lock API for embedded iframe content, so
+// games postMessage `{type:'fx-pointer-capture', capture:bool}` to the parent;
+// here we forward that to the Tauri command `set_pointer_capture` which calls
+// window.set_cursor_grab + set_cursor_visible(false) at the OS level. On web
+// this branch is a no-op (games still use realRequestLock.call(canvas) +
+// pointer-lock allow on the iframe). Wire ONCE at boot — listener stays for
+// the lifetime of the window.
+if (isTauri()) {
+    void (async () => {
+        try {
+            const { invoke } = await import('@tauri-apps/api/core');
+            const onMessage = (ev) => {
+                if (!isTrustedMessageOrigin(ev.origin))
+                    return; // foreign-origin guard
+                const data = ev.data;
+                if (data?.type !== 'fx-pointer-capture')
+                    return;
+                void invoke('set_pointer_capture', { capture: !!data.capture });
+            };
+            void installWindowMessageObservation({ target: window, onMessage });
+        }
+        catch (err) {
+            console.warn('[interface] fx-pointer-capture bridge unavailable:', err?.message ?? err);
+        }
+    })();
+}
+// Detached-window entry: when launched with `?surface=...` (a popped-out OS
+// window in the Tauri shell), render ONLY that surface — not the full IDE
+// shell. Same bundle, single index.html, no multi-entry build. The boot splash
+// in index.html is dismissed immediately since there's no heavy shell to wait
+// for. Business state stays consistent via the shared backend (/api · /ws).
+const detachedSurface = decodeSurfaceFromLocation();
+if (detachedSurface) {
+    // Boot splash is keyed off window.__forgeaxBoot; tell it we're done so the
+    // splash fades out for the lightweight detached view.
+    window.__forgeaxBoot?.done?.();
+    // Detached windows still need the store + live streams. Each OS window stays
+    // consistent through the shared backend. We deliberately skip the
+    // window-close→redock listener here (that's the main window's job).
+    bootStore();
+    createRoot(rootEl).render(_jsx(StrictMode, { children: _jsx(ErrorBoundary, { scope: "detached-surface", children: _jsx(BrandProvider, { children: _jsx(DetachedSurface, { surface: detachedSurface }) }) }) }));
+}
+else {
+    // Restore UI prefs, resolve the active game/project id, then mount the shell
+    // so DockRegion reads project-scoped layout keys on first paint.
+    void (async () => {
+        await syncBrowserPrefsFromServer();
+        initI18n();
+        try {
+            if (hasStudioDomainClients()) {
+                const j = await getStudioProjectClient().listProjects();
+                setCurrentProject(j.activeSlug ?? j.games?.[0]?.slug ?? 'default');
+            }
+        }
+        catch { /* non-critical — GameDirectoryModalHost retries */ }
+        startBrowserPrefsSync();
+        bootStageEntry();
+        bootFullShell(rootEl);
+    })();
+}
+// Shared store/stream bootstrap. NOTE (R4): chat's session-stream lives in
+// `@forgeax/chat` now and is wired by the Studio product assembly. The standalone
+// interface AppKit boot is chat-agnostic — it does not subscribe the chat
+// message stream (the interface foundation must not import the chat application).
+function bootStore() {
+    // Health/INFO bridge — capture shell errors + iframe-forwarded health signals
+    // (Play/Edit/plugin) into the status bar. Must run before any iframe mounts so
+    // early createApp failures are caught. Idempotent.
+    installHealthBridge();
+    bootBroadcast(); // R5/P1 唯一公共广播 socket（telemetry）
+    if (hasSessionClient()) {
+        subscribeNarrativeCopilot();
+        subscribeFileActivityStream();
+        subscribePerceptionStream();
+        void useShellStore.getState().initSessions();
+    }
+    bootUiBridge(); // UI 语义操作层(ActionRegistry + lease + ui_* 应答;方案:产品AI化-语义操作层)
+}
+function bootFullShell(el) {
+    // 全链路 trace:app.boot 初始化 trace(store-wiring + shell-mount;纯浏览器)。
+    beginAppBoot();
+    // R3 (2026-05-20 重做) —— boot 流程见 bootStore():subscribeSessionStream 先挂
+    // handler,再 initSessions → connectForgeaXWs。store 是唯一真值源。
+    appBootSpan('app.boot.store', () => bootStore());
+    // Windowing: when a detached surface window is closed by the user, redock it
+    // (the main window re-mounts its keep-alive iframe or retained Page anchor).
+    // Browser popup polling and Tauri destroyed events both converge here.
+    getWindowManager().onSurfaceWindowClosed((d) => {
+        getSurfaceWindowingController().markSurfaceDocked(d);
+    });
+    if (import.meta.env.DEV) {
+        // DevTools bridge — exposes the Zustand store to window.__dev so that the
+        // external forgeax-devtools panel (~/Dev/forgeax-devtools/) can read and
+        // patch store state without being part of this repo. Stripped in production.
+        window['__dev'] = useShellStore;
+    }
+    appBootSpan('app.boot.shell', () => {
+        createRoot(el).render(_jsx(StrictMode, { children: _jsx(ErrorBoundary, { scope: "studio-shell", children: _jsx(BrandProvider, { children: _jsx(App, {}) }) }) }));
+    });
+    endAppBoot();
+}

package/dist/package/node/store-parts/domain-clients.js

@@ -0,0 +1,17 @@
+/** Domain-shaped Studio service contracts injected by the product composition root. */
+let configuredClients = null;
+export function configureStudioDomainClients(clients) {
+    configuredClients = clients;
+}
+export function hasStudioDomainClients() {
+    return configuredClients !== null;
+}
+function requireClients() {
+    if (!configuredClients) {
+        throw new Error('No Studio domain clients configured. The Studio composition root must inject them before booting interface.');
+    }
+    return configuredClients;
+}
+export const getAgentCatalogClient = () => requireClients().agents;
+export const getStudioProjectClient = () => requireClients().projects;
+export const getStudioBuildClient = () => requireClients().builds;

package/dist/package/node/store-parts/observability.js

@@ -0,0 +1,35 @@
+import { recordLog } from '../lib/logSink.js';
+export function createObservabilityState(set) {
+    return {
+        consoleLog: [],
+        pushConsole: (entry) => {
+            recordLog('console', entry);
+            set((s) => ({
+                consoleLog: s.consoleLog.length >= 500
+                    ? [...s.consoleLog.slice(s.consoleLog.length - 499), entry]
+                    : [...s.consoleLog, entry],
+            }));
+        },
+        clearConsole: () => set({ consoleLog: [] }),
+        networkLog: [],
+        pushNetwork: (entry) => {
+            recordLog('network', entry);
+            set((s) => ({
+                networkLog: s.networkLog.length >= 500
+                    ? [...s.networkLog.slice(s.networkLog.length - 499), entry]
+                    : [...s.networkLog, entry],
+            }));
+        },
+        clearNetwork: () => set({ networkLog: [] }),
+        telemetry: [],
+        pushTelemetry: (records) => {
+            if (!records.length)
+                return;
+            set((s) => {
+                const next = [...s.telemetry, ...records];
+                return { telemetry: next.length > 500 ? next.slice(next.length - 500) : next };
+            });
+        },
+        clearTelemetry: () => set({ telemetry: [] }),
+    };
+}

package/dist/package/node/store-parts/persistence.js

@@ -0,0 +1,245 @@
+const PROVIDER_OVERRIDE_KEY = 'forgeax.providerOverride';
+const SETTINGS_SECTION_KEY = 'forgeax.settingsSection';
+const ACTIVE_SID_KEY = 'forgeax.activeSid';
+const AGENT_BY_SID_KEY = 'forgeax.agentBySid';
+const LEGACY_TABS_KEY = 'forgeax.tabs';
+const LEGACY_ACTIVE_TAB_KEY = 'forgeax.activeTabId';
+function stableValue(value) {
+    if (Array.isArray(value))
+        return value.map(stableValue);
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, entry]) => [key, stableValue(entry)]));
+    }
+    return value;
+}
+function equalDurableValue(left, right) {
+    return JSON.stringify(stableValue(left)) === JSON.stringify(stableValue(right));
+}
+export async function verifyDurableSave(input) {
+    const base = {
+        requestId: input.requestId,
+        writerRealmId: input.writerRealmId,
+        authoritative: input.authoritative,
+    };
+    if (!input.requestId.trim() || !input.writerRealmId.trim()) {
+        return {
+            ...base,
+            state: 'unknown',
+            readerRealmId: null,
+            observed: null,
+            error: {
+                code: 'invalid-request',
+                hint: 'Save verification requires a requestId and writer realm identity.',
+                retryable: false,
+                recoveryActions: ['persistence.discover', 'persistence.retry'],
+            },
+        };
+    }
+    let reader;
+    try {
+        reader = await input.createFreshReader();
+    }
+    catch {
+        return {
+            ...base,
+            state: 'unknown',
+            readerRealmId: null,
+            observed: null,
+            error: {
+                code: 'read-back-failed',
+                hint: 'The independent reader could not be created; durability is unknown.',
+                retryable: true,
+                recoveryActions: ['persistence.inspect', 'persistence.retry'],
+            },
+        };
+    }
+    if (!reader.realmId.trim() || reader.realmId === input.writerRealmId) {
+        return {
+            ...base,
+            state: 'unknown',
+            readerRealmId: reader.realmId || null,
+            observed: null,
+            error: {
+                code: 'reader-not-independent',
+                hint: 'Durability requires a newly created reader realm distinct from the writer.',
+                retryable: false,
+                recoveryActions: ['persistence.discover', 'persistence.retry'],
+            },
+        };
+    }
+    let observed;
+    try {
+        observed = await reader.read();
+    }
+    catch {
+        return {
+            ...base,
+            state: 'unknown',
+            readerRealmId: reader.realmId,
+            observed: null,
+            error: {
+                code: 'read-back-failed',
+                hint: 'The independent reader failed to read the authoritative value; durability is unknown.',
+                retryable: true,
+                recoveryActions: ['persistence.inspect', 'persistence.retry'],
+            },
+        };
+    }
+    if (!equalDurableValue(input.authoritative, observed)) {
+        return {
+            ...base,
+            state: 'dirty',
+            readerRealmId: reader.realmId,
+            observed,
+            error: {
+                code: 'durability-mismatch',
+                hint: 'The fresh reader observed a different authoritative value; the save is not clean.',
+                retryable: true,
+                recoveryActions: ['persistence.inspect', 'persistence.retry'],
+            },
+        };
+    }
+    return {
+        ...base,
+        state: 'clean',
+        readerRealmId: reader.realmId,
+        observed,
+    };
+}
+export async function saveAndVerifyDurably(input) {
+    if (!input.requestId.trim() || !input.writerRealmId.trim())
+        return {
+            requestId: input.requestId,
+            writerRealmId: input.writerRealmId,
+            state: 'unknown',
+            readerRealmId: null,
+            authoritative: null,
+            observed: null,
+            error: {
+                code: 'invalid-request',
+                hint: 'Save requires a requestId and writer realm identity.',
+                retryable: false,
+                recoveryActions: ['persistence.discover', 'persistence.retry'],
+            },
+        };
+    let authoritative;
+    try {
+        authoritative = await input.save();
+    }
+    catch {
+        return {
+            requestId: input.requestId,
+            writerRealmId: input.writerRealmId,
+            state: 'unknown',
+            readerRealmId: null,
+            authoritative: null,
+            observed: null,
+            error: {
+                code: 'save-failed',
+                hint: 'The authoritative Host save failed; the durable state is unknown.',
+                retryable: true,
+                recoveryActions: ['persistence.inspect', 'persistence.retry'],
+            },
+        };
+    }
+    return verifyDurableSave({ ...input, authoritative });
+}
+export function loadProviderOverride() {
+    try {
+        const v = localStorage.getItem(PROVIDER_OVERRIDE_KEY);
+        return v && v !== 'null' ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveProviderOverride(id) {
+    try {
+        if (id === null)
+            localStorage.removeItem(PROVIDER_OVERRIDE_KEY);
+        else
+            localStorage.setItem(PROVIDER_OVERRIDE_KEY, id);
+    }
+    catch {
+        /* ignore (private mode / SSR) */
+    }
+}
+export function loadSettingsSection() {
+    try {
+        const v = localStorage.getItem(SETTINGS_SECTION_KEY);
+        return v && v.trim() ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveSettingsSection(id) {
+    try {
+        if (id)
+            localStorage.setItem(SETTINGS_SECTION_KEY, id);
+        else
+            localStorage.removeItem(SETTINGS_SECTION_KEY);
+    }
+    catch {
+        /* ignore */
+    }
+}
+export function cleanupLegacySessionKeys() {
+    try {
+        localStorage.removeItem(LEGACY_TABS_KEY);
+        localStorage.removeItem(LEGACY_ACTIVE_TAB_KEY);
+    }
+    catch {
+        /* ignore (private mode / SSR) */
+    }
+}
+export function loadAgentBySid() {
+    try {
+        const raw = localStorage.getItem(AGENT_BY_SID_KEY);
+        if (!raw)
+            return {};
+        const obj = JSON.parse(raw);
+        if (!obj || typeof obj !== 'object' || Array.isArray(obj))
+            return {};
+        const out = {};
+        for (const [sid, agent] of Object.entries(obj)) {
+            if (typeof sid === 'string' && typeof agent === 'string' && sid && agent) {
+                out[sid] = agent;
+            }
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+export function persistAgentBySid(map) {
+    try {
+        localStorage.setItem(AGENT_BY_SID_KEY, JSON.stringify(map));
+    }
+    catch {
+        /* ignore */
+    }
+}
+export function loadActiveSid() {
+    try {
+        const v = localStorage.getItem(ACTIVE_SID_KEY);
+        return v && v.trim() ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function persistActiveSid(sid) {
+    try {
+        if (sid)
+            localStorage.setItem(ACTIVE_SID_KEY, sid);
+        else
+            localStorage.removeItem(ACTIVE_SID_KEY);
+    }
+    catch {
+        /* ignore */
+    }
+}

package/dist/package/node/store-parts/session-client.js

@@ -0,0 +1,17 @@
+let configuredClient = null;
+export function configureSessionClient(client) {
+    configuredClient = client;
+}
+/** True once the composition root injected a client. Lets optional consumers
+ *  (session-client plugin) degrade gracefully instead of hitting the
+ *  getSessionClient() throw — interface-alone / standalone-editor hosts have
+ *  no forgeax-server and never configure one. */
+export function hasSessionClient() {
+    return configuredClient !== null;
+}
+export function getSessionClient() {
+    if (!configuredClient) {
+        throw new Error('No session client configured. The Studio composition root must inject one before booting interface.');
+    }
+    return configuredClient;
+}

package/dist/package/node/store-parts/session-pick.js

@@ -0,0 +1,21 @@
+// 会话回落挑选规则（SSOT）—— initSessions / refreshSessions / setActiveGame 共用。
+//
+// 历史与 game 绑定：刷新 / 切 game / 列表变更后，UI 应回到「上次明确停留的那条
+// 会话（persisted sid，若仍存在）」，否则回到「该 game 最近活跃的一条」。server
+// 的 /api/sessions 不保证按活跃度排序，所以这里显式按 lastActivityAt 挑，
+// 而不是拿列表第 0 位。
+/** 该 game 最近活跃的一条会话 sid；空列表 → null。 */
+export function mostRecentSid(tabs) {
+    let best = null;
+    for (const t of tabs) {
+        if (!best || (t.lastActivityAt ?? 0) > (best.lastActivityAt ?? 0))
+            best = t;
+    }
+    return best?.sid ?? null;
+}
+/** persisted sid 仍在列表里 → 尊重用户上次的停留；否则回落最近活跃。 */
+export function pickActiveSid(tabs, persisted) {
+    if (persisted && tabs.some((t) => t.sid === persisted))
+        return persisted;
+    return mostRecentSid(tabs);
+}

package/dist/package/node/store-parts/shell.js

@@ -0,0 +1,37 @@
+import { getSurfaceWindowingController } from '../lib/platform/index.js';
+import { loadSettingsSection, saveSettingsSection } from './persistence.js';
+export function createShellState(set, get) {
+    return {
+        detachSurface: (d, opts) => getSurfaceWindowingController().detachSurface(d, opts),
+        redockSurface: (d) => getSurfaceWindowingController().redockSurface(d),
+        activeSession: 'main-design',
+        setActiveSession: (s) => set({ activeSession: s }),
+        activeOverlay: null,
+        overlayParam: loadSettingsSection(),
+        openOverlay: (id, param) => {
+            const p = param ?? get().overlayParam ?? null;
+            saveSettingsSection(p);
+            set({ activeOverlay: id, overlayParam: p });
+        },
+        setOverlayParam: (param) => {
+            saveSettingsSection(param);
+            set({ overlayParam: param });
+        },
+        closeOverlay: () => set({ activeOverlay: null }),
+        gameDirectoryModalOpen: false,
+        openGameDirectoryModal: () => set({ gameDirectoryModalOpen: true }),
+        closeGameDirectoryModal: () => set({ gameDirectoryModalOpen: false }),
+        gameSwitcherOpen: false,
+        setGameSwitcherOpen: (v) => set({ gameSwitcherOpen: v }),
+        gameModalOpen: false,
+        openGameModal: () => set({ gameModalOpen: true }),
+        closeGameModal: () => set({ gameModalOpen: false }),
+        fullscreen: false,
+        setFullscreen: (v) => set({ fullscreen: v }),
+        toggleFullscreen: () => set((s) => ({ fullscreen: !s.fullscreen })),
+        sidebarCollapsed: false,
+        chatpanelCollapsed: false,
+        toggleSidebar: () => set((s) => ({ sidebarCollapsed: !s.sidebarCollapsed })),
+        toggleChatpanel: () => set((s) => ({ chatpanelCollapsed: !s.chatpanelCollapsed })),
+    };
+}