@forgeax/interface 0.4.1

package/dist/package/browser/lib/ui-bridge.js

@@ -0,0 +1,224 @@
+/** ui-bridge —— UI 语义操作层的 interface 侧运输层:lease + manifest push + ui_* 应答。
+ *
+ *  对端(编排层 @forgeax/orchestrator):
+ *    - POST /:sid/ui-lease       获焦 acquire / 心跳续期(displace 语义,「最后获焦 tab」持有)
+ *    - POST /:sid/ui-manifest    registry 变更时 push 可序列化 manifest(**必须持 lease**——
+ *                                manifest 是 trust-gate 的权限输入,声明与执行方必须同源)
+ *    - perception:query(WS)     kind = ui_snapshot / ui_invoke / ui_screenshot → 本模块应答
+ *    - POST /:sid/perception-reply  带 leaseId 回灌(server 校验;非持有者的回灌被拒)
+ *
+ *  多标签规则(评审 2.7,P0 定死):最后获焦的 tab 持 lease,WS 心跳续期;收到 ui_* 查询
+ *  且本 tab 可见而无 lease 时机会式 acquire(单 tab 断续场景自愈;两 tab 同可见时后
+ *  acquire 者胜,server 只认现任 leaseId,不会双应答)。
+ */
+import { installWindowMessageObservation } from '@forgeax/app-shell/react';
+import { getSessionClient, hasSessionClient } from '../store-parts/session-client';
+import { buildManifest, dispatchAction, onRegistryChange, snapshotActions, snapshotState, } from './action-registry';
+import { registerBuiltinActions } from './builtin-actions';
+import { startActionDomDiscovery } from './action-dom-discovery';
+import { installUiActionHighlight } from './ui-action-highlight';
+import { installVagActionBridge } from './vag-action-bridge';
+import { buildA11ySummary } from './a11y-summary';
+import { captureUiScreenshot } from './ui-screenshot';
+import { isTrustedMessageOrigin } from './trustedOrigins';
+import { useShellStore } from '../store';
+const clientId = (() => {
+    try {
+        return crypto.randomUUID();
+    }
+    catch {
+        return `tab-${Math.random().toString(36).slice(2)}`;
+    }
+})();
+const leases = new Map();
+/** 见过的 sid(store activeSid + 收到过 ui_* 查询的)——心跳续期的范围。 */
+const knownSids = new Set();
+function holdingLease(sid) {
+    const l = leases.get(sid);
+    return l && l.expiresAt > Date.now() ? l.leaseId : null;
+}
+async function acquireLease(sid, opts = {}) {
+    try {
+        const r = await fetch(`/api/sessions/${encodeURIComponent(sid)}/ui-lease`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ clientId }),
+        });
+        const j = (await r.json().catch(() => ({})));
+        if (!j.ok || typeof j.leaseId !== 'string')
+            return null;
+        leases.set(sid, { leaseId: j.leaseId, expiresAt: Date.now() + (j.ttlMs ?? 30_000) });
+        knownSids.add(sid);
+        // 每次 acquire 成功都重推 manifest(幂等整表替换,payload 很小)。顺序约束:trust-gate
+        // 的查表在 invoke 往返**之前**发生,manifest 必须先于第一次 ui_invoke 到位,否则
+        // fail-closed ask;「只在首次推」曾在会话切换场景留下一次竞态缺口(e2e Test D),
+        // 无条件重推把这类缺口整类消掉。skipPush 防 pushManifest→acquireLease 递归。
+        if (!opts.skipPush)
+            void pushManifest(sid);
+        return j.leaseId;
+    }
+    catch {
+        return null;
+    }
+}
+async function pushManifest(sid) {
+    const leaseId = holdingLease(sid) ?? (await acquireLease(sid, { skipPush: true }));
+    if (!leaseId)
+        return; // 拿不到 lease(别的 tab 持有)→ 不推,由持有者推
+    try {
+        await fetch(`/api/sessions/${encodeURIComponent(sid)}/ui-manifest`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ leaseId, actions: buildManifest() }),
+        });
+    }
+    catch {
+        /* fail-soft:下次 registry 变更 / lease 续期再推 */
+    }
+}
+async function answerUiQuery(evt) {
+    if (evt.event.type !== 'perception:query')
+        return;
+    const p = evt.event.payload;
+    const kind = p.kind;
+    if (kind !== 'ui_snapshot' && kind !== 'ui_invoke' && kind !== 'ui_screenshot')
+        return; // world/frame 归 preview surface
+    if (typeof p.reqId !== 'string')
+        return;
+    const sid = evt.sid;
+    knownSids.add(sid);
+    // lease 检查:非持有者不应答。本 tab 可见而无 lease → 机会式 acquire(displace)。
+    let leaseId = holdingLease(sid);
+    if (!leaseId && typeof document !== 'undefined' && document.visibilityState === 'visible') {
+        leaseId = await acquireLease(sid);
+    }
+    if (!leaseId)
+        return;
+    let snapshot;
+    if (kind === 'ui_snapshot') {
+        const q = (p.query ?? {});
+        const detail = typeof q.detail === 'string' ? q.detail : undefined;
+        snapshot = {
+            actions: snapshotActions(detail, Array.isArray(q.ids) ? q.ids.filter((x) => typeof x === 'string') : undefined),
+            state: snapshotState(),
+            // P1-13 a11y 兜底:未注册区域的只读定向摘要(detail:'a11y' 按需拉,默认不带)。
+            ...(detail === 'a11y' ? { a11y: buildA11ySummary() } : {}),
+        };
+    }
+    else if (kind === 'ui_screenshot') {
+        // P3 兜底证据:DOM→canvas 栅格化(失败 fail-soft captured:false,见 ui-screenshot.ts)。
+        snapshot = await captureUiScreenshot(p.query);
+    }
+    else {
+        const q = (p.query ?? {});
+        if (typeof q.actionId !== 'string' || !q.actionId) {
+            snapshot = { status: 'rejected', reason: 'ui_invoke requires actionId (string)' };
+        }
+        else {
+            snapshot = await dispatchAction(q.actionId, q.args && typeof q.args === 'object' ? q.args : {}, { source: 'ai' });
+        }
+    }
+    try {
+        await fetch(`/api/sessions/${encodeURIComponent(sid)}/perception-reply`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ reqId: p.reqId, snapshot, leaseId }),
+        });
+    }
+    catch {
+        /* fail-soft:server 侧超时兜底 */
+    }
+}
+// ─── 全局快捷键的 iframe→host 接收器(todo 004)──────────────────────────────
+// 焦点在 iframe 内时,命令面板(⌘K)/ useGlobalShortcuts 的顶层监听拿不到按键。
+// 各 iframe 内装 `installShortcutForwarder`（权威在 @forgeax/extension-platform/transport，消费方 vendor）
+// 把白名单键 postMessage 上来;此处校验 origin 后在顶层重放 → 现有监听自动统一处理。
+// 常量与 Extension Platform transport 的 shortcut forwarder 保持一致；
+// Interface 不静态依赖 transport 实现，因此在边界内联。
+const FORGEAX_FORWARD_KEY = 'FORGEAX_FORWARD_KEY';
+let shortcutReceiverInstalled = false;
+function installShortcutReceiver() {
+    if (shortcutReceiverInstalled || typeof window === 'undefined')
+        return;
+    shortcutReceiverInstalled = true;
+    const onMessage = (e) => {
+        if (!isTrustedMessageOrigin(e.origin) || !e.data || typeof e.data !== 'object')
+            return;
+        const d = e.data;
+        if (d.type !== FORGEAX_FORWARD_KEY || typeof d.key !== 'string')
+            return;
+        // 在顶层重放 keydown → CommandPalette(window keydown)+ useGlobalShortcuts(capture)
+        // 都在 window 上监听,dispatch 到 window 即 AT_TARGET 触发两者。合成事件 target=window,
+        // isTypingTarget 返回 false,故 Esc / Ctrl+/ 等 allowInInput 键也照常。
+        window.dispatchEvent(new KeyboardEvent('keydown', {
+            key: d.key,
+            code: typeof d.code === 'string' ? d.code : '',
+            keyCode: typeof d.keyCode === 'number' ? d.keyCode : 0,
+            metaKey: !!d.metaKey,
+            ctrlKey: !!d.ctrlKey,
+            shiftKey: !!d.shiftKey,
+            altKey: !!d.altKey,
+            bubbles: true,
+            cancelable: true,
+        }));
+    };
+    void installWindowMessageObservation({ target: window, onMessage });
+}
+// ─── boot ───────────────────────────────────────────────────────────────────
+let booted = false;
+let repushTimer = null;
+/** main.tsx 调用一次(幂等):登记内置 action + DOM 发现 + lease 生命周期 + 查询应答。 */
+export function bootUiBridge() {
+    if (booted || typeof window === 'undefined')
+        return;
+    booted = true;
+    registerBuiltinActions();
+    startActionDomDiscovery();
+    installUiActionHighlight(); // P1-11:AI 派发时闪高亮 / 浮标
+    installVagActionBridge(); // P1-12:iframe 内 action 经 VAG_ACTION_* 接入注册表
+    installShortcutReceiver(); // todo 004:iframe 内全局快捷键(⌘K 等)转发上来,顶层重放
+    // ui_* 查询应答(onSessionEvent 按 key 幂等,HMR 安全;world/frame 由 perception-stream 继续中转)。
+    if (hasSessionClient()) {
+        getSessionClient().onSessionEvent('ui-bridge', (evt) => void answerUiQuery(evt));
+    }
+    // registry 变更 → debounce 重推 manifest(只推本 tab 持 lease 的 sid)。
+    onRegistryChange(() => {
+        if (repushTimer)
+            clearTimeout(repushTimer);
+        repushTimer = setTimeout(() => {
+            repushTimer = null;
+            for (const sid of knownSids)
+                if (holdingLease(sid))
+                    void pushManifest(sid);
+        }, 300);
+    });
+    // 获焦 / 可见 → acquire(displace:「最后获焦 tab」成为权威 surface)。
+    const onFocus = () => {
+        const sid = useShellStore.getState().activeSid;
+        if (sid)
+            void acquireLease(sid);
+    };
+    window.addEventListener('focus', onFocus);
+    document.addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'visible')
+            onFocus();
+    });
+    // activeSid 变化 → 对新会话建 lease + 推 manifest。
+    let lastSid = null;
+    useShellStore.subscribe((state) => {
+        const sid = state.activeSid ?? null;
+        if (sid && sid !== lastSid) {
+            lastSid = sid;
+            void acquireLease(sid);
+        }
+    });
+    onFocus(); // boot 时若已可见,立即建 lease
+    // 心跳续期(TTL 30s → 每 10s;仅本 tab 可见时续,失焦让位给获焦 tab)。
+    setInterval(() => {
+        if (document.visibilityState !== 'visible')
+            return;
+        for (const sid of knownSids)
+            if (holdingLease(sid))
+                void acquireLease(sid);
+    }, 10_000);
+}

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

