@forgeax/interface 0.4.1

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

@@ -0,0 +1,38 @@
+/**
+ * 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().
+ */
+export interface SurfaceAction {
+    id: string;
+    label?: string;
+    args?: unknown;
+    enabled: boolean;
+    hotkey?: string;
+}
+export interface SurfaceState {
+    extensionId: string;
+    surfaceId: string;
+    actions: SurfaceAction[];
+    snapshot: unknown;
+    /** Wall-clock ms when this surface was last refreshed by the plugin. */
+    updatedAt: number;
+}
+type Listener = (snapshot: ReadonlyMap<string, SurfaceState>) => void;
+export declare function upsertSurface(s: SurfaceState): void;
+/** Drop every surface owned by `extensionId`. Call when an iframe unmounts. */
+export declare function removeExtensionSurfaces(extensionId: string): void;
+export declare function listSurfaces(): SurfaceState[];
+export declare function getSurface(extensionId: string, surfaceId: string): SurfaceState | null;
+export declare function subscribeSurfaces(cb: Listener): () => void;
+/** Test helper. */
+export declare function _resetSurfaceStoreForTests(): void;
+export {};

package/dist/package/browser/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();
+}

package/dist/package/browser/lib/surface.d.ts

@@ -0,0 +1,56 @@
+/** 服务端 ui-surfaces.ts 的 JsonSchema 同构, 客户端不强约束. */
+export type JsonSchema = Record<string, unknown>;
+export type UIActionSource = "ai" | "user" | "plugin";
+export interface UISurfaceActionDef<A = unknown> {
+    /** 唯一动作 id (跨 surface 内唯一). */
+    id: string;
+    argsSchema?: JsonSchema;
+    exposedToAI?: boolean;
+    requireConfirm?: boolean;
+    /** Local handler. 玩家 / AI 路径在这里收敛.
+     *  返回值会作为 ack.result 回服务端. throw -> ack.ok=false + error. */
+    run: (args: A, ctx: ActionContext) => unknown | Promise<unknown>;
+}
+export interface ActionContext {
+    /** 来源 'ai' / 'user' / 'plugin' -- handler 可据此决定是否弹确认. */
+    source: UIActionSource;
+    /** AI 路径独有: enqueueAction 给的 token. user 路径为 null. */
+    token: string | null;
+}
+export interface UseSurfaceOptions<S, AMap extends Record<string, UISurfaceActionDef>> {
+    id: string;
+    layer?: "host" | "plugin" | "iframe";
+    schema: JsonSchema;
+    initialSnapshot: S;
+    actions: AMap;
+    /** false -> 整个 surface 不报给 AI (e.g. dev-only debug surface). 默认 true. */
+    exposedToAI?: boolean;
+    /** AI pending action 轮询间隔. <=0 关闭轮询. 默认 1000ms. */
+    pollIntervalMs?: number;
+}
+export interface SurfaceHandle<S, AMap extends Record<string, UISurfaceActionDef>> {
+    /** 当前 snapshot (React state, 触发 re-render). */
+    snapshot: S;
+    /** 主写入入口 -- 调用方更新 state 时调; 同时 PUT 给服务端. */
+    setSnapshot: (next: S | ((prev: S) => S)) => void;
+    /** 玩家 / 本地路径调一个 action. 也是 AI 路径轮询拿到 pending 后内部调的同一函数. */
+    dispatch: <K extends keyof AMap>(action: K, args: Parameters<AMap[K]["run"]>[0]) => Promise<unknown>;
+    /** 服务端是否已确认 register OK (failed register 不阻塞 UI, 但 AI 路径会熄火). */
+    mounted: boolean;
+    /** 最近一次 PUT/POST 错误 (用于 dev banner). */
+    lastError: string | null;
+}
+/**
+ * useSurface -- 把一个 React 组件挂成 UISurface.
+ *
+ * 重要不变量 (DUAL-MODALITY §2.1):
+ *   - DOM event handler 内部必须走 dispatch() 而非 inline setState; 这是把 AI 路径
+ *     提升成一等公民的代价. setSnapshot 只用于"非动作驱动的状态同步"
+ *     (e.g. 外部 store mirror).
+ *   - 每次 setSnapshot 自动 PUT 服务端镜像 (server 是 snapshot 的 source of truth
+ *     for AI; React state 是 source of truth for DOM render).
+ *
+ * 错误处理: register 失败不抛 -- 客户端仍可玩本地, 只是 AI 看不到这个 surface.
+ * lastError 暴露原因, dev banner 可挂.
+ */
+export declare function useSurface<S, AMap extends Record<string, UISurfaceActionDef>>(opts: UseSurfaceOptions<S, AMap>): SurfaceHandle<S, AMap>;

