@forgeax/interface 0.4.1

package/dist/package/node/lib/platform/window-manager.js

@@ -0,0 +1,82 @@
+/**
+ * WindowManager — detach a surface into its own OS window and redock it.
+ *
+ * This is the "windowing" layer. It is the OUT-OF-window twin of keep-alive:
+ * keep-alive hosts a surface CSS-hidden inside the main window; windowing hosts
+ * it in a separate Tauri WebviewWindow. The owning store flips a surface
+ * between `docked` and `floating` and this manager makes the OS-level change.
+ *
+ * Pattern adapted from gameclaw_pet/src/shared/window-manager.ts (dynamic
+ * WebviewWindow create/destroy), but our detached windows reuse the SAME
+ * frontend bundle — they load `index.html?surface=...` and the entry renders a
+ * single <DetachedSurface>. Cross-window business state stays consistent for
+ * free because every window talks to the same backend (/api, /ws).
+ *
+ * Browser form delegates its product-neutral popup lifecycle to App Shell;
+ * Interface supplies only the ForgeaX surface URL policy. Tauri stays here as
+ * a product runtime integration and loads the same surface URL contract.
+ */
+import { isTauri, loadWebviewWindowApi } from './runtime.js';
+import { createBrowserWindowManager, createExternalWindowManager, } from '@forgeax/app-shell/window';
+import { encodeSurfaceWindowQuery, surfaceWindowUrl, } from './surface.js';
+let _manager = null;
+export function getWindowManager() {
+    if (!_manager) {
+        _manager = isTauri()
+            ? createExternalWindowManager({
+                canDetach: isTauri,
+                loadHost: loadTauriWindowHost,
+            })
+            : createBrowserWindowManager({
+                surfaceUrl: (d) => `index.html?${encodeSurfaceWindowQuery(d, 'browser-page')}`,
+            });
+    }
+    return _manager;
+}
+function toExternalWindowHandle(window) {
+    return {
+        show: () => window.show(),
+        focus: () => window.setFocus(),
+        close: () => window.close(),
+    };
+}
+async function loadTauriWindowHost() {
+    const mod = await loadWebviewWindowApi();
+    if (!mod)
+        return undefined;
+    return {
+        async getByLabel(label) {
+            const window = await mod.WebviewWindow.getByLabel(label);
+            return window ? toExternalWindowHandle(window) : null;
+        },
+        async create(label, surface, options, lifecycle) {
+            const hasPosition = typeof options?.x === 'number' && typeof options?.y === 'number';
+            const window = new mod.WebviewWindow(label, {
+                url: surfaceWindowUrl(surface, 'tauri-webview'),
+                title: options?.title ?? surface.id,
+                width: options?.width ?? 960,
+                height: options?.height ?? 720,
+                ...(hasPosition ? { x: options.x, y: options.y } : { center: true }),
+                resizable: true,
+                // Preserve HTML5 Dockview drag-and-drop inside the detached Webview.
+                dragDropEnabled: false,
+            });
+            try {
+                await Promise.all([
+                    // Redock only after the OS window is actually gone.
+                    window.once('tauri://destroyed', lifecycle.destroyed),
+                    window.once('tauri://created', lifecycle.created),
+                    window.once('tauri://error', lifecycle.error),
+                ]);
+            }
+            catch (error) {
+                try {
+                    await window.close();
+                }
+                catch { /* registration failed after creation */ }
+                throw error;
+            }
+            return toExternalWindowHandle(window);
+        },
+    };
+}

package/dist/package/node/lib/project-context.js

