@world-engines/project-host 0.1.0-alpha.0

package/dist/chromium-preview-browser-driver.js

@@ -0,0 +1,575 @@
+import { spawn } from "node:child_process";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { createServer } from "node:net";
+import { join } from "node:path";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { createPreviewBrowserCapabilities } from "./preview-browser-adapter.js";
+import { ensureSafeProjectDirectory } from "./safe-project-path.js";
+const DEFAULT_BROWSER_PATHS = process.platform === "win32"
+    ? [
+        "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+        "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe",
+        "C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe",
+        "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+    ]
+    : ["/usr/bin/google-chrome", "/usr/bin/chromium", "/usr/bin/chromium-browser"];
+const START_TIMEOUT_MS = 15_000;
+const COMMAND_TIMEOUT_MS = 10_000;
+const DEFAULT_RENDER_READY_TIMEOUT_MS = 10_000;
+class CdpConnection {
+    #socket;
+    #pending = new Map();
+    #listeners = new Map();
+    #nextId = 0;
+    constructor(socket) {
+        this.#socket = socket;
+        socket.addEventListener("message", (event) => {
+            if (typeof event.data !== "string")
+                return;
+            let envelope;
+            try {
+                envelope = JSON.parse(event.data);
+            }
+            catch {
+                return;
+            }
+            if (envelope.id !== undefined) {
+                const pending = this.#pending.get(envelope.id);
+                if (pending === undefined)
+                    return;
+                this.#pending.delete(envelope.id);
+                clearTimeout(pending.timer);
+                if (envelope.error !== undefined)
+                    pending.reject(new Error(`CDP ${envelope.error.code ?? "error"}: ${envelope.error.message ?? "failed"}`));
+                else
+                    pending.resolve(envelope.result ?? {});
+                return;
+            }
+            if (envelope.method !== undefined) {
+                for (const listener of this.#listeners.get(envelope.method) ?? [])
+                    listener(envelope.params ?? {}, envelope.sessionId);
+            }
+        });
+        socket.addEventListener("close", () => this.#rejectAll(new Error("CDP connection closed")));
+        socket.addEventListener("error", () => this.#rejectAll(new Error("CDP connection failed")));
+    }
+    static async connect(url) {
+        const socket = new WebSocket(url);
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new Error("CDP websocket timeout")), COMMAND_TIMEOUT_MS);
+            socket.addEventListener("open", () => { clearTimeout(timer); resolve(); }, { once: true });
+            socket.addEventListener("error", () => { clearTimeout(timer); reject(new Error("CDP websocket failed")); }, { once: true });
+        });
+        return new CdpConnection(socket);
+    }
+    #rejectAll(error) {
+        for (const pending of this.#pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.#pending.clear();
+    }
+    command(method, params = {}, sessionId) {
+        const id = ++this.#nextId;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#pending.delete(id);
+                reject(new Error(`CDP command timeout: ${method}`));
+            }, COMMAND_TIMEOUT_MS);
+            this.#pending.set(id, { resolve, reject, timer });
+            this.#socket.send(JSON.stringify({ id, method, params, ...(sessionId === undefined ? {} : { sessionId }) }));
+        });
+    }
+    once(method, timeoutMs = COMMAND_TIMEOUT_MS) {
+        return new Promise((resolve, reject) => {
+            const listeners = this.#listeners.get(method) ?? new Set();
+            const timer = setTimeout(() => { listeners.delete(listener); reject(new Error(`CDP event timeout: ${method}`)); }, timeoutMs);
+            const listener = (params) => { clearTimeout(timer); listeners.delete(listener); resolve(params); };
+            listeners.add(listener);
+            this.#listeners.set(method, listeners);
+        });
+    }
+    on(method, listener) {
+        const listeners = this.#listeners.get(method) ?? new Set();
+        listeners.add(listener);
+        this.#listeners.set(method, listeners);
+        return () => listeners.delete(listener);
+    }
+    close() { this.#socket.close(); }
+}
+async function reservePort() {
+    const server = createServer();
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", resolve);
+    });
+    const address = server.address();
+    if (address === null || typeof address === "string")
+        throw new Error("browser port reservation failed");
+    await new Promise((resolve, reject) => server.close((error) => error === undefined ? resolve() : reject(error)));
+    return address.port;
+}
+async function existingBrowserPath(explicit) {
+    const { access } = await import("node:fs/promises");
+    for (const candidate of explicit === undefined ? DEFAULT_BROWSER_PATHS : [explicit]) {
+        try {
+            await access(candidate);
+            return candidate;
+        }
+        catch { /* try next installed browser */ }
+    }
+    throw new AuthoringBridgeError("E_CAPABILITY_UNAVAILABLE", "未找到可用的 Chrome/Edge 浏览器");
+}
+function cdpValue(result) {
+    const remote = result.result;
+    if (typeof remote !== "object" || remote === null)
+        return undefined;
+    const value = remote.value;
+    return value;
+}
+function jsString(value) { return JSON.stringify(value).replace(/</gu, "\\u003c"); }
+function validatedCdpWebSocketUrl(value, port, kind = "page") {
+    if (value === undefined)
+        throw new Error("browser CDP target unavailable");
+    const url = new URL(value);
+    if (url.protocol !== "ws:"
+        || url.hostname !== "127.0.0.1"
+        || url.port !== String(port)
+        || !(kind === "page" ? /^\/devtools\/page\/[A-Za-z0-9_-]+$/u : /^\/devtools\/browser\/[A-Za-z0-9_-]+$/u).test(url.pathname)
+        || url.username !== ""
+        || url.password !== ""
+        || url.search !== ""
+        || url.hash !== "")
+        throw new Error("browser returned an untrusted CDP websocket endpoint");
+    return url.href;
+}
+async function stopOwnedBrowser(child) {
+    if (child.exitCode !== null)
+        return;
+    const exited = new Promise((resolve) => child.once("exit", () => resolve()));
+    child.kill();
+    await Promise.race([exited, new Promise((resolve) => setTimeout(resolve, 2_000))]);
+    if (child.exitCode === null && process.platform === "win32" && child.pid !== undefined) {
+        const killer = spawn("taskkill.exe", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+        await new Promise((resolve) => killer.once("exit", () => resolve()));
+        await Promise.race([exited, new Promise((resolve) => setTimeout(resolve, 2_000))]);
+    }
+}
+function findFrame(tree, previewUrl) {
+    if (typeof tree !== "object" || tree === null)
+        return null;
+    const record = tree;
+    const frame = record.frame;
+    if (typeof frame === "object" && frame !== null) {
+        const candidate = frame;
+        if (typeof candidate.id === "string" && typeof candidate.url === "string" && candidate.url.startsWith(previewUrl)) {
+            return { id: candidate.id, url: candidate.url };
+        }
+    }
+    if (Array.isArray(record.childFrames)) {
+        for (const child of record.childFrames) {
+            const found = findFrame(child, previewUrl);
+            if (found !== null)
+                return found;
+        }
+    }
+    return null;
+}
+/** 系统 Chrome/Edge 的真实 CDP driver；默认 headless，不弹窗，也不注入 cookie 或作者能力。 */
+export class ChromiumPreviewBrowserDriver {
+    #options;
+    #session = null;
+    constructor(options = {}) { this.#options = options; }
+    async #open(sessionId, url) {
+        if (this.#session?.sessionId === sessionId)
+            return this.#session;
+        await this.close();
+        const executable = await existingBrowserPath(this.#options.executablePath);
+        if (this.#options.tempRoot === undefined) {
+            throw new AuthoringBridgeError("E_CAPABILITY_UNAVAILABLE", "Preview 浏览器缺少项目内 profile 根目录");
+        }
+        const tempRoot = this.#options.tempRoot;
+        await mkdir(tempRoot, { recursive: true });
+        const profilePath = await mkdtemp(join(tempRoot, "worldengine-preview-browser-"));
+        const port = await reservePort();
+        const topLevelUrl = this.#options.hostPageUrl ?? url;
+        const child = spawn(executable, [
+            `--remote-debugging-port=${port}`,
+            "--remote-debugging-address=127.0.0.1",
+            `--user-data-dir=${profilePath}`,
+            "--no-first-run",
+            "--no-default-browser-check",
+            "--disable-background-networking",
+            "--disable-component-update",
+            "--disable-sync",
+            "--disable-extensions",
+            "--disable-features=Translate,OptimizationHints,MediaRouter",
+            ...(this.#options.headless === false ? [] : ["--headless=new"]),
+            "about:blank",
+        ], { stdio: "ignore", windowsHide: true });
+        try {
+            const deadline = Date.now() + START_TIMEOUT_MS;
+            let target;
+            while (Date.now() < deadline) {
+                if (child.exitCode !== null)
+                    throw new Error(`browser exited with ${child.exitCode}`);
+                try {
+                    const response = await fetch(`http://127.0.0.1:${port}/json/version`);
+                    if (response.ok) {
+                        target = await response.json();
+                        break;
+                    }
+                }
+                catch { /* browser has not opened CDP yet */ }
+                await new Promise((resolve) => setTimeout(resolve, 50));
+            }
+            const cdp = await CdpConnection.connect(validatedCdpWebSocketUrl(target?.webSocketDebuggerUrl, port, "browser"));
+            const created = await cdp.command("Target.createTarget", { url: "about:blank" });
+            if (typeof created.targetId !== "string")
+                throw new Error("browser page target unavailable");
+            const attached = await cdp.command("Target.attachToTarget", { targetId: created.targetId, flatten: true });
+            if (typeof attached.sessionId !== "string")
+                throw new Error("browser page session unavailable");
+            const rootSessionId = attached.sessionId;
+            const consoleEntries = [];
+            const defaultContexts = new Map();
+            const childTargets = new Map();
+            cdp.on("Runtime.consoleAPICalled", (params) => {
+                const rawType = params.type;
+                const level = rawType === "error" ? "error" : rawType === "warning" ? "warning" : rawType === "debug" ? "debug" : "info";
+                const args = Array.isArray(params.args) ? params.args : [];
+                const text = args.map((entry) => {
+                    if (typeof entry !== "object" || entry === null)
+                        return String(entry);
+                    const record = entry;
+                    return typeof record.value === "string" ? record.value : typeof record.description === "string" ? record.description : JSON.stringify(record.value);
+                }).join(" ");
+                consoleEntries.push({ level, text });
+                if (consoleEntries.length > 200)
+                    consoleEntries.splice(0, consoleEntries.length - 200);
+            });
+            cdp.on("Runtime.executionContextCreated", (params, sessionId) => {
+                if (typeof params.context !== "object" || params.context === null)
+                    return;
+                const context = params.context;
+                const aux = context.auxData;
+                if (typeof context.id === "number" && typeof aux === "object" && aux !== null) {
+                    const data = aux;
+                    if (data.isDefault === true && typeof data.frameId === "string") {
+                        defaultContexts.set(data.frameId, { contextId: context.id, ...(sessionId === undefined ? {} : { sessionId }) });
+                    }
+                }
+            });
+            cdp.on("Runtime.executionContextDestroyed", (params) => {
+                if (typeof params.executionContextId !== "number")
+                    return;
+                for (const [frameId, context] of defaultContexts)
+                    if (context.contextId === params.executionContextId)
+                        defaultContexts.delete(frameId);
+            });
+            cdp.on("Runtime.executionContextsCleared", () => defaultContexts.clear());
+            cdp.on("Target.attachedToTarget", (params) => {
+                if (typeof params.sessionId !== "string")
+                    return;
+                const info = params.targetInfo;
+                if (typeof info === "object" && info !== null) {
+                    const target = info;
+                    if (typeof target.targetId === "string" && typeof target.url === "string") {
+                        childTargets.set(params.sessionId, { targetId: target.targetId, url: target.url });
+                    }
+                }
+                void cdp.command("Runtime.enable", {}, params.sessionId).catch(() => undefined);
+            });
+            await Promise.all([
+                cdp.command("Target.setAutoAttach", { autoAttach: true, waitForDebuggerOnStart: false, flatten: true }, rootSessionId),
+                cdp.command("Page.enable", {}, rootSessionId),
+                cdp.command("Runtime.enable", {}, rootSessionId),
+            ]);
+            const opened = { sessionId, process: child, profilePath, cdp, rootSessionId, console: consoleEntries, defaultContexts, childTargets, url: topLevelUrl };
+            this.#session = opened;
+            await this.#navigate(opened, topLevelUrl);
+            if (this.#options.hostPageUrl !== undefined) {
+                if (this.#options.expectedProjectId !== undefined) {
+                    const status = await this.#evaluate(opened, `(async()=>{const r=await fetch("/api/status",{credentials:"same-origin",cache:"no-store"});return {status:r.status,body:await r.json()};})()`);
+                    if (typeof status !== "object" || status === null)
+                        throw new Error("GUI status unavailable");
+                    const statusRecord = status;
+                    const body = statusRecord.body;
+                    const result = body?.result;
+                    const project = result?.project;
+                    const projectId = result?.project_id ?? project?.project_id;
+                    if (statusRecord.status !== 200 || projectId !== this.#options.expectedProjectId)
+                        throw new Error("GUI project identity mismatch");
+                }
+                const activate = this.#options.activatePreviewSelector ?? '[data-view="view"]';
+                await this.#evaluate(opened, `(()=>{const e=document.querySelector(${jsString(activate)});if(!e)throw new Error("preview activator missing");e.click();return true;})()`);
+                const frameSelector = this.#options.previewFrameSelector ?? "#preview-frame";
+                let frameBound = false;
+                const bindDeadline = Date.now() + COMMAND_TIMEOUT_MS;
+                while (Date.now() < bindDeadline) {
+                    const src = await this.#evaluate(opened, `(()=>{const e=document.querySelector(${jsString(frameSelector)});return e&&e.src||"";})()`);
+                    if (typeof src === "string" && src.startsWith(url)) {
+                        frameBound = true;
+                        break;
+                    }
+                    await new Promise((resolve) => setTimeout(resolve, 50));
+                }
+                if (!frameBound)
+                    throw new Error("GUI Host did not bind the current Preview URL");
+                await this.#frameContext(opened, url);
+            }
+            return opened;
+        }
+        catch (error) {
+            await stopOwnedBrowser(child);
+            await rm(profilePath, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+            throw new AuthoringBridgeError("E_CAPABILITY_UNAVAILABLE", `无法启动 Preview 浏览器: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    async #navigate(session, url) {
+        const loaded = session.cdp.once("Page.loadEventFired").catch(() => ({}));
+        await session.cdp.command("Page.navigate", { url }, session.rootSessionId);
+        await loaded;
+        session.url = url;
+    }
+    async #frameContext(session, previewUrl) {
+        const deadline = Date.now() + COMMAND_TIMEOUT_MS;
+        let frameObserved = false;
+        while (Date.now() < deadline) {
+            const tree = await session.cdp.command("Page.getFrameTree", {}, session.rootSessionId);
+            const frame = findFrame(tree.frameTree, previewUrl);
+            let attached = frame === null
+                ? [...session.childTargets.entries()].find(([, target]) => target.url.startsWith(previewUrl))
+                : undefined;
+            if (frame === null && attached === undefined) {
+                const targets = await session.cdp.command("Target.getTargets");
+                const infos = Array.isArray(targets.targetInfos) ? targets.targetInfos : [];
+                const target = infos.find((entry) => {
+                    if (typeof entry !== "object" || entry === null)
+                        return false;
+                    const info = entry;
+                    return info.type === "iframe" && typeof info.url === "string" && info.url.startsWith(previewUrl);
+                });
+                if (target !== undefined && typeof target.targetId === "string" && typeof target.url === "string") {
+                    frameObserved = true;
+                    const existing = [...session.childTargets.entries()].find(([, value]) => value.targetId === target.targetId);
+                    if (existing === undefined) {
+                        const result = await session.cdp.command("Target.attachToTarget", { targetId: target.targetId, flatten: true });
+                        if (typeof result.sessionId === "string") {
+                            session.childTargets.set(result.sessionId, { targetId: target.targetId, url: target.url });
+                            await session.cdp.command("Runtime.enable", {}, result.sessionId);
+                            attached = [result.sessionId, { targetId: target.targetId, url: target.url }];
+                        }
+                    }
+                    else
+                        attached = existing;
+                }
+            }
+            const candidate = frame ?? (attached === undefined ? null : { id: attached[1].targetId, url: attached[1].url });
+            if (candidate !== null) {
+                frameObserved = true;
+                const attachedSessionId = attached?.[0];
+                const context = session.defaultContexts.get(candidate.id)
+                    ?? (attachedSessionId === undefined ? undefined : [...session.defaultContexts.values()].find((entry) => entry.sessionId === attachedSessionId));
+                if (context !== undefined) {
+                    session.frameId = candidate.id;
+                    session.executionContextId = context.contextId;
+                    return { frameId: candidate.id, contextId: context.contextId, ...(context.sessionId === undefined ? {} : { sessionId: context.sessionId }), url: candidate.url };
+                }
+            }
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+        throw new AuthoringBridgeError("E_CAPABILITY_UNAVAILABLE", frameObserved
+            ? `sandbox Preview frame 已加载但默认 execution context 不可用（contexts=${session.defaultContexts.size}）`
+            : `真实 Host 未加载受控 sandbox Preview frame（contexts=${session.defaultContexts.size}）`);
+    }
+    async #evaluate(session, expression, contextId, cdpSessionId) {
+        const result = await session.cdp.command("Runtime.evaluate", {
+            expression,
+            returnByValue: true,
+            awaitPromise: true,
+            ...(contextId === undefined ? {} : { contextId }),
+        }, cdpSessionId ?? session.rootSessionId);
+        const exception = result.exceptionDetails;
+        if (exception !== undefined)
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "Preview 浏览器操作失败");
+        return cdpValue(result);
+    }
+    async #waitForRenderReady(session, frame) {
+        const timeoutMs = this.#options.renderReadyTimeoutMs ?? DEFAULT_RENDER_READY_TIMEOUT_MS;
+        if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > COMMAND_TIMEOUT_MS) {
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "Preview render readiness timeout 无效");
+        }
+        const deadline = Date.now() + timeoutMs;
+        let reason = "chatplay-not-ready";
+        while (Date.now() < deadline) {
+            const remainingMs = deadline - Date.now();
+            const readiness = await this.#evaluate(session, `(async()=>{
+        const timeout=(ms)=>new Promise((resolve)=>setTimeout(()=>resolve(false),ms));
+        const nextPaint=()=>new Promise((resolve)=>{
+          let settled=false;
+          const finish=(value)=>{if(!settled){settled=true;clearTimeout(timer);resolve(value);}};
+          const timer=setTimeout(()=>finish(false),100);
+          requestAnimationFrame(()=>finish(true));
+        });
+        const visibleSignature=()=>Array.from(document.body.querySelectorAll("*")).flatMap((element)=>{
+          if (element instanceof HTMLScriptElement || element instanceof HTMLStyleElement || element instanceof HTMLLinkElement || element instanceof HTMLMetaElement) return [];
+          const style=getComputedStyle(element);
+          if (style.display==="none" || style.visibility!=="visible" || Number(style.opacity)===0) return [];
+          const rect=element.getBoundingClientRect();
+          if (rect.width<=0 || rect.height<=0) return [];
+          const directText=Array.from(element.childNodes).some((node)=>node.nodeType===Node.TEXT_NODE && (node.textContent||"").trim().length>0);
+          const paintedSurface=style.backgroundImage!=="none" || !/^rgba?\\(0,\\s*0,\\s*0,\\s*0\\)$/u.test(style.backgroundColor) || parseFloat(style.borderTopWidth)>0 || parseFloat(style.borderRightWidth)>0 || parseFloat(style.borderBottomWidth)>0 || parseFloat(style.borderLeftWidth)>0 || style.boxShadow!=="none";
+          const intrinsic=element instanceof HTMLCanvasElement || element instanceof HTMLImageElement || element instanceof HTMLVideoElement || element instanceof SVGElement;
+          return directText || paintedSurface || intrinsic ? [element.tagName+":"+Math.round(rect.width)+"x"+Math.round(rect.height)+":"+(directText?1:0)+":"+(paintedSurface?1:0)+":"+(intrinsic?1:0)] : [];
+        }).join("|");
+        const chatPlay=window.ChatPlay;
+        if (!chatPlay || !chatPlay.ready || typeof chatPlay.ready.then!=="function") return {ready:false,reason:"chatplay-unavailable"};
+        const sdkReady=await Promise.race([Promise.resolve(chatPlay.ready).then(()=>true,()=>false),timeout(Math.min(100,${Math.max(1, remainingMs)}))]);
+        if (sdkReady!==true) return {ready:false,reason:"chatplay-not-ready"};
+        const before=visibleSignature();
+        if (before==="") return {ready:false,reason:"renderable-view-missing"};
+        if (await nextPaint()!==true || await nextPaint()!==true) return {ready:false,reason:"paint-not-observed"};
+        const after=visibleSignature();
+        return {ready:before===after && after!=="",reason:"render-unstable"};
+      })()`, frame.contextId, frame.sessionId);
+            if (typeof readiness === "object" && readiness !== null) {
+                const record = readiness;
+                if (record.ready === true)
+                    return;
+                if (typeof record.reason === "string")
+                    reason = record.reason;
+            }
+            if (Date.now() < deadline)
+                await new Promise((resolve) => setTimeout(resolve, Math.min(50, deadline - Date.now())));
+        }
+        throw new AuthoringBridgeError("E_PREVIEW_NOT_READY", `Preview 未在限定时间内完成 ChatPlay ready 与首次可视渲染 (${reason})`);
+    }
+    async inspect(request) {
+        const session = await this.#open(request.sessionId, request.url);
+        const frame = this.#options.hostPageUrl === undefined ? undefined : await this.#frameContext(session, request.url);
+        if (frame !== undefined)
+            await this.#waitForRenderReady(session, frame);
+        const selector = request.selector ?? "body";
+        const snapshot = await this.#evaluate(session, `(()=>{const e=document.querySelector(${jsString(selector)});if(!e)return null;return {dom:e.outerHTML||"",text:e.textContent||"",url:location.href,ready:document.readyState==="complete"};})()`, frame?.contextId, frame?.sessionId);
+        if (snapshot === null || typeof snapshot !== "object")
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "Preview selector 未命中");
+        const record = snapshot;
+        let screenshot;
+        if (request.includeScreenshot) {
+            let clip;
+            if (frame !== undefined) {
+                const frameSelector = this.#options.previewFrameSelector ?? "#preview-frame";
+                const bounds = await this.#evaluate(session, `(()=>{const e=document.querySelector(${jsString(frameSelector)});if(!e)return null;const r=e.getBoundingClientRect();return {x:r.x,y:r.y,width:r.width,height:r.height};})()`);
+                if (typeof bounds !== "object" || bounds === null)
+                    throw new AuthoringBridgeError("E_CAPABILITY_UNAVAILABLE", "Preview iframe 截图区域不可用");
+                const box = bounds;
+                if (![box.x, box.y, box.width, box.height].every((value) => typeof value === "number" && Number.isFinite(value)) || box.width <= 0 || box.height <= 0) {
+                    throw new AuthoringBridgeError("E_CAPABILITY_UNAVAILABLE", "Preview iframe 截图区域无效");
+                }
+                clip = { x: box.x, y: box.y, width: box.width, height: box.height, scale: 1 };
+            }
+            const result = await session.cdp.command("Page.captureScreenshot", { format: "png", fromSurface: true, captureBeyondViewport: false, ...(clip === undefined ? {} : { clip }) }, session.rootSessionId);
+            if (typeof result.data !== "string")
+                throw new Error("CDP screenshot missing");
+            screenshot = { bytes: Buffer.from(result.data, "base64"), mimeType: "image/png" };
+        }
+        return {
+            url: typeof record.url === "string" ? record.url : session.url,
+            ready: record.ready === true,
+            dom: typeof record.dom === "string" ? record.dom : "",
+            text: typeof record.text === "string" ? record.text : "",
+            ...(request.includeConsole ? { console: Object.freeze([...session.console]) } : {}),
+            ...(screenshot === undefined ? {} : { screenshot }),
+        };
+    }
+    async interact(request) {
+        const session = await this.#open(request.sessionId, request.url);
+        let frame = this.#options.hostPageUrl === undefined ? undefined : await this.#frameContext(session, request.url);
+        if (request.action === "navigate") {
+            if (frame === undefined)
+                await this.#navigate(session, request.target);
+            else {
+                session.defaultContexts.delete(frame.frameId);
+                delete session.frameId;
+                delete session.executionContextId;
+                await session.cdp.command("Page.navigate", { url: request.target, frameId: frame.frameId }, session.rootSessionId);
+                frame = await this.#frameContext(session, request.target);
+            }
+        }
+        else if (request.action === "click")
+            await this.#evaluate(session, `(()=>{const e=document.querySelector(${jsString(request.target)});if(!e)throw new Error("missing");e.click();return true;})()`, frame?.contextId, frame?.sessionId);
+        else if (request.action === "type")
+            await this.#evaluate(session, `(()=>{const e=document.querySelector(${jsString(request.target)});if(!e||!("value" in e))throw new Error("missing");e.focus();e.value=${jsString(request.value ?? "")};e.dispatchEvent(new Event("input",{bubbles:true}));e.dispatchEvent(new Event("change",{bubbles:true}));return true;})()`, frame?.contextId, frame?.sessionId);
+        else if (request.action === "scroll")
+            await this.#evaluate(session, `(()=>{const e=document.querySelector(${jsString(request.target)});if(!e)throw new Error("missing");e.scrollIntoView({block:"center",inline:"center"});return true;})()`, frame?.contextId, frame?.sessionId);
+        else {
+            const key = request.value ?? request.target;
+            if (!/^(?:Enter|Escape|Tab|ArrowUp|ArrowDown|ArrowLeft|ArrowRight|Backspace|Delete|Home|End|PageUp|PageDown| )$/u.test(key)) {
+                throw new AuthoringBridgeError("E_SCHEMA_INVALID", "Preview press key 不在白名单中");
+            }
+            await session.cdp.command("Input.dispatchKeyEvent", { type: "keyDown", key }, session.rootSessionId);
+            await session.cdp.command("Input.dispatchKeyEvent", { type: "keyUp", key }, session.rootSessionId);
+        }
+        const value = await this.#evaluate(session, "location.href", frame?.contextId, frame?.sessionId);
+        return { url: typeof value === "string" ? value : session.url };
+    }
+    /** 仅供开发 harness 验证正式高层 SDK；不暴露任意 RPC/eval。 */
+    async sendChatPlayUserMessage(sessionId, previewUrl, text) {
+        if (text.trim().length === 0 || text.length > 64 * 1024)
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "ChatPlay message 无效");
+        const session = await this.#open(sessionId, previewUrl);
+        const frame = await this.#frameContext(session, previewUrl);
+        const value = await this.#evaluate(session, `(async()=>{await window.ChatPlay.ready;return window.ChatPlay.sendUserMessage(${jsString(text)});})()`, frame.contextId, frame.sessionId);
+        if (typeof value !== "object" || value === null)
+            throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "ChatPlay send 回执无效");
+        const result = value;
+        if ((result.messageId !== undefined && typeof result.messageId !== "string") || (result.turnId !== undefined && typeof result.turnId !== "string")) {
+            throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "ChatPlay send 回执字段无效");
+        }
+        return Object.freeze({
+            ...(typeof result.messageId === "string" ? { messageId: result.messageId } : {}),
+            ...(typeof result.turnId === "string" ? { turnId: result.turnId } : {}),
+        });
+    }
+    async listChatPlayMessages(sessionId, previewUrl) {
+        const session = await this.#open(sessionId, previewUrl);
+        const frame = await this.#frameContext(session, previewUrl);
+        const value = await this.#evaluate(session, "(async()=>{await window.ChatPlay.ready;return window.ChatPlay.listMessages({limit:200});})()", frame.contextId, frame.sessionId);
+        if (!Array.isArray(value) || value.some((entry) => typeof entry !== "object" || entry === null || Array.isArray(entry))) {
+            throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "ChatPlay message list 无效");
+        }
+        return Object.freeze(value.map((entry) => Object.freeze({ ...entry })));
+    }
+    async close() {
+        const session = this.#session;
+        this.#session = null;
+        if (session === null)
+            return;
+        if (session.process.exitCode === null) {
+            const exited = new Promise((resolve) => session.process.once("exit", () => resolve()));
+            await session.cdp.command("Browser.close").catch(() => undefined);
+            await Promise.race([exited, new Promise((resolve) => setTimeout(resolve, 2_000))]);
+            if (session.process.exitCode === null)
+                await stopOwnedBrowser(session.process);
+        }
+        session.cdp.close();
+        await rm(session.profilePath, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+    }
+}
+/** ProjectHost/CLI 的窄接线入口：CLI 只需把返回 capability 传入 LocalProjectHostOptions。 */
+export async function createChromiumPreviewBrowserHarness(runtime, options = {}) {
+    const preview = runtime.inspect();
+    if (preview === null || preview.state !== "running")
+        throw new AuthoringBridgeError("E_PREVIEW_NOT_RUNNING", "Preview 浏览器需要 running session");
+    const cacheRoot = options.tempRoot ?? await ensureSafeProjectDirectory(preview.project_root, ".worldengine/cache/browser");
+    const driver = new ChromiumPreviewBrowserDriver({ ...options, tempRoot: cacheRoot });
+    return Object.freeze({
+        driver,
+        desktopAuthoringCapabilities: createPreviewBrowserCapabilities({
+            inspectSession: () => runtime.inspect(),
+            driver,
+        }),
+        close: () => driver.close(),
+    });
+}

package/dist/cli/download.d.ts

@@ -0,0 +1,12 @@
+import { type DownloadRemoteRequest, type RemoteDownloadPlan } from "../transfer/download.js";
+export interface DownloadCliInvocation {
+    readonly kind: "plan" | "confirm" | "operation" | "reconcile" | "restore";
+    readonly target_pair_id?: string;
+    readonly parts?: readonly ("scenario" | "view")[];
+    readonly plan?: RemoteDownloadPlan;
+    readonly plan_digest?: string;
+    readonly operation_id?: string;
+}
+/** 非交互 CLI 只能以当前 frozen plan digest 确认覆盖，不读取 cookie。 */
+export declare function parseDownloadInvocation(args: readonly string[]): DownloadCliInvocation;
+export declare function toDownloadRemoteRequest(projectId: string, invocation: DownloadCliInvocation): DownloadRemoteRequest;

package/dist/cli/download.js

@@ -0,0 +1,50 @@
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { parseRemoteDownloadPlan } from "../transfer/download.js";
+function invalid(message) { throw new AuthoringBridgeError("E_SCHEMA_INVALID", message); }
+function parseParts(value) {
+    if (value === undefined)
+        invalid("download plan 需要 --parts scenario|view|both");
+    const parts = value === "both" ? ["scenario", "view"] : value.split(",");
+    if (parts.length < 1 || parts.length > 2 || new Set(parts).size !== parts.length || parts.some((part) => part !== "scenario" && part !== "view"))
+        invalid("--parts 只接受 scenario、view 或 both");
+    return parts;
+}
+function parseJsonPlan(value) {
+    if (value === undefined)
+        invalid("download confirm 需要 --plan-json <frozen-plan-json>");
+    try {
+        return parseRemoteDownloadPlan(JSON.parse(value));
+    }
+    catch (error) {
+        if (error instanceof AuthoringBridgeError)
+            throw error;
+        invalid("--plan-json 必须是 JSON frozen plan");
+    }
+}
+/** 非交互 CLI 只能以当前 frozen plan digest 确认覆盖，不读取 cookie。 */
+export function parseDownloadInvocation(args) {
+    const [command, ...rest] = args;
+    if (command === "plan") {
+        const [targetPairId, flag, parts, ...extra] = rest;
+        if (!targetPairId || flag !== "--parts" || extra.length !== 0)
+            invalid("download plan <target-pair-id> --parts scenario|view|both");
+        return { kind: "plan", target_pair_id: targetPairId, parts: parseParts(parts) };
+    }
+    if (command === "confirm") {
+        const [planFlag, planJson, confirmFlag, digest, ...extra] = rest;
+        if (planFlag !== "--plan-json" || confirmFlag !== "--confirm-plan" || !digest || extra.length !== 0)
+            invalid("download confirm --plan-json <frozen-plan-json> --confirm-plan <digest>");
+        return { kind: "confirm", plan: parseJsonPlan(planJson), plan_digest: digest };
+    }
+    if (command === "operation" || command === "reconcile" || command === "restore") {
+        if (rest.length !== 1 || !rest[0])
+            invalid(`download ${command} <operation-id>`);
+        return { kind: command, operation_id: rest[0] };
+    }
+    invalid("download 只接受 plan、confirm、operation、reconcile 或 restore");
+}
+export function toDownloadRemoteRequest(projectId, invocation) {
+    if (invocation.kind !== "plan")
+        invalid("只有 download plan 可创建远端请求");
+    return { project_id: projectId, target_pair_id: invocation.target_pair_id, parts: invocation.parts };
+}