autokap 1.0.0

package/dist/browser.js

@@ -0,0 +1,2902 @@
+import { chromium } from 'playwright';
+import sharp from 'sharp';
+import { createHash } from 'crypto';
+/**
+ * Set-of-Marks (SoM) annotation: overlays colored [N] badges on each visible
+ * interactive element so the vision model can reference elements by their badge index.
+ * Inspired by SoM prompting (Yang et al., 2310.11441) used in production web agents.
+ *
+ * Color scheme by role:
+ *   button → blue    input/textarea/select → green    link → orange    other → gray
+ */
+async function annotateWithSetOfMarks(screenshot, elements) {
+    // Only annotate visible elements that have a valid bounding box
+    const toAnnotate = elements.filter(el => el.visible && el.boundingBox && el.boundingBox.width > 4 && el.boundingBox.height > 4);
+    if (toAnnotate.length === 0)
+        return screenshot;
+    const meta = await sharp(screenshot).metadata();
+    const imgWidth = meta.width ?? 1280;
+    const imgHeight = meta.height ?? 800;
+    function roleColor(el) {
+        const role = el.role?.toLowerCase() ?? '';
+        const tag = el.tag?.toLowerCase() ?? '';
+        if (role === 'button' || tag === 'button')
+            return '#2563eb'; // blue
+        if (tag === 'input' || tag === 'textarea' || tag === 'select' || role === 'textbox' || role === 'combobox' || role === 'spinbutton')
+            return '#16a34a'; // green
+        if (role === 'link' || tag === 'a')
+            return '#ea580c'; // orange
+        return '#6b7280'; // gray
+    }
+    // Build an SVG overlay with one rectangle + badge per element
+    const svgParts = [];
+    for (const el of toAnnotate) {
+        const bb = el.boundingBox;
+        // Clamp bounding box to image dimensions
+        const x = Math.max(0, Math.min(Math.round(bb.x), imgWidth - 2));
+        const y = Math.max(0, Math.min(Math.round(bb.y), imgHeight - 2));
+        const w = Math.min(Math.round(bb.width), imgWidth - x);
+        const h = Math.min(Math.round(bb.height), imgHeight - y);
+        if (w < 2 || h < 2)
+            continue;
+        const color = roleColor(el);
+        const label = String(el.index);
+        const fontSize = Math.max(9, Math.min(13, Math.round(h * 0.55)));
+        const badgeW = Math.max(label.length * fontSize * 0.65 + 4, 14);
+        const badgeH = fontSize + 4;
+        const bx = Math.min(x, imgWidth - badgeW);
+        const by = Math.max(0, y - badgeH);
+        svgParts.push(
+        // Element outline rectangle
+        `<rect x="${x}" y="${y}" width="${w}" height="${h}" fill="none" stroke="${color}" stroke-width="1.5" opacity="0.75"/>`, 
+        // Badge background
+        `<rect x="${bx}" y="${by}" width="${badgeW}" height="${badgeH}" fill="${color}" rx="2"/>`, 
+        // Badge text
+        `<text x="${bx + badgeW / 2}" y="${by + badgeH - 3}" font-family="monospace,sans-serif" font-size="${fontSize}" font-weight="bold" fill="white" text-anchor="middle">${label}</text>`);
+    }
+    if (svgParts.length === 0)
+        return screenshot;
+    const svgOverlay = `<svg xmlns="http://www.w3.org/2000/svg" width="${imgWidth}" height="${imgHeight}">${svgParts.join('')}</svg>`;
+    try {
+        return await sharp(screenshot)
+            .composite([{ input: Buffer.from(svgOverlay), top: 0, left: 0 }])
+            .jpeg({ quality: 72 })
+            .toBuffer();
+    }
+    catch {
+        // If annotation fails (e.g. coordinate overflow), return original screenshot
+        return screenshot;
+    }
+}
+function normalizeViewportDimension(value) {
+    if (!Number.isFinite(value))
+        return 1;
+    return Math.max(1, Math.round(value));
+}
+function resolveEffectivePadding(config, bbox) {
+    let top = 0, right = 0, bottom = 0, left = 0;
+    // Layer 1: percentage-based
+    if (config.paddingPercent != null) {
+        top = bottom = (config.paddingPercent / 100) * bbox.height;
+        left = right = (config.paddingPercent / 100) * bbox.width;
+    }
+    // Layer 2: uniform (overrides percent)
+    if (config.padding != null) {
+        top = right = bottom = left = config.padding;
+    }
+    // Layer 3: per-side (overrides uniform)
+    if (config.paddingTop != null)
+        top = config.paddingTop;
+    if (config.paddingRight != null)
+        right = config.paddingRight;
+    if (config.paddingBottom != null)
+        bottom = config.paddingBottom;
+    if (config.paddingLeft != null)
+        left = config.paddingLeft;
+    return { top, right, bottom, left };
+}
+import { dismissCookiesAndWidgets } from './cookie-dismiss.js';
+import { CHROMIUM_ARGS, browserPool } from './browser-pool.js';
+async function withHelperTimeout(label, timeoutMs, work) {
+    if (!timeoutMs || timeoutMs <= 0) {
+        return work();
+    }
+    let timer = null;
+    try {
+        return await Promise.race([
+            work(),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/**
+ * Map a BCP-47 language tag to a Playwright-compatible locale string.
+ * Playwright accepts both "fr" and "fr-FR". We normalize 2-char codes to their
+ * primary regional variant so JS Intl APIs behave correctly.
+ */
+function langToLocale(lang) {
+    if (!lang)
+        return 'en-US';
+    if (lang.includes('-') || lang.includes('_'))
+        return lang;
+    const map = {
+        en: 'en-US', fr: 'fr-FR', de: 'de-DE', es: 'es-ES',
+        it: 'it-IT', pt: 'pt-PT', nl: 'nl-NL', ja: 'ja-JP',
+        zh: 'zh-CN', ko: 'ko-KR', ar: 'ar-SA', ru: 'ru-RU',
+        pl: 'pl-PL', sv: 'sv-SE', da: 'da-DK', fi: 'fi-FI',
+        no: 'nb-NO', tr: 'tr-TR', cs: 'cs-CZ', hu: 'hu-HU',
+    };
+    return map[lang] ?? lang;
+}
+function normalizeDeviceScaleFactor(value) {
+    if (!Number.isFinite(value))
+        return 2;
+    return Math.max(0.5, Math.min(4, Number(value)));
+}
+function resolveRecordedVideoSize(viewport) {
+    // Playwright's video recorder expects a canvas size close to the CSS viewport.
+    // Using viewport × deviceScaleFactor can produce a larger recording surface
+    // with the page rendered only in the top-left corner, leaving the remainder
+    // as empty matte. Keep the recorded frame size aligned to the viewport and
+    // let the browser's deviceScaleFactor handle HiDPI rendering internally.
+    const width = Math.max(2, Math.round(viewport.width)) & ~1;
+    const height = Math.max(2, Math.round(viewport.height)) & ~1;
+    return { width, height };
+}
+function escapeCssAttributeValue(value) {
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"');
+}
+function escapeCssIdentifier(value) {
+    return value.replace(/(^-?\d)|[^a-zA-Z0-9_-]/g, (match) => `\\${match}`);
+}
+export function buildStableCssSelectorCandidates(snapshot) {
+    const tag = snapshot.tag.toLowerCase();
+    const candidates = [];
+    const push = (selector) => {
+        if (selector && !candidates.includes(selector)) {
+            candidates.push(selector);
+        }
+    };
+    if (snapshot.id) {
+        push(`#${escapeCssIdentifier(snapshot.id)}`);
+    }
+    for (const [attr, value] of [
+        ['data-testid', snapshot.dataTestId],
+        ['data-test', snapshot.dataTest],
+        ['data-qa', snapshot.dataQa],
+        ['data-cy', snapshot.dataCy],
+    ]) {
+        if (!value)
+            continue;
+        push(`[${attr}="${escapeCssAttributeValue(value)}"]`);
+        push(`${tag}[${attr}="${escapeCssAttributeValue(value)}"]`);
+    }
+    if (snapshot.name) {
+        push(`${tag}[name="${escapeCssAttributeValue(snapshot.name)}"]`);
+        if (snapshot.type) {
+            push(`${tag}[name="${escapeCssAttributeValue(snapshot.name)}"][type="${escapeCssAttributeValue(snapshot.type)}"]`);
+        }
+    }
+    if (tag === 'a' && snapshot.href) {
+        push(`a[href="${escapeCssAttributeValue(snapshot.href)}"]`);
+        if (snapshot.hreflang) {
+            push(`a[href="${escapeCssAttributeValue(snapshot.href)}"][hreflang="${escapeCssAttributeValue(snapshot.hreflang)}"]`);
+        }
+    }
+    for (const [attr, value] of [
+        ['aria-label', snapshot.ariaLabel],
+        ['title', snapshot.title],
+        ['placeholder', snapshot.placeholder],
+        ['data-lang', snapshot.dataLang],
+        ['data-language', snapshot.dataLanguage],
+        ['data-locale', snapshot.dataLocale],
+        ['data-theme', snapshot.dataTheme],
+        ['data-color-scheme', snapshot.dataColorScheme],
+        ['hreflang', snapshot.hreflang],
+    ]) {
+        if (!value)
+            continue;
+        push(`${tag}[${attr}="${escapeCssAttributeValue(value)}"]`);
+        if (snapshot.role) {
+            push(`${tag}[role="${escapeCssAttributeValue(snapshot.role)}"][${attr}="${escapeCssAttributeValue(value)}"]`);
+        }
+        if (snapshot.type) {
+            push(`${tag}[type="${escapeCssAttributeValue(snapshot.type)}"][${attr}="${escapeCssAttributeValue(value)}"]`);
+        }
+    }
+    if (snapshot.type) {
+        push(`${tag}[type="${escapeCssAttributeValue(snapshot.type)}"]`);
+    }
+    return candidates;
+}
+export function selectStableCssSelector(snapshot, isUniqueSelector) {
+    for (const selector of buildStableCssSelectorCandidates(snapshot)) {
+        if (isUniqueSelector(selector)) {
+            return selector;
+        }
+    }
+    return null;
+}
+function formatUrlForSummary(rawUrl) {
+    try {
+        const url = new URL(rawUrl);
+        return `${url.pathname || '/'}${url.search}${url.hash}` || rawUrl;
+    }
+    catch {
+        return rawUrl;
+    }
+}
+export function describeObservationChange(before, after) {
+    const changes = [];
+    if (after.url !== before.url) {
+        changes.push(`URL -> ${formatUrlForSummary(after.url)}`);
+    }
+    if (after.title !== before.title) {
+        changes.push(`title -> "${after.title || '(untitled)'}"`);
+    }
+    const scrollDeltaY = after.scrollY - before.scrollY;
+    if (Math.abs(scrollDeltaY) >= 40) {
+        changes.push(`scroll ${scrollDeltaY > 0 ? 'down' : 'up'} ${Math.abs(scrollDeltaY)}px`);
+    }
+    const interactiveDelta = after.interactiveCount - before.interactiveCount;
+    if (Math.abs(interactiveDelta) >= 1) {
+        changes.push(`interactive ${before.interactiveCount} -> ${after.interactiveCount}`);
+    }
+    if (after.dialogCount !== before.dialogCount) {
+        changes.push(`dialogs ${before.dialogCount} -> ${after.dialogCount}`);
+    }
+    if (after.expandedCount !== before.expandedCount) {
+        changes.push(`expanded controls ${before.expandedCount} -> ${after.expandedCount}`);
+    }
+    if (after.loadingIndicatorCount !== before.loadingIndicatorCount) {
+        if (after.loadingIndicatorCount === 0 && before.loadingIndicatorCount > 0) {
+            changes.push('loading indicators cleared');
+        }
+        else {
+            changes.push(`loading indicators ${before.loadingIndicatorCount} -> ${after.loadingIndicatorCount}`);
+        }
+    }
+    if (after.scrollHeight !== before.scrollHeight && Math.abs(after.scrollHeight - before.scrollHeight) > 100) {
+        changes.push(`page height ${before.scrollHeight}px -> ${after.scrollHeight}px`);
+    }
+    if (after.textSample
+        && after.textSample !== before.textSample
+        && !changes.some((entry) => entry.startsWith('URL ->'))) {
+        changes.push(`visible text changed to "${after.textSample.slice(0, 80)}"`);
+    }
+    return {
+        before,
+        after,
+        changed: changes.length > 0,
+        summary: changes.length > 0
+            ? changes.join('; ')
+            : 'No visible state change detected after the action.',
+    };
+}
+export class Browser {
+    options;
+    browser = null;
+    context = null;
+    page = null;
+    elementMap = new Map();
+    poolContext = false;
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * Create a Browser using the shared pool (server/web API mode).
+     * The Chromium process is reused across captures; only the context is isolated.
+     * Call browser.close() when done — it releases the context back to the pool.
+     */
+    static async fromPool(options) {
+        const instance = new Browser(options);
+        instance.context = await browserPool.acquireContext(options.viewport, normalizeDeviceScaleFactor(options.deviceScaleFactor), {
+            lang: langToLocale(options.lang ?? 'en'),
+            colorScheme: options.colorScheme ?? 'light',
+            storageState: options.storageState,
+        });
+        instance.page = await instance.context.newPage();
+        instance.poolContext = true;
+        return instance;
+    }
+    /**
+     * Create a Browser with a dedicated Chromium process and video recording enabled.
+     * The context is configured with `recordVideo` so Playwright records the session.
+     *
+     * IMPORTANT: After calling `browser.close()`, retrieve the video file path via
+     * `browser.currentPage.video()?.path()` BEFORE closing (save ref beforehand).
+     * Or call `browser.saveVideo(outputPath)` before closing.
+     *
+     * @param videoDir - Directory where Playwright will write the WebM file.
+     */
+    static async forVideoRecording(options, videoDir, cursorScript) {
+        const instance = new Browser(options);
+        const deviceScaleFactor = normalizeDeviceScaleFactor(options.deviceScaleFactor);
+        const recordedVideoSize = resolveRecordedVideoSize(options.viewport);
+        // Dedicated browser process for video — cannot use the pool because
+        // `recordVideo` must be set at context creation time.
+        instance.browser = await chromium.launch({
+            headless: true,
+            args: CHROMIUM_ARGS,
+        });
+        instance.context = await instance.browser.newContext({
+            viewport: options.viewport,
+            deviceScaleFactor,
+            locale: langToLocale(options.lang ?? 'en'),
+            colorScheme: options.colorScheme ?? 'light',
+            storageState: options.storageState,
+            recordVideo: {
+                dir: videoDir,
+                size: recordedVideoSize,
+            },
+        });
+        // Inject cursor overlay at context level — survives all navigations in this session
+        await instance.context.addInitScript(cursorScript);
+        instance.page = await instance.context.newPage();
+        return instance;
+    }
+    /**
+     * Close only the browser context (not the browser process).
+     * Use this for video recording: closing the context finalizes the WebM on disk
+     * while keeping the browser process alive so that saveAs() can still use the IPC channel.
+     * Call browser.close() afterwards to shut down the browser process.
+     */
+    async closeContext() {
+        if (this.context) {
+            try {
+                await this.context.close();
+            }
+            catch { /* ignore */ }
+            this.context = null;
+        }
+    }
+    async launch() {
+        // Pool mode: context and page are already initialized via fromPool()
+        if (this.poolContext)
+            return;
+        this.browser = await chromium.launch({
+            headless: !this.options.headed,
+            args: CHROMIUM_ARGS,
+        });
+        this.context = await this.browser.newContext({
+            viewport: this.options.viewport,
+            deviceScaleFactor: normalizeDeviceScaleFactor(this.options.deviceScaleFactor),
+            locale: langToLocale(this.options.lang ?? 'en'),
+            colorScheme: this.options.colorScheme ?? 'light',
+            storageState: this.options.storageState,
+        });
+        this.page = await this.context.newPage();
+    }
+    async addCookies(cookies) {
+        const context = this.ensureContext();
+        await context.addCookies(cookies.map(c => ({
+            name: c.name,
+            value: c.value,
+            domain: c.domain,
+            path: c.path || '/',
+            httpOnly: c.httpOnly ?? false,
+            secure: c.secure ?? true,
+            sameSite: c.sameSite || 'Lax',
+        })));
+    }
+    async close() {
+        if (this.poolContext) {
+            // Pool mode: close just the page, then release the context back to the pool
+            if (this.page) {
+                try {
+                    await this.page.close();
+                }
+                catch { /* ignore */ }
+                this.page = null;
+            }
+            if (this.context) {
+                await browserPool.releaseContext(this.context);
+                this.context = null;
+            }
+            this.poolContext = false;
+            return;
+        }
+        // Standalone mode (CLI): close the entire browser process
+        if (this.browser) {
+            await this.browser.close();
+            this.browser = null;
+            this.context = null;
+            this.page = null;
+        }
+    }
+    async navigateTo(url) {
+        const page = this.ensurePage();
+        // Fix common URL typos (htpps, hhtps, htps, etc.)
+        url = url.replace(/^h+t+p+s?:\/\//i, (m) => /s/i.test(m) ? 'https://' : 'http://');
+        if (!/^https?:\/\//i.test(url)) {
+            url = 'https://' + url;
+        }
+        try {
+            await page.goto(url, { waitUntil: 'load', timeout: 20000 });
+        }
+        catch {
+            // Fallback for SPAs that never fully load
+            await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 15000 });
+        }
+        // Wait for network to settle (no new requests for 300ms, max 3s)
+        await page.waitForLoadState('networkidle', { timeout: 3000 }).catch(() => { });
+        // Wait for DOM to stabilize (no mutations for 200ms, max 2s)
+        await this.waitForDomStability(page);
+    }
+    /**
+     * Wait for DOM to stabilize: no MutationObserver events for `settleMs`,
+     * with an overall timeout of `timeoutMs`.
+     */
+    async waitForDomStability(page, settleMs = 200, timeoutMs = 2000) {
+        try {
+            await page.evaluate(([settle, timeout]) => {
+                return new Promise((resolve) => {
+                    let timer;
+                    const observer = new MutationObserver(() => {
+                        clearTimeout(timer);
+                        timer = setTimeout(() => { observer.disconnect(); resolve(); }, settle);
+                    });
+                    observer.observe(document.documentElement, {
+                        childList: true, subtree: true, attributes: true,
+                    });
+                    // Start the settle timer immediately (page might already be stable)
+                    timer = setTimeout(() => { observer.disconnect(); resolve(); }, settle);
+                    // Hard timeout
+                    setTimeout(() => { observer.disconnect(); resolve(); }, timeout);
+                });
+            }, [settleMs, timeoutMs]);
+        }
+        catch {
+            // Page may have navigated during wait
+        }
+    }
+    async takeScreenshot() {
+        const page = this.ensurePage();
+        // Move cursor off-screen to avoid hover effects in screenshots
+        await page.mouse.move(0, 0);
+        return Buffer.from(await page.screenshot({ type: 'png', fullPage: false }));
+    }
+    async takeScreenshotForAI(options = {}) {
+        const page = this.ensurePage();
+        return withHelperTimeout('takeScreenshotForAI', options.timeoutMs, async () => {
+            await page.mouse.move(0, 0);
+            // Normalize the screenshot to viewport CSS pixels via browser canvas.
+            const viewport = page.viewportSize();
+            if (viewport) {
+                const fullBuf = await page.screenshot({ type: 'png', fullPage: false });
+                const resized = await page.evaluate(async ({ pngBase64, w, h }) => {
+                    const img = new Image();
+                    img.src = `data:image/png;base64,${pngBase64}`;
+                    await new Promise((resolve) => { img.onload = () => resolve(); });
+                    const canvas = document.createElement('canvas');
+                    canvas.width = w;
+                    canvas.height = h;
+                    const ctx = canvas.getContext('2d');
+                    ctx.drawImage(img, 0, 0, w, h);
+                    // Return as JPEG base64 (strip the data:image/jpeg;base64, prefix)
+                    return canvas.toDataURL('image/jpeg', 0.70).split(',')[1];
+                }, { pngBase64: fullBuf.toString('base64'), w: viewport.width, h: viewport.height });
+                return Buffer.from(resized, 'base64');
+            }
+            return Buffer.from(await page.screenshot({ type: 'jpeg', quality: 70, fullPage: false }));
+        });
+    }
+    async getAccessibilityTree(options = {}) {
+        const page = this.ensurePage();
+        return withHelperTimeout('getAccessibilityTree', options.timeoutMs, async () => {
+            try {
+                return await page.locator('body').ariaSnapshot();
+            }
+            catch {
+                // Fallback: build a simple text tree from the DOM
+                return await page.evaluate(() => {
+                    function walk(node, depth) {
+                        const role = node.getAttribute('role') || node.tagName.toLowerCase();
+                        const text = (node.textContent || '').trim().slice(0, 60);
+                        const indent = '  '.repeat(depth);
+                        let result = `${indent}${role}`;
+                        if (text && node.children.length === 0) {
+                            result += `: "${text}"`;
+                        }
+                        result += '\n';
+                        for (const child of Array.from(node.children)) {
+                            result += walk(child, depth + 1);
+                        }
+                        return result;
+                    }
+                    return walk(document.body, 0);
+                });
+            }
+        });
+    }
+    async getInteractiveElements(options = {}) {
+        const page = this.ensurePage();
+        const elements = await withHelperTimeout('getInteractiveElements', options.timeoutMs, () => page.evaluate(() => {
+            document
+                .querySelectorAll('[data-ak-interactive-index]')
+                .forEach(el => el.removeAttribute('data-ak-interactive-index'));
+            const INTERACTIVE_SELECTORS = [
+                'a[href]', 'button', 'input', 'select', 'textarea', 'summary',
+                '[role="button"]', '[role="link"]', '[role="tab"]',
+                '[role="menuitem"]', '[role="menuitemcheckbox"]', '[role="menuitemradio"]',
+                '[role="checkbox"]', '[role="radio"]',
+                '[role="switch"]', '[role="combobox"]', '[role="option"]',
+                '[role="slider"]', '[role="spinbutton"]', '[role="listbox"]',
+                '[role="treeitem"]', '[role="gridcell"]',
+                '[tabindex]:not([tabindex="-1"])', '[onclick]',
+                '[contenteditable="true"]',
+                '[aria-haspopup]',
+                'label[for]',
+                // Bootstrap / common framework toggles
+                '[data-toggle]', '[data-bs-toggle]',
+                // Language/theme selectors are often custom elements
+                '[data-lang]', '[data-language]', '[data-locale]',
+                '[hreflang]',
+            ];
+            const allElements = document.querySelectorAll(INTERACTIVE_SELECTORS.join(','));
+            // Also find implicitly clickable elements — covers icon buttons, React/Vue
+            // components with JS event listeners, and other non-semantic interactive elements.
+            const clickableElements = new Set();
+            const SKIP_TAGS = new Set(['A', 'BUTTON', 'INPUT', 'SELECT', 'TEXTAREA', 'HTML', 'BODY']);
+            const candidateSelectors = 'div, span, li, label, p, img, svg, i, em, strong, figure, figcaption, nav > *, header > *, footer > *, section > *, article > *, main > *, aside > *';
+            const candidates = document.body.querySelectorAll(candidateSelectors);
+            for (const el of candidates) {
+                if (SKIP_TAGS.has(el.tagName))
+                    continue;
+                const rect = el.getBoundingClientRect();
+                if (rect.width === 0 || rect.height === 0)
+                    continue;
+                if (rect.width > 800 && rect.height > 600)
+                    continue;
+                const style = window.getComputedStyle(el);
+                if (style.display === 'none' || style.visibility === 'hidden')
+                    continue;
+                const isClickable = 
+                // Standard cursor:pointer detection
+                style.cursor === 'pointer'
+                    // React/framework patterns: data-* attributes that suggest interactivity
+                    || el.hasAttribute('data-state')
+                    || el.hasAttribute('data-radix-collection-item')
+                    || el.hasAttribute('data-slot')
+                    // Inline event handlers (beyond [onclick] already covered above)
+                    || el.hasAttribute('onmousedown')
+                    || el.hasAttribute('onpointerdown')
+                    || el.hasAttribute('ontouchstart')
+                    // Elements with tabindex that might have been missed
+                    || (el.tabIndex >= 0 && el.tagName !== 'DIV')
+                    // Small icon-like elements (SVG icons, font icons) inside interactive contexts
+                    || (rect.width <= 48 && rect.height <= 48 && (el.closest('button, [role="button"], a[href]') !== null
+                        || style.cursor === 'pointer'
+                        || el.hasAttribute('title')));
+                if (isClickable) {
+                    // For small icons inside buttons, prefer the parent button
+                    const parentButton = el.closest('button, [role="button"]');
+                    if (parentButton && parentButton !== el) {
+                        clickableElements.add(parentButton);
+                    }
+                    else {
+                        clickableElements.add(el);
+                    }
+                }
+            }
+            // Merge both sets (avoid duplicates)
+            const combined = new Set(allElements);
+            for (const el of clickableElements)
+                combined.add(el);
+            // Viewport dimensions for visibility check
+            const vw = window.innerWidth;
+            const vh = window.innerHeight;
+            const scrollX = window.scrollX;
+            const scrollY = window.scrollY;
+            // Helper: get the direct/own text of an element (not its children's text)
+            function getOwnText(el) {
+                let text = '';
+                for (const child of el.childNodes) {
+                    if (child.nodeType === Node.TEXT_NODE) {
+                        text += (child.textContent || '').trim() + ' ';
+                    }
+                }
+                return text.trim();
+            }
+            // Helper: get the shallow text (own text + immediate child text, not deep)
+            function getShallowText(el) {
+                const own = getOwnText(el);
+                if (own)
+                    return own;
+                // If no own text, get text from direct children only (1 level deep)
+                let childText = '';
+                for (const child of el.children) {
+                    const ct = getOwnText(child);
+                    if (ct)
+                        childText += ct + ' ';
+                }
+                return childText.trim();
+            }
+            const quoteForSelector = (value) => value
+                .replace(/\\/g, '\\\\')
+                .replace(/"/g, '\\"');
+            const isUniqueSelector = (selector, expected) => {
+                try {
+                    const matches = document.querySelectorAll(selector);
+                    return matches.length === 1 && matches[0] === expected;
+                }
+                catch {
+                    return false;
+                }
+            };
+            const buildStableCssSelector = (node) => {
+                const tag = node.tagName.toLowerCase();
+                const candidates = [];
+                const push = (selector) => {
+                    if (selector && !candidates.includes(selector)) {
+                        candidates.push(selector);
+                    }
+                };
+                const role = node.getAttribute('role');
+                const type = node.getAttribute('type');
+                const id = node.getAttribute('id');
+                if (id) {
+                    push(`#${CSS.escape(id)}`);
+                }
+                for (const attr of ['data-testid', 'data-test', 'data-qa', 'data-cy']) {
+                    const value = node.getAttribute(attr);
+                    if (!value)
+                        continue;
+                    push(`[${attr}="${quoteForSelector(value)}"]`);
+                    push(`${tag}[${attr}="${quoteForSelector(value)}"]`);
+                }
+                const name = node.getAttribute('name');
+                if (name) {
+                    push(`${tag}[name="${quoteForSelector(name)}"]`);
+                    if (type) {
+                        push(`${tag}[name="${quoteForSelector(name)}"][type="${quoteForSelector(type)}"]`);
+                    }
+                }
+                const rawHref = node.getAttribute('href');
+                if (tag === 'a' && rawHref) {
+                    push(`a[href="${quoteForSelector(rawHref)}"]`);
+                    const hreflang = node.getAttribute('hreflang');
+                    if (hreflang) {
+                        push(`a[href="${quoteForSelector(rawHref)}"][hreflang="${quoteForSelector(hreflang)}"]`);
+                    }
+                }
+                for (const attr of ['aria-label', 'title', 'placeholder', 'data-lang', 'data-language', 'data-locale', 'data-theme', 'data-color-scheme', 'hreflang']) {
+                    const value = node.getAttribute(attr);
+                    if (!value)
+                        continue;
+                    push(`${tag}[${attr}="${quoteForSelector(value)}"]`);
+                    if (role) {
+                        push(`${tag}[role="${quoteForSelector(role)}"][${attr}="${quoteForSelector(value)}"]`);
+                    }
+                    if (type) {
+                        push(`${tag}[type="${quoteForSelector(type)}"][${attr}="${quoteForSelector(value)}"]`);
+                    }
+                }
+                if (type) {
+                    push(`${tag}[type="${quoteForSelector(type)}"]`);
+                }
+                for (const selector of candidates) {
+                    if (isUniqueSelector(selector, node)) {
+                        return selector;
+                    }
+                }
+                return null;
+            };
+            const results = [];
+            for (const el of combined) {
+                const htmlEl = el;
+                // Skip hidden elements (but allow fixed-position elements which may have null offsetParent)
+                const style = window.getComputedStyle(htmlEl);
+                const isFixed = style.position === 'fixed' || style.position === 'sticky';
+                if (!isFixed && htmlEl.offsetParent === null && htmlEl.tagName !== 'BODY')
+                    continue;
+                if (style.display === 'none' || style.visibility === 'hidden')
+                    continue;
+                if (parseFloat(style.opacity) === 0)
+                    continue;
+                const rect = htmlEl.getBoundingClientRect();
+                // Skip elements with no size
+                if (rect.width === 0 && rect.height === 0)
+                    continue;
+                // Skip extremely large container elements that happen to have cursor:pointer
+                if (rect.width > vw * 0.9 && rect.height > vh * 0.9)
+                    continue;
+                // Check if element is in viewport
+                const visibleWidth = Math.max(0, Math.min(rect.right, vw) - Math.max(rect.left, 0));
+                const visibleHeight = Math.max(0, Math.min(rect.bottom, vh) - Math.max(rect.top, 0));
+                const inViewport = visibleWidth > 0 && visibleHeight > 0;
+                const fullyVisible = rect.top >= 0 && rect.left >= 0 && rect.bottom <= vh && rect.right <= vw;
+                const visibilityState = !inViewport ? 'offscreen' : fullyVisible ? 'full' : 'partial';
+                const elementIndex = results.length;
+                htmlEl.setAttribute('data-ak-interactive-index', String(elementIndex));
+                const selector = buildStableCssSelector(htmlEl) ?? `[data-ak-interactive-index="${elementIndex}"]`;
+                // Get text content — prefer shallow/own text to avoid parent element pollution
+                let text = '';
+                if (htmlEl.tagName === 'INPUT' || htmlEl.tagName === 'TEXTAREA') {
+                    text = htmlEl.placeholder || htmlEl.value || '';
+                }
+                else {
+                    // Use shallow text first (more specific), fall back to full textContent
+                    text = getShallowText(htmlEl);
+                    if (!text) {
+                        text = (htmlEl.textContent || '').trim();
+                    }
+                }
+                // For empty-text elements, try multiple fallbacks (common for icon buttons)
+                if (!text) {
+                    text = htmlEl.getAttribute('title')
+                        || htmlEl.getAttribute('aria-label')
+                        // Check child SVG title element (common pattern: <button><svg><title>Edit</title></svg></button>)
+                        || htmlEl.querySelector('svg > title')?.textContent?.trim()
+                        // Check child img alt
+                        || htmlEl.querySelector('img')?.getAttribute('alt')
+                        // Check aria-labelledby reference
+                        || (() => {
+                            const labelledBy = htmlEl.getAttribute('aria-labelledby');
+                            if (labelledBy) {
+                                const labelEl = document.getElementById(labelledBy);
+                                if (labelEl)
+                                    return labelEl.textContent?.trim() || '';
+                            }
+                            return '';
+                        })()
+                        || '';
+                }
+                text = text.slice(0, 80);
+                // Get role
+                const role = htmlEl.getAttribute('role')
+                    || (htmlEl.tagName === 'A' ? 'link' : '')
+                    || (htmlEl.tagName === 'BUTTON' ? 'button' : '')
+                    || (htmlEl.tagName === 'INPUT' ? `input[${htmlEl.type}]` : '')
+                    || htmlEl.tagName.toLowerCase();
+                // Get href for links
+                const href = htmlEl.tagName === 'A' ? htmlEl.href : null;
+                // Get input type
+                const inputType = (htmlEl.tagName === 'INPUT' || htmlEl.tagName === 'SELECT' || htmlEl.tagName === 'TEXTAREA')
+                    ? htmlEl.type || htmlEl.tagName.toLowerCase()
+                    : null;
+                const titleAttr = htmlEl.getAttribute('title') || null;
+                results.push({
+                    tag: htmlEl.tagName.toLowerCase(),
+                    role,
+                    text,
+                    ariaLabel: htmlEl.getAttribute('aria-label'),
+                    title: titleAttr,
+                    ariaControls: htmlEl.getAttribute('aria-controls'),
+                    ariaExpanded: htmlEl.getAttribute('aria-expanded'),
+                    ariaHasPopup: htmlEl.getAttribute('aria-haspopup'),
+                    href,
+                    inputType,
+                    boundingBox: {
+                        x: Math.round(rect.x),
+                        y: Math.round(rect.y),
+                        width: Math.round(rect.width),
+                        height: Math.round(rect.height),
+                    },
+                    pageBox: {
+                        x: Math.round(rect.x + scrollX),
+                        y: Math.round(rect.y + scrollY),
+                        width: Math.round(rect.width),
+                        height: Math.round(rect.height),
+                    },
+                    selector,
+                    visible: inViewport,
+                    visibilityState,
+                });
+            }
+            return results;
+        }));
+        // Capture scroll position at the time elements were observed
+        const scrollPos = await page.evaluate(() => ({
+            x: window.scrollX,
+            y: window.scrollY,
+        }));
+        // Assign indices and store mapping (including scroll position for reliable screenshots)
+        this.elementMap.clear();
+        return elements.map((el, i) => {
+            this.elementMap.set(i, {
+                selector: el.selector,
+                boundingBox: el.boundingBox,
+                pageBox: el.pageBox,
+                scrollPos,
+                tag: el.tag,
+                text: el.text,
+                ariaLabel: el.ariaLabel,
+                role: el.role,
+                inputType: el.inputType,
+            });
+            const { pageBox: _pageBox, ...publicElement } = el;
+            return { index: i, ...publicElement };
+        });
+    }
+    /**
+     * Extract a simplified DOM representation of the page.
+     * Strips scripts, styles, SVGs, class/style attributes, and collapses empty containers.
+     * Returns clean indented HTML-like text, budget-capped at ~4000 chars.
+     */
+    async getSimplifiedDOM() {
+        const page = this.ensurePage();
+        try {
+            return await page.evaluate(() => {
+                const SKIP_TAGS = new Set(['STYLE', 'SCRIPT', 'SVG', 'NOSCRIPT', 'LINK', 'META', 'BR', 'HR', 'IFRAME', 'CANVAS', 'VIDEO', 'AUDIO', 'SOURCE', 'PICTURE', 'TEMPLATE']);
+                const KEEP_ATTRS = new Set(['id', 'role', 'aria-label', 'aria-expanded', 'aria-haspopup', 'aria-controls', 'aria-selected', 'aria-checked', 'aria-disabled', 'href', 'type', 'name', 'placeholder', 'alt', 'title', 'value', 'for', 'action', 'method', 'data-testid']);
+                const MAX_CHARS = 4000;
+                let output = '';
+                let stopped = false;
+                function append(text) {
+                    if (stopped)
+                        return;
+                    if (output.length + text.length > MAX_CHARS) {
+                        output += text.slice(0, MAX_CHARS - output.length);
+                        output += '\n... (truncated)';
+                        stopped = true;
+                        return;
+                    }
+                    output += text;
+                }
+                function getDirectText(node) {
+                    let text = '';
+                    for (const child of node.childNodes) {
+                        if (child.nodeType === 3) { // TEXT_NODE
+                            const t = (child.textContent || '').trim();
+                            if (t)
+                                text += (text ? ' ' : '') + t;
+                        }
+                    }
+                    return text.slice(0, 80);
+                }
+                function walk(node, depth) {
+                    if (stopped)
+                        return;
+                    if (node.nodeType === 8)
+                        return; // COMMENT_NODE
+                    const tag = node.tagName;
+                    if (!tag)
+                        return;
+                    if (SKIP_TAGS.has(tag))
+                        return;
+                    // Collect kept attributes
+                    const attrs = [];
+                    for (const attr of node.attributes) {
+                        if (KEEP_ATTRS.has(attr.name)) {
+                            let val = attr.value.trim();
+                            if (val.length > 80)
+                                val = val.slice(0, 77) + '...';
+                            if (val)
+                                attrs.push(`${attr.name}="${val}"`);
+                        }
+                    }
+                    const directText = getDirectText(node);
+                    const childElements = Array.from(node.children).filter(c => c.nodeType === 1 && !SKIP_TAGS.has(c.tagName));
+                    // Collapse empty containers (no text, no meaningful children)
+                    if (!directText && childElements.length === 0 && attrs.length === 0)
+                        return;
+                    const indent = '  '.repeat(Math.min(depth, 10));
+                    const tagLower = tag.toLowerCase();
+                    const attrStr = attrs.length > 0 ? ' ' + attrs.join(' ') : '';
+                    if (childElements.length === 0) {
+                        // Leaf node — inline
+                        if (directText) {
+                            append(`${indent}<${tagLower}${attrStr}>${directText}</${tagLower}>\n`);
+                        }
+                        else if (attrStr) {
+                            append(`${indent}<${tagLower}${attrStr} />\n`);
+                        }
+                    }
+                    else {
+                        // Container with children
+                        if (directText) {
+                            append(`${indent}<${tagLower}${attrStr}>${directText}\n`);
+                        }
+                        else {
+                            append(`${indent}<${tagLower}${attrStr}>\n`);
+                        }
+                        for (const child of childElements) {
+                            walk(child, depth + 1);
+                        }
+                        append(`${indent}</${tagLower}>\n`);
+                    }
+                }
+                // Start from body, skip head
+                const body = document.body;
+                if (body) {
+                    // Include title
+                    const title = document.title;
+                    if (title)
+                        append(`<title>${title.slice(0, 100)}</title>\n`);
+                    walk(body, 0);
+                }
+                return output;
+            });
+        }
+        catch (err) {
+            return ''; // Fallback: empty DOM, accessibility tree still available
+        }
+    }
+    async getPageState(opts) {
+        const page = this.ensurePage();
+        const [cleanScreenshot, accessibilityTree, interactiveElements, scrollInfo, simplifiedDOM] = await Promise.all([
+            this.takeScreenshotForAI(),
+            this.getAccessibilityTree(),
+            this.getInteractiveElements(),
+            page.evaluate(() => ({
+                scrollY: Math.round(window.scrollY),
+                scrollHeight: document.documentElement.scrollHeight,
+                viewportHeight: window.innerHeight,
+            })),
+            this.getSimplifiedDOM(),
+        ]);
+        const annotatedScreenshot = opts?.skipAnnotation
+            ? cleanScreenshot
+            : await annotateWithSetOfMarks(cleanScreenshot, interactiveElements);
+        return {
+            cleanScreenshot,
+            screenshot: annotatedScreenshot,
+            accessibilityTree,
+            interactiveElements,
+            simplifiedDOM,
+            scrollInfo,
+        };
+    }
+    /** Lightweight page state without screenshots — skips takeScreenshotForAI + SoM annotation. */
+    async getPageStateLite() {
+        const page = this.ensurePage();
+        const [accessibilityTree, interactiveElements, scrollInfo, simplifiedDOM] = await Promise.all([
+            this.getAccessibilityTree(),
+            this.getInteractiveElements(),
+            page.evaluate(() => ({
+                scrollY: Math.round(window.scrollY),
+                scrollHeight: document.documentElement.scrollHeight,
+                viewportHeight: window.innerHeight,
+            })),
+            this.getSimplifiedDOM(),
+        ]);
+        return { accessibilityTree, interactiveElements, simplifiedDOM, scrollInfo };
+    }
+    async exportStorageState() {
+        const context = this.ensureContext();
+        return context.storageState();
+    }
+    async exportSessionStorage() {
+        const page = this.ensurePage();
+        const snapshot = await page.evaluate(() => {
+            const entries = {};
+            for (let index = 0; index < window.sessionStorage.length; index += 1) {
+                const key = window.sessionStorage.key(index);
+                if (!key)
+                    continue;
+                entries[key] = window.sessionStorage.getItem(key) ?? '';
+            }
+            return {
+                origin: window.location.origin,
+                entries,
+            };
+        });
+        if (!snapshot.origin || Object.keys(snapshot.entries).length === 0) {
+            return {};
+        }
+        return {
+            [snapshot.origin]: snapshot.entries,
+        };
+    }
+    async prepareSessionStorage(bundle, options = {}) {
+        if (!bundle || Object.keys(bundle).length === 0)
+            return;
+        const context = this.ensureContext();
+        const page = this.ensurePage();
+        await context.addInitScript(({ storageByOrigin, replace }) => {
+            try {
+                const entries = storageByOrigin[window.location.origin];
+                if (!entries)
+                    return;
+                if (replace)
+                    window.sessionStorage.clear();
+                for (const [key, value] of Object.entries(entries)) {
+                    window.sessionStorage.setItem(key, String(value));
+                }
+            }
+            catch {
+                // Ignore storage restoration issues on restricted pages.
+            }
+        }, { storageByOrigin: bundle, replace: options.replace ?? false });
+        await page.evaluate(({ storageByOrigin, replace }) => {
+            try {
+                const entries = storageByOrigin[window.location.origin];
+                if (!entries)
+                    return;
+                if (replace)
+                    window.sessionStorage.clear();
+                for (const [key, value] of Object.entries(entries)) {
+                    window.sessionStorage.setItem(key, String(value));
+                }
+            }
+            catch {
+                // Ignore storage restoration issues on restricted pages.
+            }
+        }, { storageByOrigin: bundle, replace: options.replace ?? false }).catch(() => {
+            // The current page may not yet be navigated to the target origin.
+        });
+    }
+    async capturePageSignals(options = {}) {
+        const page = this.ensurePage();
+        return withHelperTimeout('capturePageSignals', options.timeoutMs, () => page.evaluate(() => {
+            const dedupe = (values, limit = 12) => {
+                const seen = new Set();
+                const result = [];
+                for (const raw of values) {
+                    const value = (raw || '').replace(/\s+/g, ' ').trim();
+                    if (!value)
+                        continue;
+                    const key = value.toLowerCase();
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    result.push(value);
+                    if (result.length >= limit)
+                        break;
+                }
+                return result;
+            };
+            const dedupeObjects = (values, makeKey, limit = 12) => {
+                const seen = new Set();
+                const result = [];
+                for (const value of values) {
+                    const key = makeKey(value);
+                    if (!key || seen.has(key))
+                        continue;
+                    seen.add(key);
+                    result.push(value);
+                    if (result.length >= limit)
+                        break;
+                }
+                return result;
+            };
+            const isVisible = (node) => {
+                if (!(node instanceof HTMLElement))
+                    return false;
+                const style = window.getComputedStyle(node);
+                if (style.display === 'none' || style.visibility === 'hidden' || parseFloat(style.opacity || '1') === 0) {
+                    return false;
+                }
+                const rect = node.getBoundingClientRect();
+                return rect.width > 0 && rect.height > 0;
+            };
+            const textFor = (node) => {
+                if (!(node instanceof HTMLElement))
+                    return '';
+                const aria = node.getAttribute('aria-label') || node.getAttribute('title') || '';
+                const text = (node.innerText || node.textContent || '').replace(/\s+/g, ' ').trim();
+                return (text || aria).slice(0, 120);
+            };
+            const quoteForSelector = (value) => value
+                .replace(/\\/g, '\\\\')
+                .replace(/"/g, '\\"');
+            const buildSelector = (node) => {
+                if (!(node instanceof HTMLElement))
+                    return '';
+                const tag = node.tagName.toLowerCase();
+                const id = node.getAttribute('id');
+                if (id)
+                    return `#${CSS.escape(id)}`;
+                for (const attr of ['data-testid', 'data-test', 'data-qa', 'data-cy']) {
+                    const value = node.getAttribute(attr);
+                    if (value)
+                        return `[${attr}="${quoteForSelector(value)}"]`;
+                }
+                for (const attr of ['name', 'aria-label', 'data-lang', 'data-language', 'data-locale', 'data-theme', 'data-color-scheme', 'hreflang']) {
+                    const value = node.getAttribute(attr);
+                    if (value)
+                        return `${tag}[${attr}="${quoteForSelector(value)}"]`;
+                }
+                if (node instanceof HTMLAnchorElement) {
+                    const href = node.getAttribute('href');
+                    if (href)
+                        return `a[href*="${quoteForSelector(href.slice(0, 80))}"]`;
+                }
+                const text = textFor(node).slice(0, 60);
+                if (text) {
+                    if (tag === 'button' || tag === 'a' || node.getAttribute('role')) {
+                        return `${tag}:has-text("${quoteForSelector(text)}")`;
+                    }
+                    return `${tag}:has-text("${quoteForSelector(text)}")`;
+                }
+                return tag;
+            };
+            const LOCALE_HINT_RE = /\b(lang|locale|language|idioma|sprache|langue|lingua|english|fran[cç]ais|deutsch|espa[nñ]ol|italiano|portugu[eê]s|nederlands|polski|svenska|dansk|suomi|norsk|japanese|japonais|中文|日本語)\b/i;
+            const THEME_HINT_RE = /\b(theme|appearance|mode|color[- ]?scheme|dark|light|system|clair|sombre|oscuro|claro|hell|dunkel)\b/i;
+            const STORAGE_LOCALE_RE = /\b(lang|locale|language|i18n|intl|translation|translations)\b/i;
+            const STORAGE_THEME_RE = /\b(theme|appearance|color[-_ ]?scheme|darkmode|dark_mode|mode)\b/i;
+            const LOGIN_BUTTON_RE = /\b(sign[\s-]?in|log[\s-]?in|connexion|se connecter|continue with email|continue|access account|login)\b/i;
+            const LOGOUT_BUTTON_RE = /\b(sign[\s-]?out|log[\s-]?out|d[eé]connexion|se d[eé]connecter|logout)\b/i;
+            const ACCOUNT_MENU_RE = /\b(account|profile|profil|compte|workspace|organization|organisation|team|billing|settings)\b/i;
+            const EMAIL_LIKE_RE = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i;
+            const PERSON_LIKE_RE = /^[A-ZÀ-Ý][A-Za-zÀ-ÿ'’-]{1,20}(?:\s+[A-ZÀ-Ý][A-Za-zÀ-ÿ'’-]{1,20}){1,2}$/;
+            const CORPORATE_SUFFIX_RE = /\b(inc|llc|ltd|corp|gmbh|sas|sarl|company|studio|agency)\b/i;
+            const classifyVariantKind = (combined) => {
+                if (LOCALE_HINT_RE.test(combined))
+                    return 'locale';
+                if (THEME_HINT_RE.test(combined))
+                    return 'theme';
+                return 'unknown';
+            };
+            const classifyStorageKind = (key, value) => {
+                const combined = `${key} ${value}`;
+                if (STORAGE_LOCALE_RE.test(combined))
+                    return 'locale';
+                if (STORAGE_THEME_RE.test(combined))
+                    return 'theme';
+                return 'unknown';
+            };
+            const collectText = (selector, limit = 8) => {
+                return dedupe(Array.from(document.querySelectorAll(selector))
+                    .filter(isVisible)
+                    .map((node) => textFor(node))
+                    .slice(0, limit), limit);
+            };
+            const looksLikeAccountText = (value) => {
+                const normalized = (value || '').replace(/\s+/g, ' ').trim();
+                if (!normalized)
+                    return false;
+                if (LOGIN_BUTTON_RE.test(normalized) || LOGOUT_BUTTON_RE.test(normalized))
+                    return false;
+                if (EMAIL_LIKE_RE.test(normalized))
+                    return true;
+                return PERSON_LIKE_RE.test(normalized) && !CORPORATE_SUFFIX_RE.test(normalized);
+            };
+            const collectActionLabels = (selector, matcher, limit = 8) => dedupe(Array.from(document.querySelectorAll(selector))
+                .filter(isVisible)
+                .map((node) => textFor(node))
+                .filter((text) => matcher.test(text))
+                .slice(0, limit), limit);
+            const body = document.body ?? document.documentElement;
+            const walker = document.createTreeWalker(body, NodeFilter.SHOW_TEXT);
+            let visibleText = '';
+            while (walker.nextNode() && visibleText.length < 800) {
+                const parent = walker.currentNode.parentElement;
+                if (!isVisible(parent))
+                    continue;
+                const nextText = (walker.currentNode.textContent || '').replace(/\s+/g, ' ').trim();
+                if (!nextText)
+                    continue;
+                visibleText += `${visibleText ? ' ' : ''}${nextText}`;
+            }
+            const html = document.documentElement;
+            const canonical = document.querySelector('link[rel="canonical"]')?.getAttribute('href') ?? null;
+            const hreflangs = dedupe(Array.from(document.querySelectorAll('link[rel="alternate"][hreflang]'))
+                .map((node) => `${node.getAttribute('hreflang') || ''}:${node.getAttribute('href') || ''}`), 16);
+            const headingTexts = collectText('h1, h2, h3');
+            const navLabels = collectText('header a, header button, nav a, nav button, [role="navigation"] a, [role="navigation"] button');
+            const breadcrumbLabels = dedupe(Array.from(document.querySelectorAll('nav[aria-label*="breadcrumb" i] a, nav[aria-label*="breadcrumb" i] li, [data-breadcrumb] a, .breadcrumb a, .breadcrumbs a, ol.breadcrumb li, ul.breadcrumb li'))
+                .filter((node) => node instanceof HTMLElement && isVisible(node))
+                .map((node) => textFor(node)), 10);
+            const localeHints = dedupe([
+                html.getAttribute('lang'),
+                ...Array.from(document.querySelectorAll('[hreflang], [lang], [data-lang], [data-locale]'))
+                    .flatMap((node) => [
+                    node.getAttribute('hreflang'),
+                    node.getAttribute('lang'),
+                    node.getAttribute('data-lang'),
+                    node.getAttribute('data-locale'),
+                    textFor(node),
+                ]),
+            ], 20);
+            const themeRootHints = dedupe([
+                html.className || '',
+                document.body?.className || '',
+                html.getAttribute('data-theme') || '',
+                document.body?.getAttribute('data-theme') || '',
+                html.getAttribute('theme') || '',
+                document.body?.getAttribute('theme') || '',
+                html.getAttribute('color-scheme') || '',
+                document.body?.getAttribute('color-scheme') || '',
+                document.querySelector('meta[name="color-scheme"]')?.getAttribute('content') || '',
+            ], 16);
+            const themeRootTokens = themeRootHints.join(' ').toLowerCase();
+            const parseColor = (value) => {
+                if (!value)
+                    return null;
+                const normalized = value.trim().toLowerCase();
+                const rgbMatch = normalized.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*([0-9.]+))?\)/);
+                if (rgbMatch) {
+                    return {
+                        r: Number(rgbMatch[1]),
+                        g: Number(rgbMatch[2]),
+                        b: Number(rgbMatch[3]),
+                        a: rgbMatch[4] ? Number(rgbMatch[4]) : 1,
+                    };
+                }
+                const hexMatch = normalized.match(/^#([0-9a-f]{6}|[0-9a-f]{3})$/i);
+                if (hexMatch) {
+                    const hex = hexMatch[1];
+                    if (hex.length === 3) {
+                        return {
+                            r: Number.parseInt(`${hex[0]}${hex[0]}`, 16),
+                            g: Number.parseInt(`${hex[1]}${hex[1]}`, 16),
+                            b: Number.parseInt(`${hex[2]}${hex[2]}`, 16),
+                            a: 1,
+                        };
+                    }
+                    return {
+                        r: Number.parseInt(hex.slice(0, 2), 16),
+                        g: Number.parseInt(hex.slice(2, 4), 16),
+                        b: Number.parseInt(hex.slice(4, 6), 16),
+                        a: 1,
+                    };
+                }
+                return null;
+            };
+            const luminanceFor = (value) => {
+                const parsed = parseColor(value);
+                if (!parsed || parsed.a === 0)
+                    return null;
+                const normalize = (channel) => {
+                    const srgb = channel / 255;
+                    return srgb <= 0.03928 ? srgb / 12.92 : ((srgb + 0.055) / 1.055) ** 2.4;
+                };
+                const r = normalize(parsed.r);
+                const g = normalize(parsed.g);
+                const b = normalize(parsed.b);
+                return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+            };
+            const chromeThemeSamples = dedupeObjects(['body', 'header', 'nav', 'aside', '[role="navigation"]', '[data-toolbar]', '.toolbar']
+                .flatMap((selector) => Array.from(document.querySelectorAll(selector))
+                .filter(isVisible)
+                .slice(0, selector === 'body' ? 1 : 2)
+                .map((node) => {
+                const style = window.getComputedStyle(node);
+                const area = selector === 'body'
+                    ? 'body'
+                    : selector === 'header'
+                        ? 'header'
+                        : selector === 'nav' || selector === '[role="navigation"]'
+                            ? 'nav'
+                            : selector === 'aside'
+                                ? 'aside'
+                                : 'toolbar';
+                return {
+                    area,
+                    selector,
+                    background: style.backgroundColor || null,
+                    color: style.color || null,
+                    luminance: luminanceFor(style.backgroundColor || null),
+                };
+            })), (sample) => `${sample.area}|${sample.selector}|${sample.background}|${sample.color}`, 10);
+            let detectedTheme = null;
+            const hasDarkToken = /\bdark\b/.test(themeRootTokens);
+            const hasLightToken = /\blight\b/.test(themeRootTokens);
+            const brightChrome = chromeThemeSamples.filter((sample) => sample.luminance !== null && sample.luminance >= 0.58).length;
+            const darkChrome = chromeThemeSamples.filter((sample) => sample.luminance !== null && sample.luminance <= 0.28).length;
+            if (hasDarkToken !== hasLightToken) {
+                const tokenTheme = hasDarkToken ? 'dark' : 'light';
+                if ((tokenTheme === 'dark' && brightChrome === 0)
+                    || (tokenTheme === 'light' && darkChrome === 0)
+                    || chromeThemeSamples.length === 0) {
+                    detectedTheme = tokenTheme;
+                }
+            }
+            else if (brightChrome > 0 && darkChrome === 0) {
+                detectedTheme = 'light';
+            }
+            else if (darkChrome > 0 && brightChrome === 0) {
+                detectedTheme = 'dark';
+            }
+            const preferredColorScheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+            const variantControls = dedupeObjects(Array.from(document.querySelectorAll('select, button, a[href], summary, [role="button"], [role="link"], [role="menuitem"], [role="menuitemradio"], [role="switch"], [role="radio"], [aria-haspopup], [data-lang], [data-language], [data-locale], [data-theme], [data-color-scheme], [theme], [color-scheme]'))
+                .filter(isVisible)
+                .flatMap((node) => {
+                if (!(node instanceof HTMLElement))
+                    return [];
+                const label = textFor(node);
+                const tag = node.tagName.toLowerCase();
+                const role = node.getAttribute('role') || '';
+                const href = node instanceof HTMLAnchorElement ? node.href : node.getAttribute('href');
+                const value = node instanceof HTMLInputElement || node instanceof HTMLSelectElement
+                    ? node.value
+                    : node.getAttribute('value');
+                const attrBag = [
+                    label,
+                    role,
+                    href,
+                    value,
+                    node.getAttribute('aria-label'),
+                    node.getAttribute('title'),
+                    node.getAttribute('name'),
+                    node.getAttribute('id'),
+                    node.getAttribute('data-lang'),
+                    node.getAttribute('data-language'),
+                    node.getAttribute('data-locale'),
+                    node.getAttribute('data-theme'),
+                    node.getAttribute('data-color-scheme'),
+                    node.getAttribute('theme'),
+                    node.getAttribute('color-scheme'),
+                    node.getAttribute('hreflang'),
+                ].filter(Boolean).join(' ');
+                let kind = classifyVariantKind(attrBag);
+                let mechanism = 'custom';
+                let options;
+                if (node instanceof HTMLSelectElement) {
+                    mechanism = 'select';
+                    options = Array.from(node.options)
+                        .map((option) => ({
+                        label: (option.textContent || option.label || '').replace(/\s+/g, ' ').trim().slice(0, 80),
+                        value: option.value || null,
+                        selected: option.selected,
+                    }))
+                        .filter((option) => option.label || option.value)
+                        .slice(0, 16);
+                    if (kind === 'unknown') {
+                        const optionText = options.map((option) => `${option.label} ${option.value || ''}`).join(' ');
+                        kind = classifyVariantKind(`${attrBag} ${optionText}`);
+                    }
+                }
+                else if (tag === 'a' || role === 'link') {
+                    mechanism = 'link';
+                }
+                else if (role === 'switch' || node.getAttribute('aria-pressed') != null || /toggle/i.test(attrBag)) {
+                    mechanism = 'toggle';
+                }
+                else if (role.startsWith('menuitem')) {
+                    mechanism = 'menuitem';
+                }
+                else if (role === 'radio' || node.getAttribute('type') === 'radio') {
+                    mechanism = 'radio';
+                }
+                else {
+                    mechanism = 'button';
+                }
+                const selector = buildSelector(node);
+                if (!selector)
+                    return [];
+                if (kind === 'unknown')
+                    return [];
+                return [{
+                        kind,
+                        mechanism,
+                        selector,
+                        label: label || node.getAttribute('aria-label') || node.getAttribute('title') || selector,
+                        value: value || null,
+                        href: href || null,
+                        tag,
+                        role,
+                        options,
+                    }];
+            }), (control) => `${control.kind}|${control.selector}|${control.label}`, 20);
+            const collectStorageHints = (storage, storageName) => {
+                const hints = [];
+                for (let index = 0; index < storage.length; index += 1) {
+                    const key = storage.key(index);
+                    if (!key)
+                        continue;
+                    const value = storage.getItem(key) || '';
+                    const normalizedValue = value.replace(/\s+/g, ' ').trim().slice(0, 140);
+                    const kind = classifyStorageKind(key, normalizedValue);
+                    if (kind === 'unknown')
+                        continue;
+                    hints.push({
+                        storage: storageName,
+                        key,
+                        kind,
+                        valueSample: normalizedValue,
+                    });
+                }
+                return hints;
+            };
+            const storageHints = dedupeObjects([
+                ...collectStorageHints(window.localStorage, 'localStorage'),
+                ...collectStorageHints(window.sessionStorage, 'sessionStorage'),
+            ], (hint) => `${hint.storage}|${hint.kind}|${hint.key}`, 20);
+            const hasPasswordField = Array.from(document.querySelectorAll('input[type="password"], input[autocomplete="current-password"], input[autocomplete="new-password"]')).some((node) => isVisible(node));
+            const hasEmailField = Array.from(document.querySelectorAll('input[type="email"], input[autocomplete="email"], input[autocomplete="username"], input[name*="email" i], input[id*="email" i]')).some((node) => isVisible(node));
+            const hasAuthForm = Array.from(document.querySelectorAll('form'))
+                .filter(isVisible)
+                .some((form) => {
+                const formText = [
+                    textFor(form),
+                    ...Array.from(form.querySelectorAll('button, a[href], input, [role="button"]'))
+                        .filter(isVisible)
+                        .map((node) => textFor(node)),
+                ].join(' ');
+                const formHasPassword = Array.from(form.querySelectorAll('input[type="password"], input[autocomplete="current-password"], input[autocomplete="new-password"]')).some((node) => isVisible(node));
+                const formHasEmail = Array.from(form.querySelectorAll('input[type="email"], input[autocomplete="email"], input[autocomplete="username"], input[name*="email" i], input[id*="email" i]')).some((node) => isVisible(node));
+                return formHasPassword || (formHasEmail && LOGIN_BUTTON_RE.test(formText));
+            });
+            const loginButtons = collectActionLabels('button, a[href], input[type="submit"], [role="button"], [role="menuitem"]', LOGIN_BUTTON_RE);
+            const logoutButtons = collectActionLabels('button, a[href], input[type="submit"], [role="button"], [role="menuitem"]', LOGOUT_BUTTON_RE);
+            const accountMenuLabels = dedupe(Array.from(document.querySelectorAll('header a, header button, nav a, nav button, aside a, aside button, summary, [aria-haspopup], [role="menuitem"], [data-testid*="account" i], [data-testid*="profile" i]'))
+                .filter(isVisible)
+                .map((node) => textFor(node))
+                .filter((text) => ACCOUNT_MENU_RE.test(text) || looksLikeAccountText(text)), 8);
+            const accountLikeText = dedupe([
+                ...accountMenuLabels.filter((text) => looksLikeAccountText(text)),
+                ...navLabels.filter((text) => looksLikeAccountText(text)),
+                ...breadcrumbLabels.filter((text) => looksLikeAccountText(text)),
+            ], 8);
+            return {
+                url: window.location.href,
+                title: document.title || '',
+                htmlLang: html.getAttribute('lang'),
+                canonicalUrl: canonical,
+                hreflangs,
+                headings: headingTexts,
+                navLabels,
+                breadcrumbLabels,
+                visibleText: visibleText.slice(0, 800),
+                localeHints,
+                detectedTheme,
+                preferredColorScheme,
+                themeRootHints,
+                chromeThemeSamples,
+                authHints: {
+                    hasPasswordField,
+                    hasEmailField,
+                    hasAuthForm,
+                    loginButtons,
+                    logoutButtons,
+                    accountMenuLabels,
+                    accountLikeText,
+                },
+                variantControls,
+                storageHints,
+            };
+        }));
+    }
+    async captureObservation() {
+        const page = this.ensurePage();
+        return page.evaluate(() => {
+            const root = document.body ?? document.documentElement;
+            const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+            let textSample = '';
+            while (walker.nextNode() && textSample.length < 240) {
+                const nextText = (walker.currentNode.textContent || '').replace(/\s+/g, ' ').trim();
+                if (!nextText)
+                    continue;
+                textSample += `${textSample ? ' ' : ''}${nextText}`;
+            }
+            const interactiveSelectors = [
+                'a[href]', 'button', 'input', 'select', 'textarea',
+                '[role="button"]', '[role="link"]', '[role="tab"]',
+                '[role="menuitem"]', '[role="checkbox"]', '[role="radio"]',
+                '[role="switch"]', '[role="combobox"]', '[tabindex]:not([tabindex="-1"])',
+            ];
+            const isVisible = (node) => {
+                if (!(node instanceof HTMLElement))
+                    return false;
+                const style = window.getComputedStyle(node);
+                if (style.display === 'none' || style.visibility === 'hidden' || parseFloat(style.opacity || '1') === 0) {
+                    return false;
+                }
+                const rect = node.getBoundingClientRect();
+                return rect.width > 0 && rect.height > 0;
+            };
+            const dialogCount = Array.from(document.querySelectorAll('dialog[open], [role="dialog"], [aria-modal="true"]')).filter(isVisible).length;
+            const expandedCount = Array.from(document.querySelectorAll('[aria-expanded="true"], details[open]')).filter(isVisible).length;
+            const loadingSelectors = [
+                '[aria-busy="true"]',
+                '[class*="spinner"]', '[class*="loading"]', '[class*="skeleton"]',
+                '[class*="Spinner"]', '[class*="Loading"]', '[class*="Skeleton"]',
+            ];
+            const loadingIndicatorCount = Array.from(document.querySelectorAll(loadingSelectors.join(','))).filter(isVisible).length;
+            return {
+                url: window.location.href,
+                title: document.title || '',
+                readyState: document.readyState,
+                scrollX: Math.round(window.scrollX),
+                scrollY: Math.round(window.scrollY),
+                scrollHeight: document.documentElement.scrollHeight,
+                interactiveCount: Array.from(document.querySelectorAll(interactiveSelectors.join(','))).filter(isVisible).length,
+                dialogCount,
+                expandedCount,
+                loadingIndicatorCount,
+                textSample: textSample.slice(0, 240),
+            };
+        });
+    }
+    async captureVerificationBundle(options = {}) {
+        const page = this.ensurePage();
+        const maxAttempts = Math.max(1, options.maxAttempts ?? 3);
+        const settleMs = Math.max(120, options.settleMs ?? 180);
+        let lastError = null;
+        for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+            // Run networkidle + DOM stability in parallel — they are independent signals
+            await Promise.all([
+                page.waitForLoadState('networkidle', { timeout: 1500 }).catch(() => { }),
+                this.waitForDomStability(page, settleMs, 1800).catch(() => { }),
+            ]);
+            const before = await this.captureObservation();
+            const screenshot = await this.takeScreenshotForAI();
+            const [pageSignals, after] = await Promise.all([
+                this.capturePageSignals(),
+                this.captureObservation(),
+            ]);
+            const sameUrl = before.url === pageSignals.url && pageSignals.url === after.url;
+            const pageReady = before.readyState !== 'loading' && after.readyState !== 'loading';
+            if (sameUrl && pageReady) {
+                const capturedAt = new Date().toISOString();
+                const coherenceKey = createHash('sha1')
+                    .update(`${pageSignals.url}|${after.readyState}|${after.scrollY}|${capturedAt}`)
+                    .digest('hex')
+                    .slice(0, 16);
+                return {
+                    screenshot,
+                    pageSignals,
+                    observation: after,
+                    url: pageSignals.url,
+                    title: pageSignals.title || after.title,
+                    capturedAt,
+                    coherenceKey,
+                };
+            }
+            lastError = new Error(`stale verification snapshot (attempt ${attempt}/${maxAttempts}): `
+                + `url ${before.url} -> ${pageSignals.url} -> ${after.url}; `
+                + `readyState ${before.readyState} -> ${after.readyState}`);
+            if (attempt < maxAttempts) {
+                await page.waitForTimeout(120);
+            }
+        }
+        throw lastError ?? new Error('stale verification snapshot');
+    }
+    async captureVideoVerificationBundle(options = {}) {
+        const page = this.ensurePage();
+        const maxAttempts = Math.max(1, options.maxAttempts ?? 3);
+        const settleMs = Math.max(120, options.settleMs ?? 180);
+        let lastError = null;
+        for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+            // Run networkidle + DOM stability in parallel — they are independent signals
+            await Promise.all([
+                page.waitForLoadState('networkidle', { timeout: 1500 }).catch(() => { }),
+                this.waitForDomStability(page, settleMs, 1800).catch(() => { }),
+            ]);
+            const before = await this.captureObservation();
+            const screenshot = await this.takeScreenshotForAI({ timeoutMs: options.helperTimeoutMs });
+            const [pageSignals, accessibilityTree, interactiveElements, scrollInfo, after] = await Promise.all([
+                this.capturePageSignals({ timeoutMs: options.helperTimeoutMs }),
+                this.getAccessibilityTree({ timeoutMs: options.helperTimeoutMs }),
+                this.getInteractiveElements({ timeoutMs: options.helperTimeoutMs }),
+                page.evaluate(() => ({
+                    scrollY: Math.round(window.scrollY),
+                    scrollHeight: document.documentElement.scrollHeight,
+                    viewportHeight: window.innerHeight,
+                })),
+                this.captureObservation(),
+            ]);
+            const sameUrl = before.url === pageSignals.url && pageSignals.url === after.url;
+            const pageReady = before.readyState !== 'loading' && after.readyState !== 'loading';
+            if (sameUrl && pageReady) {
+                const capturedAt = new Date().toISOString();
+                const coherenceKey = createHash('sha1')
+                    .update(`${pageSignals.url}|${after.readyState}|${after.scrollY}|${capturedAt}`)
+                    .digest('hex')
+                    .slice(0, 16);
+                return {
+                    screenshot,
+                    pageSignals,
+                    observation: after,
+                    accessibilityTree,
+                    interactiveElements,
+                    scrollInfo,
+                    url: pageSignals.url,
+                    title: pageSignals.title || after.title,
+                    capturedAt,
+                    coherenceKey,
+                };
+            }
+            lastError = new Error(`stale verification snapshot (attempt ${attempt}/${maxAttempts}): `
+                + `url ${before.url} -> ${pageSignals.url} -> ${after.url}; `
+                + `readyState ${before.readyState} -> ${after.readyState}`);
+            options.onRetry?.(lastError.message);
+            if (attempt < maxAttempts) {
+                await page.waitForTimeout(120);
+            }
+        }
+        throw lastError ?? new Error('stale verification snapshot');
+    }
+    async waitForPageReaction(before, options = {}) {
+        const page = this.ensurePage();
+        const baseline = before ?? await this.captureObservation();
+        const timeoutMs = Math.max(250, options.timeoutMs ?? 2200);
+        const settleMs = Math.max(150, options.settleMs ?? 350);
+        const deadline = Date.now() + timeoutMs;
+        let last = baseline;
+        let lastMovementAt = Date.now();
+        let observedChange = false;
+        await page.waitForTimeout(100);
+        while (Date.now() < deadline) {
+            const current = await this.captureObservation().catch(() => last);
+            const sinceBaseline = describeObservationChange(baseline, current);
+            const sinceLast = describeObservationChange(last, current);
+            if (sinceBaseline.changed) {
+                observedChange = true;
+            }
+            if (sinceLast.changed || current.readyState !== last.readyState) {
+                last = current;
+                lastMovementAt = Date.now();
+            }
+            const quietForMs = Date.now() - lastMovementAt;
+            const ready = current.readyState !== 'loading';
+            const noChangeGraceMs = Math.max(150, options.idleGraceMs ?? Math.min(settleMs, 250));
+            // Fast settle: when the page is fully stable (complete + no loading indicators + no URL change),
+            // use a reduced settle threshold of 150ms instead of the full settleMs (typically 350ms).
+            const isFullyStable = ready && current.readyState === 'complete'
+                && current.loadingIndicatorCount === 0
+                && current.url === baseline.url;
+            const effectiveSettleMs = (observedChange && isFullyStable) ? Math.min(settleMs, 150) : settleMs;
+            if ((observedChange && quietForMs >= effectiveSettleMs && ready) || (!observedChange && quietForMs >= noChangeGraceMs && ready)) {
+                return describeObservationChange(baseline, current);
+            }
+            if (observedChange && current.url !== baseline.url) {
+                const remaining = deadline - Date.now();
+                if (remaining > 200) {
+                    await page.waitForLoadState('load', { timeout: Math.min(remaining, 900) }).catch(() => { });
+                }
+            }
+            await page.waitForTimeout(120);
+        }
+        const after = await this.captureObservation().catch(() => baseline);
+        return describeObservationChange(baseline, after);
+    }
+    computeVisibilityState(box, viewport) {
+        const visibleWidth = Math.max(0, Math.min(box.x + box.width, viewport.width) - Math.max(box.x, 0));
+        const visibleHeight = Math.max(0, Math.min(box.y + box.height, viewport.height) - Math.max(box.y, 0));
+        if (visibleWidth === 0 || visibleHeight === 0)
+            return 'offscreen';
+        if (box.x >= 0 && box.y >= 0 && box.x + box.width <= viewport.width && box.y + box.height <= viewport.height) {
+            return 'full';
+        }
+        return 'partial';
+    }
+    getVisiblePoint(box, viewport) {
+        const left = Math.max(1, box.x);
+        const right = Math.min(viewport.width - 1, box.x + box.width);
+        const top = Math.max(1, box.y);
+        const bottom = Math.min(viewport.height - 1, box.y + box.height);
+        if (right <= left || bottom <= top) {
+            return {
+                x: Math.max(1, Math.min(viewport.width - 1, Math.round(box.x + box.width / 2))),
+                y: Math.max(1, Math.min(viewport.height - 1, Math.round(box.y + box.height / 2))),
+            };
+        }
+        return {
+            x: Math.round((left + right) / 2),
+            y: Math.round((top + bottom) / 2),
+        };
+    }
+    async withResolvedLocator(element, fn) {
+        const page = this.ensurePage();
+        if (!element.selector)
+            return null;
+        const token = `ak-target-${Math.random().toString(36).slice(2, 10)}`;
+        const matched = await page.evaluate(({ selector, pageBox, token, tag, text, ariaLabel, role, inputType }) => {
+            document.querySelectorAll('[data-ak-target]').forEach(el => el.removeAttribute('data-ak-target'));
+            const matches = Array.from(document.querySelectorAll(selector));
+            if (matches.length === 0)
+                return false;
+            const normalizedText = text.trim().toLowerCase();
+            const normalizedAria = (ariaLabel || '').trim().toLowerCase();
+            const targetCenterX = pageBox ? pageBox.x + pageBox.width / 2 : null;
+            const targetCenterY = pageBox ? pageBox.y + pageBox.height / 2 : null;
+            const scored = matches
+                .map((node) => {
+                const el = node;
+                const rect = el.getBoundingClientRect();
+                if (rect.width === 0 && rect.height === 0)
+                    return null;
+                const absX = rect.x + window.scrollX;
+                const absY = rect.y + window.scrollY;
+                const centerX = absX + rect.width / 2;
+                const centerY = absY + rect.height / 2;
+                const ownText = (el.textContent || '').trim().slice(0, 120).toLowerCase();
+                const ownAria = (el.getAttribute('aria-label') || '').trim().toLowerCase();
+                const ownRole = el.getAttribute('role')
+                    || (el.tagName === 'A' ? 'link' : '')
+                    || (el.tagName === 'BUTTON' ? 'button' : '')
+                    || (el.tagName === 'INPUT' ? `input[${el.type}]` : '')
+                    || el.tagName.toLowerCase();
+                const ownInputType = (el.tagName === 'INPUT' || el.tagName === 'SELECT' || el.tagName === 'TEXTAREA')
+                    ? el.type || el.tagName.toLowerCase()
+                    : null;
+                let score = 0;
+                if (targetCenterX != null && targetCenterY != null) {
+                    score += Math.abs(centerX - targetCenterX) + Math.abs(centerY - targetCenterY);
+                }
+                if (pageBox) {
+                    score += Math.abs(rect.width - pageBox.width) * 1.5;
+                    score += Math.abs(rect.height - pageBox.height) * 1.5;
+                }
+                if (el.tagName.toLowerCase() !== tag)
+                    score += 200;
+                if (ownRole !== role)
+                    score += 120;
+                if ((ownInputType || null) !== (inputType || null))
+                    score += 80;
+                if (normalizedAria && ownAria !== normalizedAria)
+                    score += 120;
+                if (normalizedText) {
+                    if (ownText === normalizedText)
+                        score -= 120;
+                    else if (ownText.includes(normalizedText) || normalizedText.includes(ownText))
+                        score -= 60;
+                    else
+                        score += 160;
+                }
+                return { el, score };
+            })
+                .filter((entry) => entry !== null)
+                .sort((a, b) => a.score - b.score);
+            const best = scored[0]?.el;
+            if (!best)
+                return false;
+            best.setAttribute('data-ak-target', token);
+            return true;
+        }, {
+            selector: element.selector,
+            pageBox: element.pageBox,
+            token,
+            tag: element.tag,
+            text: element.text,
+            ariaLabel: element.ariaLabel,
+            role: element.role,
+            inputType: element.inputType,
+        });
+        if (!matched)
+            return null;
+        try {
+            const locator = page.locator(`[data-ak-target="${token}"]`).first();
+            return await fn(locator);
+        }
+        finally {
+            await page.evaluate((targetToken) => {
+                document
+                    .querySelectorAll(`[data-ak-target="${targetToken}"]`)
+                    .forEach(el => el.removeAttribute('data-ak-target'));
+            }, token).catch(() => { });
+        }
+    }
+    async measureElement(index) {
+        const page = this.ensurePage();
+        const element = this.elementMap.get(index);
+        if (!element)
+            throw new Error(`Element index ${index} not found`);
+        const measuredFromDom = await this.withResolvedLocator(element, async (locator) => {
+            const box = await locator.boundingBox();
+            if (!box)
+                return null;
+            const viewport = page.viewportSize();
+            if (!viewport)
+                return null;
+            const scroll = await page.evaluate(() => ({ x: window.scrollX, y: window.scrollY }));
+            const roundedBox = {
+                x: Math.round(box.x),
+                y: Math.round(box.y),
+                width: Math.round(box.width),
+                height: Math.round(box.height),
+            };
+            return {
+                boundingBox: roundedBox,
+                pageBox: {
+                    x: Math.round(box.x + scroll.x),
+                    y: Math.round(box.y + scroll.y),
+                    width: Math.round(box.width),
+                    height: Math.round(box.height),
+                },
+                visibilityState: this.computeVisibilityState(roundedBox, viewport),
+            };
+        });
+        if (measuredFromDom)
+            return measuredFromDom;
+        if (!element.pageBox)
+            return null;
+        const viewport = page.viewportSize();
+        if (!viewport)
+            return null;
+        const scroll = await page.evaluate(() => ({ x: window.scrollX, y: window.scrollY }));
+        const fallbackBox = {
+            x: Math.round(element.pageBox.x - scroll.x),
+            y: Math.round(element.pageBox.y - scroll.y),
+            width: element.pageBox.width,
+            height: element.pageBox.height,
+        };
+        return {
+            boundingBox: fallbackBox,
+            pageBox: element.pageBox,
+            visibilityState: this.computeVisibilityState(fallbackBox, viewport),
+        };
+    }
+    async ensureElementInView(index, margin = 24) {
+        return this.alignElementInView(index, { align: 'center', margin });
+    }
+    async alignElementInView(index, options = {}) {
+        const page = this.ensurePage();
+        const element = this.elementMap.get(index);
+        if (!element)
+            throw new Error(`Element index ${index} not found`);
+        const align = options.align ?? 'center';
+        const margin = options.margin ?? 24;
+        await this.withResolvedLocator(element, async (locator) => {
+            await locator.scrollIntoViewIfNeeded({ timeout: 5000 });
+        });
+        let measured = await this.measureElement(index);
+        if (!measured)
+            throw new Error(`Could not measure element index ${index}`);
+        const viewport = page.viewportSize();
+        if (!viewport)
+            return measured;
+        const maxScroll = await page.evaluate(() => {
+            const root = document.scrollingElement || document.documentElement;
+            return {
+                x: Math.max(0, root.scrollWidth - window.innerWidth),
+                y: Math.max(0, root.scrollHeight - window.innerHeight),
+            };
+        });
+        const pageBox = measured.pageBox;
+        const computeAxisTarget = (coord, size, viewportSize, maxAxis) => {
+            if (align === 'start') {
+                return Math.max(0, Math.min(Math.round(coord - margin), maxAxis));
+            }
+            if (align === 'end') {
+                return Math.max(0, Math.min(Math.round(coord + size - viewportSize + margin), maxAxis));
+            }
+            const centered = size + margin * 2 <= viewportSize
+                ? coord - Math.max(0, (viewportSize - size) / 2)
+                : coord - margin;
+            return Math.max(0, Math.min(Math.round(centered), maxAxis));
+        };
+        const targetScrollX = computeAxisTarget(pageBox.x, pageBox.width, viewport.width, maxScroll.x);
+        const targetScrollY = computeAxisTarget(pageBox.y, pageBox.height, viewport.height, maxScroll.y);
+        await page.evaluate(({ x, y }) => window.scrollTo(x, y), {
+            x: targetScrollX,
+            y: targetScrollY,
+        });
+        await page.waitForTimeout(250);
+        measured = await this.measureElement(index);
+        if (!measured)
+            throw new Error(`Could not re-measure element index ${index}`);
+        return measured;
+    }
+    async scrollElementIntoView(index, options = {}) {
+        await this.alignElementInView(index, options);
+    }
+    async dismissOverlays() {
+        return dismissCookiesAndWidgets(this.ensurePage());
+    }
+    async hoverByIndex(index) {
+        const page = this.ensurePage();
+        const element = this.elementMap.get(index);
+        if (!element)
+            throw new Error(`Element index ${index} not found`);
+        const measured = await this.ensureElementInView(index, 32);
+        const viewport = page.viewportSize();
+        if (!viewport)
+            throw new Error('Viewport unavailable during hover');
+        const point = this.getVisiblePoint(measured.boundingBox, viewport);
+        await page.mouse.move(point.x, point.y);
+    }
+    async hoverBySelector(selector) {
+        const page = this.ensurePage();
+        await page.hover(selector, { timeout: 5000 });
+    }
+    async hoverByCoordinates(x, y) {
+        const page = this.ensurePage();
+        await page.mouse.move(x, y);
+    }
+    async safeExpand(options) {
+        const page = this.ensurePage();
+        const waitForExpansionSignal = async (locator, stateBefore) => {
+            if (options.expectedSelector) {
+                await page.locator(options.expectedSelector).first().waitFor({ state: 'visible', timeout: 3000 });
+                return;
+            }
+            if (options.expectedText) {
+                await page.getByText(options.expectedText, { exact: false }).first().waitFor({ state: 'visible', timeout: 3000 });
+                return;
+            }
+            if (stateBefore.ariaExpanded !== null) {
+                for (let attempt = 0; attempt < 8; attempt += 1) {
+                    const expanded = await locator.evaluate(el => el.getAttribute('aria-expanded'));
+                    if (expanded === 'true')
+                        return;
+                    await page.waitForTimeout(120);
+                }
+            }
+            if (stateBefore.ariaControls) {
+                await page.waitForFunction((id) => {
+                    const controlled = document.getElementById(id);
+                    if (!controlled)
+                        return false;
+                    const style = window.getComputedStyle(controlled);
+                    const rect = controlled.getBoundingClientRect();
+                    return style.display !== 'none'
+                        && style.visibility !== 'hidden'
+                        && parseFloat(style.opacity || '1') > 0
+                        && rect.width > 0
+                        && rect.height > 0;
+                }, stateBefore.ariaControls, { timeout: 2500 }).catch(() => { });
+                return;
+            }
+            if (stateBefore.detailsOpen) {
+                return;
+            }
+            await page.waitForTimeout(350);
+        };
+        const expandWithLocator = async (locator) => {
+            await locator.waitFor({ state: 'visible', timeout: 5000 });
+            const stateBefore = await locator.evaluate((el) => ({
+                ariaExpanded: el.getAttribute('aria-expanded'),
+                ariaControls: el.getAttribute('aria-controls'),
+                detailsOpen: el.tagName === 'SUMMARY'
+                    ? !!(el.parentElement && el.parentElement.tagName === 'DETAILS' && el.parentElement.open)
+                    : el.open === true,
+            }));
+            if (stateBefore.ariaExpanded === 'true' || stateBefore.detailsOpen) {
+                await waitForExpansionSignal(locator, stateBefore);
+                return;
+            }
+            await locator.click({ timeout: 5000 });
+            await waitForExpansionSignal(locator, stateBefore);
+        };
+        if (options.index !== undefined) {
+            const element = this.elementMap.get(options.index);
+            if (!element)
+                throw new Error(`Element index ${options.index} not found`);
+            await this.ensureElementInView(options.index, 32);
+            const expanded = await this.withResolvedLocator(element, async (locator) => {
+                await expandWithLocator(locator);
+                return true;
+            });
+            if (!expanded) {
+                throw new Error(`Could not resolve expandable element index ${options.index}`);
+            }
+            return;
+        }
+        if (options.selector) {
+            await expandWithLocator(page.locator(options.selector).first());
+            return;
+        }
+        throw new Error('safeExpand requires index or selector');
+    }
+    async clickByIndex(index) {
+        const page = this.ensurePage();
+        const element = this.elementMap.get(index);
+        if (!element)
+            throw new Error(`Element index ${index} not found`);
+        const measured = await this.ensureElementInView(index, 32);
+        const viewport = page.viewportSize();
+        if (!viewport)
+            throw new Error('Viewport unavailable during click');
+        // Prefer coordinate click — it's always precise after re-centering and
+        // avoids ambiguous selectors when multiple elements share the same classes.
+        const point = this.getVisiblePoint(measured.boundingBox, viewport);
+        await page.mouse.click(point.x, point.y);
+    }
+    async clickBySelector(selector, options) {
+        const page = this.ensurePage();
+        await page.click(selector, { timeout: 5000, force: options?.force });
+    }
+    async clickByCoordinates(x, y) {
+        const page = this.ensurePage();
+        await page.mouse.click(x, y);
+    }
+    async typeText(text, options) {
+        const page = this.ensurePage();
+        if (options?.index !== undefined) {
+            const measured = await this.ensureElementInView(options.index, 32);
+            const viewport = page.viewportSize();
+            if (!viewport)
+                throw new Error('Viewport unavailable during typing');
+            const point = this.getVisiblePoint(measured.boundingBox, viewport);
+            await page.mouse.click(point.x, point.y);
+            if (options.clearFirst) {
+                await page.keyboard.press('Control+A');
+            }
+            await page.keyboard.type(text);
+        }
+        else if (options?.selector) {
+            if (options.clearFirst) {
+                await page.fill(options.selector, text);
+            }
+            else {
+                await page.click(options.selector, { timeout: 5000 });
+                await page.keyboard.type(text);
+            }
+        }
+        else {
+            await page.keyboard.type(text);
+        }
+    }
+    async selectOption(options) {
+        const page = this.ensurePage();
+        const option = typeof options.optionLabel === 'string' ? { label: options.optionLabel }
+            : typeof options.optionValue === 'string' ? { value: options.optionValue }
+                : typeof options.optionIndex === 'number' ? { index: options.optionIndex }
+                    : null;
+        if (!option) {
+            throw new Error('selectOption requires optionLabel, optionValue, or optionIndex');
+        }
+        if (options.index !== undefined) {
+            const element = this.elementMap.get(options.index);
+            if (!element)
+                throw new Error(`Element index ${options.index} not found`);
+            await this.ensureElementInView(options.index, 32);
+            const selected = await this.withResolvedLocator(element, async (locator) => {
+                await locator.selectOption(option, { timeout: 5000 });
+                return true;
+            });
+            if (!selected) {
+                throw new Error(`Could not resolve select element index ${options.index}`);
+            }
+            return;
+        }
+        if (options.selector) {
+            const locator = page.locator(options.selector).first();
+            await locator.waitFor({ state: 'visible', timeout: 5000 });
+            await locator.selectOption(option, { timeout: 5000 });
+            return;
+        }
+        throw new Error('selectOption requires index or selector');
+    }
+    async scroll(direction, amount = 500, selector) {
+        const page = this.ensurePage();
+        const dx = direction === 'right' ? amount : direction === 'left' ? -amount : 0;
+        const dy = direction === 'down' ? amount : direction === 'up' ? -amount : 0;
+        if (selector) {
+            await page.evaluate(({ sel, deltaX, deltaY }) => {
+                const el = document.querySelector(sel);
+                if (el)
+                    el.scrollBy(deltaX, deltaY);
+            }, { sel: selector, deltaX: dx, deltaY: dy });
+        }
+        else {
+            await page.evaluate(({ deltaX, deltaY }) => window.scrollBy(deltaX, deltaY), { deltaX: dx, deltaY: dy });
+        }
+    }
+    async pressKey(key) {
+        const page = this.ensurePage();
+        await page.keyboard.press(key);
+    }
+    async searchText(query) {
+        const page = this.ensurePage();
+        return page.evaluate((q) => {
+            const results = [];
+            // Use a page-global counter so data-ak-search-index values are stable across
+            // multiple searchText calls within the same element capture session.
+            const w = window;
+            if (typeof w.__akSearchIndexCounter === 'undefined')
+                w.__akSearchIndexCounter = 0;
+            let searchIndexCounter = w.__akSearchIndexCounter;
+            const lowerQ = q.toLowerCase();
+            const vw = window.innerWidth;
+            const vh = window.innerHeight;
+            // Helper: get direct/own text of an element
+            function getOwnText(el) {
+                let t = '';
+                for (const child of el.childNodes) {
+                    if (child.nodeType === Node.TEXT_NODE) {
+                        t += (child.textContent || '').trim() + ' ';
+                    }
+                }
+                return t.trim();
+            }
+            const quoteForSelector = (value) => value
+                .replace(/\\/g, '\\\\')
+                .replace(/"/g, '\\"');
+            const isUniqueSelector = (selector, expected) => {
+                try {
+                    const matches = document.querySelectorAll(selector);
+                    return matches.length === 1 && matches[0] === expected;
+                }
+                catch {
+                    return false;
+                }
+            };
+            const buildStableCssSelector = (node) => {
+                const tag = node.tagName.toLowerCase();
+                const candidates = [];
+                const push = (selector) => {
+                    if (selector && !candidates.includes(selector)) {
+                        candidates.push(selector);
+                    }
+                };
+                const role = node.getAttribute('role');
+                const type = node.getAttribute('type');
+                const id = node.getAttribute('id');
+                if (id) {
+                    push(`#${CSS.escape(id)}`);
+                }
+                for (const attr of ['data-testid', 'data-test', 'data-qa', 'data-cy']) {
+                    const value = node.getAttribute(attr);
+                    if (!value)
+                        continue;
+                    push(`[${attr}="${quoteForSelector(value)}"]`);
+                    push(`${tag}[${attr}="${quoteForSelector(value)}"]`);
+                }
+                const name = node.getAttribute('name');
+                if (name) {
+                    push(`${tag}[name="${quoteForSelector(name)}"]`);
+                    if (type) {
+                        push(`${tag}[name="${quoteForSelector(name)}"][type="${quoteForSelector(type)}"]`);
+                    }
+                }
+                const rawHref = node.getAttribute('href');
+                if (tag === 'a' && rawHref) {
+                    push(`a[href="${quoteForSelector(rawHref)}"]`);
+                    const hreflang = node.getAttribute('hreflang');
+                    if (hreflang) {
+                        push(`a[href="${quoteForSelector(rawHref)}"][hreflang="${quoteForSelector(hreflang)}"]`);
+                    }
+                }
+                for (const attr of ['aria-label', 'title', 'placeholder', 'data-lang', 'data-language', 'data-locale', 'data-theme', 'data-color-scheme', 'hreflang']) {
+                    const value = node.getAttribute(attr);
+                    if (!value)
+                        continue;
+                    push(`${tag}[${attr}="${quoteForSelector(value)}"]`);
+                    if (role) {
+                        push(`${tag}[role="${quoteForSelector(role)}"][${attr}="${quoteForSelector(value)}"]`);
+                    }
+                    if (type) {
+                        push(`${tag}[type="${quoteForSelector(type)}"][${attr}="${quoteForSelector(value)}"]`);
+                    }
+                }
+                if (type) {
+                    push(`${tag}[type="${quoteForSelector(type)}"]`);
+                }
+                for (const selector of candidates) {
+                    if (isUniqueSelector(selector, node)) {
+                        return selector;
+                    }
+                }
+                return null;
+            };
+            // Walk all elements, find those containing the query text
+            const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_ELEMENT);
+            const seen = new Set();
+            let node = walker.currentNode;
+            while (node) {
+                const el = node;
+                const fullText = (el.textContent || '').trim();
+                const ownText = getOwnText(el);
+                const ariaLabel = el.getAttribute('aria-label') || '';
+                const placeholder = el.placeholder || '';
+                const title = el.getAttribute('title') || '';
+                // Match on the element's OWN text using word-boundary regex (e.g. "pro" should
+                // match the heading <h3>pro</h3> but NOT "The problem" or "3 projects").
+                // Fall back to substring matching on aria/placeholder/title (these are always specific).
+                const escapedQ = q.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                const wordBoundaryRe = new RegExp(`\\b${escapedQ}\\b`, 'i');
+                const matchOwn = wordBoundaryRe.test(ownText) || wordBoundaryRe.test(ariaLabel)
+                    || ariaLabel.toLowerCase().includes(lowerQ)
+                    || placeholder.toLowerCase().includes(lowerQ)
+                    || title.toLowerCase().includes(lowerQ);
+                // For leaf elements (no element children) also allow full-text word-boundary match.
+                const isLeaf = el.children.length === 0;
+                const matchText = matchOwn || (isLeaf && wordBoundaryRe.test(fullText));
+                if (matchText && !seen.has(el)) {
+                    const style = window.getComputedStyle(el);
+                    if (style.display !== 'none' && style.visibility !== 'hidden' && parseFloat(style.opacity) !== 0) {
+                        const rect = el.getBoundingClientRect();
+                        if (rect.width > 0 && rect.height > 0) {
+                            seen.add(el);
+                            // Determine if clickable
+                            const isInteractive = ['A', 'BUTTON', 'INPUT', 'SELECT', 'TEXTAREA'].includes(el.tagName);
+                            const hasRole = ['button', 'link', 'tab', 'menuitem', 'option'].includes(el.getAttribute('role') || '');
+                            const hasCursor = style.cursor === 'pointer';
+                            const hasTabindex = el.hasAttribute('tabindex') && el.getAttribute('tabindex') !== '-1';
+                            const hasOnclick = el.hasAttribute('onclick');
+                            // Display text: prefer own text or aria-label (most specific)
+                            const displayText = ownText || ariaLabel || placeholder || title || fullText;
+                            // Get role
+                            const role = el.getAttribute('role')
+                                || (el.tagName === 'A' ? 'link' : '')
+                                || (el.tagName === 'BUTTON' ? 'button' : '')
+                                || el.tagName.toLowerCase();
+                            // Get href
+                            const href = el.tagName === 'A' ? el.href : null;
+                            const visibleWidth = Math.max(0, Math.min(rect.right, vw) - Math.max(rect.left, 0));
+                            const visibleHeight = Math.max(0, Math.min(rect.bottom, vh) - Math.max(rect.top, 0));
+                            const inViewport = visibleWidth > 0 && visibleHeight > 0;
+                            const fullyVisible = rect.top >= 0 && rect.left >= 0 && rect.bottom <= vh && rect.right <= vw;
+                            const visibilityState = !inViewport ? 'offscreen' : fullyVisible ? 'full' : 'partial';
+                            // Prefer a stable CSS selector; fall back to temporary automation selectors
+                            // only when the DOM does not expose a unique attribute-based handle.
+                            let selector;
+                            const stableSelector = buildStableCssSelector(el);
+                            const existingIdx = el.getAttribute('data-ak-interactive-index');
+                            const existingSearchIdx = el.getAttribute('data-ak-search-index');
+                            if (stableSelector) {
+                                selector = stableSelector;
+                            }
+                            else if (existingIdx !== null) {
+                                selector = `[data-ak-interactive-index="${existingIdx}"]`;
+                            }
+                            else if (existingSearchIdx !== null) {
+                                // Reuse the existing search index from a previous search call
+                                // instead of assigning a new one — keeps selectors stable.
+                                selector = `[data-ak-search-index="${existingSearchIdx}"]`;
+                            }
+                            else {
+                                el.setAttribute('data-ak-search-index', String(searchIndexCounter));
+                                selector = `[data-ak-search-index="${searchIndexCounter}"]`;
+                                searchIndexCounter++;
+                            }
+                            // Find nearest meaningful container (card, list item, section, etc.)
+                            // Walk up the DOM and look for a component-like ancestor.
+                            const SEMANTIC_CONTAINERS = new Set([
+                                'ARTICLE', 'SECTION', 'LI', 'ASIDE', 'DIALOG', 'DETAILS', 'FIGURE', 'FORM', 'NAV',
+                            ]);
+                            const CONTAINER_ROLES = new Set([
+                                'listitem', 'article', 'dialog', 'region', 'group', 'tabpanel', 'card',
+                            ]);
+                            let containerInfo;
+                            let bestContainer = null;
+                            let ancestor = el.parentElement;
+                            const maxWalkUp = 8;
+                            let walkCount = 0;
+                            const viewportArea = Math.max(1, vw * vh);
+                            while (ancestor && ancestor !== document.body && walkCount < maxWalkUp) {
+                                walkCount++;
+                                const ancTag = ancestor.tagName;
+                                const ancRole = ancestor.getAttribute('role') || '';
+                                const ancRect = ancestor.getBoundingClientRect();
+                                // Skip invisible or zero-size ancestors
+                                if (ancRect.width <= 0 || ancRect.height <= 0) {
+                                    ancestor = ancestor.parentElement;
+                                    continue;
+                                }
+                                // A container must be meaningfully larger than the matched element
+                                const areaRatio = (ancRect.width * ancRect.height) / Math.max(1, rect.width * rect.height);
+                                const viewportRatio = (ancRect.width * ancRect.height) / viewportArea;
+                                const ancestorClass = ancestor.className && typeof ancestor.className === 'string'
+                                    ? ancestor.className
+                                    : '';
+                                const looksLikeCardClass = /\b(card|tile|item|row|preset|mockup|template|gallery|capture|thumb|thumbnail)\b/i
+                                    .test(`${ancestor.id || ''} ${ancestorClass}`);
+                                let reason = '';
+                                let score = 0;
+                                if (SEMANTIC_CONTAINERS.has(ancTag)) {
+                                    reason = `semantic <${ancTag.toLowerCase()}>`;
+                                    score += 6;
+                                }
+                                else if (CONTAINER_ROLES.has(ancRole)) {
+                                    reason = `role="${ancRole}"`;
+                                    score += 6;
+                                }
+                                else if (ancestor.id && !/^(root|app|__next)$/i.test(ancestor.id)) {
+                                    reason = `#${ancestor.id}`;
+                                    score += 4;
+                                }
+                                else if (looksLikeCardClass) {
+                                    reason = `class/id match`;
+                                    score += 5;
+                                }
+                                else if (areaRatio >= 3) {
+                                    // Check if this element is a grid/flex child (sibling of similar elements)
+                                    const parentDisplay = ancestor.parentElement
+                                        ? window.getComputedStyle(ancestor.parentElement).display
+                                        : '';
+                                    const isGridFlexChild = parentDisplay.includes('flex') || parentDisplay.includes('grid');
+                                    if (isGridFlexChild && ancestor.parentElement && ancestor.parentElement.children.length >= 2) {
+                                        reason = `flex/grid child (${ancestor.parentElement.children.length} siblings)`;
+                                        score += 5;
+                                    }
+                                }
+                                // Skip giant layout wrappers such as <main> that are usually too broad to be a component crop.
+                                const isLayoutWrapper = /^(MAIN|BODY|HTML)$/i.test(ancTag);
+                                if (isLayoutWrapper && viewportRatio >= 0.75) {
+                                    ancestor = ancestor.parentElement;
+                                    continue;
+                                }
+                                if (reason && areaRatio >= 2) {
+                                    if (viewportRatio <= 0.9)
+                                        score += 2;
+                                    if (areaRatio <= 40)
+                                        score += 2;
+                                    if (walkCount <= 3)
+                                        score += 1;
+                                    score -= Math.max(0, viewportRatio - 0.65) * 8;
+                                    score -= Math.max(0, areaRatio - 60) / 20;
+                                    if (!bestContainer || score > bestContainer.score) {
+                                        bestContainer = {
+                                            ancestor,
+                                            rect: ancRect,
+                                            reason,
+                                            score,
+                                        };
+                                    }
+                                }
+                                ancestor = ancestor.parentElement;
+                            }
+                            if (bestContainer) {
+                                const { ancestor: containerAncestor, rect: containerRect, reason } = bestContainer;
+                                // Prefer a stable CSS selector for the container as well.
+                                let containerSel;
+                                const stableContainerSelector = buildStableCssSelector(containerAncestor);
+                                const existingAkIdx = containerAncestor.getAttribute('data-ak-interactive-index');
+                                const existingSearchIdx = containerAncestor.getAttribute('data-ak-search-index');
+                                const existingContainerIdx = containerAncestor.getAttribute('data-ak-container-index');
+                                if (stableContainerSelector) {
+                                    containerSel = stableContainerSelector;
+                                }
+                                else if (existingAkIdx !== null) {
+                                    containerSel = `[data-ak-interactive-index="${existingAkIdx}"]`;
+                                }
+                                else if (existingSearchIdx !== null) {
+                                    containerSel = `[data-ak-search-index="${existingSearchIdx}"]`;
+                                }
+                                else if (existingContainerIdx !== null) {
+                                    containerSel = `[data-ak-container-index="${existingContainerIdx}"]`;
+                                }
+                                else {
+                                    containerAncestor.setAttribute('data-ak-container-index', String(searchIndexCounter));
+                                    containerSel = `[data-ak-container-index="${searchIndexCounter}"]`;
+                                    searchIndexCounter++;
+                                }
+                                containerInfo = {
+                                    tag: containerAncestor.tagName.toLowerCase(),
+                                    selector: containerSel,
+                                    boundingBox: {
+                                        x: Math.round(containerRect.x),
+                                        y: Math.round(containerRect.y),
+                                        width: Math.round(containerRect.width),
+                                        height: Math.round(containerRect.height),
+                                    },
+                                    reason,
+                                };
+                            }
+                            results.push({
+                                tag: el.tagName.toLowerCase(),
+                                text: displayText.slice(0, 100),
+                                href,
+                                role,
+                                clickable: isInteractive || hasRole || hasCursor || hasTabindex || hasOnclick,
+                                visible: inViewport,
+                                visibilityState,
+                                boundingBox: {
+                                    x: Math.round(rect.x),
+                                    y: Math.round(rect.y),
+                                    width: Math.round(rect.width),
+                                    height: Math.round(rect.height),
+                                },
+                                selector,
+                                container: containerInfo,
+                            });
+                        }
+                    }
+                }
+                node = walker.nextNode();
+            }
+            // Persist the counter so subsequent searchText calls don't reuse the same indices.
+            w.__akSearchIndexCounter = searchIndexCounter;
+            const visibilityRank = (state) => state === 'full' ? 0 : state === 'partial' ? 1 : 2;
+            // Prefer actionable, visible matches before falling back to smaller fuzzy matches.
+            return results
+                .sort((a, b) => {
+                if (a.clickable !== b.clickable)
+                    return a.clickable ? -1 : 1;
+                const visibilityDelta = visibilityRank(a.visibilityState) - visibilityRank(b.visibilityState);
+                if (visibilityDelta !== 0)
+                    return visibilityDelta;
+                return (a.boundingBox.width * a.boundingBox.height) - (b.boundingBox.width * b.boundingBox.height);
+            })
+                .slice(0, 15);
+        }, query);
+    }
+    /** Temporarily hide all fixed/sticky overlays (navbars, banners, FABs, etc.) */
+    async hideFixedOverlays() {
+        const page = this.ensurePage();
+        await page.evaluate(() => {
+            document.querySelectorAll('*').forEach(el => {
+                const pos = getComputedStyle(el).position;
+                if (pos === 'fixed' || pos === 'sticky') {
+                    const h = el;
+                    h.setAttribute('data-ak-vis', h.style.visibility);
+                    h.style.setProperty('visibility', 'hidden', 'important');
+                }
+            });
+        });
+    }
+    /** Restore overlays hidden by hideFixedOverlays */
+    async restoreFixedOverlays() {
+        const page = this.ensurePage();
+        await page.evaluate(() => {
+            document.querySelectorAll('[data-ak-vis]').forEach(el => {
+                const h = el;
+                h.style.visibility = h.getAttribute('data-ak-vis') || '';
+                h.removeAttribute('data-ak-vis');
+            });
+        });
+    }
+    async screenshotElement(index, padding = 0) {
+        const page = this.ensurePage();
+        const element = this.elementMap.get(index);
+        if (!element)
+            throw new Error(`Element index ${index} not found in elementMap`);
+        // Move cursor off-screen to avoid hover artifacts
+        await page.mouse.move(0, 0);
+        // Hide fixed/sticky overlays (navbars, banners) that could cover the element
+        await this.hideFixedOverlays();
+        const originalViewport = page.viewportSize();
+        let resizedForCapture = false;
+        try {
+            let measured = await this.ensureElementInView(index, Math.max(24, padding + 16));
+            let viewport = page.viewportSize();
+            if (viewport && originalViewport) {
+                const requiredWidth = measured.boundingBox.width + padding * 2 + 48;
+                const requiredHeight = measured.boundingBox.height + padding * 2 + 48;
+                const needsResize = requiredWidth > viewport.width || requiredHeight > viewport.height;
+                if (needsResize) {
+                    await page.setViewportSize({
+                        width: Math.max(originalViewport.width, Math.ceil(requiredWidth)),
+                        height: Math.max(originalViewport.height, Math.ceil(requiredHeight)),
+                    });
+                    resizedForCapture = true;
+                    await page.waitForTimeout(250);
+                    measured = await this.ensureElementInView(index, Math.max(24, padding + 16));
+                    viewport = page.viewportSize();
+                }
+            }
+            if (!viewport)
+                throw new Error('Viewport unavailable during element screenshot');
+            const bb = measured.boundingBox;
+            const clip = {
+                x: Math.max(0, bb.x - padding),
+                y: Math.max(0, bb.y - padding),
+                width: Math.max(1, bb.width + padding * 2),
+                height: Math.max(1, bb.height + padding * 2),
+            };
+            clip.width = Math.min(clip.width, viewport.width - clip.x);
+            clip.height = Math.min(clip.height, viewport.height - clip.y);
+            if (clip.width <= 0 || clip.height <= 0) {
+                throw new Error(`Element index ${index} is still outside the viewport after alignment`);
+            }
+            return Buffer.from(await page.screenshot({ type: 'png', clip }));
+        }
+        finally {
+            if (resizedForCapture && originalViewport) {
+                await page.setViewportSize(originalViewport).catch(() => { });
+                await page.waitForTimeout(150).catch(() => { });
+            }
+            await this.restoreFixedOverlays();
+        }
+    }
+    async screenshotRegion(x, y, width, height, padding = 0) {
+        const page = this.ensurePage();
+        // Move cursor off-screen to avoid hover artifacts
+        await page.mouse.move(0, 0);
+        const scroll = await page.evaluate(() => ({ x: window.scrollX, y: window.scrollY }));
+        const deviceScaleFactor = await page.evaluate(() => window.devicePixelRatio || 1);
+        const clip = {
+            x: Math.max(0, Math.round(scroll.x + x - padding)),
+            y: Math.max(0, Math.round(scroll.y + y - padding)),
+            width: Math.max(1, Math.round(width + padding * 2)),
+            height: Math.max(1, Math.round(height + padding * 2)),
+        };
+        // Hide fixed/sticky overlays (navbars, banners) that could cover the region
+        await this.hideFixedOverlays();
+        try {
+            const fullPage = Buffer.from(await page.screenshot({ type: 'png', fullPage: true }));
+            const image = sharp(fullPage);
+            const meta = await image.metadata();
+            const imageWidth = meta.width ?? 0;
+            const imageHeight = meta.height ?? 0;
+            const left = Math.max(0, Math.min(Math.round(clip.x * deviceScaleFactor), Math.max(0, imageWidth - 1)));
+            const top = Math.max(0, Math.min(Math.round(clip.y * deviceScaleFactor), Math.max(0, imageHeight - 1)));
+            const extractWidth = Math.max(1, Math.min(Math.round(clip.width * deviceScaleFactor), Math.max(1, imageWidth - left)));
+            const extractHeight = Math.max(1, Math.min(Math.round(clip.height * deviceScaleFactor), Math.max(1, imageHeight - top)));
+            return await image
+                .extract({ left, top, width: extractWidth, height: extractHeight })
+                .png()
+                .toBuffer();
+        }
+        finally {
+            await this.restoreFixedOverlays();
+        }
+    }
+    async screenshotBySelector(selector, outscale = 0) {
+        const page = this.ensurePage();
+        const config = typeof outscale === 'number' ? { padding: outscale } : outscale;
+        const shouldClamp = config.clampToViewport !== false;
+        // 1. Atomic DOM validation: uniqueness + visibility
+        const domCheck = await page.evaluate((sel) => {
+            const nodes = Array.from(document.querySelectorAll(sel));
+            if (nodes.length !== 1) {
+                return { matchCount: nodes.length, visible: false, boundingBox: null, isFixed: false };
+            }
+            const el = nodes[0];
+            const rect = el.getBoundingClientRect();
+            const style = getComputedStyle(el);
+            const isFixed = style.position === 'fixed' || style.position === 'sticky';
+            const visible = (el.offsetParent !== null || isFixed) && rect.width > 0 && rect.height > 0;
+            return {
+                matchCount: 1,
+                visible,
+                isFixed,
+                boundingBox: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+            };
+        }, selector);
+        if (domCheck.matchCount === 0) {
+            const err = {
+                error: 'no_match',
+                errorMessage: `No element matches selector "${selector}"`,
+            };
+            throw err;
+        }
+        if (domCheck.matchCount > 1) {
+            const err = {
+                error: 'ambiguous',
+                errorMessage: `${domCheck.matchCount} elements match selector "${selector}" — selector must be unique`,
+            };
+            throw err;
+        }
+        if (!domCheck.visible) {
+            const bb = domCheck.boundingBox;
+            const isZeroSize = bb !== null && bb.width === 0 && bb.height === 0;
+            const err = {
+                error: isZeroSize ? 'zero_size' : 'invisible',
+                errorMessage: isZeroSize
+                    ? `Element matches but has zero dimensions (${bb?.width ?? 0}x${bb?.height ?? 0}) — element may be hidden`
+                    : `Element matches but is not visible (offsetParent null and not fixed/sticky) — element may be display:none`,
+            };
+            throw err;
+        }
+        // 2. Scroll element into view and wait for layout to settle
+        const locator = page.locator(selector);
+        if (!domCheck.isFixed) {
+            await locator.scrollIntoViewIfNeeded({ timeout: 5000 });
+            await page.waitForTimeout(200);
+        }
+        // 3. Re-measure post-scroll bounding box (viewport-relative) + scroll position
+        const [rect, pageInfo] = await Promise.all([
+            locator.boundingBox(),
+            page.evaluate(() => ({
+                scrollX: window.scrollX,
+                scrollY: window.scrollY,
+                docWidth: document.documentElement.scrollWidth,
+                docHeight: document.documentElement.scrollHeight,
+                dpr: window.devicePixelRatio || 1,
+                isFixed: false, // already know from domCheck
+            })),
+        ]);
+        if (!rect) {
+            const err = {
+                error: 'invisible',
+                errorMessage: `Element "${selector}" became unavailable after scroll`,
+            };
+            throw err;
+        }
+        // 4. Resolve directional padding
+        const pad = resolveEffectivePadding(config, rect);
+        // 5. Convert viewport-relative bbox to document coordinates and apply padding
+        //    For fixed/sticky elements: don't add scroll offset (already viewport-absolute)
+        const docX = domCheck.isFixed ? rect.x : rect.x + pageInfo.scrollX;
+        const docY = domCheck.isFixed ? rect.y : rect.y + pageInfo.scrollY;
+        let clipDoc = {
+            x: docX - pad.left,
+            y: docY - pad.top,
+            width: rect.width + pad.left + pad.right,
+            height: rect.height + pad.top + pad.bottom,
+        };
+        // 6. Clamp to document bounds
+        if (shouldClamp) {
+            clipDoc.x = Math.max(0, clipDoc.x);
+            clipDoc.y = Math.max(0, clipDoc.y);
+            clipDoc.width = Math.min(clipDoc.width, pageInfo.docWidth - clipDoc.x);
+            clipDoc.height = Math.min(clipDoc.height, pageInfo.docHeight - clipDoc.y);
+        }
+        if (clipDoc.width <= 0 || clipDoc.height <= 0) {
+            const err = {
+                error: 'invisible',
+                errorMessage: `Element "${selector}" capture zone has zero dimensions after clamping`,
+            };
+            throw err;
+        }
+        // 7. Hide overlays, take full-page screenshot, extract clip via sharp
+        await page.mouse.move(0, 0);
+        await this.hideFixedOverlays();
+        try {
+            const dpr = pageInfo.dpr;
+            const fullPage = Buffer.from(await page.screenshot({ type: 'png', fullPage: true }));
+            const image = sharp(fullPage);
+            const meta = await image.metadata();
+            const imgW = meta.width ?? 0;
+            const imgH = meta.height ?? 0;
+            const left = Math.max(0, Math.min(Math.round(clipDoc.x * dpr), Math.max(0, imgW - 1)));
+            const top = Math.max(0, Math.min(Math.round(clipDoc.y * dpr), Math.max(0, imgH - 1)));
+            const extractW = Math.max(1, Math.min(Math.round(clipDoc.width * dpr), Math.max(1, imgW - left)));
+            const extractH = Math.max(1, Math.min(Math.round(clipDoc.height * dpr), Math.max(1, imgH - top)));
+            const buffer = await image
+                .extract({ left, top, width: extractW, height: extractH })
+                .png()
+                .toBuffer();
+            const validation = {
+                matchCount: 1,
+                visible: true,
+                boundingBox: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+            };
+            return { buffer, validation };
+        }
+        finally {
+            await this.restoreFixedOverlays();
+        }
+    }
+    /**
+     * Capture a page region by bounding box coordinates (document-relative).
+     * Used as a fallback when no CSS selector can be resolved for the target element.
+     */
+    async screenshotByRegion(region, outscale = 0) {
+        const page = this.ensurePage();
+        const config = typeof outscale === 'number' ? { padding: outscale } : outscale;
+        const shouldClamp = config.clampToViewport !== false;
+        const pageInfo = await page.evaluate(() => ({
+            scrollX: window.scrollX,
+            scrollY: window.scrollY,
+            docWidth: document.documentElement.scrollWidth,
+            docHeight: document.documentElement.scrollHeight,
+            dpr: window.devicePixelRatio || 1,
+        }));
+        const pad = resolveEffectivePadding(config, region);
+        let clipDoc = {
+            x: region.x - pad.left,
+            y: region.y - pad.top,
+            width: region.width + pad.left + pad.right,
+            height: region.height + pad.top + pad.bottom,
+        };
+        if (shouldClamp) {
+            clipDoc.x = Math.max(0, clipDoc.x);
+            clipDoc.y = Math.max(0, clipDoc.y);
+            clipDoc.width = Math.min(clipDoc.width, pageInfo.docWidth - clipDoc.x);
+            clipDoc.height = Math.min(clipDoc.height, pageInfo.docHeight - clipDoc.y);
+        }
+        if (clipDoc.width <= 0 || clipDoc.height <= 0) {
+            throw new Error(`Region capture zone has zero dimensions after clamping`);
+        }
+        // Scroll region into view
+        await page.evaluate(({ x, y }) => window.scrollTo(x, y - 100), { x: clipDoc.x, y: clipDoc.y });
+        await page.waitForTimeout(200);
+        await page.mouse.move(0, 0);
+        await this.hideFixedOverlays();
+        try {
+            const dpr = pageInfo.dpr;
+            const fullPage = Buffer.from(await page.screenshot({ type: 'png', fullPage: true }));
+            const image = sharp(fullPage);
+            const meta = await image.metadata();
+            const imgW = meta.width ?? 0;
+            const imgH = meta.height ?? 0;
+            const left = Math.max(0, Math.min(Math.round(clipDoc.x * dpr), Math.max(0, imgW - 1)));
+            const top = Math.max(0, Math.min(Math.round(clipDoc.y * dpr), Math.max(0, imgH - 1)));
+            const extractW = Math.max(1, Math.min(Math.round(clipDoc.width * dpr), Math.max(1, imgW - left)));
+            const extractH = Math.max(1, Math.min(Math.round(clipDoc.height * dpr), Math.max(1, imgH - top)));
+            return image
+                .extract({ left, top, width: extractW, height: extractH })
+                .png()
+                .toBuffer();
+        }
+        finally {
+            await this.restoreFixedOverlays();
+        }
+    }
+    async wait(ms) {
+        const page = this.ensurePage();
+        await page.waitForTimeout(Math.min(ms, 5000));
+    }
+    /**
+     * Force-load all lazy-loaded images on the page before element capture.
+     *
+     * 1. Strip loading="lazy" and promote data-src/data-srcset attributes
+     * 2. Scroll through the full page to trigger IntersectionObserver callbacks
+     * 3. Wait for all visible images to finish loading
+     */
+    async forceLoadLazyImages(options) {
+        const page = this.ensurePage();
+        const timeout = options?.timeout ?? 10_000;
+        const startTime = Date.now();
+        // Phase 1: Strip lazy attributes and promote data-src
+        await page.evaluate(() => {
+            for (const el of document.querySelectorAll('img[loading="lazy"], iframe[loading="lazy"]')) {
+                el.removeAttribute('loading');
+                if (el.tagName === 'IMG') {
+                    const img = el;
+                    const src = img.src;
+                    if (src) {
+                        img.src = '';
+                        img.src = src;
+                    }
+                }
+            }
+            for (const img of document.querySelectorAll('img[data-src]')) {
+                const ds = img.getAttribute('data-src');
+                if (!img.src || img.src === '' || img.src === window.location.href)
+                    img.src = ds;
+            }
+            for (const img of document.querySelectorAll('img[data-srcset]')) {
+                const dss = img.getAttribute('data-srcset');
+                if (!img.getAttribute('srcset'))
+                    img.setAttribute('srcset', dss);
+            }
+        });
+        // Phase 2: Scroll sweep to trigger IntersectionObserver callbacks
+        const dims = await page.evaluate(() => ({
+            scrollHeight: document.documentElement.scrollHeight,
+            viewportHeight: window.innerHeight,
+            scrollX: window.scrollX,
+            scrollY: window.scrollY,
+        }));
+        if (dims.scrollHeight > dims.viewportHeight) {
+            const step = Math.floor(dims.viewportHeight * 0.8);
+            let y = 0;
+            while (y < dims.scrollHeight) {
+                if (Date.now() - startTime > timeout * 0.6)
+                    break;
+                await page.evaluate((scrollY) => window.scrollTo(0, scrollY), y);
+                await page.waitForTimeout(150);
+                y += step;
+            }
+            // Scroll to very bottom to catch remaining elements
+            await page.evaluate(() => window.scrollTo(0, document.documentElement.scrollHeight));
+            await page.waitForTimeout(150);
+            // Restore original scroll position
+            await page.evaluate(({ x, y }) => window.scrollTo(x, y), { x: dims.scrollX, y: dims.scrollY });
+        }
+        // Phase 3: Wait for all images to finish loading
+        const remainingMs = Math.max(timeout - (Date.now() - startTime), 2000);
+        try {
+            await page.evaluate((maxWait) => {
+                return new Promise((resolve) => {
+                    const deadline = Date.now() + maxWait;
+                    const check = () => {
+                        const imgs = document.querySelectorAll('img');
+                        for (const img of imgs) {
+                            if (!img.src || img.src.startsWith('data:'))
+                                continue;
+                            if (img.width <= 1 && img.height <= 1)
+                                continue;
+                            if (!img.complete)
+                                return false;
+                        }
+                        return true;
+                    };
+                    if (check()) {
+                        resolve();
+                        return;
+                    }
+                    const iv = setInterval(() => {
+                        if (check() || Date.now() > deadline) {
+                            clearInterval(iv);
+                            resolve();
+                        }
+                    }, 200);
+                });
+            }, remainingMs);
+        }
+        catch {
+            // Timeout — proceed with what we have
+        }
+        await page.waitForTimeout(200);
+    }
+    async setColorScheme(scheme) {
+        const page = this.ensurePage();
+        await page.emulateMedia({ colorScheme: scheme });
+        // Grace period: wait for CSS transitions triggered by theme switch to settle.
+        // Without this, elements may have pointer-events intercepted by the <html> element
+        // during the transition, causing Playwright clicks to timeout.
+        await page.waitForTimeout(600);
+    }
+    async setLanguage(lang) {
+        const context = this.ensureContext();
+        const page = this.ensurePage();
+        await context.setExtraHTTPHeaders({ 'Accept-Language': lang });
+        await page.addInitScript((locale) => {
+            Object.defineProperty(navigator, 'language', { get: () => locale, configurable: true });
+            Object.defineProperty(navigator, 'languages', { get: () => [locale], configurable: true });
+        }, lang);
+    }
+    async resizeViewport(width, height) {
+        const page = this.ensurePage();
+        await page.setViewportSize({
+            width: normalizeViewportDimension(width),
+            height: normalizeViewportDimension(height),
+        });
+    }
+    get currentPage() {
+        return this.ensurePage();
+    }
+    get browserContext() {
+        return this.ensureContext();
+    }
+    /**
+     * Observation pass for mock data generation.
+     * Navigates to the given URL, waits for network idle, and records all JSON API responses.
+     * Auth/analytics/asset endpoints are filtered out automatically.
+     */
+    async observeNetworkRequests(url, waitMs = 2000) {
+        const page = this.ensurePage();
+        const observed = [];
+        const SKIP_PATTERNS = [
+            /\/auth\b/, /\/oauth\b/, /\/token\b/, /\/session\b/,
+            /\/login\b/, /\/logout\b/, /\/refresh\b/, /\/verify\b/,
+            /\/_next\//, /\/analytics\b/, /posthog\./, /sentry\./,
+            /\.(js|css|woff2?|ttf|svg|png|jpg|jpeg|gif|ico|webp)(\?|$)/i,
+            /favicon/i,
+        ];
+        const handler = async (response) => {
+            try {
+                const reqUrl = response.url();
+                if (SKIP_PATTERNS.some((re) => re.test(reqUrl)))
+                    return;
+                const ct = response.headers()['content-type'] ?? '';
+                if (!ct.includes('application/json'))
+                    return;
+                const body = await response.json().catch(() => null);
+                if (body === null)
+                    return;
+                observed.push({
+                    url: reqUrl,
+                    method: response.request().method(),
+                    status: response.status(),
+                    responseBody: body,
+                });
+            }
+            catch {
+                // ignore errors from individual responses
+            }
+        };
+        page.on('response', handler);
+        try {
+            await page.goto(url, { waitUntil: 'networkidle', timeout: 15000 }).catch(() => { });
+            if (waitMs > 0)
+                await page.waitForTimeout(waitMs);
+        }
+        finally {
+            page.off('response', handler);
+        }
+        return observed;
+    }
+    /**
+     * Sets up Playwright route interceptors for each resolved mock.
+     * Must be called before navigating to the page for the actual capture.
+     */
+    async setupRouteInterception(mocks) {
+        const page = this.ensurePage();
+        for (const mock of mocks) {
+            await page.route(mock.urlPattern, (route) => {
+                if (mock.method && route.request().method() !== mock.method) {
+                    return route.continue();
+                }
+                const body = mock.contentType.includes('application/json')
+                    ? JSON.stringify(mock.responseBody)
+                    : typeof mock.responseBody === 'string'
+                        ? mock.responseBody
+                        : JSON.stringify(mock.responseBody);
+                return route.fulfill({
+                    status: mock.status,
+                    contentType: mock.contentType,
+                    body,
+                });
+            });
+        }
+    }
+    /**
+     * Removes all route interceptors set by setupRouteInterception.
+     * Must be called before setting up new mocks to prevent stacking.
+     */
+    async clearRouteInterception() {
+        const page = this.ensurePage();
+        await page.unrouteAll({ behavior: 'wait' });
+    }
+    ensurePage() {
+        if (!this.page)
+            throw new Error('Browser not launched. Call launch() first.');
+        return this.page;
+    }
+    ensureContext() {
+        if (!this.context)
+            throw new Error('Browser not launched. Call launch() first.');
+        return this.context;
+    }
+}
+//# sourceMappingURL=browser.js.map