@@ -0,0 +1,42 @@
+/** Active project identity used only to namespace project-owned Page state. */
+let currentProjectId = 'default';
+let projectListeners = [];
+const PAGE_ONLY_MIGRATION_KEY = 'forgeax:migrations:page-only-v1';
+function discardRetiredGlobalLayouts() {
+    if (typeof localStorage === 'undefined' || localStorage.getItem(PAGE_ONLY_MIGRATION_KEY) === 'done')
+        return;
+    const retiredShellTerm = ['work', 'bench'].join('');
+    const retired = new RegExp(`(?:${retiredShellTerm}|ws-layout|panel-locations|app-mode)`, 'i');
+    const keys = [];
+    for (let index = 0; index < localStorage.length; index += 1) {
+        const key = localStorage.key(index);
+        if (key && retired.test(key))
+            keys.push(key);
+    }
+    keys.forEach((key) => localStorage.removeItem(key));
+    localStorage.setItem(PAGE_ONLY_MIGRATION_KEY, 'done');
+}
+export function setCurrentProject(projectId) {
+    discardRetiredGlobalLayouts();
+    if (!projectId || projectId === currentProjectId)
+        return;
+    currentProjectId = projectId;
+    projectListeners.forEach((listener) => {
+        try {
+            listener(projectId);
+        }
+        catch { /* isolated observer */ }
+    });
+}
+export function getCurrentProject() {
+    discardRetiredGlobalLayouts();
+    return currentProjectId;
+}
+export function subscribeCurrentProject(listener) {
+    projectListeners.push(listener);
+    return () => { projectListeners = projectListeners.filter((candidate) => candidate !== listener); };
+}
+export function __resetCurrentProjectIdForTests() {
+    currentProjectId = 'default';
+    projectListeners = [];
+}

package/dist/package/node/lib/project.js

@@ -0,0 +1,8 @@
+// Single source of truth for project/path/branch shown in the TopBar title.
+// Static for now. A future iteration can replace this with server-owned active
+// game metadata so the title reflects the actual git branch and game path.
+export const CURRENT_PROJECT = {
+    name: 'forgeax',
+    path: 'games/gta-2.5d',
+    branch: 'main',
+};

package/dist/package/node/lib/recent-games.js