@@ -0,0 +1,31 @@
+/** ui-screenshot —— `ui_screenshot`(方案 P3)的 interface 侧应答:web 形态 DOM→canvas
+ *  兜底截屏(零依赖,foreignObject 栅格化路线)。
+ *
+ *  定位是**兜底证据,不是主感知通道**(主通道 = ui_snapshot 的文本 manifest + 状态摘要),
+ *  故一切失败都 fail-soft 成 `{ captured:false, reason }`(契约 description 已叮嘱模型
+ *  勿重试)。已知呈现局限(SVG-as-image 上下文**不加载任何外部资源**):
+ *  - webfont 回退系统字体;<img> / 跨源 iframe / GPU 合成 canvas 呈空白;
+ *  - WebKit(桌面 WKWebView)对 foreignObject→canvas 有已知渲染缺陷 → 大概率走
+ *    fail-soft 分支;Tauri 原生截屏是后续增强(方案 P3 注)。
+ *
+ *  target 解析:'app'(默认)= document.body;'panel:<id>' = DockPanelHost 的结构标记
+ *  `[data-fx-slot="DockPanel:<id>"]`(其外壳 display:contents 量不出 rect,故实际
+ *  量测/序列化首个元素子节点)。
+ */
+export interface ScreenshotOk {
+    dataUrl: string;
+    width: number;
+    height: number;
+    target: string;
+    note: string;
+}
+export interface ScreenshotFail {
+    captured: false;
+    reason: string;
+    target?: string;
+}
+/** 解析截屏目标元素;认不出 → null(调用方回 captured:false)。 */
+export declare function resolveScreenshotTarget(target: string): HTMLElement | null;
+/** 应答 `ui_screenshot` 查询:成功 `{ dataUrl, width, height, target, note }`,
+ *  失败一律 `{ captured:false, reason }`(fail-soft,勿重试语义由契约承担)。 */
+export declare function captureUiScreenshot(query: unknown): Promise<ScreenshotOk | ScreenshotFail>;

