autokap 1.0.0

package/dist/cli-utils.d.ts

@@ -0,0 +1,25 @@
+import type { CaptureManifest, IsolatedElement, LoginCredentials } from './types.js';
+export declare function parseViewport(input: string): {
+    width: number;
+    height: number;
+};
+export declare function parseViewports(input: string): Array<{
+    width: number;
+    height: number;
+}>;
+export declare function parseLanguages(input: string): string[];
+export declare function buildThemeList(dark: boolean): Array<'light' | 'dark'>;
+export declare function buildCredentials(opts: {
+    email?: string;
+    password?: string;
+    loginUrl?: string;
+}): LoginCredentials | undefined;
+export declare function parseElements(specs: string[]): IsolatedElement[];
+export declare function stripBuffersFromManifest(manifest: CaptureManifest): object;
+export declare function replaceSkillPlaceholders(content: string, opts: {
+    projectUrl?: string;
+    projectId?: string;
+    apiKey?: string;
+    apiBaseUrl?: string;
+}): string;
+export declare function buildRetryPrompt(originalPrompt: string, assessment: string, clarification: string, attemptNumber: number): string;

package/dist/cli-utils.js

@@ -0,0 +1,80 @@
+export function parseViewport(input) {
+    const parts = input.split('x').map(Number);
+    if (parts.length !== 2 || parts.some(isNaN)) {
+        throw new Error(`Invalid viewport format: "${input}". Use WxH (e.g., 1440x900)`);
+    }
+    return { width: parts[0], height: parts[1] };
+}
+export function parseViewports(input) {
+    return input.split(',').map(s => {
+        const trimmed = s.trim();
+        const parts = trimmed.split('x').map(Number);
+        if (parts.length !== 2 || parts.some(isNaN)) {
+            throw new Error(`Invalid viewport in --viewports: "${trimmed}". Use WxH (e.g., 1440x900)`);
+        }
+        return { width: parts[0], height: parts[1] };
+    });
+}
+export function parseLanguages(input) {
+    return input.split(',').map(l => l.trim()).filter(Boolean);
+}
+export function buildThemeList(dark) {
+    const themes = ['light'];
+    if (dark)
+        themes.push('dark');
+    return themes;
+}
+export function buildCredentials(opts) {
+    if (!opts.email && !opts.password)
+        return undefined;
+    return {
+        loginUrl: opts.loginUrl,
+        email: opts.email,
+        password: opts.password,
+    };
+}
+export function parseElements(specs) {
+    const elements = [];
+    for (const spec of specs) {
+        const colonIdx = spec.indexOf(':');
+        if (colonIdx === -1) {
+            throw new Error(`Invalid --element format: "${spec}". Use "name:description"`);
+        }
+        elements.push({
+            name: spec.slice(0, colonIdx).trim(),
+            description: spec.slice(colonIdx + 1).trim(),
+        });
+    }
+    return elements;
+}
+export function stripBuffersFromManifest(manifest) {
+    return {
+        ...manifest,
+        captures: manifest.captures.map(c => ({
+            ...c,
+            result: {
+                ...c.result,
+                screenshots: undefined,
+            },
+        })),
+    };
+}
+export function replaceSkillPlaceholders(content, opts) {
+    let result = content;
+    if (opts.projectUrl) {
+        result = result.replace(/\[AUTOKAP_PROJECT_URL\]/g, opts.projectUrl);
+    }
+    if (opts.projectId) {
+        result = result.replace(/\[AUTOKAP_PROJECT_ID\]/g, opts.projectId);
+    }
+    if (opts.apiKey) {
+        result = result.replace(/YOUR_API_KEY/g, opts.apiKey);
+    }
+    const baseUrl = opts.apiBaseUrl ?? 'https://app.autokap.com';
+    result = result.replace(/https:\/\/app\.autokap\.com/g, baseUrl);
+    return result;
+}
+export function buildRetryPrompt(originalPrompt, assessment, clarification, attemptNumber) {
+    return `${originalPrompt}\n\nIMPORTANT CLARIFICATION FROM USER (attempt #${attemptNumber}):\nThe previous attempt failed: "${assessment}"\nUser says: ${clarification}`;
+}
+//# sourceMappingURL=cli-utils.js.map

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+export declare const program: Command;
+export declare function main(): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,365 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { config as loadEnv } from 'dotenv';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import readline from 'node:readline';
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+import { Browser } from './browser.js';
+import { runAgent } from './agent.js';
+import { captureIsolatedElement } from './element-capture.js';
+import { dismissCookiesAndWidgets } from './cookie-dismiss.js';
+import { logger } from './logger.js';
+import { getPostHog, shutdownPostHog, DISTINCT_ID } from './posthog.js';
+import { parseViewport, parseViewports, parseLanguages, buildThemeList, buildCredentials, parseElements, stripBuffersFromManifest, replaceSkillPlaceholders, buildRetryPrompt, } from './cli-utils.js';
+function askUser(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise(resolve => {
+        rl.question(question, answer => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+export const program = new Command();
+program
+    .name('autokap')
+    .version(version)
+    .description('AI-powered screenshot capture tool')
+    .option('--url <url>', 'Target URL')
+    .option('--prompt <prompt>', 'What to capture (natural language)')
+    .option('--dark', 'Also capture dark mode variant', false)
+    .option('--langs <codes>', 'Comma-separated language codes (e.g., en,fr,de)', 'en')
+    .option('--output <dir>', 'Output directory', './output')
+    .option('--headed', 'Show browser window (debug mode)', false)
+    .option('--viewport <size>', 'Viewport size WxH (e.g., 1440x900)', '1440x900')
+    .option('--viewports <sizes>', 'Comma-separated viewport sizes for multi-viewport capture (e.g., "1440x900,768x1024,375x812")')
+    .option('--max-iter <n>', 'Max agent iterations', '30')
+    .option('--model <id>', 'OpenRouter model ID', 'x-ai/grok-4.1-fast')
+    .option('--reasoning-effort <level>', 'Reasoning effort for compatible models: low, medium, high, off', 'medium')
+    .option('--login-url <url>', 'Login page URL (if different from --url)')
+    .option('--email <email>', 'Login email/username')
+    .option('--password <password>', 'Login password')
+    .option('--cookies <file>', 'Path to a JSON file with cookies to inject (for OAuth/session auth)')
+    .option('--lang-instructions <text>', 'How to switch language on the site (e.g., "Click the language selector in the footer and choose the target language")')
+    .option('--theme-instructions <text>', 'How to switch theme on the site (e.g., "Click the sun/moon icon in the top-right corner")')
+    .option('--element <specs...>', 'Isolated elements to capture (format: "name:description")');
+// ── Skill subcommand ──────────────────────────────────────────────────
+program
+    .command('skill')
+    .description('Output or install the AutoKap preset creation skill for AI coding agents')
+    .option('--output <path>', 'Write skill file to this path instead of stdout')
+    .option('--project-url <url>', 'Replace the project URL placeholder in the skill')
+    .option('--project-id <id>', 'Replace the project ID placeholder in the skill')
+    .option('--api-key <key>', 'Replace the API key placeholder in the skill')
+    .option('--api-base-url <url>', 'Replace the API base URL placeholder (default: https://app.autokap.com)')
+    .action(async (opts) => {
+    const skillPath = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..', 'assets', 'skill', 'SKILL.md');
+    let rawContent;
+    try {
+        rawContent = await fs.readFile(skillPath, 'utf-8');
+    }
+    catch {
+        console.error('Error: Could not find SKILL.md. Make sure the autokap package is installed correctly.');
+        process.exit(1);
+    }
+    const content = replaceSkillPlaceholders(rawContent, opts);
+    if (opts.output) {
+        const outDir = path.dirname(opts.output);
+        await fs.mkdir(outDir, { recursive: true });
+        await fs.writeFile(opts.output, content, 'utf-8');
+        console.log(`Skill file written to: ${opts.output}`);
+        console.log('');
+        console.log('Next steps:');
+        console.log('  Claude Code:  Place the file in .claude/commands/autokap-preset.md');
+        console.log('  Cursor:       Place the file in .cursor/rules/autokap-preset.md');
+        console.log('  Other agents: Point your agent to the file when asking it to create presets');
+    }
+    else {
+        process.stdout.write(content);
+    }
+    process.exit(0);
+});
+export async function main() {
+    loadEnv();
+    const opts = program.opts();
+    if (!opts.url) {
+        logger.error("Missing required option: --url <url>");
+        process.exit(1);
+    }
+    if (!opts.prompt) {
+        logger.error("Missing required option: --prompt <prompt>");
+        process.exit(1);
+    }
+    const apiKey = process.env.OPENROUTER_API_KEY;
+    if (!apiKey) {
+        logger.error('OPENROUTER_API_KEY not set. Create a .env file or set the environment variable.');
+        process.exit(1);
+    }
+    // Parse viewport
+    const { width: vw, height: vh } = parseViewport(opts.viewport);
+    // Parse multi-viewports (if provided)
+    const viewports = opts.viewports ? parseViewports(opts.viewports) : undefined;
+    // Parse languages
+    const langs = parseLanguages(opts.langs);
+    // Build theme list
+    const themes = buildThemeList(opts.dark);
+    // Build credentials (if provided)
+    const credentials = buildCredentials({
+        email: opts.email,
+        password: opts.password,
+        loginUrl: opts.loginUrl,
+    });
+    // Parse isolated elements
+    const elements = opts.element ? parseElements(opts.element) : [];
+    // Ensure output directory exists
+    const outputDir = path.resolve(opts.output);
+    await fs.mkdir(outputDir, { recursive: true });
+    logger.info(`URL: ${opts.url}`);
+    logger.info(`Prompt: "${opts.prompt}"`);
+    logger.info(`Model: ${opts.model}${opts.reasoningEffort !== 'off' ? ` (reasoning: ${opts.reasoningEffort})` : ''}`);
+    logger.info(`Viewport: ${vw}x${vh}${viewports ? ` + multi: ${viewports.map(v => `${v.width}x${v.height}`).join(', ')}` : ''}`);
+    logger.info(`Themes: ${themes.join(', ')}`);
+    logger.info(`Languages: ${langs.join(', ')}`);
+    logger.info(`Max iterations: ${opts.maxIter}`);
+    if (credentials)
+        logger.info(`Login: ${credentials.email || '(no email)'}${credentials.loginUrl ? ` via ${credentials.loginUrl}` : ''}`);
+    if (opts.cookies)
+        logger.info(`Cookies: ${opts.cookies}`);
+    if (opts.langInstructions)
+        logger.info(`Lang instructions: "${opts.langInstructions}"`);
+    if (opts.themeInstructions)
+        logger.info(`Theme instructions: "${opts.themeInstructions}"`);
+    if (elements.length > 0)
+        logger.info(`Isolated elements: ${elements.map(e => e.name).join(', ')}`);
+    logger.info(`Output: ${outputDir}`);
+    // Track capture start
+    getPostHog().capture({
+        distinctId: DISTINCT_ID,
+        event: 'capture_started',
+        properties: {
+            url: opts.url,
+            prompt: opts.prompt,
+            model: opts.model,
+            themes,
+            langs,
+            viewport: `${vw}x${vh}`,
+            multi_viewports: viewports ? viewports.map(v => `${v.width}x${v.height}`) : null,
+            max_iterations: parseInt(opts.maxIter, 10),
+            has_credentials: !!credentials,
+            has_cookies: !!opts.cookies,
+            element_count: elements.length,
+        },
+    });
+    // Launch browser
+    const browser = new Browser({
+        headed: opts.headed,
+        viewport: { width: vw, height: vh },
+    });
+    await browser.launch();
+    logger.success('Browser launched');
+    // Inject cookies if provided
+    if (opts.cookies) {
+        try {
+            const cookieFile = await fs.readFile(path.resolve(opts.cookies), 'utf-8');
+            const cookies = JSON.parse(cookieFile);
+            if (!Array.isArray(cookies))
+                throw new Error('Cookies file must contain a JSON array');
+            await browser.addCookies(cookies);
+            logger.success(`Injected ${cookies.length} cookies from ${opts.cookies}`);
+        }
+        catch (err) {
+            logger.error(`Failed to load cookies: ${err.message}`);
+            process.exit(1);
+        }
+    }
+    const manifest = {
+        url: opts.url,
+        prompt: opts.prompt,
+        timestamp: new Date().toISOString(),
+        captures: [],
+    };
+    try {
+        for (const lang of langs) {
+            for (const theme of themes) {
+                logger.info(`--- Capturing: theme=${theme}, lang=${lang} ---`);
+                // Set language and navigate
+                await browser.setLanguage(lang);
+                await browser.navigateTo(opts.url);
+                logger.info('Page loaded');
+                // Pre-cleanup: dismiss cookies and widgets
+                const cookieResult = await dismissCookiesAndWidgets(browser.currentPage);
+                if (cookieResult.dismissed) {
+                    logger.success(`Cookies dismissed: ${cookieResult.method}`);
+                }
+                // Set color scheme
+                await browser.setColorScheme(theme);
+                // Wait for re-renders
+                await browser.wait(500);
+                // Run AI agent with retry on give_up
+                let currentPrompt = opts.prompt;
+                let retryCount = 0;
+                const maxRetries = 3;
+                let result;
+                while (true) {
+                    const config = {
+                        url: opts.url,
+                        prompt: currentPrompt,
+                        dark: theme === 'dark',
+                        langs: [lang],
+                        outputDir,
+                        headed: opts.headed,
+                        viewport: { width: vw, height: vh },
+                        maxIterations: parseInt(opts.maxIter, 10),
+                        model: opts.model,
+                        reasoningEffort: opts.reasoningEffort,
+                        credentials,
+                        langInstructions: opts.langInstructions,
+                        themeInstructions: opts.themeInstructions,
+                        currentLang: lang,
+                        currentTheme: theme,
+                        viewports,
+                    };
+                    result = await runAgent(browser, config, apiKey);
+                    // If succeeded or max retries reached, stop
+                    if (result.success || retryCount >= maxRetries)
+                        break;
+                    // Save diagnostic state on failure
+                    if (result.diagnostic) {
+                        const diagFilename = `diagnostic_${lang}_${theme}_attempt${retryCount}.png`;
+                        const diagPath = path.join(outputDir, diagFilename);
+                        await fs.writeFile(diagPath, result.diagnostic.screenshot);
+                        logger.info(`Diagnostic screenshot saved: ${diagPath}`);
+                        const diagStateFilename = `diagnostic_${lang}_${theme}_attempt${retryCount}.json`;
+                        const diagStatePath = path.join(outputDir, diagStateFilename);
+                        await fs.writeFile(diagStatePath, JSON.stringify({
+                            reason: result.diagnostic.giveUpReason,
+                            url: result.diagnostic.url,
+                            interactiveElements: result.diagnostic.interactiveElements.slice(0, 50),
+                            accessibilityTreeSnippet: result.diagnostic.accessibilityTreeSnippet,
+                            actions: result.actions,
+                        }, null, 2));
+                        logger.info(`Diagnostic state saved: ${diagStatePath}`);
+                    }
+                    // Ask user for clarification
+                    logger.error(`Agent gave up: ${result.assessment}`);
+                    logger.info('You can provide additional instructions to help the agent retry, or press Enter to skip.');
+                    const clarification = await askUser('\nAdditional instructions (or Enter to skip): ');
+                    if (!clarification)
+                        break; // User chose to skip
+                    // Append clarification to the prompt and retry
+                    retryCount++;
+                    currentPrompt = buildRetryPrompt(opts.prompt, result.assessment, clarification, retryCount + 1);
+                    logger.info(`Retrying with clarification (attempt ${retryCount + 1}/${maxRetries + 1})...`);
+                }
+                // Save final screenshot
+                const filename = `screenshot_${lang}_${theme}.png`;
+                const filepath = path.join(outputDir, filename);
+                const finalScreenshot = await browser.takeScreenshot();
+                await fs.writeFile(filepath, finalScreenshot);
+                result.screenshotPath = filepath;
+                if (result.success) {
+                    logger.success(`Final screenshot saved: ${filepath}`);
+                }
+                else {
+                    logger.error(`Failed (diagnostic saved): ${filepath}`);
+                }
+                // Save workflow screenshots (intermediate captures)
+                const screenshotEntries = [];
+                for (const ws of result.screenshots) {
+                    const wsFilename = `screenshot_${lang}_${theme}_step${ws.index}.png`;
+                    const wsPath = path.join(outputDir, wsFilename);
+                    await fs.writeFile(wsPath, ws.buffer);
+                    ws.path = wsPath;
+                    screenshotEntries.push({
+                        index: ws.index,
+                        iteration: ws.iteration,
+                        label: ws.label,
+                        filename: wsFilename,
+                    });
+                    logger.success(`Workflow screenshot saved: ${wsPath} ("${ws.label}")`);
+                }
+                manifest.captures.push({
+                    theme,
+                    lang,
+                    filename,
+                    screenshots: screenshotEntries,
+                    result,
+                });
+                // Capture isolated elements (if page is ready)
+                if (elements.length > 0 && result.success) {
+                    logger.info(`--- Capturing ${elements.length} isolated element(s): lang=${lang}, theme=${theme} ---`);
+                    await browser.forceLoadLazyImages({ timeout: 8000 });
+                    for (const element of elements) {
+                        const elementResult = await captureIsolatedElement(browser, element, apiKey, opts.model);
+                        if (elementResult.success) {
+                            const elFilename = `${element.name}__${lang}_${theme}.png`;
+                            const elPath = path.join(outputDir, elFilename);
+                            await fs.writeFile(elPath, elementResult.buffer);
+                            logger.success(`Element "${element.name}" saved: ${elPath}`);
+                        }
+                        else {
+                            logger.error(`Element "${element.name}" failed: ${elementResult.assessment}`);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    finally {
+        await browser.close();
+        logger.info('Browser closed');
+    }
+    // Track capture completion
+    const successes = manifest.captures.filter(c => c.result.success).length;
+    const total = manifest.captures.length;
+    const totalScreenshots = manifest.captures.reduce((sum, c) => sum + c.screenshots.length, 0);
+    const totalTokens = manifest.captures.reduce((sum, c) => sum + c.result.usage.reduce((s, u) => s + (u.totalTokens ?? 0), 0), 0);
+    getPostHog().capture({
+        distinctId: DISTINCT_ID,
+        event: 'capture_completed',
+        properties: {
+            url: opts.url,
+            model: opts.model,
+            successes,
+            total,
+            total_workflow_screenshots: totalScreenshots,
+            total_tokens: totalTokens,
+            all_succeeded: successes === total,
+        },
+    });
+    // Write manifest (strip Buffer fields from screenshots before serializing)
+    const manifestForJson = stripBuffersFromManifest(manifest);
+    const manifestPath = path.join(outputDir, 'manifest.json');
+    await fs.writeFile(manifestPath, JSON.stringify(manifestForJson, null, 2));
+    logger.info(`Manifest saved: ${manifestPath}`);
+    // Summary
+    if (successes === total) {
+        logger.success(`Done: ${successes}/${total} captures succeeded (${totalScreenshots} workflow screenshots)`);
+    }
+    else {
+        logger.error(`Done: ${successes}/${total} captures succeeded (${totalScreenshots} workflow screenshots)`);
+    }
+    await shutdownPostHog();
+}
+// Only run when executed directly (not imported by tests)
+const isDirectExecution = process.argv[1] && (process.argv[1].endsWith('/cli.js') ||
+    process.argv[1].endsWith('/cli.ts'));
+if (isDirectExecution) {
+    // Use parseAsync so that subcommand action handlers (e.g. `skill`) complete
+    // before any fallback code runs. Without this, the sync `parse()` would
+    // trigger `main()` before the async skill handler can call process.exit().
+    program.parseAsync().then(async () => {
+        // If a subcommand was invoked, its action handler calls process.exit().
+        // The code below only runs for the default capture command.
+        await main();
+    }).catch(async (err) => {
+        getPostHog().captureException(err, DISTINCT_ID);
+        await shutdownPostHog();
+        logger.error(err.message);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/clip-orchestrator.d.ts

@@ -0,0 +1,148 @@
+import type { ClipDefinition, ClipOptions, LoginCredentials, VideoPlan, StepUsage, VideoPhase } from './types.js';
+export interface ClipTarget {
+    id: string;
+    label: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+}
+export interface ClipOrchestratorConfig {
+    url: string;
+    clips: ClipDefinition[];
+    targets: ClipTarget[];
+    outputScale?: number;
+    langs: string[];
+    themes: Array<'light' | 'dark'>;
+    clipOptions?: ClipOptions;
+    credentials?: LoginCredentials;
+    model: string;
+    apiKey: string;
+    runId: string;
+    presetId?: string;
+    projectId?: string;
+    langInstructions?: string;
+    themeInstructions?: string;
+    navigationInstructions?: string;
+    abortSignal?: AbortSignal;
+    /** Fallback model used when the primary model fails to produce tool calls (e.g. in repair lane). */
+    fallbackModel?: string;
+    /** Per-clip timeout in milliseconds. Default: 180_000 (3 minutes). */
+    perClipTimeoutMs?: number;
+}
+export interface ClipVariantResult {
+    clipId: string;
+    clipName: string;
+    clipScript: string;
+    targetId: string;
+    targetLabel: string;
+    viewportWidth: number;
+    viewportHeight: number;
+    lang: string;
+    theme: string;
+    success: boolean;
+    gifPath?: string;
+    mp4Path?: string;
+    thumbnailPath?: string;
+    durationMs: number;
+    fileSizeBytes?: number;
+    plan?: VideoPlan;
+    stepsExecuted: number;
+    assessment: string;
+    failedPhase?: 'preflight' | 'planning' | 'dry_run' | 'recording' | 'postprocess';
+    failedStepIndex?: number;
+    failedSubphase?: string;
+    usage: StepUsage[];
+}
+export interface ClipOrchestratorResult {
+    results: ClipVariantResult[];
+    totalClips: number;
+    successCount: number;
+}
+export interface ClipOrchestratorCallbacks {
+    onClipStart?: (data: {
+        clipId: string;
+        clipName: string;
+        variantId: string;
+        target: {
+            width: number;
+            height: number;
+        };
+        lang: string;
+        theme: string;
+        clipIndex: number;
+        totalClips: number;
+    }) => void;
+    onClipPhase?: (data: {
+        clipId: string;
+        variantId: string;
+        phase: VideoPhase;
+    }) => void;
+    onClipStep?: (data: {
+        clipId: string;
+        variantId: string;
+        stepIndex: number;
+        total: number;
+        description: string;
+        phase: 'dry_run' | 'recording';
+    }) => void;
+    onClipStepResult?: (data: {
+        clipId: string;
+        variantId: string;
+        stepIndex: number;
+        ok: boolean;
+        reason?: string;
+    }) => void;
+    onClipRecordingDone?: (data: {
+        clipId: string;
+        variantId: string;
+        success: boolean;
+        gifPath?: string;
+        mp4Path?: string;
+        thumbnailPath?: string;
+        durationMs: number;
+        fileSizeBytes?: number;
+        lang: string;
+        theme: string;
+        targetId: string;
+        targetLabel: string;
+        assessment?: string;
+        failedPhase?: 'preflight' | 'planning' | 'dry_run' | 'recording' | 'postprocess';
+        failedStepIndex?: number;
+        failedSubphase?: string;
+    }) => void;
+    onClipPostprocessStart?: (data: {
+        clipId: string;
+        variantId: string;
+    }) => void;
+    onClipPostprocessDone?: (data: {
+        clipId: string;
+        variantId: string;
+        success: boolean;
+        gifPath?: string;
+        mp4Path?: string;
+    }) => void;
+    onClipsAllDone?: (data: {
+        totalClips: number;
+        successCount: number;
+    }) => void;
+    onLog?: (entry: {
+        level: string;
+        message: string;
+        timestamp: number;
+    }) => void;
+    /** Emit a live Playwright screenshot (base64 JPEG) for real-time preview in the UI. */
+    onScreenshot?: (base64: string) => void;
+}
+/**
+ * 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 declare function runClipOrchestrator(config: ClipOrchestratorConfig, callbacks?: ClipOrchestratorCallbacks): Promise<ClipOrchestratorResult>;