@forgeax/interface 0.4.1

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

@@ -0,0 +1 @@
+export declare function useFloatingSurfaces(): Readonly<Record<string, true>>;

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

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

package/dist/package/browser/lib/platform/window-manager.d.ts

@@ -0,0 +1,2 @@
+import { type WindowManager } from '@forgeax/app-shell/window';
+export declare function getWindowManager(): WindowManager;

package/dist/package/browser/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';
+import { createBrowserWindowManager, createExternalWindowManager, } from '@forgeax/app-shell/window';
+import { encodeSurfaceWindowQuery, surfaceWindowUrl, } from './surface';
+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/browser/lib/project-context.d.ts

@@ -0,0 +1,4 @@
+export declare function setCurrentProject(projectId: string): void;
+export declare function getCurrentProject(): string;
+export declare function subscribeCurrentProject(listener: (projectId: string) => void): () => void;
+export declare function __resetCurrentProjectIdForTests(): void;

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

@@ -0,0 +1,5 @@
+export declare const CURRENT_PROJECT: {
+    readonly name: "forgeax";
+    readonly path: "games/gta-2.5d";
+    readonly branch: "main";
+};

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

@@ -0,0 +1,24 @@
+/** 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 { type ProjectRow } from '../store-parts/domain-clients';
+export declare function subscribeRecentGames(listener: () => void): () => void;
+/** Stable scalar snapshot for useSyncExternalStore consumers. */
+export declare function getRecentGamesRevision(): number;
+/** 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 declare function warmRecentGames(): Promise<void>;
+/** 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 declare function getRecentGames(limit?: number): ProjectRow[];

package/dist/package/browser/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';
+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/browser/lib/repair-builtin-menus.d.ts

@@ -0,0 +1,6 @@
+/** 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 declare function repairBuiltinMenusIfEmpty(): void;
+/** Test-only: tear down ad-hoc repair registration. */
+export declare function __resetBuiltinMenuRepairForTest(): void;

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

@@ -0,0 +1,18 @@
+import { builtinMenusExtension } from '../core/extensions/builtin-menus';
+import { snapshotMenu } from './menu-registry';
+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/browser/lib/reply-language.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+export type ReplyLang = 'en' | 'zh';
+/** Resolve the reply language for a turn — always the current UI locale. */
+export declare function resolveReplyLanguage(_userText: string): ReplyLang;

package/dist/package/browser/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';
+/** Resolve the reply language for a turn — always the current UI locale. */
+export function resolveReplyLanguage(_userText) {
+    return getLocale();
+}

package/dist/package/browser/lib/resilient-polling.d.ts

@@ -0,0 +1,9 @@
+export type ExtensionStatusKind = 'model-binding' | 'skill' | 'tool' | 'agent';
+export type ExtensionKindCounts = Record<ExtensionStatusKind, {
+    count: number;
+    ids: string[];
+}>;
+export declare function deriveExtensionKindCounts(items: readonly {
+    id: string;
+    kind: string;
+}[]): ExtensionKindCounts;

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

@@ -0,0 +1,8 @@
+import { type Locale, type TFunction } from '../i18n';
+interface SessionTimeOptions {
+    now?: number;
+    locale?: Locale;
+    translate?: TFunction;
+}
+export declare function formatSessionTime(timestamp: number | undefined, options?: SessionTimeOptions): string;
+export {};

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

@@ -0,0 +1,40 @@
+import { getLocale, t } from '../i18n';
+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/browser/lib/shell-live-data.d.ts

@@ -0,0 +1,12 @@
+import type { HealthResponse } from './dashboard-api';
+import { type ExtensionKindCounts } from './resilient-polling';
+export type LiveSnapshot<T> = {
+    state: 'loading';
+} | {
+    state: 'ok';
+    value: T;
+} | {
+    state: 'down';
+};
+export declare function useSharedHealth(): LiveSnapshot<HealthResponse>;
+export declare function useSharedExtensionCounts(): LiveSnapshot<ExtensionKindCounts>;

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

@@ -0,0 +1,5 @@
+export interface SseFrame {
+    event: string;
+    data: string;
+}
+export declare function parseSse(stream: ReadableStream<Uint8Array>): AsyncIterable<SseFrame>;

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

@@ -0,0 +1,70 @@
+export declare const STORAGE_KEYS: {
+    /** persisted open chat tabs. */
+    readonly tabs: "forgeax.tabs";
+    /** active session id. */
+    readonly activeSid: "forgeax.activeSid";
+    /** active tab id. */
+    readonly activeTabId: "forgeax.activeTabId";
+    /** first-run boot splash seen flag. */
+    readonly 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. */
+    readonly 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. */
+    readonly onboardingSeenLegacy: "forgeax.onboarding.seen";
+    /** active UI language code ('en' | 'zh' | …). English is the default/source. */
+    readonly locale: "forgeax.locale";
+    /** persistent cli provider override (store.ts). null → native forgeax path. */
+    readonly 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. */
+    readonly lastModelByProvider: "forgeax.lastModel.byProvider.v1";
+    /** agent chat reply language ('en' | 'zh'). Global, decoupled from UI locale.
+     *  Default 'en'. Overridden per-turn by followInput when that is enabled. */
+    readonly replyLanguage: "forgeax.replyLanguage";
+    /** when '1', the agent reply language follows the detected language of each
+     *  user message (highest priority). Default enabled ('1'). */
+    readonly followInput: "forgeax.followInput";
+    /** when '1', the first-run Publish coach-mark has been seen (or skipped). */
+    readonly publishOnboarded: "forgeax.publish.onboarded";
+    /** Contact email reused by the manual feedback form. Plain string, v1. */
+    readonly feedbackEmail: "forgeax.feedback.email.v1";
+    /** [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. */
+    readonly 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. */
+    readonly activityRailPinnedVideoGameDefault: "forgeax.activityRail.pinned.videoGameDefault.v1";
+    /** [ABANDONED, v2] briefly seeded every registered activity; intentionally not migrated. */
+    readonly activityRailPinnedLegacyV2: "forgeax.activityRail.pinned.v2";
+    /** [LEGACY, v1] plugin slugs (or early qualified IDs); read-only migration source. */
+    readonly activityRailPinnedLegacyV1: "forgeax.activityRail.pinned.v1";
+};
+export declare const APP_EVENTS: {
+    readonly dockLayoutToggle: "forgeax:shell:dock-layout-toggle";
+    readonly dockReset: "forgeax:shell:dock-reset";
+    readonly animHandoff: "forgeax:anim-handoff";
+    /** Viewport run axis changed. detail: { running: boolean }. */
+    readonly viewportRunChanged: "forgeax:viewport-run-changed";
+    /** Open (or focus, if already open) a dock panel by id. detail: { id: string } */
+    readonly openPanel: "forgeax:shell:open-panel";
+    /** Focus a dock panel by id ONLY if it already exists (no reopen / no force-insert). detail: { id: string } */
+    readonly 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). */
+    readonly 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 } */
+    readonly 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. */
+    readonly onboardingChanged: "forgeax:onboarding-changed";
+};