package/dist/package/browser/lib/ui-screenshot.js

@@ -0,0 +1,155 @@
+/** ui-screenshot —— `ui_screenshot`(方案 P3)的 interface 侧应答:web 形态 DOM→canvas
+ *  兜底截屏(零依赖,foreignObject 栅格化路线)。
+ *
+ *  定位是**兜底证据,不是主感知通道**(主通道 = ui_snapshot 的文本 manifest + 状态摘要),
+ *  故一切失败都 fail-soft 成 `{ captured:false, reason }`(契约 description 已叮嘱模型
+ *  勿重试)。已知呈现局限(SVG-as-image 上下文**不加载任何外部资源**):
+ *  - webfont 回退系统字体;<img> / 跨源 iframe / GPU 合成 canvas 呈空白;
+ *  - WebKit(桌面 WKWebView)对 foreignObject→canvas 有已知渲染缺陷 → 大概率走
+ *    fail-soft 分支;Tauri 原生截屏是后续增强(方案 P3 注)。
+ *
+ *  target 解析:'app'(默认)= document.body;'panel:<id>' = DockPanelHost 的结构标记
+ *  `[data-fx-slot="DockPanel:<id>"]`(其外壳 display:contents 量不出 rect,故实际
+ *  量测/序列化首个元素子节点)。
+ */
+/** 长边上限:压 payload,同时贴近视觉模型的甜点分辨率。 */
+const MAX_EDGE = 1568;
+const JPEG_QUALITY = 0.85;
+/** 解析截屏目标元素;认不出 → null(调用方回 captured:false)。 */
+export function resolveScreenshotTarget(target) {
+    if (target === 'app')
+        return document.body;
+    if (target.startsWith('panel:')) {
+        const id = target.slice('panel:'.length);
+        const host = document.querySelector(`[data-fx-slot="DockPanel:${CSS.escape(id)}"]`);
+        if (!(host instanceof HTMLElement))
+            return null;
+        // 外壳 display:contents(见 DockPanelHost)→ 用首个元素子节点量测/序列化。
+        const body = host.firstElementChild;
+        return body instanceof HTMLElement ? body : host;
+    }
+    return null;
+}
+/** 汇总同源样式表文本(跨源 cssRules 读取会抛 → 跳过;外链字体反正不加载)。 */
+function collectSameOriginCss() {
+    const chunks = [];
+    for (const sheet of Array.from(document.styleSheets)) {
+        try {
+            for (const rule of Array.from(sheet.cssRules))
+                chunks.push(rule.cssText);
+        }
+        catch {
+            /* 跨源样式表 → 跳过(对应区域回退无样式,兜底证据可接受) */
+        }
+    }
+    // <style> 内容走 CDATA 包裹,CSS 里理论上不会出现的终结子串防御性剔除。
+    return chunks.join('\n').replaceAll(']]>', '');
+}
+/** 克隆并去掉序列化无意义/有害的活性节点(script 不该出现在图里;其余空白节点保留占位)。 */
+function cloneForSerialization(el, width, height) {
+    const clone = el.cloneNode(true);
+    for (const s of Array.from(clone.querySelectorAll('script')))
+        s.remove();
+    if (el === document.body) {
+        // A nested <body> is invalid XHTML and breaks the percentage-height chain
+        // used by the Studio shell. Replace it with an explicitly sized body-like
+        // root so shorter dock columns do not expose transparent bands.
+        const bodyRoot = document.createElement('div');
+        bodyRoot.className = clone.className;
+        for (const child of Array.from(clone.childNodes))
+            bodyRoot.appendChild(child);
+        const style = getComputedStyle(el);
+        Object.assign(bodyRoot.style, {
+            position: 'relative',
+            width: `${width}px`,
+            height: `${height}px`,
+            margin: '0',
+            padding: '0',
+            overflow: 'hidden',
+            color: style.color,
+            background: style.background,
+            fontFamily: style.fontFamily,
+            fontSize: style.fontSize,
+            lineHeight: style.lineHeight,
+        });
+        return bodyRoot;
+    }
+    return clone;
+}
+function captureBackground(el) {
+    let current = el;
+    while (current) {
+        const color = getComputedStyle(current).backgroundColor;
+        if (color && color !== 'transparent' && color !== 'rgba(0, 0, 0, 0)')
+            return color;
+        current = current.parentElement;
+    }
+    const bodyColor = getComputedStyle(document.body).backgroundColor;
+    return bodyColor && bodyColor !== 'transparent' ? bodyColor : '#0d0d0d';
+}
+/** 栅格化图片加载超时:UI 侧必须先于编排层的通道超时(15s)给出确定答复。 */
+const RASTER_TIMEOUT_MS = 5_000;
+function loadImage(src) {
+    return new Promise((resolve, reject) => {
+        const img = new Image();
+        const timer = setTimeout(() => reject(new Error('svg rasterization timed out')), RASTER_TIMEOUT_MS);
+        img.onload = () => {
+            clearTimeout(timer);
+            resolve(img);
+        };
+        img.onerror = () => {
+            clearTimeout(timer);
+            reject(new Error('svg rasterization failed to load'));
+        };
+        img.src = src;
+    });
+}
+/** 应答 `ui_screenshot` 查询:成功 `{ dataUrl, width, height, target, note }`,
+ *  失败一律 `{ captured:false, reason }`(fail-soft,勿重试语义由契约承担)。 */
+export async function captureUiScreenshot(query) {
+    const q = (query ?? {});
+    const target = typeof q.target === 'string' && q.target ? q.target : 'app';
+    const el = resolveScreenshotTarget(target);
+    if (!el) {
+        return { captured: false, reason: `unknown target "${target}" — use 'app' or 'panel:<id>'`, target };
+    }
+    try {
+        const rect = el.getBoundingClientRect();
+        const w = Math.max(1, Math.ceil(rect.width || el.scrollWidth));
+        const h = Math.max(1, Math.ceil(rect.height || el.scrollHeight));
+        const scale = Math.min(1, MAX_EDGE / Math.max(w, h));
+        const outW = Math.max(1, Math.round(w * scale));
+        const outH = Math.max(1, Math.round(h * scale));
+        const css = collectSameOriginCss();
+        const xhtml = new XMLSerializer().serializeToString(cloneForSerialization(el, w, h));
+        const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}">` +
+            `<foreignObject width="100%" height="100%">` +
+            `<div xmlns="http://www.w3.org/1999/xhtml"><style><![CDATA[${css}]]></style>${xhtml}</div>` +
+            `</foreignObject></svg>`;
+        const img = await loadImage(`data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`);
+        const canvas = document.createElement('canvas');
+        canvas.width = outW;
+        canvas.height = outH;
+        const ctx = canvas.getContext('2d');
+        if (!ctx)
+            return { captured: false, reason: 'canvas 2d context unavailable', target };
+        ctx.fillStyle = captureBackground(el); // JPEG has no alpha; match the live surface instead of flashing white.
+        ctx.fillRect(0, 0, outW, outH);
+        ctx.drawImage(img, 0, 0, outW, outH);
+        // 栅格失败/污染(toDataURL 抛 SecurityError)都会落到 catch → fail-soft。
+        const dataUrl = canvas.toDataURL('image/jpeg', JPEG_QUALITY);
+        if (!dataUrl.startsWith('data:image/')) {
+            return { captured: false, reason: 'canvas produced no image data', target };
+        }
+        return {
+            dataUrl,
+            width: outW,
+            height: outH,
+            target,
+            note: 'best-effort DOM rasterization: external images/fonts and embedded frames/canvases may render blank',
+        };
+    }
+    catch (e) {
+        return { captured: false, reason: `capture failed: ${e.message}`, target };
+    }
+}

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

