@szc-ft/mcp-szcd-client 0.27.1 → 0.27.3

package/lib/browser-engine.js

@@ -61,7 +61,7 @@ export class BrowserEngine {
      */
     async connect(cdpUrl, options = {}) {
         const puppeteer = await loadPuppeteer();
-        this.browser = await puppeteer.connect({ browserURL: cdpUrl });
+        this.browser = await puppeteer.connect({ browserURL: cdpUrl, defaultViewport: null });
         this.mode = "connect";
         this.ownedBrowser = false;
 
@@ -145,11 +145,14 @@ export class BrowserEngine {
         const startTime = Date.now();
         try {
             const result = await this._dispatchStep(step, context);
+            if (step.type === "apiCapture" || step.type === "api-capture") {
+                context.lastApiCapture = result;
+            }
             return {
                 ...result,
                 step: step.type,
                 duration: Date.now() - startTime,
-                status: "PASS",
+                status: result?.passed === false ? "FAIL" : "PASS",
             };
         } catch (err) {
             return {
@@ -178,11 +181,834 @@ export class BrowserEngine {
         }
     }
 
+    async observe(options = {}) {
+        const targetFrame = await this._resolveObserveFrame(options);
+        const selector = options.selector || "body";
+        const depth = Number.parseInt(options.depth ?? 5, 10);
+        const maxInteractiveElements = Number.parseInt(options.maxInteractiveElements ?? 200, 10);
+        const frames = await this._getFrameSummaries();
+        const tree = await this._buildDomTree(targetFrame.frame, selector, depth);
+        const interactiveElements = await this._collectInteractiveElements(
+            targetFrame.frame,
+            targetFrame.frameId,
+            maxInteractiveElements
+        );
+        const title = await this.page.title().catch(() => "");
+
+        return {
+            type: "observe",
+            url: this.page.url(),
+            title,
+            timestamp: new Date().toISOString(),
+            mode: this.mode,
+            target: {
+                frameId: targetFrame.frameId,
+                frameUrl: targetFrame.frame.url(),
+                matchedBy: targetFrame.matchedBy,
+            },
+            frames,
+            tree,
+            interactiveElements,
+            summary: {
+                frames: frames.length,
+                interactiveElements: interactiveElements.length,
+            },
+        };
+    }
+
+    async act(options = {}) {
+        const targetFrame = await this._resolveObserveFrame(options);
+        if (options.menuPath) {
+            return this._actMenuPath(targetFrame, options);
+        }
+
+        const index = options.index !== undefined ? Number.parseInt(options.index, 10) : undefined;
+        const selector = this._resolveSelector(options.selector || options.click || options.hover);
+        const typeText = options.typeText ?? options.text;
+        const action = options.hover ? "hover" : typeText !== undefined ? "type" : "click";
+
+        const result = await targetFrame.frame.evaluate((actOptions) => {
+            function getText(el) {
+                return (el.innerText || el.textContent || "").replace(/\s+/g, " ").trim().slice(0, 120);
+            }
+
+            function roleOf(el) {
+                const explicit = el.getAttribute("role");
+                if (explicit) return explicit;
+                const tag = el.tagName.toLowerCase();
+                if (tag === "button") return "button";
+                if (tag === "a") return "link";
+                if (["input", "textarea"].includes(tag)) return "textbox";
+                if (tag === "select") return "combobox";
+                return "generic";
+            }
+
+            function getName(el, text) {
+                return (
+                    el.getAttribute("aria-label") ||
+                    el.getAttribute("title") ||
+                    el.getAttribute("placeholder") ||
+                    el.getAttribute("alt") ||
+                    text ||
+                    ""
+                ).slice(0, 120);
+            }
+
+            function isCandidate(el) {
+                const tag = el.tagName.toLowerCase();
+                return ["a", "button", "input", "select", "textarea", "summary"].includes(tag) ||
+                    el.getAttribute("role") ||
+                    el.getAttribute("tabindex") !== null ||
+                    el.onclick ||
+                    el.getAttribute("data-testid") ||
+                    (typeof el.className === "string" && /btn|button|menu-item|ant-btn|ant-menu|ant-select|ant-input/.test(el.className));
+            }
+
+            function interactiveElements() {
+                return Array.from(document.querySelectorAll("a,button,input,select,textarea,summary,[role],[tabindex],[data-testid],[class*='btn'],[class*='button'],[class*='menu-item'],[class*='ant-btn'],[class*='ant-menu'],[class*='ant-select'],[class*='ant-input']"))
+                    .filter(isCandidate);
+            }
+
+            function findBySelector(selector) {
+                if (!selector) return null;
+                if (selector.startsWith("text=")) {
+                    const expected = selector.slice(5).trim();
+                    return interactiveElements().find((el) => getText(el).includes(expected) || getName(el, getText(el)).includes(expected)) ||
+                        Array.from(document.querySelectorAll("*")).find((el) => getText(el).includes(expected));
+                }
+                if (selector.startsWith("role=")) {
+                    const match = selector.match(/^role=([^\[]+)(?:\[name="([^"]+)"\])?/);
+                    const expectedRole = match?.[1]?.trim();
+                    const expectedName = match?.[2]?.trim();
+                    return interactiveElements().find((el) => {
+                        const text = getText(el);
+                        const name = getName(el, text);
+                        return roleOf(el) === expectedRole && (!expectedName || name.includes(expectedName) || text.includes(expectedName));
+                    });
+                }
+                try {
+                    return document.querySelector(selector);
+                } catch {
+                    return null;
+                }
+            }
+
+            const el = actOptions.index !== undefined
+                ? interactiveElements()[actOptions.index - 1]
+                : findBySelector(actOptions.selector);
+
+            if (!el) {
+                return { found: false };
+            }
+
+            el.scrollIntoView({ block: "center", inline: "center" });
+            const rect = el.getBoundingClientRect();
+            const style = window.getComputedStyle(el);
+            const visible = rect.width > 0 && rect.height > 0 && style.visibility !== "hidden" && style.display !== "none";
+            const enabled = !el.disabled && el.getAttribute("aria-disabled") !== "true";
+            const text = getText(el);
+            const name = getName(el, text);
+            const baseResult = {
+                found: true,
+                tagName: el.tagName,
+                role: roleOf(el),
+                name,
+                text,
+                visible,
+                enabled,
+                bbox: {
+                    x: Math.round(rect.x),
+                    y: Math.round(rect.y),
+                    width: Math.round(rect.width),
+                    height: Math.round(rect.height),
+                },
+            };
+
+            if (!visible || !enabled) {
+                return { ...baseResult, performed: false };
+            }
+
+            if (actOptions.action === "hover") {
+                el.dispatchEvent(new MouseEvent("mouseover", { bubbles: true }));
+                el.dispatchEvent(new MouseEvent("mouseenter", { bubbles: true }));
+                return { ...baseResult, performed: true, action: "hover" };
+            }
+
+            if (actOptions.action === "type") {
+                el.focus();
+                if ("value" in el) {
+                    el.value = actOptions.clear ? "" : el.value;
+                    el.value += actOptions.typeText;
+                } else if (el.isContentEditable) {
+                    el.textContent = actOptions.clear ? actOptions.typeText : `${el.textContent || ""}${actOptions.typeText}`;
+                } else {
+                    return { ...baseResult, performed: false, error: "Target is not typeable" };
+                }
+                el.dispatchEvent(new InputEvent("input", { bubbles: true, inputType: "insertText", data: actOptions.typeText }));
+                el.dispatchEvent(new Event("change", { bubbles: true }));
+                return { ...baseResult, performed: true, action: "type", value: "value" in el ? el.value : el.textContent };
+            }
+
+            el.click();
+            return { ...baseResult, performed: true, action: "click" };
+        }, {
+            index,
+            selector,
+            action,
+            typeText,
+            clear: Boolean(options.clear),
+        });
+
+        if (!result.found) {
+            throw new Error(index !== undefined ? `Interactive element index not found: ${index}` : `Element not found: ${selector}`);
+        }
+        if (!result.performed) {
+            throw new Error(result.error || `Element is not actionable: ${index ?? selector}`);
+        }
+
+        return {
+            acted: true,
+            action: result.action,
+            index,
+            selector,
+            target: {
+                frameId: targetFrame.frameId,
+                frameUrl: targetFrame.frame.url(),
+                matchedBy: targetFrame.matchedBy,
+            },
+            element: result,
+        };
+    }
+
+    async _actMenuPath(targetFrame, options = {}) {
+        const menuPath = Array.isArray(options.menuPath)
+            ? options.menuPath
+            : String(options.menuPath).split("/").map((item) => item.trim()).filter(Boolean);
+        const waitAfterEach = Number.parseInt(options.waitAfterEach ?? 300, 10);
+
+        if (menuPath.length === 0) {
+            throw new Error("menuPath is empty");
+        }
+
+        const result = await targetFrame.frame.evaluate(async (pathItems, waitMs) => {
+            function sleep(ms) {
+                return new Promise((resolve) => setTimeout(resolve, ms));
+            }
+
+            function textOf(el) {
+                return (el.innerText || el.textContent || "").replace(/\s+/g, " ").trim();
+            }
+
+            function classText(el) {
+                return typeof el.className === "string" ? el.className : "";
+            }
+
+            function isVisible(el) {
+                const rect = el.getBoundingClientRect();
+                const style = window.getComputedStyle(el);
+                return rect.width > 0 && rect.height > 0 && style.display !== "none" && style.visibility !== "hidden";
+            }
+
+            function menuCandidates() {
+                return Array.from(document.querySelectorAll([
+                    "[role='menuitem']",
+                    ".ant-menu-item",
+                    ".ant-menu-submenu-title",
+                    "li[class*='menu']",
+                    "a",
+                    "button",
+                    "[class*='menu-item']",
+                    "[class*='submenu']",
+                ].join(","))).filter(isVisible);
+            }
+
+            function scoreCandidate(el, text, level) {
+                const actual = textOf(el);
+                if (!actual) return -1;
+                let score = -1;
+                if (actual === text) score = 100;
+                else if (actual.includes(text)) score = 70;
+                else if (text.includes(actual)) score = 50;
+                if (score < 0) return -1;
+                const cls = classText(el);
+                const role = el.getAttribute("role") || "";
+                if (role === "menuitem") score += 10;
+                if (cls.includes("ant-menu-submenu-title")) score += level < pathItems.length - 1 ? 20 : -5;
+                if (cls.includes("ant-menu-item")) score += level === pathItems.length - 1 ? 20 : 0;
+                if (cls.includes("ant-menu-item-selected")) score += 5;
+                return score;
+            }
+
+            function findMenuItem(text, level) {
+                return menuCandidates()
+                    .map((el) => ({ el, score: scoreCandidate(el, text, level), text: textOf(el) }))
+                    .filter((item) => item.score >= 0)
+                    .sort((a, b) => b.score - a.score)[0] || null;
+            }
+
+            function elementSnapshot(el) {
+                const rect = el.getBoundingClientRect();
+                return {
+                    tagName: el.tagName,
+                    text: textOf(el).slice(0, 120),
+                    role: el.getAttribute("role") || null,
+                    className: classText(el),
+                    ariaExpanded: el.getAttribute("aria-expanded"),
+                    bbox: {
+                        x: Math.round(rect.x),
+                        y: Math.round(rect.y),
+                        width: Math.round(rect.width),
+                        height: Math.round(rect.height),
+                    },
+                };
+            }
+
+            const steps = [];
+
+            for (let i = 0; i < pathItems.length; i++) {
+                const text = pathItems[i];
+                let match = findMenuItem(text, i);
+                if (!match && i > 0) {
+                    await sleep(waitMs * 2);
+                    match = findMenuItem(text, i);
+                }
+                if (!match) {
+                    return { found: false, failedAt: text, steps };
+                }
+
+                const el = match.el;
+                el.scrollIntoView({ block: "center", inline: "center" });
+                const beforeUrl = location.href;
+                const beforeText = document.body?.innerText || "";
+                const isLast = i === pathItems.length - 1;
+                const before = elementSnapshot(el);
+
+                el.dispatchEvent(new MouseEvent("mouseover", { bubbles: true }));
+                el.dispatchEvent(new MouseEvent("mouseenter", { bubbles: true }));
+                el.click();
+                await sleep(waitMs);
+
+                const afterClass = classText(el);
+                const afterExpanded = el.getAttribute("aria-expanded");
+                steps.push({
+                    text,
+                    action: isLast ? "click" : "expand",
+                    status: "PASS",
+                    matchedText: match.text,
+                    before,
+                    after: {
+                        className: afterClass,
+                        ariaExpanded: afterExpanded,
+                        urlChanged: location.href !== beforeUrl,
+                        textChanged: (document.body?.innerText || "") !== beforeText,
+                        selected: afterClass.includes("selected") || afterClass.includes("active"),
+                    },
+                });
+            }
+
+            return {
+                found: true,
+                performed: true,
+                steps,
+                currentUrl: location.href,
+                title: document.title,
+            };
+        }, menuPath, waitAfterEach);
+
+        if (!result.found) {
+            throw new Error(`Menu path item not found: ${result.failedAt}`);
+        }
+
+        return {
+            acted: true,
+            action: "menuPath",
+            menuPath,
+            target: {
+                frameId: targetFrame.frameId,
+                frameUrl: targetFrame.frame.url(),
+                matchedBy: targetFrame.matchedBy,
+            },
+            steps: result.steps,
+            currentUrl: result.currentUrl,
+            title: result.title,
+        };
+    }
+
+    async assert(options = {}) {
+        const targetFrame = await this._resolveObserveFrame(options);
+        const previousFrame = this._activeFrame;
+        this._activeFrame = targetFrame.frame === this.page.mainFrame() ? null : targetFrame.frame;
+
+        try {
+            const checks = {};
+            let passed = true;
+
+            if (options.selector) {
+                const elementResult = await this._checkElement({ selector: options.selector, expect: options.expect || {} });
+                checks.element = elementResult;
+                if (!elementResult.passed) passed = false;
+            }
+
+            if (options.urlContains) {
+                const currentUrl = this.page.url();
+                checks.urlContains = { expected: options.urlContains, actual: currentUrl, passed: currentUrl.includes(options.urlContains) };
+                if (!checks.urlContains.passed) passed = false;
+            }
+
+            if (options.textContains) {
+                const textResult = await this.safeEval((text) => {
+                    const bodyText = document.body?.innerText || "";
+                    return { expected: text, passed: bodyText.includes(text) };
+                }, options.textContains);
+                checks.textContains = textResult;
+                if (!textResult.passed) passed = false;
+            }
+
+            return {
+                passed,
+                target: {
+                    frameId: targetFrame.frameId,
+                    frameUrl: targetFrame.frame.url(),
+                    matchedBy: targetFrame.matchedBy,
+                },
+                checks,
+            };
+        } finally {
+            this._activeFrame = previousFrame;
+        }
+    }
+
+    async captureApi(options = {}) {
+        const wait = Number.parseInt(options.wait ?? options.timeout ?? 15000, 10);
+        const includeRequestBody = options.includeRequestBody !== false;
+        const includeResponseBody = Boolean(options.includeResponseBody);
+        const methodFilter = options.method ? String(options.method).toUpperCase() : null;
+        const urlPattern = options.urlPattern || options.urlIncludes || "";
+        const targetFrame = await this._resolveObserveFrame(options).catch(() => null);
+        const requests = new Map();
+        const sessions = [];
+        const targets = [];
+        const pendingBodies = [];
+        const startedAt = Date.now();
+
+        const matchesUrl = (url = "") => !urlPattern || url.includes(urlPattern);
+        const matchesMethod = (method = "") => !methodFilter || method.toUpperCase() === methodFilter;
+        const normalizeHeaders = (headers = {}) => Object.fromEntries(Object.entries(headers).map(([key, value]) => [key, String(value)]));
+
+        const addSession = async (session, targetInfo) => {
+            await session.send("Network.enable").catch(() => null);
+            sessions.push(session);
+            targets.push(targetInfo);
+
+            session.on("Network.requestWillBeSent", (event) => {
+                const request = event.request || {};
+                if (!matchesUrl(request.url) || !matchesMethod(request.method)) return;
+                requests.set(`${targetInfo.id}:${event.requestId}`, {
+                    id: event.requestId,
+                    targetId: targetInfo.id,
+                    targetType: targetInfo.type,
+                    targetUrl: targetInfo.url,
+                    frameId: event.frameId,
+                    url: request.url,
+                    method: request.method,
+                    requestHeaders: normalizeHeaders(request.headers),
+                    requestBody: includeRequestBody ? request.postData || null : undefined,
+                    status: null,
+                    responseHeaders: null,
+                    responseBody: null,
+                    responseBodyBase64Encoded: null,
+                    errorText: null,
+                    startTime: Date.now(),
+                    endTime: null,
+                    duration: null,
+                });
+            });
+
+            session.on("Network.responseReceived", (event) => {
+                const item = requests.get(`${targetInfo.id}:${event.requestId}`);
+                if (!item) return;
+                const response = event.response || {};
+                item.status = response.status;
+                item.mimeType = response.mimeType;
+                item.responseHeaders = normalizeHeaders(response.headers);
+                item.responseUrl = response.url;
+            });
+
+            session.on("Network.loadingFinished", async (event) => {
+                const item = requests.get(`${targetInfo.id}:${event.requestId}`);
+                if (!item) return;
+                item.endTime = Date.now();
+                item.duration = item.endTime - item.startTime;
+                if (includeResponseBody) {
+                    const bodyTask = session.send("Network.getResponseBody", { requestId: event.requestId })
+                        .then((body) => {
+                            item.responseBody = body.body;
+                            item.responseBodyBase64Encoded = body.base64Encoded;
+                        })
+                        .catch((err) => {
+                            item.responseBodyError = err.message;
+                        });
+                    pendingBodies.push(bodyTask);
+                }
+            });
+
+            session.on("Network.loadingFailed", (event) => {
+                const item = requests.get(`${targetInfo.id}:${event.requestId}`);
+                if (!item) return;
+                item.endTime = Date.now();
+                item.duration = item.endTime - item.startTime;
+                item.errorText = event.errorText || "loadingFailed";
+            });
+        };
+
+        const pageSession = await this.page.target().createCDPSession();
+        await addSession(pageSession, {
+            id: "page",
+            type: "page",
+            url: this.page.url(),
+            matchedBy: "currentPage",
+        });
+
+        const pageTarget = this.page.target();
+        const attachCandidates = this.browser.targets().filter((target) => {
+            if (target === pageTarget) return false;
+            if (!["iframe", "page"].includes(target.type())) return false;
+            const targetUrl = target.url() || "";
+            if (options.targetUrlContains && !targetUrl.includes(options.targetUrlContains)) return false;
+            if (targetFrame?.frame && targetUrl && targetFrame.frame.url() && targetUrl !== targetFrame.frame.url() && !targetUrl.includes(targetFrame.frame.url())) {
+                return options.includeAllTargets === true;
+            }
+            return true;
+        });
+
+        for (const target of attachCandidates) {
+            const session = await target.createCDPSession().catch(() => null);
+            if (!session) continue;
+            await addSession(session, {
+                id: target.url() || `${target.type()}-${targets.length}`,
+                type: target.type(),
+                url: target.url() || "",
+                matchedBy: "browser.targets",
+            });
+        }
+
+        if (options.reload) {
+            await this.page.reload({ waitUntil: options.waitUntil || "domcontentloaded", timeout: options.reloadTimeout || 30000 }).catch(() => null);
+        }
+
+        await new Promise((resolve) => setTimeout(resolve, wait));
+        await Promise.allSettled(pendingBodies);
+
+        await Promise.all(sessions.map((session) => session.send("Network.disable").catch(() => null)));
+
+        const requestList = Array.from(requests.values()).sort((a, b) => a.startTime - b.startTime);
+        const title = await this.page.title().catch(() => "");
+        const failed = requestList.filter((item) => item.errorText || (item.status && item.status >= 400));
+
+        return {
+            type: "apiCapture",
+            page: {
+                url: this.page.url(),
+                title,
+            },
+            target: targetFrame ? {
+                frameId: targetFrame.frameId,
+                frameUrl: targetFrame.frame.url(),
+                matchedBy: targetFrame.matchedBy,
+            } : null,
+            targets,
+            requests: requestList,
+            summary: {
+                total: requestList.length,
+                success: requestList.length - failed.length,
+                failed: failed.length,
+                targets: targets.length,
+                duration: Date.now() - startedAt,
+            },
+        };
+    }
+
+    assertApi(captureResult, options = {}) {
+        if (!captureResult || !Array.isArray(captureResult.requests)) {
+            throw new Error("assertApi requires an apiCapture result");
+        }
+
+        const requests = captureResult.requests;
+        const expect = options.expect || options;
+        const checks = {};
+        let passed = true;
+
+        if (expect.maxFailed !== undefined) {
+            const actual = requests.filter((item) => item.errorText || (item.status && item.status >= 400)).length;
+            checks.maxFailed = {
+                expected: Number.parseInt(expect.maxFailed, 10),
+                actual,
+                passed: actual <= Number.parseInt(expect.maxFailed, 10),
+            };
+            if (!checks.maxFailed.passed) passed = false;
+        }
+
+        if (expect.forbidStatusGte !== undefined) {
+            const threshold = Number.parseInt(expect.forbidStatusGte, 10);
+            const violations = requests
+                .filter((item) => item.status && item.status >= threshold)
+                .map((item) => ({ url: item.url, method: item.method, status: item.status }));
+            checks.forbidStatusGte = {
+                expected: threshold,
+                violations,
+                passed: violations.length === 0,
+            };
+            if (!checks.forbidStatusGte.passed) passed = false;
+        }
+
+        if (expect.requiredUrls !== undefined) {
+            const requiredUrls = Array.isArray(expect.requiredUrls) ? expect.requiredUrls : [expect.requiredUrls];
+            checks.requiredUrls = requiredUrls.map((url) => {
+                const matched = requests.filter((item) => item.url?.includes(url));
+                return {
+                    url,
+                    matched: matched.length,
+                    passed: matched.length > 0,
+                };
+            });
+            if (checks.requiredUrls.some((item) => !item.passed)) passed = false;
+        }
+
+        if (expect.requiredMethods !== undefined) {
+            const requiredMethods = Array.isArray(expect.requiredMethods) ? expect.requiredMethods : [expect.requiredMethods];
+            checks.requiredMethods = requiredMethods.map((method) => {
+                const normalized = String(method).toUpperCase();
+                const matched = requests.filter((item) => item.method === normalized);
+                return {
+                    method: normalized,
+                    matched: matched.length,
+                    passed: matched.length > 0,
+                };
+            });
+            if (checks.requiredMethods.some((item) => !item.passed)) passed = false;
+        }
+
+        if (expect.minTotal !== undefined) {
+            const expected = Number.parseInt(expect.minTotal, 10);
+            checks.minTotal = {
+                expected,
+                actual: requests.length,
+                passed: requests.length >= expected,
+            };
+            if (!checks.minTotal.passed) passed = false;
+        }
+
+        return {
+            type: "assertApi",
+            passed,
+            checks,
+            summary: captureResult?.summary || {
+                total: requests.length,
+                failed: requests.filter((item) => item.errorText || (item.status && item.status >= 400)).length,
+            },
+        };
+    }
+
+    async _resolveObserveFrame(options = {}) {
+        const frames = this.page.frames();
+        const mainFrame = this.page.mainFrame();
+
+        if (options.frameIndex !== undefined) {
+            const index = Number.parseInt(options.frameIndex, 10);
+            if (frames[index]) {
+                return { frame: frames[index], frameId: index === 0 ? "main" : `frame-${index}`, matchedBy: `frameIndex ${index}` };
+            }
+        }
+
+        if (options.frameUrlContains) {
+            const index = frames.findIndex((frame) => frame.url().includes(options.frameUrlContains));
+            if (index >= 0) {
+                return { frame: frames[index], frameId: index === 0 ? "main" : `frame-${index}`, matchedBy: `url contains "${options.frameUrlContains}"` };
+            }
+        }
+
+        if (options.frameContentContains) {
+            for (let i = 0; i < frames.length; i++) {
+                const matched = await frames[i].evaluate((text) =>
+                    document.body?.innerText?.includes(text) || false,
+                    options.frameContentContains
+                ).catch(() => false);
+                if (matched) {
+                    return { frame: frames[i], frameId: i === 0 ? "main" : `frame-${i}`, matchedBy: `body contains "${options.frameContentContains}"` };
+                }
+            }
+        }
+
+        const mainIndex = frames.indexOf(mainFrame);
+        return { frame: mainFrame, frameId: mainIndex <= 0 ? "main" : `frame-${mainIndex}`, matchedBy: "main" };
+    }
+
+    async _getFrameSummaries() {
+        const frames = this.page.frames();
+        const mainFrame = this.page.mainFrame();
+        const summaries = [];
+        for (let i = 0; i < frames.length; i++) {
+            const frame = frames[i];
+            const title = await frame.evaluate(() => document.title || "").catch(() => "");
+            summaries.push({
+                frameId: frame === mainFrame ? "main" : `frame-${i}`,
+                url: frame.url(),
+                title,
+                isMain: frame === mainFrame,
+            });
+        }
+        return summaries;
+    }
+
+    async _buildDomTree(frame, selector, depth) {
+        return frame.evaluate((rootSelector, maxDepth) => {
+            function attrsOf(el) {
+                const attrs = {};
+                for (const attr of Array.from(el.attributes || [])) {
+                    if (["id", "class", "role", "aria-label", "title", "placeholder", "href", "src", "data-testid"].includes(attr.name)) {
+                        attrs[attr.name] = attr.value.slice(0, 120);
+                    }
+                }
+                return attrs;
+            }
+
+            function directTextOf(el) {
+                return Array.from(el.childNodes || [])
+                    .filter((node) => node.nodeType === Node.TEXT_NODE)
+                    .map((node) => node.textContent.trim())
+                    .filter(Boolean)
+                    .join(" ")
+                    .slice(0, 120);
+            }
+
+            function build(el, currentDepth) {
+                if (!el || currentDepth > maxDepth) return null;
+                const tag = el.tagName?.toLowerCase();
+                if (!tag || ["script", "style", "path"].includes(tag)) return null;
+                const rect = el.getBoundingClientRect();
+                const node = {
+                    tag,
+                    attrs: attrsOf(el),
+                    text: directTextOf(el),
+                    visible: rect.width > 0 && rect.height > 0,
+                    children: [],
+                };
+                for (const child of Array.from(el.children || [])) {
+                    const childNode = build(child, currentDepth + 1);
+                    if (childNode) node.children.push(childNode);
+                }
+                return node;
+            }
+
+            return build(document.querySelector(rootSelector) || document.body, 0);
+        }, selector, depth).catch((err) => ({ error: err.message, tag: "error", attrs: {}, text: "", visible: false, children: [] }));
+    }
+
+    async _collectInteractiveElements(frame, frameId, maxElements) {
+        return frame.evaluate((currentFrameId, limit) => {
+            function cssEscape(value) {
+                if (window.CSS?.escape) return window.CSS.escape(value);
+                return String(value).replace(/["'\\]/g, "\\$&");
+            }
+
+            function getText(el) {
+                return (el.innerText || el.textContent || "").replace(/\s+/g, " ").trim().slice(0, 120);
+            }
+
+            function getName(el, text) {
+                return (
+                    el.getAttribute("aria-label") ||
+                    el.getAttribute("title") ||
+                    el.getAttribute("placeholder") ||
+                    el.getAttribute("alt") ||
+                    text ||
+                    ""
+                ).slice(0, 120);
+            }
+
+            function roleOf(el) {
+                const explicit = el.getAttribute("role");
+                if (explicit) return explicit;
+                const tag = el.tagName.toLowerCase();
+                if (tag === "button") return "button";
+                if (tag === "a") return "link";
+                if (["input", "textarea"].includes(tag)) return "textbox";
+                if (tag === "select") return "combobox";
+                return "generic";
+            }
+
+            function selectorCandidates(el, role, name, text) {
+                const selectors = [];
+                const testId = el.getAttribute("data-testid");
+                if (testId) selectors.push(`[data-testid="${cssEscape(testId)}"]`);
+                if (el.id) selectors.push(`#${cssEscape(el.id)}`);
+                if (role && role !== "generic" && name) selectors.push(`role=${role}[name="${name.replace(/"/g, "\\\"")}"]`);
+                if (text) selectors.push(`text=${text.replace(/"/g, "\\\"")}`);
+                const tag = el.tagName.toLowerCase();
+                const className = typeof el.className === "string" ? el.className.trim().split(/\s+/).filter(Boolean)[0] : "";
+                if (className) selectors.push(`${tag}.${cssEscape(className)}`);
+                selectors.push(tag);
+                return [...new Set(selectors)].slice(0, 5);
+            }
+
+            function isCandidate(el) {
+                const tag = el.tagName.toLowerCase();
+                return ["a", "button", "input", "select", "textarea", "summary"].includes(tag) ||
+                    el.getAttribute("role") ||
+                    el.getAttribute("tabindex") !== null ||
+                    el.onclick ||
+                    el.getAttribute("data-testid") ||
+                    (typeof el.className === "string" && /btn|button|menu-item|ant-btn|ant-menu|ant-select|ant-input/.test(el.className));
+            }
+
+            const viewportWidth = window.innerWidth || document.documentElement.clientWidth;
+            const viewportHeight = window.innerHeight || document.documentElement.clientHeight;
+            return Array.from(document.querySelectorAll("a,button,input,select,textarea,summary,[role],[tabindex],[data-testid],[class*='btn'],[class*='button'],[class*='menu-item'],[class*='ant-btn'],[class*='ant-menu'],[class*='ant-select'],[class*='ant-input']"))
+                .filter(isCandidate)
+                .slice(0, limit)
+                .map((el, idx) => {
+                    const rect = el.getBoundingClientRect();
+                    const style = window.getComputedStyle(el);
+                    const text = getText(el);
+                    const role = roleOf(el);
+                    const name = getName(el, text);
+                    const visible = rect.width > 0 && rect.height > 0 && style.visibility !== "hidden" && style.display !== "none";
+                    return {
+                        index: idx + 1,
+                        frameId: currentFrameId,
+                        tag: el.tagName.toLowerCase(),
+                        role,
+                        name,
+                        text,
+                        selectorCandidates: selectorCandidates(el, role, name, text),
+                        bbox: {
+                            x: Math.round(rect.x),
+                            y: Math.round(rect.y),
+                            width: Math.round(rect.width),
+                            height: Math.round(rect.height),
+                        },
+                        state: {
+                            visible,
+                            enabled: !el.disabled && el.getAttribute("aria-disabled") !== "true",
+                            inViewport: rect.bottom >= 0 && rect.right >= 0 && rect.top <= viewportHeight && rect.left <= viewportWidth,
+                        },
+                    };
+                });
+        }, frameId, maxElements).catch(() => []);
+    }
+
     /**
      * 步骤分发
      */
     async _dispatchStep(step, context) {
         switch (step.type) {
+            case "observe":      return this.observe(step);
+            case "act":          return this.act(step);
+            case "assert":       return this.assert(step);
+            case "apiCapture":   return this.captureApi(step);
+            case "api-capture":  return this.captureApi(step);
+            case "assertApi":    return this.assertApi(step.captureResult || context.lastApiCapture, step);
+            case "assert-api":   return this.assertApi(step.captureResult || context.lastApiCapture, step);
             case "navigate":     return this._navigate(step);
             case "screenshot":   return this._screenshot(step, context);
             case "compare":      return this._compare(step, context);
@@ -649,7 +1475,7 @@ export class BrowserEngine {
  * 动态加载 puppeteer-core，从共享缓存目录加载，缺失时自动安装
  */
 async function loadPuppeteer() {
-    const { ensureSharedDeps, loadFromShared } = await import("./shared-deps.js");
+    const { ensureCoreDeps, loadFromShared } = await import("./shared-deps.js");
 
     // 1. 尝试从项目本地 node_modules 加载（开发环境或已手动安装）
     try {
@@ -659,8 +1485,8 @@ async function loadPuppeteer() {
         // 本地未安装
     }
 
-    // 2. 确保共享缓存已安装，然后从共享目录加载
-    await ensureSharedDeps();
+    // 2. observe/act/assert 主链路只需要 puppeteer-core
+    await ensureCoreDeps();
 
     try {
         return loadFromShared("puppeteer-core");