@nextclaw/x-harness 0.1.1 → 0.2.0

package/dist/browser-dom-navigation.js

@@ -1,50 +1,71 @@
 import { xURL } from "./platform-rules.js";
-export function createDOMNavigation(dependencies) {
-    const { session, tab, observe } = dependencies;
-    async function searchSources(command) {
+export class DOMNavigation {
+    #session;
+    #tab;
+    #observe;
+    searchSources;
+    waitForFolder;
+    waitForPosts;
+    openObserved;
+    refreshPerson;
+    refreshPosts;
+    constructor(dependencies) {
+        const { session, tab, observe } = dependencies;
+        this.#session = session;
+        this.#tab = tab;
+        this.#observe = observe;
+        this.searchSources = this.handleSearchSources.bind(this);
+        this.waitForFolder = this.handleWaitForFolder.bind(this);
+        this.waitForPosts = this.handleWaitForPosts.bind(this);
+        this.openObserved = this.handleOpenObserved.bind(this);
+        this.refreshPerson = this.handleRefreshPerson.bind(this);
+        this.refreshPosts = this.handleRefreshPosts.bind(this);
+    }
+    async handleSearchSources(command) {
         if (typeof command.query !== "string" ||
             !command.query.trim() ||
             command.query.length > 300)
             throw new Error("需一条有效搜索词");
-        session.current = null;
+        this.#session.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);
+        if (typeof this.#tab.url !== "function" ||
+            (await this.#tab.url()) !== destination)
+            await this.#tab.goto(destination);
         return;
     }
-    async function waitForFolder(command) {
-        await tab.playwright
+    async handleWaitForFolder(command) {
+        await this.#tab.playwright
             .getByText(command.folder, { exact: true })
             .waitFor({ state: "visible", timeoutMs: 2000 });
         return;
     }
-    async function waitForPosts(command) {
-        await tab.playwright
+    async handleWaitForPosts(command) {
+        await this.#tab.playwright
             .getByRole("article")
             .first()
             .waitFor({ state: "visible", timeoutMs: 5000 });
         return;
     }
-    async function openObserved(command) {
+    async handleOpenObserved(command) {
         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)
+            typeof this.#tab.url === "function" &&
+            (await this.#tab.url()) === xURL(command.url).href)
             return;
-        const originalPage = session.current?.result?.page;
-        session.replyBinding = null;
-        session.current = null;
+        const originalPage = this.#session.current?.result?.page;
+        this.#session.replyBinding = null;
+        this.#session.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
+            typeof this.#tab.playwright?.locator === "function") {
+            link = this.#tab.playwright
                 .locator(`a[href=${JSON.stringify(path)}]`)
                 .filter({ visible: true });
             if (command.view === "person" &&
@@ -63,9 +84,9 @@ export function createDOMNavigation(dependencies) {
         if (clickedLink)
             await link.click();
         else
-            await tab.goto(command.url);
+            await this.#tab.goto(command.url);
         try {
-            await tab.playwright.waitForURL(command.url, { timeoutMs: 5000 });
+            await this.#tab.playwright.waitForURL(command.url, { timeoutMs: 5000 });
         }
         catch (error) {
             // One inert client-link timeout may use the same observed URL directly.
@@ -74,7 +95,7 @@ export function createDOMNavigation(dependencies) {
                 !originalPage ||
                 !/Timed out waiting for URL/.test(error instanceof Error ? error.message : ""))
                 throw error;
-            const check = await observe({
+            const check = await this.#observe({
                 view: command.view,
                 handle: command.handle,
                 limit: 1,
@@ -83,39 +104,39 @@ export function createDOMNavigation(dependencies) {
                 check.needsStateCheck ||
                 check.alerts?.length)
                 throw error;
-            await tab.goto(command.url);
-            await tab.playwright.waitForURL(command.url, { timeoutMs: 5000 });
+            await this.#tab.goto(command.url);
+            await this.#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
+            await this.#tab.playwright
                 .locator('[data-testid="UserName"]')
                 .waitFor({ state: "visible", timeoutMs: 5000 });
         }
         else if (command.view === "composer") {
-            await tab.playwright
+            await this.#tab.playwright
                 .getByRole("textbox", { name: /^(帖子文本|Post text)$/i })
                 .waitFor({ state: "visible", timeoutMs: 5000 });
         }
         else if (command.view === "posts") {
-            await tab.playwright
+            await this.#tab.playwright
                 .getByRole("article")
                 .first()
                 .waitFor({ state: "visible", timeoutMs: 5000 });
         }
         return;
     }
-    async function refreshPerson(command) {
-        const at = xURL(await tab.url());
-        session.replyBinding = null;
+    async handleRefreshPerson(command) {
+        const at = xURL(await this.#tab.url());
+        this.#session.replyBinding = null;
         if (at.href !== xURL(command.url).href ||
             at.pathname.toLowerCase() !== `/${command.handle}`.toLowerCase())
             throw new Error("持久核验页面不匹配");
-        session.current = null;
+        this.#session.current = null;
         // Let the actual UI request settle before reloading; optimistic Following is not durable proof.
         let idleTimedOut = false;
         try {
-            await tab.playwright.waitForLoadState({
+            await this.#tab.playwright.waitForLoadState({
                 state: "networkidle",
                 timeoutMs: 8000,
             });
@@ -127,39 +148,34 @@ export function createDOMNavigation(dependencies) {
             // must expose the target relationship before any fresh observation.
             idleTimedOut = true;
         }
-        await tab.reload();
-        await tab.playwright
+        await this.#tab.reload();
+        await this.#tab.playwright
             .getByRole("button", {
             name: new RegExp(`^(?:正在关注|取消关注|关注|回关) @${command.handle}$`, "i"),
         })
             .waitFor({ state: "visible", timeoutMs: 5000 });
         if (idleTimedOut)
-            session.refreshNotice =
+            this.#session.refreshNotice =
                 "networkidle超时，已沿真实reload与目标关系控件恢复核验";
         return;
     }
-    async function refreshPosts(command) {
-        session.replyBinding = null;
+    async handleRefreshPosts(command) {
+        this.#session.replyBinding = null;
         if (!command.evidenceRef ||
-            xURL(await tab.url()).href !== xURL(command.url).href)
+            xURL(await this.#tab.url()).href !== xURL(command.url).href)
             throw new Error("公开核验页面不匹配");
-        session.current = null;
-        await tab.reload();
+        this.#session.current = null;
+        await this.#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
+        if (typeof this.#tab.getAXState === "function")
+            await this.#tab.getAXState({ emit: false });
+        await this.#tab.playwright
             .getByRole("article")
             .first()
             .waitFor({ state: "visible", timeoutMs: 5000 });
         return;
     }
-    return {
-        searchSources,
-        waitForFolder,
-        waitForPosts,
-        openObserved,
-        refreshPerson,
-        refreshPosts,
-    };
+}
+export function createDOMNavigation(...args) {
+    return new DOMNavigation(...args);
 }

package/dist/browser-dom-submission.d.ts

@@ -1,2 +1,7 @@
 import type { DOMDependencies } from "./browser-dom-dependencies.js";
-export declare function createDOMSubmission(dependencies: Pick<DOMDependencies, "submitAX" | "session" | "tab" | "observe" | "unique" | "locator">): (command: any, prepared: any, query: any, result: any) => Promise<void>;
+export declare class DOMSubmission {
+    #private;
+    constructor(dependencies: Pick<DOMDependencies, "submitAX" | "session" | "tab" | "observe" | "unique" | "locator">);
+    finishDOMAction(command: any, prepared: any, query: any, result: any): Promise<void>;
+}
+export declare function createDOMSubmission(...args: ConstructorParameters<typeof DOMSubmission>): (command: any, prepared: any, query: any, result: any) => Promise<void>;

package/dist/browser-dom-submission.js

@@ -1,8 +1,23 @@
 import { xURL } from "./platform-rules.js";
 import { valueOf } from "./browser-common.js";
-export function createDOMSubmission(dependencies) {
-    const { submitAX, session, tab, observe, unique, locator } = dependencies;
-    return async function finishDOMAction(command, prepared, query, result) {
+export class DOMSubmission {
+    #submitAX;
+    #session;
+    #tab;
+    #observe;
+    #unique;
+    #locator;
+    constructor(dependencies) {
+        this.finishDOMAction = this.finishDOMAction.bind(this);
+        const { submitAX, session, tab, observe, unique, locator } = dependencies;
+        this.#submitAX = submitAX;
+        this.#session = session;
+        this.#tab = tab;
+        this.#observe = observe;
+        this.#unique = unique;
+        this.#locator = locator;
+    }
+    async finishDOMAction(command, prepared, query, result) {
         const { loc, submittedEditor } = prepared;
         const binding = command.operation === "openReply"
             ? {
@@ -13,8 +28,9 @@ export function createDOMSubmission(dependencies) {
             }
             : null;
         let nativeSubmitIndex;
-        if (submitAX && ["submitPost", "submitReply"].includes(command.operation)) {
-            const native = await submitAX.observe({ mode: "composer" });
+        if (this.#submitAX &&
+            ["submitPost", "submitReply"].includes(command.operation)) {
+            const native = await this.#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)(?:,|$)"
@@ -30,9 +46,9 @@ export function createDOMSubmission(dependencies) {
         }
         if (["submitPost", "submitReply"].includes(command.operation))
             await command.beforeSubmit?.();
-        session.current = null;
+        this.#session.current = null;
         if (nativeSubmitIndex !== undefined)
-            await submitAX.act({
+            await this.#submitAX.act({
                 index: nativeSubmitIndex,
                 operation: "click",
                 read: { mode: "composer" },
@@ -42,15 +58,15 @@ export function createDOMSubmission(dependencies) {
         else
             await loc.click();
         if (binding) {
-            session.replyBinding = binding;
-            await tab.playwright
+            this.#session.replyBinding = binding;
+            await this.#tab.playwright
                 .getByRole("textbox", { name: /^(帖子文本|Post text)$/i })
                 .waitFor({ state: "visible", timeoutMs: 5000 });
-            if (xURL(await tab.url()).pathname === "/compose/post")
-                await tab.playwright
+            if (xURL(await this.#tab.url()).pathname === "/compose/post")
+                await this.#tab.playwright
                     .getByText(`回复 @${binding.author}`, { exact: true })
                     .waitFor({ state: "visible", timeoutMs: 5000 });
-            const composer = await observe({ view: "composer" });
+            const composer = await this.#observe({ view: "composer" });
             const quote = composer.replyQuotes?.length === 1 ? composer.replyQuotes[0] : null;
             if (!composer.replyToId &&
                 !composer.needsStateCheck &&
@@ -62,11 +78,11 @@ export function createDOMSubmission(dependencies) {
                 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 }));
-                session.current = null;
+                const dialog = await this.#unique(this.#locator("dialog").filter({ visible: true }));
+                const more = await this.#unique(dialog.getByRole("button", { name: /^(显示更多|Show more)$/i }));
+                this.#session.current = null;
                 await more.click();
-                await observe({ view: "composer" });
+                await this.#observe({ view: "composer" });
             }
         }
         // Inline replies keep the editor mounted. Wait for this submitted text to clear before
@@ -74,9 +90,12 @@ export function createDOMSubmission(dependencies) {
         if (submittedEditor)
             await submittedEditor.waitFor({ state: "hidden", timeoutMs: 10000 });
         if (["submitPost", "submitReply"].includes(command.operation))
-            await tab.playwright.waitForLoadState({
+            await this.#tab.playwright.waitForLoadState({
                 state: "networkidle",
                 timeoutMs: 8000,
             });
-    };
+    }
+}
+export function createDOMSubmission(...args) {
+    return new DOMSubmission(...args).finishDOMAction;
 }

package/dist/browser-dom.d.ts

@@ -1,2 +1,14 @@
 export { readXNetworkDiagnostics } from "./browser-dom-network.js";
-export declare function createDOMXBrowser(tab: any, { readDOM, nativeSubmit }?: any): any;
+export declare class DOMXBrowser {
+    #private;
+    capabilities: (operation: any) => any;
+    observe: (query: any) => Promise<any>;
+    constructor(tab: any, { readDOM, nativeSubmit }?: any);
+    private handleObserve;
+    private locator;
+    private unique;
+    collectCreator({ handle, ...options }: import("./types.js").CreatorOptions): Promise<import("./boundary.js").BoundaryRecord>;
+    screenshot(): any;
+    act(command: any): Promise<any>;
+}
+export declare function createDOMXBrowser(...args: ConstructorParameters<typeof DOMXBrowser>): any;

package/dist/browser-dom.js

@@ -7,29 +7,85 @@ 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 } = {}) {
-    const session = {};
-    const submitAX = nativeSubmit
-        ? createAXHarness({
-            getAXState: (options) => tab.getAXState(options),
-            click: (index) => tab.click(index),
-        })
-        : null;
-    async function observe(query) {
-        session.current = null;
-        const evaluate = tab?.playwright?.evaluate?.bind(tab.playwright);
+export class DOMXBrowser {
+    #tab;
+    #readDOM;
+    #nativeSubmit;
+    #session;
+    #submitAX;
+    #navigation;
+    #editing;
+    #finishDOMAction;
+    capabilities;
+    observe;
+    constructor(tab, { readDOM = readXObservation, nativeSubmit = false } = {}) {
+        this.act = this.act.bind(this);
+        this.screenshot = this.screenshot.bind(this);
+        this.collectCreator = this.collectCreator.bind(this);
+        this.#tab = tab;
+        this.#readDOM = readDOM;
+        this.#nativeSubmit = nativeSubmit;
+        this.#session = {};
+        this.#submitAX = this.#nativeSubmit
+            ? createAXHarness({
+                getAXState: (options) => this.#tab.getAXState(options),
+                click: (index) => this.#tab.click(index),
+            })
+            : null;
+        this.#navigation = createDOMNavigation({
+            session: this.#session,
+            tab: this.#tab,
+            observe: this.handleObserve.bind(this),
+        });
+        this.#editing = createDOMEditing({
+            session: this.#session,
+            unique: this.unique.bind(this),
+            locator: this.locator.bind(this),
+            tab: this.#tab,
+            observe: this.handleObserve.bind(this),
+        });
+        this.#finishDOMAction = createDOMSubmission({
+            submitAX: this.#submitAX,
+            session: this.#session,
+            tab: this.#tab,
+            observe: this.handleObserve.bind(this),
+            unique: this.unique.bind(this),
+            locator: this.locator.bind(this),
+        });
+        Object.assign(this, createDOMCapabilities({
+            tab: this.#tab,
+            nativeSubmit: this.#nativeSubmit,
+        }));
+        this.observe = this.handleObserve.bind(this);
+        Object.assign(this, serialized({
+            ...createDOMCapabilities({
+                tab: this.#tab,
+                nativeSubmit: this.#nativeSubmit,
+            }),
+            observe: this.handleObserve.bind(this),
+            collectCreator: this.collectCreator,
+            screenshot: () => {
+                this.#session.current = null;
+                return this.#tab.screenshot();
+            },
+            act: this.act,
+        }));
+    }
+    async handleObserve(query) {
+        this.#session.current = null;
+        const evaluate = this.#tab?.playwright?.evaluate?.bind(this.#tab.playwright);
         if (!evaluate)
             throw new Error("缺playwright.evaluate能力");
-        const result = await evaluate(readDOM, {
+        const result = await evaluate(this.#readDOM, {
             ...query,
             limit: query.limit ?? 1,
         });
         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 (session.refreshNotice) {
-            result.notices.push(session.refreshNotice);
-            session.refreshNotice = null;
+        if (this.#session.refreshNotice) {
+            result.notices.push(this.#session.refreshNotice);
+            this.#session.refreshNotice = null;
         }
         result.alerts = (result.alerts ?? []).filter((text) => text.trim() !== "检测到 AI 生成内容");
         if (query.view === "composer") {
@@ -37,67 +93,58 @@ export function createDOMXBrowser(tab, { readDOM = readXObservation, nativeSubmi
                 raw.editors?.length === 1 ? raw.editors[0].text : null;
             if (result.inlineComposer &&
                 raw.editors?.length === 1 &&
-                session.replyBinding?.page === result.page &&
+                this.#session.replyBinding?.page === result.page &&
                 result.page.match(/\/status\/(\d+)$/)?.[1] ===
-                    session.replyBinding.postId)
-                result.replyToId = session.replyBinding.postId;
+                    this.#session.replyBinding.postId)
+                result.replyToId = this.#session.replyBinding.postId;
             if (!result.inlineComposer &&
                 raw.editors?.length === 1 &&
-                session.replyBinding?.body &&
-                session.replyBinding?.author &&
+                this.#session.replyBinding?.body &&
+                this.#session.replyBinding?.author &&
                 result.replyContexts?.length === 1 &&
-                (result.replyContexts[0].includes(session.replyBinding.body) ||
+                (result.replyContexts[0].includes(this.#session.replyBinding.body) ||
                     (result.replyQuotes?.length === 1 &&
                         result.replyQuotes[0].length >= 80 &&
-                        session.replyBinding.body.startsWith(result.replyQuotes[0]))) &&
-                result.replyContexts[0].includes(`回复 @${session.replyBinding.author}`))
-                result.replyToId = session.replyBinding.postId;
+                        this.#session.replyBinding.body.startsWith(result.replyQuotes[0]))) &&
+                result.replyContexts[0].includes(`回复 @${this.#session.replyBinding.author}`))
+                result.replyToId = this.#session.replyBinding.postId;
         }
-        session.current = { query, result };
+        this.#session.current = { query, result };
         return result;
     }
-    const locator = (role, label = undefined) => tab.playwright.getByRole(role, label ? { name: label, exact: true } : {});
-    const unique = async (loc) => {
+    locator(role, label = undefined) {
+        return this.#tab.playwright.getByRole(role, label ? { name: label, exact: true } : {});
+    }
+    async unique(loc) {
         if ((await loc.count()) !== 1)
             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({
-        ...createDOMCapabilities({ tab, nativeSubmit }),
-        observe,
-        async collectCreator({ handle, ...options }) {
-            session.current = null;
-            return collectCreatorDOM(tab, handle, options);
-        },
-        screenshot: () => {
-            session.current = null;
-            return tab.screenshot();
-        },
-        async act(command) {
-            if (Object.hasOwn(navigation, command.operation))
-                return navigation[command.operation](command);
-            if (!session.current)
-                throw new Error("DOM语义操作必须先observe");
-            const { query, result } = session.current;
-            const handler = Object.hasOwn(editing, command.operation)
-                ? editing[command.operation]
-                : undefined;
-            if (!handler)
-                throw new Error("未封装的DOM动作");
-            const prepared = await handler(command);
-            if (prepared.completed)
-                return prepared.value;
-            return finishDOMAction(command, prepared, query, result);
-        },
-    });
+    }
+    async collectCreator({ handle, ...options }) {
+        this.#session.current = null;
+        return collectCreatorDOM(this.#tab, handle, options);
+    }
+    screenshot() {
+        this.#session.current = null;
+        return this.#tab.screenshot();
+    }
+    async act(command) {
+        if (Object.hasOwn(this.#navigation, command.operation))
+            return this.#navigation[command.operation](command);
+        if (!this.#session.current)
+            throw new Error("DOM语义操作必须先observe");
+        const { query, result } = this.#session.current;
+        const handler = Object.hasOwn(this.#editing, command.operation)
+            ? this.#editing[command.operation]
+            : undefined;
+        if (!handler)
+            throw new Error("未封装的DOM动作");
+        const prepared = await handler(command);
+        if (prepared.completed)
+            return prepared.value;
+        return this.#finishDOMAction(command, prepared, query, result);
+    }
+}
+export function createDOMXBrowser(...args) {
+    return new DOMXBrowser(...args);
 }

package/dist/browser-native.d.ts

@@ -1 +1,14 @@
-export declare function createNativeXBrowser(app: any): any;
+import type { BoundaryRecord } from "./boundary.js";
+export declare class NativeXBrowser {
+    #private;
+    observe: (query: any) => Promise<any>;
+    constructor(app: any);
+    private navigateNativeTarget;
+    private handleObserve;
+    private one;
+    collectCreator(args: import("./types.js").CreatorOptions): Promise<BoundaryRecord>;
+    capabilities(operation: any): any;
+    act(command: any): Promise<any>;
+    screenshot(): any;
+}
+export declare function createNativeXBrowser(...args: ConstructorParameters<typeof NativeXBrowser>): any;