@@ -0,0 +1,47 @@
+/** ui-trajectory —— 记录「页面上发生过哪些操作」的滚动轨迹(人 + AI 同一张表),
+ *  作为 AI 可观察上下文出墙(ui_snapshot 的 `ui.trajectory` 片 + `trajectory.read` 工具)。
+ *
+ *  数据源 = action-registry 的**唯一**派发入口 `dispatchAction`,它每次派发都发
+ *  `UI_ACTION_DISPATCH_EVENT`(人点按钮 / AI 经 ui_invoke,两条路都走它)。这里订阅它,
+ *  落进一个定长环形缓冲。与 lib/ui-action-highlight.ts 互补:那边只闪「AI 那条」并丢弃
+ *  人的操作;这里**两者都留**,因为 AI 要理解上下文就得看到用户刚才做了什么。
+ *
+ *  可序列化:entry 只含原始标量 / 浅裁剪后的 args,过得了 snapshotState 的 JSON 出墙。
+ *  隐私:credential 级 action 的 args 整体打码(不把密钥类入参喂进 AI 上下文)。 */
+export interface TrajectoryEntry {
+    /** 单调自增序号(即使同毫秒也可稳定排序 / 去重)。 */
+    seq: number;
+    /** Date.now() 毫秒时间戳。 */
+    ts: number;
+    /** action id('domain.verb')。 */
+    id: string;
+    /** 人读标题(从注册表 derive;action 已注销则缺省)。 */
+    title?: string;
+    /** 谁触发的。 */
+    source: 'human' | 'ai';
+    /** 权限分级(从注册表 derive)。 */
+    capability?: string;
+    /** 浅裁剪后的入参(credential 级打码;缺省 = 无参)。 */
+    args?: Record<string, unknown>;
+}
+/** 环形缓冲上限 == 单次 read 上限(供工具的 limit 收敛 + tool 描述出墙)。 */
+export declare const TRAJECTORY_MAX = 200;
+/** 记录一条轨迹。跳过 `trajectory.*` 自省读写,避免 AI 拉轨迹时污染轨迹本身。 */
+export declare function recordTrajectory(detail: {
+    id: string;
+    source: 'human' | 'ai';
+    args?: Record<string, unknown>;
+}): void;
+/** 读取轨迹尾部(oldest→newest)。source 过滤按「谁触发」。 */
+export declare function readTrajectory(opts?: {
+    limit?: number;
+    source?: 'human' | 'ai';
+}): {
+    total: number;
+    count: number;
+    entries: TrajectoryEntry[];
+};
+/** 清空缓冲,返回清掉的条数。 */
+export declare function clearTrajectory(): number;
+/** 订阅派发事件开始记录(幂等:重复调返回同一退订)。返回退订函数。 */
+export declare function startTrajectoryRecording(): () => void;

