autokap 1.0.5 → 1.0.7

package/dist/browser.js

@@ -366,15 +366,57 @@ export class Browser {
             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.context = await this.browser.newContext(this.buildContextOptions());
         this.page = await this.context.newPage();
     }
+    async recreateContext(options = {}) {
+        if (this.poolContext) {
+            throw new Error('Cannot recreate the context for a pooled browser instance');
+        }
+        this.options = {
+            ...this.options,
+            ...options,
+            viewport: options.viewport ?? this.options.viewport,
+            deviceScaleFactor: options.deviceScaleFactor ?? this.options.deviceScaleFactor,
+            lang: options.lang ?? this.options.lang,
+            colorScheme: options.colorScheme ?? this.options.colorScheme,
+            storageState: options.storageState ?? this.options.storageState,
+        };
+        if (!this.browser) {
+            await this.launch();
+            return;
+        }
+        if (this.page) {
+            try {
+                await this.page.close();
+            }
+            catch { /* ignore */ }
+            this.page = null;
+        }
+        if (this.context) {
+            try {
+                await this.context.close();
+            }
+            catch { /* ignore */ }
+            this.context = null;
+        }
+        this.context = await this.browser.newContext(this.buildContextOptions());
+        this.page = await this.context.newPage();
+        this.elementMap.clear();
+    }
+    async setDeviceScaleFactor(deviceScaleFactor) {
+        const normalizedScale = normalizeDeviceScaleFactor(deviceScaleFactor);
+        if (normalizeDeviceScaleFactor(this.options.deviceScaleFactor) === normalizedScale) {
+            return;
+        }
+        const sessionStorage = this.page
+            ? await this.exportSessionStorage().catch(() => undefined)
+            : undefined;
+        await this.recreateContext({ deviceScaleFactor: normalizedScale });
+        if (sessionStorage && Object.keys(sessionStorage).length > 0) {
+            await this.prepareSessionStorage(sessionStorage, { replace: false });
+        }
+    }
     async addCookies(cookies) {
         const context = this.ensureContext();
         await context.addCookies(cookies.map(c => ({
@@ -987,6 +1029,116 @@ export class Browser {
             [snapshot.origin]: snapshot.entries,
         };
     }
+    async reloadCurrentPage(options = {}) {
+        const page = this.ensurePage();
+        await page.reload({
+            waitUntil: options.waitUntil ?? 'domcontentloaded',
+            timeout: options.timeout ?? 15_000,
+        }).catch(async () => {
+            await this.navigateTo(page.url());
+        });
+    }
+    async writeStorageHintCandidate(params) {
+        const page = this.ensurePage();
+        return page.evaluate(({ storageName, key, candidate, kind }) => {
+            const storage = storageName === 'localStorage' ? window.localStorage : window.sessionStorage;
+            const current = storage.getItem(key);
+            if (current == null)
+                return false;
+            if (current === candidate)
+                return true;
+            const LOCALE_KEY_WHITELIST = ['lang', 'locale', 'language', 'i18n', 'intl', 'i18n-locale', 'next-i18next', 'NEXT_LOCALE', 'nuxt-i18n-locale'];
+            const THEME_KEY_WHITELIST = ['theme', 'color-scheme', 'colorScheme', 'dark-mode', 'darkMode', 'appearance'];
+            const whitelist = kind === 'locale' ? LOCALE_KEY_WHITELIST : THEME_KEY_WHITELIST;
+            const isAllowedKey = (inputKey) => {
+                const lower = inputKey.toLowerCase();
+                return whitelist.some((entry) => {
+                    const normalized = entry.toLowerCase();
+                    if (lower === normalized)
+                        return true;
+                    const re = new RegExp(`(?:^|[^a-zA-Z0-9])${normalized.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&')}(?:$|[^a-zA-Z0-9])`, 'i');
+                    return re.test(lower);
+                });
+            };
+            const looksLikeTargetValue = (value) => {
+                if (kind === 'locale') {
+                    return /^[a-z]{2,3}(-[a-zA-Z]{2,4})?$/.test(value.trim());
+                }
+                return /^(light|dark|auto|system|dim|high-contrast)$/i.test(value.trim());
+            };
+            const rewrite = (input, parentKeyAllowed = false) => {
+                if (typeof input === 'string') {
+                    if (!looksLikeTargetValue(input))
+                        return { changed: false, value: input };
+                    return { changed: input !== candidate, value: candidate };
+                }
+                if (Array.isArray(input)) {
+                    if (!parentKeyAllowed)
+                        return { changed: false, value: input };
+                    let changed = false;
+                    const next = input.map((entry) => {
+                        const rewritten = rewrite(entry, true);
+                        changed = changed || rewritten.changed;
+                        return rewritten.value;
+                    });
+                    return { changed, value: next };
+                }
+                if (input && typeof input === 'object') {
+                    let changed = false;
+                    const next = {};
+                    for (const [entryKey, entryValue] of Object.entries(input)) {
+                        const keyAllowed = isAllowedKey(entryKey);
+                        if (keyAllowed && typeof entryValue === 'string' && looksLikeTargetValue(entryValue)) {
+                            if (entryValue !== candidate)
+                                changed = true;
+                            next[entryKey] = candidate;
+                            continue;
+                        }
+                        const rewritten = rewrite(entryValue, keyAllowed);
+                        changed = changed || rewritten.changed;
+                        next[entryKey] = rewritten.value;
+                    }
+                    return { changed, value: next };
+                }
+                return { changed: false, value: input };
+            };
+            let nextValue = candidate;
+            try {
+                const parsed = JSON.parse(current);
+                const rewritten = rewrite(parsed);
+                if (rewritten.changed) {
+                    nextValue = JSON.stringify(rewritten.value);
+                }
+            }
+            catch {
+                nextValue = candidate;
+            }
+            storage.setItem(key, nextValue);
+            return true;
+        }, params);
+    }
+    async probeSelector(selector) {
+        const page = this.ensurePage();
+        try {
+            return await page.locator(selector).first().evaluate((node) => ({
+                tag: node.tagName.toLowerCase(),
+                role: node.getAttribute('role') || '',
+                href: node instanceof HTMLAnchorElement ? node.href : node.getAttribute('href'),
+                label: (node.getAttribute('aria-label')
+                    || node.getAttribute('title')
+                    || node.innerText
+                    || node.textContent
+                    || '').replace(/\s+/g, ' ').trim().slice(0, 120),
+                inputType: node instanceof HTMLInputElement ? node.type : node.getAttribute('type'),
+                ariaExpanded: node.getAttribute('aria-expanded'),
+                ariaControls: node.getAttribute('aria-controls'),
+                ariaHasPopup: node.getAttribute('aria-haspopup'),
+            }));
+        }
+        catch {
+            return null;
+        }
+    }
     async prepareSessionStorage(bundle, options = {}) {
         if (!bundle || Object.keys(bundle).length === 0)
             return;
@@ -2797,9 +2949,16 @@ export class Browser {
     }
     async resizeViewport(width, height) {
         const page = this.ensurePage();
+        this.options = {
+            ...this.options,
+            viewport: {
+                width: normalizeViewportDimension(width),
+                height: normalizeViewportDimension(height),
+            },
+        };
         await page.setViewportSize({
-            width: normalizeViewportDimension(width),
-            height: normalizeViewportDimension(height),
+            width: this.options.viewport.width,
+            height: this.options.viewport.height,
         });
     }
     get currentPage() {
@@ -2898,5 +3057,14 @@ export class Browser {
             throw new Error('Browser not launched. Call launch() first.');
         return this.context;
     }
+    buildContextOptions() {
+        return {
+            viewport: this.options.viewport,
+            deviceScaleFactor: normalizeDeviceScaleFactor(this.options.deviceScaleFactor),
+            locale: langToLocale(this.options.lang ?? 'en'),
+            colorScheme: this.options.colorScheme ?? 'light',
+            storageState: this.options.storageState,
+        };
+    }
 }
 //# sourceMappingURL=browser.js.map

package/dist/capture-alt-text.d.ts

@@ -0,0 +1,12 @@
+interface GenerateAltTextParams {
+    url: string;
+    prompt: string;
+    lang: string;
+    theme: 'light' | 'dark';
+    targetLabel?: string;
+    elementName?: string;
+    model: string;
+    apiKey: string;
+}
+export declare function generateAltText(params: GenerateAltTextParams): Promise<string | null>;
+export {};

package/dist/capture-alt-text.js

@@ -0,0 +1,51 @@
+export async function generateAltText(params) {
+    const { url, prompt, lang, theme, targetLabel, elementName, model, apiKey } = params;
+    const contextParts = [
+        `URL: ${url}`,
+        `Capture intent: "${prompt}"`,
+        `Theme: ${theme}`,
+    ];
+    if (targetLabel)
+        contextParts.push(`Device: ${targetLabel}`);
+    if (elementName)
+        contextParts.push(`Isolated element: ${elementName}`);
+    const systemPrompt = `You generate concise alt text for web page screenshots, for accessibility purposes.
+Write in ${lang}. Output ONLY the alt text, nothing else. Keep it under 150 characters.
+Describe what the screenshot represents based on the context provided.`;
+    try {
+        const res = await fetch('https://openrouter.ai/api/v1/chat/completions', {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                'Content-Type': 'application/json',
+                'HTTP-Referer': 'https://autokap.app',
+                'X-Title': 'Screenshot Agent',
+            },
+            body: JSON.stringify({
+                model,
+                max_tokens: 100,
+                stream: false,
+                messages: [
+                    { role: 'system', content: systemPrompt },
+                    { role: 'user', content: contextParts.join('\n') },
+                ],
+                provider: { zdr: true },
+            }),
+            signal: AbortSignal.timeout(5_000),
+        });
+        if (!res.ok) {
+            console.warn(`[generate-alt-text] LLM call failed: HTTP ${res.status}`);
+            return null;
+        }
+        const json = (await res.json());
+        const content = json.choices?.[0]?.message?.content?.trim();
+        if (!content)
+            return null;
+        return content.replace(/^["']|["']$/g, '');
+    }
+    catch {
+        console.warn('[generate-alt-text] ALT text generation failed');
+        return null;
+    }
+}
+//# sourceMappingURL=capture-alt-text.js.map

package/dist/capture-encryption.d.ts

@@ -0,0 +1,10 @@
+export interface EncryptedEnvelope {
+    __encrypted: true;
+    version: 1;
+    iv: string;
+    tag: string;
+    ciphertext: string;
+}
+export declare function encrypt(plaintext: string, secret: string): EncryptedEnvelope;
+export declare function decrypt(envelope: EncryptedEnvelope, secret: string): string;
+export declare function isEncryptedEnvelope(value: unknown): value is EncryptedEnvelope;

package/dist/capture-encryption.js

@@ -0,0 +1,41 @@
+import crypto from 'node:crypto';
+function deriveKey(secret) {
+    return crypto.createHash('sha256').update(secret).digest();
+}
+export function encrypt(plaintext, secret) {
+    const key = deriveKey(secret);
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+    const ciphertext = Buffer.concat([
+        cipher.update(plaintext, 'utf8'),
+        cipher.final(),
+    ]);
+    const tag = cipher.getAuthTag();
+    return {
+        __encrypted: true,
+        version: 1,
+        iv: iv.toString('base64'),
+        tag: tag.toString('base64'),
+        ciphertext: ciphertext.toString('base64'),
+    };
+}
+export function decrypt(envelope, secret) {
+    const key = deriveKey(secret);
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, Buffer.from(envelope.iv, 'base64'));
+    decipher.setAuthTag(Buffer.from(envelope.tag, 'base64'));
+    return Buffer.concat([
+        decipher.update(Buffer.from(envelope.ciphertext, 'base64')),
+        decipher.final(),
+    ]).toString('utf8');
+}
+export function isEncryptedEnvelope(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    return (candidate.__encrypted === true
+        && candidate.version === 1
+        && typeof candidate.iv === 'string'
+        && typeof candidate.tag === 'string'
+        && typeof candidate.ciphertext === 'string');
+}
+//# sourceMappingURL=capture-encryption.js.map

package/dist/capture-language-preflight.d.ts

@@ -0,0 +1,41 @@
+import type { Browser } from "./browser.js";
+import { type RequestedLanguageState, type RequestedThemeState } from "./session-profile.js";
+import type { AgentResult, LoginCredentials, StepUsage, ValidatedSessionProfile, VideoPageSignals } from "./types.js";
+import { type ScreenshotSelectorMemoryUpdate } from "./capture-selector-memory.js";
+interface LanguageObservation {
+    currentUrl: string;
+    signals: VideoPageSignals | null;
+    languageState: RequestedLanguageState | null;
+    themeState: RequestedThemeState | null;
+}
+export interface ScreenshotLanguagePreflightResult {
+    ok: boolean;
+    resolvedBy: "already_active" | "deterministic_repair" | "language_preflight_agent" | "blocked";
+    observation: LanguageObservation;
+    usage: StepUsage[];
+    selectorUpdates: ScreenshotSelectorMemoryUpdate[];
+    rebasedToStartUrl: boolean;
+    reason?: string;
+}
+export declare function ensureScreenshotVariantLanguage(params: {
+    browser: Browser;
+    requestedLang: string;
+    requestedTheme: "light" | "dark";
+    startUrl?: string;
+    profile?: ValidatedSessionProfile;
+    credentials?: LoginCredentials;
+    selectorMemory?: Record<string, string[]>;
+    langInstructions?: string;
+    themeInstructions?: string;
+    onLog?: (message: string) => void;
+    performRepair?: () => Promise<{
+        repaired: boolean;
+        updates: ScreenshotSelectorMemoryUpdate[];
+    } | null>;
+    rebaseToStartUrl?: (currentUrl: string, startUrl: string) => Promise<void>;
+    runLanguageSwitchAgent?: (state: {
+        languageState: RequestedLanguageState | null;
+        themeState: RequestedThemeState | null;
+    }) => Promise<AgentResult | null>;
+}): Promise<ScreenshotLanguagePreflightResult>;
+export {};

package/dist/capture-language-preflight.js

@@ -0,0 +1,286 @@
+import { evaluateRequestedLanguageState, evaluateRequestedThemeState, performDeterministicSessionRepair, } from "./session-profile.js";
+import { extractSelectorUpdates, } from "./capture-selector-memory.js";
+import { isCaptureStepTimeoutError, withCaptureStepTimeout, } from "./capture-step-timeout.js";
+import { urlMatchesCaptureTarget } from "./capture-run-optimizer.js";
+const LANGUAGE_OBSERVATION_TIMEOUT_MS = 12000;
+const LANGUAGE_REPAIR_TIMEOUT_MS = 15000;
+const LANGUAGE_STABILITY_DELAY_MS = 900;
+function urlsRoughlyMatch(expectedUrl, currentUrl) {
+    if (!expectedUrl || !currentUrl)
+        return false;
+    return urlMatchesCaptureTarget(currentUrl, expectedUrl) || urlMatchesCaptureTarget(expectedUrl, currentUrl);
+}
+async function waitForVariantStability(browser, delayMs) {
+    if (typeof browser.wait === "function") {
+        await browser.wait(delayMs);
+        return;
+    }
+    const pageWait = browser.currentPage.waitForTimeout;
+    if (typeof pageWait === "function") {
+        await pageWait.call(browser.currentPage, delayMs);
+        return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+function summarizeRequestedLanguageState(state) {
+    if (!state)
+        return "language_state=unavailable";
+    return [
+        state.requested ? `requested=${state.requested}` : null,
+        state.detected ? `detected=${state.detected}` : "detected=unknown",
+        `ambiguous=${state.ambiguous}`,
+        ...state.reasons.slice(0, 3),
+    ]
+        .filter(Boolean)
+        .join("; ");
+}
+function summarizeRequestedThemeState(state) {
+    if (!state)
+        return "theme_state=unavailable";
+    return [
+        state.requested ? `requested=${state.requested}` : null,
+        state.detected ? `detected=${state.detected}` : "detected=unknown",
+        `ambiguous=${state.ambiguous}`,
+        ...state.reasons.slice(0, 3),
+    ]
+        .filter(Boolean)
+        .join("; ");
+}
+function summarizeVariantObservation(observation) {
+    return [
+        summarizeRequestedLanguageState(observation.languageState),
+        summarizeRequestedThemeState(observation.themeState),
+    ].join(" | ");
+}
+function isObservationReady(observation) {
+    const languageReady = !!(observation.languageState?.active
+        && !observation.languageState.ambiguous);
+    const themeReady = !!(observation.themeState?.active
+        && !observation.themeState.ambiguous);
+    return languageReady && themeReady;
+}
+function buildFailureReason(requestedLang, requestedTheme, observation) {
+    const failures = [];
+    if (!observation.languageState) {
+        failures.push(`unable to inspect the current UI language for "${requestedLang}"`);
+    }
+    else if (!observation.languageState.active || observation.languageState.ambiguous) {
+        failures.push(`requested "${requestedLang}", detected "${observation.languageState.detected ?? "unknown"}" (${observation.languageState.reasons.join("; ")})`);
+    }
+    if (!observation.themeState) {
+        failures.push(`unable to inspect the current UI theme for "${requestedTheme}"`);
+    }
+    else if (!observation.themeState.active || observation.themeState.ambiguous) {
+        failures.push(`theme requested "${requestedTheme}", detected "${observation.themeState.detected ?? "unknown"}" (${observation.themeState.reasons.join("; ")})`);
+    }
+    if (failures.length === 0) {
+        return "";
+    }
+    return `Language preflight failed: ${failures.join(" | ")}.`;
+}
+async function observeLanguageState(browser, requestedLang, params) {
+    const currentUrl = browser.currentPage.url();
+    const phase = params?.phase ?? "inspection";
+    params?.onLog?.(`Language guard: inspecting fixed UI chrome during ${phase}.`);
+    const signals = await withCaptureStepTimeout(() => browser.capturePageSignals(), {
+        stepLabel: `inspecting fixed UI chrome during ${phase}`,
+        timeoutMs: LANGUAGE_OBSERVATION_TIMEOUT_MS,
+    }).catch((error) => {
+        if (isCaptureStepTimeoutError(error)) {
+            params?.onLog?.(`Language guard: fixed UI inspection timed out after ${error.timeoutMs}ms during ${phase}.`);
+            return null;
+        }
+        params?.onLog?.(`Language guard: fixed UI inspection failed during ${phase} (${error instanceof Error ? error.message : String(error)}).`);
+        return null;
+    });
+    return {
+        currentUrl,
+        signals,
+        languageState: signals
+            ? evaluateRequestedLanguageState({
+                currentUrl,
+                requestedLang,
+                signals,
+            })
+            : null,
+        themeState: signals
+            ? evaluateRequestedThemeState({
+                requestedTheme: params?.requestedTheme,
+                signals,
+            })
+            : null,
+    };
+}
+async function confirmStableLanguageState(params) {
+    if (!isObservationReady(params.observation)) {
+        return params.observation;
+    }
+    params.onLog?.(`Language guard: waiting ${LANGUAGE_STABILITY_DELAY_MS}ms to confirm the variant remains stable during ${params.phase}.`);
+    await waitForVariantStability(params.browser, LANGUAGE_STABILITY_DELAY_MS);
+    return observeLanguageState(params.browser, params.requestedLang, {
+        onLog: params.onLog,
+        phase: `${params.phase} stability verification`,
+        requestedTheme: params.requestedTheme,
+    });
+}
+export async function ensureScreenshotVariantLanguage(params) {
+    const usage = [];
+    const selectorUpdates = [];
+    const requestedLang = params.requestedLang.trim().toLowerCase();
+    let rebasedToStartUrl = false;
+    const rebaseIfNeeded = async (observation) => {
+        if (!params.startUrl
+            || !params.rebaseToStartUrl
+            || urlsRoughlyMatch(params.startUrl, observation.currentUrl)) {
+            return observation;
+        }
+        params.onLog?.(`Language guard: rebasing back to ${params.startUrl} after language switch from ${observation.currentUrl}.`);
+        await params.rebaseToStartUrl(observation.currentUrl, params.startUrl);
+        rebasedToStartUrl = true;
+        return observeLanguageState(params.browser, requestedLang, {
+            onLog: params.onLog,
+            phase: "post-rebase verification",
+            requestedTheme: params.requestedTheme,
+        });
+    };
+    let observation = await observeLanguageState(params.browser, requestedLang, {
+        onLog: params.onLog,
+        phase: "initial preflight",
+        requestedTheme: params.requestedTheme,
+    });
+    if (isObservationReady(observation)) {
+        return {
+            ok: true,
+            resolvedBy: "already_active",
+            observation,
+            usage,
+            selectorUpdates,
+            rebasedToStartUrl,
+        };
+    }
+    params.onLog?.(`Language guard: requested variant "${requestedLang}/${params.requestedTheme}" is not active yet; ${summarizeVariantObservation(observation)}.`);
+    params.onLog?.("Language guard: running deterministic variant repair before the main workflow.");
+    const repair = await withCaptureStepTimeout(async () => (params.performRepair
+        ?? (async () => {
+            const result = await performDeterministicSessionRepair(params.browser, {
+                startUrl: params.startUrl,
+                requestedLang,
+                requestedTheme: params.requestedTheme,
+                credentials: params.credentials,
+                profile: params.profile,
+                selectorMemory: params.selectorMemory,
+            }).catch(() => null);
+            return result
+                ? {
+                    repaired: result.repaired,
+                    updates: result.updates.map((update) => ({
+                        ...update,
+                        source: "deterministic",
+                    })),
+                }
+                : null;
+        }))(), {
+        stepLabel: "running deterministic variant repair",
+        timeoutMs: LANGUAGE_REPAIR_TIMEOUT_MS,
+    }).catch((error) => {
+        if (isCaptureStepTimeoutError(error)) {
+            params.onLog?.(`Language guard: deterministic repair timed out after ${error.timeoutMs}ms.`);
+            return null;
+        }
+        params.onLog?.(`Language guard: deterministic repair failed (${error instanceof Error ? error.message : String(error)}).`);
+        return null;
+    });
+    if (repair?.updates.length) {
+        selectorUpdates.push(...repair.updates);
+    }
+    observation = await observeLanguageState(params.browser, requestedLang, {
+        onLog: params.onLog,
+        phase: "post-repair verification",
+        requestedTheme: params.requestedTheme,
+    });
+    if (isObservationReady(observation)) {
+        observation = await rebaseIfNeeded(observation);
+        observation = await confirmStableLanguageState({
+            browser: params.browser,
+            requestedLang,
+            requestedTheme: params.requestedTheme,
+            observation,
+            onLog: params.onLog,
+            phase: "post-deterministic-repair",
+        });
+    }
+    if (isObservationReady(observation)) {
+        params.onLog?.(`Language guard: fixed UI variant switched successfully after deterministic repair; ${summarizeVariantObservation(observation)}.`);
+        return {
+            ok: true,
+            resolvedBy: "deterministic_repair",
+            observation,
+            usage,
+            selectorUpdates,
+            rebasedToStartUrl,
+        };
+    }
+    if (!params.runLanguageSwitchAgent) {
+        const reason = buildFailureReason(requestedLang, params.requestedTheme, observation);
+        params.onLog?.(`Language guard: blocking variant before main workflow. ${reason}`);
+        return {
+            ok: false,
+            resolvedBy: "blocked",
+            observation,
+            usage,
+            selectorUpdates,
+            rebasedToStartUrl,
+            reason,
+        };
+    }
+    params.onLog?.(`Language guard: deterministic repair was insufficient; launching dedicated variant preflight. ${summarizeVariantObservation(observation)}.`);
+    const preflightAgentResult = await params.runLanguageSwitchAgent({
+        languageState: observation.languageState,
+        themeState: observation.themeState,
+    }).catch(() => null);
+    if (preflightAgentResult?.usage?.length) {
+        usage.push(...preflightAgentResult.usage);
+    }
+    if (preflightAgentResult?.actions?.length) {
+        selectorUpdates.push(...extractSelectorUpdates(preflightAgentResult.actions));
+    }
+    observation = await observeLanguageState(params.browser, requestedLang, {
+        onLog: params.onLog,
+        phase: "post-variant-switch verification",
+        requestedTheme: params.requestedTheme,
+    });
+    if (isObservationReady(observation)) {
+        observation = await rebaseIfNeeded(observation);
+        observation = await confirmStableLanguageState({
+            browser: params.browser,
+            requestedLang,
+            requestedTheme: params.requestedTheme,
+            observation,
+            onLog: params.onLog,
+            phase: "post-variant-switch",
+        });
+    }
+    if (isObservationReady(observation)) {
+        params.onLog?.(`Language guard: fixed UI variant switched successfully after dedicated variant preflight. ${summarizeVariantObservation(observation)}.`);
+        return {
+            ok: true,
+            resolvedBy: "language_preflight_agent",
+            observation,
+            usage,
+            selectorUpdates,
+            rebasedToStartUrl,
+        };
+    }
+    const reason = buildFailureReason(requestedLang, params.requestedTheme, observation);
+    params.onLog?.(`Language guard: blocking variant before main workflow. ${reason}`);
+    return {
+        ok: false,
+        resolvedBy: "blocked",
+        observation,
+        usage,
+        selectorUpdates,
+        rebasedToStartUrl,
+        reason,
+    };
+}
+//# sourceMappingURL=capture-language-preflight.js.map

package/dist/capture-llm-page-identity.d.ts

@@ -0,0 +1,15 @@
+import type { CapturePageIdentity, StepUsage } from "./types.js";
+import type { ScreenshotPageRunInput } from "./capture-run-optimizer.js";
+export interface PageIdentityInferenceResult {
+    identities: Record<string, CapturePageIdentity>;
+    usage: StepUsage | null;
+}
+/**
+ * Use a cheap LLM call to classify all pages in a capture run.
+ * Falls back to regex heuristics if the LLM call fails.
+ */
+export declare function inferPageIdentitiesWithLLM(pageRuns: ScreenshotPageRunInput[], model: string, apiKey: string, providerPrefs?: Record<string, {
+    order?: string[];
+    require?: string[];
+    disallow?: string[];
+}>): Promise<PageIdentityInferenceResult>;