codex-chatgpt-control 0.5.0-alpha.1 → 0.5.1-alpha.2

package/dist/src/commands/configuration.js

@@ -2,11 +2,14 @@ import { enumerateVisibleMenuItems } from "../dom/menus.js";
 import { localeLabels } from "../dom/locale-labels.js";
 import { normalizeForLabelMatch, visibleLabelMatches } from "../dom/label-match.js";
 import { resultError, resultOk } from "../errors.js";
+import { tabIdFromPage } from "../browser/attach.js";
 import { contextFromPage } from "./context.js";
 import { detectExperience, openExperience } from "./experience.js";
 import { setMode } from "./modes.js";
 import { ensurePage } from "./session.js";
 const WORK_AXES = ["model", "effort", "speed"];
+const CONFIGURATION_CONTROL_DISCOVERY_TIMEOUT_MS = 5_000;
+const CONFIGURATION_CONTROL_POLL_MS = 250;
 const CONFIGURATION_AXIS_ORDER = [
     "model",
     "intelligence",
@@ -44,18 +47,27 @@ export async function inspectConfiguration(env, args = {}) {
             };
         }
         const experience = detected.data.experience;
-        const rootOpened = experience !== "unknown" && await openConfigurationRoot(page, experience);
+        const initialPanel = await readConfigurationPanel(page);
+        const rootOpened = experience !== "unknown" && await waitForConfigurationRoot(page, experience, args.timeoutMs);
         if (rootOpened) {
             await page.waitForTimeout?.(150);
         }
+        const workAdvancedOpened = experience !== "work"
+            || (rootOpened && await ensureWorkAdvancedPanel(page));
+        if (experience === "work" && workAdvancedOpened) {
+            await page.waitForTimeout?.(150);
+        }
         const panel = await readConfigurationPanel(page);
