@forgeax/interface 0.4.1

package/dist/package/node/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/node/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/node/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/node/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/node/lib/text-edit-actions.js

@@ -0,0 +1,184 @@
+const capturedTargets = new WeakMap();
+const NON_TEXT_INPUT_TYPES = new Set([
+    'button', 'checkbox', 'color', 'file', 'hidden', 'image', 'radio', 'range',
+    'reset', 'submit',
+]);
+export function textEditTargetFrom(target) {
+    if (!(target instanceof Element))
+        return null;
+    const candidate = target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement
+        ? target
+        : target.closest('input, textarea');
+    if (candidate instanceof HTMLTextAreaElement)
+        return candidate;
+    if (candidate instanceof HTMLInputElement && !NON_TEXT_INPUT_TYPES.has(candidate.type))
+        return candidate;
+    const editable = target.closest('[contenteditable]:not([contenteditable="false"])');
+    return editable instanceof HTMLElement ? editable : null;
+}
+export function selectedText(target) {
+    if (!(target instanceof HTMLInputElement) && !(target instanceof HTMLTextAreaElement)) {
+        const selection = target.ownerDocument.getSelection();
+        if (!selection || selection.rangeCount === 0)
+            return '';
+        const range = selection.getRangeAt(0);
+        return rangeBelongsTo(range, target) ? selection.toString() : '';
+    }
+    const start = target.selectionStart;
+    const end = target.selectionEnd;
+    return typeof start === 'number' && typeof end === 'number'
+        ? target.value.slice(start, end)
+        : '';
+}
+function setNativeValue(target, value) {
+    const prototype = target instanceof HTMLTextAreaElement
+        ? HTMLTextAreaElement.prototype
+        : HTMLInputElement.prototype;
+    const setter = Object.getOwnPropertyDescriptor(prototype, 'value')?.set;
+    if (setter)
+        setter.call(target, value);
+    else
+        target.value = value;
+}
+function replaceNativeSelection(target, inserted) {
+    const start = target.selectionStart ?? target.value.length;
+    const end = target.selectionEnd ?? target.value.length;
+    const nextValue = target.value.slice(0, start) + inserted + target.value.slice(end);
+    setNativeValue(target, nextValue);
+    const caret = start + inserted.length;
+    try {
+        target.setSelectionRange(caret, caret);
+    }
+    catch { /* unsupported input type */ }
+    target.dispatchEvent(new Event('input', { bubbles: true }));
+    target.focus();
+}
+function rangeBelongsTo(range, target) {
+    const container = range.commonAncestorContainer;
+    return container === target || target.contains(container);
+}
+function selectionRangeFor(target) {
+    const ownerDocument = target.ownerDocument;
+    const selection = ownerDocument.getSelection();
+    if (selection && selection.rangeCount > 0) {
+        const current = selection.getRangeAt(0);
+        if (rangeBelongsTo(current, target))
+            return current;
+    }
+    const range = ownerDocument.createRange();
+    range.selectNodeContents(target);
+    range.collapse(false);
+    return range;
+}
+function replaceContentEditableSelection(target, inserted) {
+    target.focus();
+    const selection = target.ownerDocument.getSelection();
+    const range = selectionRangeFor(target);
+    range.deleteContents();
+    if (inserted.length > 0) {
+        const text = target.ownerDocument.createTextNode(inserted);
+        range.insertNode(text);
+        range.setStartAfter(text);
+    }
+    range.collapse(true);
+    selection?.removeAllRanges();
+    selection?.addRange(range);
+    target.dispatchEvent(new Event('input', { bubbles: true }));
+}
+function replaceSelection(target, inserted) {
+    if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) {
+        replaceNativeSelection(target, inserted);
+        return;
+    }
+    replaceContentEditableSelection(target, inserted);
+}
+function selectAllText(target) {
+    target.focus();
+    if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) {
+        try {
+            target.setSelectionRange(0, target.value.length);
+        }
+        catch {
+            target.select();
+        }
+        return;
+    }
+    const selection = target.ownerDocument.getSelection();
+    const range = target.ownerDocument.createRange();
+    range.selectNodeContents(target);
+    selection?.removeAllRanges();
+    selection?.addRange(range);
+}
+function captureTarget(target) {
+    if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) {
+        return {
+            target,
+            selectionStart: target.selectionStart,
+            selectionEnd: target.selectionEnd,
+        };
+    }
+    const selection = target.ownerDocument.getSelection();
+    const range = selection && selection.rangeCount > 0 && rangeBelongsTo(selection.getRangeAt(0), target)
+        ? selection.getRangeAt(0).cloneRange()
+        : undefined;
+    return { target, range };
+}
+function restoreTarget(captured) {
+    const { target } = captured;
+    if (!target.isConnected)
+        return null;
+    target.focus();
+    if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) {
+        if (typeof captured.selectionStart === 'number' && typeof captured.selectionEnd === 'number') {
+            try {
+                target.setSelectionRange(captured.selectionStart, captured.selectionEnd);
+            }
+            catch { /* unsupported input type */ }
+        }
+        return target;
+    }
+    if (captured.range) {
+        const selection = target.ownerDocument.getSelection();
+        selection?.removeAllRanges();
+        selection?.addRange(captured.range);
+    }
+    return target;
+}
+/** Preserve the focused editor before a web menu moves DOM focus into its
+ * portalled menu surface. The next text command consumes this snapshot. */
+export function captureFocusedTextEditTarget(ownerDocument = document) {
+    const target = textEditTargetFrom(ownerDocument.activeElement);
+    if (!target) {
+        capturedTargets.delete(ownerDocument);
+        return false;
+    }
+    capturedTargets.set(ownerDocument, captureTarget(target));
+    return true;
+}
+export async function executeTextEditAction(action, target, clipboard = navigator.clipboard) {
+    if (action === 'selectAll') {
+        selectAllText(target);
+        return true;
+    }
+    if (!clipboard)
+        return false;
+    if (action === 'copy') {
+        await clipboard.writeText(selectedText(target));
+        return true;
+    }
+    if (action === 'cut') {
+        await clipboard.writeText(selectedText(target));
+        replaceSelection(target, '');
+        return true;
+    }
+    replaceSelection(target, await clipboard.readText());
+    return true;
+}
+export async function executeFocusedTextEditAction(action, ownerDocument = document, clipboard = navigator.clipboard) {
+    const activeTarget = textEditTargetFrom(ownerDocument.activeElement);
+    const captured = activeTarget ? undefined : capturedTargets.get(ownerDocument);
+    if (captured)
+        capturedTargets.delete(ownerDocument);
+    const target = activeTarget ?? (captured ? restoreTarget(captured) : null);
+    return target ? executeTextEditAction(action, target, clipboard) : false;
+}