@@ -0,0 +1,50 @@
+/** recent-games —— File → 打开最近 submenu 的数据源。
+ *
+ *  菜单的 `dynamicChildren` 派生器必须**同步**求值 (Radix 在 submenu 展开时同步
+ *  渲染 SubContent),而游戏列表来自 async 的 `listGames()`。本模块把二者解耦:
+ *    - `warmRecentGames()` —— async 预取,在 File 菜单 dropdown 打开时调用一次,
+ *      结果写入模块级缓存;
+ *    - `getRecentGames(limit)` —— sync 读缓存,按 mtime 降序 (最近打开在前) 取前
+ *      N 个,供 dynamicChildren 派生菜单项。
+ *
+ *  SSOT remains the server's /api/projects collection; the cache is only a
+ *  的快照,不是第二真值源 (每次 File 菜单打开都重新 warm)。
+ */
+import { getStudioProjectClient, hasStudioDomainClients } from '../store-parts/domain-clients.js';
+let cache = [];
+let revision = 0;
+const listeners = new Set();
+export function subscribeRecentGames(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+/** Stable scalar snapshot for useSyncExternalStore consumers. */
+export function getRecentGamesRevision() {
+    return revision;
+}
+/** Prefetch the game list into the sync cache. Call when the File dropdown
+ *  opens so `getRecentGames` has data ready by the time the submenu expands.
+ *  Failures leave the previous cache intact (stale is better than empty flash). */
+export async function warmRecentGames() {
+    if (!hasStudioDomainClients())
+        return;
+    try {
+        const j = await getStudioProjectClient().listProjects();
+        cache = j.games ?? [];
+        revision += 1;
+        listeners.forEach((listener) => listener());
+    }
+    catch {
+        /* keep last-known cache on transient failure */
+    }
+}
+/** Sync read: most-recently-modified games first, capped at `limit`.
+ *  `GameRow` carries `mtime` under an index signature (typed `unknown`), so
+ *  coerce defensively — a missing/NaN mtime sorts last rather than crashing. */
+export function getRecentGames(limit = 8) {
+    const mt = (g) => {
+        const v = Number(g.mtime);
+        return Number.isFinite(v) ? v : 0;
+    };
+    return [...cache].sort((a, b) => mt(b) - mt(a)).slice(0, limit);
+}

package/dist/package/node/lib/repair-builtin-menus.js

@@ -0,0 +1,18 @@
+import { builtinMenusExtension } from '../core/extensions/builtin-menus.js';
+import { snapshotMenu } from './menu-registry.js';
+let adhocCleanup;
+/** Re-register built-in menus when the module-level registry was cleared
+ *  (React StrictMode dispose race, Vite HMR module swap) but shell chrome
+ *  is still mounted. Idempotent — no-op when File menu already populated. */
+export function repairBuiltinMenusIfEmpty() {
+    if (snapshotMenu('file').length > 0)
+        return;
+    adhocCleanup?.();
+    const result = builtinMenusExtension.setup?.({});
+    adhocCleanup = typeof result === 'function' ? result : undefined;
+}
+/** Test-only: tear down ad-hoc repair registration. */
+export function __resetBuiltinMenuRepairForTest() {
+    adhocCleanup?.();
+    adhocCleanup = undefined;
+}

package/dist/package/node/lib/reply-language.js

@@ -0,0 +1,11 @@
+/**
+ * Agent reply-language resolution.
+ *
+ * Reply language follows the interface locale (Settings → Language). The agent
+ * is asked to answer in the same language as the UI chrome.
+ */
+import { getLocale } from '../i18n/index.js';
+/** Resolve the reply language for a turn — always the current UI locale. */
+export function resolveReplyLanguage(_userText) {
+    return getLocale();
+}

package/dist/package/node/lib/resilient-polling.js

@@ -0,0 +1,16 @@
+export function deriveExtensionKindCounts(items) {
+    const result = {
+        'model-binding': { count: 0, ids: [] },
+        skill: { count: 0, ids: [] },
+        tool: { count: 0, ids: [] },
+        agent: { count: 0, ids: [] },
+    };
+    for (const item of items) {
+        if (!(item.kind in result))
+            continue;
+        const row = result[item.kind];
+        row.count += 1;
+        row.ids.push(item.id);
+    }
+    return result;
+}

package/dist/package/node/lib/session-time.js

@@ -0,0 +1,40 @@
+import { getLocale, t } from '../i18n/index.js';
+const DAY_MS = 86_400_000;
+function calendarDayDiff(now, then) {
+    return Math.floor((Date.UTC(now.getFullYear(), now.getMonth(), now.getDate())
+        - Date.UTC(then.getFullYear(), then.getMonth(), then.getDate()))
+        / DAY_MS);
+}
+function clock(date) {
+    return `${String(date.getHours()).padStart(2, '0')}:${String(date.getMinutes()).padStart(2, '0')}`;
+}
+export function formatSessionTime(timestamp, options = {}) {
+    if (!timestamp || !Number.isFinite(timestamp))
+        return '';
+    const nowMs = options.now ?? Date.now();
+    const locale = options.locale ?? getLocale();
+    const translate = options.translate ?? t;
+    if (timestamp > nowMs)
+        return translate('sessionTime.justNow');
+    const now = new Date(nowMs);
+    const then = new Date(timestamp);
+    const dayDiff = calendarDayDiff(now, then);
+    const time = clock(then);
+    if (dayDiff <= 0)
+        return translate('sessionTime.todayTime', { time });
+    if (dayDiff === 1)
+        return translate('sessionTime.yesterdayTime', { time });
+    if (dayDiff < 7) {
+        const weekday = new Intl.DateTimeFormat(locale === 'zh' ? 'zh-CN' : 'en-US', {
+            weekday: 'short',
+        }).format(then);
+        return translate('sessionTime.weekdayTime', { weekday, time });
+    }
+    const month = locale === 'zh'
+        ? String(then.getMonth() + 1)
+        : new Intl.DateTimeFormat('en-US', { month: 'short' }).format(then);
+    const day = then.getDate();
+    return then.getFullYear() === now.getFullYear()
+        ? translate('sessionTime.dateThisYear', { month, day })
+        : translate('sessionTime.dateOtherYear', { year: then.getFullYear(), month, day });
+}

package/dist/package/node/lib/shell-live-data.js

@@ -0,0 +1,66 @@
+import { useSyncExternalStore } from 'react';
+import { createSettledPollingLifecycle } from '@forgeax/app-shell/react';
+import { deriveExtensionKindCounts, } from './resilient-polling.js';
+function createLiveStore(load, intervalMs) {
+    let snapshot = { state: 'loading' };
+    const listeners = new Set();
+    let stop;
+    const emit = () => listeners.forEach((listener) => listener());
+    const start = () => {
+        const poll = createSettledPollingLifecycle({
+            task: async (signal) => {
+                try {
+                    const value = await load(signal);
+                    snapshot = { state: 'ok', value };
+                }
+                catch (error) {
+                    if (signal.aborted)
+                        throw error;
+                    snapshot = { state: 'down' };
+                    throw error;
+                }
+                finally {
+                    emit();
+                }
+            },
+            intervalMs,
+            timeoutMs: 5_000,
+        });
+        poll.start();
+        return poll.dispose;
+    };
+    return {
+        subscribe(listener) {
+            listeners.add(listener);
+            if (listeners.size === 1)
+                stop = start();
+            return () => {
+                listeners.delete(listener);
+                if (listeners.size === 0) {
+                    stop?.();
+                    stop = undefined;
+                }
+            };
+        },
+        getSnapshot: () => snapshot,
+    };
+}
+const healthStore = createLiveStore(async (signal) => {
+    const response = await fetch('/api/health', { cache: 'no-store', signal });
+    if (!response.ok)
+        throw new Error(`/api/health ${response.status}`);
+    return response.json();
+}, 5_000);
+const extensionCountsStore = createLiveStore(async (signal) => {
+    const response = await fetch('/api/extensions/list', { cache: 'no-store', signal });
+    if (!response.ok)
+        throw new Error(`/api/extensions/list ${response.status}`);
+    const payload = await response.json();
+    return deriveExtensionKindCounts(payload.items);
+}, 12_000);
+export function useSharedHealth() {
+    return useSyncExternalStore(healthStore.subscribe, healthStore.getSnapshot, healthStore.getSnapshot);
+}
+export function useSharedExtensionCounts() {
+    return useSyncExternalStore(extensionCountsStore.subscribe, extensionCountsStore.getSnapshot, extensionCountsStore.getSnapshot);
+}

package/dist/package/node/lib/sse.js

@@ -0,0 +1,42 @@
+// Minimal SSE parser over a fetch ReadableStream.
+// Yields {event, data} frames; handles multi-line `data:` accumulation per spec.
+export async function* parseSse(stream) {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let buf = '';
+    let event = '';
+    let data = '';
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buf += decoder.decode(value, { stream: true });
+            let idx;
+            while ((idx = buf.indexOf('\n')) >= 0) {
+                const line = buf.slice(0, idx).replace(/\r$/, '');
+                buf = buf.slice(idx + 1);
+                if (line === '') {
+                    if (event || data)
+                        yield { event, data };
+                    event = '';
+                    data = '';
+                }
+                else if (line.startsWith('event:')) {
+                    event = line.slice(6).trim();
+                }
+                else if (line.startsWith('data:')) {
+                    data += (data ? '\n' : '') + line.slice(5).trim();
+                }
+            }
+        }
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}