package/dist/package/browser/lib/surface.js

@@ -0,0 +1,225 @@
+// P9.3 — useSurface() hook + thin client around /api/bus/ui/* (server router
+// lives at packages/server/src/api/ui-surfaces.ts).
+//
+// Spec: forgeax-dev-diary/2026-05-16/DUAL-MODALITY-UI.md §四 (4 层物理实现)
+//
+// 双模态 (dual-modality) 收敛点的 React 端实现:
+//   1. mount   useSurface() effect 启动时 POST /surfaces 注册 schema + 初始 snapshot
+//   2. update  调用方每次 state 变化调 setSnapshot() 并 PUT 服务端镜像
+//   3. dispatch DOM event handler 调 dispatch('act', args) 直走本地 actions[act].run
+//   4. ai-path  AI POST /surfaces/:id/action 入队; hook 轮询 /pending 拉走 +
+//               同样调 actions[act].run + POST /ack 上报结果
+//   5. unmount  cleanup -> DELETE /surfaces/:id
+//
+// 注意: 服务端 registry 是 in-mem 单进程; vite dev 重启不掉服务端 -- 我们靠
+// register 时 "re-mount 同 id" 语义 (UISurfaceRegistry.register 检测旧 record,
+// pending 不丢, 走 ui.surface.mounted remount:true) 保证刷新无副作用.
+import { useEffect, useRef, useState, useCallback } from "react";
+/** 本页面的身份。surface id(host.sidebar 等)是"这类界面"的名字,不是"哪个页面"
+ *  的名字 —— 两个 ForgeaX 标签页注册同一个 id、共用同一条 pending 队列和同一份
+ *  snapshot。于是一次 AI 派发落在哪一页是随机的,而回读 snapshot 又必然"验证成功"
+ *  (那份 snapshot 正是执行了动作的那一页 PUT 上来的),工具就会向用户断言一个
+ *  他看不见的变化。轮询时把这个 id 带上,服务端据此数出"现在有几个页面在听",
+ *  >1 时工具改说"无法确认是哪一页动了",而不是继续断言。
+ *
+ *  只做**检测**不做路由:知道有几页 ≠ 知道用户在看哪一页(那需要焦点上报 +
+ *  按页分队列)。先把撒谎那部分干掉。 */
+const PAGE_ID = `p${Math.random().toString(36).slice(2, 9)}`;
+const POLL_INTERVAL_MS = 1000;
+/**
+ * useSurface -- 把一个 React 组件挂成 UISurface.
+ *
+ * 重要不变量 (DUAL-MODALITY §2.1):
+ *   - DOM event handler 内部必须走 dispatch() 而非 inline setState; 这是把 AI 路径
+ *     提升成一等公民的代价. setSnapshot 只用于"非动作驱动的状态同步"
+ *     (e.g. 外部 store mirror).
+ *   - 每次 setSnapshot 自动 PUT 服务端镜像 (server 是 snapshot 的 source of truth
+ *     for AI; React state 是 source of truth for DOM render).
+ *
+ * 错误处理: register 失败不抛 -- 客户端仍可玩本地, 只是 AI 看不到这个 surface.
+ * lastError 暴露原因, dev banner 可挂.
+ */
+export function useSurface(opts) {
+    const { id, layer = "host", schema, initialSnapshot, actions, exposedToAI, pollIntervalMs } = opts;
+    const [snapshot, _setSnapshot] = useState(initialSnapshot);
+    const [mounted, setMounted] = useState(false);
+    const [lastError, setLastError] = useState(null);
+    const snapshotRef = useRef(initialSnapshot);
+    const actionsRef = useRef(actions);
+    // actionsRef 跟随 actions prop (closures 经常引用最新 state) -- 关键: 不要把
+    // actions 进依赖, 否则每次父组件 re-render 都会触发卸载 -> 重新 register, 闪烁.
+    actionsRef.current = actions;
+    // setSnapshot wrapper -- 1) React state 2) snapshot ref 3) PUT 服务端
+    const setSnapshot = useCallback((next) => {
+        _setSnapshot((prev) => {
+            const v = typeof next === "function" ? next(prev) : next;
+            snapshotRef.current = v;
+            // Fire-and-forget; PUT 失败仅写 lastError, 不回滚 React state.
+            void fetch(`/api/bus/ui/surfaces/${encodeURIComponent(id)}/snapshot`, {
+                method: "PUT",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ snapshot: v }),
+            })
+                .then((r) => {
+                if (!r.ok)
+                    setLastError(`PUT snapshot HTTP ${r.status}`);
+                else
+                    setLastError(null);
+            })
+                .catch((e) => setLastError(`PUT snapshot: ${e.message}`));
+            return v;
+        });
+    }, [id]);
+    // dispatch -- DOM 路径 + AI 路径在这里收敛.
+    const dispatch = useCallback(async (action, args) => {
+        const def = actionsRef.current[action];
+        if (!def) {
+            throw new Error(`[useSurface ${id}] unknown action: ${String(action)}`);
+        }
+        // 单门账本对称:AI 路径每步落 ui.surface.action,人路径此前零记录。
+        // handler 已在本地跑,这里只补账 —— fire-and-forget,不挡交互,失败静默
+        // (账本是观测面,不是功能依赖)。
+        void fetch(`/api/bus/ui/surfaces/${encodeURIComponent(id)}/dispatched`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ action: def.id, args }),
+        }).catch(() => { });
+        return await def.run(args, { source: "user", token: null });
+    }, [id]);
+    // register / unregister effect -- 仅依赖 id + layer + schema + exposedToAI.
+    // actions 通过 actionsRef 兜底, 不进依赖.
+    useEffect(() => {
+        let cancelled = false;
+        const body = {
+            id,
+            layer,
+            // 注册即入册:注销要按**在册成员**判定,不能靠"最近有没有轮询"——只读面
+            // (所有 action 对 AI 隐藏)根本不进轮询循环(2026-08-06 外审)。
+            page: PAGE_ID,
+            schema,
+            snapshot: snapshotRef.current,
+            exposedToAI: exposedToAI !== false,
+            actions: Object.values(actionsRef.current).map((a) => ({
+                id: a.id,
+                argsSchema: a.argsSchema,
+                exposedToAI: a.exposedToAI,
+                requireConfirm: a.requireConfirm,
+            })),
+        };
+        fetch("/api/bus/ui/surfaces", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+        })
+            .then((r) => {
+            if (cancelled)
+                return;
+            if (!r.ok) {
+                setLastError(`register HTTP ${r.status}`);
+                setMounted(false);
+            }
+            else {
+                setLastError(null);
+                setMounted(true);
+            }
+        })
+            .catch((e) => {
+            if (!cancelled) {
+                setLastError(`register: ${e.message}`);
+                setMounted(false);
+            }
+        });
+        return () => {
+            cancelled = true;
+            // best-effort DELETE -- 失败不影响 React 卸载.
+            // 按页注销:多个标签页共用同一个 surface id,整删会把别的页面一起弄哑
+            // (2026-08-06 外审 MAJOR)。服务端只在没有其他存活页面时才真正移除记录。
+            void fetch(`/api/bus/ui/surfaces/${encodeURIComponent(id)}?page=${encodeURIComponent(PAGE_ID)}`, { method: "DELETE" }).catch(() => { });
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [id, layer, exposedToAI]);
+    // pending-action polling -- AI 路径的客户端 puller.
+    useEffect(() => {
+        const interval = pollIntervalMs ?? POLL_INTERVAL_MS;
+        if (interval <= 0)
+            return;
+        if (!mounted)
+            return;
+        // A surface whose actions are all hidden from AI has no server-to-client
+        // action path to service. Avoid a permanent empty GET loop for read-only
+        // surfaces such as host.toast; snapshot mirroring still works normally.
+        const hasAiActions = Object.values(actionsRef.current).some((action) => action.exposedToAI !== false);
+        if (!hasAiActions)
+            return;
+        let stopped = false;
+        let timer = null;
+        // 404 backoff -- StrictMode 双 mount / 启动期 race 期间 register POST
+        // 还没落到 server, polling 这边就先看到 404. 默认 1s 间隔会瞬间在 console
+        // 喷一大坨. 收到 404 时退避到 30s, 给 register 留下窗口; 任何 200 立刻
+        // 回到正常 interval.
+        const NOT_FOUND_BACKOFF_MS = 30_000;
+        const tick = async () => {
+            if (stopped)
+                return;
+            let nextDelay = interval;
+            try {
+                const r = await fetch(`/api/bus/ui/surfaces/${encodeURIComponent(id)}/pending?page=${PAGE_ID}`);
+                if (!stopped && r.ok) {
+                    const body = (await r.json());
+                    for (const item of body.items) {
+                        const def = actionsRef.current[item.action];
+                        if (!def) {
+                            // ack as error so server side ledger logs it -- 客户端没这个 action 了
+                            await ack(id, item.token, false, undefined, `client-side unknown action: ${item.action}`);
+                            continue;
+                        }
+                        try {
+                            const result = await def.run(item.args, { source: item.source, token: item.token });
+                            await ack(id, item.token, true, result, undefined);
+                        }
+                        catch (e) {
+                            // 结构化标记随回执上报;丢在这里,下游就只能去错误文案里捞子串。
+                            // **只在为真时才传** —— `=== true` 会把"没有这个属性"变成 false,而 false
+                            // 在协议里意思是"确定没开始执行"(可以安全回落重派),与"未知"后果相反。
+                            // 2026-08-07:这条纪律我在别处写了三遍,却在这一行自己违反了,由新增的
+                            // ack 请求体钉子照出来。
+                            const started = e.started === true ? true : undefined;
+                            await ack(id, item.token, false, undefined, e.message, started);
+                        }
+                    }
+                }
+                else if (!stopped && r.status === 404) {
+                    nextDelay = NOT_FOUND_BACKOFF_MS;
+                }
+            }
+            catch {
+                // 网络抖动: 静默重试; lastError 由 register / snapshot 路径报.
+            }
+            finally {
+                if (!stopped)
+                    timer = setTimeout(tick, nextDelay);
+            }
+        };
+        timer = setTimeout(tick, interval);
+        return () => {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+        };
+    }, [id, mounted, pollIntervalMs]);
+    return { snapshot, setSnapshot, dispatch, mounted, lastError };
+}
+async function ack(id, token, ok, result, error, started) {
+    try {
+        await fetch(`/api/bus/ui/surfaces/${encodeURIComponent(id)}/ack`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            // started 缺省 = **未知**,不能用 false 冒充"确定没开始" —— 消费方据键的有无判断。
+            // (2026-08-07 外审 N3:此前这个信号只活在中文错误文案的子串里,重排一句话就失效。)
+            body: JSON.stringify({ token, ok, result, error, ...(started === undefined ? {} : { started }) }),
+        });
+    }
+    catch {
+        // 静默 -- ack 失败时上层 action 已 run, ledger 拿不到 applied 事件就是结果.
+    }
+}

