autokap 1.0.7 → 1.0.10

package/dist/v2/cli-runner-local.js

@@ -0,0 +1,91 @@
+/**
+ * Capture Agent — CLI command wrapper
+ *
+ * `autokap run` stays local-first: Playwright runs on the user's machine.
+ * The server only provides the compiled program and persists artifacts/results.
+ */
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { logger } from '../logger.js';
+import { parseProgram } from './schema.js';
+import { runCapture } from './cli-runner.js';
+export async function runLocal(presetId, opts) {
+    let program;
+    if (opts.program) {
+        try {
+            const raw = await fs.readFile(opts.program, 'utf-8');
+            program = parseProgram(JSON.parse(raw));
+            logger.info(`[capture] Loaded program from file: ${opts.program}`);
+        }
+        catch (err) {
+            logger.error(`[capture] Failed to load program: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    }
+    const run = await runCapture({
+        presetId,
+        program,
+        headed: opts.headed,
+        onProgress: (event) => {
+            const prefix = `[capture][${event.variantId}]`;
+            switch (event.type) {
+                case 'variant_start':
+                    logger.info(`${prefix} Starting variant`);
+                    break;
+                case 'variant_end':
+                    logger.info(`${prefix} ${event.status === 'ok' ? 'DONE' : 'FAILED'}: ${event.message}`);
+                    break;
+                case 'opcode_start':
+                    logger.info(`${prefix}[${event.opcodeIndex}] >> ${event.opcodeKind}: ${event.message}`);
+                    break;
+                case 'opcode_end':
+                    if (event.status === 'ok') {
+                        logger.info(`${prefix}[${event.opcodeIndex}] << OK (${event.opcodeKind})`);
+                    }
+                    else if (event.status === 'recovered') {
+                        logger.warn(`${prefix}[${event.opcodeIndex}] << RECOVERED: ${event.message}`);
+                    }
+                    else {
+                        logger.error(`${prefix}[${event.opcodeIndex}] << FAILED: ${event.message}`);
+                    }
+                    break;
+                case 'recovery':
+                    logger.warn(`${prefix}[${event.opcodeIndex}] RECOVERY: ${event.message}`);
+                    break;
+                case 'breaker_trip':
+                    logger.error(`${prefix} CIRCUIT BREAKER: ${event.message}`);
+                    break;
+            }
+        },
+    });
+    if (run.runResult && opts.output) {
+        await persistArtifactsLocally(presetId, opts.output, run.runResult.variantResults);
+    }
+    if (!run.success) {
+        logger.error(`Error: ${run.error ?? run.runResult?.error ?? 'capture failed'}`);
+        process.exit(1);
+    }
+    process.exit(0);
+}
+async function persistArtifactsLocally(presetId, outputDirOption, variants) {
+    const outputDir = path.resolve(outputDirOption);
+    await fs.mkdir(outputDir, { recursive: true });
+    for (const variant of variants) {
+        for (let index = 0; index < variant.artifacts.length; index += 1) {
+            const artifact = variant.artifacts[index];
+            const ext = artifact.mimeType === 'image/png'
+                ? 'png'
+                : artifact.mimeType === 'image/jpeg'
+                    ? 'jpg'
+                    : artifact.mimeType.includes('gif')
+                        ? 'gif'
+                        : artifact.mimeType.includes('mp4')
+                            ? 'mp4'
+                            : 'webm';
+            const filePath = path.join(outputDir, `v2-${presetId.slice(0, 8)}-${variant.variantId}-${index}.${ext}`);
+            await fs.writeFile(filePath, artifact.buffer);
+            logger.info(`[capture] Artifact saved locally: ${filePath}`);
+        }
+    }
+}
+//# sourceMappingURL=cli-runner-local.js.map

package/dist/v2/cli-runner.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Capture Agent — CLI Runner
+ *
+ * Entry point for V2 execution from the CLI.
+ * Flow:
+ * 1. Authenticate via stored API key
+ * 2. Fetch compiled program from server
+ * 3. Validate program against Zod schema
+ * 4. Launch local Playwright browser per variant
+ * 5. Execute program via opcode-runner
+ * 6. Upload artifacts + telemetry to server
+ */
+import { type ProgressEvent } from './opcode-runner.js';
+import type { ExecutionProgram, RunResult } from './types.js';
+export interface CLIRunnerOptions {
+    /** Preset ID to run */
+    presetId: string;
+    /** Override: provide program directly instead of fetching from server */
+    program?: ExecutionProgram;
+    /** Selector memory map (fetched from server or cached locally) */
+    selectorMemory?: Record<string, string[]>;
+    /** Show browser window. Default: false (headless) */
+    headed?: boolean;
+    /** Abort signal for cancellation */
+    abortSignal?: AbortSignal;
+    /** Progress callback */
+    onProgress?: (event: ProgressEvent) => void;
+}
+export interface CLIRunResult {
+    success: boolean;
+    runResult?: RunResult;
+    error?: string;
+}
+export declare function runCapture(options: CLIRunnerOptions): Promise<CLIRunResult>;

package/dist/v2/cli-runner.js

@@ -0,0 +1,300 @@
+/**
+ * Capture Agent — CLI Runner
+ *
+ * Entry point for V2 execution from the CLI.
+ * Flow:
+ * 1. Authenticate via stored API key
+ * 2. Fetch compiled program from server
+ * 3. Validate program against Zod schema
+ * 4. Launch local Playwright browser per variant
+ * 5. Execute program via opcode-runner
+ * 6. Upload artifacts + telemetry to server
+ */
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { Browser } from '../browser.js';
+import { requireConfig } from '../cli-config.js';
+import { WebPlaywrightLocal } from './web-playwright-local.js';
+import { executeProgram } from './opcode-runner.js';
+import { RecoveryChainImpl } from './recovery-chain.js';
+import { parseProgram } from './schema.js';
+import { buildCursorOverlayScript } from '../legacy/video-prompts.js';
+import { logger } from '../logger.js';
+// ── Main entry point ────────────────────────────────────────────────
+export async function runCapture(options) {
+    const config = await requireConfig();
+    // Step 1: Get the compiled program
+    let program;
+    if (options.program) {
+        program = options.program;
+    }
+    else {
+        const fetched = await fetchProgram(config, options.presetId);
+        if (!fetched.success) {
+            return { success: false, error: fetched.error };
+        }
+        program = fetched.program;
+    }
+    // Step 2: Validate the program
+    try {
+        program = parseProgram(program);
+    }
+    catch (err) {
+        return { success: false, error: `program validation failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    // Persist against the canonical preset identifier selected by the CLI,
+    // even if the compiled program carries a human-readable preset slug/name.
+    if (program.presetId !== options.presetId) {
+        program = {
+            ...program,
+            presetId: options.presetId,
+        };
+    }
+    logger.info(`[capture] Running preset "${options.presetId}" — ${program.steps.length} opcodes, ${program.variants.length} variant(s)`);
+    // Step 3: Set up recovery chain
+    const recoveryChain = new RecoveryChainImpl({
+        selectorMemory: options.selectorMemory,
+        programSteps: program.steps,
+        // LLM provider will be wired in when the healer is integrated with OpenRouter
+    });
+    const llmConfig = resolveCliLLMConfig();
+    // Step 4: Execute the program
+    const runOptions = {
+        recoveryChain,
+        abortSignal: options.abortSignal,
+        llmConfig,
+        presetName: program.presetId,
+        onProgress: (event) => {
+            logProgress(event);
+            options.onProgress?.(event);
+        },
+    };
+    const createAdapter = async (variant) => {
+        const browserOptions = {
+            headed: options.headed ?? false,
+            viewport: variant.viewport,
+            deviceScaleFactor: variant.deviceScaleFactor,
+            lang: variant.locale,
+            colorScheme: variant.theme,
+            storageState: program.preconditions.storageState,
+        };
+        const recordable = program.mediaMode === 'clip';
+        let recordingDir;
+        let browser;
+        if (recordable) {
+            recordingDir = await fs.mkdtemp(path.join(os.tmpdir(), `autokap-${program.mediaMode}-`));
+            browser = await Browser.forVideoRecording(browserOptions, recordingDir, buildCursorOverlayScript(program.artifactPlan.cursorTheme ?? 'minimal'));
+        }
+        else {
+            browser = await Browser.fromPool(browserOptions);
+            await browser.launch();
+        }
+        await applyPreconditions(browser, program);
+        return new WebPlaywrightLocal(browser, recordingDir);
+    };
+    const runResult = await executeProgram(program, createAdapter, runOptions);
+    if (runResult.success) {
+        logger.info(`[capture] Run completed successfully — ${runResult.telemetry.totalOpcodes} opcodes, ${runResult.telemetry.recoveredOpcodes} recovered, ${runResult.totalDurationMs}ms`);
+    }
+    else {
+        logger.error(`[capture] Run failed: ${runResult.error}`);
+    }
+    try {
+        await uploadResults(config, program, runResult);
+    }
+    catch (err) {
+        logger.error(`[capture] Failed to upload results: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return { success: runResult.success, runResult };
+}
+// ── Server communication ────────────────────────────────────────────
+async function fetchProgram(config, presetId) {
+    try {
+        const url = `${config.apiBaseUrl}/api/v2/programs/${presetId}`;
+        const response = await fetch(url, {
+            headers: {
+                'Authorization': `Bearer ${config.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+        });
+        if (!response.ok) {
+            return { success: false, error: `server returned ${response.status}: ${await response.text()}` };
+        }
+        const data = await response.json();
+        return { success: true, program: data };
+    }
+    catch (err) {
+        return { success: false, error: `failed to fetch program: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+async function uploadResults(config, program, result) {
+    const runId = randomUUID();
+    // Upload artifacts
+    for (const variant of result.variantResults) {
+        const variantSpec = program.variants.find((entry) => entry.id === variant.variantId);
+        for (const artifact of variant.artifacts) {
+            const formData = new FormData();
+            const filename = buildArtifactFilename(program.presetId, variant.variantId, artifact);
+            formData.append('file', new Blob([new Uint8Array(artifact.buffer)], { type: artifact.mimeType }), filename);
+            formData.append('presetId', program.presetId);
+            formData.append('programVersion', String(program.programVersion));
+            formData.append('compileFingerprint', program.compileFingerprint);
+            formData.append('runId', runId);
+            formData.append('variantId', variant.variantId);
+            formData.append('targetId', variantSpec?.targetId ?? variant.variantId);
+            formData.append('targetLabel', variantSpec?.targetLabel ?? variantSpec?.deviceFrame ?? variant.variantId);
+            formData.append('mediaMode', artifact.mediaMode);
+            formData.append('mimeType', artifact.mimeType);
+            formData.append('captureType', artifact.captureType ?? 'fullpage');
+            formData.append('captureUrl', artifact.captureUrl ?? program.baseUrl);
+            formData.append('lang', variantSpec?.locale ?? 'en');
+            formData.append('theme', variantSpec?.theme ?? 'light');
+            if (variantSpec?.deviceFrame) {
+                formData.append('deviceFrame', variantSpec.deviceFrame);
+            }
+            formData.append('viewport', JSON.stringify(variantSpec?.viewport ?? null));
+            formData.append('artifactPlan', JSON.stringify(program.artifactPlan));
+            if (artifact.altText) {
+                formData.append('altText', artifact.altText);
+            }
+            if (artifact.elementSelector) {
+                formData.append('elementSelector', artifact.elementSelector);
+            }
+            if (artifact.captureId) {
+                formData.append('captureId', artifact.captureId);
+            }
+            if (artifact.captureName) {
+                formData.append('captureName', artifact.captureName);
+            }
+            if (artifact.clipId) {
+                formData.append('clipId', artifact.clipId);
+            }
+            if (artifact.clipName) {
+                formData.append('clipName', artifact.clipName);
+            }
+            if (artifact.stepDescription) {
+                formData.append('stepDescription', artifact.stepDescription);
+            }
+            if (typeof artifact.stepIndex === 'number') {
+                formData.append('stepIndex', String(artifact.stepIndex));
+            }
+            if (typeof artifact.durationMs === 'number') {
+                formData.append('durationMs', String(artifact.durationMs));
+            }
+            if (typeof artifact.trimStartMs === 'number') {
+                formData.append('trimStartMs', String(artifact.trimStartMs));
+            }
+            const response = await fetch(`${config.apiBaseUrl}/api/v2/artifacts`, {
+                method: 'POST',
+                headers: { 'Authorization': `Bearer ${config.apiKey}` },
+                body: formData,
+            });
+            if (!response.ok) {
+                throw new Error(`artifact upload failed for ${variant.variantId}: ${response.status} ${await response.text()}`);
+            }
+        }
+    }
+    // Upload telemetry + healer patches
+    const telemetryResponse = await fetch(`${config.apiBaseUrl}/api/v2/telemetry`, {
+        method: 'POST',
+        headers: {
+            'Authorization': `Bearer ${config.apiKey}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            runId,
+            presetId: program.presetId,
+            programVersion: program.programVersion,
+            compileFingerprint: program.compileFingerprint,
+            success: result.success,
+            mediaMode: program.mediaMode,
+            telemetry: result.telemetry,
+            healerPatches: result.healerPatches,
+            runResult: result,
+            totalDurationMs: result.totalDurationMs,
+            variantSummaries: result.variantResults.map(v => ({
+                variantId: v.variantId,
+                success: v.success,
+                opcodeCount: v.opcodeResults.length,
+                artifactCount: v.artifacts.length,
+                durationMs: v.durationMs,
+                error: v.error,
+            })),
+        }),
+    });
+    if (!telemetryResponse.ok) {
+        throw new Error(`telemetry upload failed: ${telemetryResponse.status} ${await telemetryResponse.text()}`);
+    }
+}
+async function applyPreconditions(browser, program) {
+    const { preconditions } = program;
+    const hasConcreteSessionState = Boolean(preconditions.storageState
+        || (preconditions.cookies && preconditions.cookies.length > 0)
+        || (preconditions.sessionStorage && Object.keys(preconditions.sessionStorage).length > 0));
+    if (preconditions.auth === 'authenticated' && !hasConcreteSessionState) {
+        throw new Error('authenticated precondition requires storageState, cookies, or sessionStorage');
+    }
+    if (preconditions.credentialsId && !hasConcreteSessionState) {
+        throw new Error(`credentialsId "${preconditions.credentialsId}" is not resolved by the CLI runtime; provide storageState/cookies/sessionStorage in the program`);
+    }
+    if (preconditions.cookies && preconditions.cookies.length > 0) {
+        await browser.addCookies(preconditions.cookies);
+    }
+    if (preconditions.sessionStorage && Object.keys(preconditions.sessionStorage).length > 0) {
+        await browser.prepareSessionStorage(preconditions.sessionStorage, { replace: false });
+    }
+}
+function resolveCliLLMConfig() {
+    const apiKey = process.env.OPENROUTER_API_KEY?.trim();
+    if (!apiKey)
+        return undefined;
+    return {
+        apiKey,
+        model: process.env.AUTOKAP_V2_LLM_MODEL?.trim() || undefined,
+    };
+}
+function buildArtifactFilename(presetId, variantId, artifact) {
+    const ext = artifact.mimeType === 'image/jpeg'
+        ? 'jpg'
+        : artifact.mimeType === 'image/png'
+            ? 'png'
+            : artifact.mimeType.includes('gif')
+                ? 'gif'
+                : artifact.mimeType.includes('mp4')
+                    ? 'mp4'
+                    : 'webm';
+    const stepToken = typeof artifact.stepIndex === 'number' ? `-${artifact.stepIndex}` : '';
+    return `${presetId}-${variantId}${stepToken}.${ext}`;
+}
+// ── Progress logging ────────────────────────────────────────────────
+function logProgress(event) {
+    const prefix = `[capture][${event.variantId}]`;
+    switch (event.type) {
+        case 'variant_start':
+            logger.info(`${prefix} Starting variant`);
+            break;
+        case 'variant_end':
+            logger.info(`${prefix} ${event.status === 'ok' ? 'Completed' : 'Failed'}: ${event.message}`);
+            break;
+        case 'opcode_start':
+            logger.debug(`${prefix}[${event.opcodeIndex}] ${event.opcodeKind}: ${event.message}`);
+            break;
+        case 'opcode_end':
+            if (event.status === 'failed') {
+                logger.error(`${prefix}[${event.opcodeIndex}] FAILED: ${event.message}`);
+            }
+            else if (event.status === 'recovered') {
+                logger.warn(`${prefix}[${event.opcodeIndex}] RECOVERED: ${event.message}`);
+            }
+            break;
+        case 'recovery':
+            logger.warn(`${prefix}[${event.opcodeIndex}] Recovery: ${event.message}`);
+            break;
+        case 'breaker_trip':
+            logger.error(`${prefix} Circuit breaker tripped: ${event.message}`);
+            break;
+    }
+}
+//# sourceMappingURL=cli-runner.js.map

package/dist/v2/compiler-prompts.d.ts

@@ -0,0 +1,27 @@
+/**
+ * V2 Capture Agent — Compiler Prompts
+ *
+ * System and user prompts for compiling natural-language presets
+ * into ExecutionProgramV2 opcodes.
+ */
+import type { MediaMode, VariantSpec } from './types.js';
+export interface CompilerPromptContext {
+    /** User-authored preset prompt (natural language) */
+    presetPrompt: string;
+    /** Base URL of the target site */
+    baseUrl: string;
+    /** Media mode */
+    mediaMode: MediaMode;
+    /** Variant specifications */
+    variants: VariantSpec[];
+    /** AKTree snapshot from exploration (optional) */
+    akTreeSnapshot?: string;
+    /** Page URL at time of exploration */
+    exploredUrl?: string;
+    /** Whether auth is required */
+    requiresAuth: boolean;
+    /** Navigation instructions (if separate from capture instructions) */
+    navigationInstructions?: string;
+}
+export declare function buildCompilerSystemPrompt(): string;
+export declare function buildCompilerUserPrompt(context: CompilerPromptContext): string;

package/dist/v2/compiler-prompts.js

@@ -0,0 +1,123 @@
+/**
+ * V2 Capture Agent — Compiler Prompts
+ *
+ * System and user prompts for compiling natural-language presets
+ * into ExecutionProgramV2 opcodes.
+ */
+export function buildCompilerSystemPrompt() {
+    return `You are a web automation compiler. You transform natural-language instructions into a deterministic sequence of browser opcodes.
+
+## Opcode Reference
+
+Each opcode is a JSON object with these common fields:
+- kind: the opcode type (see below)
+- description: human-readable description of what this step does
+- postcondition: { type, pattern?, selector?, text?, threshold?, waitMs? }
+- recovery: { retries: 2, useSelectorMemory: true, useAltInteraction: true, allowReload: false, allowHealer: true }
+- timeoutMs: max time in ms (default 15000)
+- maxFailures: max recovery attempts (default 3)
+
+### Available Opcodes
+
+NAVIGATE { url: string }
+  Navigate to a URL. Postcondition: route_matches.
+
+DISMISS_OVERLAYS {}
+  Dismiss cookie banners, popups, chat widgets. Postcondition: overlay_dismissed.
+
+ASSERT_ROUTE { urlPattern: string }
+  Verify the current URL matches a pattern. Postcondition: route_matches.
+
+ASSERT_SURFACE { selectors: string[], matchAll: boolean }
+  Verify elements are visible. Postcondition: element_visible.
+
+CLICK { selector: string, fingerprint?: string, selectorAlternates?: string[] }
+  Click an element. Postcondition: what CHANGED as a result (not "element was clicked").
+
+TYPE { selector: string, text: string, clearFirst: boolean }
+  Type text into a field. Postcondition: text_contains or any_change.
+
+PRESS_KEY { key: string }
+  Press a keyboard key. Postcondition: any_change.
+
+WAIT_FOR { selector: string, state: "visible"|"attached" }
+  Wait for an element. Postcondition: element_visible.
+
+SET_LOCALE { locale: string, method: "browser_context"|"ui_interaction"|"storage", selector?: string }
+  Set the page locale. Postcondition: always.
+
+SET_THEME { theme: "light"|"dark", method: "color_scheme"|"ui_interaction"|"storage", selector?: string }
+  Set the color scheme. Postcondition: always.
+
+SCROLL { direction: "up"|"down"|"left"|"right", amount?: number, targetSelector?: string }
+  Scroll the page. Postcondition: element_visible (for the target) or always.
+
+CAPTURE_SCREENSHOT { elementSelector?: string }
+  Take a screenshot. Postcondition: always.
+
+BEGIN_CLIP {} / END_CLIP {}
+  Start/stop clip recording. Postcondition: always.
+
+BEGIN_VIDEO {} / END_VIDEO {}
+  Start/stop video recording. Postcondition: always.
+
+### Postcondition Types
+- route_matches: URL pathname matches glob pattern. e.g. { type: "route_matches", pattern: "/dashboard*" }
+- element_visible: Element matching selector is visible. e.g. { type: "element_visible", selector: "h1" }
+- element_absent: Element is NOT visible. e.g. { type: "element_absent", selector: ".modal" }
+- text_contains: Element text includes string. e.g. { type: "text_contains", selector: "#name", text: "John" }
+- overlay_dismissed: No blocking overlays. e.g. { type: "overlay_dismissed" }
+- screenshot_stable: Page visually stable. e.g. { type: "screenshot_stable", threshold: 0.01 }
+- any_change: Any detectable change (soft). e.g. { type: "any_change" }
+- always: Always passes. e.g. { type: "always" }
+
+## Critical Rules
+
+1. Every CLICK/TYPE must have a postcondition that describes WHAT CHANGED, not just "element was clicked".
+   Bad: { type: "always" } after a click
+   Good: { type: "element_visible", selector: ".dropdown-menu" } after clicking a dropdown trigger
+
+2. Always start with NAVIGATE + DISMISS_OVERLAYS.
+
+3. Use real CSS selectors from the AKTree when provided. Prefer data-testid, id, or semantic selectors over fragile class-based ones.
+
+4. For multi-step flows (login, modal navigation), add WAIT_FOR between steps to ensure the page has transitioned.
+
+5. For clips/videos, place BEGIN_CLIP/END_CLIP or BEGIN_VIDEO/END_VIDEO around the interaction portion only (not navigation).
+
+6. Include selectorAlternates when you can infer multiple valid selectors for the same element.
+
+7. Set waitMs on postconditions that involve page transitions (login, navigation) to at least 10000.
+
+## Response Format
+
+Return ONLY a JSON array of opcodes. No markdown, no explanation.`;
+}
+export function buildCompilerUserPrompt(context) {
+    const parts = [];
+    parts.push(`## Preset Instructions\n${context.presetPrompt}`);
+    parts.push(`\n## Target\nURL: ${context.baseUrl}\nMedia: ${context.mediaMode}`);
+    if (context.navigationInstructions) {
+        parts.push(`\n## Navigation Instructions\n${context.navigationInstructions}`);
+    }
+    if (context.requiresAuth) {
+        parts.push(`\n## Authentication\nThis preset requires authentication. Use TYPE opcodes with placeholder text "{{email}}" and "{{password}}" for credential fields. The runtime will substitute real credentials.`);
+    }
+    if (context.variants.length > 0) {
+        const variantDesc = context.variants.map(v => {
+            const parts = [`${v.viewport.width}x${v.viewport.height}`];
+            if (v.locale)
+                parts.push(`locale: ${v.locale}`);
+            if (v.theme)
+                parts.push(`theme: ${v.theme}`);
+            return parts.join(', ');
+        }).join('\n  ');
+        parts.push(`\n## Variants\nThe program will be executed once per variant. Locale/theme switching is handled by the runtime via SET_LOCALE/SET_THEME opcodes.\n  ${variantDesc}`);
+    }
+    if (context.akTreeSnapshot) {
+        parts.push(`\n## Live AKTree (from site exploration)\nURL at exploration: ${context.exploredUrl ?? context.baseUrl}\n\n${context.akTreeSnapshot.slice(0, 12000)}`);
+    }
+    parts.push(`\nCompile these instructions into a JSON array of opcodes. Use real selectors from the AKTree when available.`);
+    return parts.join('\n');
+}
+//# sourceMappingURL=compiler-prompts.js.map

package/dist/v2/compiler.d.ts

@@ -0,0 +1,37 @@
+/**
+ * V2 Capture Agent — Preset Compiler
+ *
+ * Transforms natural-language presets into ExecutionProgramV2.
+ * Flow:
+ * 1. Parse preset metadata (URL, variants, auth, media mode)
+ * 2. (Optional) Explore the target site to capture real AKTree selectors
+ * 3. LLM generates opcode sequence grounded in real DOM
+ * 4. Validate output against Zod schema
+ * 5. Return compiled program with fingerprint
+ */
+import type { ExecutionProgramV2, VariantSpec, MediaMode, PreconditionSpec } from './types.js';
+export interface CompilerLLMProvider {
+    call(systemPrompt: string, userPrompt: string): Promise<{
+        response: string;
+        costEur: number;
+    }>;
+}
+export interface PresetInput {
+    presetId: string;
+    prompt: string;
+    baseUrl: string;
+    mediaMode: MediaMode;
+    variants: VariantSpec[];
+    preconditions: PreconditionSpec;
+    navigationInstructions?: string;
+    /** Pre-captured AKTree from exploration */
+    akTreeSnapshot?: string;
+    exploredUrl?: string;
+}
+export interface CompilerResult {
+    success: boolean;
+    program?: ExecutionProgramV2;
+    error?: string;
+    costEur: number;
+}
+export declare function compilePreset(input: PresetInput, llmProvider: CompilerLLMProvider): Promise<CompilerResult>;