package/dist/package/node/lib/storageKeys.js

@@ -0,0 +1,89 @@
+// Storage key registry — the single place every localStorage key the interface
+// owns is declared (architecture review §D). Before this, ~17 `forgeax:*` keys
+// with ad-hoc versions (v1/v2/v4/v5) were scattered across modules with no map,
+// making migrations easy to miss and collisions easy to introduce.
+//
+// RULE: never inline a `'forgeax…'` localStorage key string in a component.
+// Add it here (with a one-line purpose + version note) and import the const.
+//
+// Versioning: when a value's SHAPE changes incompatibly, bump its key suffix
+// (…:v2 → …:v3) and add a migration. The dockview layout uses a separate
+// numeric stamp (LAYOUT_VERSION) handled by the page workspace migrator.
+export const STORAGE_KEYS = {
+    // ── session / chat shell (store.ts) ──
+    /** persisted open chat tabs. */
+    tabs: 'forgeax.tabs',
+    /** active session id. */
+    activeSid: 'forgeax.activeSid',
+    /** active tab id. */
+    activeTabId: 'forgeax.activeTabId',
+    /** first-run boot splash seen flag. */
+    bootSplash: 'forgeax.boot.splash.v1',
+    /** first-run onboarding state machine (welcome→project→home). Shape:
+     *  OnboardingPersisted (see components/Onboarding/types). v2 supersedes the
+     *  legacy boolean `onboardingSeenLegacy`, which is read once to migrate. */
+    onboarding: 'forgeax.onboarding.v2',
+    /** legacy boolean "onboarding dismissed" flag (pre state-machine) — read once
+     *  to migrate existing users past the first-run wizard, then ignored. */
+    onboardingSeenLegacy: 'forgeax.onboarding.seen',
+    // ── i18n ──
+    /** active UI language code ('en' | 'zh' | …). English is the default/source. */
+    locale: 'forgeax.locale',
+    // ── model routing ──
+    /** persistent cli provider override (store.ts). null → native forgeax path. */
+    providerOverride: 'forgeax.providerOverride',
+    /** { [providerKey]: modelId } — last model the user HAND-PICKED per provider
+     *  (providerKey = cli-id | 'forgeax'). New sessions seed from this so the
+     *  picker lands on "where I left off"; a provider SWITCH still resets to the
+     *  provider default. See lib/model-prefs.ts. */
+    lastModelByProvider: 'forgeax.lastModel.byProvider.v1',
+    // ── reply language ──
+    /** agent chat reply language ('en' | 'zh'). Global, decoupled from UI locale.
+     *  Default 'en'. Overridden per-turn by followInput when that is enabled. */
+    replyLanguage: 'forgeax.replyLanguage',
+    /** when '1', the agent reply language follows the detected language of each
+     *  user message (highest priority). Default enabled ('1'). */
+    followInput: 'forgeax.followInput',
+    // ── publish module ──
+    /** when '1', the first-run Publish coach-mark has been seen (or skipped). */
+    publishOnboarded: 'forgeax.publish.onboarded',
+    /** Contact email reused by the manual feedback form. Plain string, v1. */
+    feedbackEmail: 'forgeax.feedback.email.v1',
+    // ── activity rail ──
+    /** [v3] qualified activity IDs pinned to the ActivityRail.
+     *  Shape: string[]. Display order keeps the historical curated entries first,
+     *  then follows ActivityRegistry order for newly pinned extensions;
+     *  missing key → the historical 12-plugin product seed is derived. */
+    activityRailPinned: 'forgeax.activityRail.pinned.v3',
+    /** one-shot migration marker: add the Video Game entry to existing v3 pins
+     *  once without re-pinning it after a deliberate user unpin. */
+    activityRailPinnedVideoGameDefault: 'forgeax.activityRail.pinned.videoGameDefault.v1',
+    /** [ABANDONED, v2] briefly seeded every registered activity; intentionally not migrated. */
+    activityRailPinnedLegacyV2: 'forgeax.activityRail.pinned.v2',
+    /** [LEGACY, v1] plugin slugs (or early qualified IDs); read-only migration source. */
+    activityRailPinnedLegacyV1: 'forgeax.activityRail.pinned.v1',
+};
+// Cross-component window CustomEvent names (NOT storage, but same "stringly-typed
+// global namespace" footgun — centralized here so they can't drift either).
+export const APP_EVENTS = {
+    dockLayoutToggle: 'forgeax:shell:dock-layout-toggle',
+    dockReset: 'forgeax:shell:dock-reset',
+    animHandoff: 'forgeax:anim-handoff',
+    /** Viewport run axis changed. detail: { running: boolean }. */
+    viewportRunChanged: 'forgeax:viewport-run-changed',
+    /** Open (or focus, if already open) a dock panel by id. detail: { id: string } */
+    openPanel: 'forgeax:shell:open-panel',
+    /** Focus a dock panel by id ONLY if it already exists (no reopen / no force-insert). detail: { id: string } */
+    focusPanel: 'forgeax:shell:focus-panel',
+    /** Chat composer intercepted a send with no model path — open the connect
+     *  prompt. detail: { text?: string } (the pending message, echoed back on
+     *  resume so the composer can re-send it after the user connects). */
+    openConnectPrompt: 'forgeax:open-connect-prompt',
+    /** Connect prompt resolved with a usable model path — the composer that
+     *  opened it should re-send the pending message. detail: { text?: string } */
+    resumeSend: 'forgeax:resume-send',
+    /** Onboarding milestones changed in the SAME session (tour finished, first
+     *  chat done) — lets the chat empty-state hint react without a reload, since
+     *  it can't re-read localStorage on its own. No detail. */
+    onboardingChanged: 'forgeax:onboarding-changed',
+};

