autokap 1.0.6 → 1.0.7

package/dist/ws-handler.js

@@ -0,0 +1,1663 @@
+/**
+ * WS handler — orchestrates a capture run for a single CLI connection.
+ *
+ * The CLI stays a thin RPC adapter around a local Playwright browser.
+ * The orchestration stays server-side and reuses shared capture helpers
+ * so the WS flow does not drift from the HTTP capture flow.
+ */
+import crypto from 'node:crypto';
+import { chromium } from 'playwright';
+import { replayAgent, runAgent, verifyCaptureReadiness } from './agent.js';
+import { buildAgentRunHints } from './session-profile.js';
+import { captureIsolatedElement } from './element-capture.js';
+import { getCapturePromptValidationError, getCaptureUrlHostname, resolveCaptureRequestPlan, sanitizeStorageSegment, urlsPointToSameCaptureState, } from './capture-request-plan.js';
+import { insertCostLogs, resolveAllCosts, updateCostLogCaptureContext, } from './cost-logging.js';
+import { insertScreenshotOperationLog, reconcilePendingBillingOperationCosts, } from './billing-operation-logging.js';
+import { generateAltText } from './capture-alt-text.js';
+import { ensureScreenshotVariantLanguage } from './capture-language-preflight.js';
+import { inferPageIdentitiesWithLLM } from './capture-llm-page-identity.js';
+import { resolveRunModels } from './capture-model-resolution.js';
+import { extractSelectorUpdates, loadScreenshotSelectorMemory, persistScreenshotSelectorMemoryUpdates, } from './capture-selector-memory.js';
+import { hydratePresetConfigFromStorage } from './capture-preset-credentials.js';
+import { applySelectorMemoryUpdates, buildSequentialHandoffArtifacts, buildSessionBootstrapProfile, deriveRunSharedAuthProfile, getUrlOrigin, mergeSelectorMemory, resolveIsolatedElementAssignments, resolveScopedSelectorMemory, scopeSelectorMemoryUpdates, shouldReuseLivePageState, shouldUseSequentialPageHandoff, urlMatchesCaptureTarget, } from './capture-run-optimizer.js';
+import { decryptSessionField, encryptSessionField, } from './capture-session-profile-encryption.js';
+import { buildVariantManifestContext, createVariantCaptureState, markVariantCaptureBlocked, markVariantCaptureInProgress, recordValidatedVariantCapture, validateVariantCaptureState, } from './capture-variant-state.js';
+import { syncStudioVariantAfterCapture } from './capture-studio-sync.js';
+import { applyDeviceFrame, invalidateDeviceConfigCache } from './mockup.js';
+import { localizeStatusBar } from './status-bar-l10n.js';
+import { logger } from './logger.js';
+import { getRemoteBrowserCompatibilityError, RemoteBrowser, } from './remote-browser.js';
+import { recordCreditUsage } from './server-credit-usage.js';
+import { cleanupExpiredCapturesForOwner, ensureCaptureConfigAllowed, ensureMonthlyCreditsQuota, ensureResourceNotLocked, getBillingAccountForUser, getCaptureOverageState, getBillingPlan, getIncrementalOverageCount, getLockedResourceIds, getOwnerBillingUsage, getProjectOwnerBillingContext, getRemainingOverageCredits, getSignupBonusCredits, getStripeOveragePriceIdForPlan, isYearlySubscription, PlanLimitError, recordStripeMeterEvent, SCREENSHOT_CREDIT_COST, shouldUseStripePlan, } from './server-capture-runtime.js';
+import { buildCaptureWebhookPayload, dispatchProjectCaptureWebhook, getProjectWebhookConfig, } from './server-project-webhooks.js';
+import { getServerPostHog } from './server-posthog.js';
+import { applyPlanScreenshotWatermark } from './server-screenshot-watermark.js';
+import { validateApiKey, requireScope, getSupabase } from './ws-auth.js';
+const BUCKET = 'screenshots';
+function getOpenRouterKey() {
+    const key = process.env.OPENROUTER_API_KEY ?? '';
+    if (!key)
+        logger.error('OPENROUTER_API_KEY is not set');
+    return key;
+}
+async function waitForClientHello(ws, timeoutMs = 3_000) {
+    return await new Promise((resolve) => {
+        let settled = false;
+        let timer = setTimeout(() => {
+            settled = true;
+            cleanup();
+            resolve(null);
+        }, timeoutMs);
+        const cleanup = () => {
+            if (timer) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            ws.off('message', onMessage);
+            ws.off('close', onClose);
+            ws.off('error', onClose);
+        };
+        const onClose = () => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(null);
+        };
+        const onMessage = (data) => {
+            if (settled)
+                return;
+            try {
+                const raw = typeof data === 'string' ? data : data.toString('utf-8');
+                const parsed = JSON.parse(raw);
+                if (parsed.type !== 'client_hello' || !parsed.client)
+                    return;
+                settled = true;
+                cleanup();
+                resolve(parsed.client);
+            }
+            catch {
+                // Ignore non-JSON or non-hello messages until timeout.
+            }
+        };
+        ws.on('message', onMessage);
+        ws.on('close', onClose);
+        ws.on('error', onClose);
+    });
+}
+export async function handleConnection(ws, req) {
+    const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+    const rawKey = url.searchParams.get('key') ?? '';
+    const presetId = url.searchParams.get('preset_id') ?? '';
+    const clientHelloPromise = waitForClientHello(ws);
+    const sendEvent = (type, data) => {
+        if (ws.readyState === ws.OPEN) {
+            ws.send(JSON.stringify({ type, ...data }));
+        }
+    };
+    const auth = await validateApiKey(rawKey);
+    if (!auth) {
+        sendEvent('error', { message: 'Invalid API key' });
+        ws.close(4001, 'Invalid API key');
+        return;
+    }
+    try {
+        requireScope(auth.scopes, 'presets:execute');
+    }
+    catch {
+        sendEvent('error', { message: 'Missing scope: presets:execute' });
+        ws.close(4003, 'Forbidden');
+        return;
+    }
+    if (!presetId) {
+        sendEvent('error', { message: 'Missing preset_id parameter' });
+        ws.close(4000, 'Missing preset_id');
+        return;
+    }
+    const supabase = getSupabase();
+    const { data: preset, error: presetError } = await supabase
+        .from('presets')
+        .select('id, project_id, name, config')
+        .eq('id', presetId)
+        .single();
+    if (presetError || !preset) {
+        sendEvent('error', { message: `Preset not found: ${presetId}` });
+        ws.close(4004, 'Preset not found');
+        return;
+    }
+    const { data: project, error: projectError } = await supabase
+        .from('projects')
+        .select('id, url, name, user_id')
+        .eq('id', preset.project_id)
+        .single();
+    if (projectError || !project) {
+        sendEvent('error', { message: 'Project not found' });
+        ws.close(4004, 'Project not found');
+        return;
+    }
+    if (project.user_id !== auth.userId) {
+        sendEvent('error', { message: 'Not authorized to run this preset' });
+        ws.close(4003, 'Forbidden');
+        return;
+    }
+    const clientInfo = await clientHelloPromise;
+    const compatibilityError = getRemoteBrowserCompatibilityError(clientInfo);
+    if (compatibilityError) {
+        sendEvent('error', { message: compatibilityError });
+        ws.close(4000, 'CLI update required');
+        return;
+    }
+    const config = hydratePresetConfigFromStorage(preset.config);
+    const projectUrl = String(project.url ?? '');
+    const planInput = {
+        ...config,
+        url: projectUrl,
+        prompt: String(config.prompt ?? ''),
+    };
+    const promptValidationError = getCapturePromptValidationError(planInput);
+    if (promptValidationError) {
+        sendEvent('error', { message: promptValidationError });
+        ws.close(4000, 'Invalid capture prompt config');
+        return;
+    }
+    invalidateDeviceConfigCache();
+    const { pageRuns: pages, pageDefinitionIssues, langs, themes, variantPlan, targets, elements, outputScale, totalCaptures, } = await resolveCaptureRequestPlan(planInput);
+    if (pageDefinitionIssues.length > 0) {
+        sendEvent('error', {
+            message: pageDefinitionIssues.map((issue) => issue.reason).join(' '),
+        });
+        ws.close(4000, 'Ambiguous capture pages');
+        return;
+    }
+    sendEvent('progress', { message: `Loaded preset "${preset.name}" for ${projectUrl}` });
+    let resolvedModel = '';
+    let resolvedFallback;
+    let resolvedVisionModel;
+    const providerPreferences = {};
+    try {
+        const { data: cfgRows } = await supabase
+            .from('app_config')
+            .select('key, value')
+            .in('key', [
+            'default_model', 'fallback_model', 'vision_model',
+            'default_model_provider', 'fallback_model_provider', 'vision_model_provider',
+        ]);
+        const cfg = {};
+        for (const row of cfgRows ?? [])
+            cfg[row.key] = row.value;
+        const resolved = resolveRunModels({
+            requestModel: config.model ?? null,
+            defaultModel: cfg.default_model,
+            fallbackModel: cfg.fallback_model,
+            presetId,
+        });
+        resolvedModel = resolved.model;
+        resolvedFallback = resolved.fallbackModel;
+        resolvedVisionModel = cfg.vision_model?.trim() || undefined;
+        for (const [cfgKey, modelVal] of [
+            ['default_model_provider', resolvedModel],
+            ['fallback_model_provider', resolvedFallback],
+            ['vision_model_provider', resolvedVisionModel],
+        ]) {
+            try {
+                const raw = cfg[cfgKey];
+                if (raw && modelVal)
+                    providerPreferences[modelVal] = JSON.parse(raw);
+            }
+            catch {
+                // Ignore invalid provider preference JSON.
+            }
+        }
+    }
+    catch {
+        // Non-blocking: the app_config table may be missing during bootstrap.
+    }
+    if (!resolvedModel) {
+        sendEvent('error', { message: 'No model configured. Set a default model in the admin dashboard.' });
+        ws.close(5000, 'No model');
+        return;
+    }
+    let plan = getBillingPlan('free');
+    let billingOwnerUserId = auth.userId;
+    let billingAccount = null;
+    let allowOverage = false;
+    let usedCreditsBefore = 0;
+    let remainingOverageCreditsBefore = null;
+    try {
+        const billingContext = await getProjectOwnerBillingContext(supabase, project.id);
+        plan = billingContext.plan;
+        billingOwnerUserId = billingContext.ownerUserId;
+        const lockState = await getLockedResourceIds(supabase, billingOwnerUserId, plan);
+        ensureResourceNotLocked(project.id, lockState.lockedProjectIds, 'project');
+        const lockedPresets = lockState.lockedPresetIdsByProject.get(project.id);
+        if (lockedPresets) {
+            ensureResourceNotLocked(presetId, lockedPresets, 'preset');
+        }
+        ensureCaptureConfigAllowed(plan, {
+            langs,
+            themes: [...themes],
+            elements,
+        });
+        const usage = await getOwnerBillingUsage(supabase, billingOwnerUserId);
+        usedCreditsBefore = usage.credits;
+        billingAccount = await getBillingAccountForUser(supabase, billingOwnerUserId);
+        const hasActiveStripeSub = !!billingAccount?.stripe_subscription_id
+            && shouldUseStripePlan(billingAccount.stripe_subscription_status);
+        const overageLimitCents = billingAccount?.capture_overage_limit_cents ?? null;
+        const overageState = getCaptureOverageState({
+            planId: plan.id,
+            quota: plan.entitlements.creditsPerMonth,
+            usedCredits: usage.credits,
+            allowOverages: billingAccount?.allow_capture_overages ?? false,
+            overageLimitCents,
+            hasActiveSubscription: hasActiveStripeSub,
+            hasOveragePrice: !!getStripeOveragePriceIdForPlan(plan.id),
+            isYearlySubscription: isYearlySubscription(billingAccount),
+        });
+        allowOverage = overageState.eligible;
+        remainingOverageCreditsBefore = getRemainingOverageCredits({
+            planId: plan.id,
+            quota: plan.entitlements.creditsPerMonth,
+            usedCredits: usage.credits,
+            overageLimitCents,
+        });
+        const requestedCredits = totalCaptures * SCREENSHOT_CREDIT_COST;
+        const bonusCredits = getSignupBonusCredits(billingAccount, usage.billingPeriodStart);
+        ensureMonthlyCreditsQuota(plan, usage.credits, requestedCredits, allowOverage, overageLimitCents, bonusCredits);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        sendEvent('error', {
+            message,
+            ...(error instanceof PlanLimitError ? { code: error.code } : {}),
+        });
+        ws.close(error instanceof PlanLimitError ? 4003 : 5000, 'Capture unavailable');
+        return;
+    }
+    const runHints = await loadRunHints(supabase, presetId);
+    const runId = crypto.randomUUID();
+    const runStartedAt = new Date().toISOString();
+    const credentials = config.credentials ?? undefined;
+    const maxIterations = Number(config.maxIterations ?? 60) || 60;
+    const { error: runInsertError } = await supabase
+        .from('capture_runs')
+        .insert({
+        id: runId,
+        user_id: auth.userId,
+        api_key_id: auth.apiKeyId,
+        preset_id: presetId,
+        project_id: project.id,
+        status: 'running',
+        progress_current: 0,
+        progress_total: totalCaptures,
+        captures: [],
+        credits_used: 0,
+        started_at: runStartedAt,
+    });
+    if (runInsertError) {
+        sendEvent('error', { message: `Failed to create run: ${runInsertError.message}` });
+        ws.close(5000, 'Internal error');
+        return;
+    }
+    const remoteBrowser = new RemoteBrowser(ws);
+    const abortController = new AbortController();
+    let aborted = false;
+    ws.on('close', () => {
+        aborted = true;
+        abortController.abort();
+    });
+    const mockupState = {
+        browser: null,
+        context: null,
+    };
+    const getMockupContext = async () => {
+        if (!mockupState.context) {
+            mockupState.browser = await chromium.launch({ headless: true });
+            mockupState.context = await mockupState.browser.newContext();
+        }
+        return mockupState.context;
+    };
+    const closeMockup = async () => {
+        try {
+            await mockupState.context?.close();
+        }
+        catch { /* ignore */ }
+        try {
+            await mockupState.browser?.close();
+        }
+        catch { /* ignore */ }
+    };
+    const selectorMemoryCache = new Map();
+    const sessionProfileCache = new Map();
+    const liveVariantActions = new Map();
+    const liveVariantReference = new Map();
+    const runSharedAuthProfiles = new Map();
+    const captureResults = [];
+    let runSharedStorageState;
+    let runSharedSessionStorage;
+    let successCount = 0;
+    let captureIndex = 0;
+    const rootOrigin = getUrlOrigin(projectUrl);
+    const updateRunProgress = async () => {
+        await supabase
+            .from('capture_runs')
+            .update({
+            progress_current: captureIndex,
+            credits_used: successCount,
+        })
+            .eq('id', runId);
+    };
+    const finalizeRunSideEffects = async () => {
+        try {
+            if (allowOverage && billingAccount?.stripe_customer_id && successCount > 0) {
+                const rawOverageCount = getIncrementalOverageCount({
+                    quota: plan.entitlements.creditsPerMonth,
+                    usedBefore: usedCreditsBefore,
+                    completedCount: successCount * SCREENSHOT_CREDIT_COST,
+                });
+                const overageCount = remainingOverageCreditsBefore === null
+                    ? rawOverageCount
+                    : Math.min(rawOverageCount, remainingOverageCreditsBefore);
+                if (overageCount > 0) {
+                    await recordStripeMeterEvent({
+                        customerId: billingAccount.stripe_customer_id,
+                        value: overageCount,
+                        identifier: runId,
+                    });
+                }
+            }
+        }
+        catch {
+            // Non-blocking.
+        }
+        try {
+            await cleanupExpiredCapturesForOwner(supabase, billingOwnerUserId);
+        }
+        catch {
+            // Non-blocking.
+        }
+    };
+    const logAgentUsage = async (params) => {
+        if (params.usage.length === 0) {
+            return [];
+        }
+        try {
+            const ids = await insertCostLogs(supabase, {
+                runId,
+                userId: auth.userId,
+                projectId: project.id,
+                presetId,
+                lang: params.lang,
+                theme: params.theme,
+                captureType: params.captureType,
+                elementName: params.elementName,
+                targetId: params.targetId,
+                viewportWidth: params.viewportWidth,
+                viewportHeight: params.viewportHeight,
+            }, params.usage);
+            if (ids.length > 0) {
+                void resolveAllCosts(supabase, ids.map((id, index) => ({
+                    costLogId: id,
+                    generationId: params.usage[index]?.generationId ?? null,
+                })), getOpenRouterKey(), supabase).catch((error) => {
+                    logger.error(`Cost resolution failed: ${error.message}`);
+                });
+            }
+            return ids;
+        }
+        catch (error) {
+            logger.error(`Failed to log agent usage: ${error.message}`);
+            return [];
+        }
+    };
+    const loadSelectorMemoryForVariant = async (domain, lang, theme) => {
+        const cacheKey = `${domain}:${lang}:${theme}`;
+        if (selectorMemoryCache.has(cacheKey)) {
+            return selectorMemoryCache.get(cacheKey) ?? {};
+        }
+        const memory = await loadScreenshotSelectorMemory(supabase, {
+            projectId: project.id,
+            presetId,
+            domain,
+            lang,
+            theme,
+        }).catch(() => ({}));
+        selectorMemoryCache.set(cacheKey, memory);
+        return memory;
+    };
+    const loadSessionProfileForVariant = async (domain, lang, theme) => {
+        const cacheKey = `${domain}:${lang}:${theme}`;
+        if (sessionProfileCache.has(cacheKey)) {
+            return sessionProfileCache.get(cacheKey);
+        }
+        try {
+            const { data } = await supabase
+                .from('screenshot_session_profiles')
+                .select('storage_state, session_storage, auth_state, account_label, detected_lang, detected_theme, validated_start_url, last_known_url, summary, validation_status, last_used_at, profile_version')
+                .eq('project_id', project.id)
+                .eq('preset_id', presetId)
+                .eq('domain', domain)
+                .eq('lang', lang)
+                .eq('theme', theme)
+                .gt('expires_at', new Date().toISOString())
+                .limit(1)
+                .single();
+            if (!data?.storage_state) {
+                sessionProfileCache.set(cacheKey, undefined);
+                return undefined;
+            }
+            const profile = {
+                storageState: decryptSessionField(data.storage_state),
+                sessionStorage: decryptSessionField(data.session_storage) ?? undefined,
+                authState: data.auth_state ?? 'unknown',
+                accountLabel: data.account_label ?? null,
+                detectedLang: data.detected_lang ?? null,
+                detectedTheme: data.detected_theme ?? null,
+                validatedStartUrl: data.validated_start_url ?? null,
+                lastKnownUrl: data.last_known_url ?? null,
+                summary: data.summary ?? null,
+                validationStatus: data.validation_status ?? 'unknown',
+                lastUsedAt: data.last_used_at ?? null,
+                profileVersion: data.profile_version ?? 1,
+            };
+            sessionProfileCache.set(cacheKey, profile);
+            return profile;
+        }
+        catch {
+            sessionProfileCache.set(cacheKey, undefined);
+            return undefined;
+        }
+    };
+    const persistSessionProfile = async (domain, lang, theme, profile) => {
+        if (!profile.storageState)
+            return;
+        const cacheKey = `${domain}:${lang}:${theme}`;
+        const storedProfile = {
+            ...profile,
+            lastUsedAt: new Date().toISOString(),
+        };
+        try {
+            await supabase
+                .from('screenshot_session_profiles')
+                .upsert({
+                project_id: project.id,
+                preset_id: presetId,
+                domain,
+                lang,
+                theme,
+                storage_state: encryptSessionField(storedProfile.storageState),
+                session_storage: encryptSessionField(storedProfile.sessionStorage) ?? null,
+                auth_state: storedProfile.authState,
+                account_label: storedProfile.accountLabel ?? null,
+                detected_lang: storedProfile.detectedLang ?? null,
+                detected_theme: storedProfile.detectedTheme ?? null,
+                validated_start_url: storedProfile.validatedStartUrl ?? null,
+                last_known_url: storedProfile.lastKnownUrl ?? null,
+                summary: storedProfile.summary ?? null,
+                validation_status: storedProfile.validationStatus,
+                last_validated_at: new Date().toISOString(),
+                last_used_at: storedProfile.lastUsedAt,
+                profile_version: storedProfile.profileVersion ?? 1,
+                expires_at: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
+            }, {
+                onConflict: 'project_id,preset_id,domain,lang,theme',
+            });
+            sessionProfileCache.set(cacheKey, storedProfile);
+        }
+        catch (error) {
+            logger.error(`Session profile persistence failed for ${domain}/${lang}/${theme}: ${error.message}`);
+        }
+    };
+    const getRunSharedAuthProfile = (startUrl) => {
+        const startOrigin = getUrlOrigin(startUrl);
+        if (startOrigin && runSharedAuthProfiles.has(startOrigin)) {
+            return runSharedAuthProfiles.get(startOrigin);
+        }
+        if (!startOrigin && rootOrigin && runSharedAuthProfiles.has(rootOrigin)) {
+            return runSharedAuthProfiles.get(rootOrigin);
+        }
+        if (!startOrigin && runSharedAuthProfiles.size === 1) {
+            return Array.from(runSharedAuthProfiles.values())[0];
+        }
+        return undefined;
+    };
+    const rememberRunSharedAuthProfile = (profile, startUrl) => {
+        const sharedProfile = deriveRunSharedAuthProfile(profile);
+        if (!sharedProfile)
+            return;
+        const keys = new Set();
+        const startOrigin = getUrlOrigin(startUrl);
+        const profileOrigin = getUrlOrigin(profile?.lastKnownUrl ?? profile?.validatedStartUrl ?? null);
+        if (startOrigin)
+            keys.add(startOrigin);
+        if (profileOrigin)
+            keys.add(profileOrigin);
+        if (rootOrigin)
+            keys.add(rootOrigin);
+        for (const key of keys) {
+            runSharedAuthProfiles.set(key, sharedProfile);
+        }
+    };
+    const persistFullPageCapture = async (params) => {
+        const { pageRun, target, lang, theme, agentResult, includeActions, includeWorkflowScreenshots } = params;
+        const pageSegment = sanitizeStorageSegment(pageRun.pageId);
+        let finalBuffer = await remoteBrowser.takeScreenshot();
+        let rawScreenshotUrl = null;
+        let browserBar;
+        try {
+            await remoteBrowser.resizeViewport(target.viewport.width, target.viewport.height);
+            await remoteBrowser.wait(300);
+            finalBuffer = await remoteBrowser.takeScreenshot();
+            if (target.deviceFrame) {
+                const rawPath = `screenshots/${auth.userId}/${runId}/${pageSegment}/${target.id}_${lang}_${theme}_raw.png`;
+                const { error } = await supabase.storage
+                    .from(BUCKET)
+                    .upload(rawPath, finalBuffer, { contentType: 'image/png', upsert: true });
+                if (!error) {
+                    rawScreenshotUrl = supabase.storage.from(BUCKET).getPublicUrl(rawPath).data.publicUrl;
+                }
+                try {
+                    const pageUrl = remoteBrowser.currentPage.url();
+                    const pageTitle = await remoteBrowser.currentPage.title();
+                    const mockupOptions = target.mockupOptions ?? {};
+                    browserBar = (mockupOptions.autoBrowserBar ?? true)
+                        ? {
+                            url: pageUrl,
+                            pageTitle,
+                            tabIconUrl: pageUrl
+                                ? `https://www.google.com/s2/favicons?domain=${new URL(pageUrl).hostname}&sz=64`
+                                : undefined,
+                        }
+                        : mockupOptions.browserBar;
+                    const localizedOptions = {
+                        ...mockupOptions,
+                        outputScale,
+                        statusBar: localizeStatusBar(mockupOptions.statusBar, lang),
+                        browserBar,
+                    };
+                    const mockupContext = await getMockupContext();
+                    finalBuffer = await applyDeviceFrame(finalBuffer, target.deviceFrame, mockupContext, localizedOptions);
+                }
+                catch (error) {
+                    logger.error(`Mockup failed for ${target.deviceFrame}: ${error.message}`);
+                }
+            }
+            finalBuffer = await applyPlanScreenshotWatermark(plan, finalBuffer);
+            const storagePath = `screenshots/${auth.userId}/${runId}/${pageSegment}/${target.id}_${lang}_${theme}.png`;
+            const { error: uploadError } = await supabase.storage
+                .from(BUCKET)
+                .upload(storagePath, finalBuffer, { contentType: 'image/png', upsert: true });
+            const screenshotUrl = uploadError
+                ? null
+                : supabase.storage.from(BUCKET).getPublicUrl(storagePath).data.publicUrl;
+            const persistedSuccess = agentResult.success && !!screenshotUrl;
+            const persistedAssessment = persistedSuccess
+                ? agentResult.assessment
+                : agentResult.success
+                    ? 'Capture completed but screenshot upload failed.'
+                    : agentResult.assessment || 'Capture failed';
+            captureResults.push({
+                url: pageRun.url,
+                lang,
+                theme,
+                captureType: 'fullpage',
+                elementName: pageRun.pageId ?? undefined,
+                targetId: target.id,
+                targetLabel: target.label,
+                deviceFrame: target.deviceFrame,
+                success: persistedSuccess,
+                assessment: persistedAssessment,
+                iterations: agentResult.iterations,
+                finalScreenshotUrl: screenshotUrl ?? undefined,
+            });
+            const costLogIds = await logAgentUsage({
+                usage: agentResult.usage,
+                lang,
+                theme,
+                captureType: 'fullpage',
+                elementName: pageRun.pageId ?? undefined,
+                targetId: target.id,
+                viewportWidth: target.viewport.width,
+                viewportHeight: target.viewport.height,
+            });
+            const captureInsert = await supabase
+                .from('captures')
+                .insert({
+                run_id: runId,
+                preset_id: presetId,
+                project_id: project.id,
+                target_id: target.id,
+                element_name: pageRun.pageId ?? null,
+                url: pageRun.url,
+                prompt: pageRun.prompt,
+                lang,
+                theme,
+                success: persistedSuccess,
+                assessment: persistedAssessment,
+                iterations: agentResult.iterations,
+                screenshot_url: screenshotUrl,
+                raw_screenshot_url: rawScreenshotUrl,
+                device_frame: target.deviceFrame ?? null,
+                capture_type: 'fullpage',
+                credits: persistedSuccess ? SCREENSHOT_CREDIT_COST : 0,
+                config: {
+                    targets,
+                    pageId: pageRun.pageId,
+                    model: resolvedModel,
+                    outputScale,
+                    actions: includeActions ? agentResult.actions : [],
+                    workflowScreenshots: includeWorkflowScreenshots ? agentResult.screenshots.length : 0,
+                },
+            })
+                .select('id')
+                .single();
+            const captureId = captureInsert.data?.id ?? null;
+            if (captureInsert.error) {
+                logger.error(`Capture insert failed: ${captureInsert.error.message}`);
+            }
+            if (persistedSuccess && captureId) {
+                successCount += 1;
+                await recordCreditUsage(supabase, {
+                    userId: auth.userId,
+                    projectId: project.id,
+                    presetId,
+                    runId,
+                    type: 'screenshot',
+                    credits: SCREENSHOT_CREDIT_COST,
+                    sourceId: captureId,
+                });
+            }
+            if (captureId && costLogIds.length > 0) {
+                await updateCostLogCaptureContext(supabase, costLogIds, {
+                    captureId,
+                    targetId: target.id,
+                    viewportWidth: target.viewport.width,
+                    viewportHeight: target.viewport.height,
+                });
+            }
+            await insertScreenshotOperationLog(supabase, {
+                runId,
+                userId: auth.userId,
+                projectId: project.id,
+                presetId,
+                captureId,
+                captureType: 'fullpage',
+                lang,
+                theme,
+                elementName: pageRun.pageId ?? undefined,
+                targetId: target.id,
+                viewportWidth: target.viewport.width,
+                viewportHeight: target.viewport.height,
+                deviceFrame: target.deviceFrame ?? null,
+            }, {
+                outcome: persistedSuccess ? 'succeeded' : 'failed',
+                outcomeReason: persistedSuccess ? null : persistedAssessment,
+                billable: persistedSuccess && !!captureId,
+                creditsCharged: persistedSuccess && captureId ? SCREENSHOT_CREDIT_COST : 0,
+                costLogIds,
+                usage: agentResult.usage,
+                metadata: {
+                    pageId: pageRun.pageId,
+                    pageUrl: pageRun.url,
+                    prompt: pageRun.prompt,
+                    runtimeStrategy: agentResult.runtimeStrategy ?? null,
+                    source: 'ws_remote_playwright',
+                    workflowScreenshotsIncluded: includeWorkflowScreenshots,
+                    actionsIncluded: includeActions,
+                },
+            });
+            void reconcilePendingBillingOperationCosts(supabase).catch(() => undefined);
+            if (!persistedSuccess) {
+                const errorType = agentResult.success
+                    ? 'storage_upload_failure'
+                    : agentResult.actions.some((action) => action.action === 'give_up')
+                        ? 'give_up'
+                        : agentResult.iterations >= maxIterations
+                            ? 'max_iterations'
+                            : 'verification_failure';
+                getServerPostHog()?.capture({
+                    distinctId: auth.userId,
+                    event: 'capture_page_error',
+                    properties: {
+                        runId,
+                        presetId,
+                        projectId: project.id,
+                        pageUrl: pageRun.url,
+                        pageId: pageRun.pageId,
+                        errorType,
+                        lang,
+                        theme,
+                        iteration: agentResult.iterations,
+                        assessment: persistedAssessment?.slice(0, 500) ?? null,
+                    },
+                });
+                if (captureId) {
+                    try {
+                        await supabase.from('agent_errors').insert({
+                            preset_id: presetId,
+                            run_id: runId,
+                            capture_id: captureId,
+                            error_type: errorType,
+                            message: persistedAssessment,
+                            description: persistedAssessment,
+                            screenshot_url: screenshotUrl,
+                            agent_context: {
+                                iterations: agentResult.iterations,
+                                maxIterations,
+                                captureTarget: {
+                                    lang,
+                                    theme,
+                                    targetLabel: target.label,
+                                    viewport: target.viewport,
+                                },
+                            },
+                        });
+                    }
+                    catch {
+                        // Non-blocking.
+                    }
+                }
+            }
+            if (persistedSuccess && captureId && screenshotUrl) {
+                await syncStudioVariantAfterCapture({
+                    supabase,
+                    projectId: project.id,
+                    presetId,
+                    targetId: target.id,
+                    lang,
+                    theme,
+                    elementName: pageRun.pageId,
+                    captureId,
+                    screenshotUrl,
+                    rawScreenshotUrl,
+                    deviceFrame: target.deviceFrame ?? null,
+                    browserBar,
+                }).catch((error) => {
+                    logger.error(`Studio sync failed: ${error.message}`);
+                });
+            }
+            if (captureId && screenshotUrl) {
+                const altText = await generateAltText({
+                    url: pageRun.url,
+                    prompt: pageRun.prompt,
+                    lang,
+                    theme,
+                    targetLabel: target.label,
+                    elementName: pageRun.pageId ?? undefined,
+                    model: resolvedModel,
+                    apiKey: getOpenRouterKey(),
+                }).catch(() => null);
+                if (altText) {
+                    await supabase
+                        .from('captures')
+                        .update({ alt_text: altText })
+                        .eq('id', captureId);
+                }
+            }
+            getServerPostHog()?.capture({
+                distinctId: auth.userId,
+                event: 'capture_page_optimization',
+                properties: {
+                    runId,
+                    projectId: project.id,
+                    presetId,
+                    targetId: target.id,
+                    pageId: pageRun.pageId,
+                    lang,
+                    theme,
+                    success: persistedSuccess,
+                    runtimeStrategy: agentResult.runtimeStrategy ?? null,
+                    deterministicRecoveryUsed: agentResult.deterministicRecoveryUsed ?? false,
+                    evaluatorUsed: agentResult.evaluatorUsed ?? false,
+                    iterationCount: agentResult.iterations,
+                    source: 'ws_remote_playwright',
+                },
+            });
+        }
+        finally {
+            captureIndex += 1;
+            await updateRunProgress();
+            sendEvent('progress', {
+                message: `[${captureIndex}/${totalCaptures}] ${lang}/${theme} · ${pageRun.pageId ?? 'main'} · ${target.label}`,
+            });
+        }
+    };
+    const persistElementCapture = async (params) => {
+        const { pageRun, element, lang, theme, result } = params;
+        try {
+            if (!result.success || !result.buffer) {
+                captureResults.push({
+                    url: pageRun.url,
+                    lang,
+                    theme,
+                    captureType: 'element',
+                    elementName: element.name,
+                    targetId: targets[0]?.id,
+                    targetLabel: targets[0]?.label,
+                    success: false,
+                    assessment: result.assessment || 'Element capture failed.',
+                    iterations: 0,
+                });
+                return;
+            }
+            const finalBuffer = await applyPlanScreenshotWatermark(plan, result.buffer);
+            const costLogIds = await logAgentUsage({
+                usage: result.usage,
+                lang,
+                theme,
+                captureType: 'element',
+                elementName: element.name,
+                targetId: targets[0]?.id,
+                viewportWidth: targets[0]?.viewport.width ?? null,
+                viewportHeight: targets[0]?.viewport.height ?? null,
+            });
+            const storagePath = `screenshots/${auth.userId}/${runId}/elements/${sanitizeStorageSegment(pageRun.pageId)}/${element.name}_${lang}_${theme}.png`;
+            const { error: uploadError } = await supabase.storage
+                .from(BUCKET)
+                .upload(storagePath, finalBuffer, { contentType: 'image/png', upsert: true });
+            if (uploadError) {
+                logger.error(`Element upload failed: ${uploadError.message}`);
+                captureResults.push({
+                    url: pageRun.url,
+                    lang,
+                    theme,
+                    captureType: 'element',
+                    elementName: element.name,
+                    targetId: targets[0]?.id,
+                    targetLabel: targets[0]?.label,
+                    success: false,
+                    assessment: uploadError.message,
+                    iterations: 0,
+                });
+                await insertScreenshotOperationLog(supabase, {
+                    runId,
+                    userId: auth.userId,
+                    projectId: project.id,
+                    presetId,
+                    captureId: null,
+                    captureType: 'element',
+                    lang,
+                    theme,
+                    elementName: element.name,
+                    targetId: targets[0]?.id,
+                    viewportWidth: targets[0]?.viewport.width ?? null,
+                    viewportHeight: targets[0]?.viewport.height ?? null,
+                    deviceFrame: null,
+                }, {
+                    outcome: 'failed',
+                    outcomeReason: uploadError.message,
+                    billable: false,
+                    creditsCharged: 0,
+                    costLogIds,
+                    usage: result.usage,
+                    metadata: {
+                        pageId: pageRun.pageId,
+                        pageUrl: pageRun.url,
+                        prompt: pageRun.prompt,
+                        source: 'ws_remote_playwright',
+                    },
+                });
+                void reconcilePendingBillingOperationCosts(supabase).catch(() => undefined);
+                return;
+            }
+            const screenshotUrl = supabase.storage.from(BUCKET).getPublicUrl(storagePath).data.publicUrl;
+            const { data: captureRow, error } = await supabase
+                .from('captures')
+                .insert({
+                run_id: runId,
+                preset_id: presetId,
+                project_id: project.id,
+                target_id: targets[0]?.id ?? null,
+                element_name: element.name,
+                url: pageRun.url,
+                prompt: pageRun.prompt,
+                lang,
+                theme,
+                success: true,
+                assessment: result.assessment,
+                screenshot_url: screenshotUrl,
+                capture_type: 'element',
+                credits: SCREENSHOT_CREDIT_COST,
+                config: {
+                    element,
+                    outputScale,
+                    pageId: pageRun.pageId,
+                },
+            })
+                .select('id')
+                .single();
+            if (error) {
+                logger.error(`Element capture insert failed: ${error.message}`);
+                return;
+            }
+            captureResults.push({
+                url: pageRun.url,
+                lang,
+                theme,
+                captureType: 'element',
+                elementName: element.name,
+                targetId: targets[0]?.id,
+                targetLabel: targets[0]?.label,
+                success: true,
+                assessment: result.assessment,
+                iterations: 0,
+                finalScreenshotUrl: screenshotUrl,
+            });
+            successCount += 1;
+            await recordCreditUsage(supabase, {
+                userId: auth.userId,
+                projectId: project.id,
+                presetId,
+                runId,
+                type: 'screenshot',
+                credits: SCREENSHOT_CREDIT_COST,
+                sourceId: captureRow.id,
+            });
+            await updateCostLogCaptureContext(supabase, costLogIds, {
+                captureId: captureRow.id,
+                targetId: targets[0]?.id ?? null,
+                viewportWidth: targets[0]?.viewport.width ?? null,
+                viewportHeight: targets[0]?.viewport.height ?? null,
+            });
+            await insertScreenshotOperationLog(supabase, {
+                runId,
+                userId: auth.userId,
+                projectId: project.id,
+                presetId,
+                captureId: captureRow.id,
+                captureType: 'element',
+                lang,
+                theme,
+                elementName: element.name,
+                targetId: targets[0]?.id,
+                viewportWidth: targets[0]?.viewport.width ?? null,
+                viewportHeight: targets[0]?.viewport.height ?? null,
+                deviceFrame: null,
+            }, {
+                outcome: 'succeeded',
+                outcomeReason: null,
+                billable: true,
+                creditsCharged: SCREENSHOT_CREDIT_COST,
+                costLogIds,
+                usage: result.usage,
+                metadata: {
+                    pageId: pageRun.pageId,
+                    pageUrl: pageRun.url,
+                    prompt: pageRun.prompt,
+                    source: 'ws_remote_playwright',
+                },
+            });
+            void reconcilePendingBillingOperationCosts(supabase).catch(() => undefined);
+            await syncStudioVariantAfterCapture({
+                supabase,
+                projectId: project.id,
+                presetId,
+                targetId: targets[0]?.id ?? null,
+                lang,
+                theme,
+                elementName: element.name,
+                captureId: captureRow.id,
+                screenshotUrl,
+                matchTargetId: false,
+            }).catch(() => { });
+            const altText = await generateAltText({
+                url: pageRun.url,
+                prompt: pageRun.prompt,
+                lang,
+                theme,
+                targetLabel: targets[0]?.label,
+                elementName: element.name,
+                model: resolvedModel,
+                apiKey: getOpenRouterKey(),
+            }).catch(() => null);
+            if (altText) {
+                await supabase
+                    .from('captures')
+                    .update({ alt_text: altText })
+                    .eq('id', captureRow.id);
+            }
+        }
+        finally {
+            captureIndex += 1;
+            await updateRunProgress();
+            sendEvent('progress', {
+                message: `[${captureIndex}/${totalCaptures}] ${lang}/${theme} · ${pageRun.pageId ?? 'main'} · element:${element.name}`,
+            });
+        }
+    };
+    sendEvent('capture_plan', {
+        variants: variantPlan.map((variant) => ({
+            key: variant.key,
+            lang: variant.lang,
+            theme: variant.theme,
+            pages: variant.pages,
+        })),
+        totalCaptures,
+    });
+    const { identities: sharedPageIdentities } = await inferPageIdentitiesWithLLM(variantPlan[0]?.pages ?? [], resolvedModel, getOpenRouterKey(), Object.keys(providerPreferences).length > 0 ? providerPreferences : undefined);
+    try {
+        for (const [variantIndex, variant] of variantPlan.entries()) {
+            if (aborted)
+                throw new Error('Client disconnected');
+            const { lang, theme, pages: variantPages } = variant;
+            const firstTarget = targets[0];
+            const firstPage = variantPages[0];
+            const variantCaptureStartIndex = captureIndex;
+            const expectedVariantCaptureCount = (variantPages.length * targets.length) + elements.length;
+            try {
+                const firstDomain = getCaptureUrlHostname(firstPage.url);
+                const persistedSessionProfile = await loadSessionProfileForVariant(firstDomain, lang, theme);
+                const bootstrapSelection = buildSessionBootstrapProfile({
+                    runAuthProfile: getRunSharedAuthProfile(firstPage.url),
+                    persistedVariantProfile: persistedSessionProfile,
+                    requestedLang: lang,
+                    requestedTheme: theme,
+                    startUrl: firstPage.url,
+                });
+                let bootstrapProfile = bootstrapSelection.profile;
+                if (runSharedStorageState) {
+                    bootstrapProfile = bootstrapProfile
+                        ? {
+                            ...bootstrapProfile,
+                            storageState: runSharedStorageState,
+                            sessionStorage: runSharedSessionStorage ?? bootstrapProfile.sessionStorage,
+                        }
+                        : {
+                            storageState: runSharedStorageState,
+                            sessionStorage: runSharedSessionStorage,
+                            authState: 'authenticated',
+                            accountLabel: null,
+                            detectedLang: null,
+                            detectedTheme: null,
+                            validatedStartUrl: firstPage.url,
+                            lastKnownUrl: firstPage.url,
+                            summary: 'Reusing live storage state from the previous successful variant.',
+                            validationStatus: 'unknown',
+                            lastUsedAt: null,
+                            profileVersion: 1,
+                        };
+                }
+                sendEvent('progress', {
+                    message: `Variant ${variantIndex + 1}/${variantPlan.length}: ${lang}/${theme}`,
+                });
+                await remoteBrowser.recreateContext({
+                    viewport: firstTarget.viewport,
+                    deviceScaleFactor: outputScale,
+                    lang,
+                    colorScheme: theme,
+                    storageState: bootstrapProfile?.storageState,
+                });
+                await remoteBrowser.prepareSessionStorage(bootstrapProfile?.sessionStorage, { replace: false });
+                let activeSessionProfile = bootstrapProfile;
+                let carryoverContext;
+                let variantState = createVariantCaptureState(variantPages, sharedPageIdentities);
+                const elementAssignments = resolveIsolatedElementAssignments({
+                    elements,
+                    pageRuns: variantPages,
+                });
+                const variantStartSelectorMemory = resolveScopedSelectorMemory(await loadSelectorMemoryForVariant(firstDomain, lang, theme), {
+                    pageId: firstPage.pageId,
+                    pageIdentity: sharedPageIdentities[firstPage.pageId ?? 'main'] ?? null,
+                    pageUrl: firstPage.url,
+                });
+                if (!urlMatchesCaptureTarget(remoteBrowser.currentPage.url(), firstPage.url)) {
+                    await remoteBrowser.navigateTo(firstPage.url);
+                    await remoteBrowser.wait(500);
+                    await remoteBrowser.dismissOverlays().catch(() => undefined);
+                }
+                const variantLanguagePreflight = await ensureScreenshotVariantLanguage({
+                    browser: remoteBrowser,
+                    requestedLang: lang,
+                    requestedTheme: theme,
+                    startUrl: firstPage.url,
+                    profile: activeSessionProfile,
+                    credentials,
+                    selectorMemory: variantStartSelectorMemory,
+                    langInstructions: config.langInstructions,
+                    themeInstructions: config.themeInstructions,
+                    onLog: (message) => {
+                        sendEvent('progress', { message });
+                    },
+                    rebaseToStartUrl: async () => {
+                        await remoteBrowser.navigateTo(firstPage.url);
+                        await remoteBrowser.wait(500);
+                        await remoteBrowser.dismissOverlays().catch(() => undefined);
+                    },
+                    runLanguageSwitchAgent: async ({ languageState, themeState }) => {
+                        return runAgent(remoteBrowser, {
+                            url: remoteBrowser.currentPage.url() || firstPage.url,
+                            prompt: [
+                                `Prepare the current page so the UI is rendered in "${lang}" and the theme is "${theme}".`,
+                                `Current inspection: language=${languageState?.detected ?? 'unknown'}; theme=${themeState?.detected ?? 'unknown'}.`,
+                                firstPage.prompt,
+                            ].join(' '),
+                            dark: theme === 'dark',
+                            langs: [lang],
+                            outputDir: '/tmp/autokap-ws',
+                            headed: false,
+                            viewport: firstTarget.viewport,
+                            maxIterations: Math.min(maxIterations, 10),
+                            model: resolvedModel,
+                            fallbackModel: resolvedFallback,
+                            visionModel: resolvedVisionModel,
+                            providerPreferences: Object.keys(providerPreferences).length > 0 ? providerPreferences : undefined,
+                            credentials,
+                            currentLang: lang,
+                            currentTheme: theme,
+                            selectorMemory: Object.keys(variantStartSelectorMemory).length > 0 ? variantStartSelectorMemory : undefined,
+                            sessionProfile: activeSessionProfile,
+                            runHints: runHints && runHints.length > 0 ? runHints : undefined,
+                            runMode: 'language_preflight',
+                            abortSignal: abortController.signal,
+                        }, getOpenRouterKey());
+                    },
+                });
+                if (variantLanguagePreflight.selectorUpdates.length > 0) {
+                    const scopedUpdates = scopeSelectorMemoryUpdates(variantLanguagePreflight.selectorUpdates, {
+                        pageId: firstPage.pageId,
+                        pageIdentity: sharedPageIdentities[firstPage.pageId ?? 'main'] ?? null,
+                        pageUrl: firstPage.url,
+                    });
+                    const cacheKey = `${firstDomain}:${lang}:${theme}`;
+                    selectorMemoryCache.set(cacheKey, applySelectorMemoryUpdates(selectorMemoryCache.get(cacheKey) ?? {}, scopedUpdates));
+                    void persistScreenshotSelectorMemoryUpdates(supabase, {
+                        projectId: project.id,
+                        presetId,
+                        domain: firstDomain,
+                        lang,
+                        theme,
+                    }, scopedUpdates).catch(() => undefined);
+                }
+                if (!variantLanguagePreflight.ok) {
+                    throw new Error(variantLanguagePreflight.reason
+                        ?? `Language preflight failed before starting the main workflow for ${lang}/${theme}.`);
+                }
+                if (activeSessionProfile?.authState === 'authenticated'
+                    && activeSessionProfile.validationStatus !== 'invalid') {
+                    rememberRunSharedAuthProfile(activeSessionProfile, remoteBrowser.currentPage.url());
+                }
+                for (const [pageIndex, pageRun] of variantPages.entries()) {
+                    if (aborted)
+                        throw new Error('Client disconnected');
+                    const pageId = pageRun.pageId ?? 'main';
+                    const pageDomain = getCaptureUrlHostname(pageRun.url);
+                    variantState = markVariantCaptureInProgress(variantState, pageRun.pageId);
+                    const variantManifest = buildVariantManifestContext({
+                        state: variantState,
+                        currentPageRun: pageRun,
+                    });
+                    const selectorMemory = resolveScopedSelectorMemory(mergeSelectorMemory(await loadSelectorMemoryForVariant(pageDomain, lang, theme), carryoverContext?.selectorMemory), {
+                        pageId: pageRun.pageId,
+                        pageIdentity: variantManifest.currentPageIdentity ?? null,
+                        pageUrl: pageRun.url,
+                    });
+                    const buildConfig = (viewport = firstTarget.viewport) => {
+                        const nextConfig = {
+                            url: pageRun.url,
+                            prompt: pageRun.prompt,
+                            dark: theme === 'dark',
+                            langs: [lang],
+                            outputDir: '/tmp/autokap-ws',
+                            headed: false,
+                            viewport,
+                            maxIterations,
+                            model: resolvedModel,
+                            fallbackModel: resolvedFallback,
+                            visionModel: resolvedVisionModel,
+                            providerPreferences: Object.keys(providerPreferences).length > 0 ? providerPreferences : undefined,
+                            credentials,
+                            langInstructions: config.langInstructions,
+                            themeInstructions: config.themeInstructions,
+                            currentLang: lang,
+                            currentTheme: theme,
+                            reasoningLocale: config.reasoningLocale,
+                            reasoningEffort: config.reasoningEffort ?? 'medium',
+                            runHints: runHints && runHints.length > 0 ? runHints : undefined,
+                            selectorMemory: Object.keys(selectorMemory).length > 0 ? selectorMemory : undefined,
+                            sessionProfile: activeSessionProfile,
+                            handoffContext: carryoverContext,
+                            variantManifest,
+                            runMode: 'capture',
+                            analyticsId: auth.userId,
+                            enableDeterministicRecovery: true,
+                            enableRecoveryEvaluator: true,
+                            enableSalienceCompression: true,
+                            abortSignal: abortController.signal,
+                        };
+                        if (variantIndex > 1) {
+                            const reference = liveVariantReference.get(pageId);
+                            if (reference) {
+                                nextConfig.variantReference = reference;
+                            }
+                        }
+                        return nextConfig;
+                    };
+                    sendEvent('progress', {
+                        message: `Preparing ${lang}/${theme} · ${pageId} (${pageIndex + 1}/${variantPages.length})`,
+                    });
+                    let primaryAgentResult = null;
+                    const currentUrl = remoteBrowser.currentPage.url();
+                    const canUseSequentialHandoff = !!(carryoverContext
+                        && shouldUseSequentialPageHandoff({
+                            pageIndex,
+                            currentUrl,
+                            pageUrl: pageRun.url,
+                            previousPageId: carryoverContext.previousPageId,
+                            pageId: pageRun.pageId,
+                            previousPrompt: carryoverContext.previousPrompt,
+                            pagePrompt: pageRun.prompt,
+                        }));
+                    const reuseLiveState = shouldReuseLivePageState({
+                        pageIndex,
+                        presetRootUrl: projectUrl,
+                        pageUrl: pageRun.url,
+                        currentUrl,
+                        isAuthenticated: activeSessionProfile?.authState === 'authenticated',
+                    });
+                    if (canUseSequentialHandoff) {
+                        const readiness = await verifyCaptureReadiness(remoteBrowser, buildConfig(), getOpenRouterKey(), {
+                            assessment: 'Sequential handoff preflight: approve only if the current live page already satisfies this capture.',
+                            stepNumber: 0,
+                        }).catch(() => null);
+                        if (readiness?.verified) {
+                            primaryAgentResult = buildPreverifiedAgentResult('Capture approved directly from sequential handoff state.', readiness);
+                        }
+                    }
+                    if (!primaryAgentResult && !canUseSequentialHandoff && !reuseLiveState && !urlMatchesCaptureTarget(currentUrl, pageRun.url)) {
+                        await remoteBrowser.navigateTo(pageRun.url);
+                        await remoteBrowser.wait(500);
+                        await remoteBrowser.dismissOverlays().catch(() => undefined);
+                    }
+                    if (!primaryAgentResult && variantIndex > 0) {
+                        const recordedActions = liveVariantActions.get(pageId);
+                        if (recordedActions && recordedActions.length > 0) {
+                            sendEvent('progress', {
+                                message: `Replaying first successful variant for ${lang}/${theme} · ${pageId}`,
+                            });
+                            primaryAgentResult = await replayAgent(remoteBrowser, buildConfig(), getOpenRouterKey(), recordedActions, { allowFullAgentFallback: true }).catch((error) => makeFailedAgentResult(error.message));
+                        }
+                    }
+                    if (!primaryAgentResult) {
+                        primaryAgentResult = await runAgent(remoteBrowser, buildConfig(), getOpenRouterKey()).catch((error) => makeFailedAgentResult(error.message));
+                    }
+                    const preparedPageUrl = remoteBrowser.currentPage.url() || pageRun.url;
+                    await persistFullPageCapture({
+                        pageRun,
+                        target: firstTarget,
+                        lang,
+                        theme,
+                        agentResult: primaryAgentResult,
+                        includeActions: true,
+                        includeWorkflowScreenshots: true,
+                    });
+                    for (const target of targets.slice(1)) {
+                        await remoteBrowser.resizeViewport(target.viewport.width, target.viewport.height);
+                        await remoteBrowser.wait(250);
+                        await remoteBrowser.dismissOverlays().catch(() => undefined);
+                        let targetResult;
+                        const targetConfig = buildConfig(target.viewport);
+                        const targetReadiness = await verifyCaptureReadiness(remoteBrowser, targetConfig, getOpenRouterKey(), {
+                            assessment: 'Same-session target recheck: approve only if the resized page still satisfies the capture.',
+                            stepNumber: 0,
+                        }).catch(() => null);
+                        if (targetReadiness?.verified) {
+                            targetResult = buildPreverifiedAgentResult('Capture approved after same-session target recheck.', targetReadiness);
+                        }
+                        else {
+                            targetResult = await replayAgent(remoteBrowser, targetConfig, getOpenRouterKey(), primaryAgentResult.actions, { allowFullAgentFallback: false }).catch((error) => makeFailedAgentResult(error.message));
+                        }
+                        await persistFullPageCapture({
+                            pageRun,
+                            target,
+                            lang,
+                            theme,
+                            agentResult: targetResult,
+                            includeActions: false,
+                            includeWorkflowScreenshots: false,
+                        });
+                        await restorePreparedPageState(remoteBrowser, firstTarget.viewport, preparedPageUrl);
+                    }
+                    if (primaryAgentResult.success) {
+                        const recorded = recordValidatedVariantCapture({
+                            state: variantState,
+                            capture: {
+                                pageId,
+                                prompt: pageRun.prompt,
+                                url: pageRun.url,
+                                assessment: primaryAgentResult.assessment,
+                                fingerprint: primaryAgentResult.verification?.pageFingerprint ?? null,
+                                identity: variantManifest.currentPageIdentity ?? null,
+                            },
+                        });
+                        variantState = recorded.state;
+                        if (recorded.duplicateOfPageId) {
+                            const blockingReason = `Duplicate capture blocked: page "${pageId}" matches previously validated page "${recorded.duplicateOfPageId}".`;
+                            variantState = markVariantCaptureBlocked({
+                                state: variantState,
+                                pageId,
+                                reason: blockingReason,
+                            });
+                            primaryAgentResult = {
+                                ...primaryAgentResult,
+                                success: false,
+                                assessment: blockingReason,
+                            };
+                        }
+                    }
+                    if (primaryAgentResult.success) {
+                        if (primaryAgentResult.actions.length > 0 && !liveVariantActions.has(pageId)) {
+                            liveVariantActions.set(pageId, primaryAgentResult.actions);
+                        }
+                        if (!liveVariantReference.has(pageId)) {
+                            liveVariantReference.set(pageId, {
+                                finalUrl: remoteBrowser.currentPage.url() || pageRun.url,
+                                assessment: primaryAgentResult.assessment,
+                                pageTitle: await remoteBrowser.currentPage.title().catch(() => ''),
+                                actions: primaryAgentResult.actions,
+                            });
+                        }
+                        if (primaryAgentResult.actions.length > 0) {
+                            const scopeContext = {
+                                pageId: pageRun.pageId,
+                                pageIdentity: variantManifest.currentPageIdentity ?? null,
+                                pageUrl: pageRun.url,
+                            };
+                            const selectorUpdates = scopeSelectorMemoryUpdates(extractSelectorUpdates(primaryAgentResult.actions), scopeContext);
+                            if (selectorUpdates.length > 0) {
+                                const cacheKey = `${pageDomain}:${lang}:${theme}`;
+                                selectorMemoryCache.set(cacheKey, applySelectorMemoryUpdates(selectorMemoryCache.get(cacheKey) ?? {}, selectorUpdates));
+                                void persistScreenshotSelectorMemoryUpdates(supabase, {
+                                    projectId: project.id,
+                                    presetId,
+                                    domain: pageDomain,
+                                    lang,
+                                    theme,
+                                }, selectorUpdates).catch(() => undefined);
+                            }
+                        }
+                        const pageElements = elementAssignments
+                            .filter((assignment) => assignment.pageId === pageId)
+                            .map((assignment) => assignment.element);
+                        if (pageElements.length > 0) {
+                            await restorePreparedPageState(remoteBrowser, firstTarget.viewport, preparedPageUrl);
+                            await remoteBrowser.forceLoadLazyImages({ timeout: 8000 }).catch(() => undefined);
+                        }
+                        for (const element of pageElements) {
+                            const elementResult = await captureIsolatedElement(remoteBrowser, element, getOpenRouterKey(), resolvedModel).catch((error) => {
+                                logger.error(`Element "${element.name}" capture failed: ${error.message}`);
+                                return null;
+                            });
+                            if (elementResult) {
+                                await persistElementCapture({
+                                    pageRun,
+                                    element,
+                                    lang,
+                                    theme,
+                                    result: elementResult,
+                                });
+                            }
+                            else {
+                                captureResults.push({
+                                    url: pageRun.url,
+                                    lang,
+                                    theme,
+                                    captureType: 'element',
+                                    elementName: element.name,
+                                    targetId: targets[0]?.id,
+                                    targetLabel: targets[0]?.label,
+                                    success: false,
+                                    assessment: `Element capture failed for ${element.name}.`,
+                                    iterations: 0,
+                                });
+                                captureIndex += 1;
+                                await updateRunProgress();
+                                sendEvent('progress', {
+                                    message: `[${captureIndex}/${totalCaptures}] ${lang}/${theme} · ${pageRun.pageId ?? 'main'} · element:${element.name} failed`,
+                                });
+                            }
+                        }
+                        const storageState = await remoteBrowser.exportStorageState().catch(() => undefined);
+                        const sessionStorage = await remoteBrowser.exportSessionStorage().catch(() => undefined);
+                        const currentUrl = remoteBrowser.currentPage.url() || preparedPageUrl;
+                        activeSessionProfile = buildPersistableProfile(activeSessionProfile, storageState, sessionStorage, currentUrl, lang, theme);
+                        if (activeSessionProfile.storageState) {
+                            runSharedStorageState = activeSessionProfile.storageState;
+                            runSharedSessionStorage = activeSessionProfile.sessionStorage;
+                            await persistSessionProfile(pageDomain, lang, theme, activeSessionProfile);
+                        }
+                        rememberRunSharedAuthProfile(activeSessionProfile, currentUrl);
+                        carryoverContext = await buildHandoffContext({
+                            browser: remoteBrowser,
+                            pageRun,
+                            profile: activeSessionProfile,
+                            lang,
+                            theme,
+                            selectorMemory,
+                            actions: primaryAgentResult.actions,
+                        });
+                    }
+                    else {
+                        variantState = markVariantCaptureBlocked({
+                            state: variantState,
+                            pageId,
+                            reason: primaryAgentResult.assessment || `Capture failed for ${pageId}.`,
+                        });
+                        carryoverContext = undefined;
+                    }
+                }
+                const variantValidation = validateVariantCaptureState(variantState);
+                if (!variantValidation.ok) {
+                    sendEvent('progress', {
+                        message: `Variant ${lang}/${theme} completed with blocking issues: `
+                            + [
+                                ...variantValidation.missingPages.map((pageId) => `missing ${pageId}`),
+                                ...variantValidation.blockedPages.map((entry) => `blocked ${entry.pageId}`),
+                                ...variantValidation.duplicatePageIds.map((entry) => `duplicate ${entry.pageId}->${entry.duplicateOfPageId}`),
+                            ].join(', '),
+                    });
+                }
+                sendEvent('variant_complete', {
+                    lang,
+                    theme,
+                    success: variantValidation.ok,
+                    reason: variantValidation.ok ? null : 'Variant completed with blocking issues.',
+                });
+            }
+            catch (error) {
+                if (aborted)
+                    throw error;
+                const message = error.message;
+                logger.error(`Variant ${lang}/${theme} failed: ${message}`);
+                const consumedCaptures = captureIndex - variantCaptureStartIndex;
+                const remainingCaptures = Math.max(0, expectedVariantCaptureCount - consumedCaptures);
+                if (remainingCaptures > 0) {
+                    captureIndex += remainingCaptures;
+                    await updateRunProgress();
+                }
+                getServerPostHog()?.capture({
+                    distinctId: auth.userId,
+                    event: 'capture_variant_error',
+                    properties: {
+                        runId,
+                        presetId,
+                        projectId: project.id,
+                        lang,
+                        theme,
+                        error: message.slice(0, 500),
+                        variantIndex,
+                        source: 'ws_remote_playwright',
+                    },
+                });
+                sendEvent('progress', {
+                    message: `Variant ${lang}/${theme} failed: ${message}`,
+                });
+                sendEvent('variant_complete', {
+                    lang,
+                    theme,
+                    success: false,
+                    reason: message,
+                });
+                continue;
+            }
+        }
+    }
+    catch (error) {
+        const message = error.message;
+        logger.error(`Capture run failed: ${message}`);
+        await supabase
+            .from('capture_runs')
+            .update({
+            status: 'failed',
+            error_message: message,
+            completed_at: new Date().toISOString(),
+        })
+            .eq('id', runId);
+        sendEvent('error', { message });
+        await finalizeRunSideEffects();
+        remoteBrowser.destroy();
+        await closeMockup();
+        return;
+    }
+    await supabase
+        .from('capture_runs')
+        .update({
+        status: 'completed',
+        progress_current: totalCaptures,
+        credits_used: successCount,
+        completed_at: new Date().toISOString(),
+    })
+        .eq('id', runId);
+    getServerPostHog()?.capture({
+        distinctId: auth.userId,
+        event: 'capture_run_optimization_summary',
+        properties: {
+            runId,
+            presetId,
+            projectId: project.id,
+            successCount,
+            totalCaptures,
+            source: 'ws_remote_playwright',
+        },
+    });
+    sendEvent('done', { summary: { successes: successCount, total: totalCaptures } });
+    if (plan.entitlements.captureCompleteWebhook) {
+        try {
+            const webhookConfig = await getProjectWebhookConfig(supabase, project.id);
+            if (webhookConfig) {
+                await dispatchProjectCaptureWebhook({
+                    config: webhookConfig,
+                    payload: buildCaptureWebhookPayload({
+                        runId,
+                        projectId: project.id,
+                        presetId,
+                        results: captureResults,
+                    }),
+                });
+            }
+        }
+        catch {
+            // Non-blocking.
+        }
+    }
+    await finalizeRunSideEffects();
+    remoteBrowser.destroy();
+    await closeMockup();
+    logger.success(`Run ${runId} completed: ${successCount}/${totalCaptures}`);
+}
+function urlsRoughlyMatch(left, right) {
+    return urlsPointToSameCaptureState(left, right);
+}
+async function loadRunHints(supabase, presetId) {
+    try {
+        const { data } = await supabase
+            .from('agent_errors')
+            .select('error_type, message, user_response, created_at')
+            .eq('preset_id', presetId)
+            .order('created_at', { ascending: false })
+            .limit(10);
+        const hints = buildAgentRunHints((data ?? []));
+        return hints.length > 0 ? hints : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function buildPersistableProfile(previousProfile, storageState, sessionStorage, currentUrl, lang, theme) {
+    return {
+        storageState,
+        sessionStorage,
+        authState: previousProfile?.authState ?? inferAuthState(storageState, sessionStorage),
+        accountLabel: previousProfile?.accountLabel ?? null,
+        detectedLang: lang,
+        detectedTheme: theme,
+        validatedStartUrl: previousProfile?.validatedStartUrl ?? currentUrl,
+        lastKnownUrl: currentUrl,
+        summary: previousProfile?.summary ?? 'Validated browser state captured from a successful WS-driven run.',
+        validationStatus: previousProfile?.validationStatus ?? 'unknown',
+        lastUsedAt: new Date().toISOString(),
+        profileVersion: previousProfile?.profileVersion ?? 1,
+    };
+}
+function inferAuthState(storageState, sessionStorage) {
+    const structuredStorageState = storageState && typeof storageState === 'object' && !Array.isArray(storageState)
+        ? storageState
+        : undefined;
+    const cookieCount = structuredStorageState?.cookies?.length ?? 0;
+    const originCount = structuredStorageState?.origins?.length ?? 0;
+    const sessionOriginCount = sessionStorage ? Object.keys(sessionStorage).length : 0;
+    return cookieCount > 0 || originCount > 0 || sessionOriginCount > 0
+        ? 'authenticated'
+        : 'unknown';
+}
+function buildPreverifiedAgentResult(assessment, verification) {
+    return {
+        success: true,
+        screenshotPath: null,
+        screenshots: [],
+        iterations: 0,
+        actions: [],
+        assessment,
+        usage: verification.usage ? [verification.usage] : [],
+        runtimeStrategy: 'preverified_handoff',
+        deterministicRecoveryUsed: false,
+        evaluatorUsed: false,
+        verification,
+    };
+}
+function makeFailedAgentResult(message) {
+    return {
+        success: false,
+        screenshotPath: null,
+        assessment: message,
+        iterations: 0,
+        actions: [],
+        screenshots: [],
+        usage: [],
+    };
+}
+async function buildHandoffContext(params) {
+    const handoffArtifacts = buildSequentialHandoffArtifacts(params.actions ?? []);
+    return {
+        previousPageId: params.pageRun.pageId,
+        previousPrompt: params.pageRun.prompt,
+        currentUrl: params.browser.currentPage.url() || params.pageRun.url,
+        pageTitle: await params.browser.currentPage.title().catch(() => null),
+        authState: params.profile.authState,
+        accountLabel: params.profile.accountLabel ?? null,
+        currentLang: params.lang,
+        currentTheme: params.theme,
+        summary: `Continue from the validated live state reached for ${params.pageRun.pageId ?? 'main'}.`,
+        selectorHints: handoffArtifacts.selectorHints,
+        navigationHints: [],
+        selectorMemory: mergeSelectorMemory(params.selectorMemory, handoffArtifacts.selectorMemory),
+    };
+}
+async function restorePreparedPageState(browser, viewport, preparedPageUrl) {
+    await browser.resizeViewport(viewport.width, viewport.height);
+    if (!urlsRoughlyMatch(browser.currentPage.url(), preparedPageUrl)) {
+        await browser.navigateTo(preparedPageUrl);
+    }
+    await browser.dismissOverlays().catch(() => undefined);
+    await browser.wait(250);
+}
+//# sourceMappingURL=ws-handler.js.map