package/dist/package/browser/lib/ui-trajectory.js

@@ -0,0 +1,99 @@
+/** ui-trajectory —— 记录「页面上发生过哪些操作」的滚动轨迹(人 + AI 同一张表),
+ *  作为 AI 可观察上下文出墙(ui_snapshot 的 `ui.trajectory` 片 + `trajectory.read` 工具)。
+ *
+ *  数据源 = action-registry 的**唯一**派发入口 `dispatchAction`,它每次派发都发
+ *  `UI_ACTION_DISPATCH_EVENT`(人点按钮 / AI 经 ui_invoke,两条路都走它)。这里订阅它,
+ *  落进一个定长环形缓冲。与 lib/ui-action-highlight.ts 互补:那边只闪「AI 那条」并丢弃
+ *  人的操作;这里**两者都留**,因为 AI 要理解上下文就得看到用户刚才做了什么。
+ *
+ *  可序列化:entry 只含原始标量 / 浅裁剪后的 args,过得了 snapshotState 的 JSON 出墙。
+ *  隐私:credential 级 action 的 args 整体打码(不把密钥类入参喂进 AI 上下文)。 */
+import { installCustomEventObservation } from '@forgeax/app-shell/react';
+import { getAction, UI_ACTION_DISPATCH_EVENT } from './action-registry';
+// 环形缓冲容量 == `trajectory.read` 单次可拉上限(readTrajectory 用它收敛 limit)。
+// 二者本就相等,故一个常量封两处:内存占用,以及 AI 一次拉取的**最坏上下文体积**
+// (SNAPSHOT_TAIL 20 条随每次 ui_snapshot 出墙不受此限;这里管的是按需 read 的天花板)。
+// 定 200:近 200 条操作足够 AI 理解上下文,同时把最坏一次拉取从 ~500 条压到 ~200 条。
+const MAX = 200;
+const buffer = [];
+let seq = 0;
+let stop = null;
+/** 环形缓冲上限 == 单次 read 上限(供工具的 limit 收敛 + tool 描述出墙)。 */
+export const TRAJECTORY_MAX = MAX;
+/** 浅裁剪 args:长字符串截断、嵌套结构降级为占位、credential 级整体打码。 */
+function redactArgs(args, capability) {
+    if (!args || Object.keys(args).length === 0)
+        return undefined;
+    if (capability === 'credential')
+        return { redacted: true };
+    const out = {};
+    for (const [k, v] of Object.entries(args)) {
+        if (typeof v === 'string')
+            out[k] = v.length > 120 ? `${v.slice(0, 120)}…` : v;
+        else if (v === null || typeof v === 'number' || typeof v === 'boolean')
+            out[k] = v;
+        else
+            out[k] = Array.isArray(v) ? `[array:${v.length}]` : `[${typeof v}]`;
+    }
+    return out;
+}
+/** 记录一条轨迹。跳过 `trajectory.*` 自省读写,避免 AI 拉轨迹时污染轨迹本身。 */
+export function recordTrajectory(detail) {
+    if (!detail || typeof detail.id !== 'string')
+        return;
+    if (detail.id.startsWith('trajectory.'))
+        return;
+    const def = getAction(detail.id);
+    const entry = {
+        seq: ++seq,
+        ts: Date.now(),
+        id: detail.id,
+        source: detail.source === 'ai' ? 'ai' : 'human',
+    };
+    if (def?.title)
+        entry.title = def.title;
+    if (def?.capability)
+        entry.capability = def.capability;
+    const args = redactArgs(detail.args, def?.capability);
+    if (args)
+        entry.args = args;
+    buffer.push(entry);
+    if (buffer.length > MAX)
+        buffer.splice(0, buffer.length - MAX);
+}
+/** 读取轨迹尾部(oldest→newest)。source 过滤按「谁触发」。 */
+export function readTrajectory(opts = {}) {
+    const src = opts.source === 'human' || opts.source === 'ai' ? opts.source : undefined;
+    const filtered = src ? buffer.filter((e) => e.source === src) : buffer;
+    const limit = Math.min(opts.limit && opts.limit > 0 ? Math.floor(opts.limit) : 50, MAX);
+    const entries = filtered.slice(-limit);
+    return { total: filtered.length, count: entries.length, entries };
+}
+/** 清空缓冲,返回清掉的条数。 */
+export function clearTrajectory() {
+    const n = buffer.length;
+    buffer.length = 0;
+    return n;
+}
+/** 订阅派发事件开始记录(幂等:重复调返回同一退订)。返回退订函数。 */
+export function startTrajectoryRecording() {
+    if (typeof window === 'undefined')
+        return () => { };
+    if (stop)
+        return stop;
+    const onDispatch = (e) => {
+        const d = e.detail;
+        if (d)
+            recordTrajectory(d);
+    };
+    const disposeDispatchObservation = installCustomEventObservation({
+        target: window,
+        eventType: UI_ACTION_DISPATCH_EVENT,
+        onEvent: onDispatch,
+    });
+    stop = () => {
+        disposeDispatchObservation();
+        stop = null;
+    };
+    return stop;
+}

