@forgeax/interface 0.4.1

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

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

@@ -0,0 +1,34 @@
+export interface SpanCtx {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    startTs: number;
+    sid?: string;
+    agentId?: string;
+}
+/** W3C traceparent(sampled flag 固定 01),供下行传播。 */
+export declare function toTraceparent(ctx: SpanCtx): string;
+/** 把攒批的浏览器 span 上传到 server 落盘(best-effort,fire-and-forget,绝不拖垮 UI)。
+ *  turn 结束(chatTurnEnd)+ app.boot 完成时调用。 */
+export declare function flushTelemetryUpload(): void;
+/** First passive Agent-unresponsive warning. Long-running generation is normal. */
+export declare const AGENT_UNRESPONSIVE_TIMEOUT_MS = 600000;
+/** 提交时调用:起 ui.send(root)+ ui.request,返回 ui.request 的 traceparent(放进 POST payload 下行)。
+ *  kernel = 本轮所选内核/provider(失速时标注)。即刻早 flush + 起失速看门狗。 */
+export declare function beginChatTurn(agentId: string, sid?: string, kernel?: string): {
+    traceparent: string;
+};
+/** 首个流式 token(thinking 或 text 皆算):结束 ui.request(=真实 TTFT,含思考前置耗时),
+ *  起 ui.stream(=首 token→turnEnd 的流式耗时)。幂等(text/thinking 两处站点共用,先到先触发)。 */
+export declare function chatFirstToken(agentId: string): void;
+/** Tool results are positive liveness evidence even when no text token exists. */
+export declare function chatToolResult(agentId: string): void;
+/** turn 结束:收尾 ui.request/ui.stream,起 ui.render,rAF 后(真实上屏帧)结束 ui.render + ui.send root。 */
+export declare function chatTurnEnd(agentId: string, outcome: 'ok' | 'cancelled' | 'error', errMessage?: string): void;
+/** 应用启动:起 app.boot root(幂等)。 */
+export declare function beginAppBoot(): void;
+/** 在 app.boot 下包一个同步初始化阶段(如 store-wiring / shell-mount),自动起止 child span。 */
+export declare function appBootSpan<T>(name: string, fn: () => T): T;
+/** 启动完成:收 app.boot root 并上传(app.boot 无 sid → 落 .forgeax/sessions/browser/logs/)。 */
+export declare function endAppBoot(): void;

package/dist/package/browser/lib/trace.js