package/dist/package/browser/lib/surfaceAnchors.d.ts

@@ -0,0 +1,16 @@
+export type SurfaceKind = 'play' | 'edit';
+type AnchorListener = () => void;
+/** Register (el) / unregister (null) the DOM node that marks where `kind`'s
+ *  surface should be drawn. Call from the dockview panel's mount/unmount. */
+export declare function setAnchor(kind: SurfaceKind, el: HTMLElement | null): void;
+export declare function getAnchor(kind: SurfaceKind): HTMLElement | null;
+/** Fires whenever an anchor is added/removed (panel mount/unmount, workspace
+ *  switch, pop-out). The keep-alive layer re-evaluates which surface is visible. */
+export declare function subscribeAnchors(cb: AnchorListener): () => void;
+/** Pure position/size invalidation — anchor identity unchanged but its rect may
+ *  have moved (dock drag/resize/close). DockShell pings this on layout change. */
+export declare function pingAnchorRelayout(): void;
+export declare function subscribeRelayout(cb: AnchorListener): () => void;
+/** Test helper. */
+export declare function _resetSurfaceAnchorsForTests(): void;
+export {};

package/dist/package/browser/lib/surfaceAnchors.js

@@ -0,0 +1,76 @@
+// Surface anchor registry — the bridge between the dockview `preview`/`edit`
+// panels and the always-mounted SurfaceKeepAliveLayer.
+//
+// Why this exists: Play / Edit / AI are separate dockview *workspaces*. Switching
+// tabs rebuilds the whole dock tree (DockShell `api.fromJSON`/`clear+buildDefault`),
+// which would destroy + cold-reboot the heavy Play/Edit viewport iframes on every
+// switch (the freeze). To keep those iframes ALIVE we mount them ONCE in a stable
+// parent outside dockview (SurfaceKeepAliveLayer) and position each one over the
+// place where its dockview panel currently sits. The dockview panel renders only a
+// thin `<SurfaceAnchor>` placeholder that publishes its DOM element here; the layer
+// reads the active anchor's rect and overlays the live surface on top.
+//
+// Same "render-but-hide, never re-parent" idea as KeepAliveExtensionIframes — moving an
+// iframe between DOM parents forces a reload, so the iframe never moves; only its
+// fixed-position rect tracks the anchor.
+const anchors = new Map();
+const anchorListeners = new Set();
+const relayoutListeners = new Set();
+function notifyAnchors() {
+    for (const cb of anchorListeners) {
+        try {
+            cb();
+        }
+        catch (e) {
+            if (typeof console !== 'undefined')
+                console.error('[surfaceAnchors] listener', e);
+        }
+    }
+}
+/** Register (el) / unregister (null) the DOM node that marks where `kind`'s
+ *  surface should be drawn. Call from the dockview panel's mount/unmount. */
+export function setAnchor(kind, el) {
+    if (el) {
+        if (anchors.get(kind) === el)
+            return;
+        anchors.set(kind, el);
+    }
+    else {
+        if (!anchors.has(kind))
+            return;
+        anchors.delete(kind);
+    }
+    notifyAnchors();
+}
+export function getAnchor(kind) {
+    return anchors.get(kind) ?? null;
+}
+/** Fires whenever an anchor is added/removed (panel mount/unmount, workspace
+ *  switch, pop-out). The keep-alive layer re-evaluates which surface is visible. */
+export function subscribeAnchors(cb) {
+    anchorListeners.add(cb);
+    return () => { anchorListeners.delete(cb); };
+}
+/** Pure position/size invalidation — anchor identity unchanged but its rect may
+ *  have moved (dock drag/resize/close). DockShell pings this on layout change. */
+export function pingAnchorRelayout() {
+    for (const cb of relayoutListeners) {
+        try {
+            cb();
+        }
+        catch (e) {
+            if (typeof console !== 'undefined')
+                console.error('[surfaceAnchors] relayout', e);
+        }
+    }
+}
+export function subscribeRelayout(cb) {
+    relayoutListeners.add(cb);
+    return () => { relayoutListeners.delete(cb); };
+}
+/** Test helper. */
+export function _resetSurfaceAnchorsForTests() {
+    anchors.clear();
+    anchorListeners.clear();
+    relayoutListeners.clear();
+}