package/dist/package/browser/lib/use-bus-snapshot.d.ts

@@ -0,0 +1,3 @@
+import { type BusTopics } from './bus';
+export declare function useBusSnapshot<K extends keyof BusTopics>(topic: K): BusTopics[K] | undefined;
+export declare function useBusSnapshot(topic: string): unknown;

package/dist/package/browser/lib/use-bus-snapshot.js

@@ -0,0 +1,13 @@
+// interface bus 的 React 读侧 —— 订阅某 topic 的 retained 快照，随 owner 发布重渲染。
+//
+// 配套 `bus.ts`：owner app 用 `publish(topic, snap, { retain: true })` 广播只读真值，
+// 壳骨架 / 其他 app 用 `useBusSnapshot(topic)` 读一份响应式只读副本 —— 无需直读
+// owner 的 store（保持 interface foundation 对 app 领域态零知识）。
+//
+// 注意：owner 每次变更必须发布**新的对象引用**（快照语义），否则 useSyncExternalStore
+// 认为未变、不重渲染。返回 `undefined` 表示 owner 尚未发布过（消费者自行 `?? 缺省`）。
+import { useSyncExternalStore } from 'react';
+import { peek, subscribe } from './bus';
+export function useBusSnapshot(topic) {
+    return useSyncExternalStore((onChange) => subscribe(topic, () => onChange()), () => peek(topic), () => peek(topic));
+}