package/dist/package/node/lib/surface-store.js

@@ -0,0 +1,62 @@
+/**
+ * Phase D2 — surface store.
+ *
+ * In-process registry of `surface.expose` snapshots that arrive from plugin
+ * iframes via the host SDK (`port.surface.subscribe` in StandaloneExtensionIframe).
+ * Lets the dev-mode hover overlay show "this button equals tool X(args)" and
+ * gives an AI prompt-builder a single place to read the catalogue of UI
+ * actions the user could currently click.
+ *
+ * Scope intentionally narrow: a Map keyed on `extensionId:surfaceId`, plus a
+ * subscribe(cb) fanout. No persistence, no server round-trip — a refresh
+ * tears it down and the next iframe load re-emits expose().
+ */
+const surfaces = new Map();
+const listeners = new Set();
+function key(extensionId, surfaceId) {
+    return `${extensionId}:${surfaceId}`;
+}
+function fanout() {
+    for (const cb of listeners) {
+        try {
+            cb(surfaces);
+        }
+        catch (e) {
+            if (typeof console !== 'undefined')
+                console.error('[surface-store] listener', e);
+        }
+    }
+}
+export function upsertSurface(s) {
+    surfaces.set(key(s.extensionId, s.surfaceId), { ...s, updatedAt: Date.now() });
+    fanout();
+}
+/** Drop every surface owned by `extensionId`. Call when an iframe unmounts. */
+export function removeExtensionSurfaces(extensionId) {
+    let changed = false;
+    for (const k of [...surfaces.keys()]) {
+        if (surfaces.get(k).extensionId === extensionId) {
+            surfaces.delete(k);
+            changed = true;
+        }
+    }
+    if (changed)
+        fanout();
+}
+export function listSurfaces() {
+    return [...surfaces.values()];
+}
+export function getSurface(extensionId, surfaceId) {
+    return surfaces.get(key(extensionId, surfaceId)) ?? null;
+}
+export function subscribeSurfaces(cb) {
+    listeners.add(cb);
+    return () => {
+        listeners.delete(cb);
+    };
+}
+/** Test helper. */
+export function _resetSurfaceStoreForTests() {
+    surfaces.clear();
+    listeners.clear();
+}