autokap 1.0.6 → 1.0.8

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>;

package/dist/v2/compiler.js

@@ -0,0 +1,147 @@
+/**
+ * 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 { DEFAULT_RECOVERY_POLICY } from './types.js';
+import { ExecutionOpcodeSchema, ExecutionProgramV2Schema } from './schema.js';
+import { buildCompilerSystemPrompt, buildCompilerUserPrompt } from './compiler-prompts.js';
+// ── Main compile function ───────────────────────────────────────────
+export async function compilePreset(input, llmProvider) {
+    const systemPrompt = buildCompilerSystemPrompt();
+    const context = {
+        presetPrompt: input.prompt,
+        baseUrl: input.baseUrl,
+        mediaMode: input.mediaMode,
+        variants: input.variants,
+        requiresAuth: input.preconditions.auth === 'authenticated',
+        navigationInstructions: input.navigationInstructions,
+        akTreeSnapshot: input.akTreeSnapshot,
+        exploredUrl: input.exploredUrl,
+    };
+    const userPrompt = buildCompilerUserPrompt(context);
+    try {
+        const { response, costEur } = await llmProvider.call(systemPrompt, userPrompt);
+        // Parse opcodes from LLM response
+        const opcodes = parseOpcodeResponse(response);
+        if (!opcodes) {
+            return { success: false, error: 'LLM response is not a valid JSON array of opcodes', costEur };
+        }
+        // Validate each opcode
+        const validatedOpcodes = [];
+        for (let i = 0; i < opcodes.length; i++) {
+            const enriched = enrichOpcode(opcodes[i]);
+            const result = ExecutionOpcodeSchema.safeParse(enriched);
+            if (!result.success) {
+                return {
+                    success: false,
+                    error: `opcode ${i} validation failed: ${result.error}`,
+                    costEur,
+                };
+            }
+            validatedOpcodes.push(result.data);
+        }
+        if (validatedOpcodes.length === 0) {
+            return { success: false, error: 'LLM produced zero opcodes', costEur };
+        }
+        // Build the program
+        const program = {
+            presetId: input.presetId,
+            programVersion: 1,
+            mediaMode: input.mediaMode,
+            baseUrl: input.baseUrl,
+            variants: input.variants,
+            preconditions: input.preconditions,
+            steps: validatedOpcodes,
+            artifactPlan: {
+                mediaMode: input.mediaMode,
+                ...(input.mediaMode === 'clip' ? { format: { clipFormat: 'gif' } } : {}),
+            },
+            compileFingerprint: computeFingerprint(input),
+            compiledAt: new Date().toISOString(),
+            compiledWith: 'gemini-3-flash',
+        };
+        // Final program-level validation
+        const programResult = ExecutionProgramV2Schema.safeParse(program);
+        if (!programResult.success) {
+            return {
+                success: false,
+                error: `program validation failed: ${programResult.error}`,
+                costEur,
+            };
+        }
+        return { success: true, program: programResult.data, costEur };
+    }
+    catch (err) {
+        return {
+            success: false,
+            error: `compiler error: ${err instanceof Error ? err.message : String(err)}`,
+            costEur: 0,
+        };
+    }
+}
+// ── Response parsing ────────────────────────────────────────────────
+function parseOpcodeResponse(response) {
+    try {
+        // Strip markdown code fences if present
+        let cleaned = response.trim();
+        if (cleaned.startsWith('```')) {
+            cleaned = cleaned.replace(/^```(?:json)?\s*/, '').replace(/```\s*$/, '').trim();
+        }
+        const parsed = JSON.parse(cleaned);
+        if (Array.isArray(parsed))
+            return parsed;
+        // Some models wrap in { steps: [...] } or { opcodes: [...] }
+        if (parsed && typeof parsed === 'object') {
+            if (Array.isArray(parsed.steps))
+                return parsed.steps;
+            if (Array.isArray(parsed.opcodes))
+                return parsed.opcodes;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Enriches a raw opcode from LLM with default values for fields
+ * the LLM might omit.
+ */
+function enrichOpcode(raw) {
+    return {
+        ...raw,
+        description: raw.description || `${raw.kind} step`,
+        postcondition: raw.postcondition ?? { type: 'always' },
+        recovery: raw.recovery ?? { ...DEFAULT_RECOVERY_POLICY },
+        timeoutMs: raw.timeoutMs ?? 15000,
+        maxFailures: raw.maxFailures ?? 3,
+        // Type-specific defaults
+        ...(raw.kind === 'TYPE' && raw.clearFirst === undefined ? { clearFirst: true } : {}),
+        ...(raw.kind === 'ASSERT_SURFACE' && raw.matchAll === undefined ? { matchAll: true } : {}),
+        ...(raw.kind === 'WAIT_FOR' && !raw.state ? { state: 'visible' } : {}),
+    };
+}
+// ── Fingerprint ─────────────────────────────────────────────────────
+function computeFingerprint(input) {
+    const content = JSON.stringify({
+        prompt: input.prompt,
+        baseUrl: input.baseUrl,
+        mediaMode: input.mediaMode,
+        navigation: input.navigationInstructions,
+        auth: input.preconditions.auth,
+    });
+    // Simple hash
+    let hash = 0;
+    for (let i = 0; i < content.length; i++) {
+        hash = ((hash << 5) - hash + content.charCodeAt(i)) | 0;
+    }
+    return Math.abs(hash).toString(36);
+}
+//# sourceMappingURL=compiler.js.map

package/dist/v2/explorer.d.ts

@@ -0,0 +1,41 @@
+/**
+ * V2 Capture Agent — Site Explorer
+ *
+ * Deterministic exploration of the target site to capture AKTree snapshots.
+ * These snapshots ground the compiler's opcode generation in real DOM structure,
+ * preventing hallucinated selectors.
+ *
+ * The explorer uses the Browser class directly — no LLM calls.
+ */
+import type { Browser } from '../browser.js';
+import type { AKTree } from '../types.js';
+export interface ExplorationResult {
+    /** Serialized AKTree at the explored URL */
+    akTreeSerialized: string;
+    /** Raw AKTree object */
+    akTree: AKTree;
+    /** URL at time of exploration */
+    url: string;
+    /** Whether overlays were dismissed */
+    overlaysDismissed: boolean;
+}
+export interface ExploreOptions {
+    /** Target URL to explore */
+    url: string;
+    /** Dismiss overlays before capturing AKTree. Default: true */
+    dismissOverlays?: boolean;
+    /** Max time to wait for page load (ms). Default: 15000 */
+    loadTimeoutMs?: number;
+}
+/**
+ * Explores a single URL: navigates, dismisses overlays, and captures AKTree.
+ * Uses an existing Browser instance — does not create or close it.
+ */
+export declare function explorePage(browser: Browser, options: ExploreOptions): Promise<ExplorationResult>;
+/**
+ * Explores multiple URLs on the same site.
+ * Useful for presets that involve navigation across pages.
+ */
+export declare function explorePages(browser: Browser, urls: string[], options?: {
+    dismissOverlays?: boolean;
+}): Promise<ExplorationResult[]>;