autokap 1.0.7 → 1.0.10

package/dist/web-playwright-local.js

@@ -0,0 +1,989 @@
+/**
+ * Capture Agent — WebPlaywrightLocal RuntimeAdapter
+ *
+ * Thin adapter delegating to the existing Browser class from src/browser.ts.
+ * This is the first (and for now only) RuntimeAdapter implementation.
+ */
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { humanType, moveMouse } from './mouse-animation.js';
+import { resolveTarget } from './semantic-resolver.js';
+import { logger } from './logger.js';
+import { ClipCaptureLoop } from './clip-capture-loop.js';
+import { assembleMp4FromFrames } from './clip-postprocess.js';
+export class WebPlaywrightLocal {
+    browser;
+    recordingDir;
+    sessionStartedAt = Date.now();
+    recording = null;
+    clipCursor = null;
+    constructor(browser, recordingDir) {
+        this.browser = browser;
+        this.recordingDir = recordingDir;
+    }
+    async navigate(url) {
+        await this.browser.navigateTo(url);
+    }
+    async getCurrentUrl() {
+        const page = await this.browser.currentPage;
+        return page.url();
+    }
+    async getAKTree() {
+        return this.browser.getAKTree();
+    }
+    async getPageSignals() {
+        return this.browser.capturePageSignals();
+    }
+    async click(selector, options) {
+        const page = await this.browser.currentPage;
+        const t0 = Date.now();
+        logger.debug(`[click] start selector="${selector}"${options?.useKeyboard ? ' mode=keyboard' : ''}${options?.useJsDispatch ? ' mode=js_dispatch' : ''}${options?.coordinates ? ` mode=coords(${options.coordinates.x},${options.coordinates.y})` : ''}`);
+        try {
+            if (options?.coordinates) {
+                await this.moveClipCursorToPoint(options.coordinates);
+                await this.browser.clickByCoordinates(options.coordinates.x, options.coordinates.y);
+                logger.debug(`[click] done coords took ${Date.now() - t0}ms`);
+                return;
+            }
+            const locator = page.locator(selector).first();
+            const animatedTarget = await this.moveClipCursorToLocator(locator);
+            if (options?.useKeyboard) {
+                await locator.focus();
+                await page.keyboard.press('Enter');
+                logger.debug(`[click] done keyboard took ${Date.now() - t0}ms`);
+                return;
+            }
+            if (options?.useJsDispatch) {
+                await locator.dispatchEvent('click');
+                logger.debug(`[click] done js_dispatch took ${Date.now() - t0}ms`);
+                return;
+            }
+            // Click at the exact point we animated to (when the overlay is active)
+            // so Playwright doesn't recenter the mouse and produce a last-frame snap.
+            const clickPosition = animatedTarget
+                ? await this.relativeClickPosition(locator, animatedTarget)
+                : null;
+            if (options?.button && options.button !== 'left') {
+                await locator.click({
+                    button: options.button,
+                    timeout: 5000,
+                    force: options?.force,
+                    ...(clickPosition ? { position: clickPosition } : {}),
+                });
+                logger.debug(`[click] done button=${options.button} took ${Date.now() - t0}ms`);
+                return;
+            }
+            if (clickPosition) {
+                await locator.click({
+                    timeout: 5000,
+                    force: options?.force,
+                    position: clickPosition,
+                });
+            }
+            else {
+                await this.browser.clickBySelector(selector, { force: options?.force });
+            }
+            await this.emitClipClickPulse();
+            logger.debug(`[click] done normal took ${Date.now() - t0}ms`);
+        }
+        catch (err) {
+            logger.debug(`[click] FAILED after ${Date.now() - t0}ms — ${err instanceof Error ? err.message : String(err)}`);
+            throw err;
+        }
+    }
+    /**
+     * Click an element using semantic target resolution.
+     * Tries CSS selector first, falls back to Playwright semantic locators.
+     */
+    async clickByTarget(opts) {
+        const page = await this.browser.currentPage;
+        const resolved = await resolveTarget(page, opts);
+        if (!resolved) {
+            throw new Error(`cannot find target: ${describeResolveOptions(opts)}`);
+        }
+        const target = await this.moveClipCursorToLocator(resolved.locator);
+        const position = target
+            ? await this.relativeClickPosition(resolved.locator, target)
+            : null;
+        await resolved.locator.click({
+            timeout: 5000,
+            ...(position ? { position } : {}),
+        });
+    }
+    /**
+     * Type into an element using semantic target resolution.
+     */
+    async typeByTarget(opts, text, clearFirst = true) {
+        const page = await this.browser.currentPage;
+        const resolved = await resolveTarget(page, opts);
+        if (!resolved) {
+            throw new Error(`cannot find target for typing: ${describeResolveOptions(opts)}`);
+        }
+        if (this.clipCursor) {
+            await this.typeIntoLocator(resolved.locator, text, clearFirst);
+            return;
+        }
+        if (clearFirst) {
+            await resolved.locator.fill(text);
+            return;
+        }
+        await resolved.locator.click();
+        await resolved.locator.pressSequentially(text);
+    }
+    /**
+     * Wait for an element using semantic target resolution.
+     */
+    async waitForTarget(opts, timeoutMs = 10000) {
+        const page = await this.browser.currentPage;
+        const resolved = await resolveTarget(page, { ...opts, timeoutMs });
+        return resolved !== null;
+    }
+    /**
+     * Scroll an element into view using semantic target resolution.
+     */
+    async scrollIntoViewByTarget(opts) {
+        const page = await this.browser.currentPage;
+        const resolved = await resolveTarget(page, opts);
+        if (!resolved) {
+            throw new Error(`cannot find target to scroll into view: ${describeResolveOptions(opts)}`);
+        }
+        if (this.clipCursor) {
+            await this.moveClipCursorToViewportCenter();
+            await resolved.locator.evaluate((node) => {
+                node.scrollIntoView({ block: 'center', behavior: 'smooth' });
+            });
+            await page.waitForTimeout(350);
+            return;
+        }
+        await resolved.locator.scrollIntoViewIfNeeded({ timeout: 5000 });
+    }
+    async type(selector, text, clearFirst = true) {
+        if (this.clipCursor) {
+            const page = await this.browser.currentPage;
+            await this.typeIntoLocator(page.locator(selector).first(), text, clearFirst);
+            return;
+        }
+        await this.browser.typeText(text, { selector, clearFirst });
+    }
+    async pressKey(key) {
+        const page = await this.browser.currentPage;
+        if (this.clipCursor) {
+            await page.waitForTimeout(90);
+            await page.keyboard.press(key);
+            return;
+        }
+        await this.browser.pressKey(key);
+    }
+    async scroll(direction, amount) {
+        if (this.clipCursor) {
+            const page = await this.browser.currentPage;
+            await this.moveClipCursorToViewportCenter();
+            const dx = direction === 'right' ? (amount ?? 500) : direction === 'left' ? -(amount ?? 500) : 0;
+            const dy = direction === 'down' ? (amount ?? 500) : direction === 'up' ? -(amount ?? 500) : 0;
+            await page.evaluate(({ deltaX, deltaY }) => {
+                window.scrollBy({ left: deltaX, top: deltaY, behavior: 'smooth' });
+            }, { deltaX: dx, deltaY: dy });
+            await page.waitForTimeout(420);
+            return;
+        }
+        await this.browser.scroll(direction, amount);
+    }
+    async scrollIntoView(selector) {
+        const page = await this.browser.currentPage;
+        if (this.clipCursor) {
+            await this.moveClipCursorToViewportCenter();
+            await page.locator(selector).first().evaluate((node) => {
+                node.scrollIntoView({ block: 'center', behavior: 'smooth' });
+            });
+            await page.waitForTimeout(350);
+            return;
+        }
+        await page.locator(selector).first().scrollIntoViewIfNeeded({ timeout: 5000 });
+    }
+    async waitFor(condition) {
+        try {
+            const page = await this.browser.currentPage;
+            const stateMap = { visible: 'visible', attached: 'attached' };
+            await page.locator(condition.selector).waitFor({
+                state: stateMap[condition.state],
+                timeout: condition.timeoutMs,
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async dismissOverlays() {
+        // Pass 1: Built-in cookie/widget dismissal (cookie-dismiss.ts)
+        const result = await this.browser.dismissOverlays();
+        if (result.dismissed)
+            return result;
+        // Pass 2: Playwright-level sweep for common accept/close buttons
+        // in cookie-like containers that the built-in module might miss
+        const page = await this.browser.currentPage;
+        const acceptPatterns = [
+            'button:has-text("Accept")',
+            'button:has-text("Accept all")',
+            'button:has-text("Accepter")',
+            'button:has-text("Tout accepter")',
+            'button:has-text("Got it")',
+            'button:has-text("I agree")',
+            'button:has-text("OK")',
+            '[role="button"]:has-text("Accept")',
+            '[role="button"]:has-text("Accept all")',
+        ];
+        for (const pattern of acceptPatterns) {
+            try {
+                const btn = page.locator(pattern).first();
+                if (await btn.isVisible({ timeout: 500 })) {
+                    // Check if the button is near the bottom of the viewport (likely a banner)
+                    const box = await btn.boundingBox();
+                    const viewport = page.viewportSize();
+                    if (box && viewport && box.y > viewport.height * 0.6) {
+                        await btn.click({ timeout: 2000 });
+                        await page.waitForTimeout(500);
+                        return { dismissed: true, method: `overlay-sweep:${pattern}` };
+                    }
+                }
+            }
+            catch {
+                // Try next pattern
+            }
+        }
+        // Pass 3: Try Escape key for modal overlays
+        try {
+            await page.keyboard.press('Escape');
+            await page.waitForTimeout(300);
+        }
+        catch {
+            // Non-fatal
+        }
+        return result;
+    }
+    async takeScreenshot() {
+        return this.browser.takeScreenshot();
+    }
+    async takeElementScreenshot(selector) {
+        const { buffer } = await this.browser.screenshotBySelector(selector);
+        return buffer;
+    }
+    async takeCleanScreenshot() {
+        return this.browser.takeScreenshot();
+    }
+    async beginRecording(options) {
+        const page = await this.browser.currentPage;
+        const baseDir = this.recordingDir
+            ?? await fs.mkdtemp(path.join(os.tmpdir(), 'autokap-recording-'));
+        const framesDir = path.join(baseDir, 'frames');
+        await fs.mkdir(framesDir, { recursive: true });
+        const loop = new ClipCaptureLoop({ page, framesDir });
+        await loop.start();
+        this.recording = {
+            mediaMode: options.mediaMode,
+            startedAt: Date.now(),
+            framesDir,
+            mp4Path: path.join(baseDir, `${options.mediaMode}.mp4`),
+            loop,
+            finalized: false,
+        };
+        this.clipCursor = { currentPosition: null };
+        await this.seedClipCursor();
+    }
+    async endRecording() {
+        if (!this.recording) {
+            throw new Error('recording was not started');
+        }
+        if (this.recording.finalized) {
+            const buffer = await fs.readFile(this.recording.mp4Path);
+            return {
+                buffer,
+                durationMs: Date.now() - this.recording.startedAt,
+                mimeType: 'video/mp4',
+                trimStartMs: this.recording.result?.trimStartMs ?? 0,
+            };
+        }
+        const result = await this.recording.loop.stop();
+        await this.browser.closeContext();
+        await assembleMp4FromFrames({
+            framesDir: this.recording.framesDir,
+            outputPath: this.recording.mp4Path,
+            fps: result.measuredFps,
+            frameOffsetsMs: result.frameOffsetsMs,
+        });
+        this.recording.finalized = true;
+        this.recording.result = result;
+        this.clipCursor = null;
+        const buffer = await fs.readFile(this.recording.mp4Path);
+        return {
+            buffer,
+            durationMs: Date.now() - this.recording.startedAt,
+            mimeType: 'video/mp4',
+            trimStartMs: result.trimStartMs,
+        };
+    }
+    async setLocale(locale) {
+        await this.browser.setLanguage(locale);
+    }
+    async setColorScheme(scheme) {
+        await this.browser.setColorScheme(scheme);
+    }
+    async reloadPage() {
+        await this.browser.reloadCurrentPage();
+    }
+    async writeStorageHint(params) {
+        if (params.storage === 'cookie') {
+            const page = await this.browser.currentPage;
+            const url = new URL(page.url());
+            await this.browser.addCookies([{
+                    name: params.key,
+                    value: params.value,
+                    domain: url.hostname,
+                    path: '/',
+                    httpOnly: false,
+                    secure: url.protocol === 'https:',
+                    sameSite: 'Lax',
+                }]);
+            return true;
+        }
+        return this.browser.writeStorageHintCandidate({
+            storageName: params.storage,
+            key: params.key,
+            candidate: params.value,
+            kind: params.kind,
+        });
+    }
+    async hover(selector) {
+        const page = await this.browser.currentPage;
+        const locator = page.locator(selector).first();
+        const target = await this.moveClipCursorToLocator(locator);
+        const position = target
+            ? await this.relativeClickPosition(locator, target)
+            : null;
+        if (position) {
+            await locator.hover({ timeout: 5000, position });
+        }
+        else {
+            await this.browser.hoverBySelector(selector);
+        }
+    }
+    async hoverByTarget(opts) {
+        const page = await this.browser.currentPage;
+        const resolved = await resolveTarget(page, opts);
+        if (!resolved) {
+            throw new Error(`cannot find target for hover: ${describeResolveOptions(opts)}`);
+        }
+        const target = await this.moveClipCursorToLocator(resolved.locator);
+        const position = target
+            ? await this.relativeClickPosition(resolved.locator, target)
+            : null;
+        await resolved.locator.hover({
+            timeout: 5000,
+            ...(position ? { position } : {}),
+        });
+    }
+    async selectOption(selector, option) {
+        await this.browser.selectOption({
+            selector,
+            optionLabel: option.label,
+            optionValue: option.value,
+            optionIndex: option.index,
+        });
+    }
+    async check(selector, checked) {
+        const page = await this.browser.currentPage;
+        const locator = page.locator(selector).first();
+        const target = await this.moveClipCursorToLocator(locator);
+        const position = target
+            ? await this.relativeClickPosition(locator, target)
+            : null;
+        const opts = { timeout: 5000, ...(position ? { position } : {}) };
+        if (checked) {
+            await locator.check(opts);
+        }
+        else {
+            await locator.uncheck(opts);
+        }
+    }
+    async doubleClick(selector) {
+        const page = await this.browser.currentPage;
+        const locator = page.locator(selector).first();
+        const target = await this.moveClipCursorToLocator(locator);
+        const position = target
+            ? await this.relativeClickPosition(locator, target)
+            : null;
+        await locator.dblclick({
+            timeout: 5000,
+            ...(position ? { position } : {}),
+        });
+    }
+    async drag(opts) {
+        const page = await this.browser.currentPage;
+        const viewport = page.viewportSize();
+        if (!viewport)
+            throw new Error('cannot drag without a known viewport');
+        const sourceResolved = await resolveTarget(page, {
+            selector: opts.selector,
+            target: opts.target,
+            selectorAlternates: opts.selectorAlternates,
+        });
+        if (!sourceResolved) {
+            throw new Error(`cannot find drag source: ${describeResolveOptions({ selector: opts.selector, target: opts.target })}`);
+        }
+        await sourceResolved.locator.scrollIntoViewIfNeeded({ timeout: 5000 }).catch(() => undefined);
+        const sourceBox = await sourceResolved.locator.boundingBox();
+        if (!sourceBox) {
+            throw new Error('drag source has no bounding box');
+        }
+        const sourcePoint = getHumanPointInBox(sourceBox, viewport);
+        const sourceCenter = {
+            x: sourceBox.x + sourceBox.width / 2,
+            y: sourceBox.y + sourceBox.height / 2,
+        };
+        let destPoint;
+        if (opts.toSelector || opts.toTarget) {
+            const destResolved = await resolveTarget(page, {
+                selector: opts.toSelector,
+                target: opts.toTarget,
+                selectorAlternates: opts.toSelectorAlternates,
+            });
+            if (!destResolved) {
+                throw new Error(`cannot find drag destination: ${describeResolveOptions({ selector: opts.toSelector, target: opts.toTarget })}`);
+            }
+            await destResolved.locator.scrollIntoViewIfNeeded({ timeout: 5000 }).catch(() => undefined);
+            const destBox = await destResolved.locator.boundingBox();
+            if (!destBox) {
+                throw new Error('drag destination has no bounding box');
+            }
+            destPoint = getHumanPointInBox(destBox, viewport);
+        }
+        else if (opts.offset) {
+            destPoint = {
+                x: clampPoint(sourceCenter.x + opts.offset.dx, 4, viewport.width - 4),
+                y: clampPoint(sourceCenter.y + opts.offset.dy, 4, viewport.height - 4),
+            };
+        }
+        else {
+            throw new Error('DRAG requires toSelector, toTarget, or offset');
+        }
+        const distance = Math.hypot(destPoint.x - sourcePoint.x, destPoint.y - sourcePoint.y);
+        const dragDurationMs = Math.min(1100, Math.max(400, 500 + distance));
+        if (this.clipCursor) {
+            await this.moveClipCursorToPoint(sourcePoint);
+        }
+        else {
+            await page.mouse.move(sourcePoint.x, sourcePoint.y);
+        }
+        await page.waitForTimeout(80 + Math.random() * 80);
+        await page.mouse.down();
+        if (this.clipCursor) {
+            await page.evaluate(() => {
+                if (typeof window.__akPressCursor === 'function') {
+                    window.__akPressCursor();
+                }
+            }).catch(() => { });
+        }
+        await moveMouse(page, sourcePoint, destPoint, { durationMs: dragDurationMs });
+        await page.waitForTimeout(70 + Math.random() * 60);
+        await page.mouse.up();
+        if (this.clipCursor) {
+            await page.evaluate(() => {
+                if (typeof window.__akReleaseCursor === 'function') {
+                    window.__akReleaseCursor();
+                }
+            }).catch(() => { });
+            this.clipCursor.currentPosition = destPoint;
+            await this.emitClipClickPulse();
+        }
+    }
+    // ── Mock data DOM mutations (soft / non-blocking) ──
+    async cloneElement(opts) {
+        const page = await this.browser.currentPage;
+        const clonedCount = await page.evaluate(({ sourceSelector, containerSelector, count, removeSource }) => {
+            const source = document.querySelector(sourceSelector);
+            const container = document.querySelector(containerSelector);
+            if (!source) {
+                throw new Error(`cloneElement: source "${sourceSelector}" not found`);
+            }
+            if (!container) {
+                throw new Error(`cloneElement: container "${containerSelector}" not found`);
+            }
+            let cloned = 0;
+            for (let i = 0; i < count; i++) {
+                const clone = source.cloneNode(true);
+                // Tag the clone so the mock-data row addressing can find it
+                // independently of nth-child math (which breaks when the
+                // container has non-template siblings like placeholders).
+                clone.setAttribute('data-ak-mock-clone', String(i));
+                container.appendChild(clone);
+                cloned++;
+            }
+            if (removeSource && source.parentElement === container) {
+                source.remove();
+            }
+            return cloned;
+        }, opts);
+        return { clonedCount };
+    }
+    async setAttribute(opts) {
+        const page = await this.browser.currentPage;
+        await page.evaluate(({ selector, attribute, value }) => {
+            const el = document.querySelector(selector);
+            if (!el) {
+                throw new Error(`setAttribute: element "${selector}" not found`);
+            }
+            el.setAttribute(attribute, value);
+        }, opts);
+    }
+    async setTextContent(opts) {
+        const page = await this.browser.currentPage;
+        await page.evaluate(({ selector, text }) => {
+            const el = document.querySelector(selector);
+            if (!el) {
+                throw new Error(`setTextContent: element "${selector}" not found`);
+            }
+            el.textContent = text;
+        }, opts);
+    }
+    async removeElement(opts) {
+        const page = await this.browser.currentPage;
+        const removedCount = await page.evaluate(({ selector }) => {
+            const nodes = document.querySelectorAll(selector);
+            if (nodes.length === 0) {
+                throw new Error(`removeElement: no elements match "${selector}"`);
+            }
+            nodes.forEach((n) => n.remove());
+            return nodes.length;
+        }, opts);
+        return { removedCount };
+    }
+    async setInputValue(opts) {
+        const page = await this.browser.currentPage;
+        await page.evaluate(({ selector, value }) => {
+            const el = document.querySelector(selector);
+            if (!el) {
+                throw new Error(`setInputValue: element "${selector}" not found`);
+            }
+            // Use the native value setter so React (and other controlled-component
+            // libraries) notice the change. Setting `el.value` directly bypasses
+            // React's internal value tracker and is silently ignored on next render.
+            const proto = el instanceof HTMLTextAreaElement
+                ? window.HTMLTextAreaElement.prototype
+                : el instanceof HTMLSelectElement
+                    ? window.HTMLSelectElement.prototype
+                    : window.HTMLInputElement.prototype;
+            const desc = Object.getOwnPropertyDescriptor(proto, 'value');
+            if (desc?.set) {
+                desc.set.call(el, value);
+            }
+            else {
+                el.value = value;
+            }
+            el.dispatchEvent(new Event('input', { bubbles: true }));
+            el.dispatchEvent(new Event('change', { bubbles: true }));
+        }, opts);
+    }
+    async clickHidden(opts) {
+        const page = await this.browser.currentPage;
+        await page.evaluate(({ selector }) => {
+            const el = document.querySelector(selector);
+            if (!el) {
+                throw new Error(`clickHidden: element "${selector}" not found`);
+            }
+            // Use the native click() method so React onClick handlers fire.
+            el.click();
+        }, opts);
+    }
+    async serializeDom(selector) {
+        const page = await this.browser.currentPage;
+        const baseUrl = page.url();
+        const fallbackViewport = page.viewportSize() ?? { width: 1440, height: 900 };
+        const rawCapture = await page.evaluate((targetSelector) => {
+            function serializeDoctype() {
+                return document.doctype
+                    ? `<!DOCTYPE ${document.doctype.name}` +
+                        (document.doctype.publicId ? ` PUBLIC "${document.doctype.publicId}"` : '') +
+                        (document.doctype.systemId && !document.doctype.publicId ? ' SYSTEM' : '') +
+                        (document.doctype.systemId ? ` "${document.doctype.systemId}"` : '') +
+                        '>'
+                    : '';
+            }
+            function copyAttributes(source, target) {
+                for (const attr of Array.from(source.attributes)) {
+                    target.setAttribute(attr.name, attr.value);
+                }
+            }
+            function buildFocusedBranch(element) {
+                let branch = element.cloneNode(true);
+                let currentSource = element.parentElement;
+                while (currentSource && currentSource !== document.body) {
+                    const shell = currentSource.cloneNode(false);
+                    shell.appendChild(branch);
+                    branch = shell;
+                    currentSource = currentSource.parentElement;
+                }
+                return branch;
+            }
+            /**
+             * Inline same-origin <link rel="stylesheet"> tags as <style> blocks.
+             * This makes the captured HTML self-contained — CSS chunk names are
+             * build-specific and will 404 when served from a different build.
+             * Cross-origin stylesheets (e.g. Google Fonts CSS) are left as <link>
+             * tags since their URLs are stable public CDN paths.
+             */
+            function inlineStylesheets(doc) {
+                const links = Array.from(doc.querySelectorAll('link[rel="stylesheet"]'));
+                for (const link of links) {
+                    const href = link.getAttribute('href');
+                    if (!href)
+                        continue;
+                    // Skip cross-origin stylesheets — their cssRules aren't accessible
+                    // and their URLs are stable (e.g. fonts.googleapis.com).
+                    try {
+                        const url = new URL(href, location.origin);
+                        if (url.origin !== location.origin)
+                            continue;
+                    }
+                    catch {
+                        continue;
+                    }
+                    // Find the matching CSSStyleSheet and read its rules.
+                    const sheet = Array.from(doc.styleSheets).find((s) => s.ownerNode === link);
+                    if (!sheet)
+                        continue;
+                    let cssText = '';
+                    try {
+                        const rules = sheet.cssRules;
+                        for (let i = 0; i < rules.length; i++) {
+                            cssText += rules[i].cssText + '\n';
+                        }
+                    }
+                    catch {
+                        continue;
+                    } // SecurityError for cross-origin sheets
+                    if (!cssText)
+                        continue;
+                    const style = doc.createElement('style');
+                    style.textContent = cssText;
+                    link.replaceWith(style);
+                }
+            }
+            const doctype = serializeDoctype();
+            const root = document.documentElement;
+            if (!targetSelector) {
+                inlineStylesheets(document);
+                return {
+                    html: doctype + (root ? root.outerHTML : ''),
+                    viewport: {
+                        width: window.innerWidth || document.documentElement.clientWidth || 1440,
+                        height: window.innerHeight || document.documentElement.clientHeight || 900,
+                    },
+                };
+            }
+            const element = document.querySelector(targetSelector);
+            if (!element) {
+                throw new Error(`serializeDom: no element matched selector "${targetSelector}"`);
+            }
+            if (element === document.documentElement) {
+                inlineStylesheets(document);
+                return {
+                    html: doctype + root.outerHTML,
+                    viewport: {
+                        width: window.innerWidth || document.documentElement.clientWidth || 1440,
+                        height: window.innerHeight || document.documentElement.clientHeight || 900,
+                    },
+                };
+            }
+            const nextDoc = document.implementation.createHTMLDocument(document.title || '');
+            copyAttributes(document.documentElement, nextDoc.documentElement);
+            nextDoc.head.innerHTML = document.head ? document.head.innerHTML : '';
+            copyAttributes(document.body, nextDoc.body);
+            if (element === document.body) {
+                nextDoc.body.innerHTML = document.body.innerHTML;
+            }
+            else {
+                const branch = buildFocusedBranch(element);
+                nextDoc.body.replaceChildren(nextDoc.importNode(branch, true));
+            }
+            // Inline stylesheets in the cloned document. The <link> elements were
+            // copied from the live document's <head>, so their ownerNode points to
+            // the cloned <link>. The CSSStyleSheet objects on the *live* document
+            // still hold the parsed rules — iterate those and match by href.
+            const liveSheets = Array.from(document.styleSheets);
+            const clonedLinks = Array.from(nextDoc.querySelectorAll('link[rel="stylesheet"]'));
+            for (const link of clonedLinks) {
+                const href = link.getAttribute('href');
+                if (!href)
+                    continue;
+                try {
+                    const url = new URL(href, location.origin);
+                    if (url.origin !== location.origin)
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                // Match by href against the live document's stylesheets.
+                const liveSheet = liveSheets.find((s) => {
+                    try {
+                        return s.href === new URL(href, location.origin).href;
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+                if (!liveSheet)
+                    continue;
+                let cssText = '';
+                try {
+                    const rules = liveSheet.cssRules;
+                    for (let i = 0; i < rules.length; i++) {
+                        cssText += rules[i].cssText + '\n';
+                    }
+                }
+                catch {
+                    continue;
+                }
+                if (!cssText)
+                    continue;
+                const style = nextDoc.createElement('style');
+                style.textContent = cssText;
+                link.replaceWith(style);
+            }
+            const rect = element.getBoundingClientRect();
+            return {
+                html: doctype + nextDoc.documentElement.outerHTML,
+                viewport: {
+                    width: Math.max(1, Math.ceil(rect.width || window.innerWidth || document.documentElement.clientWidth || 1440)),
+                    height: Math.max(1, Math.ceil(rect.height || window.innerHeight || document.documentElement.clientHeight || 900)),
+                },
+            };
+        }, selector ?? null);
+        // Lazy import to avoid loading parse5 unless DOM capture is actually used.
+        const { sanitizeDom } = await import('./dom-serializer.js');
+        const viewport = rawCapture?.viewport ?? fallbackViewport;
+        const result = sanitizeDom({ html: rawCapture.html, baseUrl, viewport });
+        return {
+            html: result.html,
+            assetUrls: result.assetUrls,
+            viewport,
+            capturedAt: new Date().toISOString(),
+        };
+    }
+    async serializeFragment(selector) {
+        const page = await this.browser.currentPage;
+        const baseUrl = page.url();
+        const rawHtml = await page.evaluate((sel) => {
+            const el = document.querySelector(sel);
+            return el ? el.outerHTML : null;
+        }, selector);
+        if (!rawHtml) {
+            throw new Error(`serializeFragment: no element matched selector "${selector}"`);
+        }
+        const { sanitizeFragment } = await import('./dom-serializer.js');
+        const result = sanitizeFragment({ html: rawHtml, baseUrl });
+        return {
+            html: result.html,
+            assetUrls: result.assetUrls,
+            capturedAt: new Date().toISOString(),
+        };
+    }
+    async extractFavicon() {
+        try {
+            const page = await this.browser.currentPage;
+            const faviconUrl = await page.evaluate(() => {
+                const icons = Array.from(document.querySelectorAll('link[rel="icon"], link[rel="shortcut icon"], link[rel="apple-touch-icon"]'));
+                if (icons.length > 0) {
+                    // Prefer apple-touch-icon > icon > shortcut icon, largest size
+                    icons.sort((a, b) => {
+                        const priority = (el) => el.rel === 'apple-touch-icon' ? 3 : el.rel === 'icon' ? 2 : 1;
+                        const size = (el) => {
+                            const s = el.getAttribute('sizes')?.split('x')[0];
+                            return s ? parseInt(s, 10) : 0;
+                        };
+                        return priority(b) - priority(a) || size(b) - size(a);
+                    });
+                    return icons[0].href;
+                }
+                return new URL('/favicon.ico', window.location.origin).href;
+            });
+            if (!faviconUrl)
+                return null;
+            const response = await page.context().request.get(faviconUrl, { timeout: 5000 });
+            if (!response.ok())
+                return null;
+            const buffer = Buffer.from(await response.body());
+            if (buffer.length === 0 || buffer.length > 512 * 1024)
+                return null;
+            const contentType = response.headers()['content-type'] ?? 'image/png';
+            const mimeType = contentType.split(';')[0].trim();
+            return { buffer, mimeType };
+        }
+        catch {
+            return null;
+        }
+    }
+    async close() {
+        await this.browser.close();
+    }
+    async typeIntoLocator(locator, text, clearFirst) {
+        const page = await this.browser.currentPage;
+        await locator.waitFor({ state: 'visible', timeout: 5000 });
+        await locator.scrollIntoViewIfNeeded({ timeout: 5000 }).catch(() => undefined);
+        const target = await this.moveClipCursorToLocator(locator);
+        const position = target
+            ? await this.relativeClickPosition(locator, target)
+            : null;
+        await locator.click({
+            timeout: 5000,
+            ...(position ? { position } : {}),
+        });
+        if (clearFirst) {
+            await page.keyboard.press('Control+A');
+        }
+        await page.waitForTimeout(70);
+        await humanType(page, text);
+    }
+    async seedClipCursor() {
+        if (!this.clipCursor)
+            return;
+        const page = await this.browser.currentPage;
+        const viewport = page.viewportSize();
+        if (!viewport)
+            return;
+        const startX = Math.round(viewport.width * (0.3 + Math.random() * 0.4));
+        const startY = Math.round(viewport.height * (0.3 + Math.random() * 0.4));
+        await page.mouse.move(startX, startY);
+        await page.evaluate(({ x, y }) => {
+            if (typeof window.__akMoveCursor === 'function')
+                window.__akMoveCursor(x, y);
+        }, { x: startX, y: startY }).catch(() => { });
+        this.clipCursor.currentPosition = { x: startX, y: startY };
+        await page.waitForTimeout(60);
+    }
+    async moveClipCursorToViewportCenter() {
+        if (!this.clipCursor)
+            return;
+        const page = await this.browser.currentPage;
+        const viewport = page.viewportSize();
+        if (!viewport)
+            return;
+        await this.moveClipCursorToPoint({
+            x: Math.round(viewport.width / 2),
+            y: Math.round(viewport.height / 2),
+        });
+    }
+    /**
+     * Animate the cursor to a point inside `locator` and return that point so
+     * the caller can click at the SAME coordinates (via
+     * `locator.click({ position })`). Returning the target avoids the "snap"
+     * bug where Playwright's default click recentered the mouse after the
+     * human-like Bezier landed somewhere off-center.
+     *
+     * Returns null when the cursor overlay is disabled, when the element has
+     * no bounding box, or when the cursor is already inside the element (no
+     * move needed, caller should let Playwright click at its default center).
+     */
+    async moveClipCursorToLocator(locator) {
+        if (!this.clipCursor)
+            return null;
+        await locator.waitFor({ state: 'visible', timeout: 5000 });
+        await locator.scrollIntoViewIfNeeded({ timeout: 5000 }).catch(() => undefined);
+        const page = await this.browser.currentPage;
+        const viewport = page.viewportSize();
+        const box = await locator.boundingBox();
+        if (!box || !viewport)
+            return null;
+        // Skip the move if the cursor is already inside the element — avoids
+        // erratic micro-movements when HOVER is immediately followed by CLICK
+        // on the same target.
+        const cur = this.clipCursor.currentPosition;
+        if (cur
+            && cur.x >= box.x && cur.x <= box.x + box.width
+            && cur.y >= box.y && cur.y <= box.y + box.height) {
+            return cur;
+        }
+        const target = getHumanPointInBox(box, viewport);
+        await this.moveClipCursorToPoint(target);
+        return target;
+    }
+    /**
+     * Convert an absolute viewport point to a position relative to `locator`'s
+     * bounding box, suitable for `locator.click({ position })`. Returns null
+     * if the point is outside the box (defensive fallback — callers should
+     * then let Playwright click at the default center).
+     */
+    async relativeClickPosition(locator, absolute) {
+        const box = await locator.boundingBox().catch(() => null);
+        if (!box)
+            return null;
+        const rx = absolute.x - box.x;
+        const ry = absolute.y - box.y;
+        if (rx < 0 || ry < 0 || rx > box.width || ry > box.height)
+            return null;
+        return { x: rx, y: ry };
+    }
+    async moveClipCursorToPoint(point, options) {
+        if (!this.clipCursor)
+            return;
+        const page = await this.browser.currentPage;
+        const from = this.clipCursor.currentPosition;
+        if (from) {
+            await moveMouse(page, from, point, options);
+        }
+        else {
+            await page.mouse.move(point.x, point.y);
+            await page.evaluate(({ x, y }) => {
+                if (typeof window.__akMoveCursor === 'function')
+                    window.__akMoveCursor(x, y);
+            }, { x: Math.round(point.x), y: Math.round(point.y) }).catch(() => { });
+        }
+        this.clipCursor.currentPosition = point;
+    }
+    async emitClipClickPulse() {
+        if (!this.clipCursor?.currentPosition)
+            return;
+        const page = await this.browser.currentPage;
+        const { x, y } = this.clipCursor.currentPosition;
+        await page.evaluate(({ px, py }) => {
+            if (typeof window.__akClickPulse === 'function')
+                window.__akClickPulse(px, py);
+        }, { px: Math.round(x), py: Math.round(y) }).catch(() => { });
+    }
+}
+function describeResolveOptions(opts) {
+    const parts = [];
+    if (opts.selector)
+        parts.push(`selector="${opts.selector}"`);
+    if (opts.target?.text)
+        parts.push(`text="${opts.target.text}"`);
+    if (opts.target?.role)
+        parts.push(`role="${opts.target.role}"`);
+    if (opts.target?.label)
+        parts.push(`label="${opts.target.label}"`);
+    if (opts.target?.placeholder)
+        parts.push(`placeholder="${opts.target.placeholder}"`);
+    return parts.join(', ') || 'no target specified';
+}
+function getHumanPointInBox(box, viewport) {
+    const insetX = Math.min(Math.max(box.width * 0.2, 6), Math.max(6, box.width / 2));
+    const insetY = Math.min(Math.max(box.height * 0.2, 6), Math.max(6, box.height / 2));
+    const minX = box.x + insetX;
+    const maxX = box.x + Math.max(insetX, box.width - insetX);
+    const minY = box.y + insetY;
+    const maxY = box.y + Math.max(insetY, box.height - insetY);
+    const targetX = maxX <= minX ? box.x + box.width / 2 : randomBetween(minX, maxX);
+    const targetY = maxY <= minY ? box.y + box.height / 2 : randomBetween(minY, maxY);
+    return {
+        x: clampPoint(targetX, 4, viewport.width - 4),
+        y: clampPoint(targetY, 4, viewport.height - 4),
+    };
+}
+function randomBetween(min, max) {
+    return min + Math.random() * Math.max(0, max - min);
+}
+function clampPoint(value, min, max) {
+    return Math.round(Math.max(min, Math.min(max, value)));
+}
+//# sourceMappingURL=web-playwright-local.js.map