npm - @forgeax/interface - Versions diffs - 0.4.1 - Mend

@forgeax/interface 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (963) hide show

package/dist/package/node/lib/ui-screenshot.js ADDED Viewed

@@ -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/node/lib/ui-trajectory.js ADDED Viewed

@@ -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.js';
+// 环形缓冲容量 == `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/node/lib/use-bus-snapshot.js ADDED Viewed

@@ -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.js';
+export function useBusSnapshot(topic) {
+    return useSyncExternalStore((onChange) => subscribe(topic, () => onChange()), () => peek(topic), () => peek(topic));
+}

package/dist/package/node/lib/use-extension-manifest.js ADDED Viewed

@@ -0,0 +1,67 @@
+import { useEffect, useState } from 'react';
+import { createRestartableTimeoutTaskLifecycle } from '@forgeax/app-shell/react';
+import { listExtensionsShared } from './extension-api.js';
+/** 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;
+}

package/dist/package/node/lib/useConfirmToast.js ADDED Viewed

@@ -0,0 +1,120 @@
+/**
+ * useConfirmToast — SSE subscription hook for tool.confirm-required events.
+ *
+ * Live stream only (D-6): subscribes to GET /api/events/stream?topic=tool.confirm-required.
+ * No SSE replay on reconnect — tokens that arrive before connection are ignored.
+ *
+ * Exposes:
+ *   - pendingConfirms: read-only array of pending confirm requests
+ *   - ack(token, decision): POST /api/tools/confirm { token, decision: 'allow' }
+ *   - deny(token): POST /api/tools/confirm { token, decision: 'deny' }
+ */
+import { useState, useEffect, useCallback } from 'react';
+import { parseSse } from './sse.js';
+/**
+ * Parse a raw SSE data string as a tool.confirm-required envelope.
+ * Returns the inner ConfirmPayload, or null if the envelope does not match.
+ */
+export function parseConfirmEnvelope(raw) {
+    let envelope;
+    try {
+        envelope = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof envelope !== 'object' ||
+        envelope === null ||
+        envelope.topic !== 'tool.confirm-required') {
+        return null;
+    }
+    const payload = envelope.payload;
+    if (typeof payload !== 'object' ||
+        payload === null ||
+        typeof payload.toolId !== 'string' ||
+        typeof payload.token !== 'string' ||
+        typeof payload.caller !== 'object' ||
+        payload.caller === null) {
+        return null;
+    }
+    const p = payload;
+    return {
+        toolId: p.toolId,
+        token: p.token,
+        caller: p.caller,
+        reason: typeof p.reason === 'string' ? p.reason : undefined,
+        message: typeof p.message === 'string' ? p.message : undefined,
+    };
+}
+const STREAM_URL = '/api/events/stream?topic=tool.confirm-required';
+const ACK_URL = '/api/tools/confirm';
+export function useConfirmToast() {
+    const [pendingConfirms, setPendingConfirms] = useState([]);
+    useEffect(() => {
+        let aborted = false;
+        const controller = new AbortController();
+        const run = async () => {
+            let res;
+            try {
+                res = await fetch(STREAM_URL, { signal: controller.signal });
+            }
+            catch {
+                return;
+            }
+            if (!res.ok || !res.body)
+                return;
+            try {
+                for await (const frame of parseSse(res.body)) {
+                    if (aborted)
+                        break;
+                    if (!frame.data)
+                        continue;
+                    const payload = parseConfirmEnvelope(frame.data);
+                    if (!payload)
+                        continue;
+                    setPendingConfirms((prev) => {
+                        if (prev.some((p) => p.token === payload.token))
+                            return prev;
+                        return [...prev, { ...payload, receivedAt: Date.now() }];
+                    });
+                }
+            }
+            catch {
+                // Stream ended or aborted — no-op.
+            }
+        };
+        void run();
+        return () => {
+            aborted = true;
+            controller.abort();
+        };
+    }, []);
+    const dismiss = useCallback((token) => {
+        setPendingConfirms((prev) => prev.filter((p) => p.token !== token));
+    }, []);
+    const ack = useCallback(async (token) => {
+        try {
+            await fetch(ACK_URL, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ token, decision: 'allow' }),
+            });
+        }
+        finally {
+            dismiss(token);
+        }
+    }, [dismiss]);
+    const deny = useCallback(async (token) => {
+        try {
+            await fetch(ACK_URL, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ token, decision: 'deny' }),
+            });
+        }
+        finally {
+            dismiss(token);
+        }
+    }, [dismiss]);
+    return { pendingConfirms, ack, deny };
+}

package/dist/package/node/lib/utils.js ADDED Viewed

