autokap 1.0.7 → 1.0.8

package/dist/opcode-runner.js

@@ -0,0 +1,770 @@
+/**
+ * Capture Agent — Opcode Runner
+ *
+ * Deterministic execution engine for ExecutionProgram.
+ * Executes opcodes sequentially, verifies postconditions,
+ * delegates to recovery chain on failure, and respects circuit breaker.
+ */
+import { isSoftOpcodeKind } from './execution-types.js';
+import { evaluatePostcondition } from './postcondition.js';
+import { ActionVerifier } from './action-verifier.js';
+import { CircuitBreaker } from './circuit-breaker.js';
+import { smartWaitForStability } from './smart-wait.js';
+import { verifyCaptureQuality } from './capture-verification.js';
+import { generateAltText } from './alt-text.js';
+import { executeOpcodeCoreAction } from './opcode-actions.js';
+import { logger } from './logger.js';
+function formatOpcodeDebug(opcode) {
+    const fields = [];
+    const o = opcode;
+    if (typeof o.selector === 'string')
+        fields.push(`selector="${o.selector}"`);
+    if (typeof o.url === 'string')
+        fields.push(`url="${o.url}"`);
+    if (typeof o.text === 'string')
+        fields.push(`text="${o.text.slice(0, 40)}"`);
+    if (typeof o.stateName === 'string')
+        fields.push(`stateName="${o.stateName}"`);
+    if (typeof o.groupName === 'string')
+        fields.push(`group="${o.groupName}"`);
+    if (opcode.postcondition)
+        fields.push(`post=${opcode.postcondition.type}`);
+    const recovery = opcode.recovery;
+    if (recovery) {
+        const flags = [];
+        if (recovery.retries)
+            flags.push(`retries=${recovery.retries}`);
+        if (recovery.useSelectorMemory)
+            flags.push('selMem');
+        if (recovery.useAltInteraction)
+            flags.push('alt');
+        if (recovery.allowReload)
+            flags.push('reload');
+        if (recovery.allowHealer)
+            flags.push('healer');
+        if (flags.length)
+            fields.push(`recovery=[${flags.join(',')}]`);
+    }
+    return fields.length ? ` (${fields.join(', ')})` : '';
+}
+/** Default recovery chain for consumers that do not inject one. */
+export class NoOpRecoveryChain {
+    async attempt() {
+        return { recovered: false, reason: 'no recovery chain configured' };
+    }
+}
+// ── Main execution function ─────────────────────────────────────────
+export async function executeProgram(program, createAdapter, options = {}) {
+    const recoveryChain = options.recoveryChain ?? new NoOpRecoveryChain();
+    const maxParallelVariants = Math.max(1, Math.floor(options.maxParallelVariants ?? 1));
+    const startTime = Date.now();
+    const variantResults = new Array(program.variants.length);
+    const healerPatches = [];
+    const telemetry = {
+        llmCallCount: 0,
+        llmCostEur: 0,
+        llmStepUsages: [],
+        totalOpcodes: 0,
+        recoveredOpcodes: 0,
+        failedOpcodes: 0,
+        skippedOpcodes: 0,
+        healerInvocations: 0,
+        circuitBreakerTrips: 0,
+    };
+    let nextVariantIndex = 0;
+    const workerCount = Math.min(maxParallelVariants, program.variants.length);
+    const workers = Array.from({ length: workerCount }, async () => {
+        while (!options.abortSignal?.aborted) {
+            const currentIndex = nextVariantIndex++;
+            if (currentIndex >= program.variants.length) {
+                return;
+            }
+            const variant = program.variants[currentIndex];
+            options.onProgress?.({
+                type: 'variant_start',
+                variantId: variant.id,
+                message: `starting variant ${variant.id}`,
+            });
+            const variantResult = await executeVariant(program, variant, createAdapter, recoveryChain, telemetry, healerPatches, options);
+            variantResults[currentIndex] = variantResult;
+            options.onProgress?.({
+                type: 'variant_end',
+                variantId: variant.id,
+                status: variantResult.success ? 'ok' : 'failed',
+                message: variantResult.success
+                    ? `variant ${variant.id} completed`
+                    : `variant ${variant.id} failed: ${variantResult.error}`,
+            });
+        }
+    });
+    await Promise.all(workers);
+    const completedVariantResults = variantResults.filter((result) => Boolean(result));
+    const aborted = options.abortSignal?.aborted && completedVariantResults.length < program.variants.length;
+    const success = !aborted && completedVariantResults.length > 0 && completedVariantResults.every(v => v.success);
+    return {
+        programId: program.presetId,
+        success,
+        variantResults: completedVariantResults,
+        telemetry,
+        healerPatches: success ? healerPatches : [], // Only propagate patches on success
+        totalDurationMs: Date.now() - startTime,
+        error: aborted ? 'aborted' : (success ? undefined : completedVariantResults.find(v => !v.success)?.error),
+    };
+}
+// ── Variant execution ───────────────────────────────────────────────
+async function executeVariant(program, variant, createAdapter, recoveryChain, telemetry, healerPatches, options) {
+    const startTime = Date.now();
+    const breaker = new CircuitBreaker();
+    const verifier = new ActionVerifier();
+    const opcodeResults = [];
+    const artifacts = [];
+    const executionState = {};
+    let adapter = null;
+    try {
+        adapter = await createAdapter(variant);
+        for (let i = 0; i < program.steps.length; i++) {
+            if (options.abortSignal?.aborted) {
+                return {
+                    variantId: variant.id,
+                    success: false,
+                    opcodeResults,
+                    durationMs: Date.now() - startTime,
+                    artifacts,
+                    error: 'aborted',
+                };
+            }
+            // Check circuit breaker before starting
+            const breakerState = breaker.isTripped();
+            if (breakerState.tripped) {
+                telemetry.circuitBreakerTrips++;
+                options.onProgress?.({
+                    type: 'breaker_trip',
+                    variantId: variant.id,
+                    opcodeIndex: i,
+                    message: breakerState.reason,
+                });
+                return {
+                    variantId: variant.id,
+                    success: false,
+                    opcodeResults,
+                    durationMs: Date.now() - startTime,
+                    artifacts,
+                    error: `circuit breaker tripped: ${breakerState.reason}`,
+                };
+            }
+            const opcode = program.steps[i];
+            options.onProgress?.({
+                type: 'opcode_start',
+                variantId: variant.id,
+                opcodeIndex: i,
+                opcodeKind: opcode.kind,
+                message: opcode.description,
+            });
+            const result = await executeOpcode(opcode, i, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, artifacts, options, variant.id, executionState, program.artifactPlan, program.mockDataGroups, variant, program.preconditions.credentials);
+            opcodeResults.push(result);
+            telemetry.totalOpcodes++;
+            if (result.status === 'recovered')
+                telemetry.recoveredOpcodes++;
+            if (result.status === 'failed')
+                telemetry.failedOpcodes++;
+            options.onProgress?.({
+                type: 'opcode_end',
+                variantId: variant.id,
+                opcodeIndex: i,
+                opcodeKind: opcode.kind,
+                status: result.status,
+                message: result.error ?? `${opcode.kind} ${result.status}`,
+            });
+            // Abort variant on fatal opcode failure
+            if (result.status === 'failed') {
+                return {
+                    variantId: variant.id,
+                    success: false,
+                    opcodeResults,
+                    durationMs: Date.now() - startTime,
+                    artifacts,
+                    error: `opcode ${i} (${opcode.kind}) failed: ${result.error}`,
+                };
+            }
+        }
+        return {
+            variantId: variant.id,
+            success: true,
+            opcodeResults,
+            durationMs: Date.now() - startTime,
+            artifacts,
+        };
+    }
+    catch (err) {
+        return {
+            variantId: variant.id,
+            success: false,
+            opcodeResults,
+            durationMs: Date.now() - startTime,
+            artifacts,
+            error: `unexpected error: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    finally {
+        if (adapter) {
+            try {
+                await adapter.close();
+            }
+            catch { /* ignore close errors */ }
+        }
+    }
+}
+// ── Single opcode execution ─────────────────────────────────────────
+/**
+ * Mark a soft opcode as skipped without aborting the variant.
+ * Increments telemetry and (for INJECT_MOCK_DATA) records the group result.
+ * Circuit breaker is intentionally not ticked.
+ */
+function softSkipResult(opcode, index, startTime, reason, telemetry) {
+    telemetry.skippedOpcodes++;
+    if (opcode.kind === 'INJECT_MOCK_DATA') {
+        if (!telemetry.mockDataGroupResults)
+            telemetry.mockDataGroupResults = {};
+        telemetry.mockDataGroupResults[opcode.groupName] = 'skipped';
+    }
+    return {
+        opcodeIndex: index,
+        kind: opcode.kind,
+        status: 'skipped',
+        durationMs: Date.now() - startTime,
+        recoveryAttempts: 0,
+        error: reason,
+    };
+}
+async function executeOpcode(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, artifacts, options, variantId, executionState, artifactPlan, mockDataGroups, currentVariant, credentials) {
+    const startTime = Date.now();
+    const deadlineMs = startTime + opcode.timeoutMs;
+    const isInteraction = ['CLICK', 'TYPE', 'PRESS_KEY', 'SCROLL'].includes(opcode.kind);
+    const isSoft = isSoftOpcodeKind(opcode.kind);
+    // Track page context for circuit breaker
+    try {
+        const url = await adapter.getCurrentUrl();
+        breaker.setPage(url);
+    }
+    catch { /* ignore */ }
+    // Execute with timeout
+    try {
+        logger.debug(`[opcode ${index}] ${opcode.kind} start — budget ${opcode.timeoutMs}ms${formatOpcodeDebug(opcode)}`);
+        if (isInteraction) {
+            const beforeStart = Date.now();
+            await verifier.captureBeforeState(adapter);
+            logger.debug(`[opcode ${index}] captureBeforeState took ${Date.now() - beforeStart}ms`);
+        }
+        const actionBudgetMs = getRemainingTimeMs(deadlineMs);
+        if (actionBudgetMs <= 0) {
+            const reason = `timeout after ${opcode.timeoutMs}ms`;
+            logger.debug(`[opcode ${index}] no budget left after captureBeforeState (deadline=${deadlineMs}, now=${Date.now()})`);
+            if (isSoft)
+                return softSkipResult(opcode, index, startTime, reason, telemetry);
+            return handleFailure(opcode, index, adapter, verifier, isInteraction, breaker, recoveryChain, telemetry, healerPatches, options, variantId, currentVariant, startTime, deadlineMs, reason);
+        }
+        logger.debug(`[opcode ${index}] action exec start — actionBudget ${actionBudgetMs}ms`);
+        const actionStart = Date.now();
+        const result = await withTimeout(() => executeOpcodeAction(opcode, index, adapter, artifacts, telemetry, currentVariant, executionState, artifactPlan, mockDataGroups, options, credentials), actionBudgetMs);
+        logger.debug(`[opcode ${index}] action exec end — took ${Date.now() - actionStart}ms, success=${result.success}${result.error ? `, error=${result.error}` : ''}`);
+        if (!result.success) {
+            const reason = result.error ?? 'action failed';
+            if (isSoft)
+                return softSkipResult(opcode, index, startTime, reason, telemetry);
+            return handleFailure(opcode, index, adapter, verifier, isInteraction, breaker, recoveryChain, telemetry, healerPatches, options, variantId, currentVariant, startTime, deadlineMs, reason);
+        }
+        // Verify postcondition
+        const postconditionBudgetMs = getRemainingTimeMs(deadlineMs);
+        if (postconditionBudgetMs <= 0) {
+            const reason = `timeout after ${opcode.timeoutMs}ms`;
+            logger.debug(`[opcode ${index}] no budget left for postcondition check`);
+            if (isSoft)
+                return softSkipResult(opcode, index, startTime, reason, telemetry);
+            return handleFailure(opcode, index, adapter, verifier, isInteraction, breaker, recoveryChain, telemetry, healerPatches, options, variantId, currentVariant, startTime, deadlineMs, reason);
+        }
+        const postStart = Date.now();
+        const postcondition = await evaluatePostcondition(adapter, withClampedPostconditionTimeout(opcode.postcondition, postconditionBudgetMs));
+        logger.debug(`[opcode ${index}] postcondition (${opcode.postcondition.type}) took ${Date.now() - postStart}ms — passed=${postcondition.passed}, reason="${postcondition.reason}"`);
+        if (!postcondition.passed) {
+            const reason = `postcondition failed: ${postcondition.reason}`;
+            if (isSoft)
+                return softSkipResult(opcode, index, startTime, reason, telemetry);
+            return handleFailure(opcode, index, adapter, verifier, isInteraction, breaker, recoveryChain, telemetry, healerPatches, options, variantId, currentVariant, startTime, deadlineMs, reason);
+        }
+        // Verify action had effect (for interaction opcodes)
+        if (isInteraction) {
+            const verification = await verifier.verifyAfterAction(adapter);
+            if (!verification.hadEffect && opcode.postcondition.type !== 'always' && opcode.postcondition.type !== 'any_change') {
+                return handleFailure(opcode, index, adapter, verifier, isInteraction, breaker, recoveryChain, telemetry, healerPatches, options, variantId, currentVariant, startTime, deadlineMs, `action had no effect: ${verification.summary}`);
+            }
+        }
+        // Record successful mock data application
+        if (opcode.kind === 'INJECT_MOCK_DATA') {
+            if (!telemetry.mockDataGroupResults)
+                telemetry.mockDataGroupResults = {};
+            telemetry.mockDataGroupResults[opcode.groupName] = 'applied';
+        }
+        breaker.recordSuccess(index);
+        return {
+            opcodeIndex: index,
+            kind: opcode.kind,
+            status: 'ok',
+            durationMs: Date.now() - startTime,
+            recoveryAttempts: 0,
+        };
+    }
+    catch (err) {
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        if (isSoft)
+            return softSkipResult(opcode, index, startTime, errorMsg, telemetry);
+        return handleFailure(opcode, index, adapter, verifier, isInteraction, breaker, recoveryChain, telemetry, healerPatches, options, variantId, currentVariant, startTime, deadlineMs, errorMsg);
+    }
+}
+// ── Failure handling with recovery ──────────────────────────────────
+async function handleFailure(opcode, index, adapter, verifier, isInteraction, breaker, recoveryChain, telemetry, healerPatches, options, variantId, currentVariant, startTime, deadlineMs, errorMsg) {
+    const breakerState = breaker.recordFailure(index, opcode.maxFailures);
+    if (breakerState.tripped) {
+        telemetry.circuitBreakerTrips++;
+        return {
+            opcodeIndex: index,
+            kind: opcode.kind,
+            status: 'failed',
+            durationMs: Date.now() - startTime,
+            recoveryAttempts: 0,
+            error: `${errorMsg} (circuit breaker: ${breakerState.reason})`,
+        };
+    }
+    const remainingTimeMs = getRemainingTimeMs(deadlineMs);
+    if (remainingTimeMs <= 0) {
+        return {
+            opcodeIndex: index,
+            kind: opcode.kind,
+            status: 'failed',
+            durationMs: Date.now() - startTime,
+            recoveryAttempts: 0,
+            error: `${errorMsg} (timeout after ${opcode.timeoutMs}ms)`,
+        };
+    }
+    // Attempt recovery
+    options.onProgress?.({
+        type: 'recovery',
+        variantId,
+        opcodeIndex: index,
+        opcodeKind: opcode.kind,
+        message: `recovering from: ${errorMsg}`,
+    });
+    const recovery = await recoveryChain.attempt(opcode, index, adapter, {
+        remainingTimeMs,
+        maxDeterministicRetries: Math.max(0, opcode.maxFailures - breakerState.opcodeFailures),
+        currentVariant,
+    });
+    if (recovery.llmResult) {
+        telemetry.llmCallCount++;
+        telemetry.llmCostEur += recovery.llmResult.costEur;
+        telemetry.llmStepUsages.push({
+            stepType: 'healer_invocation',
+            generationId: recovery.llmResult.generationId,
+            model: recovery.llmResult.model,
+            promptTokens: recovery.llmResult.promptTokens,
+            completionTokens: recovery.llmResult.completionTokens,
+        });
+        telemetry.healerInvocations++;
+    }
+    if (recovery.recovered) {
+        if (recovery.patch) {
+            healerPatches.push(recovery.patch);
+        }
+        if (isInteraction) {
+            const verification = await verifier.verifyAfterAction(adapter);
+            if (!verification.hadEffect && opcode.postcondition.type !== 'always' && opcode.postcondition.type !== 'any_change') {
+                return {
+                    opcodeIndex: index,
+                    kind: opcode.kind,
+                    status: 'failed',
+                    durationMs: Date.now() - startTime,
+                    recoveryAttempts: 1,
+                    error: `${errorMsg} (recovery succeeded but action still had no effect: ${verification.summary})`,
+                };
+            }
+        }
+        breaker.recordSuccess(index);
+        return {
+            opcodeIndex: index,
+            kind: opcode.kind,
+            status: 'recovered',
+            durationMs: Date.now() - startTime,
+            recoveryAttempts: 1,
+            recoveryStrategy: recovery.strategy,
+        };
+    }
+    return {
+        opcodeIndex: index,
+        kind: opcode.kind,
+        status: 'failed',
+        durationMs: Date.now() - startTime,
+        recoveryAttempts: 1,
+        error: `${errorMsg} (recovery failed: ${recovery.reason})`,
+    };
+}
+// ── Opcode action dispatch ──────────────────────────────────────────
+async function executeOpcodeAction(opcode, opcodeIndex, adapter, artifacts, telemetry, currentVariant, executionState, artifactPlan, mockDataGroups, runOptions, credentials) {
+    try {
+        void artifactPlan;
+        switch (opcode.kind) {
+            case 'NAVIGATE':
+            case 'DISMISS_OVERLAYS':
+            case 'CLICK':
+            case 'TYPE':
+            case 'PRESS_KEY':
+            case 'WAIT_FOR':
+            case 'SET_LOCALE':
+            case 'SET_THEME':
+            case 'SCROLL':
+            case 'HOVER':
+            case 'SELECT_OPTION':
+            case 'CHECK':
+            case 'DOUBLE_CLICK':
+            case 'CLONE_ELEMENT':
+            case 'INJECT_MOCK_DATA':
+            case 'REMOVE_ELEMENT':
+            case 'SET_ATTRIBUTE':
+                return executeOpcodeCoreAction(opcode, adapter, { currentVariant, mockDataGroups, credentials });
+            case 'ASSERT_ROUTE':
+                return evaluateImmediateAssertion(await evaluatePostcondition(adapter, {
+                    type: 'route_matches',
+                    pattern: opcode.urlPattern,
+                    waitMs: 1,
+                }), 'ASSERT_ROUTE failed');
+            case 'ASSERT_SURFACE':
+                return evaluateSurfaceAssertion(adapter, opcode.selectors, opcode.matchAll);
+            case 'CAPTURE_SCREENSHOT': {
+                await smartWaitForStability(adapter, { maxWaitMs: 5000 });
+                const captureUrl = await adapter.getCurrentUrl();
+                const takeBuffer = async () => {
+                    if (opcode.elementSelector && adapter.takeElementScreenshot) {
+                        return adapter.takeElementScreenshot(opcode.elementSelector);
+                    }
+                    if (opcode.elementSelector) {
+                        throw new Error(`element capture requires adapter support for selector "${opcode.elementSelector}"`);
+                    }
+                    return adapter.takeScreenshot();
+                };
+                let buffer = await takeBuffer();
+                if (runOptions?.llmConfig) {
+                    const verification = await verifyCaptureQuality(buffer, {
+                        expectedDescription: opcode.description,
+                        url: captureUrl,
+                        locale: currentVariant?.locale,
+                        theme: currentVariant?.theme,
+                    }, runOptions.llmConfig);
+                    if (verification.llmResult) {
+                        telemetry.llmCallCount++;
+                        telemetry.llmCostEur += verification.llmResult.costEur;
+                        telemetry.llmStepUsages.push({
+                            stepType: 'capture_verification',
+                            generationId: verification.llmResult.generationId,
+                            model: verification.llmResult.model,
+                            promptTokens: verification.llmResult.promptTokens,
+                            completionTokens: verification.llmResult.completionTokens,
+                        });
+                    }
+                    if (!verification.passed) {
+                        await smartWaitForStability(adapter, { maxWaitMs: 8000 });
+                        const retryBuffer = await takeBuffer();
+                        const retryVerification = await verifyCaptureQuality(retryBuffer, {
+                            expectedDescription: opcode.description,
+                            url: captureUrl,
+                            locale: currentVariant?.locale,
+                            theme: currentVariant?.theme,
+                        }, runOptions.llmConfig);
+                        if (retryVerification.llmResult) {
+                            telemetry.llmCallCount++;
+                            telemetry.llmCostEur += retryVerification.llmResult.costEur;
+                            telemetry.llmStepUsages.push({
+                                stepType: 'capture_verification',
+                                generationId: retryVerification.llmResult.generationId,
+                                model: retryVerification.llmResult.model,
+                                promptTokens: retryVerification.llmResult.promptTokens,
+                                completionTokens: retryVerification.llmResult.completionTokens,
+                            });
+                        }
+                        if (retryVerification.passed) {
+                            buffer = retryBuffer;
+                        }
+                    }
+                }
+                let altText;
+                if (runOptions?.llmConfig) {
+                    try {
+                        const altResult = await generateAltText(buffer, {
+                            description: opcode.description,
+                            url: captureUrl,
+                            locale: currentVariant?.locale,
+                            presetName: runOptions.presetName,
+                        }, runOptions.llmConfig);
+                        altText = altResult.altText;
+                        if (altResult.llmResult) {
+                            telemetry.llmCallCount++;
+                            telemetry.llmCostEur += altResult.llmResult.costEur;
+                            telemetry.llmStepUsages.push({
+                                stepType: 'alt_text_generation',
+                                generationId: altResult.llmResult.generationId,
+                                model: altResult.llmResult.model,
+                                promptTokens: altResult.llmResult.promptTokens,
+                                completionTokens: altResult.llmResult.completionTokens,
+                            });
+                        }
+                    }
+                    catch {
+                        // Alt text generation failed — non-fatal
+                    }
+                }
+                // Extract page favicon for browser bar mockup
+                let tabIconData;
+                let tabIconMimeType;
+                if (adapter.extractFavicon) {
+                    const favicon = await adapter.extractFavicon();
+                    if (favicon) {
+                        tabIconData = favicon.buffer;
+                        tabIconMimeType = favicon.mimeType;
+                    }
+                }
+                artifacts.push({
+                    mediaMode: 'screenshot',
+                    buffer,
+                    mimeType: 'image/png',
+                    captureType: opcode.elementSelector ? 'element' : 'fullpage',
+                    captureUrl,
+                    dimensions: currentVariant?.viewport,
+                    captureId: opcode.captureId,
+                    captureName: opcode.captureName ?? opcode.description,
+                    elementSelector: opcode.elementSelector,
+                    altText,
+                    stepDescription: opcode.description,
+                    stepIndex: opcodeIndex,
+                    variantId: currentVariant?.id,
+                    tabIconData,
+                    tabIconMimeType,
+                });
+                break;
+            }
+            case 'BEGIN_CLIP':
+                if (executionState.activeClip) {
+                    return { success: false, error: 'cannot start a new clip before the previous one ends' };
+                }
+                executionState.activeClip = {
+                    clipId: opcode.clipId,
+                    clipName: opcode.clipName,
+                };
+                await adapter.beginRecording({ mediaMode: 'clip' });
+                break;
+            case 'END_CLIP': {
+                const clipIdentity = resolveClipIdentity(executionState.activeClip, opcode);
+                const recording = await adapter.endRecording();
+                executionState.activeClip = undefined;
+                artifacts.push({
+                    mediaMode: 'clip',
+                    buffer: recording.buffer,
+                    mimeType: recording.mimeType,
+                    durationMs: recording.durationMs,
+                    trimStartMs: recording.trimStartMs,
+                    dimensions: undefined,
+                    captureType: 'fullpage',
+                    captureUrl: await adapter.getCurrentUrl(),
+                    clipId: clipIdentity.clipId,
+                    clipName: clipIdentity.clipName,
+                    stepDescription: opcode.description,
+                    stepIndex: opcodeIndex,
+                    variantId: currentVariant?.id,
+                });
+                break;
+            }
+            case 'CAPTURE_DOM': {
+                if (opcode.selector) {
+                    const attached = await adapter.waitFor({
+                        selector: opcode.selector,
+                        state: 'attached',
+                        timeoutMs: 5000,
+                    });
+                    if (!attached) {
+                        return {
+                            success: false,
+                            error: `CAPTURE_DOM could not find selector "${opcode.selector}" in the DOM`,
+                        };
+                    }
+                }
+                await smartWaitForStability(adapter, { maxWaitMs: 5000 });
+                if (!adapter.serializeDom) {
+                    return {
+                        success: false,
+                        error: 'CAPTURE_DOM requires an adapter that implements serializeDom() — Interactive Demos pipeline (AUT-121)',
+                    };
+                }
+                const captureUrl = await adapter.getCurrentUrl();
+                const serialized = await adapter.serializeDom(opcode.selector);
+                const buffer = Buffer.from(serialized.html, 'utf8');
+                // Take a viewport screenshot for the thumbnail
+                const thumbnailBuffer = await adapter.takeScreenshot();
+                artifacts.push({
+                    mediaMode: 'dom',
+                    buffer,
+                    mimeType: 'text/html; charset=utf-8',
+                    captureType: opcode.selector ? 'element' : 'fullpage',
+                    captureUrl,
+                    dimensions: serialized.viewport,
+                    captureId: opcode.stateName,
+                    captureName: opcode.stateName,
+                    stepDescription: opcode.description,
+                    stepIndex: opcodeIndex,
+                    variantId: currentVariant?.id,
+                    elementSelector: opcode.selector,
+                    stateName: opcode.stateName,
+                    domHtml: serialized.html,
+                    domAssetUrls: serialized.assetUrls,
+                    domHtmlBytes: buffer.byteLength,
+                    domThumbnailBuffer: thumbnailBuffer,
+                });
+                break;
+            }
+            case 'CAPTURE_FRAGMENT': {
+                if (!adapter.serializeFragment) {
+                    return {
+                        success: false,
+                        error: 'CAPTURE_FRAGMENT requires an adapter that implements serializeFragment() — Interactive Demos Phase 5',
+                    };
+                }
+                // Optional hidden trigger button (mirrors the mock data trigger
+                // pattern). Useful for fragments that aren't reachable via
+                // visible UI. The trigger is clicked via clickHidden() so it
+                // bypasses visibility/disabled checks.
+                if (opcode.triggerSelector) {
+                    if (!adapter.clickHidden) {
+                        return {
+                            success: false,
+                            error: `CAPTURE_FRAGMENT.triggerSelector requires adapter.clickHidden() support`,
+                        };
+                    }
+                    try {
+                        await adapter.clickHidden({ selector: opcode.triggerSelector });
+                    }
+                    catch (err) {
+                        return {
+                            success: false,
+                            error: `CAPTURE_FRAGMENT trigger click failed: ${err instanceof Error ? err.message : String(err)}`,
+                        };
+                    }
+                }
+                // Wait for the fragment selector to be present in the DOM (the
+                // trigger may have inserted it dynamically). Mirror the screenshot
+                // smart-wait so animations / portal mounts settle before serialization.
+                const visible = await adapter.waitFor({
+                    selector: opcode.selector,
+                    state: 'attached',
+                    timeoutMs: 5000,
+                });
+                if (!visible) {
+                    return {
+                        success: false,
+                        error: `CAPTURE_FRAGMENT could not find selector "${opcode.selector}" in the DOM`,
+                    };
+                }
+                await smartWaitForStability(adapter, { maxWaitMs: 3000 });
+                const captureUrl = await adapter.getCurrentUrl();
+                const serialized = await adapter.serializeFragment(opcode.selector);
+                const buffer = Buffer.from(serialized.html, 'utf8');
+                const variantName = opcode.variantName ?? 'default';
+                artifacts.push({
+                    mediaMode: 'dom',
+                    buffer,
+                    mimeType: 'text/html; charset=utf-8',
+                    captureType: 'element',
+                    captureUrl,
+                    // captureId is the unique upload key — including the variant
+                    // ensures multiple variants of the same fragment do not collide.
+                    captureId: `${opcode.parentState}/${opcode.fragmentName}/${variantName}`,
+                    captureName: opcode.fragmentName,
+                    elementSelector: opcode.selector,
+                    stepDescription: opcode.description,
+                    stepIndex: opcodeIndex,
+                    variantId: currentVariant?.id,
+                    fragmentName: opcode.fragmentName,
+                    fragmentVariantName: variantName,
+                    parentStateName: opcode.parentState,
+                    mountStrategy: opcode.mountStrategy ?? 'inline',
+                    mountTargetSelector: opcode.mountTargetSelector,
+                    domHtml: serialized.html,
+                    domAssetUrls: serialized.assetUrls,
+                    domHtmlBytes: buffer.byteLength,
+                });
+                break;
+            }
+            default: {
+                const _exhaustive = opcode;
+                return { success: false, error: `unknown opcode kind: ${opcode.kind}` };
+            }
+        }
+        return { success: true };
+    }
+    catch (err) {
+        return {
+            success: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+// ── Helpers ─────────────────────────────────────────────────────────
+async function withTimeout(fn, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`timeout after ${timeoutMs}ms`)), timeoutMs);
+        fn()
+            .then(result => { clearTimeout(timer); resolve(result); })
+            .catch(err => { clearTimeout(timer); reject(err); });
+    });
+}
+function getRemainingTimeMs(deadlineMs) {
+    return Math.max(0, deadlineMs - Date.now());
+}
+function resolveClipIdentity(activeClip, opcode) {
+    if (activeClip?.clipId && opcode.clipId && activeClip.clipId !== opcode.clipId) {
+        throw new Error(`END_CLIP clipId "${opcode.clipId}" does not match active clip "${activeClip.clipId}"`);
+    }
+    return {
+        clipId: opcode.clipId ?? activeClip?.clipId,
+        clipName: opcode.clipName ?? activeClip?.clipName ?? opcode.description,
+    };
+}
+function withClampedPostconditionTimeout(spec, maxWaitMs) {
+    return {
+        ...spec,
+        waitMs: Math.max(1, Math.min(spec.waitMs ?? maxWaitMs, maxWaitMs)),
+    };
+}
+function evaluateImmediateAssertion(result, prefix) {
+    return result.passed
+        ? { success: true }
+        : { success: false, error: `${prefix}: ${result.reason}` };
+}
+async function evaluateSurfaceAssertion(adapter, selectors, matchAll) {
+    const checks = await Promise.all(selectors.map(async (selector) => ({
+        selector,
+        result: await evaluatePostcondition(adapter, {
+            type: 'element_visible',
+            selector,
+            waitMs: 1,
+        }),
+    })));
+    if (matchAll) {
+        const failed = checks.find((entry) => !entry.result.passed);
+        return failed
+            ? { success: false, error: `ASSERT_SURFACE failed for "${failed.selector}": ${failed.result.reason}` }
+            : { success: true };
+    }
+    if (checks.some((entry) => entry.result.passed)) {
+        return { success: true };
+    }
+    return {
+        success: false,
+        error: `ASSERT_SURFACE failed: none of the selectors matched (${selectors.join(', ')})`,
+    };
+}
+//# sourceMappingURL=opcode-runner.js.map