@nextclaw/x-harness 0.1.0 → 0.2.0

package/dist/readers.js

@@ -1,1045 +1,9 @@
-// Self-contained, read-only DOM function for cua_repl's documented evaluate.
-export function readPosts({ offset = 0, limit = 5, targetId = "", } = {}) {
-    if (!Number.isInteger(offset) ||
-        offset < 0 ||
-        !Number.isInteger(limit) ||
-        limit < 1 ||
-        limit > 5)
-        throw new Error("offset>=0；limit为1～5");
-    if (targetId && !/^\d+$/.test(targetId))
-        throw new Error("targetId必须是数字公开ID");
-    const visible = (el) => el.getClientRects().length > 0;
-    const primaryTime = (a) => Array.from(a.querySelectorAll("time")).find((t) => visible(t) &&
-        /\/status\/\d+(?:$|[/?#])/.test(t.closest("a")?.getAttribute("href") ?? "")) ?? null;
-    const all = Array.from(document.querySelectorAll("article")).filter(visible);
-    const candidates = targetId
-        ? all.filter((a) => {
-            const primary = primaryTime(a)?.closest("a")?.getAttribute("href");
-            return (primary && new RegExp(`/status/${targetId}(?:$|[/?#])`).test(primary));
-        })
-        : all;
-    const posts = candidates.slice(offset, offset + limit).map((a) => {
-        const time = primaryTime(a);
-        const primary = time?.closest("a")?.getAttribute("href") ?? null;
-        const links = [
-            ...new Set(Array.from(a.querySelectorAll("a[href]"))
-                .filter(visible)
-                .map((l) => l.getAttribute("href"))),
-        ];
-        const buttons = Array.from(a.querySelectorAll("button"))
-            .filter(visible)
-            .map((b) => ({
-            label: b.getAttribute("aria-label") || b.innerText,
-            disabled: b.hasAttribute("disabled"),
-        }));
-        const text = a.innerText;
-        const datetime = time?.getAttribute("datetime") ?? null;
-        const id = primary?.match(/\/status\/(\d+)/)?.[1] ?? null;
-        const author = primary?.match(/\/([^/]+)\/status\//)?.[1] ?? null;
-        const images = Array.from(a.querySelectorAll('[data-testid="tweetPhoto"] img'))
-            .filter(visible)
-            .map((img) => ({
-            alt: img.getAttribute("alt"),
-            src: img.getAttribute("src"),
-        }));
-        const media = Array.from(a.querySelectorAll('[data-testid="videoPlayer"],video'))
-            .filter(visible)
-            .map((el) => ({
-            kind: "video",
-            label: el.getAttribute("aria-label"),
-            poster: el.getAttribute("poster"),
-            requiresViewing: true,
-        }));
-        return {
-            id,
-            author,
-            datetime,
-            primary,
-            text,
-            links,
-            buttons,
-            // View/quote counts may be visible links rather than buttons; collect in this same read.
-            metrics: [
-                ...buttons,
-                ...Array.from(a.querySelectorAll('a[href$="/analytics"],a[href$="/quotes"]'))
-                    .filter(visible)
-                    .map((link) => ({
-                    label: link.getAttribute("aria-label") ||
-                        `${link.getAttribute("href").endsWith("/analytics") ? "观看" : "引用"} ${link.innerText}`,
-                })),
-            ],
-            images,
-            media,
-            needsExpansion: /显示更多|Show more/i.test(text),
-            missing: [
-                !id && "id",
-                !author && "author",
-                !datetime && "datetime",
-                !text && "text",
-            ].filter(Boolean),
-        };
-    });
-    const versionLinks = Array.from(document.querySelectorAll("a[href]"))
-        .filter(visible)
-        .filter((a) => /最新版本|查看最新帖子|Latest version|View latest/i.test(a.innerText))
-        .slice(0, 5)
-        .map((a) => ({ label: a.innerText, href: a.getAttribute("href") }));
-    const emptyEvidence = all.length === 0
-        ? [
-            ...new Set(Array.from(document.querySelectorAll("main span"))
-                .filter(visible)
-                .map((e) => e.innerText?.trim())
-                .filter((text) => text &&
-                text.length <= 400 &&
-                !text.includes("\n") &&
-                /^(?:没有.*结果|未找到.*结果|No results for)/i.test(text))),
-        ].slice(0, 2)
-        : [];
-    return {
-        renderedArticles: all.length,
-        matched: candidates.length,
-        offset,
-        moreInDOM: candidates.length > offset + posts.length,
-        pageComplete: false,
-        needsStateCheck: all.length === 0 && emptyEvidence.length === 0,
-        posts,
-        versionLinks,
-        emptyEvidence,
-        alerts: Array.from(document.querySelectorAll('[role="alert"]'))
-            .filter(visible)
-            .map((e) => e.innerText),
-    };
-}
-export function changes(result, cache, page, fresh = false) {
-    const unchangedIds = [];
-    const posts = result.posts.filter((post) => {
-        if (!post.id)
-            return true;
-        const key = `${page}|${post.id}`;
-        const value = JSON.stringify(post);
-        const changed = cache[key] !== value;
-        cache[key] = value;
-        if (!fresh && !changed)
-            unchangedIds.push(post.id);
-        return fresh || changed;
-    });
-    const outputChars = JSON.stringify({ ...result, posts, unchangedIds }).length;
-    const optimizationHint = outputChars > 8000
-        ? posts.length > 1
-            ? "缩小读取窗口或按已观察ID定向读取；保留完整正文"
-            : "单篇证据本身长，保留全文，不截断"
-        : null;
-    return {
-        ...result,
-        posts,
-        unchanged: result.posts.length - posts.length,
-        unchangedIds,
-        fresh,
-        outputChars,
-        optimizationHint,
-    };
-}
-// Native Chrome fallback: process a suppressed full AX observation in the REPL.
-// Keeps visible leaf evidence and action indexes; never reconstructs a diff as a full page.
-export function readAX(state, { mode = "posts", offset = 0, limit = 1, targetId = "", targetHandle = "", } = {}) {
-    if (!["posts", "composer", "profile", "people", "navigation"].includes(mode))
-        throw new Error("AX mode必须为posts/composer/profile/people/navigation");
-    if (typeof state !== "string")
-        throw new Error("AX state必须为完整字符串");
-    if (!Number.isInteger(offset) ||
-        offset < 0 ||
-        !Number.isInteger(limit) ||
-        limit < 1 ||
-        limit > 5 ||
-        (targetId && !/^\d+$/.test(targetId)))
-        throw new Error("无效AX读取窗口或ID");
-    if (targetHandle && (mode !== "people" || !/^\w{1,15}$/.test(targetHandle)))
-        throw new Error("targetHandle必须为people模式已观察的handle");
-    const alertLines = state
-        .split("\n")
-        .filter((line) => /抱歉.*限制|速度限制|请求异常|访问受限|验证码|验证挑战|登录以继续|captcha|rate limit/i.test(line));
-    const unknown = (reason) => ({
-        mode,
-        posts: [],
-        evidence: [],
-        alerts: alertLines,
-        missing: [reason],
-        needsStateCheck: true,
-        pageComplete: false,
-    });
-    if (/following is a diff|Removed element IDs:|no change in the accessibility tree/i.test(state))
-        return unknown("full-ax-required");
-    const page = state.match(/URL:\s*((?:https?:\/\/)?x\.com\/[^\s,]*)/)?.[1];
-    if (!page && mode !== "navigation")
-        return unknown("x-page-unconfirmed");
-    const nodes = [], stack = [];
-    for (const line of state.split("\n")) {
-        const match = line.match(/^(\s*)(\d+) (.*)$/);
-        // Multiline post text such as "37 位中文主样本" is not an AX node.
-        if (!match ||
-            (!match[1] && !/^(?:标准窗口|window|menu bar)(?: |$)/i.test(match[3]))) {
-            if (nodes.length &&
-                line.trim() &&
-                !/^The focused UI|Window:|Wall time:|Output:/.test(line))
-                nodes.at(-1).label += "\n" + line;
-            continue;
-        }
-        const depth = match[1].replace(/\t/g, "    ").length;
-        while (stack.length && nodes[stack.at(-1)].depth >= depth)
-            stack.pop();
-        // Chrome tab AX uses English role names; native app AX uses the canonical labels below.
-        const label = match[3]
-            .replace(/^link Description: /, "link ")
-            .replace(/^combo box(?: \([^)]*\))? (?:Description: )?/, "组合框 ")
-            .replace(/^button(?: \((?![^)]*disabled)[^)]*\))? /, "按钮 ")
-            .replace(/^text entry area(?: \(settable\))? Description: /, "文本输入区域 ");
-        const node = {
-            index: Number(match[2]),
-            label,
-            depth,
-            parent: stack.at(-1) ?? null,
-        };
-        nodes.push(node);
-        stack.push(nodes.length - 1);
-    }
-    const descendants = (i) => {
-        let end = i + 1;
-        while (end < nodes.length && nodes[end].depth > nodes[i].depth)
-            end++;
-        return nodes.slice(i + 1, end);
-    };
-    const leaf = (n) => /^(?:文本(?: |$)|text |link |按钮 |弹出式按钮 |切换按钮 |图像 |文本输入区(?:域)? |文本区域 |文本栏 |组合框 |单选按钮 |复选框 )/.test(n.label) || /^container [\d,.万亿KMB]+ 次(?:观看|查看)$/.test(n.label);
-    const evidence = (ns) => ns.filter(leaf).map(({ index, label }) => ({ index, label }));
-    // Missing business evidence must not force callers to print the entire AX tree.
-    const navigation = nodes
-        .filter((n) => /^(?:标准窗口|window|HTML 内容) .*URL:/.test(n.label) ||
-        /^文本栏 .*地址和搜索栏/.test(n.label) ||
-        /^按钮 (?:重新加载|新标签页)$/.test(n.label) ||
-        n.label === "窗口" ||
-        /^标签 \(selected/.test(n.label) ||
-        /^(?:tab|标签)(?: \([^)]*\))? (?:帖子|回复|转帖|媒体|文章|Posts|Replies|Reposts|Media|Articles)(?:,|$)/.test(n.label) ||
-        /^组合框 (?:查询词条|Search)(?:,|$)/.test(n.label) ||
-        /^link (?:主页|搜索和发现|通知|个人资料), Value: x\.com\//.test(n.label))
-        .map(({ index, label }) => ({ index, label }));
-    const roots = [];
-    const within = (node, root) => {
-        let p = node.parent;
-        while (p !== null) {
-            if (p === root)
-                return true;
-            p = nodes[p].parent;
-        }
-        return false;
-    };
-    nodes.forEach((n, i) => {
-        // Chrome's window container also contains @handle and every post link.
-        if (!/^(?:container |article ).*@\w+/.test(n.label) ||
-            /\bURL:/.test(n.label))
-            return;
-        if (roots.some((root) => within(n, root)))
-            return;
-        if (descendants(i).some((d) => /^link /.test(d.label) && /x\.com\/\w+\/status\/\d+/.test(d.label)))
-            roots.push(i);
-    });
-    const peopleTimeline = nodes.findIndex((n) => /^container 时间线：(认证关注者|关注者|正在关注)$/.test(n.label));
-    const peopleRoots = peopleTimeline < 0
-        ? []
-        : nodes
-            .map((n, i) => ({ n, i }))
-            .filter(({ n, i }) => within(n, peopleTimeline) &&
-            /^按钮 .*@\w+(?: |$)/.test(n.label) &&
-            descendants(i).some((d) => /^link @\w+, Value: x\.com\/\w+(?:,|$)/.test(d.label)))
-            .map(({ i }) => i);
-    const warning = /抱歉.*限制|速度限制|请求异常|访问受限|验证码|验证挑战|登录以继续|captcha|rate limit/i;
-    const explicitAlert = (n) => {
-        let current = n;
-        while (current) {
-            if (/^(?:alert|警告|对话框|dialog|status|状态)(?: |$)/i.test(current.label))
-                return true;
-            current = current.parent === null ? null : nodes[current.parent];
-        }
-        return /^(?:文本输入区(?:域)?|文本区域|文本栏|按钮) /i.test(n.label);
-    };
-    const alerts = nodes
-        .filter((n, i) => warning.test(n.label) &&
-        (![...roots, ...peopleRoots].some((root) => i === root || within(n, root)) ||
-            explicitAlert(n)) &&
-        !descendants(i).some((d) => warning.test(d.label)))
-        .map((n) => ({ index: n.index, label: n.label }));
-    if (mode === "navigation")
-        return {
-            mode,
-            page,
-            posts: [],
-            evidence: navigation,
-            alerts,
-            pageComplete: false,
-            needsStateCheck: !navigation.length,
-            missing: navigation.length ? [] : ["navigation-not-found"],
-        };
-    if (mode === "people") {
-        const all = peopleRoots.map((i) => ({
-            handle: nodes[i].label.match(/@(\w+)/)[1],
-            evidence: evidence(descendants(i)),
-        }));
-        const matches = targetHandle
-            ? all.filter((p) => p.handle.toLowerCase() === targetHandle.toLowerCase())
-            : all;
-        const missing = peopleTimeline < 0
-            ? ["people-timeline-not-found"]
-            : !matches.length
-                ? ["person-not-found"]
-                : targetHandle && matches.length > 1
-                    ? ["person-ambiguous"]
-                    : [];
-        return {
-            mode,
-            page,
-            posts: [],
-            people: missing.length ? [] : matches.slice(offset, offset + limit),
-            renderedPeople: all.length,
-            matched: matches.length,
-            offset,
-            moreInDOM: matches.length > offset + limit,
-            alerts,
-            navigation: missing.length ? navigation : undefined,
-            missing,
-            needsStateCheck: !!missing.length,
-            pageComplete: false,
-        };
-    }
-    if (mode === "posts") {
-        const all = roots.map((i) => {
-            const postNodes = descendants(i);
-            const items = evidence(postNodes);
-            const authorHandle = nodes[i].label.match(/@(\w+)/)?.[1];
-            const primary = items.find((n) => /^link /.test(n.label) &&
-                n.label
-                    .match(/x\.com\/(\w+)\/status\/\d+(?:[?#][^\s,]*)?(?:,|$)/)?.[1]
-                    ?.toLowerCase() === authorHandle?.toLowerCase());
-            const edited = postNodes.filter((n) => /^link 这是该帖子的最新版本。/.test(n.label) &&
-                n.label
-                    .match(/x\.com\/(\w+)\/status\/\d+\/history(?:,|$)/)?.[1]
-                    ?.toLowerCase() === authorHandle?.toLowerCase() &&
-                !postNodes.some((q) => /^(?:container |article )引用(?: |$)/.test(q.label) &&
-                    within(n, nodes.indexOf(q))));
-            const source = primary ?? (edited.length === 1 ? edited[0] : null);
-            const match = source?.label.match(/x\.com\/(\w+)\/status\/(\d+)/);
-            const text = items
-                .filter((n) => /^(?:文本 |text )/.test(n.label))
-                .map((n) => n.label.replace(/^(?:文本 |text )/, ""))
-                .join("\n");
-            return {
-                id: match?.[2] ?? null,
-                author: match?.[1] ?? null,
-                primary: source?.label ?? null,
-                datetime: null,
-                timeEvidence: source?.label ?? null,
-                text,
-                evidence: items,
-                needsExpansion: /显示更多|Show more/i.test(text) ||
-                    items.some((n) => /显示更多|Show more/i.test(n.label)),
-                missing: [!match && "id", !text && "text", "datetime"].filter(Boolean),
-            };
-        });
-        const candidates = targetId
-            ? all.filter((p) => p.id === targetId)
-            : all;
-        return {
-            mode,
-            page,
-            renderedArticles: all.length,
-            matched: candidates.length,
-            offset,
-            moreInDOM: candidates.length > offset + limit,
-            pageComplete: false,
-            needsStateCheck: candidates.length === 0,
-            missing: candidates.length ? [] : ["post-not-found"],
-            posts: candidates.slice(offset, offset + limit),
-            alerts,
-            navigation: candidates.length ? undefined : navigation,
-        };
-    }
-    if (mode === "profile") {
-        const start = nodes.findIndex((n) => n.label === "container 主页时间线");
-        if (start < 0)
-            return { ...unknown("profile-not-found"), page, alerts, navigation };
-        const main = descendants(start), end = main.findIndex((n) => /container 个人资料时间线/.test(n.label));
-        if (end < 0)
-            return {
-                ...unknown("profile-boundary-not-found"),
-                page,
-                alerts,
-                navigation,
-            };
-        return {
-            mode,
-            page,
-            posts: [],
-            evidence: evidence(main.slice(0, end)),
-            alerts,
-            pageComplete: false,
-            needsStateCheck: false,
-        };
-    }
-    const dialog = nodes.findIndex((n) => /^(?:对话框|dialog)(?: |$)/.test(n.label));
-    if (dialog < 0) {
-        const editors = nodes.filter((n) => /^(?:文本输入区(?:域)?|文本区域|文本栏) /.test(n.label));
-        const submits = nodes.filter((n) => /^按钮 (?:回复|Reply)(?:,|$)/i.test(n.label));
-        if (/x\.com\/\w+\/status\/\d+(?:[?#]|$)/.test(page ?? "") &&
-            editors.length === 1 &&
-            submits.length === 1) {
-            return {
-                mode,
-                page,
-                inlineComposer: true,
-                posts: [],
-                evidence: evidence([...editors, ...submits]),
-                alerts,
-                pageComplete: false,
-                needsStateCheck: false,
-            };
-        }
-        return {
-            ...unknown("composer-dialog-not-found"),
-            page,
-            alerts,
-            navigation,
-        };
-    }
-    const items = evidence(descendants(dialog));
-    if (!items.some((n) => /^(?:文本输入区(?:域)?|文本区域|文本栏) /.test(n.label)) ||
-        !items.some((n) => /^按钮 (?:发帖|发布|回复|Post|Reply)(?:,|$)/i.test(n.label))) {
-        return {
-            ...unknown("composer-boundary-unconfirmed"),
-            page,
-            alerts,
-            navigation,
-        };
-    }
-    return {
-        mode,
-        page,
-        posts: [],
-        evidence: items,
-        alerts,
-        pageComplete: false,
-        needsStateCheck: false,
-    };
-}
-// Native operations share one observation boundary. No raw AX leaves this session.
-// Browser Tab input takes (index, value), while native App input takes (value).
-export function createAXTabHarness(tab) {
-    return createAXHarness({
-        getAXState: (options) => tab.getAXState(options),
-        click: (index) => tab.click(index),
-        pressKey: (key) => tab.pressKey(null, key),
-        paste: (value) => tab.paste(null, value),
-        scroll: (...args) => tab.scroll(...args),
-        getScreenshot: (options) => tab.getScreenshot(options),
-    });
-}
-export function createAXHarness(app) {
-    let controls = new Map(), readable = false, busy = false;
-    const requireMethods = (methods) => {
-        const missing = methods.filter((name) => typeof app?.[name] !== "function");
-        if (missing.length) {
-            controls.clear();
-            readable = false;
-            throw new Error(`harness能力不足：${missing.join("/")}；先补原入口并验证，未执行操作`);
-        }
-    };
-    const indexes = (value) => {
-        if (!value || typeof value !== "object")
-            return;
-        if (Number.isInteger(value.index) && typeof value.label === "string")
-            controls.set(value.index, value.label);
-        for (const child of Object.values(value))
-            indexes(child);
-    };
-    const observe = async (options = {}) => {
-        controls.clear();
-        readable = false;
-        readAX("", options);
-        requireMethods(["getAXState"]);
-        const result = readAX(await app.getAXState({ emit: false, disableDiffing: true }), options);
-        indexes(result);
-        readable = true;
-        return result;
-    };
-    return {
-        async observe(options = {}) {
-            if (busy)
-                throw new Error("AX操作进行中，禁止并发读取");
-            busy = true;
-            try {
-                return await observe(options);
-            }
-            finally {
-                busy = false;
-            }
-        },
-        async act({ index, operation = "click", value, read = {}, } = {}) {
-            if (busy)
-                throw new Error("AX操作进行中，禁止并发写入");
-            if (!readable || !controls.has(index))
-                throw new Error("必须先observe；index须来自最新定向证据");
-            if (!["click", "fill", "paste", "pressKey", "scroll", "secondary"].includes(operation))
-                throw new Error("未封装的AX操作，先补能力并验证");
-            // Validate before any side effect; a malformed follow-up read must never submit.
-            readAX("", read);
-            if (["fill", "paste", "pressKey", "secondary"].includes(operation) &&
-                typeof value !== "string")
-                throw new Error("AX操作value须为字符串");
-            if (["fill", "paste", "pressKey"].includes(operation) &&
-                !/^(?:文本输入区(?:域)?|文本区域|文本栏|组合框) /.test(controls.get(index)))
-                throw new Error("键盘操作须定位最新证据中的编辑控件");
-            if (operation === "secondary" &&
-                !controls.get(index).includes(`Secondary Actions: ${value}`))
-                throw new Error("未观察到该辅助动作");
-            if (operation === "scroll" &&
-                !["up", "down", "left", "right"].includes(value))
-                throw new Error("无效滚动方向");
-            const methods = operation === "fill"
-                ? ["click", "pressKey", "paste"]
-                : ["paste", "pressKey"].includes(operation)
-                    ? ["click", operation]
-                    : [
-                        operation === "secondary"
-                            ? "performSecondaryAction"
-                            : operation,
-                    ];
-            requireMethods([...methods, "getAXState"]);
-            busy = true;
-            controls.clear();
-            readable = false;
-            try {
-                if (operation === "click")
-                    await app.click(index);
-                else if (["fill", "paste", "pressKey"].includes(operation)) {
-                    await app.click(index);
-                    if (operation === "fill") {
-                        await app.pressKey("super+a");
-                        await app.paste(value);
-                    }
-                    else
-                        await app[operation](value);
-                }
-                else if (operation === "scroll")
-                    await app.scroll(index, value, 1);
-                else
-                    await app.performSecondaryAction(index, value);
-                return await observe(read);
-            }
-            finally {
-                busy = false;
-            }
-        },
-        async screenshot() {
-            if (busy)
-                throw new Error("AX操作进行中，禁止并发截图");
-            requireMethods(["getScreenshot"]);
-            busy = true;
-            controls.clear();
-            readable = false;
-            try {
-                return await app.getScreenshot({ emit: false });
-            }
-            finally {
-                busy = false;
-            }
-        },
-    };
-}
-export function setupCode() {
-    return `var xReadPosts = ${readPosts.toString()};\nvar xReadChanges = ${changes.toString()};\nvar xReadProfile = ${readProfile.toString()};\nvar xScreenCandidates = ${screenCandidates.toString()};\nvar xReadAX = ${readAX.toString()};\nvar xCreateAXHarness = (function(readAX) { return ${createAXHarness.toString()}; })(xReadAX);\nvar xAXSessions = {};\nvar xReadCache = {};\n`;
-}
-// Profile selectors are the visible controls observed in the live X workflow.
-// Missing/ambiguous counters remain unknown; rounded counts carry their precision.
-export function readProfile({ handle } = {}) {
-    if (!/^[A-Za-z0-9_]{1,15}$/.test(handle ?? ""))
-        throw new Error("需要已观察的X handle");
-    const visible = (el) => el.getClientRects().length > 0;
-    const main = document.querySelector("main");
-    if (!main)
-        return {
-            handle,
-            blue: null,
-            relationship: "unknown",
-            alerts: ["missing-main"],
-            observedAt: new Date().toISOString(),
-        };
-    const buttons = Array.from(main.querySelectorAll("button")).filter(visible);
-    const labels = buttons.map((b) => b.getAttribute("aria-label") || b.innerText);
-    const relationship = labels.includes(`正在关注 @${handle}`) ||
-        labels.includes(`取消关注 @${handle}`)
-        ? "following"
-        : labels.includes(`回关 @${handle}`)
-            ? "follows-you"
-            : labels.includes(`关注 @${handle}`)
-                ? "not-following"
-                : "unknown";
-    const badges = buttons
-        .filter((b) => b.getAttribute("aria-label") === "提供已验证账号的详细信息。")
-        .map((b) => b.querySelector("svg"))
-        .filter(Boolean);
-    const blue = badges.length === 1
-        ? [
-            getComputedStyle(badges[0]).color,
-            getComputedStyle(badges[0]).fill,
-        ].includes("rgb(29, 155, 240)")
-        : null;
-    const links = Array.from(main.querySelectorAll("a[href]")).filter(visible);
-    const counter = (suffixes) => {
-        const matched = links.filter((a) => suffixes.some((s) => a.getAttribute("href")?.toLowerCase() ===
-            `/${handle}/${s}`.toLowerCase()));
-        const texts = [...new Set(matched.map((a) => a.innerText.trim()))];
-        if (texts.length !== 1)
-            return { value: null, text: texts, precision: "unknown" };
-        const match = texts[0].match(/^([\d,.]+)\s*(万|亿|[KMB])?/i);
-        const factors = {
-            万: 1e4,
-            亿: 1e8,
-            K: 1e3,
-            M: 1e6,
-            B: 1e9,
-        };
-        const value = match
-            ? Number(match[1].replaceAll(",", "")) *
-                (factors[match[2]?.toUpperCase()] ?? 1)
-            : null;
-        const hrefs = [...new Set(matched.map((a) => a.getAttribute("href")))];
-        return {
-            value: Number.isFinite(value) ? value : null,
-            text: texts[0],
-            precision: match?.[2] ? "rounded" : "exact",
-            url: hrefs.length === 1 ? "https://x.com" + hrefs[0] : null,
-        };
-    };
-    return {
-        handle,
-        blue,
-        relationship,
-        relationshipControls: labels
-            .filter((label) => label.includes("@" + handle) || /取消关注|订阅/.test(label))
-            .slice(0, 5),
-        biography: main.querySelector('[data-testid="UserDescription"]')
-            ?.innerText ?? null,
-        following: counter(["following"]),
-        followers: counter(["followers", "verified_followers"]),
-        alerts: Array.from(document.querySelectorAll('[role="alert"]'))
-            .filter(visible)
-            .map((a) => a.innerText),
-        observedAt: new Date().toISOString(),
-    };
-}
-// Bounded visible person cells for a currently loaded follower/following list.
-export function readPeople({ offset = 0, limit = 5 } = {}) {
-    if (!Number.isInteger(offset) ||
-        offset < 0 ||
-        !Number.isInteger(limit) ||
-        limit < 1 ||
-        limit > 5)
-        throw new Error("人物窗口须为非负offset及1–5 limit");
-    const visible = (el) => el.getClientRects().length > 0;
-    const cells = Array.from(document.querySelectorAll('main [data-testid="UserCell"]')).filter(visible);
-    const people = cells.slice(offset, offset + limit).map((cell) => {
-        const links = Array.from(cell.querySelectorAll("a[href]"))
-            .filter(visible)
-            .map((a) => ({ text: a.innerText, href: a.getAttribute("href") }));
-        const buttons = Array.from(cell.querySelectorAll("button"))
-            .filter(visible)
-            .map((b) => ({
-            label: b.getAttribute("aria-label") || b.innerText,
-            disabled: b.disabled,
-        }));
-        return { text: cell.innerText, links, buttons };
-    });
-    return {
-        page: location.href,
-        people,
-        offset,
-        renderedPeople: cells.length,
-        moreInDOM: offset + limit < cells.length,
-        pageComplete: false,
-        needsStateCheck: !people.length,
-        missing: people.length ? [] : ["people-cells-not-found"],
-        alerts: Array.from(document.querySelectorAll('[role="alert"]'))
-            .filter(visible)
-            .map((a) => a.innerText),
-        observedAt: new Date().toISOString(),
-    };
-}
-export function readComposer() {
-    const visible = (el) => el.getClientRects().length > 0 && !el.closest('[aria-hidden="true"]');
-    const dialogs = Array.from(document.querySelectorAll('[role="dialog"]')).filter(visible);
-    const root = dialogs.length === 1
-        ? dialogs[0]
-        : dialogs.length === 0
-            ? document.querySelector("main")
-            : null;
-    if (location.pathname.startsWith("/compose/post/unsent/")) {
-        const text = root?.innerText ?? "";
-        return {
-            page: location.href,
-            unsent: true,
-            text: text.slice(0, 8000),
-            truncated: text.length > 8000,
-            controls: root
-                ? Array.from(root.querySelectorAll('button,a,[role="tab"]'))
-                    .filter(visible)
-                    .slice(0, 30)
-                    .map((el) => ({
-                    label: el.getAttribute("aria-label") || el.innerText,
-                    href: el.getAttribute("href"),
-                }))
-                : [],
-            needsStateCheck: !root || text.length > 8000,
-        };
-    }
-    const navigation = Array.from(document.querySelectorAll('a[href="/compose/post"],button[data-testid="SideNav_AccountSwitcher_Button"]'))
-        .filter(visible)
-        .map((el) => ({
-        role: el.tagName === "A" ? "link" : "button",
-        label: el.getAttribute("aria-label") || el.innerText,
-    }));
-    if (Array.from(document.querySelectorAll('[role="textbox"],textarea,[contenteditable="true"]')).filter(visible).length !== 1)
-        return {
-            page: location.href,
-            navigation,
-            dialog: root &&
-                (dialogs.length === 1 || location.pathname === "/compose/post/media")
-                ? {
-                    buttons: Array.from(root.querySelectorAll('button,[role="tab"]'))
-                        .filter(visible)
-                        .map((el) => ({
-                        role: el.getAttribute("role") || "button",
-                        label: el.getAttribute("aria-label") || el.innerText,
-                    })),
-                    fields: Array.from(root.querySelectorAll("textarea,input"))
-                        .filter(visible)
-                        .map((el) => ({
-                        label: el.getAttribute("aria-label"),
-                        placeholder: el.getAttribute("placeholder"),
-                        value: el.value,
-                    })),
-                }
-                : null,
-            needsStateCheck: true,
-            missing: ["composer-editor-not-found"],
-            editorCandidates: Array.from(document.querySelectorAll('[role="textbox"],textarea,[contenteditable="true"]'))
-                .filter(visible)
-                .map((el) => ({
-                label: el.getAttribute("aria-label"),
-                testId: el.getAttribute("data-testid"),
-                tag: el.tagName,
-            })),
-        };
-    const editors = Array.from(document.querySelectorAll('[role="textbox"],textarea,[contenteditable="true"]')).filter(visible);
-    let scope = editors[0];
-    while (scope.parentElement &&
-        !Array.from(scope.querySelectorAll("button")).some((el) => visible(el) &&
-            /^(发帖|回复|更新)$/.test(el.getAttribute("aria-label") || el.innerText)))
-        scope = scope.parentElement;
-    if (scope === document.body || scope === document.documentElement)
-        return {
-            page: location.href,
-            needsStateCheck: true,
-            missing: ["composer-submit-scope-not-found"],
-        };
-    return {
-        page: location.href,
-        navigation,
-        editors: editors.map((el) => ({
-            label: el.getAttribute("aria-label"),
-            testId: el.getAttribute("data-testid"),
-            text: el.innerText,
-        })),
-        buttons: Array.from(scope.querySelectorAll("button"))
-            .filter(visible)
-            .map((el) => ({
-            label: el.getAttribute("aria-label") || el.innerText,
-            disabled: el.disabled,
-            testId: el.getAttribute("data-testid"),
-            ariaDisabled: el.getAttribute("aria-disabled"),
-            ariaBusy: el.getAttribute("aria-busy"),
-        })),
-        images: Array.from(scope.querySelectorAll("img"))
-            .filter(visible)
-            .map((el) => ({ alt: el.alt })),
-        needsStateCheck: false,
-    };
-}
-export function readMenu() {
-    const visible = (el) => el.getClientRects().length > 0;
-    const roots = Array.from(document.querySelectorAll('[role="menu"],[role="dialog"],[data-testid="Dropdown"]')).filter(visible);
-    const items = [
-        ...new Set(roots.flatMap((root) => Array.from(root.querySelectorAll('a[href],button,[role="menuitem"]')))),
-    ].filter(visible);
-    return {
-        items: items.map((el) => ({
-            role: el.getAttribute("role") || (el.tagName === "A" ? "link" : "button"),
-            label: el.getAttribute("aria-label") || el.innerText,
-            href: el.getAttribute("href"),
-        })),
-        needsStateCheck: !items.length,
-        missing: items.length ? [] : ["menu-not-found"],
-    };
-}
-// Bounded visible navigation only. Never include article links as navigation controls.
-export function readNavigation({ targetLabel } = {}) {
-    const visible = (el) => el.getClientRects().length > 0 && !el.closest('[aria-hidden="true"]');
-    const primary = document.querySelector('[data-testid="primaryColumn"]') ??
-        document.querySelector("main");
-    const nodes = [
-        ...new Set([
-            ...Array.from(document.querySelectorAll("nav a[href],nav button")).filter((el) => !el.closest("main")),
-            ...Array.from(primary?.querySelectorAll('a[href],button,[role="button"],[role="tab"]') ?? []),
-            ...Array.from(document.querySelectorAll('[role="menu"] a[href], [role="menu"] button, [data-testid="Dropdown"] a[href], [data-testid="Dropdown"] button')),
-        ]),
-    ].filter((el) => visible(el) && !el.closest("article"));
-    const controls = nodes.map((el) => ({
-        role: el.getAttribute("role") || (el.tagName === "A" ? "link" : "button"),
-        label: el.getAttribute("aria-label") || el.innerText.trim(),
-        href: el.getAttribute("href"),
-        selected: el.getAttribute("aria-selected") === "true",
-        disabled: el.disabled === true,
-    }));
-    // Some folder cards are plain clickable text, with no ARIA role or href.
-    // Only the explicitly requested, visible exact label can be promoted to a semantic control.
-    if (targetLabel &&
-        !controls.some((c) => c.label.split("\n")[0] === targetLabel)) {
-        const labels = Array.from(document.querySelectorAll("span,div")).filter((el) => visible(el) &&
-            !el.closest("article") &&
-            el.innerText.trim() === targetLabel &&
-            !Array.from(el.children).some((child) => child.innerText?.trim() === targetLabel));
-        controls.push(...labels.map((el) => ({
-            role: "text",
-            label: el.innerText.trim(),
-            href: null,
-            disabled: false,
-            source: "exact-visible-folder-label",
-        })));
-    }
-    return {
-        page: location.href,
-        controls: controls.slice(0, 40),
-        headings: Array.from(primary?.querySelectorAll('h1,h2,[role="heading"]') ?? [])
-            .filter(visible)
-            .map((el) => el.innerText.trim())
-            .slice(0, 10),
-        needsStateCheck: !controls.length || controls.length > 40,
-        missing: controls.length > 40
-            ? ["navigation-window-overflow"]
-            : controls.length
-                ? []
-                : ["navigation-not-found"],
-    };
-}
-export function readMediaEditor() {
-    if (location.pathname !== "/compose/post/media")
-        return { needsStateCheck: true, missing: ["media-route-not-found"] };
-    const visible = (el) => el.getClientRects().length > 0 && !el.closest('[aria-hidden="true"]');
-    const controls = Array.from(document.querySelectorAll('button,[role="tab"]'))
-        .filter(visible)
-        .map((el) => ({
-        role: el.getAttribute("role") || "button",
-        label: el.getAttribute("aria-label") || el.innerText,
-        disabled: el.disabled === true,
-    }));
-    const fields = Array.from(document.querySelectorAll('textarea,input,[role="textbox"]'))
-        .filter(visible)
-        .map((el) => ({
-        label: el.getAttribute("aria-label"),
-        placeholder: el.getAttribute("placeholder"),
-        value: el.value ?? el.innerText,
-    }));
-    const ready = controls.some((c) => c.role === "button" && c.label === "保存") &&
-        controls.some((c) => c.role === "tab" && c.label === "编辑图片描述");
-    return {
-        page: location.href,
-        controls: controls.slice(0, 20),
-        fields: fields.slice(0, 5),
-        needsStateCheck: !ready || controls.length > 20 || fields.length > 5,
-        missing: ready ? [] : ["media-editor-controls-not-ready"],
-        alerts: Array.from(document.querySelectorAll('[role="alert"]'))
-            .filter(visible)
-            .map((el) => el.innerText),
-    };
-}
-// Upload only through the observed image button and browser file chooser.
-export async function attachImage(tab, { path } = {}) {
-    if (!/^\/.*\.(?:png|jpe?g|webp)$/i.test(path ?? ""))
-        throw new Error("需要绝对图片路径");
-    if (typeof tab?.playwright?.evaluate !== "function" ||
-        typeof tab?.playwright?.getByRole !== "function" ||
-        typeof tab?.playwright?.waitForEvent !== "function")
-        throw new Error("harness能力不足：DOM图片选择器");
-    const before = await tab.playwright.evaluate(readComposer);
-    if (before.needsStateCheck || before.alerts?.length)
-        throw new Error("图片上传前编辑器未确认");
-    const buttons = before.buttons.filter((b) => /^(添加照片或视频|Add photos or video)$/i.test(b.label) && !b.disabled);
-    if (buttons.length !== 1)
-        throw new Error("图片按钮未唯一观察");
-    const button = tab.playwright.getByRole("button", {
-        name: buttons[0].label,
-        exact: true,
-    });
-    if ((await button.count()) !== 1 || typeof button.click !== "function")
-        throw new Error("图片按钮未唯一定位");
-    const chooserPromise = tab.playwright.waitForEvent("filechooser", {
-        timeoutMs: 10000,
-    });
-    await button.click();
-    const chooser = await chooserPromise;
-    if (typeof chooser?.setFiles !== "function")
-        throw new Error("harness能力不足：setFiles");
-    await chooser.setFiles([path]);
-    return tab.playwright.evaluate(readComposer);
-}
-export async function openReply(tab, { postId } = {}) {
-    if (!/^\d+$/.test(postId ?? ""))
-        throw new Error("需要已观察公开ID");
-    if (typeof tab?.playwright?.evaluate !== "function" ||
-        typeof tab?.playwright?.locator !== "function")
-        throw new Error("harness能力不足：精准回复范围");
-    const state = await tab.playwright.evaluate(readPosts, {
-        targetId: postId,
-        limit: 1,
-    });
-    const post = state.posts[0];
-    if (state.needsStateCheck ||
-        state.alerts.length ||
-        state.posts.length !== 1 ||
-        post.missing.length ||
-        post.needsExpansion)
-        throw new Error("回复根帖证据未完整");
-    const buttons = post.buttons.filter((b) => /回复|Reply/i.test(b.label) && !b.disabled);
-    if (buttons.length !== 1)
-        throw new Error("回复按钮未唯一观察");
-    const article = tab.playwright
-        .locator("article")
-        .filter({ has: tab.playwright.locator(`a[href="${post.primary}"]`) });
-    if ((await article.count()) !== 1)
-        throw new Error("回复文章范围不唯一");
-    const button = article.getByRole("button", {
-        name: buttons[0].label,
-        exact: true,
-    });
-    if ((await button.count()) !== 1)
-        throw new Error("回复控件不唯一");
-    await button.click();
-    return tab.playwright.evaluate(readComposer);
-}
-// This ranks observed clues, never a predicted follow-back probability.
-export function screenCandidates(profiles, { minRatio = 0.8 } = {}) {
-    if (!Array.isArray(profiles) || !Number.isFinite(minRatio) || minRatio <= 0)
-        throw new Error("profiles数组和正minRatio必填");
-    const seen = new Set();
-    return profiles
-        .map((p) => {
-        const key = String(p.handle ?? "").toLowerCase();
-        const duplicate = seen.has(key);
-        seen.add(key);
-        const following = p.following?.value, followers = p.followers?.value;
-        const ratio = Number.isFinite(following) &&
-            Number.isFinite(followers) &&
-            followers > 0
-            ? following / followers
-            : null;
-        const clues = [];
-        if (typeof p.mutualEvidence === "string" && p.mutualEvidence.trim())
-            clues.push({ kind: "explicit-mutual", evidence: p.mutualEvidence });
-        if (ratio !== null && ratio >= minRatio)
-            clues.push({
-                kind: "following-ratio",
-                ratio,
-                following: p.following,
-                followers: p.followers,
-                evidence: "关注/粉丝比例线索，非回关概率",
-            });
-        const rejected = [
-            duplicate && "duplicate",
-            p.blue !== true && "blue-unconfirmed",
-            p.relationship !== "not-following" && "relationship-ineligible",
-            p.alerts?.length && "page-alert",
-            !clues.length && "no-followback-clue",
-            !/^[A-Za-z0-9_]{1,15}$/.test(p.handle ?? "") && "invalid-handle",
-        ].filter(Boolean);
-        return { ...p, ratio, clues, eligible: rejected.length === 0, rejected };
-    })
-        .sort((a, b) => Number(b.eligible) - Number(a.eligible) ||
-        Number(b.clues.some((c) => c.kind === "explicit-mutual")) -
-            Number(a.clues.some((c) => c.kind === "explicit-mutual")));
-}
-export function profileCode({ tab = "xtab", handle } = {}) {
-    return profilesCode([{ tab, handle }]);
-}
-export function profilesCode(entries) {
-    if (!Array.isArray(entries) || !entries.length || entries.length > 5)
-        throw new Error("一次读取1～5位");
-    for (const { tab, handle } of entries) {
-        if (!/^[A-Za-z_$][\w$]*$/.test(tab ?? ""))
-            throw new Error("tab必须是已有Tab变量名");
-        if (!/^[A-Za-z0-9_]{1,15}$/.test(handle ?? ""))
-            throw new Error("需要已观察的X handle");
-    }
-    const inputs = entries
-        .map(({ tab, handle }) => `{tab:${tab},handle:${JSON.stringify(handle)}}`)
-        .join(",");
-    return `var xProfiles = [];\nfor (var entry of [${inputs}]) {\n  var page = new URL(await entry.tab.url());\n  if (page.origin !== 'https://x.com' || page.pathname.toLowerCase() !== '/' + entry.handle.toLowerCase()) { xProfiles.push({handle:entry.handle,blue:null,relationship:'unknown',alerts:['profile-url-mismatch']}); continue; }\n  xProfiles.push(await entry.tab.playwright.evaluate(xReadProfile, {handle:entry.handle}));\n}\nnodeRepl.write(xScreenCandidates(xProfiles));\n`;
-}
-export function browserCode({ handle = "xtab", offset = 0, limit = 5, targetId = "", fresh = false, } = {}) {
-    if (!/^[A-Za-z_$][\w$]*$/.test(handle))
-        throw new Error("handle必须是当前REPL已有Tab变量名");
-    if (targetId && !/^\d+$/.test(targetId))
-        throw new Error("targetId必须是已观察的数字公开ID");
-    if (!Number.isInteger(offset) ||
-        offset < 0 ||
-        !Number.isInteger(limit) ||
-        limit < 1 ||
-        limit > 5)
-        throw new Error("无效读取窗口");
-    return `var xReadResult = await ${handle}.playwright.evaluate(xReadPosts, ${JSON.stringify({ offset, limit, targetId })});\nnodeRepl.write(xReadChanges(xReadResult, xReadCache, await ${handle}.url(), ${fresh}));\n`;
-}
-export function axCode({ handle = "chrome", mode = "posts", offset = 0, limit = 1, targetId = "", targetHandle = "", fresh = false, } = {}) {
-    if (!/^[A-Za-z_$][\w$]*$/.test(handle))
-        throw new Error("handle必须是已有原生App/Tab变量名");
-    // Share validation with the pure parser, without requiring a browser.
-    readAX("", { mode, offset, limit, targetId, targetHandle });
-    return `if (xAXSessions.${handle}?.app !== ${handle}) xAXSessions.${handle} = {app:${handle}, harness:xCreateAXHarness(${handle})};\nvar xAXResult = await xAXSessions.${handle}.harness.observe(${JSON.stringify({ mode, offset, limit, targetId, targetHandle })});\nnodeRepl.write(xReadChanges(xAXResult, xReadCache, xAXResult.page ?? 'unknown', ${fresh}));\n`;
-}
-export function runReaderCLI() {
-    try {
-        const args = process.argv.slice(2);
-        const value = (flag, fallback) => args.includes(flag) ? args[args.indexOf(flag) + 1] : fallback;
-        process.stdout.write(args.includes("--setup")
-            ? setupCode()
-            : args.includes("--ax")
-                ? axCode({
-                    handle: value("--handle", "chrome"),
-                    mode: value("--mode", "posts"),
-                    offset: Number(value("--offset", 0)),
-                    limit: Number(value("--limit", 1)),
-                    targetId: value("--id", ""),
-                    targetHandle: value("--person", ""),
-                    fresh: args.includes("--fresh"),
-                })
-                : args.includes("--profile")
-                    ? profileCode({
-                        tab: value("--handle", "xtab"),
-                        handle: value("--profile", ""),
-                    })
-                    : browserCode({
-                        handle: value("--handle", "xtab"),
-                        offset: Number(value("--offset", 0)),
-                        limit: Number(value("--limit", 5)),
-                        targetId: value("--id", ""),
-                        fresh: args.includes("--fresh"),
-                    }));
-    }
-    catch (error) {
-        console.error(error.message);
-        process.exitCode = 1;
-    }
-}
+/** Compatibility exports only. Implementation owners are task-specific modules. */
+export { readPosts, changes } from "./readers-posts.js";
+export { readAX } from "./readers-ax-parser.js";
+export { createAXTabHarness, createAXHarness } from "./readers-ax-host.js";
+export { readProfile, readPeople, screenCandidates, } from "./readers-profile.js";
+export { readComposer, readMediaEditor } from "./readers-composer.js";
+export { readMenu, readNavigation } from "./readers-navigation.js";
+export { attachImage, openReply } from "./readers-actions.js";
+export { setupCode, profileCode, profilesCode, browserCode, axCode, runReaderCLI, } from "./readers-cli.js";