package/dist/package/browser/lib/use-extension-manifest.d.ts

@@ -0,0 +1,19 @@
+import { type ExtensionInfo } from './extension-api';
+/** Match the canonical manifest identity. Legacy ids are migrated before
+ * opening a Page; the runtime host never carries an alias path. */
+export declare function manifestMatchesId(m: ExtensionInfo, id: string): boolean;
+/** Fetches the bus manifest for a single plugin id, with retry/polling so a
+ *  transient miss (busy server, manifest still settling, bus reload window)
+ *  self-heals instead of leaving the panel stuck until the user switches tabs.
+ *
+ *  - First attempt rides the shared 2s cache → instant on tab switch-back.
+ *  - Subsequent attempts force a fresh fetch (every POLL_MS) so a manifest that
+ *    just gained `entry.standalone` is picked up live.
+ *  - Polling stops once we have a usable manifest (standalone present) or after
+ *    MAX_ATTEMPTS (the plugin genuinely ships no standalone entry — e.g. the
+ *    inline extension panel — so there is nothing more to wait for).
+ *
+ *  Extracted from ExtensionHostPanel so the keep-alive layer can
+ *  share one implementation (single source of truth for manifest resolution).
+ */
+export declare function useExtensionManifest(extensionId: string): ExtensionInfo | null | 'loading';