@@ -0,0 +1,273 @@
+/**
+ * 浏览器轻量 tracer —— 全链路 trace 的浏览器侧(P3)。
+ *
+ * 自建(不复用 Aegis:Aegis 是 Galileo 远端 RUM、traceId 对 app 不可读、无本地模式)。
+ * 产 `TelemetrySpan`(形状镜像 store.ts / @forgeax/types),喂 `pushTelemetry` 进 TelemetryViewer;
+ * 并(P4)经上传通道落 `<project>/.forgeax/sessions/<sid>/logs/`,和后端 span 同 traceId 拼一棵树。
+ *
+ * 链路:浏览器**起 root**(ui.send),把 ui.request 的 W3C traceparent 放进 POST payload 下行 →
+ * 后端 host/kernel/agent/tool 全挂这棵 trace 下;回传的流事件(session-stream)按 agentId 找回本轮
+ * 活动 trace,续建 ui.first-token/ui.stream/ui.turn-end/ui.render(rAF 取真实上屏帧)。
+ * 浏览器自己是 root、自己持 traceId(按 agentId 索引活动 trace),**无需服务端 echo**。
+ */
+import { useShellStore } from '../store';
+import { reportPassiveFeedbackRecovery, reportPassiveFeedbackSignal, } from './passive-feedback';
+// ─── id + 序列化 ──────────────────────────────────────────────────────────
+function randHex(bytes) {
+    const a = new Uint8Array(bytes);
+    const c = globalThis.crypto;
+    if (c?.getRandomValues)
+        c.getRandomValues(a);
+    else
+        for (let i = 0; i < bytes; i++)
+            a[i] = Math.floor(Math.random() * 256);
+    let s = '';
+    for (const b of a)
+        s += b.toString(16).padStart(2, '0');
+    return s;
+}
+const newTraceId = () => randHex(16); // 32 hex
+const newSpanId = () => randHex(8); //  16 hex
+/** W3C traceparent(sampled flag 固定 01),供下行传播。 */
+export function toTraceparent(ctx) {
+    return `00-${ctx.traceId}-${ctx.spanId}-01`;
+}
+// ─── 出口:provisional(start)+ final(end)→ pushTelemetry(本地 viewer)+ 上传 buffer ──
+// 浏览器 span 既进 TelemetryViewer(pushTelemetry,实时),又攒进 uploadBuf,turn 结束时
+// 经 POST /api/telemetry 上传 → server 落项目本地 .forgeax/sessions/<sid>/logs/(与后端 span 同 trace)。
+const uploadBuf = [];
+function emit(span) {
+    try {
+        useShellStore.getState().pushTelemetry([span]);
+    }
+    catch {
+        /* 可观测性绝不拖垮 UI */
+    }
+    uploadBuf.push(span);
+}
+/** 把攒批的浏览器 span 上传到 server 落盘(best-effort,fire-and-forget,绝不拖垮 UI)。
+ *  turn 结束(chatTurnEnd)+ app.boot 完成时调用。 */
+export function flushTelemetryUpload() {
+    if (uploadBuf.length === 0)
+        return;
+    const records = uploadBuf.splice(0);
+    const f = globalThis.fetch;
+    if (!f)
+        return;
+    // 5s 超时:server 若被冻结/无响应(正是 hang 场景),上传不能无限挂起堆积 —— 否则浏览器侧
+    //   也被拖累。超时即放弃这批(它们仍在内存 viewer 里,定位不丢)。
+    const AC = globalThis.AbortController;
+    const ac = AC ? new AC() : undefined;
+    const to = ac ? setTimeout(() => ac.abort(), 5000) : undefined;
+    void f('/api/telemetry', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ records }),
+        ...(ac ? { signal: ac.signal } : {}),
+    })
+        .catch(() => {
+        /* 上传失败不影响本地 viewer 已有的 span */
+    })
+        .finally(() => {
+        if (to)
+            clearTimeout(to);
+    });
+}
+function startSpan(name, o) {
+    const ctx = {
+        traceId: o.traceId,
+        spanId: newSpanId(),
+        name,
+        startTs: Date.now(),
+        ...(o.parentSpanId ? { parentSpanId: o.parentSpanId } : {}),
+        ...(o.sid ? { sid: o.sid } : {}),
+        ...(o.agentId ? { agentId: o.agentId } : {}),
+    };
+    emit({ kind: 'span', ...ctx, provisional: true, ...(o.attrs ? { attrs: o.attrs } : {}) });
+    return ctx;
+}
+function endSpan(ctx, status, attrs) {
+    emit({
+        kind: 'span',
+        traceId: ctx.traceId,
+        spanId: ctx.spanId,
+        ...(ctx.parentSpanId ? { parentSpanId: ctx.parentSpanId } : {}),
+        name: ctx.name,
+        startTs: ctx.startTs,
+        endTs: Date.now(),
+        ...(ctx.sid ? { sid: ctx.sid } : {}),
+        ...(ctx.agentId ? { agentId: ctx.agentId } : {}),
+        ...(status ? { status } : {}),
+        ...(attrs ? { attrs } : {}),
+    });
+}
+const active = new Map();
+// ─── 失速看门狗:浏览器是唯一「永不被冻」的目击者 ──────────────────────────────
+// 后端若卡死/冻结(如 CLI 内核 job-control 冻结整个 server),进程内 trace/log 全失效;
+// 浏览器侧在 AGENT_UNRESPONSIVE_TIMEOUT_MS 内拿不到首 token 就主动报 `ui.stall`(挂 ui.send 下,红点直观)+
+// console.warn(devtools)——把「发送后卡死」从隐形变成有时间戳、带内核名的可见事件。
+/** First passive Agent-unresponsive warning. Long-running generation is normal. */
+export const AGENT_UNRESPONSIVE_TIMEOUT_MS = 600_000;
+function clearStall(a) {
+    if (a.stallTimer !== undefined) {
+        const c = globalThis.clearTimeout;
+        c?.(a.stallTimer);
+        a.stallTimer = undefined;
+    }
+}
+function stallScope(agentId, a) {
+    return { agentId, ...(a.root.sid ? { sid: a.root.sid } : {}) };
+}
+function resolveStall(agentId, a) {
+    const reported = a.stalls > 0;
+    clearStall(a);
+    if (reported) {
+        reportPassiveFeedbackRecovery({ exceptionKey: 'agent-unresponsive', scope: stallScope(agentId, a) });
+    }
+}
+function armStall(agentId) {
+    const setT = globalThis.setTimeout;
+    if (!setT)
+        return;
+    const a = active.get(agentId);
+    if (!a)
+        return;
+    a.stallTimer = setT(() => {
+        // The callback may still run after clearTimeout in a fake timer or a
+        // queued browser task. Clear the handle first, then require identity with
+        // the active turn so an old turn can never report against its replacement.
+        a.stallTimer = undefined;
+        const cur = active.get(agentId);
+        if (cur !== a || cur.firstTokenSeen || cur.ended)
+            return; // 已有响应/已结束 → 不是失速
+        cur.stalls += 1;
+        const waitedMs = AGENT_UNRESPONSIVE_TIMEOUT_MS * cur.stalls;
+        const kernel = cur.kernel ?? 'unknown';
+        const secs = Math.round(waitedMs / 1000);
+        // 作 ui.send 的子 span(viewer 里红点)+ 错误状态;即便 server 冻、上传失败,viewer 仍可见。
+        const s = startSpan('ui.stall', {
+            traceId: cur.traceId,
+            parentSpanId: cur.root.spanId,
+            agentId,
+            sid: cur.root.sid,
+            attrs: { waitedMs, kernel, reason: 'no-first-token' },
+        });
+        endSpan(s, { code: 'error', message: `no response after ${secs}s (kernel=${kernel})` }, { waitedMs, kernel });
+        try {
+            globalThis.console?.warn(`[trace] ui.stall: 已等待 ${secs}s 仍无首 token,kernel=${kernel} sid=${cur.root.sid ?? '-'} —— 后端可能卡死/冻结`);
+        }
+        catch {
+            /* console 不可用不影响 */
+        }
+        reportPassiveFeedbackSignal({
+            code: 'ui.stall',
+            message: `Agent did not respond after ${secs} seconds\nkernel=${kernel}\nsid=${cur.root.sid ?? '-'}`,
+            scope: stallScope(agentId, cur),
+        });
+        flushTelemetryUpload();
+        armStall(agentId); // 继续观察:再过 600s 仍无 → 升级再报(waitedMs 递增)
+    }, AGENT_UNRESPONSIVE_TIMEOUT_MS);
+}
+/** 提交时调用:起 ui.send(root)+ ui.request,返回 ui.request 的 traceparent(放进 POST payload 下行)。
+ *  kernel = 本轮所选内核/provider(失速时标注)。即刻早 flush + 起失速看门狗。 */
+export function beginChatTurn(agentId, sid, kernel) {
+    const traceId = newTraceId();
+    // 同一 agentId 上一轮若从未收口(后端冻死 / WS 断 / turnEnd 丢失),其失速看门狗仍在续命;
+    // 直接 active.set 覆盖会让旧 timer 失去引用却继续每 600s 触发(读到新条目重复报)。
+    // 覆盖前先撤掉旧 timer —— active 因此被收敛到「distinct agentId 数」而非「turn 数」。
+    const prev = active.get(agentId);
+    if (prev)
+        resolveStall(agentId, prev);
+    const root = startSpan('ui.send', { traceId, sid, agentId, ...(kernel ? { attrs: { kernel } } : {}) });
+    const request = startSpan('ui.request', { traceId, parentSpanId: root.spanId, sid, agentId });
+    active.set(agentId, { traceId, root, request, firstTokenSeen: false, ended: false, kernel, stalls: 0 });
+    // 早 flush:provisional ui.send/ui.request 立即落盘(server 活着时)—— 即便随后卡死,
+    //   trace 里也留有「起了但没结束」的可见痕迹(配合失速 span 一起定位)。
+    flushTelemetryUpload();
+    armStall(agentId); // 失速看门狗:600s 内无首 token → 报 ui.stall。
+    return { traceparent: toTraceparent(request) };
+}
+/** 首个流式 token(thinking 或 text 皆算):结束 ui.request(=真实 TTFT,含思考前置耗时),
+ *  起 ui.stream(=首 token→turnEnd 的流式耗时)。幂等(text/thinking 两处站点共用,先到先触发)。 */
+export function chatFirstToken(agentId) {
+    const a = active.get(agentId);
+    if (!a || a.firstTokenSeen)
+        return;
+    a.firstTokenSeen = true;
+    resolveStall(agentId, a); // 有响应了 → 撤销失速看门狗并收掉旧告警
+    if (a.request)
+        endSpan(a.request, { code: 'ok' });
+    a.stream = startSpan('ui.stream', { traceId: a.traceId, parentSpanId: a.root.spanId, agentId, sid: a.root.sid });
+}
+/** Tool results are positive liveness evidence even when no text token exists. */
+export function chatToolResult(agentId) {
+    const a = active.get(agentId);
+    if (!a || a.ended)
+        return;
+    resolveStall(agentId, a);
+}
+/** turn 结束:收尾 ui.request/ui.stream,起 ui.render,rAF 后(真实上屏帧)结束 ui.render + ui.send root。 */
+export function chatTurnEnd(agentId, outcome, errMessage) {
+    const a = active.get(agentId);
+    if (!a || a.ended)
+        return;
+    a.ended = true;
+    resolveStall(agentId, a); // 轮结束 → 撤销失速看门狗并收掉旧告警
+    // 三值而不是布尔:取消**不算错误**(标成 error,错误率里就全是用户主动停的假失败),
+    // 但也不能就此与成功同形 —— 那等于亲手销毁取消信号,误触取消风暴在监控里会和健康流量
+    // 一模一样。所以 status 走 ok,取消另由下面 rootAttrs 的 cancelled 位留痕。
+    const status = outcome === 'error' ? { code: 'error', ...(errMessage ? { message: errMessage } : {}) } : { code: 'ok' };
+    if (a.request && !a.firstTokenSeen)
+        endSpan(a.request, status); // 无 token 直接结束的退化轮
+    if (a.stream)
+        endSpan(a.stream, status);
+    const render = startSpan('ui.render', { traceId: a.traceId, parentSpanId: a.root.spanId, agentId, sid: a.root.sid });
+    const finish = (hidden) => {
+        // hidden=true:标签页失焦时浏览器会暂停 rAF → 不等真实绘制帧、立即收口并标 paintDeferred,
+        //   否则 ui.render / ui.send 会被「标签页多久才回前台」污染成几十秒的假耗时(不是渲染慢)。
+        const rootAttrs = {
+            ...(a.kernel ? { kernel: a.kernel } : {}),
+            ...(outcome === 'cancelled' ? { cancelled: true } : {}), // 取消可审计:与成功区分开
+            ...(hidden ? { paintDeferred: true } : {}),
+        };
+        const renderAttrs = hidden ? { paintDeferred: true } : undefined;
+        endSpan(render, status, renderAttrs); // 上屏完成(或失焦延后)
+        endSpan(a.root, status, Object.keys(rootAttrs).length ? rootAttrs : undefined); // 整轮(ui.send)结束(保留 kernel)
+        active.delete(agentId);
+        flushTelemetryUpload(); // 本轮全部 span 上传 → 落项目 .forgeax
+    };
+    const doc = globalThis.document;
+    const raf = globalThis.requestAnimationFrame;
+    if (doc?.visibilityState === 'hidden' || !raf)
+        finish(doc?.visibilityState === 'hidden');
+    else
+        raf(() => finish(false));
+}
+// ─── app.boot:应用初始化 trace(纯浏览器,无跨进程)──────────────────────────
+let bootRoot = null;
+/** 应用启动:起 app.boot root(幂等)。 */
+export function beginAppBoot() {
+    if (bootRoot)
+        return;
+    bootRoot = startSpan('app.boot', { traceId: newTraceId(), agentId: 'shell' });
+}
+/** 在 app.boot 下包一个同步初始化阶段(如 store-wiring / shell-mount),自动起止 child span。 */
+export function appBootSpan(name, fn) {
+    if (!bootRoot)
+        return fn();
+    const s = startSpan(name, { traceId: bootRoot.traceId, parentSpanId: bootRoot.spanId, agentId: 'shell' });
+    try {
+        return fn();
+    }
+    finally {
+        endSpan(s, { code: 'ok' });
+    }
+}
+/** 启动完成:收 app.boot root 并上传(app.boot 无 sid → 落 .forgeax/sessions/browser/logs/)。 */
+export function endAppBoot() {
+    if (!bootRoot)
+        return;
+    endSpan(bootRoot, { code: 'ok' });
+    bootRoot = null;
+    flushTelemetryUpload();
+}

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