package/dist/package/browser/lib/surfaceKeepAliveLayout.d.ts

@@ -0,0 +1,7 @@
+/** Map a viewport-space rect onto a keep-alive overlay root's local coordinates. */
+export declare function mapViewportRectToOverlayRoot(viewportRect: DOMRectReadOnly, overlayRoot: HTMLElement | null): {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+};

package/dist/package/browser/lib/surfaceKeepAliveLayout.js

@@ -0,0 +1,12 @@
+/** Map a viewport-space rect onto a keep-alive overlay root's local coordinates. */
+export function mapViewportRectToOverlayRoot(viewportRect, overlayRoot) {
+    const origin = overlayRoot?.getBoundingClientRect();
+    const ox = origin?.left ?? 0;
+    const oy = origin?.top ?? 0;
+    return {
+        top: viewportRect.top - oy,
+        left: viewportRect.left - ox,
+        width: viewportRect.width,
+        height: viewportRect.height,
+    };
+}

package/dist/package/browser/lib/telemetry-test-prelude.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * 单测前置(仅测试用,无生产引用):阻止 store.ts 模块加载时的 daemon-WS 自动连接。
+ *
+ * store.ts 在 `typeof window !== 'undefined'` 下会在模块求值时 `connectDaemonWs(...)`,
+ * happy-dom 里这会留下一个悬挂的重连 setTimeout → 测试帧 teardown 时报
+ * 「AsyncTaskManager has been destroyed」。store 用一个全局 string 旗标
+ * `__FORGEAX_DAEMON_WS_BOUND__` 作「已绑定」判据;在 import store **之前**把它置上,
+ * store 就走「只更新 handler、不再 connect」分支(store.ts:1538-1546)。
+ *
+ * 用法:在任何会(直接或经组件)import 大 store 的测试文件里,把本模块作为**第一个**
+ * side-effect import 放最上面(ESM 按出现顺序求值,确保先于 store)。
+ */
+globalThis.__FORGEAX_DAEMON_WS_BOUND__ ??= { handler: () => { } };

package/dist/package/browser/lib/text-edit-actions.d.ts

@@ -0,0 +1,14 @@
+export type TextEditAction = 'cut' | 'copy' | 'paste' | 'selectAll';
+export interface TextClipboard {
+    readText(): Promise<string>;
+    writeText(text: string): Promise<void>;
+}
+export type NativeTextEditTarget = HTMLInputElement | HTMLTextAreaElement;
+export type TextEditTarget = NativeTextEditTarget | HTMLElement;
+export declare function textEditTargetFrom(target: EventTarget | null): TextEditTarget | null;
+export declare function selectedText(target: TextEditTarget): string;
+/** Preserve the focused editor before a web menu moves DOM focus into its
+ * portalled menu surface. The next text command consumes this snapshot. */
+export declare function captureFocusedTextEditTarget(ownerDocument?: Document): boolean;
+export declare function executeTextEditAction(action: TextEditAction, target: TextEditTarget, clipboard?: TextClipboard | undefined): Promise<boolean>;
+export declare function executeFocusedTextEditAction(action: TextEditAction, ownerDocument?: Document, clipboard?: TextClipboard | undefined): Promise<boolean>;