autokap 1.0.6 → 1.0.8

package/dist/types.d.ts

@@ -39,6 +39,67 @@ export interface CapturePageIdentity {
     dialogTarget: boolean;
     dedicatedRoute: boolean;
 }
+export type CaptureExpectedSurfaceKind = "gallery" | "dialog_selection" | "dialog_configuration" | "editor_route" | "detail_route" | "route" | "unknown";
+export type CaptureDialogPolicy = "must_be_open" | "must_be_closed" | "allow_either";
+export type CaptureRoutePolicy = "exact_or_descendant" | "same_origin" | "ignore";
+export type CaptureReusePolicy = "verified_only" | "same_surface_only" | "never";
+export type CaptureVariantPolicy = "must_match" | "prefer_match" | "ignore";
+export interface CapturePageContract {
+    expectedSurfaceKind: CaptureExpectedSurfaceKind;
+    dialogPolicy: CaptureDialogPolicy;
+    routePolicy: CaptureRoutePolicy;
+    reusePolicy: CaptureReusePolicy;
+    variantPolicy: CaptureVariantPolicy;
+}
+export type CaptureSessionTrust = "verified" | "degraded" | "dirty";
+export interface CaptureCheckpointEvidence {
+    urlMatched: boolean;
+    dialogMatched: boolean;
+    authMatched: boolean;
+    variantMatched: boolean;
+    strongSurfaceObserved: boolean;
+    surfaceMatched?: boolean;
+    strongSurfaceSignature?: string | null;
+    primarySurface?: string | null;
+    overlaySurface?: string | null;
+    navigationSurface?: string | null;
+    configurationSurface?: string | null;
+    reasons: string[];
+}
+export interface CaptureTransitionDecision {
+    mode: CaptureSessionTrust;
+    contract: CapturePageContract;
+    evidence: CaptureCheckpointEvidence;
+    reasons: string[];
+}
+export interface CaptureBaselineResult extends CaptureTransitionDecision {
+    shouldNavigateToCanonical: boolean;
+    shouldRecreateContext: boolean;
+    allowFastPath: boolean;
+}
+export type CaptureSuccessVerdict = 'candidate_match' | 'blocked' | 'terminal_match';
+export type VariantVerdict = 'matched' | 'mismatched' | 'ambiguous' | 'not_requested';
+export type CaptureStage = 'session_bootstrap' | 'page_reachability' | 'variant_hygiene' | 'capture_readiness' | 'persist_and_handoff';
+export type RegressionCause = 'auth_mismatch' | 'route_mismatch' | 'dialog_mismatch' | 'variant_hygiene_pending' | 'surface_too_weak' | 'repair_handoff' | 'stability_pending' | 'duplicate_candidate' | 'unknown';
+export interface BlockerSet {
+    stage: CaptureStage;
+    reasons: string[];
+}
+export interface StageGate {
+    stage: CaptureStage;
+    blockers: BlockerSet;
+    regressionCause?: RegressionCause | null;
+}
+export interface ObservedTaskState {
+    authState: SessionProfileAuthState | 'ambiguous';
+    pageIdentity: CapturePageIdentity | null;
+    routeState: 'matched' | 'same_origin' | 'mismatched' | 'unknown';
+    dialogState: 'open' | 'closed' | 'ambiguous' | 'unknown';
+    variantState: VariantVerdict;
+    loadingState: 'stable' | 'loading' | 'unstable' | 'unknown';
+    surfaceConfidence: SessionValidationDiagnosticConfidence;
+    goalSatisfaction: CaptureSuccessVerdict;
+}
 export interface VariantValidatedCapture {
     pageId: string;
     prompt: string;
@@ -97,6 +158,14 @@ export interface CaptureCheckpoint {
     canonicalUrl?: string | null;
     resumeUrl?: string | null;
     pageIdentity?: CapturePageIdentity | null;
+    dialogExpected?: boolean;
+    identityKind?: CapturePageIdentityKind | null;
+    surfaceSignature?: string | null;
+    strongSurfaceSignature?: string | null;
+    pageFingerprint?: string | null;
+    sessionTrust?: CaptureSessionTrust | null;
+    checkpointEvidence?: CaptureCheckpointEvidence | null;
+    checkpointType?: 'route' | 'dialog_open' | 'config_open' | 'content_ready' | 'gallery_detail' | 'editor_ready' | 'unknown';
     verifiedAt: string;
 }
 export interface VariantCaptureRepairRecord {
@@ -135,6 +204,8 @@ export interface VariantCaptureManifest {
     expectedPageIds: string[];
     currentPageId?: string | null;
     currentPageIdentity?: CapturePageIdentity | null;
+    promptFingerprint?: string | null;
+    pagePromptFingerprints?: Record<string, string>;
     completedPages: string[];
     remainingPages: string[];
     previousValidatedCaptures: VariantValidatedCapture[];
@@ -157,6 +228,9 @@ export interface CaptureHandoffContext {
     selectorHints?: string[];
     navigationHints?: string[];
     selectorMemory?: Record<string, string[]>;
+    trust?: CaptureSessionTrust;
+    strongCheckpointId?: string | null;
+    derivedFromRepair?: boolean;
 }
 export interface BrowserOptions {
     headed: boolean;
@@ -503,7 +577,7 @@ export interface ClipOptions {
 /** Usage metadata from a single OpenRouter API call */
 export interface StepUsage {
     stepNumber: number;
-    stepType: 'agent_iteration' | 'verification' | 'element_capture' | 'video_planning' | 'video_variant_classification' | 'video_step_verification' | 'video_step_fix' | 'assistant_chat' | 'mock_data_generation' | 'page_identity_classification';
+    stepType: 'agent_iteration' | 'verification' | 'element_capture' | 'video_planning' | 'video_variant_classification' | 'video_step_verification' | 'video_step_fix' | 'assistant_chat' | 'mock_data_generation' | 'page_identity_classification' | 'capture_verification' | 'alt_text_generation' | 'healer_invocation';
     generationId: string | null;
     modelRequested: string;
     modelUsed: string | null;
@@ -532,16 +606,41 @@ export interface StepUsage {
     sessionProfileReused?: boolean;
     actionReplayUsed?: boolean;
 }
+export type AgentLane = 'fast_nav' | 'full_nav' | 'repair' | 'verification';
+export type ActionExpectedEffect = 'route_change' | 'dialog_open' | 'menu_open' | 'panel_expand' | 'selection_applied' | 'content_identity_change' | 'no_effect_ok';
+export type VerificationReadinessState = 'ready' | 'not_ready_actionable' | 'unstable_retryable';
+export type ReplayFailureCode = 'wrong_route' | 'wrong_identity' | 'missing_dialog' | 'unstable_loading' | 'anchor_unresolved' | 'late_replay_divergence' | 'duplicate_verification_skipped' | 'execution_failed' | 'verification_failed';
+export interface AgentRunTelemetry {
+    plannerCallCount: number;
+    visionCallCount: number;
+    verificationCallCount: number;
+    imageUploadCount: number;
+    verificationCacheHits: number;
+    replayTrimmedActionCount: number;
+    noEffectFailureCount: number;
+    unstableRetryableCount: number;
+    replayCheckpointMatchCount: number;
+    replayCheckpointMissCount: number;
+    replaySkipReason?: string | null;
+    replayFailReason?: string | null;
+    replayFailureCode?: ReplayFailureCode | null;
+    phaseTimingsMs: Record<string, number>;
+    reasoningEffortUsed?: 'low' | 'medium' | 'high' | 'xhigh' | 'off';
+    usedLitePageState?: boolean;
+}
 export interface VerificationResult {
     verified: boolean;
+    successVerdict?: CaptureSuccessVerdict;
     reason?: string;
-    usage: StepUsage | null;
+    usage: StepUsage[];
     fatal?: boolean;
     matchedPageId?: string | null;
     duplicateOfPageId?: string | null;
     blockingReason?: string;
     pageFingerprint?: string | null;
+    checkpointEvidence?: CaptureCheckpointEvidence | null;
     mode?: 'deterministic' | 'vision' | 'text_fallback' | 'bailout';
+    readinessState?: VerificationReadinessState;
 }
 export interface SelectorValidationResult {
     matchCount: number;
@@ -599,6 +698,7 @@ export interface AgentContextEntry {
 export interface AgentConfig {
     url: string;
     prompt: string;
+    promptFingerprint?: string;
     dark: boolean;
     langs: string[];
     outputDir: string;
@@ -633,8 +733,11 @@ export interface AgentConfig {
     }>;
     /** Language for the agent's reasoning/thinking output (e.g. "fr", "en") */
     reasoningLocale?: string;
-    /** OpenRouter reasoning effort for compatible models (e.g. Grok). "off" disables. Default: "medium". */
-    reasoningEffort?: 'low' | 'medium' | 'high' | 'off';
+    /** OpenRouter reasoning effort for compatible models. "off" disables. Default: "medium". */
+    reasoningEffort?: 'low' | 'medium' | 'high' | 'xhigh' | 'off';
+    /** Set of model IDs whose OpenRouter `supported_parameters` includes "reasoning". Resolved at capture start. */
+    reasoningCapableModels?: Set<string>;
+    lane?: AgentLane;
     /** Past errors and user corrections, compressed into actionable hints. */
     runHints?: AgentRunHint[];
     /** Known selectors from previous successful runs, keyed by step signature */
@@ -679,6 +782,9 @@ export interface AgentConfig {
      * Returns null if no pause is pending.
      */
     guidanceCallback?: () => Promise<string | null>;
+    verificationCache?: Map<string, VerificationResult>;
+    runtimeTelemetry?: AgentRunTelemetry;
+    uploadImageMode?: 'prefer_data_uri' | 'prefer_upload';
     /**
      * Optional callback to upload a screenshot buffer to external storage and return a public URL.
      * When provided, image messages use HTTPS URLs instead of base64 data URIs — improving
@@ -710,9 +816,119 @@ export interface InteractiveElement {
     visible: boolean;
     visibilityState: 'full' | 'partial' | 'offscreen';
 }
+export type AKType = 'button' | 'input' | 'link' | 'text' | 'image' | 'heading' | 'list' | 'table' | 'container' | 'icon' | 'toggle' | 'select' | 'checkbox' | 'radio' | 'slider' | 'tab' | 'modal' | 'nav' | 'form' | 'video' | 'audio' | 'iframe';
+export type SemanticPattern = 'cookie-banner' | 'modal' | 'navbar' | 'footer' | 'hero' | 'sidebar' | 'dropdown' | 'toast' | 'tooltip' | 'form' | 'card' | 'pricing-table' | 'cta-group';
+export type SemanticTrait = 'floating' | 'overlay' | 'sticky' | 'fixed' | 'above-fold' | 'below-fold' | 'full-width' | 'scrollable';
+export interface AKBounds {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface ScrollState {
+    scrollTop: number;
+    scrollLeft: number;
+    scrollHeight: number;
+    scrollWidth: number;
+    clientHeight: number;
+    clientWidth: number;
+    overflowY: boolean;
+    overflowX: boolean;
+}
+export interface OverlayInfo {
+    nodeId: string;
+    zIndex: number;
+    coveragePercent: number;
+    blocksInteraction: boolean;
+}
+export interface OverlayScopeSummary {
+    nodeId: string;
+    kind: 'dialog' | 'menu' | 'popover' | 'dropdown' | 'overlay';
+    label: string;
+    interactiveCount: number;
+    subjectTokenOverlap: number;
+    visibleLabels: string[];
+    summary: string;
+}
+export interface AKNode {
+    id: string;
+    type: AKType;
+    label: string;
+    value?: string;
+    bounds: AKBounds;
+    visible: boolean;
+    interactive: boolean;
+    state: {
+        disabled: boolean;
+        focused: boolean;
+        checked?: boolean;
+        expanded?: boolean;
+        selected?: boolean;
+    };
+    style: {
+        bgColor?: string;
+        fgColor?: string;
+        fontSize?: number;
+        opacity?: number;
+    };
+    semantic: {
+        pattern?: SemanticPattern;
+        confidence: 'high' | 'medium';
+        traits: SemanticTrait[];
+    };
+    scroll?: ScrollState;
+    attributes: Record<string, string>;
+    children: AKNode[];
+    sourceRef: string;
+}
+export interface AKPageState {
+    url: string;
+    title: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    scroll: ScrollState;
+}
+export interface AKTree {
+    root: AKNode;
+    page: AKPageState;
+    overlays: OverlayInfo[];
+}
+export interface FocusQuery {
+    type?: AKType[];
+    semantic?: SemanticPattern[];
+    trait?: SemanticTrait[];
+    interactive?: boolean;
+    visible?: boolean;
+    within?: string;
+    labelContains?: string;
+    maxDepth?: number;
+    includeAncestors?: boolean;
+}
+export interface AKNodeRuntimeIndexEntry {
+    id: string;
+    sourceRef: string;
+    bounds: AKBounds;
+    type: AKType;
+    label: string;
+    interactive: boolean;
+    visible: boolean;
+    value?: string;
+    attributes: Record<string, string>;
+    state: AKNode['state'];
+    semantic: AKNode['semantic'];
+    scroll?: ScrollState;
+}
 export interface PageState {
     cleanScreenshot: Buffer;
     screenshot: Buffer;
+    akTree: AKTree;
+    serializedAKTree: string;
+    /**
+     * Legacy observation fields retained temporarily for internal adapter paths.
+     * New screenshot-agent logic must read `akTree` / `serializedAKTree` instead.
+     */
     accessibilityTree: string;
     interactiveElements: InteractiveElement[];
     /** Simplified DOM: clean HTML structure without scripts/styles/classes, budget-capped. */
@@ -725,6 +941,8 @@ export interface PageState {
 }
 /** Lightweight page state without screenshots — used when vision is not needed. */
 export interface PageStateLite {
+    akTree: AKTree;
+    serializedAKTree: string;
     accessibilityTree: string;
     interactiveElements: InteractiveElement[];
     simplifiedDOM: string;
@@ -734,7 +952,7 @@ export interface PageStateLite {
         viewportHeight: number;
     };
 }
-export type ActionType = 'click' | 'type_text' | 'select_option' | 'scroll' | 'press_key' | 'wait' | 'dismiss_overlays' | 'search_text' | 'resize_viewport' | 'navigate_to' | 'analyze_screenshot' | 'take_screenshot' | 'ready_to_capture' | 'give_up' | 'note' | 'begin_subgoal' | 'capture_by_selector' | 'hover' | 'safe_expand' | 'scroll_to_element';
+export type ActionType = 'tap' | 'type' | 'click' | 'type_text' | 'select_option' | 'scroll' | 'press_key' | 'wait' | 'dismiss_overlays' | 'search_text' | 'resize_viewport' | 'navigate_to' | 'analyze_screenshot' | 'capture' | 'focus' | 'take_screenshot' | 'ready_to_capture' | 'give_up' | 'note' | 'begin_subgoal' | 'capture_by_selector' | 'hover' | 'safe_expand' | 'scroll_to_element';
 export interface ExecutedAction {
     iteration: number;
     action: ActionType;
@@ -743,6 +961,11 @@ export interface ExecutedAction {
     error?: string;
     outcome?: string;
     stateChanged?: boolean;
+    expectedEffect?: ActionExpectedEffect;
+    observedEffects?: string[];
+    effectConfirmed?: boolean;
+    noEffectReason?: string | null;
+    failureClass?: string | null;
     origin?: CaptureActionOrigin;
     phase?: CaptureRunPhase;
     checkpointId?: string | null;
@@ -769,6 +992,8 @@ export interface DiagnosticState {
 }
 export interface AgentResult {
     success: boolean;
+    captureCompleted?: boolean;
+    captureNodeId?: string | null;
     screenshotPath: string | null;
     screenshots: WorkflowScreenshot[];
     iterations: number;
@@ -780,7 +1005,17 @@ export interface AgentResult {
     deterministicRecoveryUsed?: boolean;
     evaluatorUsed?: boolean;
     verification?: VerificationResult;
+    telemetry?: AgentRunTelemetry;
 }
+export declare function isStrongCheckpointVerified(evidence?: CaptureCheckpointEvidence | null): boolean;
+export declare function isTerminalVerificationSuccess(verification?: VerificationResult | null): verification is VerificationResult & {
+    verified: true;
+    successVerdict?: 'terminal_match';
+};
+export declare function isTerminalAgentResultSuccess(agentResult?: Pick<AgentResult, 'success' | 'verification' | 'captureCompleted'> | null): agentResult is Pick<AgentResult, 'success' | 'verification' | 'captureCompleted'> & {
+    success: true;
+    captureCompleted?: true;
+};
 export interface CaptureManifest {
     url: string;
     prompt: string;

package/dist/types.js

@@ -1,2 +1,24 @@
-export {};
+export function isStrongCheckpointVerified(evidence) {
+    return !!evidence
+        && evidence.urlMatched
+        && evidence.dialogMatched
+        && evidence.authMatched
+        && evidence.variantMatched
+        && (evidence.surfaceMatched ?? true)
+        && evidence.strongSurfaceObserved;
+}
+export function isTerminalVerificationSuccess(verification) {
+    if (!verification?.verified)
+        return false;
+    if ((verification.successVerdict ?? 'terminal_match') !== 'terminal_match')
+        return false;
+    return isStrongCheckpointVerified(verification.checkpointEvidence ?? null);
+}
+export function isTerminalAgentResultSuccess(agentResult) {
+    if (!agentResult?.success)
+        return false;
+    if (agentResult.captureCompleted)
+        return true;
+    return isTerminalVerificationSuccess(agentResult.verification ?? null);
+}
 //# sourceMappingURL=types.js.map

package/dist/v2/action-verifier.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Capture Agent — Action Verifier
+ *
+ * Post-action validation: diff AKTree before/after an action
+ * to detect whether the action had a real effect or was intercepted.
+ */
+import type { RuntimeAdapter } from './types.js';
+export interface ActionVerification {
+    /** Whether the action caused a detectable change */
+    hadEffect: boolean;
+    /** What changed */
+    changes: ActionChange[];
+    /** Summary for logging */
+    summary: string;
+}
+export type ActionChangeKind = 'url_changed' | 'tree_structure_changed' | 'node_appeared' | 'node_disappeared' | 'overlay_changed' | 'no_change';
+export interface ActionChange {
+    kind: ActionChangeKind;
+    detail: string;
+}
+/**
+ * Captures AKTree state before and after an action to detect changes.
+ */
+export declare class ActionVerifier {
+    private beforeTree;
+    private beforeUrl;
+    captureBeforeState(adapter: RuntimeAdapter): Promise<void>;
+    verifyAfterAction(adapter: RuntimeAdapter): Promise<ActionVerification>;
+}

package/dist/v2/action-verifier.js

@@ -0,0 +1,133 @@
+/**
+ * Capture Agent — Action Verifier
+ *
+ * Post-action validation: diff AKTree before/after an action
+ * to detect whether the action had a real effect or was intercepted.
+ */
+/**
+ * Captures AKTree state before and after an action to detect changes.
+ */
+export class ActionVerifier {
+    beforeTree = null;
+    beforeUrl = null;
+    async captureBeforeState(adapter) {
+        try {
+            this.beforeTree = await adapter.getAKTree();
+        }
+        catch {
+            this.beforeTree = null;
+        }
+        try {
+            this.beforeUrl = await adapter.getCurrentUrl();
+        }
+        catch {
+            this.beforeUrl = null;
+        }
+    }
+    async verifyAfterAction(adapter) {
+        if (!this.beforeTree || !this.beforeUrl) {
+            return {
+                hadEffect: true, // assume effect if no before state
+                changes: [],
+                summary: 'no before state captured, assuming action had effect',
+            };
+        }
+        let afterUrl;
+        let afterTree;
+        try {
+            [afterUrl, afterTree] = await Promise.all([
+                adapter.getCurrentUrl(),
+                adapter.getAKTree(),
+            ]);
+        }
+        catch {
+            this.beforeTree = null;
+            this.beforeUrl = null;
+            return {
+                hadEffect: true,
+                changes: [],
+                summary: 'after state unavailable, skipping AKTree effect verification',
+            };
+        }
+        const changes = [];
+        // 1. URL change
+        if (afterUrl !== this.beforeUrl) {
+            changes.push({
+                kind: 'url_changed',
+                detail: `${this.beforeUrl} -> ${afterUrl}`,
+            });
+        }
+        // 2. Overlay changes
+        const beforeOverlayCount = this.beforeTree.overlays.length;
+        const afterOverlayCount = afterTree.overlays.length;
+        if (beforeOverlayCount !== afterOverlayCount) {
+            changes.push({
+                kind: 'overlay_changed',
+                detail: `overlays: ${beforeOverlayCount} -> ${afterOverlayCount}`,
+            });
+        }
+        // 3. Tree structure diff (node count at top level)
+        const beforeNodes = countVisibleNodes(this.beforeTree.root);
+        const afterNodes = countVisibleNodes(afterTree.root);
+        if (Math.abs(beforeNodes - afterNodes) > 2) {
+            changes.push({
+                kind: 'tree_structure_changed',
+                detail: `visible nodes: ${beforeNodes} -> ${afterNodes}`,
+            });
+        }
+        // 4. Check for new visible interactive nodes (e.g., modal appeared)
+        const beforeIds = collectVisibleInteractiveIds(this.beforeTree.root);
+        const afterIds = collectVisibleInteractiveIds(afterTree.root);
+        const appeared = afterIds.filter(id => !beforeIds.includes(id));
+        const disappeared = beforeIds.filter(id => !afterIds.includes(id));
+        if (appeared.length > 0) {
+            changes.push({
+                kind: 'node_appeared',
+                detail: `${appeared.length} new interactive node(s)`,
+            });
+        }
+        if (disappeared.length > 0) {
+            changes.push({
+                kind: 'node_disappeared',
+                detail: `${disappeared.length} interactive node(s) gone`,
+            });
+        }
+        // 5. Check page title change
+        if (this.beforeTree.page.title !== afterTree.page.title) {
+            changes.push({
+                kind: 'tree_structure_changed',
+                detail: `title: "${this.beforeTree.page.title}" -> "${afterTree.page.title}"`,
+            });
+        }
+        // If no changes detected at all
+        if (changes.length === 0) {
+            changes.push({ kind: 'no_change', detail: 'no detectable changes in URL, tree, or overlays' });
+        }
+        const hadEffect = changes.some(c => c.kind !== 'no_change');
+        const summary = changes.map(c => `${c.kind}: ${c.detail}`).join('; ');
+        // Reset state
+        this.beforeTree = null;
+        this.beforeUrl = null;
+        return { hadEffect, changes, summary };
+    }
+}
+// ── Helpers ─────────────────────────────────────────────────────────
+function countVisibleNodes(node) {
+    let count = node.visible ? 1 : 0;
+    for (const child of node.children) {
+        count += countVisibleNodes(child);
+    }
+    return count;
+}
+function collectVisibleInteractiveIds(node) {
+    const ids = [];
+    function walk(n) {
+        if (n.visible && n.interactive) {
+            ids.push(n.id);
+        }
+        n.children.forEach(walk);
+    }
+    walk(node);
+    return ids;
+}
+//# sourceMappingURL=action-verifier.js.map

package/dist/v2/alt-text.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Capture Agent — Alt Text Generation
+ *
+ * Generates accessible alt text for captured screenshots.
+ * Adapts to the variant's locale for localized descriptions.
+ * Cost: ~0.001 EUR per generation.
+ */
+import { type LLMProviderConfig, type LLMCallResult } from './llm-provider.js';
+export interface AltTextResult {
+    altText: string;
+    llmResult?: LLMCallResult;
+}
+export interface AltTextContext {
+    /** What the screenshot captures */
+    description: string;
+    /** Target URL */
+    url: string;
+    /** Locale for the alt text language */
+    locale?: string;
+    /** Page/preset name */
+    presetName?: string;
+}
+/**
+ * Generates alt text for a screenshot, localized to the variant's language.
+ */
+export declare function generateAltText(screenshot: Buffer, context: AltTextContext, llmConfig: LLMProviderConfig): Promise<AltTextResult>;

package/dist/v2/alt-text.js

@@ -0,0 +1,55 @@
+/**
+ * Capture Agent — Alt Text Generation
+ *
+ * Generates accessible alt text for captured screenshots.
+ * Adapts to the variant's locale for localized descriptions.
+ * Cost: ~0.001 EUR per generation.
+ */
+import { callLLM } from './llm-provider.js';
+const SYSTEM_PROMPT = `You generate concise alt text for web page screenshots.
+
+Rules:
+- Maximum 150 characters
+- Describe what is VISIBLE, not what the page is about
+- Use the language specified by the locale
+- Start with the main visual element (e.g., "Dashboard showing 5 projects")
+- Do not wrap in quotes
+- Do not start with "Screenshot of" or "Image of"
+
+Respond with ONLY the alt text, nothing else.`;
+/**
+ * Generates alt text for a screenshot, localized to the variant's language.
+ */
+export async function generateAltText(screenshot, context, llmConfig) {
+    const locale = context.locale ?? 'en';
+    const userPrompt = [
+        `Generate alt text in ${localeToLanguage(locale)} for this screenshot.`,
+        `Page: ${context.presetName ?? context.url}`,
+        `Content: ${context.description}`,
+    ].join('\n');
+    try {
+        const result = await callLLM({ ...llmConfig, maxTokens: 100, timeoutMs: 10000 }, SYSTEM_PROMPT, userPrompt, screenshot);
+        // Clean up: remove quotes, trim
+        let altText = result.text.replace(/^["']|["']$/g, '').trim();
+        if (altText.length > 150)
+            altText = altText.slice(0, 147) + '...';
+        return { altText, llmResult: result };
+    }
+    catch {
+        // Fallback: generate from context without LLM
+        return {
+            altText: `${context.presetName ?? 'Page'} — ${context.description}`.slice(0, 150),
+        };
+    }
+}
+function localeToLanguage(locale) {
+    const map = {
+        en: 'English', fr: 'French', de: 'German', es: 'Spanish',
+        pt: 'Portuguese', it: 'Italian', nl: 'Dutch', ja: 'Japanese',
+        ko: 'Korean', zh: 'Chinese', ar: 'Arabic', ru: 'Russian',
+        pl: 'Polish', sv: 'Swedish', da: 'Danish', fi: 'Finnish',
+        nb: 'Norwegian', tr: 'Turkish', cs: 'Czech', ro: 'Romanian',
+    };
+    return map[locale.split('-')[0]] ?? locale;
+}
+//# sourceMappingURL=alt-text.js.map

package/dist/v2/benchmark.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Capture Agent — Benchmark Harness
+ *
+ * Runs the same preset through V2, comparing:
+ * - Total LLM cost
+ * - Total wall-clock time
+ * - Success rate
+ * - Recovery rate (how often healing was needed)
+ *
+ * Used to prove V2 >= V1 before cutover.
+ */
+import type { ExecutionProgram, RunResult } from './types.js';
+export interface BenchmarkPreset {
+    name: string;
+    presetId: string;
+    program: ExecutionProgram;
+    /** Expected behavior description for manual verification */
+    expectedBehavior: string;
+    /** Difficulty tier */
+    tier: 'simple' | 'multi_step' | 'auth_required' | 'clip' | 'video';
+}
+export interface BenchmarkRunResult {
+    presetName: string;
+    tier: string;
+    success: boolean;
+    totalDurationMs: number;
+    llmCostEur: number;
+    llmCallCount: number;
+    totalOpcodes: number;
+    recoveredOpcodes: number;
+    failedOpcodes: number;
+    healerInvocations: number;
+    circuitBreakerTrips: number;
+    variantCount: number;
+    successfulVariants: number;
+    error?: string;
+}
+export interface BenchmarkSummary {
+    totalPresets: number;
+    successCount: number;
+    failCount: number;
+    successRate: number;
+    averageDurationMs: number;
+    averageLlmCostEur: number;
+    totalLlmCostEur: number;
+    deterministicRate: number;
+    recoveryRate: number;
+    results: BenchmarkRunResult[];
+    byTier: Record<string, {
+        total: number;
+        success: number;
+        rate: number;
+    }>;
+}
+export type RunFn = (program: ExecutionProgram) => Promise<RunResult>;
+export declare function runBenchmark(presets: BenchmarkPreset[], runCapture: RunFn, options?: {
+    runs?: number;
+}): Promise<BenchmarkSummary>;
+export declare function formatBenchmarkSummary(summary: BenchmarkSummary): string;