@@ -0,0 +1,4 @@
+/** True if `origin` is the shell's own origin, or (dev only) a localhost port.
+ *  Also accepts private-network origins (10.x / 172.16-31.x / 192.168.x) so
+ *  WSL2 forwarded addresses work without opening the gate to the public web. */
+export declare function isTrustedMessageOrigin(origin: string): boolean;

package/dist/package/browser/lib/trustedOrigins.js

@@ -0,0 +1,36 @@
+// Origin gate for cross-iframe `message` receivers in the shell.
+//
+// The interface embeds child iframes (engine Play :15173 / Edit :15280, plugin
+// panels) and receives postMessage from them. Receivers historically did NO
+// origin check, so any foreign page/iframe sharing the message bus could inject
+// VAG_* / health / context-menu / navigate events. This helper is the shell's
+// trust boundary.
+//
+// Kept interface-LOCAL on purpose: `packages/interface` keeps ZERO `@forgeax/editor*`
+// imports (an architectural invariant — see App.tsx / healthBridge.ts / panelRenderers),
+// so we cannot reuse the editor protocol's `allowedParentOrigins`. The rule:
+//   - PROD: studio is single-origin (:18920 proxies /preview + /editor) → strict
+//     same-origin. A non-same-origin message in prod is foreign → reject.
+//   - DEV (split-port): engine/editor run on localhost ports → allow localhost /
+//     127.0.0.1 origins so split-dev keeps working.
+/** True if `origin` is the shell's own origin, or (dev only) a localhost port.
+ *  Also accepts private-network origins (10.x / 172.16-31.x / 192.168.x) so
+ *  WSL2 forwarded addresses work without opening the gate to the public web. */
+export function isTrustedMessageOrigin(origin) {
+    try {
+        if (origin === window.location.origin)
+            return true;
+    }
+    catch { /* no window.location */ }
+    if (import.meta.env.DEV) {
+        try {
+            const host = new URL(origin).hostname;
+            if (host === 'localhost' || host === '127.0.0.1' || host === '[::1]')
+                return true;
+            if (/^(10\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.)/.test(host))
+                return true;
+        }
+        catch { /* opaque/empty origin */ }
+    }
+    return false;
+}

