autokap 1.0.7 → 1.0.8

package/dist/v2/semantic-resolver.js

@@ -0,0 +1,161 @@
+/**
+ * Capture Agent — Semantic Target Resolver
+ *
+ * Resolves a SemanticTarget to a concrete Playwright locator.
+ * This is the core mechanism that allows opcodes to work WITHOUT CSS selectors.
+ *
+ * Resolution cascade:
+ * 1. CSS selector (if provided, fast path)
+ * 2. Playwright semantic locators (getByRole, getByText, getByLabel, getByPlaceholder)
+ * 3. Selector alternates
+ * 4. Composite: role + name + near (for disambiguation)
+ *
+ * All resolution happens via Playwright's built-in locator API — no AKTree needed.
+ */
+/**
+ * Resolves an element on the page using the best available method.
+ * Returns the first visible locator found, or null if nothing matches.
+ */
+export async function resolveTarget(page, options) {
+    const timeout = options.timeoutMs ?? 3000;
+    // 1. Primary CSS selector
+    if (options.selector) {
+        const locator = page.locator(options.selector).first();
+        if (await isVisible(locator, timeout)) {
+            return { locator, method: 'selector' };
+        }
+    }
+    // 2. Semantic locators from target
+    if (options.target) {
+        const resolved = await resolveSemanticTarget(page, options.target, timeout);
+        if (resolved)
+            return resolved;
+    }
+    // 3. Alternate selectors
+    if (options.selectorAlternates) {
+        for (const alt of options.selectorAlternates) {
+            const locator = page.locator(alt).first();
+            if (await isVisible(locator, timeout)) {
+                return { locator, method: 'alternate' };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Resolves a SemanticTarget using Playwright's semantic locator API.
+ */
+async function resolveSemanticTarget(page, target, timeout) {
+    const exact = target.exact ?? false;
+    // Strategy A: getByRole with name (most precise)
+    if (target.role && (target.text || target.label)) {
+        const name = target.label || target.text;
+        try {
+            let locator = page.getByRole(target.role, {
+                name: name,
+                exact,
+            });
+            if (target.near) {
+                locator = narrowByNear(page, locator, target.near);
+            }
+            locator = locator.first();
+            if (await isVisible(locator, timeout)) {
+                return { locator, method: 'role' };
+            }
+        }
+        catch {
+            // Invalid role or no match
+        }
+    }
+    // Strategy B: getByRole without name
+    if (target.role && !target.text && !target.label) {
+        try {
+            let locator = page.getByRole(target.role);
+            if (target.near) {
+                locator = narrowByNear(page, locator, target.near);
+            }
+            locator = locator.first();
+            if (await isVisible(locator, timeout)) {
+                return { locator, method: 'role' };
+            }
+        }
+        catch {
+            // Invalid role
+        }
+    }
+    // Strategy C: getByText
+    if (target.text) {
+        let locator = page.getByText(target.text, { exact });
+        if (target.near) {
+            locator = narrowByNear(page, locator, target.near);
+        }
+        locator = locator.first();
+        if (await isVisible(locator, timeout)) {
+            return { locator, method: 'text' };
+        }
+    }
+    // Strategy D: getByLabel
+    if (target.label) {
+        let locator = page.getByLabel(target.label, { exact });
+        if (target.near) {
+            locator = narrowByNear(page, locator, target.near);
+        }
+        locator = locator.first();
+        if (await isVisible(locator, timeout)) {
+            return { locator, method: 'label' };
+        }
+    }
+    // Strategy E: getByPlaceholder (for inputs)
+    if (target.placeholder) {
+        let locator = page.getByPlaceholder(target.placeholder, { exact });
+        if (target.near) {
+            locator = narrowByNear(page, locator, target.near);
+        }
+        locator = locator.first();
+        if (await isVisible(locator, timeout)) {
+            return { locator, method: 'placeholder' };
+        }
+    }
+    // Strategy F: Composite — try role-based with looser matching
+    if (target.role) {
+        try {
+            const allByRole = page.getByRole(target.role);
+            const count = await allByRole.count();
+            for (let i = 0; i < Math.min(count, 10); i++) {
+                const candidate = allByRole.nth(i);
+                if (await isVisible(candidate, 500)) {
+                    const text = await candidate.textContent().catch(() => null);
+                    if (text && target.text && text.toLowerCase().includes(target.text.toLowerCase())) {
+                        return { locator: candidate, method: 'composite' };
+                    }
+                }
+            }
+        }
+        catch {
+            // No match
+        }
+    }
+    return null;
+}
+/**
+ * Narrows a locator to one near a specific text/heading on the page.
+ * Uses Playwright's `.filter()` with a parent locator containing the near text.
+ */
+function narrowByNear(page, locator, nearText) {
+    // Find a section/container that contains the near text
+    const container = page.locator(`section:has-text("${escapeForSelector(nearText)}"), div:has-text("${escapeForSelector(nearText)}"), [role="region"]:has-text("${escapeForSelector(nearText)}")`).first();
+    return container.locator(locator);
+}
+async function isVisible(locator, timeout) {
+    try {
+        await locator.waitFor({ state: 'visible', timeout });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function escapeForSelector(text) {
+    return text.replace(/"/g, '\\"').replace(/\n/g, ' ');
+}
+//# sourceMappingURL=semantic-resolver.js.map

package/dist/v2/smart-wait.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Capture Agent — Smart Wait
+ *
+ * Detects if the page is still loading before capture.
+ * Uses Playwright-native checks (no LLM) to wait for:
+ * - Network idle
+ * - No visible spinners/skeletons
+ * - DOM stability
+ */
+import type { RuntimeAdapter } from './types.js';
+export interface SmartWaitResult {
+    /** Whether the page appears stable */
+    stable: boolean;
+    /** What we waited for */
+    waitedFor: string[];
+    /** Total time spent waiting (ms) */
+    waitedMs: number;
+}
+/**
+ * Waits for the page to be visually stable before capture.
+ * Checks for common loading patterns and waits for them to resolve.
+ *
+ * This runs BEFORE CAPTURE_SCREENSHOT — deterministic, no LLM.
+ */
+export declare function smartWaitForStability(adapter: RuntimeAdapter, options?: {
+    maxWaitMs?: number;
+}): Promise<SmartWaitResult>;

package/dist/v2/smart-wait.js

@@ -0,0 +1,81 @@
+/**
+ * Capture Agent — Smart Wait
+ *
+ * Detects if the page is still loading before capture.
+ * Uses Playwright-native checks (no LLM) to wait for:
+ * - Network idle
+ * - No visible spinners/skeletons
+ * - DOM stability
+ */
+/**
+ * Waits for the page to be visually stable before capture.
+ * Checks for common loading patterns and waits for them to resolve.
+ *
+ * This runs BEFORE CAPTURE_SCREENSHOT — deterministic, no LLM.
+ */
+export async function smartWaitForStability(adapter, options) {
+    const maxWait = options?.maxWaitMs ?? 10000;
+    const startTime = Date.now();
+    const waitedFor = [];
+    // 1. Wait for no visible spinners/skeletons
+    const spinnerSelectors = [
+        '[class*="spinner"]',
+        '[class*="loading"]',
+        '[class*="skeleton"]',
+        '[class*="shimmer"]',
+        '[role="progressbar"]',
+        '[aria-busy="true"]',
+        '.animate-spin',
+        '.animate-pulse',
+    ];
+    for (const selector of spinnerSelectors) {
+        const elapsed = Date.now() - startTime;
+        if (elapsed >= maxWait)
+            break;
+        try {
+            // Check if spinner exists and is visible
+            const visible = await adapter.waitFor({
+                selector,
+                state: 'visible',
+                timeoutMs: 200, // Quick check
+            });
+            if (visible) {
+                // Spinner found — wait for it to disappear
+                waitedFor.push(selector);
+                const remaining = maxWait - (Date.now() - startTime);
+                if (remaining > 0) {
+                    // Poll until spinner disappears
+                    const deadline = Date.now() + Math.min(remaining, 5000);
+                    while (Date.now() < deadline) {
+                        const stillVisible = await adapter.waitFor({
+                            selector,
+                            state: 'visible',
+                            timeoutMs: 300,
+                        });
+                        if (!stillVisible)
+                            break;
+                        await sleep(300);
+                    }
+                }
+            }
+        }
+        catch {
+            // Selector check failed — skip
+        }
+    }
+    // 2. Brief stability pause (let animations settle)
+    const elapsed = Date.now() - startTime;
+    if (elapsed < maxWait) {
+        await sleep(Math.min(500, maxWait - elapsed));
+        waitedFor.push('stability-pause');
+    }
+    return {
+        stable: true,
+        waitedFor,
+        waitedMs: Date.now() - startTime,
+    };
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=smart-wait.js.map