@@ -0,0 +1,5 @@
+import { clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+export function cn(...inputs) {
+    return twMerge(clsx(inputs));
+}

package/dist/package/node/lib/vag-action-bridge.js ADDED Viewed

@@ -0,0 +1,130 @@
+/** vag-action-bridge —— editor 等 iframe 内 action 的 host 侧接入(P1-12)。
+ *
+ *  协议（只传可序列化数据，handler 留 iframe 本地，
+ *  interface 刻意不 import editor,inline 校验照 healthBridge 先例):
+ *
+ *    iframe → host  VAG_ACTION_MANIFEST { type, actions: [{ id, title, description?,
+ *                     inputSchema?, capability, surface?, timeoutMs? }] }
+ *                   (整表替换语义:同一 iframe 重发即覆盖它之前登记的全部 action)
+ *    host → iframe  VAG_ACTION_INVOKE { type, reqId, id, args }
+ *    iframe → host  VAG_ACTION_RESULT { type, reqId, result }(result = UiActionResult 形)
+ *
+ *  host 侧把 iframe action 注册成 **proxy action**(run = postMessage 往返),从而
+ *  ui_snapshot/ui_invoke/命令面板/右键 derive 全部自动覆盖 iframe 内功能——机制归
+ *  本文件,内容归各 iframe。注:editor 子模块侧的发消息端待 editor 仓落地(本文件
+ *  是 host 半边,协议以此为准)。
+ */
+import { installWindowMessageObservation } from '@forgeax/app-shell/react';
+import { registerAction } from './action-registry.js';
+import { isTrustedMessageOrigin } from './trustedOrigins.js';
+const VALID_CAPS = new Set([
+    'read', 'write', 'delete', 'exec', 'network', 'credential', 'delegate', 'other',
+]);
+const INVOKE_TIMEOUT_MS = 8_000;
+const MAX_ACTIONS_PER_FRAME = 200;
+/** 每个 iframe(按 source window)一份登记状态;重发 manifest = 整表替换。 */
+const frames = new Map();
+/** reqId → resolve(iframe 回 VAG_ACTION_RESULT 时解开)。 */
+const pendingInvokes = new Map();
+function sanitizeDecl(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const o = raw;
+    const id = typeof o.id === 'string' ? o.id.trim() : '';
+    const title = typeof o.title === 'string' ? o.title.trim() : '';
+    const capability = typeof o.capability === 'string' && VALID_CAPS.has(o.capability) ? o.capability : null;
+    // capability 是权限声明,非法值整条丢弃(与 server 侧 manifest 消毒同口径,fail-closed)。
+    if (!id || !title || !capability)
+        return null;
+    return {
+        id, title, capability,
+        ...(typeof o.description === 'string' ? { description: o.description } : {}),
+        ...(o.inputSchema && typeof o.inputSchema === 'object' ? { inputSchema: o.inputSchema } : {}),
+        ...(o.surface === 'ui' || o.surface === 'server' || o.surface === 'both' ? { surface: o.surface } : {}),
+        ...(typeof o.timeoutMs === 'number' && o.timeoutMs > 0 ? { timeoutMs: Math.floor(o.timeoutMs) } : {}),
+    };
+}
+function invokeInFrame(frame, id, args, timeoutMs) {
+    const reqId = `vag-${Math.random().toString(36).slice(2)}`;
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            pendingInvokes.delete(reqId);
+            resolve({ status: 'rejected', reason: `iframe did not answer within ${timeoutMs}ms` });
+        }, timeoutMs);
+        pendingInvokes.set(reqId, (result) => {
+            clearTimeout(timer);
+            pendingInvokes.delete(reqId);
+            resolve(result);
+        });
+        try {
+            frame.source.postMessage({ type: 'VAG_ACTION_INVOKE', reqId, id, args }, frame.origin);
+        }
+        catch (e) {
+            clearTimeout(timer);
+            pendingInvokes.delete(reqId);
+            resolve({ status: 'rejected', reason: `postMessage failed: ${e instanceof Error ? e.message : String(e)}` });
+        }
+    });
+}
+function handleManifest(source, origin, rawActions) {
+    // 整表替换:先注销该 iframe 之前登记的全部 proxy action(幂等,HMR/重载安全)。
+    const prev = frames.get(source);
+    if (prev)
+        for (const un of prev.unregister)
+            un();
+    const state = { source, origin, unregister: [] };
+    frames.set(source, state);
+    if (!Array.isArray(rawActions))
+        return;
+    for (const raw of rawActions.slice(0, MAX_ACTIONS_PER_FRAME)) {
+        const decl = sanitizeDecl(raw);
+        if (!decl)
+            continue;
+        const timeoutMs = Math.min(30_000, decl.timeoutMs ?? INVOKE_TIMEOUT_MS);
+        state.unregister.push(registerAction({
+            id: decl.id,
+            title: decl.title,
+            description: decl.description ?? `Invoke "${decl.title}" inside its panel (declared via VAG_ACTION_MANIFEST).`,
+            schema: decl.inputSchema ?? { type: 'object', properties: {} },
+            capability: decl.capability,
+            surface: decl.surface ?? 'ui',
+            timeoutMs,
+            available: () => {
+                try {
+                    return state.source.closed === false || state.source.closed === undefined
+                        ? true
+                        : 'origin iframe is gone (panel closed)';
+                }
+                catch {
+                    return 'origin iframe is gone (panel closed)';
+                }
+            },
+            run: (args) => invokeInFrame(state, decl.id, args, timeoutMs),
+        }));
+    }
+}
+let installed = false;
+/** bootUiBridge 调用一次(幂等):挂 window message 监听,可信 origin 才处理。 */
+export function installVagActionBridge() {
+    if (installed || typeof window === 'undefined')
+        return;
+    installed = true;
+    const onMessage = (e) => {
+        if (!isTrustedMessageOrigin(e.origin) || !e.data || typeof e.data !== 'object')
+            return;
+        const data = e.data;
+        if (data.type === 'VAG_ACTION_MANIFEST' && e.source && typeof e.source.postMessage === 'function') {
+            handleManifest(e.source, e.origin, data.actions);
+        }
+        else if (data.type === 'VAG_ACTION_RESULT' && typeof data.reqId === 'string') {
+            const resolve = pendingInvokes.get(data.reqId);
+            if (!resolve)
+                return;
+            const r = data.result;
+            resolve(r && (r.status === 'completed' || r.status === 'accepted' || r.status === 'rejected')
+                ? r
+                : { status: 'completed', ...(data.result !== undefined ? { stateDigest: data.result } : {}) });
+        }
+    };
+    void installWindowMessageObservation({ target: window, onMessage });
+}