@nextclaw/x-harness 0.1.0 → 0.1.1

package/dist/browser-dom.js

@@ -1,10 +1,14 @@
-import { createAXHarness, attachImage } from "./readers.js";
+import { createAXHarness } from "./readers-ax-host.js";
 import { readXObservation } from "./observation.js";
-import { xURL } from "./platform.js";
 import { collectCreatorDOM } from "./creator.js";
-import { serialized, missingMethods, valueOf } from "./browser-common.js";
+import { serialized } from "./browser-common.js";
+import { createDOMCapabilities } from "./browser-dom-capabilities.js";
+import { createDOMNavigation } from "./browser-dom-navigation.js";
+import { createDOMEditing } from "./browser-dom-editing.js";
+import { createDOMSubmission } from "./browser-dom-submission.js";
+export { readXNetworkDiagnostics } from "./browser-dom-network.js";
 export function createDOMXBrowser(tab, { readDOM = readXObservation, nativeSubmit = false } = {}) {
-    let current, replyBinding, refreshNotice, editBinding;
+    const session = {};
     const submitAX = nativeSubmit
         ? createAXHarness({
             getAXState: (options) => tab.getAXState(options),
@@ -12,7 +16,7 @@ export function createDOMXBrowser(tab, { readDOM = readXObservation, nativeSubmi
         })
         : null;
     async function observe(query) {
-        current = null;
+        session.current = null;
         const evaluate = tab?.playwright?.evaluate?.bind(tab.playwright);
         if (!evaluate)
             throw new Error("缺playwright.evaluate能力");
@@ -23,9 +27,9 @@ export function createDOMXBrowser(tab, { readDOM = readXObservation, nativeSubmi
         const raw = result;
         // This observed disclosure confirms AI provenance; preserve it without treating it as a rate/login failure.
         result.notices = (result.alerts ?? []).filter((text) => text.trim() === "检测到 AI 生成内容");
-        if (refreshNotice) {
-            result.notices.push(refreshNotice);
-            refreshNotice = null;
+        if (session.refreshNotice) {
+            result.notices.push(session.refreshNotice);
+            session.refreshNotice = null;
         }
         result.alerts = (result.alerts ?? []).filter((text) => text.trim() !== "检测到 AI 生成内容");
         if (query.view === "composer") {
@@ -33,22 +37,23 @@ export function createDOMXBrowser(tab, { readDOM = readXObservation, nativeSubmi
                 raw.editors?.length === 1 ? raw.editors[0].text : null;
             if (result.inlineComposer &&
                 raw.editors?.length === 1 &&
-                replyBinding?.page === result.page &&
-                result.page.match(/\/status\/(\d+)$/)?.[1] === replyBinding.postId)
-                result.replyToId = replyBinding.postId;
+                session.replyBinding?.page === result.page &&
+                result.page.match(/\/status\/(\d+)$/)?.[1] ===
+                    session.replyBinding.postId)
+                result.replyToId = session.replyBinding.postId;
             if (!result.inlineComposer &&
                 raw.editors?.length === 1 &&
-                replyBinding?.body &&
-                replyBinding?.author &&
+                session.replyBinding?.body &&
+                session.replyBinding?.author &&
                 result.replyContexts?.length === 1 &&
-                (result.replyContexts[0].includes(replyBinding.body) ||
+                (result.replyContexts[0].includes(session.replyBinding.body) ||
                     (result.replyQuotes?.length === 1 &&
                         result.replyQuotes[0].length >= 80 &&
-                        replyBinding.body.startsWith(result.replyQuotes[0]))) &&
-                result.replyContexts[0].includes(`回复 @${replyBinding.author}`))
-                result.replyToId = replyBinding.postId;
+                        session.replyBinding.body.startsWith(result.replyQuotes[0]))) &&
+                result.replyContexts[0].includes(`回复 @${session.replyBinding.author}`))
+                result.replyToId = session.replyBinding.postId;
         }
-        current = { query, result };
+        session.current = { query, result };
         return result;
     }
     const locator = (role, label = undefined) => tab.playwright.getByRole(role, label ? { name: label, exact: true } : {});
@@ -57,798 +62,42 @@ export function createDOMXBrowser(tab, { readDOM = readXObservation, nativeSubmi
             throw new Error("DOM语义控件不唯一");
         return loc;
     };
+    const navigation = createDOMNavigation({ session, tab, observe });
+    const editing = createDOMEditing({ session, unique, locator, tab, observe });
+    const finishDOMAction = createDOMSubmission({
+        submitAX,
+        session,
+        tab,
+        observe,
+        unique,
+        locator,
+    });
     return serialized({
-        capabilities(operation) {
-            const base = missingMethods(tab?.playwright, ["evaluate"]);
-            if (operation === "readCreator") {
-                base.push(...missingMethods(tab, [
-                    "url",
-                    "goto",
-                    "reload",
-                    "getAXState",
-                    "scroll",
-                ]));
-                base.push(...missingMethods(tab.playwright, ["locator"]));
-                if (typeof tab.playwright?.locator === "function") {
-                    const article = tab.playwright.locator("article");
-                    base.push(...missingMethods(article, ["first", "getByRole"]));
-                    if (typeof article.first === "function")
-                        base.push(...missingMethods(article.first(), ["waitFor"]));
-                    if (typeof article.getByRole === "function")
-                        base.push(...missingMethods(article.getByRole("button", { name: "显示更多", exact: true }), ["all"]));
-                }
-                return base;
-            }
-            if (["readBookmarks", "searchSources", "readFeedback"].includes(operation)) {
-                base.push(...missingMethods(tab, ["goto"]));
-                base.push(...missingMethods(tab?.playwright, ["getByRole", "waitForURL"]));
-                if (typeof tab?.playwright?.getByRole === "function")
-                    base.push(...missingMethods(tab.playwright.getByRole("article"), [
-                        "first",
-                        "waitFor",
-                    ]));
-                if (operation !== "readFeedback") {
-                    base.push(...missingMethods(tab?.playwright, [
-                        "getByRole",
-                        "getByText",
-                        "locator",
-                        "waitForURL",
-                    ]));
-                    if (typeof tab?.playwright?.getByRole === "function")
-                        base.push(...missingMethods(tab.playwright.getByRole("main"), [
-                            "count",
-                            "click",
-                            "first",
-                            "waitFor",
-                        ]));
-                    if (typeof tab?.playwright?.locator === "function")
-                        base.push(...missingMethods(tab.playwright.locator("a"), [
-                            "count",
-                            "filter",
-                            "press",
-                        ]));
-                    if (typeof tab?.playwright?.getByText === "function")
-                        base.push(...missingMethods(tab.playwright.getByText(""), ["waitFor"]));
-                }
-                return base;
-            }
-            if (operation !== "read")
-                base.push(...missingMethods(tab?.playwright, ["getByRole"]), ...missingMethods(tab, ["goto"]));
-            if (operation !== "read" &&
-                typeof tab?.playwright?.getByRole === "function") {
-                base.push(...missingMethods(tab.playwright.getByRole("button"), [
-                    "count",
-                    "click",
-                ]));
-                if (operation !== "submitFollow")
-                    base.push(...missingMethods(tab.playwright.getByRole("textbox"), [
-                        "count",
-                        "fill",
-                    ]));
-                if (["submitPost", "submitReply"].includes(operation)) {
-                    base.push(...missingMethods(tab.playwright, ["locator", "waitForLoadState"]));
-                    base.push(...missingMethods(tab.playwright.getByRole("button"), [
-                        "and",
-                        "waitFor",
-                    ]));
-                }
-            }
-            if (operation === "refreshPerson" || operation === "refreshPosts") {
-                base.push(...missingMethods(tab, ["reload"]));
-                base.push(...missingMethods(tab?.playwright, ["waitForLoadState"]));
-                if (typeof tab?.playwright?.getByRole === "function")
-                    base.push(...missingMethods(tab.playwright.getByRole("button"), ["waitFor"]));
-            }
-            if (operation === "openOwnPostMenu") {
-                base.push(...missingMethods(tab?.playwright, ["locator"]));
-                if (typeof tab?.playwright?.getByRole === "function")
-                    base.push(...missingMethods(tab.playwright.getByRole("article"), [
-                        "filter",
-                        "getByRole",
-                    ]));
-            }
-            if (operation === "submitEditedPost") {
-                base.push(...missingMethods(tab?.playwright, ["waitForLoadState"]));
-                if (typeof tab?.playwright?.getByRole === "function")
-                    base.push(...missingMethods(tab.playwright.getByRole("button"), ["press"]));
-            }
-            if (operation === "attachAssets")
-                base.push(...missingMethods(tab?.playwright, [
-                    "waitForEvent",
-                    "getByLabel",
-                    "getByPlaceholder",
-                ]));
-            if (nativeSubmit && ["submitPost", "submitReply"].includes(operation))
-                base.push(...missingMethods(tab, ["getAXState", "click"]));
-            return base;
-        },
+        ...createDOMCapabilities({ tab, nativeSubmit }),
         observe,
         async collectCreator({ handle, ...options }) {
-            current = null;
+            session.current = null;
             return collectCreatorDOM(tab, handle, options);
         },
+        screenshot: () => {
+            session.current = null;
+            return tab.screenshot();
+        },
         async act(command) {
-            if (command.operation === "searchSources") {
-                if (typeof command.query !== "string" ||
-                    !command.query.trim() ||
-                    command.query.length > 300)
-                    throw new Error("需一条有效搜索词");
-                current = null;
-                const destination = `https://x.com/search?q=${encodeURIComponent(command.query)}&src=typed_query&f=live`;
-                if (typeof tab.url !== "function" || (await tab.url()) !== destination)
-                    await tab.goto(destination);
-                return;
-            }
-            if (command.operation === "waitForFolder") {
-                await tab.playwright
-                    .getByText(command.folder, { exact: true })
-                    .waitFor({ state: "visible", timeoutMs: 2000 });
-                return;
-            }
-            if (command.operation === "waitForPosts") {
-                await tab.playwright
-                    .getByRole("article")
-                    .first()
-                    .waitFor({ state: "visible", timeoutMs: 5000 });
-                return;
-            }
-            if (command.operation === "openObserved") {
-                xURL(command.url);
-                if (!command.evidenceRef)
-                    throw new Error("导航缺已观察证据");
-                // A direct adapter caller must also preserve a page already at the target.
-                // Explicit recovery uses forceNavigation; durable verification uses refreshPerson.
-                if (!command.forceNavigation &&
-                    typeof tab.url === "function" &&
-                    (await tab.url()) === xURL(command.url).href)
-                    return;
-                const originalPage = current?.result?.page;
-                replyBinding = null;
-                current = null;
-                // Keep the loaded X client when the exact observed permalink is already visible.
-                // An ambiguous/missing link retains the existing navigation path, never an arbitrary click.
-                const path = xURL(command.url).pathname + xURL(command.url).search;
-                let link;
-                if (!command.forceNavigation &&
-                    typeof tab.playwright?.locator === "function") {
-                    link = tab.playwright
-                        .locator(`a[href=${JSON.stringify(path)}]`)
-                        .filter({ visible: true });
-                    if (command.view === "person" &&
-                        /^[A-Za-z0-9_]{1,15}$/.test(command.handle ?? "") &&
-                        (await link.count()) > 1) {
-                        // Avatar and name often share a profile href. Use the exact observed
-                        // handle token to select the name link, never the arbitrary first match.
-                        const named = link.filter({
-                            hasText: new RegExp(`@${command.handle}(?![A-Za-z0-9_])`, "i"),
-                        });
-                        if ((await named.count()) === 1)
-                            link = named;
-                    }
-                }
-                const clickedLink = link && (await link.count()) === 1;
-                if (clickedLink)
-                    await link.click();
-                else
-                    await tab.goto(command.url);
-                try {
-                    await tab.playwright.waitForURL(command.url, { timeoutMs: 5000 });
-                }
-                catch (error) {
-                    // One inert client-link timeout may use the same observed URL directly.
-                    // A changed route, warning, unknown UI or interrupted connection never falls back.
-                    if (!clickedLink ||
-                        !originalPage ||
-                        !/Timed out waiting for URL/.test(error instanceof Error ? error.message : ""))
-                        throw error;
-                    const check = await observe({
-                        view: command.view,
-                        handle: command.handle,
-                        limit: 1,
-                    });
-                    if (check.page !== originalPage ||
-                        check.needsStateCheck ||
-                        check.alerts?.length)
-                        throw error;
-                    await tab.goto(command.url);
-                    await tab.playwright.waitForURL(command.url, { timeoutMs: 5000 });
-                }
-                if (command.view === "person") {
-                    // Profile readiness belongs to profile content; self profiles have no Follow button.
-                    await tab.playwright
-                        .locator('[data-testid="UserName"]')
-                        .waitFor({ state: "visible", timeoutMs: 5000 });
-                }
-                else if (command.view === "composer") {
-                    await tab.playwright
-                        .getByRole("textbox", { name: /^(帖子文本|Post text)$/i })
-                        .waitFor({ state: "visible", timeoutMs: 5000 });
-                }
-                else if (command.view === "posts") {
-                    await tab.playwright
-                        .getByRole("article")
-                        .first()
-                        .waitFor({ state: "visible", timeoutMs: 5000 });
-                }
-                return;
-            }
-            if (command.operation === "refreshPerson") {
-                const at = xURL(await tab.url());
-                replyBinding = null;
-                if (at.href !== xURL(command.url).href ||
-                    at.pathname.toLowerCase() !== `/${command.handle}`.toLowerCase())
-                    throw new Error("持久核验页面不匹配");
-                current = null;
-                // Let the actual UI request settle before reloading; optimistic Following is not durable proof.
-                let idleTimedOut = false;
-                try {
-                    await tab.playwright.waitForLoadState({
-                        state: "networkidle",
-                        timeoutMs: 8000,
-                    });
-                }
-                catch (error) {
-                    if (!/Timed out waiting for networkidle/i.test(error.message ?? ""))
-                        throw error;
-                    // Long-lived X requests can prevent idle; the following reload still
-                    // must expose the target relationship before any fresh observation.
-                    idleTimedOut = true;
-                }
-                await tab.reload();
-                await tab.playwright
-                    .getByRole("button", {
-                    name: new RegExp(`^(?:正在关注|取消关注|关注|回关) @${command.handle}$`, "i"),
-                })
-                    .waitFor({ state: "visible", timeoutMs: 5000 });
-                if (idleTimedOut)
-                    refreshNotice =
-                        "networkidle超时，已沿真实reload与目标关系控件恢复核验";
-                return;
-            }
-            if (command.operation === "refreshPosts") {
-                replyBinding = null;
-                if (!command.evidenceRef ||
-                    xURL(await tab.url()).href !== xURL(command.url).href)
-                    throw new Error("公开核验页面不匹配");
-                current = null;
-                await tab.reload();
-                // Native observation settles the real loading transition when the tab exposes it.
-                if (typeof tab.getAXState === "function")
-                    await tab.getAXState({ emit: false });
-                await tab.playwright
-                    .getByRole("article")
-                    .first()
-                    .waitFor({ state: "visible", timeoutMs: 5000 });
-                return;
-            }
-            if (!current)
+            if (Object.hasOwn(navigation, command.operation))
+                return navigation[command.operation](command);
+            if (!session.current)
                 throw new Error("DOM语义操作必须先observe");
-            const { query, result } = current;
-            let loc, submittedEditor;
-            if (command.operation === "dismissMenu") {
-                if (query.view !== "menu" ||
-                    result.needsStateCheck ||
-                    !result.items?.length)
-                    throw new Error("关闭菜单需已有菜单证据");
-                const item = result.items[0];
-                current = null;
-                await (await unique(locator(item.role, item.label))).press("Escape");
-                return;
-            }
-            else if (command.operation === "openControl") {
-                if (!["navigation", "menu"].includes(query.view) ||
-                    result.needsStateCheck)
-                    throw new Error("导航控件须先唯一观察");
-                const matches = (result.controls ?? result.items ?? []).filter((c) => c.role === command.role &&
-                    c.label === command.label &&
-                    c.href === command.href &&
-                    !c.disabled);
-                if (matches.length !== 1)
-                    throw new Error("导航控件未唯一观察");
-                current = null;
-                await (await unique(command.role === "text"
-                    ? tab.playwright.getByText(command.label, { exact: true })
-                    : locator(command.role, command.label))).click();
-                if (command.href?.startsWith("/"))
-                    await tab.playwright.waitForURL(`https://x.com${command.href}`, {
-                        timeoutMs: 5000,
-                    });
-                return;
-            }
-            else if (command.operation === "openOwnPostMenu") {
-                const post = result.posts?.[0];
-                if (query.view !== "posts" ||
-                    result.needsStateCheck ||
-                    result.posts?.length !== 1 ||
-                    post.id !== command.postId ||
-                    post.author?.toLowerCase() !== result.accountHandle?.toLowerCase() ||
-                    post.primary?.match(/\/status\/(\d+)$/)?.[1] !== command.postId)
-                    throw new Error("编辑需唯一本人原帖");
-                const more = post.buttons.filter((b) => /^(更多|More)$/.test(b.label) && !b.disabled);
-                if (more.length !== 1)
-                    throw new Error("原帖更多按钮未唯一观察");
-                const article = locator("article").filter({
-                    has: tab.playwright.locator(`a[href=${JSON.stringify(post.primary)}]`),
-                    visible: true,
-                });
-                editBinding = {
-                    postId: post.id,
-                    accountHandle: result.accountHandle,
-                    body: post.body,
-                };
-                current = null;
-                await (await unique((await unique(article)).getByRole("button", {
-                    name: more[0].label,
-                    exact: true,
-                }))).click();
-                return;
-            }
-            else if (command.operation === "submitEditedPost") {
-                if (query.view !== "composer" ||
-                    result.needsStateCheck ||
-                    result.alerts?.length ||
-                    !editBinding ||
-                    editBinding.postId !== command.postId ||
-                    result.accountHandle !== editBinding.accountHandle ||
-                    !command.evidenceRef ||
-                    !command.approvedText?.trim() ||
-                    result.editorText !== command.approvedText ||
-                    result.editors?.length !== 1)
-                    throw new Error("编辑提交缺本人原帖绑定或精确审稿证据");
-                const updates = result.buttons.filter((b) => /^(更新|Update)$/.test(b.label) && !b.disabled);
-                if (updates.length !== 1)
-                    throw new Error("编辑更新按钮未唯一观察");
-                const update = await unique(locator("button", updates[0].label));
-                await command.beforeSubmit?.();
-                current = null;
-                editBinding = null;
-                if (command.activation === "keyboard")
-                    await update.press("Enter");
-                else
-                    await update.click();
-                await tab.playwright.waitForLoadState({
-                    state: "networkidle",
-                    timeoutMs: 8000,
-                });
-                return;
-            }
-            else if (command.operation === "expandPost") {
-                if (query.view !== "posts" ||
-                    result.posts?.length !== 1 ||
-                    result.posts[0].id !== command.postId)
-                    throw new Error("展开需唯一原帖");
-                const primary = result.posts[0].primary;
-                const article = locator("article").filter({
-                    has: tab.playwright.locator(`a[href=${JSON.stringify(primary)}]`),
-                    visible: true,
-                });
-                const control = (await unique(article)).getByText(/^(显示更多|Show more)$/i);
-                current = null;
-                await (await unique(control)).click();
-                return;
-            }
-            else if (command.operation === "nextPosts") {
-                if (query.view !== "posts" || result.needsStateCheck)
-                    throw new Error("翻页须先观察原列表");
-                const primary = result.posts?.at(-1)?.primary;
-                if (!primary)
-                    throw new Error("翻页须有已观察原帖链接");
-                const anchor = await unique(tab.playwright
-                    .locator(`a[href=${JSON.stringify(primary)}]`)
-                    .filter({ visible: true }));
-                current = null;
-                await anchor.press("PageDown");
-                return;
-            }
-            else if (command.operation === "clearPreparedText") {
-                if (query.view !== "composer" ||
-                    result.needsStateCheck ||
-                    !command.evidenceRef ||
-                    typeof command.text !== "string" ||
-                    result.editorText?.replace(/\n{3,}/g, "\n\n") !==
-                        command.text.replace(/\n{3,}/g, "\n\n") ||
-                    result.editors?.length !== 1)
-                    throw new Error("仅恢复本次已知稿件准备");
-                const editor = await unique(locator("textbox", result.editors[0].label));
-                await editor.press("Meta+A");
-                await editor.press("Backspace");
-                return observe({ view: "composer" });
-            }
-            else if (command.operation === "closePreparedReply") {
-                if (query.view !== "composer" ||
-                    result.needsStateCheck ||
-                    result.editorText?.trim() !== "" ||
-                    !command.evidenceRef)
-                    throw new Error("仅关闭有准备失败证据的空回复");
-                await (await unique(locator("button", "关闭"))).click();
-                replyBinding = null;
-                return observe({ view: "posts", limit: 5 });
-            }
-            else if (command.operation === "closePreparedMedia") {
-                if (query.view !== "media" ||
-                    result.needsStateCheck ||
-                    !command.evidenceRef)
-                    throw new Error("媒体恢复须有准备失败证据");
-                const backs = result.controls.filter((b) => b.role === "button" &&
-                    /^(返回|Back)$/i.test(b.label) &&
-                    !b.disabled);
-                if (backs.length !== 1)
-                    throw new Error("媒体返回入口不唯一");
-                await (await unique(locator("button", backs[0].label))).click();
-                await tab.playwright
-                    .getByRole("textbox", { name: /^(帖子文本|Post text)$/i })
-                    .waitFor({ state: "visible", timeoutMs: 5000 });
-                return observe({ view: "composer" });
-            }
-            else if (command.operation === "removePreparedMedia") {
-                if (query.view !== "composer" ||
-                    result.needsStateCheck ||
-                    result.editorText?.trim() !== "" ||
-                    !command.evidenceRef)
-                    throw new Error("仅恢复有来源证据的空正文媒体准备");
-                const removes = result.buttons.filter((b) => /^(移除媒体|Remove media)$/i.test(b.label) && !b.disabled);
-                if (removes.length !== 1)
-                    throw new Error("待恢复媒体不唯一");
-                await (await unique(locator("button", removes[0].label))).click();
-                return observe({ view: "composer" });
-            }
-            else if (command.operation === "attachAssets") {
-                if (query.view !== "composer" ||
-                    result.needsStateCheck ||
-                    command.assets?.length !== 1)
-                    throw new Error("仅上传已观察编辑器的一张带ALT图片");
-                const asset = command.assets[0];
-                if (!asset.alt?.trim())
-                    throw new Error("图片须有完整ALT");
-                current = null;
-                await attachImage(tab, { path: asset.path });
-                await tab.playwright
-                    .getByRole("button", {
-                    name: /^(?:编辑|Edit)(?:图片|照片|媒体| image| photo| media)?(?: \d+)?$/i,
-                })
-                    .waitFor({ state: "visible", timeoutMs: 5000 });
-                const composer = await observe({ view: "composer" });
-                const edits = composer.buttons.filter((b) => /^(?:编辑|Edit)(?:图片|照片|媒体| image| photo| media)?(?: \d+)?$/i.test(b.label) && !b.disabled);
-                if (edits.length !== 1)
-                    throw new Error("图片编辑入口未唯一观察");
-                await (await unique(locator("button", edits[0].label))).click();
-                await tab.playwright
-                    .getByRole("tab", {
-                    name: /^(编辑图片描述|Edit image description)$/i,
-                })
-                    .waitFor({ state: "visible", timeoutMs: 5000 });
-                let media = await observe({ view: "media" });
-                const tabControl = media.controls.find((c) => c.role === "tab" &&
-                    /^(编辑图片描述|Edit image description)$/i.test(c.label));
-                if (!tabControl)
-                    throw new Error("ALT页签未观察");
-                await (await unique(locator("tab", tabControl.label))).click();
-                media = await observe({ view: "media" });
-                if (media.needsStateCheck || media.fields.length !== 1)
-                    throw new Error("ALT输入未唯一观察");
-                const field = media.fields[0];
-                const input = field.label
-                    ? tab.playwright.getByLabel(field.label, { exact: true })
-                    : field.placeholder
-                        ? tab.playwright.getByPlaceholder(field.placeholder, {
-                            exact: true,
-                        })
-                        : locator("textbox");
-                await (await unique(input)).fill(asset.alt);
-                media = await observe({ view: "media" });
-                if (media.fields[0]?.value !== asset.alt)
-                    throw new Error("ALT全文不匹配");
-                const save = media.controls.filter((c) => c.role === "button" &&
-                    /^(保存|Save)$/i.test(c.label) &&
-                    !c.disabled);
-                if (save.length !== 1)
-                    throw new Error("ALT保存入口不唯一");
-                await (await unique(locator("button", save[0].label))).click();
-                const after = await observe({ view: "composer" });
-                if (after.needsStateCheck || !after.images?.length)
-                    throw new Error("上传图片未回到编辑器");
-                return {
-                    assets: [{ path: asset.path, alt: asset.alt }],
-                    mediaEvidence: media,
-                    composer: after,
-                };
-            }
-            else if (command.operation === "follow") {
-                if (query.view !== "person" ||
-                    query.handle !== command.handle ||
-                    result.needsStateCheck)
-                    throw new Error("人物身份未绑定");
-                const name = result.relationship === "follows-you"
-                    ? `回关 @${command.handle}`
-                    : `关注 @${command.handle}`;
-                loc = await unique(locator("button", name));
-            }
-            else if (command.operation === "openReply") {
-                replyBinding = null;
-                if (query.targetId !== command.postId || result.posts?.length !== 1)
-                    throw new Error("回复主帖未唯一绑定");
-                const names = result.posts[0].buttons.filter((b) => /回复|Reply/i.test(b.label));
-                if (names.length !== 1)
-                    throw new Error("回复按钮未唯一观察");
-                const primary = result.posts[0].primary;
-                if (!primary ||
-                    primary.match(/\/status\/(\d+)$/)?.[1] !== command.postId)
-                    throw new Error("回复主帖永久链接未绑定");
-                const article = locator("article").filter({
-                    has: tab.playwright.locator(`a[href=${JSON.stringify(primary)}]`),
-                    visible: true,
-                });
-                loc = await unique((await unique(article)).getByRole("button", {
-                    name: names[0].label,
-                    exact: true,
-                }));
-            }
-            else if (command.operation === "fillComposer") {
-                if (query.view !== "composer" || result.editors?.length !== 1)
-                    throw new Error("编辑器未唯一观察");
-                loc = await unique(locator("textbox", result.editors[0].label));
-                current = null;
-                await loc.fill(command.text);
-                const submits = result.buttons.filter((b) => /^(回复|Reply|发帖|发布|Post|更新|Update)$/i.test(b.label));
-                if (submits.length !== 1)
-                    throw new Error("编辑后提交入口不唯一");
-                await locator("button", submits[0].label)
-                    .and(tab.playwright.locator(':not([disabled]):not([aria-disabled="true"])'))
-                    .waitFor({ state: "visible", timeoutMs: 5000 });
-                return;
-            }
-            else if (["submitPost", "submitReply"].includes(command.operation)) {
-                if (query.view !== "composer")
-                    throw new Error("未观察编辑器");
-                const pattern = command.operation === "submitReply"
-                    ? /^(回复|Reply)$/i
-                    : /^(发帖|发布|Post)$/i;
-                const buttons = result.buttons?.filter((b) => pattern.test(b.label) && !b.disabled) ?? [];
-                if (buttons.length !== 1)
-                    throw new Error("提交按钮未唯一观察");
-                loc = await unique(locator("button", buttons[0].label));
-                if (command.activation !== undefined &&
-                    !["click", "keyboard"].includes(command.activation))
-                    throw new Error("提交激活方式无效");
-                if (command.activation === "keyboard" &&
-                    typeof loc.press !== "function")
-                    throw new Error("缺语义按钮键盘提交能力");
-                if (command.operation === "submitReply") {
-                    if (result.editors?.length !== 1 || !result.editorText?.trim())
-                        throw new Error("回复提交缺唯一完整编辑器");
-                    submittedEditor = locator("textbox", result.editors[0].label).filter({
-                        hasText: new RegExp(result.editorText
-                            .trim()
-                            .split(/\s+/)
-                            .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
-                            .join("\\s*")),
-                    });
-                    await unique(submittedEditor);
-                }
-                else {
-                    if (result.editors?.length !== 1 || !result.editorText?.trim())
-                        throw new Error("发帖提交缺唯一完整编辑器");
-                    // Publication with media may stay pending after the click. Do not let
-                    // receipt navigation interrupt it while the submitted text is retained.
-                    submittedEditor = locator("textbox", result.editors[0].label).filter({
-                        hasText: new RegExp(result.editorText
-                            .trim()
-                            .split(/\s+/)
-                            .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
-                            .join("\\s*")),
-                    });
-                    await unique(submittedEditor);
-                }
-            }
-            else
+            const { query, result } = session.current;
+            const handler = Object.hasOwn(editing, command.operation)
+                ? editing[command.operation]
+                : undefined;
+            if (!handler)
                 throw new Error("未封装的DOM动作");
-            const binding = command.operation === "openReply"
-                ? {
-                    page: result.page,
-                    postId: command.postId,
-                    body: result.posts[0].body,
-                    author: result.posts[0].author,
-                }
-                : null;
-            let nativeSubmitIndex;
-            if (submitAX &&
-                ["submitPost", "submitReply"].includes(command.operation)) {
-                const native = await submitAX.observe({ mode: "composer" });
-                const editors = native.evidence?.filter((e) => /^(?:文本输入区(?:域)?|文本区域|文本栏) /.test(e.label)) ?? [];
-                const buttons = native.evidence?.filter((e) => new RegExp(command.operation === "submitReply"
-                    ? "^按钮 (回复|Reply)(?:,|$)"
-                    : "^按钮 (发帖|发布|Post)(?:,|$)", "i").test(e.label)) ?? [];
-                if (native.needsStateCheck ||
-                    native.alerts?.length ||
-                    xURL(native.page).href !== xURL(result.page).href ||
-                    editors.length !== 1 ||
-                    valueOf(editors[0].label)?.trim() !== result.editorText.trim() ||
-                    buttons.length !== 1)
-                    throw new Error("原生提交缺同页、全文及唯一按钮证据");
-                nativeSubmitIndex = buttons[0].index;
-            }
-            if (["submitPost", "submitReply"].includes(command.operation))
-                await command.beforeSubmit?.();
-            current = null;
-            if (nativeSubmitIndex !== undefined)
-                await submitAX.act({
-                    index: nativeSubmitIndex,
-                    operation: "click",
-                    read: { mode: "composer" },
-                });
-            else if (command.activation === "keyboard")
-                await loc.press("Enter");
-            else
-                await loc.click();
-            if (binding) {
-                replyBinding = binding;
-                await tab.playwright
-                    .getByRole("textbox", { name: /^(帖子文本|Post text)$/i })
-                    .waitFor({ state: "visible", timeoutMs: 5000 });
-                if (xURL(await tab.url()).pathname === "/compose/post")
-                    await tab.playwright
-                        .getByText(`回复 @${binding.author}`, { exact: true })
-                        .waitFor({ state: "visible", timeoutMs: 5000 });
-                const composer = await observe({ view: "composer" });
-                const quote = composer.replyQuotes?.length === 1 ? composer.replyQuotes[0] : null;
-                if (!composer.replyToId &&
-                    !composer.needsStateCheck &&
-                    !composer.alerts?.length &&
-                    composer.editorText?.trim() === "" &&
-                    composer.replyContexts?.length === 1 &&
-                    composer.replyContexts[0].includes(`回复 @${binding.author}`) &&
-                    /显示更多|Show more/.test(composer.replyContexts[0]) &&
-                    quote?.length >= 30 &&
-                    binding.body?.startsWith(quote)) {
-                    // Expand the observed quote; the unchanged full-context binding gate must still pass.
-                    const dialog = await unique(locator("dialog").filter({ visible: true }));
-                    const more = await unique(dialog.getByRole("button", { name: /^(显示更多|Show more)$/i }));
-                    current = null;
-                    await more.click();
-                    await observe({ view: "composer" });
-                }
-            }
-            // Inline replies keep the editor mounted. Wait for this submitted text to clear before
-            // receipt navigation/reload can interrupt the actual submission request.
-            if (submittedEditor)
-                await submittedEditor.waitFor({ state: "hidden", timeoutMs: 10000 });
-            if (["submitPost", "submitReply"].includes(command.operation))
-                await tab.playwright.waitForLoadState({
-                    state: "networkidle",
-                    timeoutMs: 8000,
-                });
+            const prepared = await handler(command);
+            if (prepared.completed)
+                return prepared.value;
+            return finishDOMAction(command, prepared, query, result);
         },
-        screenshot: () => {
-            current = null;
-            return tab.screenshot();
-        },
-    });
-}
-// Read-only transport diagnostics through the same real Chrome tab capability.
-// Never return credential headers, cookies or bodies; only numeric rate metadata is allowed.
-export async function readXNetworkDiagnostics(tab, { afterSequence = 0, startObserving = false } = {}) {
-    if (typeof tab?.capabilities?.get !== "function")
-        throw new Error("缺真实Chrome诊断能力");
-    const cdp = await tab.capabilities.get("cdp");
-    if (typeof cdp?.readEvents !== "function")
-        throw new Error("缺只读网络事件能力");
-    if (startObserving)
-        await cdp.send("Network.enable");
-    const result = await cdp.readEvents({
-        afterSequence,
-        limit: 1000,
-        methods: [
-            "Network.requestWillBeSent",
-            "Network.responseReceived",
-            "Network.loadingFailed",
-        ],
     });
-    const traffic = new Map();
-    const times = [];
-    for (const event of result.events) {
-        const p = event.params ?? {};
-        let u;
-        try {
-            u = new URL(p.response?.url ?? p.request?.url);
-        }
-        catch {
-            continue;
-        }
-        if (!((u.hostname === "x.com" && u.pathname.startsWith("/i/api/")) ||
-            u.hostname === "api.x.com"))
-            continue;
-        const location = u.origin + u.pathname;
-        const row = traffic.get(location) ?? {
-            location,
-            requests: 0,
-            responses: 0,
-            statuses: {},
-        };
-        if (event.method === "Network.requestWillBeSent")
-            row.requests++;
-        if (event.method === "Network.responseReceived") {
-            row.responses++;
-            const status = p.response?.status;
-            if (Number.isInteger(status))
-                row.statuses[status] = (row.statuses[status] ?? 0) + 1;
-        }
-        if (Number.isFinite(p.timestamp))
-            times.push(p.timestamp);
-        traffic.set(location, row);
-    }
-    const rates = (headers = {}) => {
-        const allowed = {};
-        for (const [key, value] of Object.entries(headers)) {
-            const name = key.toLowerCase();
-            if (![
-                "x-rate-limit-limit",
-                "x-rate-limit-remaining",
-                "x-rate-limit-reset",
-                "retry-after",
-            ].includes(name))
-                continue;
-            if (!/^\d{1,12}$/.test(String(value).trim()))
-                continue;
-            allowed[name] = Number(value);
-        }
-        const out = {};
-        if (allowed["x-rate-limit-limit"] !== undefined)
-            out.limit = allowed["x-rate-limit-limit"];
-        if (allowed["x-rate-limit-remaining"] !== undefined)
-            out.remaining = allowed["x-rate-limit-remaining"];
-        if (allowed["x-rate-limit-reset"] !== undefined) {
-            const date = new Date(allowed["x-rate-limit-reset"] * 1000);
-            if (Number.isFinite(date.getTime()))
-                out.resetAt = date.toISOString();
-        }
-        if (allowed["retry-after"] !== undefined)
-            out.retryAfterSeconds = allowed["retry-after"];
-        return Object.keys(out).length ? out : undefined;
-    };
-    return {
-        cursor: result.cursor,
-        hasMore: result.hasMore,
-        truncated: result.truncated,
-        traffic: {
-            complete: !result.truncated && !result.hasMore,
-            requests: [...traffic.values()].reduce((n, r) => n + r.requests, 0),
-            responses: [...traffic.values()].reduce((n, r) => n + r.responses, 0),
-            durationSeconds: times.length > 1 ? Math.max(...times) - Math.min(...times) : null,
-            endpointCount: traffic.size,
-            endpoints: [...traffic.values()]
-                .sort((a, b) => b.requests - a.requests)
-                .slice(0, 10),
-        },
-        events: result.events
-            .map((e) => {
-            const p = e.params ?? {};
-            const response = p.response ?? {};
-            let location;
-            try {
-                const u = new URL(response.url ?? p.request?.url);
-                location = ["http:", "https:"].includes(u.protocol)
-                    ? u.origin + u.pathname
-                    : null;
-            }
-            catch {
-                location = null;
-            }
-            return {
-                method: e.method,
-                requestId: p.requestId,
-                location,
-                requestMethod: p.request?.method,
-                status: response.status,
-                errorText: p.errorText,
-                canceled: p.canceled,
-                timestamp: Number.isFinite(p.timestamp) ? p.timestamp : undefined,
-                rateLimit: rates(response.headers),
-            };
-        })
-            .filter((e) => e.method === "Network.loadingFailed" ||
-            (e.location &&
-                (e.status >= 400 ||
-                    e.requestMethod === "POST" ||
-                    /\/(EditTweet|CreateTweet)$/.test(e.location)))),
-    };
 }