package/dist/package/browser/lib/ui-action-highlight.d.ts

@@ -0,0 +1,2 @@
+/** bootUiBridge 调用一次(幂等)。 */
+export declare function installUiActionHighlight(): void;

package/dist/package/browser/lib/ui-action-highlight.js

@@ -0,0 +1,93 @@
+/** ui-action-highlight —— AI 操作可视化(P1-11,ghost 高亮层)。
+ *
+ *  消费 action-registry 派发时发出的 `UI_ACTION_DISPATCH_EVENT`(source:'ai'):
+ *    - 目标是 data-fx-action 绑定的元素 → 元素闪高亮(outline 脉冲);
+ *    - 编程式 action(无对应元素)→ 右下角浮标「AI 正在:<title>」,自动淡出。
+ *
+ *  纯 DOM overlay,零 store 依赖,装不上(SSR)静默跳过;观测层绝不影响派发主流程。
+ */
+import { installCustomEventObservation } from '@forgeax/app-shell/react';
+import { UI_ACTION_DISPATCH_EVENT, getAction } from './action-registry';
+const STYLE_ID = 'fx-ui-action-highlight-style';
+const BADGE_ID = 'fx-ui-action-badge';
+const HIGHLIGHT_CSS = `
+@keyframes fx-ai-pulse {
+  0% { outline-color: rgba(99, 102, 241, 0.95); outline-offset: 1px; }
+  100% { outline-color: rgba(99, 102, 241, 0); outline-offset: 6px; }
+}
+.fx-ai-highlight { outline: 2px solid rgba(99, 102, 241, 0.95); animation: fx-ai-pulse 1.2s ease-out 2; border-radius: 4px; }
+#${BADGE_ID} {
+  position: fixed; right: 16px; bottom: 16px; z-index: 2147483000;
+  background: rgba(30, 30, 46, 0.92); color: #e0e0ff; font-size: 12px;
+  padding: 6px 10px; border-radius: 8px; border: 1px solid rgba(99, 102, 241, 0.6);
+  pointer-events: none; transition: opacity 0.4s ease; opacity: 0;
+}
+`;
+function ensureStyle() {
+    if (document.getElementById(STYLE_ID))
+        return;
+    const style = document.createElement('style');
+    style.id = STYLE_ID;
+    style.textContent = HIGHLIGHT_CSS;
+    document.head.appendChild(style);
+}
+let badgeTimer = null;
+function showBadge(text) {
+    let badge = document.getElementById(BADGE_ID);
+    if (!badge) {
+        badge = document.createElement('div');
+        badge.id = BADGE_ID;
+        document.body.appendChild(badge);
+    }
+    badge.textContent = text;
+    badge.style.opacity = '1';
+    if (badgeTimer)
+        clearTimeout(badgeTimer);
+    badgeTimer = setTimeout(() => {
+        badge.style.opacity = '0';
+    }, 2_500);
+}
+function flashElement(el) {
+    el.classList.remove('fx-ai-highlight');
+    // 强制 reflow 让同元素连续两次派发都能重播动画。
+    void el.offsetWidth;
+    el.classList.add('fx-ai-highlight');
+    setTimeout(() => el.classList.remove('fx-ai-highlight'), 2_600);
+}
+let installed = false;
+/** bootUiBridge 调用一次(幂等)。 */
+export function installUiActionHighlight() {
+    if (installed || typeof document === 'undefined')
+        return;
+    installed = true;
+    ensureStyle();
+    const onUiActionDispatch = (e) => {
+        const detail = e.detail;
+        if (!detail || detail.source !== 'ai' || !detail.id)
+            return; // 人类操作不标注
+        try {
+            const el = document.querySelector(`[data-fx-action="${CSS_escape(detail.id)}"]`);
+            const title = getAction(detail.id)?.title ?? detail.id;
+            if (el && el.isConnected)
+                flashElement(el);
+            showBadge(`AI 正在:${title}`);
+        }
+        catch {
+            /* 观测层绝不影响主流程 */
+        }
+    };
+    void installCustomEventObservation({
+        target: window,
+        eventType: UI_ACTION_DISPATCH_EVENT,
+        onEvent: onUiActionDispatch,
+    });
+}
+/** CSS.escape 兜底(老 WebView 可能缺)。 */
+function CSS_escape(s) {
+    try {
+        return CSS.escape(s);
+    }
+    catch {
+        return s.replace(/["\\\]]/g, '\\$&');
+    }
+}

package/dist/package/browser/lib/ui-bridge.d.ts

@@ -0,0 +1,2 @@
+/** main.tsx 调用一次(幂等):登记内置 action + DOM 发现 + lease 生命周期 + 查询应答。 */
+export declare function bootUiBridge(): void;