codex-chatgpt-control 0.1.0-alpha.1 → 0.2.0-alpha.1

package/dist/src/commands/messages.js

@@ -1,7 +1,8 @@
 import { readPageState } from "../browser/page-state.js";
 import { resultError, resultOk } from "../errors.js";
+import { latestAssistantTurnHasResponseActions, readAssistantGenerationState } from "../dom/generation-state.js";
 import { countPageMessages, isTransientAssistantText, readLatestMessage, readLatestMessageText, readLatestMessageTextSnapshot, readMessages } from "../dom/messages.js";
-import { composerTextbox, copyResponseButtons, sendButton } from "../dom/selectors.js";
+import { composerTextbox, sendButton } from "../dom/selectors.js";
 import { normalizeLineBreaks, normalizeWhitespace } from "../dom/visible-text.js";
 import { contextFromPage } from "./context.js";
 import { withCommandOutputText } from "./output.js";
@@ -10,7 +11,8 @@ export function isResponseComplete(snapshot) {
     return snapshot.latestText.trim().length > 0
         && !isTransientAssistantText(snapshot.latestText)
         && snapshot.textStableForMs >= snapshot.stableMs
-        && !snapshot.hasStopButton
+        && !snapshot.generation.active
+        && !snapshot.generation.stopped
         && snapshot.hasResponseActions;
 }
 export async function composeMessage(env, args) {
@@ -55,13 +57,41 @@ export async function submitMessage(env, args = {}) {
     const page = env.page;
     const previousTurnCount = args.previousTurnCount ?? await countPageMessages(page).catch(() => undefined);
     try {
-        try {
-            await sendButton(page).click?.();
+        const ready = await waitForSendButtonReady(page, args.timeoutMs ?? 30000);
+        if (!ready.ready) {
+            const blocker = {
+                kind: ready.code === "attachment_processing" ? "upload_failed" : "selector_drift",
+                code: ready.code,
+                message: ready.message,
+                remediation: [
+                    {
+                        label: "Wait for composer",
+                        instruction: "Wait for ChatGPT's composer and attachments to become ready, then retry without manually changing the page.",
+                        userActionRequired: false
+                    }
+                ],
+                resumable: true
+            };
+            if (ready.visibleText !== undefined) {
+                blocker.visibleText = ready.visibleText;
+            }
+            return {
+                ok: false,
+                status: "blocked",
+                warnings: [],
+                blocker,
+                context: await contextFromPage(page)
+            };
         }
-        catch {
-            await page.keyboard?.press?.("Enter");
+        const timeoutMs = args.timeoutMs ?? 30000;
+        const startedAt = Date.now();
+        await clickSendControl(page);
+        let userTurn = await waitForSubmittedUserTurn(page, args.text, previousTurnCount, initialSubmitWaitMs(timeoutMs));
+        if (userTurn === undefined && Date.now() - startedAt < timeoutMs && await shouldRetryNoopSubmit(page, args.text)) {
+            await sleep(page, 250);
+            await clickSendControl(page);
+            userTurn = await waitForSubmittedUserTurn(page, args.text, previousTurnCount, Math.max(0, timeoutMs - (Date.now() - startedAt)));
         }
-        const userTurn = await waitForSubmittedUserTurn(page, args.text, previousTurnCount, args.timeoutMs ?? 30000);
         if (userTurn === undefined) {
             const latestUser = await readLatestMessage(page, "user", "normalized_text");
             if (submittedUserTurnMatches(latestUser?.text, args.text)) {
@@ -70,7 +100,7 @@ export async function submitMessage(env, args = {}) {
             return {
                 ok: false,
                 status: "timeout",
-                warnings: [],
+                warnings: await sendTimeoutWarnings(page),
                 error: {
                     name: "SubmitTimeout",
                     message: "No matching submitted user turn appeared before the timeout.",
@@ -85,6 +115,140 @@ export async function submitMessage(env, args = {}) {
         return resultError(error instanceof Error ? error : new Error(String(error)), await contextFromPage(page));
     }
 }
+async function clickSendControl(page) {
+    try {
+        await sendButton(page).click?.();
+    }
+    catch {
+        await page.keyboard?.press?.("Enter");
+    }
+}
+function initialSubmitWaitMs(timeoutMs) {
+    return Math.min(3000, Math.max(500, Math.floor(timeoutMs / 3)));
+}
+async function shouldRetryNoopSubmit(page, text) {
+    const state = await readSendButtonState(page).catch(() => ({ available: false }));
+    if (!isSendButtonReady(state)) {
+        return false;
+    }
+    if (text === undefined) {
+        return true;
+    }
+    const composerText = await readLocatorText(composerTextbox(page)).catch(() => "");
+    return submittedUserTurnMatches(composerText, text);
+}
+async function waitForSendButtonReady(page, timeoutMs) {
+    const started = Date.now();
+    let lastState;
+    let lastVisibleText;
+    while (Date.now() - started < timeoutMs) {
+        const state = await readSendButtonState(page).catch(() => ({ available: true }));
+        lastState = state;
+        if (isSendButtonReady(state)) {
+            return { ready: true };
+        }
+        const visibleText = await readVisibleTextForSubmit(page).catch(() => undefined);
+        if (visibleText !== undefined && /uploading|processing|attaching|preparing|reading|scanning/i.test(visibleText)) {
+            lastVisibleText = visibleText.slice(0, 500);
+        }
+        await sleep(page, 250);
+    }
+    if (lastVisibleText !== undefined) {
+        return {
+            ready: false,
+            code: "attachment_processing",
+            message: "ChatGPT still appears to be processing an attachment, so the send button did not become ready.",
+            visibleText: lastVisibleText
+        };
+    }
+    return {
+        ready: false,
+        code: "send_button_not_ready",
+        message: `ChatGPT's send button did not become ready before timeout.${describeSendState(lastState)}`
+    };
+}
+function isSendButtonReady(state) {
+    if (!state.available)
+        return false;
+    if (state.visible === false)
+        return false;
+    if (state.disabled === true)
+        return false;
+    if (state.busy === true)
+        return false;
+    return true;
+}
+async function readSendButtonState(page) {
+    const locator = sendButton(page);
+    if (typeof locator.count === "function" && await locator.count().catch(() => 1) === 0) {
+        return { available: false, reason: "not_found" };
+    }
+    const visible = typeof locator.isVisible === "function" ? await locator.isVisible({ timeoutMs: 500 }).catch(() => undefined) : undefined;
+    if (typeof locator.evaluate !== "function") {
+        const state = { available: true };
+        if (visible !== undefined)
+            state.visible = visible;
+        return state;
+    }
+    const evaluated = await locator.evaluate(element => {
+        const htmlElement = element;
+        const button = element;
+        return {
+            disabled: button.disabled === true
+                || element.getAttribute("disabled") !== null
+                || element.getAttribute("aria-disabled") === "true"
+                || element.getAttribute("data-disabled") === "true",
+            busy: element.getAttribute("aria-busy") === "true"
+                || htmlElement.className.toString().toLocaleLowerCase().includes("loading"),
+            label: element.getAttribute("aria-label")
+                ?? element.getAttribute("title")
+                ?? htmlElement.innerText
+                ?? element.textContent
+                ?? undefined
+        };
+    });
+    const state = {
+        available: true,
+        disabled: evaluated.disabled,
+        busy: evaluated.busy
+    };
+    if (visible !== undefined)
+        state.visible = visible;
+    if (evaluated.label !== undefined)
+        state.label = evaluated.label;
+    return state;
+}
+async function readVisibleTextForSubmit(page) {
+    if (typeof page.evaluate !== "function") {
+        return undefined;
+    }
+    return page.evaluate(() => document.body?.innerText ?? "");
+}
+async function sendTimeoutWarnings(page) {
+    const state = await readSendButtonState(page).catch(() => undefined);
+    if (state === undefined || isSendButtonReady(state)) {
+        return [];
+    }
+    return [`Send button state after submit timeout:${describeSendState(state)}`];
+}
+function describeSendState(state) {
+    if (state === undefined)
+        return "";
+    const parts = [];
+    if (!state.available)
+        parts.push("available=false");
+    if (state.visible !== undefined)
+        parts.push(`visible=${state.visible}`);
+    if (state.disabled !== undefined)
+        parts.push(`disabled=${state.disabled}`);
+    if (state.busy !== undefined)
+        parts.push(`busy=${state.busy}`);
+    if (state.label !== undefined && state.label.trim().length > 0)
+        parts.push(`label=${JSON.stringify(state.label.trim().slice(0, 80))}`);
+    if (state.reason !== undefined)
+        parts.push(`reason=${state.reason}`);
+    return parts.length > 0 ? ` ${parts.join(" ")}` : "";
+}
 export async function waitForMessage(env, args = {}) {
     const boot = await ensurePage(env);
     if (!boot.ok) {
@@ -122,9 +286,26 @@ export async function waitForMessage(env, args = {}) {
             latestText,
             stableMs,
             textStableForMs: Date.now() - lastChangedAt,
-            hasStopButton: await hasStopControl(page),
-            hasResponseActions: await hasResponseActions(page)
+            generation: await readAssistantGenerationState(page),
+            hasResponseActions: await latestAssistantTurnHasResponseActions(page)
         };
+        if (targetReached && snapshot.generation.stopped && latestText.length > 0) {
+            return withCommandOutputText({
+                ok: false,
+                status: "partial",
+                data: {
+                    complete: false,
+                    responseText: latestText,
+                    assistantTurnCount: latestAssistantCount,
+                    elapsedMs: Date.now() - started
+                },
+                warnings: [
+                    "ChatGPT generation appears to have been stopped or interrupted before completion.",
+                    ...snapshot.generation.signals.map(signal => `Generation state signal: ${signal}`)
+                ],
+                context: await contextFromPage(page)
+            });
+        }
         if (targetReached && isResponseComplete(snapshot)) {
             return withCommandOutputText(resultOk({ complete: true, responseText: latestText, assistantTurnCount: latestAssistantCount, elapsedMs: Date.now() - started }, await contextFromPage(page)));
         }
@@ -182,6 +363,8 @@ export async function readLatest(env, args = {}) {
         data.source = latest.source;
     if (latest.fidelity !== undefined)
         data.fidelity = latest.fidelity;
+    if (latest.captureLimit !== undefined)
+        data.captureLimit = latest.captureLimit;
     if (latest.warnings !== undefined)
         data.warnings = latest.warnings;
     if (latest.markdown !== undefined)
@@ -249,11 +432,16 @@ export async function askMessage(env, args) {
             waitArgs.afterAssistantTurnCount = beforeAssistantTurnCount;
         }
         waitResult = await waitForMessage(env, waitArgs);
-        if (!waitResult.ok && waitResult.status !== "partial") {
-            if (!readRequested || readRole(args.read) === "user") {
-                return forwardFailure(waitResult);
+        if (!waitResult.ok) {
+            if (waitResult.status === "partial") {
+                waitFailure = waitResult;
+            }
+            else {
+                if (!readRequested || readRole(args.read) === "user") {
+                    return forwardFailure(waitResult);
+                }
+                waitFailure = waitResult;
             }
-            waitFailure = waitResult;
         }
     }
     let responseText = waitResult?.data?.responseText;
@@ -265,6 +453,7 @@ export async function askMessage(env, args) {
                 return forwardFailure(waitFailure);
             }
             responseText = read.data?.text;
+            warnings.push(...read.warnings);
             if (waitFailure !== undefined) {
                 warnings.push(...waitFailure.warnings, `Assistant response was read after ${waitFailure.status}, but completion was not confirmed by the wait step.`);
             }
@@ -291,6 +480,19 @@ export async function askMessage(env, args) {
     if (state?.title !== undefined) {
         data.title = state.title;
     }
+    if (waitFailure !== undefined) {
+        data.complete = false;
+        return withCommandOutputText({
+            ok: false,
+            status: "partial",
+            data,
+            warnings: [
+                ...warnings,
+                `Assistant response was read after ${waitFailure.status}, but completion was not confirmed.`
+            ],
+            context: await contextFromPage(page)
+        });
+    }
     return withCommandOutputText(resultOk(data, await contextFromPage(page), warnings));
 }
 export async function waitAndRead(env, args = {}) {
@@ -315,7 +517,22 @@ export async function waitAndRead(env, args = {}) {
         }
         return forwardFailure(read);
     }
-    return withCommandOutputText(resultOk(askReadData("", read.data?.text, wait.data?.complete), read.context, wait.warnings));
+    const data = askReadData("", read.data?.text, wait.data?.complete);
+    const warnings = [...read.warnings, ...wait.warnings];
+    if (!wait.ok && wait.status === "partial") {
+        data.complete = false;
+        return withCommandOutputText({
+            ok: false,
+            status: "partial",
+            data,
+            warnings: [
+                ...warnings,
+                "Assistant response was read after partial wait, but completion was not confirmed."
+            ],
+            context: read.context
+        });
+    }
+    return withCommandOutputText(resultOk(data, read.context, warnings));
 }
 async function ensurePage(env) {
     if (env.page !== undefined) {
@@ -384,31 +601,6 @@ function renderSubmittedTurnMarkdownSyntax(text, preserveFenceLanguage = true) {
         .replace(/\*([^*]+)\*/g, "$1")
         .replace(/_([^_]+)_/g, "$1");
 }
-async function hasStopControl(page) {
-    if (typeof page.evaluate === "function") {
-        return page.evaluate(() => {
-            const text = document.body?.innerText ?? "";
-            return /\b(stop generating|stop streaming|cancel)\b/i.test(text);
-        }).catch(() => false);
-    }
-    return false;
-}
-async function hasResponseActions(page) {
-    try {
-        const copyButtons = copyResponseButtons(page);
-        const count = await copyButtons.count?.();
-        if (count !== undefined) {
-            return count > 0;
-        }
-        return await copyButtons.isVisible?.() === true;
-    }
-    catch {
-        if (typeof page.evaluate === "function") {
-            return page.evaluate(() => /\b(Copy response|More actions)\b/i.test(document.body?.innerText ?? "")).catch(() => false);
-        }
-        return true;
-    }
-}
 async function readAssistantProgressSnapshot(page) {
     if (typeof page.evaluate === "function") {
         return page.evaluate(() => {

package/dist/src/commands/modes.js

@@ -1,11 +1,21 @@
 import { resultError, resultOk } from "../errors.js";
 import { enumerateVisibleMenuItems, findUniqueMenuItem } from "../dom/menus.js";
+import { localeLabels } from "../dom/locale-labels.js";
 import { normalizeLabel, normalizeWhitespace } from "../dom/visible-text.js";
 import { contextFromPage } from "./context.js";
 import { bootstrap } from "./session.js";
 const DEFAULT_MODE_EFFORT = "Thinking";
-const CURRENT_MODE_LABELS = ["Latest", "Instant", "Thinking", "Extended", "Pro"];
-const MODE_OPENER_LABELS = [...CURRENT_MODE_LABELS.filter(label => label !== "Pro"), "Configure"];
+const CURRENT_MODE_LABELS = [...localeLabels.modeLabels];
+const MODE_OPENER_LABELS = [...CURRENT_MODE_LABELS.filter(label => label !== "Pro"), ...localeLabels.modeOpenerExtra];
+const MODEL_VERSION_FAMILY_PATTERN = /^gpt[\s-]/i;
+const MODEL_VERSION_LABEL_PATTERN = /^(?:o\d+|\d+(?:\.\d+)?)$/i;
+const CANONICAL_INTELLIGENCE_ORDER = new Map([
+    ["instant", 0],
+    ["medium", 1],
+    ["high", 2],
+    ["extra high", 3],
+    ["pro", 4],
+]);
 export async function setMode(env, args) {
     const boot = await ensurePage(env);
     if (!boot.ok) {
@@ -14,8 +24,10 @@ export async function setMode(env, args) {
     const page = env.page;
     try {
         const requested = requestedModeLabels(args);
-        const opened = await waitForModeMenu(page, requested, args.timeoutMs ?? 30000);
-        if (opened.alreadySelected.length === requested.length) {
+        const requestedVersion = requestedModelVersion(args);
+        const requestedForOpening = requestedVersion === undefined ? requested : [...requested, requestedVersion];
+        const opened = await waitForModeMenu(page, requestedForOpening, args.timeoutMs ?? 30000);
+        if (requestedVersion === undefined && opened.alreadySelected.length === requested.length) {
             return resultOk({ selected: opened.alreadySelected, candidates: opened.modeButtons }, await contextFromPage(page));
         }
         if (!opened.opened) {
@@ -25,7 +37,7 @@ export async function setMode(env, args) {
         const candidates = await enumerateVisibleMenuItems(page);
         const selected = [];
         for (const item of requested) {
-            const match = findUniqueMenuItem(candidates, item);
+            const match = findModeMenuItem(candidates, item);
             if (match === undefined) {
                 const candidateLabels = candidates.map(candidate => candidate.label);
                 return {
@@ -41,7 +53,22 @@ export async function setMode(env, args) {
             }
             selected.push(match.label);
         }
-        return resultOk({ selected, candidates: candidates.map(candidate => candidate.label) }, await contextFromPage(page));
+        let candidateLabels = candidates.map(candidate => candidate.label);
+        if (requestedVersion !== undefined) {
+            const versionResult = await selectModelVersion(page, requestedVersion, candidates, args.timeoutMs ?? 30000);
+            candidateLabels = dedupeLabels([...candidateLabels, ...versionResult.candidates]);
+            if (!versionResult.selected) {
+                return {
+                    ok: false,
+                    status: "unsupported",
+                    warnings: [],
+                    blocker: selectorDriftBlocker(`Model version "${requestedVersion}" was not found or was ambiguous.`, candidateLabels),
+                    context: await contextFromPage(page)
+                };
+            }
+            selected.push(versionResult.selected);
+        }
+        return resultOk({ selected, candidates: candidateLabels }, await contextFromPage(page));
     }
     catch (error) {
         return resultError(error instanceof Error ? error : new Error(String(error)), await contextFromPage(page));
@@ -77,14 +104,23 @@ export async function selectTool(env, args) {
     }
     const page = env.page;
     try {
-        const opened = await clickFirstUniqueButton(page, ["Add files and more", "Add files", "Add photos"]);
+        const opened = await clickFirstUniqueButton(page, [...localeLabels.addFilesOpenerCandidates]);
         if (!opened) {
             return selectorDrift(page, "No unique ChatGPT tool menu opener was found.");
         }
         await page.waitForTimeout?.(250);
         const candidates = await enumerateVisibleMenuItems(page);
-        const wanted = toolLabel(args.tool);
-        const match = findUniqueMenuItem(candidates, wanted);
+        const wantedCandidates = toolLabels(args.tool);
+        let match;
+        let wanted = wantedCandidates[0] ?? args.tool;
+        for (const candidate of wantedCandidates) {
+            const found = findUniqueMenuItem(candidates, candidate);
+            if (found !== undefined) {
+                match = found;
+                wanted = candidate;
+                break;
+            }
+        }
         if (match === undefined) {
             const candidateLabels = candidates.map(candidate => candidate.label);
             return {
@@ -139,6 +175,9 @@ async function clickMenuItem(page, label) {
     if (await clickModelSwitcherMenuItem(page, label)) {
         return true;
     }
+    if (await clickMenuItemByPointer(page, label)) {
+        return true;
+    }
     if (await clickMenuItemByDom(page, label)) {
         return true;
     }
@@ -149,6 +188,22 @@ async function clickMenuItem(page, label) {
     const textLocator = page.getByText?.(label, { exact: true });
     return clickIfUnique(textLocator);
 }
+async function clickMenuItemByPointer(page, label) {
+    const point = await menuItemCenter(page, { label });
+    if (point === undefined) {
+        return false;
+    }
+    const pageWithPointer = page;
+    if (pageWithPointer.mouse?.click !== undefined) {
+        await pageWithPointer.mouse.click(point.x, point.y);
+        return true;
+    }
+    if (pageWithPointer.cua?.click !== undefined) {
+        await pageWithPointer.cua.click({ x: point.x, y: point.y });
+        return true;
+    }
+    return false;
+}
 async function clickModelSwitcherMenuItem(page, label) {
     if (typeof page.evaluate !== "function" || typeof page.locator !== "function") {
         return false;
@@ -203,22 +258,36 @@ async function clickIfUnique(locator) {
     await locator.click();
     return true;
 }
-function toolLabel(tool) {
-    switch (tool) {
-        case "web_search":
-            return "Web search";
-        case "deep_research":
-            return "Deep research";
-        case "create_image":
-            return "Create image";
-        default:
-            return tool;
+function toolLabels(tool) {
+    const known = localeLabels.tools[tool];
+    return known !== undefined ? [...known] : [tool];
+}
+function findModeMenuItem(candidates, wanted) {
+    const exact = findUniqueMenuItem(candidates, wanted);
+    if (exact !== undefined) {
+        return exact;
+    }
+    const wantedIndex = CANONICAL_INTELLIGENCE_ORDER.get(normalizeLabel(wanted));
+    if (wantedIndex === undefined) {
+        return undefined;
     }
+    const intelligenceItems = candidates.filter(candidate => candidate.role === "menuitemradio"
+        && !MODEL_VERSION_LABEL_PATTERN.test(candidate.label)
+        && !MODEL_VERSION_FAMILY_PATTERN.test(candidate.label));
+    return intelligenceItems.length >= CANONICAL_INTELLIGENCE_ORDER.size
+        ? intelligenceItems[wantedIndex]
+        : undefined;
 }
 function requestedModeLabels(args) {
-    const requested = [args.model, args.effort].filter((value) => value !== undefined);
+    const requested = [args.model, args.intelligence, args.effort].filter((value) => value !== undefined);
+    if (requestedModelVersion(args) !== undefined && requested.length === 0) {
+        return [];
+    }
     return requested.length > 0 ? requested : [DEFAULT_MODE_EFFORT];
 }
+function requestedModelVersion(args) {
+    return args.modelVersion ?? args.version;
+}
 function findUniqueVisibleLabel(labels, wanted) {
     const normalized = normalizeLabel(wanted);
     const exact = labels.filter(label => normalizeLabel(label) === normalized);
@@ -245,6 +314,119 @@ function findAlreadySelectedModes(visibleButtons, requested) {
         .map(label => findUniqueVisibleLabel(visibleButtons, label))
         .filter((label) => label !== undefined);
 }
+async function selectModelVersion(page, requestedVersion, currentCandidates, timeoutMs) {
+    let candidates = await enumerateVisibleMenuItems(page);
+    if (!looksLikeModeMenu(candidates.map(candidate => candidate.label))) {
+        const opened = await waitForModeMenu(page, [requestedVersion], timeoutMs);
+        if (opened.opened) {
+            await page.waitForTimeout?.(250);
+            candidates = await enumerateVisibleMenuItems(page);
+        }
+    }
+    let exact = findExactMenuItem(candidates, requestedVersion);
+    if (exact !== undefined) {
+        return await clickMenuItem(page, exact.label)
+            ? { selected: exact.label, candidates: candidates.map(candidate => candidate.label) }
+            : { candidates: candidates.map(candidate => candidate.label) };
+    }
+    const opened = await openModelVersionSubmenu(page, currentCandidates);
+    candidates = await enumerateVisibleMenuItems(page);
+    exact = findExactMenuItem(candidates, requestedVersion);
+    if (!opened || exact === undefined) {
+        return { candidates: candidates.map(candidate => candidate.label) };
+    }
+    return await clickMenuItem(page, exact.label)
+        ? { selected: exact.label, candidates: candidates.map(candidate => candidate.label) }
+        : { candidates: candidates.map(candidate => candidate.label) };
+}
+async function openModelVersionSubmenu(page, candidates) {
+    const submenuOpeners = candidates.filter(item => item.hasPopup === true || MODEL_VERSION_FAMILY_PATTERN.test(item.label));
+    if (submenuOpeners.length === 0) {
+        return false;
+    }
+    for (const candidate of submenuOpeners) {
+        if (await openSubmenuByPointer(page, candidate)) {
+            await page.waitForTimeout?.(250);
+            if (await modelVersionMenuItemsAreVisible(page)) {
+                return true;
+            }
+        }
+        if (await clickMenuItem(page, candidate.label)) {
+            await page.waitForTimeout?.(250);
+            if (await modelVersionMenuItemsAreVisible(page)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+async function openSubmenuByPointer(page, item) {
+    const point = await menuItemCenter(page, item);
+    if (point === undefined) {
+        return false;
+    }
+    const pageWithMouse = page;
+    if (pageWithMouse.mouse?.move !== undefined) {
+        await pageWithMouse.mouse.move(point.x, point.y);
+        return true;
+    }
+    if (pageWithMouse.cua?.move !== undefined) {
+        await pageWithMouse.cua.move({ x: point.x, y: point.y });
+        return true;
+    }
+    return false;
+}
+async function menuItemCenter(page, item, roles = ["menuitem", "menuitemradio", "option"]) {
+    if (typeof page.evaluate !== "function") {
+        return undefined;
+    }
+    const target = { label: item.label, roles };
+    if (item.testId !== undefined) {
+        target.testId = item.testId;
+    }
+    return page.evaluate((target) => {
+        const normalize = (value) => value.replace(/\s+/g, " ").trim().toLowerCase();
+        const normalizedLabel = normalize(target.label);
+        const roleSelector = target.roles.map(role => `[role='${role}']`).join(",");
+        const matches = Array.from(document.querySelectorAll(roleSelector))
+            .filter(node => {
+            const element = node;
+            if (target.testId !== undefined && element.getAttribute("data-testid") !== target.testId) {
+                return false;
+            }
+            const label = normalize(element.innerText ?? element.textContent ?? "");
+            if (label !== normalizedLabel) {
+                return false;
+            }
+            const rect = element.getBoundingClientRect();
+            const style = window.getComputedStyle(element);
+            return rect.width > 0
+                && rect.height > 0
+                && style.visibility !== "hidden"
+                && style.display !== "none"
+                && style.opacity !== "0";
+        });
+        if (matches.length !== 1)
+            return undefined;
+        const rect = matches[0].getBoundingClientRect();
+        return {
+            x: Math.round(rect.left + rect.width / 2),
+            y: Math.round(rect.top + rect.height / 2)
+        };
+    }, target).catch(() => undefined);
+}
+async function modelVersionMenuItemsAreVisible(page) {
+    return (await enumerateVisibleMenuItems(page))
+        .some(candidate => candidate.role === "menuitemradio" && MODEL_VERSION_LABEL_PATTERN.test(candidate.label));
+}
+function findExactMenuItem(items, wanted) {
+    const normalized = normalizeLabel(wanted);
+    const matches = items.filter(item => item.normalized === normalized);
+    return matches.length === 1 ? matches[0] : undefined;
+}
+function dedupeLabels(labels) {
+    return Array.from(new Set(labels));
+}
 async function selectorDrift(page, message, candidates) {
     const visibleText = candidates?.join("\n") ?? await visibleButtonLabels(page);
     return {

package/dist/src/commands/project-sources.d.ts

@@ -0,0 +1,10 @@
+import type { CommandResult, ProjectSource, ProjectSourcesAddArgs, ProjectSourcesAddData, ProjectSourcesAddPlanData, ProjectSourcesListArgs, ProjectSourcesListData, ProjectSourcesPlanAddArgs, ProjectSourcesUrl, RuntimeEnv } from "../types.js";
+type SafeCandidate = NonNullable<NonNullable<CommandResult["blocker"]>["candidates"]>[number];
+export declare function normalizeProjectSourcesUrl(value: string): ProjectSourcesUrl;
+export declare function buildProjectSourceAddPlan(env: RuntimeEnv, args: ProjectSourcesPlanAddArgs): Promise<CommandResult<ProjectSourcesAddPlanData>>;
+export declare function listProjectSources(env: RuntimeEnv, args: ProjectSourcesListArgs): Promise<CommandResult<ProjectSourcesListData>>;
+export declare function addProjectSources(env: RuntimeEnv, args: ProjectSourcesAddArgs): Promise<CommandResult<ProjectSourcesAddData | ProjectSourcesAddPlanData>>;
+export declare function diffProjectSourceNames(before: ProjectSource[], after: ProjectSource[]): ProjectSource[];
+export declare function extractProjectSourcesFromHtml(html: string): ProjectSource[];
+export declare function safeProjectSourceCandidatesFromHtml(html: string): SafeCandidate[];
+export {};