autokap 1.0.2 → 1.0.4

package/dist/clip-orchestrator.js

@@ -1,950 +0,0 @@
-import { mkdtemp } from 'node:fs/promises';
-import os from 'node:os';
-import path from 'node:path';
-import { logger } from './logger.js';
-import { createBasePlan, createVariantPrefixPlan, verifyAndPatchPlan, recordPlan, runVariantPreflight, } from './video-agent.js';
-import { navigateWithAgent, } from './hybrid-navigator.js';
-import { postProcessClipRecording } from './clip-postprocess.js';
-import { createAbortError, getAbortMessage } from './abort.js';
-// ── Helpers ──────────────────────────────────────────────────────────
-/**
- * Merge two abort signals into one that fires when either fires.
- */
-function mergeAbortSignals(a, b) {
-    const controller = new AbortController();
-    const onAbort = () => controller.abort(a.aborted ? a.reason : b.reason);
-    if (a.aborted || b.aborted) {
-        onAbort();
-    }
-    else {
-        a.addEventListener('abort', onAbort, { once: true });
-        b.addEventListener('abort', onAbort, { once: true });
-    }
-    return controller.signal;
-}
-/**
- * Convert technical failure messages into user-friendly descriptions.
- */
-function humanizeClipFailure(raw, phase, subphase) {
-    // Language/theme variant failures
-    if (/variant.*not active|lang=\w+.*detected=\w+/i.test(raw)) {
-        const langMatch = raw.match(/lang=(\w+),\s*detected=(\w+)/);
-        if (langMatch) {
-            return `Could not switch the app to "${langMatch[1]}" — the page stayed in "${langMatch[2]}". Check that the app has a language selector accessible from the current page, or add language switch instructions in your preset settings.`;
-        }
-        return `Could not activate the requested language/theme. Check that the app has accessible language/theme controls, or add switch instructions in your preset settings.`;
-    }
-    // Timeout failures
-    if (/timed?\s*out|timeout/i.test(raw)) {
-        if (subphase === 'prepared_variant') {
-            return 'The language/theme switch took too long. The app may not have a language selector on this page, or the AI model failed to interact with it. Try adding explicit language switch instructions.';
-        }
-        if (phase === 'preflight') {
-            return 'Setting up the correct language/theme took too long. Try adding explicit switch instructions in your preset settings.';
-        }
-        if (phase === 'recording') {
-            return 'Recording timed out — the interaction may be too complex or the page was loading too slowly.';
-        }
-        return `The operation timed out during ${phase ?? 'execution'}. The page may be slow or unresponsive.`;
-    }
-    // Navigation failures
-    if (/navigation failed/i.test(raw)) {
-        if (/login|auth|sign.?in/i.test(raw)) {
-            return 'Could not log into the app. Check that the stored credentials are correct.';
-        }
-        return 'Could not navigate to the target page. Check the URL and navigation instructions.';
-    }
-    // Selector/element not found
-    if (/absent from.*observation|selector.*not found|cannot resolve/i.test(raw)) {
-        const selectorMatch = raw.match(/(?:target|selector)\s+"([^"]+)"/);
-        return selectorMatch
-            ? `The element "${selectorMatch[1]}" was not found on the page. It may have a different label or not be visible at this point. Check the recording instructions.`
-            : 'An expected UI element was not found on the page. Check the recording instructions — the element may have a different name or not be visible.';
-    }
-    // Planning failures
-    if (/planning failed/i.test(raw)) {
-        return 'The AI could not plan the interaction steps. Try simplifying the recording instructions or breaking them into smaller clips.';
-    }
-    // Post-processing
-    if (/post-?processing failed/i.test(raw)) {
-        return 'The clip was recorded but post-processing (GIF/MP4 conversion) failed. Try again.';
-    }
-    // No video produced
-    if (/no video file/i.test(raw)) {
-        return 'The recording produced no video. The interaction may have been too fast or the page did not react visibly.';
-    }
-    // Fallback: return raw but clean up technical noise
-    return raw
-        .replace(/Dry-run failed:\s*/gi, '')
-        .replace(/Clip variant \S+ /gi, '')
-        .replace(/\bafter \d+ms\b/gi, '')
-        .trim();
-}
-function buildVariantId(targetId, lang, theme) {
-    return `${targetId}:${lang}:${theme}`;
-}
-/**
- * Build a navigation cache key for reusing the prepared state of an identical variant.
- * Theme is part of the key because many apps require an in-app theme switch and
- * cannot safely share a light-mode navigation state with a dark-mode variant.
- */
-function buildNavCacheKey(clipId, targetId, lang, theme) {
-    return `${clipId}:${targetId}:${lang}:${theme}`;
-}
-const CLIP_PHASE_MAX_ATTEMPTS = 2;
-function isRetryableClipVariantFailure(phase, reason, failedSubphase) {
-    // Dry-run semantic failures (wrong selector, wrong page) are not retryable,
-    // but environment/variant preparation timeouts are retryable.
-    if (phase === 'dry_run') {
-        return failedSubphase === 'prepared_variant'
-            && /\b(timeout|timed out|network|socket|context closed)\b/i.test(reason);
-    }
-    return /\b(timeout|timed out|stale verification snapshot|temporary|network|net::|socket|navigation failed|page closed|context closed)\b/i.test(reason);
-}
-function computeClipPhaseTimeoutMs(phase, clipOptions) {
-    const maxDurationSec = Math.max(1, Math.round(clipOptions?.maxDurationSec ?? 8));
-    switch (phase) {
-        case 'preflight':
-            // Preflight may need to: detect variant state, try 4 deterministic fallbacks
-            // (controls, storage, locale URL, rebase), then spawn an agent repair lane
-            // that navigates to settings and switches language/theme. 30s was far too
-            // aggressive — the agent repair lane alone needs 30-60s.
-            return Math.max(120_000, Math.round(maxDurationSec * 10_000));
-        case 'planning':
-            return Math.max(90_000, Math.round(maxDurationSec * 8_000));
-        case 'dry_run':
-            return Math.max(180_000, Math.round(maxDurationSec * 18_000));
-        case 'recording':
-            return Math.max(90_000, Math.round(maxDurationSec * 12_000));
-        case 'postprocess':
-            return Math.max(45_000, Math.round(maxDurationSec * 4_000));
-    }
-}
-function createPhaseAttemptSignal(parentSignal, timeoutMs, variantId, phase) {
-    const controller = new AbortController();
-    const onParentAbort = () => {
-        controller.abort(parentSignal?.reason ?? createAbortError(`Clip variant ${variantId} cancelled.`));
-    };
-    if (parentSignal) {
-        if (parentSignal.aborted) {
-            controller.abort(parentSignal.reason ?? createAbortError(`Clip variant ${variantId} cancelled.`));
-        }
-        else {
-            parentSignal.addEventListener('abort', onParentAbort, { once: true });
-        }
-    }
-    const timer = setTimeout(() => {
-        controller.abort(createAbortError(`Clip variant ${variantId} ${phase} timed out after ${timeoutMs}ms.`));
-    }, timeoutMs);
-    return {
-        signal: controller.signal,
-        cleanup: () => {
-            clearTimeout(timer);
-            parentSignal?.removeEventListener('abort', onParentAbort);
-        },
-    };
-}
-async function executeClipPhase(params) {
-    const timeoutMs = computeClipPhaseTimeoutMs(params.phase, params.clipOptions);
-    for (let attempt = 1; attempt <= CLIP_PHASE_MAX_ATTEMPTS; attempt += 1) {
-        const { signal, cleanup } = createPhaseAttemptSignal(params.parentSignal, timeoutMs, params.variantId, params.phase);
-        const startedAt = Date.now();
-        try {
-            const result = await params.run(signal, attempt, { timeoutMs, startedAt });
-            if (result.ok) {
-                return result;
-            }
-            const retryable = isRetryableClipVariantFailure(params.phase, result.reason, result.failedSubphase);
-            if (!retryable || attempt === CLIP_PHASE_MAX_ATTEMPTS) {
-                return {
-                    ok: false,
-                    failure: {
-                        failedPhase: params.phase,
-                        reason: result.reason,
-                        retryable,
-                        failedStepIndex: result.failedStepIndex,
-                        failedSubphase: result.failedSubphase,
-                    },
-                };
-            }
-            logger.info(`Retrying clip variant ${params.variantId} ${params.phase} after transient failure: ${result.reason}`);
-        }
-        catch (err) {
-            const reason = signal.aborted && !params.parentSignal?.aborted
-                ? getAbortMessage(signal, `Clip variant ${params.variantId} ${params.phase} timed out after ${timeoutMs}ms.`)
-                : err.message;
-            const retryable = isRetryableClipVariantFailure(params.phase, reason);
-            if (!retryable || attempt === CLIP_PHASE_MAX_ATTEMPTS) {
-                return {
-                    ok: false,
-                    failure: {
-                        failedPhase: params.phase,
-                        reason,
-                        retryable,
-                    },
-                };
-            }
-            logger.info(`Retrying clip variant ${params.variantId} ${params.phase} after transient exception: ${reason}`);
-        }
-        finally {
-            cleanup();
-        }
-    }
-    return {
-        ok: false,
-        failure: {
-            failedPhase: params.phase,
-            reason: `Clip variant ${params.variantId} ${params.phase} failed without a recorded assessment.`,
-            retryable: false,
-        },
-    };
-}
-function isGenericDashboardRoute(rawUrl) {
-    try {
-        const url = new URL(rawUrl);
-        const pathname = url.pathname.replace(/\/+$/, '') || '/';
-        return pathname === '/'
-            || pathname === '/home'
-            || pathname === '/dashboard'
-            || pathname === '/app';
-    }
-    catch {
-        return false;
-    }
-}
-function requiresSpecificEntityPreparation(config) {
-    const text = `${config.navigationInstructions ?? ''}\n${config.script ?? ''}`.toLowerCase();
-    if (!text.trim())
-        return false;
-    const entityMarker = /\b(project|workspace|account|organization|organisation|team|preset|document|collection|site|app)\b/i;
-    const actionMarker = /\b(open|click|select|choose|switch|go to|navigate|enter)\b/i;
-    return entityMarker.test(text) && actionMarker.test(text);
-}
-function hasExactVariantHandoff(navResult, config, requestedLang, requestedTheme) {
-    if (navResult.exactStartStateVerified !== true) {
-        return false;
-    }
-    if (requiresSpecificEntityPreparation(config) && isGenericDashboardRoute(navResult.finalUrl)) {
-        return false;
-    }
-    // Language detection from the navigation browser frequently does not survive session
-    // transfer to a new browser context. The Accept-Language header, navigator.language
-    // override, and similar browser-level signals are set per-context and are NOT persisted
-    // in cookies or storage. Even when sessionStorage has entries, those entries rarely
-    // contain explicit language preferences.
-    //
-    // Always require variant preflight when a specific language is requested so the
-    // variant state is verified in the actual recording browser. The preflight is fast
-    // when the language is already correct (detect + immediate return).
-    if (requestedLang) {
-        // Only trust URL-anchored languages (locale prefix like /en/...) which are portable
-        if (!hasLocaleInUrl(navResult.finalUrl, requestedLang)) {
-            logger.info(`[variant-handoff] Lang ${requestedLang} not anchored in URL — requiring preflight verification.`);
-            return false;
-        }
-    }
-    const langReady = !requestedLang || navResult.variantState?.lang.active === true;
-    const themeReady = !requestedTheme || navResult.variantState?.theme.active === true;
-    return langReady && themeReady;
-}
-function hasLocaleInUrl(url, lang) {
-    try {
-        const pathname = new URL(url).pathname;
-        const normalizedLang = lang.toLowerCase().split('-')[0];
-        const segments = pathname.split('/').filter(Boolean);
-        return segments.length > 0 && segments[0].toLowerCase() === normalizedLang;
-    }
-    catch {
-        return false;
-    }
-}
-function summarizeVariantHandoffMismatch(navResult, config, requestedLang, requestedTheme) {
-    const problems = [];
-    if (requiresSpecificEntityPreparation(config) && isGenericDashboardRoute(navResult.finalUrl)) {
-        problems.push(`generic_route=${navResult.finalUrl}`);
-    }
-    if (requestedLang && navResult.variantState?.lang.active !== true) {
-        problems.push(`lang=${requestedLang} not confirmed`);
-    }
-    if (requestedTheme && navResult.variantState?.theme.active !== true) {
-        problems.push(`theme=${requestedTheme} not confirmed`);
-    }
-    return problems.join(', ');
-}
-function buildVideoAgentConfig(orchestratorConfig, clip, target, lang, theme, navResult) {
-    return {
-        url: clip.url ?? orchestratorConfig.url,
-        script: clip.script,
-        viewport: target.viewport,
-        outputScale: orchestratorConfig.outputScale,
-        model: orchestratorConfig.model,
-        apiKey: orchestratorConfig.apiKey,
-        mode: 'clip',
-        runId: orchestratorConfig.runId,
-        variantId: buildVariantId(target.id, lang, theme),
-        projectId: orchestratorConfig.projectId,
-        presetId: orchestratorConfig.presetId,
-        lang,
-        theme,
-        langInstructions: orchestratorConfig.langInstructions,
-        themeInstructions: orchestratorConfig.themeInstructions,
-        navigationInstructions: orchestratorConfig.navigationInstructions,
-        credentials: orchestratorConfig.credentials,
-        abortSignal: orchestratorConfig.abortSignal,
-        videoOptions: {
-            cursorTheme: orchestratorConfig.clipOptions?.cursorTheme ?? 'minimal',
-        },
-        fallbackModel: orchestratorConfig.fallbackModel,
-        // Inject navigation session for Phase 2
-        ...(navResult ? {
-            preparedStartUrl: navResult.finalUrl,
-            preparedStorageState: navResult.storageState,
-            preparedSessionStorage: navResult.sessionStorage,
-            preparedObservationSummary: navResult.observationSummary,
-            preparedObservationSnapshot: navResult.observationSnapshot,
-            preparedActions: navResult.actions,
-            preparedReplayActions: navResult.replayableActions,
-            preparedCoherenceKey: navResult.coherenceKey,
-        } : {}),
-    };
-}
-async function prevalidateClipPlan(config, plan) {
-    const snapshot = config.preparedObservationSnapshot;
-    if (!snapshot) {
-        return { valid: true };
-    }
-    const mutatingTypes = new Set(['click', 'type', 'select_option', 'key', 'drag']);
-    const skipTypes = new Set(['navigate', 'wait', 'dismiss_overlays', 'assert_url', 'assert_text', 'assert_element', 'assert_page']);
-    // Only validate steps that can be checked against the pre-interaction snapshot.
-    // After the first DOM-mutating step (click, type, etc.), later targets may only
-    // appear in the DOM after that interaction (dropdown items, modal content).
-    for (let stepIndex = 0; stepIndex < plan.steps.length; stepIndex += 1) {
-        const step = plan.steps[stepIndex];
-        if (skipTypes.has(step.type)) {
-            continue;
-        }
-        const validation = validateStepAgainstSnapshot(step, snapshot);
-        if (!validation.valid) {
-            // When the snapshot has interactive elements but the target is absent, it's likely
-            // a real mismatch. When the snapshot is empty or when a prior mutating step could
-            // have revealed the target (e.g. opening a dropdown), treat as a soft warning.
-            const snapshotHasElements = snapshot.interactiveElements.length > 0;
-            if (snapshotHasElements && stepIndex === 0) {
-                // First step target absent from a populated snapshot — hard fail.
-                return {
-                    valid: false,
-                    reason: `Snapshot pre-validation failed at step ${stepIndex + 1}: ${validation.reason}`,
-                };
-            }
-            // Target may appear after a prior interaction (dropdown, menu) — soft warning.
-            logger.info(`Snapshot pre-validation warning at step ${stepIndex + 1}: ${validation.reason} — allowing because the target may appear after a prior interaction.`);
-            break;
-        }
-        if (mutatingTypes.has(step.type)) {
-            break;
-        }
-    }
-    return { valid: true };
-}
-function normalizeSnapshotText(value) {
-    return (value ?? '').trim().toLowerCase();
-}
-function matchesTargetLabel(actual, expected, mode) {
-    const normalizedActual = normalizeSnapshotText(actual);
-    const normalizedExpected = normalizeSnapshotText(expected);
-    if (!normalizedActual || !normalizedExpected) {
-        return false;
-    }
-    if (mode === 'contains') {
-        return normalizedActual.includes(normalizedExpected);
-    }
-    return normalizedActual === normalizedExpected || normalizedActual.includes(normalizedExpected);
-}
-function extractSelectorHints(selector) {
-    const textTokens = Array.from(selector.matchAll(/:has-text\((["'])(.*?)\1\)/g)).map((match) => match[2] ?? '');
-    const ariaTokens = Array.from(selector.matchAll(/\[aria-label[*^$|~]?=(["'])(.*?)\1\]/g)).map((match) => match[2] ?? '');
-    const hrefTokens = Array.from(selector.matchAll(/\[href[*^$|~]?=(["'])(.*?)\1\]/g)).map((match) => match[2] ?? '');
-    const roleTokens = Array.from(selector.matchAll(/\[role=(["']?)([a-z0-9_-]+)\1\]/gi)).map((match) => match[2] ?? '');
-    const tagToken = selector.match(/^\s*([a-z][a-z0-9-]*)\b/i)?.[1]?.toLowerCase();
-    const exactSelector = selector.includes(':')
-        || selector.includes('[')
-        || selector.includes('#')
-        || selector.includes('.')
-        ? selector.trim()
-        : undefined;
-    return {
-        textTokens: [...textTokens, ...ariaTokens].filter(Boolean),
-        hrefTokens: hrefTokens.filter(Boolean),
-        roleTokens: roleTokens.filter(Boolean),
-        tagToken,
-        exactSelector,
-    };
-}
-function matchSelectorAgainstSnapshot(selector, snapshot) {
-    const selectorParts = selector.split(',').map((part) => part.trim()).filter(Boolean);
-    if (selectorParts.length === 0) {
-        return { matched: false, decisive: false };
-    }
-    let decisive = false;
-    for (const part of selectorParts) {
-        const hints = extractSelectorHints(part);
-        const partHasHints = hints.textTokens.length > 0 || hints.hrefTokens.length > 0 || hints.roleTokens.length > 0 || Boolean(hints.tagToken);
-        if (partHasHints) {
-            decisive = true;
-        }
-        const matched = snapshot.interactiveElements.some((element) => {
-            const labelCandidates = [element.text, element.ariaLabel, element.title].filter(Boolean);
-            if (hints.textTokens.length > 0 && !hints.textTokens.every((token) => labelCandidates.some((candidate) => matchesTargetLabel(candidate, token, 'contains')))) {
-                return false;
-            }
-            if (hints.hrefTokens.length > 0) {
-                const href = normalizeSnapshotText(element.href);
-                if (!href || !hints.hrefTokens.every((token) => href.includes(normalizeSnapshotText(token)))) {
-                    return false;
-                }
-            }
-            if (hints.roleTokens.length > 0) {
-                const role = normalizeSnapshotText(element.role);
-                if (!role || !hints.roleTokens.every((token) => role === normalizeSnapshotText(token))) {
-                    return false;
-                }
-            }
-            if (hints.tagToken) {
-                const tag = normalizeSnapshotText(element.tag);
-                if (!tag || tag !== hints.tagToken) {
-                    return false;
-                }
-            }
-            if (hints.exactSelector && element.selector) {
-                const normalizedElementSelector = element.selector.trim();
-                if (normalizedElementSelector === hints.exactSelector || normalizedElementSelector.includes(hints.exactSelector) || hints.exactSelector.includes(normalizedElementSelector)) {
-                    return true;
-                }
-            }
-            return partHasHints;
-        });
-        if (matched) {
-            return { matched: true, decisive: true };
-        }
-    }
-    return { matched: false, decisive };
-}
-function matchTargetAgainstSnapshot(target, snapshot) {
-    const requiresScopedIndex = typeof target.index === 'number' && target.coherenceKey && snapshot.coherenceKey && target.coherenceKey === snapshot.coherenceKey;
-    const targetHasAnchors = Boolean(target.label || target.href || target.role || target.tag || target.selector || requiresScopedIndex);
-    if (!targetHasAnchors) {
-        return { matched: false, decisive: false };
-    }
-    for (const element of snapshot.interactiveElements) {
-        const labelCandidates = [element.text, element.ariaLabel, element.title].filter(Boolean);
-        if (target.label && !labelCandidates.some((candidate) => matchesTargetLabel(candidate, target.label, target.labelMatchMode))) {
-            continue;
-        }
-        if (target.href) {
-            const href = normalizeSnapshotText(element.href);
-            if (!href || !href.includes(normalizeSnapshotText(target.href))) {
-                continue;
-            }
-        }
-        if (target.role) {
-            const role = normalizeSnapshotText(element.role);
-            if (!role || role !== normalizeSnapshotText(target.role)) {
-                continue;
-            }
-        }
-        if (target.tag) {
-            const tag = normalizeSnapshotText(element.tag);
-            if (!tag || tag !== normalizeSnapshotText(target.tag)) {
-                continue;
-            }
-        }
-        if (typeof target.index === 'number' && requiresScopedIndex && element.index !== target.index) {
-            continue;
-        }
-        if (target.selector) {
-            const selectorMatch = matchSelectorAgainstSnapshot(target.selector, {
-                ...snapshot,
-                interactiveElements: [element],
-            });
-            if (!selectorMatch.matched && selectorMatch.decisive) {
-                continue;
-            }
-        }
-        return { matched: true, decisive: true };
-    }
-    return { matched: false, decisive: true };
-}
-function validateStepAgainstSnapshot(step, snapshot) {
-    if (step.target) {
-        const targetMatch = matchTargetAgainstSnapshot(step.target, snapshot);
-        if (!targetMatch.matched && targetMatch.decisive) {
-            return {
-                valid: false,
-                reason: step.target.label
-                    ? `target "${step.target.label}" is absent from the prepared observation`
-                    : `target anchors for "${step.description}" are absent from the prepared observation`,
-            };
-        }
-    }
-    if (step.selector) {
-        const selectorMatch = matchSelectorAgainstSnapshot(step.selector, snapshot);
-        if (!selectorMatch.matched && selectorMatch.decisive) {
-            return {
-                valid: false,
-                reason: `selector "${step.selector}" is absent from the prepared observation`,
-            };
-        }
-    }
-    return { valid: true };
-}
-function wrapCallbacks(clipId, variantId, callbacks) {
-    return {
-        onPhaseChange: (phase) => callbacks.onClipPhase?.({ clipId, variantId, phase }),
-        onStep: (stepIndex, total, description, phase) => callbacks.onClipStep?.({ clipId, variantId, stepIndex, total, description, phase }),
-        onStepResult: (stepIndex, ok, reason) => callbacks.onClipStepResult?.({ clipId, variantId, stepIndex, ok, reason }),
-        onLog: callbacks.onLog,
-        onScreenshot: callbacks.onScreenshot,
-    };
-}
-// ── Main orchestrator ───────────────────────────────────────────────
-/**
- * Run the clip capture pipeline for all clips × targets × langs × themes.
- *
- * Hybrid pipeline:
- * 1. For each (clip, target, lang) — navigate once with the screenshot agent
- * 2. Share the navigation session across theme variants (light/dark)
- * 3. For each variant: plan → validate selectors → record → post-process
- *
- * Navigation sharing: themes only affect `colorScheme` (a Playwright setting),
- * so the same navigation session (cookies, localStorage, URL) is reused.
- */
-export async function runClipOrchestrator(config, callbacks = {}) {
-    const results = [];
-    const totalVariants = config.clips.length * config.targets.length * config.langs.length * config.themes.length;
-    logger.info(`Starting clip orchestration (hybrid): ${config.clips.length} clips × ${config.targets.length} targets × ${config.langs.length} langs × ${config.themes.length} themes = ${totalVariants} variants`);
-    // Navigation cache: shared only for the exact same (clip, target, lang, theme) variant.
-    const navCache = new Map();
-    for (let clipIndex = 0; clipIndex < config.clips.length; clipIndex++) {
-        const clip = config.clips[clipIndex];
-        logger.info(`Processing clip ${clipIndex + 1}/${config.clips.length}: "${clip.name}"`);
-        for (const target of config.targets) {
-            for (const lang of config.langs) {
-                for (const theme of config.themes) {
-                    const navKey = buildNavCacheKey(clip.id, target.id, lang, theme);
-                    let navResult = navCache.get(navKey);
-                    if (!navResult) {
-                        logger.info(`[hybrid] Navigating for clip="${clip.name}" target=${target.id} lang=${lang} theme=${theme}`);
-                        const NAV_MAX_ATTEMPTS = 2;
-                        let navAttempt = 0;
-                        let navError = null;
-                        let navFailed = false;
-                        while (navAttempt < NAV_MAX_ATTEMPTS && !navResult) {
-                            navAttempt += 1;
-                            try {
-                                // When navigationScript is provided, use it for navigation and keep
-                                // script exclusively for the recording planner. Otherwise, fall back
-                                // to using script for both (legacy behavior).
-                                navResult = await navigateWithAgent({
-                                    url: clip.url ?? config.url,
-                                    baseUrl: config.url,
-                                    navigationPrompt: clip.navigationScript ?? clip.script,
-                                    recordingScript: clip.navigationScript ? clip.script : undefined,
-                                    viewport: target.viewport,
-                                    outputScale: config.outputScale,
-                                    lang,
-                                    theme: theme,
-                                    credentials: config.credentials,
-                                    langInstructions: config.langInstructions,
-                                    themeInstructions: config.themeInstructions,
-                                    navigationInstructions: config.navigationInstructions,
-                                    model: config.model,
-                                    apiKey: config.apiKey,
-                                    maxIterations: 30,
-                                    abortSignal: config.abortSignal,
-                                    onLog: callbacks.onLog,
-                                    onScreenshot: callbacks.onScreenshot,
-                                });
-                                if (!navResult.success) {
-                                    const errMsg = navResult.error ?? 'unknown';
-                                    const isTransient = /\b(timeout|timed out|network|socket|context closed)\b/i.test(errMsg);
-                                    if (isTransient && navAttempt < NAV_MAX_ATTEMPTS) {
-                                        logger.info(`Navigation attempt ${navAttempt} failed (transient: ${errMsg}), retrying...`);
-                                        navResult = undefined;
-                                        continue;
-                                    }
-                                    navFailed = true;
-                                }
-                            }
-                            catch (err) {
-                                navError = err;
-                                const isTransient = /\b(timeout|timed out|network|socket|context closed)\b/i.test(navError.message);
-                                if (isTransient && navAttempt < NAV_MAX_ATTEMPTS) {
-                                    logger.info(`Navigation attempt ${navAttempt} threw (transient: ${navError.message}), retrying...`);
-                                    continue;
-                                }
-                                break;
-                            }
-                        }
-                        if (navError && !navResult) {
-                            logger.error(`Navigation failed for clip="${clip.name}" ${navKey}: ${navError.message}`);
-                            results.push({
-                                clipId: clip.id,
-                                clipName: clip.name,
-                                clipScript: clip.script,
-                                targetId: target.id,
-                                targetLabel: target.label,
-                                viewportWidth: target.viewport.width,
-                                viewportHeight: target.viewport.height,
-                                lang,
-                                theme,
-                                success: false,
-                                durationMs: 0,
-                                stepsExecuted: 0,
-                                assessment: `Navigation failed: ${navError.message}`,
-                                usage: [],
-                            });
-                            continue;
-                        }
-                        if (navFailed || !navResult) {
-                            results.push({
-                                clipId: clip.id,
-                                clipName: clip.name,
-                                clipScript: clip.script,
-                                targetId: target.id,
-                                targetLabel: target.label,
-                                viewportWidth: target.viewport.width,
-                                viewportHeight: target.viewport.height,
-                                lang,
-                                theme,
-                                success: false,
-                                durationMs: 0,
-                                stepsExecuted: 0,
-                                assessment: `Navigation failed: ${navResult?.error ?? 'unknown'}`,
-                                usage: navResult?.usage ?? [],
-                            });
-                            continue;
-                        }
-                        navCache.set(navKey, navResult);
-                    }
-                    const variantId = buildVariantId(target.id, lang, theme);
-                    const variantConfig = buildVideoAgentConfig(config, clip, target, lang, theme, navResult);
-                    const variantCallbacks = wrapCallbacks(clip.id, variantId, callbacks);
-                    callbacks.onClipStart?.({
-                        clipId: clip.id,
-                        clipName: clip.name,
-                        variantId,
-                        target: target.viewport,
-                        lang,
-                        theme,
-                        clipIndex,
-                        totalClips: config.clips.length,
-                    });
-                    // Per-clip timeout to prevent a single slow clip from blocking the entire pipeline.
-                    // 300s allows for: navigation (~45s) + preflight (~60s) + planning (~30s) + dry-run (~90s) + recording (~60s).
-                    const clipTimeoutMs = config.perClipTimeoutMs ?? 300_000;
-                    const clipAbortController = new AbortController();
-                    const clipTimer = setTimeout(() => {
-                        clipAbortController.abort(createAbortError(`Clip variant ${variantId} exceeded per-clip timeout of ${clipTimeoutMs}ms.`));
-                    }, clipTimeoutMs);
-                    // Override the abort signal for this variant
-                    variantConfig.abortSignal = config.abortSignal
-                        ? mergeAbortSignals(config.abortSignal, clipAbortController.signal)
-                        : clipAbortController.signal;
-                    let variantResult;
-                    try {
-                        variantResult = await runClipVariant(clip, target, lang, theme, navResult, variantConfig, variantCallbacks, callbacks, config.clipOptions);
-                    }
-                    catch (err) {
-                        clearTimeout(clipTimer);
-                        variantResult = {
-                            clipId: clip.id,
-                            clipName: clip.name,
-                            clipScript: clip.script,
-                            targetId: target.id,
-                            targetLabel: target.label,
-                            viewportWidth: target.viewport.width,
-                            viewportHeight: target.viewport.height,
-                            lang,
-                            theme,
-                            success: false,
-                            durationMs: 0,
-                            stepsExecuted: 0,
-                            assessment: `Clip variant timed out: ${err.message}`,
-                            usage: [],
-                        };
-                    }
-                    finally {
-                        clearTimeout(clipTimer);
-                    }
-                    if (!variantResult.success) {
-                        logger.error(`Clip variant ${variantId} failed${variantResult.failedPhase ? ` during ${variantResult.failedPhase}` : ''}: ${variantResult.assessment}`);
-                    }
-                    results.push(variantResult);
-                }
-            }
-        }
-    }
-    const successCount = results.filter(r => r.success).length;
-    callbacks.onClipsAllDone?.({ totalClips: results.length, successCount });
-    logger.info(`Clip orchestration complete: ${successCount}/${results.length} successful`);
-    return { results, totalClips: results.length, successCount };
-}
-async function runClipVariant(clip, target, lang, theme, navResult, config, videoCallbacks, orchestratorCallbacks, clipOptions) {
-    const allUsage = [...navResult.usage];
-    return runClipVariantAttempt(clip, target, lang, theme, navResult, config, allUsage, videoCallbacks, orchestratorCallbacks, clipOptions);
-}
-async function runClipVariantAttempt(clip, target, lang, theme, navResult, config, allUsage, videoCallbacks, orchestratorCallbacks, clipOptions) {
-    const variantId = buildVariantId(target.id, lang, theme);
-    const makeFailResult = (assessment, failedPhase, failure) => ({
-        clipId: clip.id,
-        clipName: clip.name,
-        clipScript: clip.script,
-        targetId: target.id,
-        targetLabel: target.label,
-        viewportWidth: target.viewport.width,
-        viewportHeight: target.viewport.height,
-        lang,
-        theme,
-        success: false,
-        durationMs: 0,
-        stepsExecuted: 0,
-        assessment: humanizeClipFailure(assessment, failedPhase, failure?.failedSubphase),
-        failedPhase,
-        failedStepIndex: failure?.failedStepIndex,
-        failedSubphase: failure?.failedSubphase,
-        usage: allUsage,
-    });
-    videoCallbacks.onPhaseChange?.('planning');
-    const shouldSkipPreflight = hasExactVariantHandoff(navResult, config, lang, theme);
-    const canUseTargetedVariantPreflight = navResult.exactStartStateVerified === true
-        && !shouldSkipPreflight
-        && !(requiresSpecificEntityPreparation(config) && isGenericDashboardRoute(navResult.finalUrl));
-    const shouldPlanVariantPrefix = !shouldSkipPreflight && !canUseTargetedVariantPreflight;
-    let preparedConfig = {
-        ...config,
-        preparedObservationSummary: config.preparedObservationSummary ?? navResult.observationSummary,
-    };
-    if (shouldSkipPreflight) {
-        logger.info(`Clip variant ${variantId} reusing exact start-state handoff from hybrid navigation; skipping variant preflight.`);
-    }
-    else {
-        let variantPrefixPlan = null;
-        if (shouldPlanVariantPrefix) {
-            const prefixPhase = await executeClipPhase({
-                phase: 'planning',
-                variantId,
-                clipOptions,
-                parentSignal: config.abortSignal,
-                run: async (signal) => {
-                    try {
-                        const prefixResult = await createVariantPrefixPlan({
-                            ...config,
-                            abortSignal: signal,
-                        });
-                        allUsage.push(prefixResult.usage);
-                        return { ok: true, value: prefixResult.plan };
-                    }
-                    catch (err) {
-                        return { ok: false, reason: `Variant preflight planning failed: ${err.message}` };
-                    }
-                },
-            });
-            if (!prefixPhase.ok) {
-                return makeFailResult(prefixPhase.failure.reason, prefixPhase.failure.failedPhase);
-            }
-            variantPrefixPlan = prefixPhase.value;
-        }
-        else if (canUseTargetedVariantPreflight) {
-            const mismatchSummary = summarizeVariantHandoffMismatch(navResult, config, lang, theme);
-            logger.info(`Clip variant ${variantId} reached the exact start state, but the requested UI variant is not confirmed${mismatchSummary ? ` (${mismatchSummary})` : ''}. Running targeted variant preflight without prefix planning.`);
-        }
-        const preflightPhase = await executeClipPhase({
-            phase: 'preflight',
-            variantId,
-            clipOptions,
-            parentSignal: config.abortSignal,
-            run: async (signal, _attempt, phaseContext) => {
-                const preflightResult = await runVariantPreflight({
-                    ...config,
-                    abortSignal: signal,
-                    internalPhaseTimeoutMs: phaseContext.timeoutMs,
-                    internalPhaseStartedAt: phaseContext.startedAt,
-                }, variantPrefixPlan, videoCallbacks);
-                if (!preflightResult.ok) {
-                    return { ok: false, reason: `Variant preflight failed: ${preflightResult.reason ?? 'unknown reason'}` };
-                }
-                return { ok: true, value: preflightResult };
-            },
-        });
-        if (!preflightPhase.ok) {
-            return makeFailResult(preflightPhase.failure.reason, preflightPhase.failure.failedPhase);
-        }
-        const preflightResult = preflightPhase.value;
-        if (preflightResult.usage?.length) {
-            allUsage.push(...preflightResult.usage);
-        }
-        preparedConfig = {
-            ...preparedConfig,
-            preparedStartUrl: preflightResult.finalUrl ?? config.preparedStartUrl ?? config.url,
-            preparedStorageState: preflightResult.storageState ?? config.preparedStorageState,
-            preparedSessionStorage: preflightResult.sessionStorage ?? config.preparedSessionStorage,
-            preparedObservationSummary: preflightResult.observationSummary ?? preparedConfig.preparedObservationSummary,
-            preparedObservationSnapshot: preflightResult.observationSnapshot ?? preparedConfig.preparedObservationSnapshot,
-        };
-    }
-    let plan;
-    const planningPhase = await executeClipPhase({
-        phase: 'planning',
-        variantId,
-        clipOptions,
-        parentSignal: config.abortSignal,
-        run: async (signal, _attempt, phaseContext) => {
-            try {
-                const planResult = await createBasePlan({
-                    ...preparedConfig,
-                    abortSignal: signal,
-                    internalPhaseTimeoutMs: phaseContext.timeoutMs,
-                    internalPhaseStartedAt: phaseContext.startedAt,
-                });
-                allUsage.push(planResult.usage);
-                logger.info(`Clip "${clip.name}" plan: "${planResult.plan.title}" — ${planResult.plan.steps.length} steps`);
-                const prevalidation = await prevalidateClipPlan(preparedConfig, planResult.plan);
-                if (!prevalidation.valid) {
-                    return { ok: false, reason: prevalidation.reason };
-                }
-                return { ok: true, value: planResult.plan };
-            }
-            catch (err) {
-                return { ok: false, reason: `Planning failed: ${err.message}` };
-            }
-        },
-    });
-    if (!planningPhase.ok) {
-        return makeFailResult(planningPhase.failure.reason, planningPhase.failure.failedPhase, planningPhase.failure);
-    }
-    plan = planningPhase.value;
-    const dryRunPhase = await executeClipPhase({
-        phase: 'dry_run',
-        variantId,
-        clipOptions,
-        parentSignal: config.abortSignal,
-        run: async (signal, _attempt, phaseContext) => {
-            const verifyResult = await verifyAndPatchPlan({
-                ...plan,
-                steps: [...plan.steps],
-            }, {
-                ...preparedConfig,
-                abortSignal: signal,
-                internalPhaseTimeoutMs: phaseContext.timeoutMs,
-                internalPhaseStartedAt: phaseContext.startedAt,
-            }, videoCallbacks);
-            allUsage.push(...verifyResult.usage);
-            if (!verifyResult.success) {
-                logger.error(`Dry-run failed for clip "${clip.name}" variant ${variantId}`);
-                return {
-                    ok: false,
-                    reason: `Dry-run failed: ${verifyResult.error}`,
-                    failedStepIndex: verifyResult.failedStepIndex,
-                    failedSubphase: verifyResult.failedSubphase,
-                };
-            }
-            return { ok: true, value: verifyResult.plan };
-        },
-    });
-    if (!dryRunPhase.ok) {
-        return makeFailResult(dryRunPhase.failure.reason, dryRunPhase.failure.failedPhase, dryRunPhase.failure);
-    }
-    plan = dryRunPhase.value;
-    const recordingPhase = await executeClipPhase({
-        phase: 'recording',
-        variantId,
-        clipOptions,
-        parentSignal: config.abortSignal,
-        run: async (signal, _attempt, phaseContext) => {
-            const recordResult = await recordPlan(plan, {
-                ...preparedConfig,
-                abortSignal: signal,
-                internalPhaseTimeoutMs: phaseContext.timeoutMs,
-                internalPhaseStartedAt: phaseContext.startedAt,
-                dryRunVariantConfirmed: true,
-            }, videoCallbacks);
-            if (!recordResult.videoPath) {
-                return { ok: false, reason: 'Recording produced no video file' };
-            }
-            return {
-                ok: true,
-                value: {
-                    ...recordResult,
-                    videoPath: recordResult.videoPath,
-                },
-            };
-        },
-    });
-    if (!recordingPhase.ok) {
-        return makeFailResult(recordingPhase.failure.reason, recordingPhase.failure.failedPhase);
-    }
-    const recordResult = recordingPhase.value;
-    orchestratorCallbacks.onClipPostprocessStart?.({ clipId: clip.id, variantId });
-    const postprocessPhase = await executeClipPhase({
-        phase: 'postprocess',
-        variantId,
-        clipOptions,
-        parentSignal: config.abortSignal,
-        run: async (_signal, _attempt, _phaseContext) => {
-            try {
-                const outputDir = await mkdtemp(path.join(os.tmpdir(), `clip-${clip.id}-`));
-                const outputScale = config.outputScale ?? 1;
-                const postResult = await postProcessClipRecording(recordResult.videoPath, outputDir, `${clip.id}_${variantId.replace(/:/g, '_')}`, {
-                    ...clipOptions,
-                    gifMaxWidth: clipOptions?.gifMaxWidth ?? Math.round(target.viewport.width * outputScale),
-                    holdLastFrameSec: clip.holdLastFrameSec ?? clipOptions?.holdLastFrameSec ?? 0,
-                    trimStartSec: recordResult.setupDurationSec,
-                });
-                return { ok: true, value: postResult };
-            }
-            catch (err) {
-                logger.error(`Post-processing failed for clip "${clip.name}" variant ${variantId}: ${err.message}`);
-                return { ok: false, reason: `Post-processing failed: ${err.message}` };
-            }
-        },
-    });
-    if (!postprocessPhase.ok) {
-        orchestratorCallbacks.onClipPostprocessDone?.({ clipId: clip.id, variantId, success: false });
-        return makeFailResult(postprocessPhase.failure.reason, postprocessPhase.failure.failedPhase);
-    }
-    const postResult = postprocessPhase.value;
-    orchestratorCallbacks.onClipPostprocessDone?.({
-        clipId: clip.id, variantId, success: true,
-        gifPath: postResult.gifPath, mp4Path: postResult.mp4Path,
-    });
-    const result = {
-        clipId: clip.id,
-        clipName: clip.name,
-        clipScript: clip.script,
-        targetId: target.id,
-        targetLabel: target.label,
-        viewportWidth: target.viewport.width,
-        viewportHeight: target.viewport.height,
-        lang,
-        theme,
-        success: true,
-        gifPath: postResult.gifPath,
-        mp4Path: postResult.mp4Path,
-        thumbnailPath: postResult.thumbnailPath,
-        durationMs: postResult.durationMs,
-        fileSizeBytes: postResult.fileSizeBytes,
-        plan,
-        stepsExecuted: recordResult.stepsExecuted,
-        assessment: `Recorded ${recordResult.stepsExecuted} steps, ${Math.round(postResult.durationMs / 1000)}s clip`,
-        usage: allUsage,
-    };
-    orchestratorCallbacks.onClipRecordingDone?.({
-        clipId: clip.id, variantId, success: true,
-        gifPath: postResult.gifPath, mp4Path: postResult.mp4Path,
-        thumbnailPath: postResult.thumbnailPath,
-        durationMs: postResult.durationMs, fileSizeBytes: postResult.fileSizeBytes,
-        lang, theme, targetId: target.id, targetLabel: target.label,
-    });
-    return result;
-}
-//# sourceMappingURL=clip-orchestrator.js.map