+        if (panel.openerLabel === undefined && initialPanel.openerLabel !== undefined) {
+            panel.openerLabel = initialPanel.openerLabel;
+        }
         const rootItems = rootOpened ? await enumerateVisibleMenuItems(page) : [];
         const data = configurationInspectionFromSurface(experience, detected.data.selectorProfile, detected.data.evidence, panel, rootItems);
         if (args.includeOptions !== false && experience === "work" && panel.axisRows.length > 0) {
             for (const axis of WORK_AXES) {
                 if (!data.availableAxes.includes(axis))
                     continue;
-                const options = await inspectWorkAxisOptions(page, axis);
+                const options = await inspectWorkAxisOptions(env, axis);
                 if (options.length > 0) {
                     data.options[axis] = options;
                 }
@@ -66,6 +78,9 @@ export async function inspectConfiguration(env, args = {}) {
         if (!rootOpened) {
             warnings.push("No scoped configuration opener was available; inspection is limited to controls already visible in the composer.");
         }
+        if (experience === "work" && rootOpened && !workAdvancedOpened) {
+            warnings.push("The Work configuration menu opened, but its Advanced model, effort, and speed controls could not be made visible.");
+        }
         if (!data.verified) {
             warnings.push("The visible configuration could not be verified from a recognized Chat or Work selector profile.");
         }
@@ -78,6 +93,18 @@ export async function inspectConfiguration(env, args = {}) {
         return resultError(error instanceof Error ? error : new Error(String(error)), await contextFromPage(page));
     }
 }
+async function waitForConfigurationRoot(page, experience, timeoutMs) {
+    const discoveryMs = Math.min(timeoutMs ?? CONFIGURATION_CONTROL_DISCOVERY_TIMEOUT_MS, CONFIGURATION_CONTROL_DISCOVERY_TIMEOUT_MS);
+    const attempts = Math.max(1, Math.ceil(Math.max(0, discoveryMs) / CONFIGURATION_CONTROL_POLL_MS));
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        if (await openConfigurationRoot(page, experience))
+            return true;
+        if (attempt + 1 < attempts) {
+            await page.waitForTimeout?.(CONFIGURATION_CONTROL_POLL_MS);
+        }
+    }
+    return false;
+}
 export async function applyConfiguration(env, args) {
     const boot = await ensurePage(env);
     if (!boot.ok) {
@@ -131,7 +158,7 @@ export async function applyConfiguration(env, args) {
                 continue;
             }
             const selection = before.experience === "work"
-                ? await selectWorkAxis(page, axis, requested)
+                ? await selectWorkAxis(env, axis, requested)
                 : await selectChatAxis(env, axis, requested, args.timeoutMs);
             if (selection === undefined) {
                 return configurationFailure(page, before, desired, selected, `Configuration option "${requested}" for ${axis} was not found or was ambiguous on the ${before.experience} surface.`, "configuration_option_not_found", before.options[axis]?.map(option => option.label));
@@ -227,36 +254,168 @@ export function configurationInspectionFromSurface(experience, detectedProfile,
         evidence
     };
 }
-async function inspectWorkAxisOptions(page, axis) {
-    await ensureWorkConfigurationRoot(page);
-    if (!await clickWorkAxisRow(page, axis)) {
-        return [];
-    }
-    await page.waitForTimeout?.(120);
-    const items = await enumerateVisibleMenuItems(page);
-    const options = items
-        .filter(item => !isConfigurationAxisRow(item.label))
+async function inspectWorkAxisOptions(env, axis) {
+    const page = env.page;
+    const options = (await openWorkAxisOptions(env, axis))
         .map(menuItemToOption);
-    await page.keyboard?.press?.("Escape");
-    await page.waitForTimeout?.(80);
+    await closeConfigurationSubmenu(page);
     return dedupeOptions(options);
 }
-async function selectWorkAxis(page, axis, requested) {
+async function selectWorkAxis(env, axis, requested) {
+    const page = env.page;
     if (!WORK_AXES.includes(axis)) {
         return undefined;
     }
-    await ensureWorkConfigurationRoot(page);
-    if (!await clickWorkAxisRow(page, axis)) {
-        return undefined;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const candidates = await openWorkAxisOptions(env, axis);
+        const match = findConfigurationOption(candidates, requested);
+        if (match !== undefined && await clickVisibleMenuItem(page, match)) {
+            await page.waitForTimeout?.(150);
+            return match.label;
+        }
+        if (attempt === 0) {
+            // The submenu can disappear between enumeration and the visible click
+            // when ChatGPT's pointer-grace timer fires. Reopen once and click from a
+            // fresh DOM instance instead of treating that transient race as drift.
+            await closeConfigurationMenus(page);
+            await page.waitForTimeout?.(200);
+        }
     }
-    await page.waitForTimeout?.(120);
-    const candidates = await enumerateVisibleMenuItems(page);
-    const match = findConfigurationOption(candidates, requested);
-    if (match === undefined || !await clickVisibleMenuItem(page, match)) {
+    return undefined;
+}
+async function openWorkAxisOptions(env, axis, allowRootRetry = true) {
+    const page = env.page;
+    if (!await ensureWorkAdvancedPanel(page))
+        return [];
+    const row = await findWorkAxisRow(page, axis);
+    if (row === undefined)
+        return [];
+    const visibleOptions = async () => filterWorkAxisOptions(await enumerateVisibleMenuItems(page), axis);
+    const alreadyOpen = await visibleOptions();
+    if (alreadyOpen.length > 0)
+        return alreadyOpen;
+    const point = await locatorCenter(row);
+    if (point !== undefined && await movePointerWithCdp(env, point)) {
+        await page.waitForTimeout?.(180);
+        const hoveredOptions = await visibleOptions();
+        if (hoveredOptions.length > 0)
+            return hoveredOptions;
+        // Radix may apply the previous submenu's pointer-grace close after the new
+        // axis briefly opens. Once that timer has elapsed, a tiny in-row nudge
+        // creates a fresh hover transition without ever leaving the root menu.
+        await movePointerWithCdp(env, { x: point.x - 2, y: point.y });
+        await movePointerWithCdp(env, point);
+        await page.waitForTimeout?.(180);
+        const retriedOptions = await visibleOptions();
+        if (retriedOptions.length > 0)
+            return retriedOptions;
+    }
+    if (point !== undefined && page.mouse?.move !== undefined) {
+        try {
+            await page.mouse.move(point.x, point.y);
+        }
+        catch {
+            // Fall through to the Computer Use and click fallbacks.
+        }
+        await page.waitForTimeout?.(180);
+        const mouseOptions = await visibleOptions();
+        if (mouseOptions.length > 0)
+            return mouseOptions;
+    }
+    if (point !== undefined && typeof page.cua?.move === "function") {
+        try {
+            await page.cua.move(point);
+        }
+        catch {
+            // Fall through to the click fallback.
+        }
+        await page.waitForTimeout?.(180);
+        const movedOptions = await visibleOptions();
+        if (movedOptions.length > 0)
+            return movedOptions;
+    }
+    if (row.click !== undefined) {
+        await row.click().catch(() => undefined);
+        await page.waitForTimeout?.(180);
+    }
+    const clickedOptions = await visibleOptions();
+    if (clickedOptions.length > 0 || !allowRootRetry)
+        return clickedOptions;
+    // A submenu pointer-grace dismissal can also close the root menu. Reopen the
+    // complete Advanced panel once and resolve a fresh row locator; stale row
+    // handles and same-coordinate pointer moves cannot recover a detached menu.
+    await closeConfigurationMenus(page);
+    await page.waitForTimeout?.(200);
+    return openWorkAxisOptions(env, axis, false);
+}
+async function locatorCenter(locator) {
+    if (locator.evaluate === undefined)
         return undefined;
+    return locator.evaluate(element => {
+        const rect = element.getBoundingClientRect();
+        return {
+            x: Math.round(rect.left + rect.width / 2),
+            y: Math.round(rect.top + rect.height / 2)
+        };
+    }).catch(() => undefined);
+}
+async function movePointerWithCdp(env, point) {
+    const page = env.page;
+    const tabId = page === undefined ? undefined : tabIdFromPage(page);
+    if (tabId === undefined || env.browser?.tabs?.get === undefined)
+        return false;
+    try {
+        const tab = await env.browser.tabs.get(tabId);
+        const capability = await tab.capabilities?.get?.("cdp");
+        if (capability?.send === undefined)
+            return false;
+        // Move directly between axis rows. Moving outside the Radix root menu first
+        // schedules its dismissal; the submenu can briefly appear and then vanish
+        // before the bounded option inspection runs.
+        await capability.send("Input.dispatchMouseEvent", {
+            type: "mouseMoved",
+            x: Math.round(point.x),
+            y: Math.round(point.y),
+            button: "none",
+            buttons: 0,
+            pointerType: "mouse"
+        });
+        return true;
     }
-    await page.waitForTimeout?.(150);
-    return match.label;
+    catch {
+        return false;
+    }
+}
+function filterWorkAxisOptions(items, axis) {
+    return items.filter(item => {
+        if (isConfigurationAxisRow(item.label))
+            return false;
+        // Keep every choice axis-specific. This excludes parent actions such as
+        // "Reset to default" and prevents a still-open model submenu from being
+        // mistaken for effort or speed choices if Escape is unavailable.
+        return workAxisOptionLabelMatches(axis, item.label);
+    });
+}
+function workAxisOptionLabelMatches(axis, label) {
+    if (axis === "model") {
+        return /\b(?:gpt[\s-]?\d|sol|luna|terra)\b/i.test(label);
+    }
+    const candidates = axis === "effort"
+        ? [
+            ...localeLabels.configurationOptions.light,
+            ...localeLabels.configurationOptions.medium,
+            ...localeLabels.configurationOptions.high,
+            ...localeLabels.configurationOptions.extraHigh,
+            ...localeLabels.configurationOptions.max,
+            ...localeLabels.configurationOptions.ultra,
+        ]
+        : axis === "speed"
+            ? [
+                ...localeLabels.configurationOptions.standard,
+                ...localeLabels.configurationOptions.fast,
+            ]
+            : [];
+    return candidates.some(candidate => visibleLabelMatches(label, candidate));
 }
 async function selectChatAxis(env, axis, requested, timeoutMs) {
     const legacyArgs = axis === "modelVersion"
@@ -286,20 +445,46 @@ async function openConfigurationRoot(page, experience) {
     if (configurationMenuLooksRecognized(existingItems, experience, existing.openerLabel)) {
         return true;
     }
+    if (existing.openerLabel !== undefined
+        && await clickIfUnique(page.getByRole?.("button", { name: existing.openerLabel, exact: true }))) {
+        return true;
+    }
     if (typeof page.evaluate === "function") {
         const clicked = await page.evaluate((surface) => {
             const normalize = (value) => value.replace(/\s+/g, " ").trim();
             const visible = (element) => {
                 const html = element;
                 const rect = html.getBoundingClientRect?.();
-                const style = typeof window !== "undefined" ? window.getComputedStyle?.(html) : undefined;
-                return (rect === undefined || (rect.width > 0 && rect.height > 0))
-                    && style?.display !== "none"
-                    && style?.visibility !== "hidden"
-                    && style?.opacity !== "0";
+                if (rect !== undefined && (rect.width <= 0 || rect.height <= 0))
+                    return false;
+                let current = element;
+                while (current !== null) {
+                    if (current.hasAttribute?.("inert") || current.getAttribute?.("aria-hidden") === "true") {
+                        return false;
+                    }
+                    const style = typeof window !== "undefined"
+                        ? window.getComputedStyle?.(current)
+                        : undefined;
+                    if (style?.display === "none" || style?.visibility === "hidden" || style?.opacity === "0") {
+                        return false;
+                    }
+                    current = current.parentElement ?? null;
+                }
+                return true;
             };
-            const forms = Array.from(document.querySelectorAll("main form, main [data-testid*='composer' i]"));
-            const controls = forms.flatMap(form => Array.from(form.querySelectorAll("button, [role='button']")))
+            const formRoots = Array.from(document.querySelectorAll("main form"));
+            const testIdRoots = Array.from(document.querySelectorAll("main [data-testid*='composer' i]"));
+            const classRoots = Array.from(document.querySelectorAll("main [class*='composer' i]"));
+            const composerRoots = formRoots.length > 0
+                ? formRoots
+                : testIdRoots.length > 0
+                    ? testIdRoots
+                    : classRoots;
+            const main = document.querySelector("main");
+            const roots = Array.from(new Set(composerRoots.length > 0
+                ? composerRoots
+                : (main === null ? [] : [main])));
+            const controls = Array.from(new Set(roots.flatMap(root => Array.from(root.querySelectorAll("button, [role='button']")))))
                 .filter(visible);
             const matches = controls.filter(control => {
                 const html = control;
@@ -347,6 +532,9 @@ function configurationMenuLooksRecognized(items, experience, openerLabel) {
     if (items.some(item => /(?:model|mode|effort|speed)-(?:switcher|selector)|model-switcher/i.test(item.testId ?? ""))) {
         return true;
     }
+    if (experience === "work" && items.some(item => localeLabels.configurationAxes.advanced.some(label => visibleLabelMatches(item.label, label)))) {
+        return true;
+    }
     if (openerLabel === undefined || items.length === 0) {
         return false;
     }
@@ -374,13 +562,22 @@ function configurationMenuLooksRecognized(items, experience, openerLabel) {
         .map(item => normalizeConfigurationId(item.label)));
     return matched.size >= 2;
 }
-async function ensureWorkConfigurationRoot(page) {
+async function ensureWorkAdvancedPanel(page) {
     const panel = await readConfigurationPanel(page);
     if (panel.axisRows.length > 0)
         return true;
-    await page.keyboard?.press?.("Escape");
-    await page.waitForTimeout?.(50);
-    return openConfigurationRoot(page, "work");
+    if (!await openConfigurationRoot(page, "work"))
+        return false;
+    const reopenedPanel = await readConfigurationPanel(page);
+    if (reopenedPanel.axisRows.length > 0)
+        return true;
+    const items = await enumerateVisibleMenuItems(page);
+    const advanced = items.filter(item => localeLabels.configurationAxes.advanced.some(label => visibleLabelMatches(item.label, label)));
+    if (advanced.length !== 1 || !await clickVisibleMenuItem(page, advanced[0])) {
+        return false;
+    }
+    await page.waitForTimeout?.(200);
+    return (await readConfigurationPanel(page)).axisRows.length > 0;
 }
 async function readConfigurationPanel(page) {
     if (typeof page.evaluate !== "function") {
@@ -395,24 +592,31 @@ async function readConfigurationPanel(page) {
         const visible = (element) => {
             const html = element;
             const rect = html.getBoundingClientRect?.();
-            const style = typeof window !== "undefined" ? window.getComputedStyle?.(html) : undefined;
-            return (rect === undefined || (rect.width > 0 && rect.height > 0))
-                && style?.display !== "none"
-                && style?.visibility !== "hidden"
-                && style?.opacity !== "0";
+            if (rect !== undefined && (rect.width <= 0 || rect.height <= 0))
+                return false;
+            let current = element;
+            while (current !== null) {
+                if (current.hasAttribute?.("inert") || current.getAttribute?.("aria-hidden") === "true") {
+                    return false;
+                }
+                const style = typeof window !== "undefined"
+                    ? window.getComputedStyle?.(current)
+                    : undefined;
+                if (style?.display === "none" || style?.visibility === "hidden" || style?.opacity === "0") {
+                    return false;
+                }
+                current = current.parentElement ?? null;
+            }
+            return true;
         };
         const overlays = Array.from(document.querySelectorAll("[role='menu'], [role='listbox'], [data-radix-popper-content-wrapper], [data-radix-menu-content]")).filter(visible);
         const roots = overlays.length > 0 ? overlays : Array.from(document.querySelectorAll("main")).filter(visible);
         const rows = roots.flatMap(root => Array.from(root.querySelectorAll("button, [role='button'], [role='menuitem'], [role='menuitemradio'], [role='option']"))).filter(visible);
         const axisRows = [];
-        let advancedVisible = false;
         for (const row of rows) {
             const html = row;
             const label = normalize(row.getAttribute("aria-label") ?? html.innerText ?? row.textContent ?? "");
             const normalized = label.toLocaleLowerCase();
-            if (normalizedAxes.advanced?.some(candidate => normalized === candidate || normalized.startsWith(`${candidate} `))) {
-                advancedVisible = true;
-            }
             for (const axis of ["model", "intelligence", "effort", "speed"]) {
                 const candidates = normalizedAxes[axis] ?? [];
                 const prefix = candidates.find(candidate => normalized === candidate || normalized.startsWith(`${candidate} `));
@@ -426,8 +630,19 @@ async function readConfigurationPanel(page) {
                 break;
             }
         }
-        const forms = Array.from(document.querySelectorAll("main form, main [data-testid*='composer' i]"));
-        const openerCandidates = forms.flatMap(form => Array.from(form.querySelectorAll("button, [role='button']")))
+        const formRoots = Array.from(document.querySelectorAll("main form"));
+        const testIdRoots = Array.from(document.querySelectorAll("main [data-testid*='composer' i]"));
+        const classRoots = Array.from(document.querySelectorAll("main [class*='composer' i]"));
+        const composerRoots = formRoots.length > 0
+            ? formRoots
+            : testIdRoots.length > 0
+                ? testIdRoots
+                : classRoots;
+        const main = document.querySelector("main");
+        const openerRoots = Array.from(new Set(composerRoots.length > 0
+            ? composerRoots
+            : (main === null ? [] : [main])));
+        const openerCandidates = Array.from(new Set(openerRoots.flatMap(root => Array.from(root.querySelectorAll("button, [role='button']")))))
             .filter(visible)
             .map(control => {
             const html = control;
@@ -441,7 +656,7 @@ async function readConfigurationPanel(page) {
             || /\b(?:gpt|sol|luna|terra|instant|medium|high|extra high|pro|thinking|extended|light|standard|fast)\b/i.test(item.label));
         const result = {
             axisRows,
-            advancedVisible
+            advancedVisible: axisRows.length > 0
         };
         if (openerCandidates.length === 1 && openerCandidates[0]?.label.length) {
             result.openerLabel = openerCandidates[0].label;
@@ -449,44 +664,47 @@ async function readConfigurationPanel(page) {
         return result;
     }, localeLabels.configurationAxes).catch(() => ({ axisRows: [], advancedVisible: false }));
 }
-async function clickWorkAxisRow(page, axis) {
+async function findWorkAxisRow(page, axis) {
     const labels = axis === "modelVersion" ? [] : localeLabels.configurationAxes[axis] ?? [];
     for (const label of labels) {
         const pattern = new RegExp(`^${escapeRegExp(label)}(?:\\s|$)`, "i");
         for (const role of ["button", "menuitem"]) {
-            if (await clickIfUnique(page.getByRole?.(role, { name: pattern }))) {
-                return true;
+            const locator = page.getByRole?.(role, { name: pattern });
+            if (locator?.count !== undefined && await locator.count().catch(() => 0) === 1) {
+                return locator;
             }
         }
     }
-    if (typeof page.evaluate !== "function")
-        return false;
-    return page.evaluate((wantedLabels) => {
-        const normalize = (value) => value.replace(/\s+/g, " ").trim().toLocaleLowerCase();
-        const wanted = wantedLabels.map(normalize);
-        const overlays = Array.from(document.querySelectorAll("[role='menu'], [data-radix-popper-content-wrapper], [data-radix-menu-content]"));
-        const nodes = overlays.flatMap(root => Array.from(root.querySelectorAll("button, [role='button'], [role='menuitem']")));
-        const matches = nodes.filter(node => {
-            const html = node;
-            const label = normalize(node.getAttribute("aria-label") ?? html.innerText ?? node.textContent ?? "");
-            return wanted.some(prefix => label === prefix || label.startsWith(`${prefix} `));
-        });
-        if (matches.length !== 1)
-            return false;
-        matches[0].click();
-        return true;
-    }, labels).catch(() => false);
+    return undefined;
 }
 async function clickVisibleMenuItem(page, item) {
     if (item.testId !== undefined && await clickIfUnique(page.locator?.(`[data-testid="${escapeAttributeValue(item.testId)}"]`))) {
         return true;
     }
-    for (const role of ["menuitemradio", "menuitem", "option"]) {
+    const roles = [...new Set([
+            item.role,
+            "menuitemradio",
+            "menuitem",
+            "option"
+        ].filter((role) => role !== undefined))];
+    // Current Chat can expose visible text such as "Advanced" while assigning
+    // the actionable menu item a different accessible name (for example,
+    // "Show compact options"). Prefer that enumerated accessible name so the
+    // bridge clicks the menu item itself rather than a nested text span.
+    if (item.ariaLabel !== undefined) {
+        for (const role of roles) {
+            if (await clickIfUnique(page.getByRole?.(role, { name: item.ariaLabel, exact: true }))) {
+                return true;
+            }
+        }
+    }
+    for (const role of roles) {
         if (await clickIfUnique(page.getByRole?.(role, { name: item.label, exact: true }))) {
             return true;
         }
     }
-    return clickIfUnique(page.getByText?.(item.label, { exact: true }));
+    const exactText = new RegExp(`^\\s*${escapeRegExp(item.label)}\\s*$`, "i");
+    return clickIfUnique(page.locator?.("button, [role='button'], [role='menuitem'], [role='menuitemradio'], [role='option']")?.filter?.({ hasText: exactText }));
 }
 function findConfigurationOption(items, requested) {
     const normalizedRequested = normalizeConfigurationId(requested);
@@ -608,16 +826,55 @@ function normalizeConfigurationId(value) {
         .trim();
 }
 async function closeConfigurationMenus(page) {
-    await page.keyboard?.press?.("Escape");
+    if (!await pressConfigurationEscape(page))
+        return;
     await page.waitForTimeout?.(50);
-    await page.keyboard?.press?.("Escape");
+    await pressConfigurationEscape(page);
+}
+async function closeConfigurationSubmenu(page) {
+    if (!await pressConfigurationEscape(page))
+        return;
+    // Radix retains a short pointer-grace timer after a submenu closes. If the
+    // next axis is hovered too quickly, that stale timer can dismiss the newly
+    // opened submenu. Let the prior close settle before moving to another row.
+    await page.waitForTimeout?.(200);
+}
+async function pressConfigurationEscape(page) {
+    if (page.keyboard?.press !== undefined) {
+        await page.keyboard.press("Escape");
+        return true;
+    }
+    if (page.cua?.keypress !== undefined) {
+        try {
+            await page.cua.keypress({ keys: ["ESC"] });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
 }
 async function clickIfUnique(locator) {
     if (locator?.count === undefined || locator.click === undefined)
         return false;
-    if (await locator.count().catch(() => 0) !== 1)
+    const count = await locator.count().catch(() => 0);
+    if (count === 1) {
+        await locator.click();
+        return true;
+    }
+    if (count <= 1 || locator.nth === undefined)
+        return false;
+    const visible = [];
+    for (let index = 0; index < count; index += 1) {
+        const candidate = locator.nth(index);
+        if (candidate.isVisible !== undefined && await candidate.isVisible().catch(() => false)) {
+            visible.push(candidate);
+        }
+    }
+    if (visible.length !== 1 || visible[0]?.click === undefined)
         return false;
-    await locator.click();
+    await visible[0].click();
     return true;
 }
 async function configurationFailure(page, before, desired, selected, message, code, candidates = []) {

package/dist/src/commands/context.d.ts

@@ -1,2 +1,6 @@
 import type { CommandContext, PageLike } from "../types.js";
-export declare function contextFromPage(page: PageLike | undefined, partial?: Partial<CommandContext>): Promise<CommandContext>;
+export type ContextReadOptions = {
+    /** Avoid all optional browser probes on mutation/deadline result paths. */
+    minimal?: boolean;
+};
+export declare function contextFromPage(page: PageLike | undefined, partial?: Partial<CommandContext>, options?: ContextReadOptions): Promise<CommandContext>;

package/dist/src/commands/context.js

@@ -1,8 +1,8 @@
 import { countPageMessages } from "../dom/messages.js";
 import { parseConversationId } from "../browser/page-state.js";
 import { withTimeout } from "./timeouts.js";
-export async function contextFromPage(page, partial = {}) {
-    if (page === undefined) {
+export async function contextFromPage(page, partial = {}, options = {}) {
+    if (page === undefined || options.minimal === true) {
         return { timestamp: new Date().toISOString(), ...partial };
     }
     const url = typeof page.url === "function" ? await Promise.resolve(page.url()).catch(() => partial.url) : partial.url;

package/dist/src/commands/conversation.js

@@ -1,17 +1,29 @@
 import { parseConversationId } from "../browser/page-state.js";
+import { isChatGPTUrl, requireChatGPTUrl } from "../browser/chatgpt-url.js";
 import { countPageMessages, readLatestMessageText } from "../dom/messages.js";
 const CHATGPT_HOME = "https://chatgpt.com/";
 export async function ensureConversationTarget(page, target, options) {
     const targetUrl = absoluteConversationUrl(target);
+    requireChatGPTUrl(targetUrl, "Conversation target URL");
     const expectedConversationId = parseConversationId(targetUrl);
     const currentUrl = typeof page.url === "function" ? await Promise.resolve(page.url()).catch(() => "") : "";
-    if (expectedConversationId !== undefined
+    if (isChatGPTUrl(typeof currentUrl === "string" ? currentUrl : "")
+        &&
+            expectedConversationId !== undefined
         && parseConversationId(typeof currentUrl === "string" ? currentUrl : "") === expectedConversationId) {
         await waitForConversationHydrated(page, options.timeoutMs, expectedConversationId);
         return ensureResult(false, targetUrl, expectedConversationId);
     }
     await page.goto?.(targetUrl, { waitUntil: "domcontentloaded", timeout: options.timeoutMs });
+    const navigatedUrl = typeof page.url === "function" ? await Promise.resolve(page.url()).catch(() => "") : "";
+    requireChatGPTUrl(typeof navigatedUrl === "string" ? navigatedUrl : "", "Conversation navigation result");
     await waitForConversationHydrated(page, options.timeoutMs, expectedConversationId);
+    const finalUrl = typeof page.url === "function" ? await Promise.resolve(page.url()).catch(() => "") : "";
+    requireChatGPTUrl(typeof finalUrl === "string" ? finalUrl : "", "Hydrated conversation URL");
+    if (expectedConversationId !== undefined
+        && parseConversationId(typeof finalUrl === "string" ? finalUrl : "") !== expectedConversationId) {
+        throw new Error(`Visible Chat navigation did not reach conversation ${expectedConversationId}.`);
+    }
     return ensureResult(true, targetUrl, expectedConversationId);
 }
 export async function waitForConversationHydrated(page, timeoutMs, expectedConversationId) {