@forgeax/interface 0.4.1

package/dist/package/browser/lib/aegis.js

@@ -0,0 +1,230 @@
+// Aegis V2 — front-end observability reporting to the Galileo platform: JS /
+// Promise / resource errors, page performance, Web Vitals, static-resource
+// speed, PV+SPA route tracking, session timeline, and API monitoring with
+// `traceparent` injection for front↔back trace linking. Auto-instrumenting:
+// once `new Aegis(...)` runs it hooks window.onerror + unhandledrejection and
+// rewrites XHR/fetch itself; no per-call-site instrumentation.
+//
+// MIRROR SAFETY (load-bearing): this package has a public open-source mirror
+// whose publish pipeline scrubs + gates on internal hostnames. So NOTHING about
+// the SDK is hardcoded here — the CDN url, report endpoint, and project token
+// all arrive via build-time `import.meta.env.VITE_AEGIS_*`. With those unset
+// (the open-source / default case) every export below is an inert no-op and no
+// internal infra leaks into the committed source or the shipped bundle.
+//
+// Configure by dropping the three values into a gitignored `.env.local`; real
+// endpoint values live in the internal setup note, not in any committed file.
+// See `.env.example` for the (placeholder) shape.
+let instance = null;
+let started = false;
+/**
+ * Boot Aegis if — and only if — a project token is configured AND this is a
+ * production build. dev (`bun dev`) deliberately stays silent to keep the
+ * Galileo dataset clean; verify the wiring with `bun run build && bun run
+ * preview` (preview is a PROD build) or in the deployed web / desktop .app.
+ *
+ * Idempotent: StrictMode double-invokes and the two boot paths in main.tsx
+ * (detached surface + full shell) can both call this; the `started` latch makes
+ * the second call a no-op.
+ */
+export function initAegis() {
+    if (started)
+        return;
+    started = true;
+    // Gate: production builds only — dev (`bun dev`) stays silent to keep the
+    // dataset clean. Escape hatch for local verification: set VITE_AEGIS_DEV=1 in
+    // .env.local to also report in dev (use VITE_AEGIS_ENV=test there so the
+    // probe data lands in the test environment, not prod).
+    const devForce = import.meta.env.VITE_AEGIS_DEV === '1' || import.meta.env.VITE_AEGIS_DEV === 'true';
+    if (!import.meta.env.PROD && !devForce) {
+        console.info('[aegis] inert: dev build — set VITE_AEGIS_DEV=1 in .env.development/.env.local and RESTART the dev server');
+        return;
+    }
+    const id = import.meta.env.VITE_AEGIS_ID;
+    const sdkUrl = import.meta.env.VITE_AEGIS_SDK_URL;
+    const hostUrl = import.meta.env.VITE_AEGIS_HOST_URL;
+    if (!id || !sdkUrl || !hostUrl) {
+        console.warn('[aegis] inert: missing env (RESTART dev after editing .env*) —', {
+            id: !!id,
+            sdkUrl: !!sdkUrl,
+            hostUrl: !!hostUrl,
+        });
+        return; // unconfigured → stay inert
+    }
+    console.info('[aegis] loading SDK:', sdkUrl);
+    const script = document.createElement('script');
+    script.src = sdkUrl;
+    script.async = true;
+    // crossorigin lets the SDK read full stack traces from cross-origin scripts;
+    // without it window.onerror only sees "Script error." for foreign sources.
+    script.crossOrigin = 'anonymous';
+    script.onload = () => {
+        const Aegis = window.Aegis;
+        if (!Aegis) {
+            console.warn('[aegis] SDK script loaded but window.Aegis missing');
+            return;
+        }
+        try {
+            // URLs to inject the `traceparent` header into, for session front↔back
+            // trace linking. forgeax calls its backend same-origin (`/api`, `/ws`),
+            // and same-origin requests skip CORS preflight, so injecting there is
+            // safe. Override via VITE_AEGIS_TRACE_URLS (comma-separated regex source).
+            const traceUrlsEnv = import.meta.env.VITE_AEGIS_TRACE_URLS;
+            const injectTraceUrls = traceUrlsEnv
+                ? traceUrlsEnv.split(',').map((s) => new RegExp(s.trim()))
+                : [/\/api\//, /\/ws/];
+            instance = new Aegis({
+                id,
+                hostUrl: { url: hostUrl },
+                // 'production' → Galileo prod environment; anything else (test/personal)
+                // routes to the test environment. Defaults to production.
+                env: import.meta.env.VITE_AEGIS_ENV || 'production',
+                // Aggregation: everything enqueued within `delay` ms is merged into ONE
+                // /collect request. Aegis defaults to 1000ms which, on a chatty app
+                // (continuous /api polling via the api plugin + console bridge), fires a
+                // request almost every second. Widen the window to batch far more per
+                // request. Override via VITE_AEGIS_DELAY (ms). compress gzips the body
+                // (needs SDK >= 2.5.50) to cut bandwidth/cost on the bigger batches.
+                delay: Number(import.meta.env.VITE_AEGIS_DELAY) || 5000,
+                compress: true,
+                plugin: {
+                    // Identity / context collectors.
+                    aid: true,
+                    device: true,
+                    close: true,
+                    fId: false, // fingerprint — hurts perf, off unless needed
+                    ie: false,
+                    // Page-view + SPA route-change tracking.
+                    pv: true,
+                    spa: true,
+                    // Error capture (JS / Promise / resource).
+                    error: true,
+                    // Static-resource speed + page performance + Web Vitals.
+                    assetSpeed: true,
+                    pagePerformance: true,
+                    webVitals: true,
+                    // Session replay-style timeline; requires the Galileo collect host.
+                    session: true,
+                    // API monitoring (rewrites XHR/fetch) WITH trace-header injection for
+                    // front↔back session linking. apiDetail left off so request/response
+                    // bodies are NOT collected (lighter + privacy-safer).
+                    api: {
+                        injectTraceHeader: 'traceparent',
+                        injectTraceUrls,
+                    },
+                    reporting: false,
+                },
+            });
+            window.__forgeaxAegis = instance;
+            console.info('[aegis] initialized → reporting to', hostUrl, '(env:', import.meta.env.VITE_AEGIS_ENV || 'production', ')');
+            installConsoleBridge(instance);
+        }
+        catch (err) {
+            console.warn('[aegis] init failed:', err?.message ?? err);
+        }
+    };
+    script.onerror = () => {
+        console.warn('[aegis] SDK script failed to load:', sdkUrl);
+    };
+    document.head.appendChild(script);
+}
+/** Format one console arg into a loggable string (Errors keep their stack). */
+function fmtConsoleArg(a) {
+    if (typeof a === 'string')
+        return a;
+    if (a instanceof Error)
+        return `${a.message}\n${a.stack ?? ''}`;
+    try {
+        return JSON.stringify(a);
+    }
+    catch {
+        return String(a); // circular / non-serializable
+    }
+}
+let consoleBridged = false;
+/**
+ * Mirror browser `console.*` output into Galileo as logs, so the platform's log
+ * view shows runtime console output (not just auto-captured errors/perf). The
+ * original console still prints to DevTools — we wrap, not replace.
+ *
+ * Which levels forward is controlled by VITE_AEGIS_CONSOLE_LEVELS (comma-sep,
+ * default all: log,info,warn,error,debug; set "off" to disable, or e.g.
+ * "warn,error" to cut volume). console.error → aegis.error; the rest →
+ * aegis.info tagged with the original level.
+ *
+ * Volume note: forwarding ALL console output is high-traffic (engine/React spam)
+ * and bills against Galileo — narrow the levels if it gets noisy.
+ */
+function installConsoleBridge(aegis) {
+    if (consoleBridged)
+        return; // idempotent (StrictMode / re-init guards)
+    const cfg = (import.meta.env.VITE_AEGIS_CONSOLE_LEVELS ?? 'log,info,warn,error,debug').trim();
+    if (cfg === 'off' || cfg === '')
+        return;
+    consoleBridged = true;
+    const wanted = new Set(cfg.split(',').map((s) => s.trim()).filter(Boolean));
+    const methods = ['log', 'info', 'warn', 'error', 'debug'];
+    const c = console;
+    let reentrant = false; // Aegis may itself console.* on send failure — don't loop
+    for (const m of methods) {
+        if (!wanted.has(m))
+            continue;
+        const original = c[m].bind(console);
+        c[m] = (...args) => {
+            original(...args); // always keep DevTools output intact
+            if (reentrant)
+                return;
+            try {
+                const msg = args.map(fmtConsoleArg).join(' ');
+                if (!msg || msg.startsWith('[aegis]'))
+                    return; // skip our own diagnostics
+                reentrant = true;
+                if (m === 'error')
+                    aegis.error({ msg, from: 'console' });
+                else
+                    aegis.info({ msg, from: 'console', consoleLevel: m });
+            }
+            catch {
+                /* never let logging crash the app */
+            }
+            finally {
+                reentrant = false;
+            }
+        };
+    }
+}
+/**
+ * Report a React-render error. React error boundaries swallow render throws
+ * before they reach window.onerror, so Aegis' auto JS-error capture never sees
+ * them — this bridges that gap. No-op until the SDK instance is live (early
+ * pre-load boundary catches are rare and still surface in the console).
+ */
+export function reportError(error, componentStack, scope) {
+    if (!instance)
+        return;
+    try {
+        instance.error({
+            msg: `[${scope ?? 'react'}] ${error.message}`,
+            stack: error.stack ?? '',
+            componentStack: componentStack ?? '',
+        });
+    }
+    catch {
+        /* never let telemetry crash the error path */
+    }
+}
+/**
+ * Attach the current user's id once known. uid is often not available at boot,
+ * so call this after auth/session resolves; Aegis backfills it on every
+ * subsequent report. No-op until the SDK instance is live.
+ */
+export function setAegisUid(uid) {
+    if (!instance || !uid)
+        return;
+    try {
+        instance.setConfig({ uid });
+    }
+    catch {
+        /* no-op */
+    }
+}

package/dist/package/browser/lib/agent-catalog-url.d.ts

@@ -0,0 +1,9 @@
+import { type Locale } from '../i18n';
+/** Current UI locale for Agent Catalog query params. */
+export declare function agentCatalogLang(): Locale;
+/** Build a locale-aligned Agent Catalog query string. */
+export declare function agentCatalogQuery(extra?: Record<string, string | undefined>): string;
+/** Build `/api/agents` with `lang` aligned to Studio locale. */
+export declare function agentCatalogUrl(extra?: Record<string, string | undefined>): string;
+/** Build the locale-aware recent Agent activity URL. */
+export declare function agentEventsRecentUrl(limit?: number): string;

package/dist/package/browser/lib/agent-catalog-url.js

@@ -0,0 +1,24 @@
+import { getLocale } from '../i18n';
+/** Current UI locale for Agent Catalog query params. */
+export function agentCatalogLang() {
+    return getLocale();
+}
+/** Build a locale-aligned Agent Catalog query string. */
+export function agentCatalogQuery(extra) {
+    const params = new URLSearchParams({ lang: getLocale() });
+    if (extra) {
+        for (const [k, v] of Object.entries(extra)) {
+            if (v !== undefined && v !== '')
+                params.set(k, v);
+        }
+    }
+    return params.toString();
+}
+/** Build `/api/agents` with `lang` aligned to Studio locale. */
+export function agentCatalogUrl(extra) {
+    return `/api/agents?${agentCatalogQuery(extra)}`;
+}
+/** Build the locale-aware recent Agent activity URL. */
+export function agentEventsRecentUrl(limit = 30) {
+    return `/api/agents/events/recent?limit=${limit}&lang=${getLocale()}`;
+}

package/dist/package/browser/lib/agent-cli-provider.d.ts

@@ -0,0 +1,10 @@
+/** Map agent manifest `preferredCliProvider` → kernel id used by `/api/cli/chat`.
+ *
+ *  Kernel ids match `packages/orchestrator/src/kernel/*-kernel.ts` and the Composer
+ *  provider picker (`cursor-agent`, `claude-code`, `codex`, …). `null` means
+ *  the forgeax-native EventBus path (no CLI subprocess). */
+export declare function preferredCliProviderToKernel(preferred?: string | null): string | null;
+/** Resolve the CLI kernel id for an agent path/display id (e.g. `cursor-default`). */
+export declare function resolveKernelForAgent(agentId: string): Promise<string | null>;
+/** Test-only: bust the bus agent cache between cases. */
+export declare function _resetAgentCliProviderCacheForTests(): void;

package/dist/package/browser/lib/agent-cli-provider.js

@@ -0,0 +1,81 @@
+/** Map agent manifest `preferredCliProvider` → kernel id used by `/api/cli/chat`.
+ *
+ *  Kernel ids match `packages/orchestrator/src/kernel/*-kernel.ts` and the Composer
+ *  provider picker (`cursor-agent`, `claude-code`, `codex`, …). `null` means
+ *  the forgeax-native EventBus path (no CLI subprocess). */
+import { listExtensionsShared } from './extension-api';
+/** Marketplace cli-provider plugin id → runtime kernel id. */
+const PREFERRED_CLI_TO_KERNEL = {
+    'forgeax-native': null,
+    '@forgeax-plugin/cli-forgeax': null,
+    '@forgeax-plugin/cli-claude-code': 'claude-code',
+    '@forgeax-plugin/cli-bc': 'claude-code',
+    '@forgeax-plugin/cli-codex': 'codex',
+    '@forgeax-plugin/cli-cursor-agent': 'cursor-agent',
+    '@forgeax-plugin/cli-kimi-code': 'kimi-code',
+    '@forgeax-plugin/cli-deepseek-harness': 'deepseek-harness',
+};
+/** Fallback when bus is unavailable (standalone editor / boot race). */
+const AGENT_KERNEL_FALLBACK = {
+    'cursor-default': 'cursor-agent',
+    'codex-default': 'codex',
+    'claude-code-default': 'claude-code',
+    'cc-coder': 'claude-code',
+    'kimi-code-default': 'kimi-code',
+    'deepseek-harness-default': 'deepseek-harness',
+};
+export function preferredCliProviderToKernel(preferred) {
+    const key = preferred?.trim();
+    if (!key)
+        return null;
+    if (key in PREFERRED_CLI_TO_KERNEL)
+        return PREFERRED_CLI_TO_KERNEL[key] ?? null;
+    // Already a kernel id (defensive).
+    if (key === 'claude-code' || key === 'codex' || key === 'cursor-agent' || key === 'codebuddy' || key === 'kimi-code' || key === 'deepseek-harness')
+        return key;
+    return null;
+}
+let agentExtensionsCache = null;
+let agentExtensionsInflight = null;
+async function loadAgentExtensions() {
+    if (agentExtensionsCache)
+        return agentExtensionsCache;
+    if (!agentExtensionsInflight) {
+        agentExtensionsInflight = listExtensionsShared()
+            .then((res) => res.items.filter((p) => p.kind === 'agent'))
+            .then((items) => {
+            agentExtensionsCache = items;
+            agentExtensionsInflight = null;
+            return items;
+        })
+            .catch(() => {
+            agentExtensionsInflight = null;
+            return [];
+        });
+    }
+    return agentExtensionsInflight;
+}
+/** Resolve the CLI kernel id for an agent path/display id (e.g. `cursor-default`). */
+export async function resolveKernelForAgent(agentId) {
+    const key = agentId.trim();
+    if (!key)
+        return null;
+    const plugins = await loadAgentExtensions();
+    const hit = plugins.find((p) => {
+        const id = p.agent?.id;
+        if (!id)
+            return false;
+        if (id === key)
+            return true;
+        return key.startsWith(`${id}#`);
+    });
+    if (hit?.agent?.preferredCliProvider) {
+        return preferredCliProviderToKernel(hit.agent.preferredCliProvider);
+    }
+    return AGENT_KERNEL_FALLBACK[key] ?? null;
+}
+/** Test-only: bust the bus agent cache between cases. */
+export function _resetAgentCliProviderCacheForTests() {
+    agentExtensionsCache = null;
+    agentExtensionsInflight = null;
+}

package/dist/package/browser/lib/ai-intents.d.ts

@@ -0,0 +1,30 @@
+/** ai-intents —— 右键唤 AI(P1-10):把「对这个对象让 AI 做某事」编码成 **detail 带
+ *  指令的 pill** 插进 composer。
+ *
+ *  为什么是 pill 而不是新通道:pill 的 `detail` 本来就是发送时展开给 AI 的文本
+ *  (composer-bridge `expandPills`),把意图模板拼进 detail 就复用了整条既有链路
+ *  (chip 展示 / 队列插入 / chat 包零改动),用户还能在 chip 旁补充说明再发。
+ *
+ *  两个来源:
+ *    1. **kind 专属 intent**(本文件 KIND_INTENTS,按 RefDescriptor.kind 键)+ 通用
+ *       「问 AI 这是什么」兜底——任何可引用单元右键即得;
+ *    2. **从 ActionRegistry derive**:右键落在 `data-fx-action` 元素上时,自动出现
+ *       「让 AI 执行此功能」——零手工维护,注册即得(方案 §3C)。
+ */
+import type { PillPayload } from './composer-bridge';
+export interface AiIntent {
+    /** 菜单显示(会加「AI:」前缀)。 */
+    label: string;
+    /** 把原 pill 加工成带指令的 detail(发送时展开给 AI 的最终文本)。 */
+    buildDetail: (pill: PillPayload) => string;
+}
+/** 给一个可引用单元列出 intent(kind 专属在前,通用兜底在后)。 */
+export declare function aiIntentsFor(refKind: string | undefined): AiIntent[];
+/** 把「原 pill × intent」加工成插 composer 的意图 pill(chip 显示意图名,detail 是完整指令)。 */
+export declare function intentPill(pill: PillPayload, intent: AiIntent): PillPayload;
+/** 从 ActionRegistry derive 的右键项(方案 §3C.2):右键落在 data-fx-action 元素上
+ *  → 「让 AI 执行此功能」。返回 null = 目标不在任何已登记 action 上。 */
+export declare function actionIntentPill(target: Element): {
+    title: string;
+    pill: PillPayload;
+} | null;

package/dist/package/browser/lib/ai-intents.js

@@ -0,0 +1,52 @@
+import { getAction } from './action-registry';
+/** 按 RefDescriptor.kind 的专属 intent(SSOT:每类可引用单元的 AI 动作都列在这里)。 */
+const KIND_INTENTS = {
+    'console-row': [
+        { label: '解释这个报错', buildDetail: (p) => `请解释下面这条游戏控制台输出的含义与可能原因:\n${p.detail}` },
+        { label: '帮我修掉', buildDetail: (p) => `下面这条游戏控制台报错来自当前游戏,请定位原因并修复对应代码:\n${p.detail}` },
+    ],
+    file: [
+        { label: '看看这个文件', buildDetail: (p) => `请读一下这个文件并概述它的职责与关键逻辑:\n${p.detail}` },
+    ],
+    'preview-game': [
+        { label: '给这个游戏提建议', buildDetail: (p) => `请体验性地评审这个游戏(可用 query_world/capture_frame 取真值),给出改进建议:\n${p.detail}` },
+    ],
+};
+const GENERIC_INTENT = {
+    label: '问 AI 这是什么',
+    buildDetail: (p) => `请解释下面引用的这个对象是什么、当前状态如何:\n${p.detail}`,
+};
+/** 给一个可引用单元列出 intent(kind 专属在前,通用兜底在后)。 */
+export function aiIntentsFor(refKind) {
+    return [...(refKind ? (KIND_INTENTS[refKind] ?? []) : []), GENERIC_INTENT];
+}
+/** 把「原 pill × intent」加工成插 composer 的意图 pill(chip 显示意图名,detail 是完整指令)。 */
+export function intentPill(pill, intent) {
+    return {
+        kind: pill.kind,
+        display: `${intent.label}:${pill.display}`,
+        icon: '🤖',
+        detail: intent.buildDetail(pill),
+        tooltip: { title: `🤖 ${intent.label}`, lines: [pill.display] },
+    };
+}
+/** 从 ActionRegistry derive 的右键项(方案 §3C.2):右键落在 data-fx-action 元素上
+ *  → 「让 AI 执行此功能」。返回 null = 目标不在任何已登记 action 上。 */
+export function actionIntentPill(target) {
+    const el = target.closest('[data-fx-action]');
+    const id = el?.dataset.fxAction?.trim();
+    if (!el || !id)
+        return null;
+    const def = getAction(id);
+    const title = def?.title ?? el.dataset.fxTitle?.trim() ?? id;
+    return {
+        title,
+        pill: {
+            kind: 'tool',
+            display: `执行:${title}`,
+            icon: '🤖',
+            detail: `请通过 ui_invoke 执行 UI action "${id}"(${title})。若需要参数,先用 ui_snapshot { detail:'schema', ids:['${id}'] } 查看 schema。`,
+            tooltip: { title: `🤖 让 AI 执行此功能`, lines: [title, id] },
+        },
+    };
+}

package/dist/package/browser/lib/broadcast-stream.d.ts

@@ -0,0 +1,17 @@
+type Frame = {
+    type?: string;
+} & Record<string, unknown>;
+type FrameHandler = (msg: Frame) => void;
+/** boot 时调一次，拉起全页唯一的广播连接。幂等：已连则 no-op。
+ *  @param url 可注入（默认 `${location.host}/ws`）——留一个注入点，方便未来 mock/回放。 */
+export declare function connect(url?: string): void;
+/** 显式断开（一般不用；测试/卸载壳时可用）。 */
+export declare function disconnect(): void;
+/** 订阅某 `type` 的广播帧，返回 unsubscribe。`type='*'` 收全部帧。 */
+export declare function subscribeBroadcast(type: string, handler: FrameHandler): () => void;
+/** 连接状态（调试/健康灯用）。 */
+export declare function getBroadcastStatus(): {
+    connected: boolean;
+    url: string;
+};
+export {};

package/dist/package/browser/lib/broadcast-stream.js

@@ -0,0 +1,163 @@
+// interface 公共广播 WS primitive —— 全页唯一一条 `/ws` 广播连接，按帧 `type` 分发。
+//
+// 设计意图（R5 store 收敛 · WS 归位）：
+//  - 后端在 `/ws`（无 sid）上 broadcast 一批 app-agnostic 帧：`daemon-tick-*`（chat）、
+//    `telemetry`（观测）等 app-agnostic 帧。它们本是**同一条广播流**，
+//    R4 期间被拆成了两条 raw socket（store.connectDaemonWs + chat/daemon-tick.ts）。
+//  - 本 primitive 把它收敛回**一条**：全页单例、按 `msg.type` 字符串分发给订阅者。
+//    它**不认识**任何帧的含义（daemon-tick 归 chat、telemetry 归观测），只做传输 + 分发。
+//  - 「按 type 客户端分发」≠「后端多路复用」：后端本就 broadcast 全部帧，此处零后端改动。
+//
+// 关键纪律：**不在 module-load 自动连**（那是 R4 前 store 的反模式：import 即偷偷开 socket）。
+// 由挂载方 boot 显式调 `connect()` 一次 —— studio 聚合壳 boot 一次；各独立 app boot 各一次。
+// 全页因此只有一条广播 socket。
+//
+// HMR 安全：socket + 订阅表挂 globalThis；模块重求值时不重复建连、不丢订阅。
+const _STREAM_FLAG = '__FORGEAX_BROADCAST_STREAM__';
+const _gt = globalThis;
+const _s = _gt[_STREAM_FLAG] ??
+    (_gt[_STREAM_FLAG] = {
+        ws: null,
+        desired: false,
+        url: '',
+        retryMs: 1000,
+        retryTimer: null,
+        handlers: new Map(),
+    });
+const RECONNECT_MAX_MS = 30_000;
+function defaultUrl() {
+    const proto = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+    return `${proto}//${window.location.host}/ws`;
+}
+function dispatch(msg) {
+    const type = typeof msg.type === 'string' ? msg.type : '';
+    const exact = type ? _s.handlers.get(type) : undefined;
+    const wildcard = _s.handlers.get('*');
+    if (exact) {
+        for (const h of [...exact]) {
+            try {
+                h(msg);
+            }
+            catch (err) {
+                console.warn(`[broadcast-stream] handler "${type}" threw`, err);
+            }
+        }
+    }
+    if (wildcard) {
+        for (const h of [...wildcard]) {
+            try {
+                h(msg);
+            }
+            catch (err) {
+                console.warn('[broadcast-stream] "*" handler threw', err);
+            }
+        }
+    }
+}
+function open() {
+    if (typeof window === 'undefined')
+        return;
+    if (_s.ws && _s.ws.readyState !== WebSocket.CLOSED)
+        return;
+    let ws;
+    try {
+        ws = new WebSocket(_s.url || defaultUrl());
+    }
+    catch {
+        scheduleReconnect();
+        return;
+    }
+    _s.ws = ws;
+    ws.onopen = () => {
+        if (_s.ws !== ws)
+            return;
+        _s.retryMs = 1000;
+    };
+    ws.onmessage = (e) => {
+        if (_s.ws !== ws)
+            return;
+        let obj;
+        try {
+            obj = JSON.parse(typeof e.data === 'string' ? e.data : '');
+        }
+        catch {
+            return;
+        }
+        if (obj && typeof obj === 'object')
+            dispatch(obj);
+    };
+    ws.onclose = () => {
+        if (_s.ws !== ws)
+            return;
+        _s.ws = null;
+        if (_s.desired)
+            scheduleReconnect();
+    };
+    ws.onerror = () => {
+        try {
+            ws.close();
+        }
+        catch { /* ignore */ }
+    };
+}
+function scheduleReconnect() {
+    if (_s.retryTimer !== null)
+        return;
+    if (!_s.desired)
+        return;
+    _s.retryTimer = window.setTimeout(() => {
+        _s.retryTimer = null;
+        _s.retryMs = Math.min(_s.retryMs * 2, RECONNECT_MAX_MS);
+        if (_s.desired)
+            open();
+    }, _s.retryMs);
+}
+/** boot 时调一次，拉起全页唯一的广播连接。幂等：已连则 no-op。
+ *  @param url 可注入（默认 `${location.host}/ws`）——留一个注入点，方便未来 mock/回放。 */
+export function connect(url) {
+    if (typeof window === 'undefined')
+        return;
+    _s.desired = true;
+    if (url)
+        _s.url = url;
+    if (_s.ws && _s.ws.readyState !== WebSocket.CLOSED)
+        return;
+    _s.retryMs = 1000;
+    open();
+}
+/** 显式断开（一般不用；测试/卸载壳时可用）。 */
+export function disconnect() {
+    _s.desired = false;
+    if (_s.retryTimer !== null) {
+        window.clearTimeout(_s.retryTimer);
+        _s.retryTimer = null;
+    }
+    if (_s.ws) {
+        try {
+            _s.ws.close();
+        }
+        catch { /* ignore */ }
+        _s.ws = null;
+    }
+}
+/** 订阅某 `type` 的广播帧，返回 unsubscribe。`type='*'` 收全部帧。 */
+export function subscribeBroadcast(type, handler) {
+    let set = _s.handlers.get(type);
+    if (!set) {
+        set = new Set();
+        _s.handlers.set(type, set);
+    }
+    set.add(handler);
+    return () => {
+        const cur = _s.handlers.get(type);
+        if (cur) {
+            cur.delete(handler);
+            if (cur.size === 0)
+                _s.handlers.delete(type);
+        }
+    };
+}
+/** 连接状态（调试/健康灯用）。 */
+export function getBroadcastStatus() {
+    return { connected: _s.ws?.readyState === WebSocket.OPEN, url: _s.url || (typeof window !== 'undefined' ? defaultUrl() : '') };
+}

package/dist/package/browser/lib/browser-prefs-sync.d.ts

@@ -0,0 +1,16 @@
+/** Persist + restore browser localStorage UI prefs via `/api/prefs/browser-localStorage`.
+ *  Snapshot lands in `.forgeax/prefs/browser-localStorage.json` for export-instance. */
+export declare function captureBrowserLocalStorage(): Record<string, string>;
+export declare function restoreBrowserLocalStorage(entries: Record<string, string>): number;
+/** Push the current localStorage snapshot to the server immediately (no debounce).
+ *  Call after a same-tab pref change that must survive a quick reload — the
+ *  `storage` event only fires in OTHER tabs, so same-tab writes are otherwise
+ *  only flushed on the 30s interval / beforeunload (unreliable). */
+export declare function flushBrowserPrefs(): void;
+/** Pull server snapshot into localStorage. Non-destructive: the snapshot only
+ *  fills keys that are MISSING locally (fresh browser / cleared storage / import
+ *  into a fresh profile). On a normal reload the local value always wins, so a
+ *  same-tab change (e.g. layout reset) is never clobbered by a stale snapshot. */
+export declare function syncBrowserPrefsFromServer(): Promise<number>;
+/** Start periodic + event-driven sync to server (call once from main.tsx). */
+export declare function startBrowserPrefsSync(): void;