package/dist/package/browser/lib/use-extension-manifest.js

@@ -0,0 +1,67 @@
+import { useEffect, useState } from 'react';
+import { createRestartableTimeoutTaskLifecycle } from '@forgeax/app-shell/react';
+import { listExtensionsShared } from './extension-api';
+/** Match the canonical manifest identity. Legacy ids are migrated before
+ * opening a Page; the runtime host never carries an alias path. */
+export function manifestMatchesId(m, id) {
+    return m.id === id;
+}
+/** Fetches the bus manifest for a single plugin id, with retry/polling so a
+ *  transient miss (busy server, manifest still settling, bus reload window)
+ *  self-heals instead of leaving the panel stuck until the user switches tabs.
+ *
+ *  - First attempt rides the shared 2s cache → instant on tab switch-back.
+ *  - Subsequent attempts force a fresh fetch (every POLL_MS) so a manifest that
+ *    just gained `entry.standalone` is picked up live.
+ *  - Polling stops once we have a usable manifest (standalone present) or after
+ *    MAX_ATTEMPTS (the plugin genuinely ships no standalone entry — e.g. the
+ *    inline extension panel — so there is nothing more to wait for).
+ *
+ *  Extracted from ExtensionHostPanel so the keep-alive layer can
+ *  share one implementation (single source of truth for manifest resolution).
+ */
+export function useExtensionManifest(extensionId) {
+    const [info, setInfo] = useState('loading');
+    useEffect(() => {
+        if (!extensionId) {
+            setInfo(null);
+            return;
+        }
+        let cancelled = false;
+        let attempts = 0;
+        const MAX_ATTEMPTS = 15; // ~22s at POLL_MS — covers cold start / scan windows
+        const POLL_MS = 1500;
+        setInfo('loading');
+        const tick = async () => {
+            attempts += 1;
+            try {
+                const res = await listExtensionsShared({ force: attempts > 1 });
+                if (cancelled)
+                    return;
+                const found = res.items.find((p) => manifestMatchesId(p, extensionId)) ?? null;
+                setInfo(found);
+                if (found?.frontendUrl || found?.entry?.standalone || found?.entry?.frontend || attempts >= MAX_ATTEMPTS)
+                    return;
+            }
+            catch {
+                if (cancelled)
+                    return;
+                if (attempts >= MAX_ATTEMPTS) {
+                    setInfo(null);
+                    return;
+                }
+            }
+            retry.schedule();
+        };
+        const retry = createRestartableTimeoutTaskLifecycle({
+            delayMs: POLL_MS,
+            task: () => { void tick(); },
+        });
+        void tick();
+        return () => {
+            cancelled = true;
+            retry.dispose();
+        };
+    }, [extensionId]);
+    return info;
+}