autokap 1.5.4 → 1.5.7

package/dist/opcode-runner.js

@@ -65,6 +65,39 @@ function resolveRecordingCaptureResolution(artifactPlan) {
     }
     return artifactPlan.format?.captureResolution;
 }
+const ACTION_EFFECT_OPCODE_KINDS = new Set([
+    'CLICK',
+    'TYPE',
+    'PRESS_KEY',
+    'SCROLL',
+    'HOVER',
+    'SELECT_OPTION',
+    'CHECK',
+    'DOUBLE_CLICK',
+    'DRAG',
+]);
+function getOpcodeActionEffectPolicy(opcode) {
+    const captureBefore = ACTION_EFFECT_OPCODE_KINDS.has(opcode.kind);
+    if (!captureBefore) {
+        return { captureBefore: false, requireEffect: false, noEffectMode: 'allow' };
+    }
+    if (opcode.postcondition.type === 'any_change') {
+        return { captureBefore: true, requireEffect: true, noEffectMode: 'fail' };
+    }
+    if (opcode.postcondition.type === 'always') {
+        return { captureBefore: true, requireEffect: false, noEffectMode: 'allow' };
+    }
+    if (opcode.kind === 'PRESS_KEY') {
+        return { captureBefore: true, requireEffect: false, noEffectMode: 'allow' };
+    }
+    return { captureBefore: true, requireEffect: true, noEffectMode: 'fail' };
+}
+function resolveRuntimePostcondition(opcode) {
+    if (opcode.kind === 'ASSERT_ROUTE' || opcode.kind === 'ASSERT_SURFACE') {
+        return { type: 'always' };
+    }
+    return opcode.postcondition;
+}
 // ── Main execution function ─────────────────────────────────────────
 export async function executeProgram(program, createAdapter, options = {}) {
     const recoveryChain = options.recoveryChain ?? new NoOpRecoveryChain();
@@ -254,7 +287,7 @@ async function executeOpcode(opcode, index, adapter, verifier, breaker, recovery
     const startTime = Date.now();
     const effectiveTimeoutMs = resolveOpcodeTimeoutMs(opcode);
     const deadlineMs = startTime + effectiveTimeoutMs;
-    const isInteraction = ['CLICK', 'TYPE', 'PRESS_KEY', 'SCROLL'].includes(opcode.kind);
+    const actionEffectPolicy = getOpcodeActionEffectPolicy(opcode);
     const isSoft = isSoftOpcodeKind(opcode.kind);
     // Track page context for circuit breaker
     try {
@@ -265,7 +298,7 @@ async function executeOpcode(opcode, index, adapter, verifier, breaker, recovery
     // Execute with timeout
     try {
         logger.debug(`[opcode ${index}] ${opcode.kind} start — budget ${effectiveTimeoutMs}ms${formatOpcodeDebug(opcode)}`);
-        if (isInteraction) {
+        if (actionEffectPolicy.captureBefore) {
             const beforeStart = Date.now();
             await verifier.captureBeforeState(adapter);
             logger.debug(`[opcode ${index}] captureBeforeState took ${Date.now() - beforeStart}ms`);
@@ -276,7 +309,7 @@ async function executeOpcode(opcode, index, adapter, verifier, breaker, recovery
             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, executionState, variantId, currentVariant, startTime, deadlineMs, effectiveTimeoutMs, reason);
+            return handleFailure(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, effectiveTimeoutMs, reason);
         }
         // For mediaMode='video', capture pre-action timing + bbox metadata inside
         // the active clip window only. Opcodes outside a clip are not part of the
@@ -310,7 +343,7 @@ async function executeOpcode(opcode, index, adapter, verifier, breaker, recovery
             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, executionState, variantId, currentVariant, startTime, deadlineMs, effectiveTimeoutMs, reason);
+            return handleFailure(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, effectiveTimeoutMs, reason);
         }
         // Verify postcondition
         const postconditionBudgetMs = getRemainingTimeMs(deadlineMs);
@@ -319,39 +352,30 @@ async function executeOpcode(opcode, index, adapter, verifier, breaker, recovery
             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, executionState, variantId, currentVariant, startTime, deadlineMs, effectiveTimeoutMs, reason);
+            return handleFailure(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, effectiveTimeoutMs, reason);
         }
+        const runtimePostcondition = resolveRuntimePostcondition(opcode);
         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}"`);
+        const postcondition = await evaluatePostcondition(adapter, withClampedPostconditionTimeout(runtimePostcondition, postconditionBudgetMs));
+        logger.debug(`[opcode ${index}] postcondition (${runtimePostcondition.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, executionState, variantId, currentVariant, startTime, deadlineMs, effectiveTimeoutMs, reason);
+            return handleFailure(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, effectiveTimeoutMs, reason);
         }
-        // Verify action had effect (for interaction opcodes). The verifier
-        // catches silent failures: e.g. CLICK on a stale selector that found
-        // nothing and the page-state-passing postcondition is coincidentally
-        // satisfied by an unrelated state. For most interactions, no DOM
-        // change after the action means the action didn't really happen.
-        //
-        // PRESS_KEY is the exception. Keys are CONDITIONAL by nature: Escape
-        // is a no-op when no modal is open; Enter is a no-op when no form is
-        // focused; Tab is a no-op when no focusable target exists. A preset
-        // may legitimately script PRESS_KEY against a page that has already
-        // reached the target state via earlier opcodes (e.g. SLEEP let an
-        // auto-close timer run). The postcondition has already passed by this
-        // point — trust it for PRESS_KEY and skip the no-effect penalty.
-        if (isInteraction) {
+        // Verify action effects through the shared policy. Weak `any_change`
+        // postconditions are only meaningful if this verifier observes a real
+        // URL/tree/state/scroll change.
+        if (actionEffectPolicy.captureBefore) {
             const verification = await verifier.verifyAfterAction(adapter);
-            if (!verification.hadEffect && opcode.postcondition.type !== 'always' && opcode.postcondition.type !== 'any_change') {
-                if (opcode.kind === 'PRESS_KEY') {
+            if (!verification.hadEffect && actionEffectPolicy.requireEffect) {
+                if (opcode.kind === 'PRESS_KEY' && actionEffectPolicy.noEffectMode === 'allow') {
                     logger.debug(`[opcode ${index}] PRESS_KEY had no DOM effect (${verification.summary}) — ` +
                         `postcondition passed, treating as redundant-but-successful`);
                 }
                 else {
-                    return handleFailure(opcode, index, adapter, verifier, isInteraction, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, effectiveTimeoutMs, `action had no effect: ${verification.summary}`);
+                    return handleFailure(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, effectiveTimeoutMs, `action had no effect: ${verification.summary}`);
                 }
             }
         }
@@ -385,7 +409,7 @@ async function executeOpcode(opcode, index, adapter, verifier, breaker, recovery
         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, executionState, variantId, currentVariant, startTime, deadlineMs, effectiveTimeoutMs, errorMsg);
+        return handleFailure(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, effectiveTimeoutMs, errorMsg);
     }
 }
 /** Post-action breathing room (ms) injected between visible interactions
@@ -411,7 +435,8 @@ function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
 // ── Failure handling with recovery ──────────────────────────────────
-async function handleFailure(opcode, index, adapter, verifier, isInteraction, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, effectiveTimeoutMs, errorMsg) {
+async function handleFailure(opcode, index, adapter, verifier, breaker, recoveryChain, telemetry, healerPatches, options, executionState, variantId, currentVariant, startTime, deadlineMs, effectiveTimeoutMs, errorMsg) {
+    const actionEffectPolicy = getOpcodeActionEffectPolicy(opcode);
     const breakerState = breaker.recordFailure(index, opcode.maxFailures);
     if (breakerState.tripped) {
         telemetry.circuitBreakerTrips++;
@@ -443,6 +468,11 @@ async function handleFailure(opcode, index, adapter, verifier, isInteraction, br
         opcodeKind: opcode.kind,
         message: `recovering from: ${errorMsg}`,
     });
+    if (actionEffectPolicy.captureBefore) {
+        const beforeRecoveryStart = Date.now();
+        await verifier.captureBeforeState(adapter);
+        logger.debug(`[opcode ${index}] recovery captureBeforeState took ${Date.now() - beforeRecoveryStart}ms`);
+    }
     const recovery = await recoveryChain.attempt(opcode, index, adapter, {
         remainingTimeMs,
         maxDeterministicRetries: Math.max(0, opcode.maxFailures - breakerState.opcodeFailures),
@@ -466,9 +496,32 @@ async function handleFailure(opcode, index, adapter, verifier, isInteraction, br
         if (recovery.patch) {
             healerPatches.push(recovery.patch);
         }
-        if (isInteraction) {
+        const postconditionBudgetMs = getRemainingTimeMs(deadlineMs);
+        if (postconditionBudgetMs <= 0) {
+            return {
+                opcodeIndex: index,
+                kind: opcode.kind,
+                status: 'failed',
+                durationMs: Date.now() - startTime,
+                recoveryAttempts: 1,
+                error: `${errorMsg} (recovery succeeded but postcondition could not be rechecked before timeout after ${effectiveTimeoutMs}ms)`,
+            };
+        }
+        const runtimePostcondition = resolveRuntimePostcondition(opcode);
+        const postcondition = await evaluatePostcondition(adapter, withClampedPostconditionTimeout(runtimePostcondition, postconditionBudgetMs));
+        if (!postcondition.passed) {
+            return {
+                opcodeIndex: index,
+                kind: opcode.kind,
+                status: 'failed',
+                durationMs: Date.now() - startTime,
+                recoveryAttempts: 1,
+                error: `${errorMsg} (recovery succeeded but postcondition still failed: ${postcondition.reason})`,
+            };
+        }
+        if (actionEffectPolicy.captureBefore) {
             const verification = await verifier.verifyAfterAction(adapter);
-            if (!verification.hadEffect && opcode.postcondition.type !== 'always' && opcode.postcondition.type !== 'any_change') {
+            if (!verification.hadEffect && actionEffectPolicy.requireEffect) {
                 return {
                     opcodeIndex: index,
                     kind: opcode.kind,
@@ -533,19 +586,27 @@ async function executeOpcodeAction(opcode, opcodeIndex, adapter, artifacts, tele
                     suppressPageReloads: Boolean(executionState.activeClip),
                 });
             case 'ASSERT_ROUTE':
+                assertRoutePostconditionSource(opcode);
                 return evaluateImmediateAssertion(await evaluatePostcondition(adapter, {
                     type: 'route_matches',
                     pattern: opcode.urlPattern,
                     waitMs: 1,
                 }), 'ASSERT_ROUTE failed');
             case 'ASSERT_SURFACE':
+                assertSurfacePostconditionSource(opcode);
                 return evaluateSurfaceAssertion(adapter, opcode.selectors, opcode.matchAll);
             case 'CAPTURE_SCREENSHOT': {
-                await smartWaitForStability(adapter, { maxWaitMs: 5000 });
+                const stability = await smartWaitForStability(adapter, { maxWaitMs: 5000 });
+                if (!stability.stable) {
+                    return {
+                        success: false,
+                        error: `page not stable before screenshot; unresolved loaders: ${stability.waitedFor.join(', ') || 'unknown'}`,
+                    };
+                }
                 const captureUrl = await adapter.getCurrentUrl();
                 const takeBuffer = async () => {
                     if (opcode.elementSelector && adapter.takeElementScreenshot) {
-                        return adapter.takeElementScreenshot(opcode.elementSelector);
+                        return adapter.takeElementScreenshot(opcode.elementSelector, opcode.outscale);
                     }
                     if (opcode.elementSelector) {
                         throw new Error(`element capture requires adapter support for selector "${opcode.elementSelector}"`);
@@ -760,13 +821,37 @@ function getZoomTargetSelector(opcode) {
     }
 }
 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); });
+    const operation = Promise.resolve().then(fn);
+    let timedOut = false;
+    let timer = null;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            timedOut = true;
+            reject(new Error(`timeout after ${timeoutMs}ms`));
+        }, timeoutMs);
     });
+    try {
+        return await Promise.race([operation, timeout]);
+    }
+    catch (err) {
+        if (!timedOut)
+            throw err;
+        // Playwright actions cannot be cancelled through the current adapter API.
+        // Before recovery starts, give the in-flight action a short chance to
+        // settle so it does not mutate the page concurrently with recovery or the
+        // next opcode. This is deadline-safe without changing adapter contracts.
+        await Promise.race([
+            operation.catch(() => undefined),
+            sleep(TIMED_OUT_ACTION_DRAIN_MS),
+        ]);
+        throw err;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
 }
+const TIMED_OUT_ACTION_DRAIN_MS = 2000;
 function getRemainingTimeMs(deadlineMs) {
     return Math.max(0, deadlineMs - Date.now());
 }
@@ -790,6 +875,22 @@ function evaluateImmediateAssertion(result, prefix) {
         ? { success: true }
         : { success: false, error: `${prefix}: ${result.reason}` };
 }
+function assertRoutePostconditionSource(opcode) {
+    const post = opcode.postcondition;
+    if (post.type === 'always')
+        return;
+    if (post.type === 'route_matches' && post.pattern === opcode.urlPattern)
+        return;
+    throw new Error(`ASSERT_ROUTE uses urlPattern as the source of truth; postcondition must be always or route_matches with the same pattern "${opcode.urlPattern}"`);
+}
+function assertSurfacePostconditionSource(opcode) {
+    const post = opcode.postcondition;
+    if (post.type === 'always')
+        return;
+    if (post.type === 'element_visible' && post.selector && opcode.selectors.includes(post.selector))
+        return;
+    throw new Error('ASSERT_SURFACE uses selectors/matchAll as the source of truth; postcondition must be always or element_visible for one of the asserted selectors');
+}
 async function evaluateSurfaceAssertion(adapter, selectors, matchAll) {
     const checks = await Promise.all(selectors.map(async (selector) => ({
         selector,

package/dist/overlay-engine.js

@@ -149,10 +149,16 @@ function findNodeById(node, id) {
     return null;
 }
 function buildSelectorFromSourceRef(sourceRef) {
-    // Extract data-testid
-    const testIdMatch = sourceRef.match(/data-testid="([^"]+)"/);
-    if (testIdMatch)
-        return `[data-testid="${testIdMatch[1]}"]`;
+    const trimmed = sourceRef.trim();
+    if (isSelectorLikeSourceRef(trimmed)) {
+        return trimmed;
+    }
+    // Extract AutoKap/test automation attributes
+    for (const attr of ['data-ak', 'data-ak-interact', 'data-testid', 'data-test', 'data-qa', 'data-cy']) {
+        const attrMatch = sourceRef.match(new RegExp(`${attr}="([^"]+)"`));
+        if (attrMatch)
+            return `[${attr}="${attrMatch[1].replace(/"/g, '\\"')}"]`;
+    }
     // Extract id
     const idMatch = sourceRef.match(/ id="([^"]+)"/);
     if (idMatch)
@@ -170,6 +176,14 @@ function buildSelectorFromSourceRef(sourceRef) {
     }
     return null;
 }
+function isSelectorLikeSourceRef(sourceRef) {
+    if (!sourceRef || sourceRef.startsWith('<'))
+        return false;
+    return sourceRef.startsWith('#')
+        || sourceRef.startsWith('.')
+        || sourceRef.startsWith('[')
+        || /^[a-z][a-z0-9-]*(?:[#.[\s>:]|$)/i.test(sourceRef);
+}
 function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }

package/dist/postcondition.js

@@ -14,12 +14,13 @@ export async function evaluatePostcondition(adapter, spec) {
     const maxWait = spec.waitMs ?? 5000;
     const pollInterval = 500;
     const deadline = Date.now() + maxWait;
+    const context = {};
     // 'always' postcondition always passes immediately
     if (spec.type === 'always') {
         return { passed: true, reason: 'always passes' };
     }
     while (Date.now() < deadline) {
-        const result = await checkOnce(adapter, spec);
+        const result = await checkOnce(adapter, spec, context);
         if (result.passed)
             return result;
         const remaining = deadline - Date.now();
@@ -28,9 +29,9 @@ export async function evaluatePostcondition(adapter, spec) {
         await sleep(Math.min(pollInterval, remaining));
     }
     // Final check after timeout
-    return checkOnce(adapter, spec);
+    return checkOnce(adapter, spec, context);
 }
-async function checkOnce(adapter, spec) {
+async function checkOnce(adapter, spec, context) {
     switch (spec.type) {
         case 'route_matches':
             return checkRouteMatches(adapter, spec.pattern);
@@ -43,11 +44,11 @@ async function checkOnce(adapter, spec) {
         case 'overlay_dismissed':
             return checkOverlayDismissed(adapter);
         case 'screenshot_stable':
-            return checkScreenshotStable(adapter, spec.threshold ?? 0.01);
+            return checkScreenshotStable(adapter, spec.threshold ?? 0.01, context);
         case 'any_change':
-            // 'any_change' is a soft postcondition — we just assume the action did something.
-            // The action-verifier handles real change detection via AKTree diff.
-            return { passed: true, reason: 'any_change always passes (action verifier handles real detection)' };
+            // The runner makes this verifier-backed by requiring a detected action
+            // effect after this structural postcondition succeeds.
+            return { passed: true, reason: 'any_change deferred to action verifier' };
         case 'always':
             return { passed: true, reason: 'always passes' };
         default:
@@ -152,8 +153,13 @@ async function checkTextContains(adapter, selector, expectedText) {
         if (!node) {
             return { passed: false, reason: `element "${selector}" not found for text check` };
         }
-        const nodeText = (node.label || '') + (node.value || '');
-        if (nodeText.includes(expectedText)) {
+        const nodeText = normalizeText([
+            node.label || '',
+            node.value || '',
+            node.attributes.__ownText || '',
+        ].join(' '));
+        const expected = normalizeText(expectedText);
+        if (nodeText.includes(expected)) {
             return { passed: true, reason: `element "${selector}" contains "${expectedText}"` };
         }
         return { passed: false, reason: `element "${selector}" text "${nodeText}" does not contain "${expectedText}"` };
@@ -182,33 +188,29 @@ async function checkOverlayDismissed(adapter) {
         return { passed: true, reason: 'overlay check skipped (AKTree unavailable), assuming dismissed' };
     }
 }
-let lastScreenshotHash = null;
-async function checkScreenshotStable(adapter, threshold) {
+async function checkScreenshotStable(adapter, threshold, context) {
     try {
         const screenshot = await adapter.takeScreenshot();
-        const currentHash = simpleHash(screenshot);
-        if (lastScreenshotHash === null) {
-            lastScreenshotHash = currentHash;
-            // Wait and take another screenshot
-            await sleep(500);
+        if (!context.lastScreenshot) {
+            context.lastScreenshot = screenshot;
+            await sleep(250);
             const screenshot2 = await adapter.takeScreenshot();
-            const hash2 = simpleHash(screenshot2);
-            lastScreenshotHash = null;
-            if (currentHash === hash2) {
-                return { passed: true, reason: 'consecutive screenshots are identical' };
+            const diff = sampledBufferDiffRatio(screenshot, screenshot2);
+            context.lastScreenshot = screenshot2;
+            if (diff <= threshold) {
+                return { passed: true, reason: `consecutive screenshots stable (diff=${diff.toFixed(4)})` };
             }
-            return { passed: false, reason: 'consecutive screenshots differ (page still changing)' };
+            return { passed: false, reason: `consecutive screenshots differ (diff=${diff.toFixed(4)})` };
         }
-        // Compare with previous
-        if (currentHash === lastScreenshotHash) {
-            lastScreenshotHash = null;
-            return { passed: true, reason: 'screenshot matches previous' };
+        const diff = sampledBufferDiffRatio(context.lastScreenshot, screenshot);
+        context.lastScreenshot = screenshot;
+        if (diff <= threshold) {
+            return { passed: true, reason: `screenshot stable (diff=${diff.toFixed(4)})` };
         }
-        lastScreenshotHash = currentHash;
-        return { passed: false, reason: 'screenshot changed from previous check' };
+        return { passed: false, reason: `screenshot changed from previous check (diff=${diff.toFixed(4)})` };
     }
     catch (err) {
-        lastScreenshotHash = null;
+        context.lastScreenshot = undefined;
         return { passed: false, reason: `error checking screenshot stability: ${err}` };
     }
 }
@@ -216,7 +218,7 @@ async function checkScreenshotStable(adapter, threshold) {
 function hasVisibleNodeWithSelector(tree, selector) {
     // Walk the AKTree looking for a visible node whose sourceRef matches the selector
     function walk(node) {
-        if (node.visible && node.sourceRef && matchesSelectorHeuristic(node.sourceRef, selector)) {
+        if (node.visible && matchesNodeSelectorHeuristic(node, selector)) {
             return true;
         }
         return node.children.some(walk);
@@ -225,7 +227,7 @@ function hasVisibleNodeWithSelector(tree, selector) {
 }
 function findNodeBySelector(tree, selector) {
     function walk(node) {
-        if (node.sourceRef && matchesSelectorHeuristic(node.sourceRef, selector)) {
+        if (matchesNodeSelectorHeuristic(node, selector)) {
             return node;
         }
         for (const child of node.children) {
@@ -237,6 +239,20 @@ function findNodeBySelector(tree, selector) {
     }
     return walk(tree.root);
 }
+function matchesNodeSelectorHeuristic(node, selector) {
+    if (node.sourceRef && matchesSelectorHeuristic(node.sourceRef, selector)) {
+        return true;
+    }
+    const attrMatch = selector.match(/\[([a-z0-9_-]+)=["'](.+?)["']\]/i);
+    if (attrMatch) {
+        const [, attr, rawValue] = attrMatch;
+        return (node.attributes[attr] ?? '').toLowerCase() === rawValue.toLowerCase();
+    }
+    if (selector.startsWith('#')) {
+        return (node.attributes.id ?? '').toLowerCase() === selector.slice(1).toLowerCase();
+    }
+    return false;
+}
 /**
  * Heuristic match between an AKTree sourceRef and a CSS-like selector.
  * Not a full CSS selector engine — handles common patterns:
@@ -248,10 +264,18 @@ function findNodeBySelector(tree, selector) {
 function matchesSelectorHeuristic(sourceRef, selector) {
     const lower = sourceRef.toLowerCase();
     const selectorLower = selector.toLowerCase();
-    // data-testid match
-    const testIdMatch = selector.match(/\[data-testid=["'](.+?)["']\]/);
-    if (testIdMatch) {
-        return lower.includes(`data-testid="${testIdMatch[1]}"`);
+    if (selectorLower === lower) {
+        return true;
+    }
+    // Generic attribute selector match, including AutoKap's canonical data-ak
+    // selectors and legacy test-id selectors.
+    const attrMatch = selector.match(/\[([a-z0-9_-]+)=["'](.+?)["']\]/i);
+    if (attrMatch) {
+        const [, attr, rawValue] = attrMatch;
+        const value = rawValue.toLowerCase();
+        return lower === `[${attr.toLowerCase()}="${value}"]`
+            || lower.includes(`[${attr.toLowerCase()}="${value}"]`)
+            || lower.includes(`${attr.toLowerCase()}="${value}"`);
     }
     // ID match
     if (selector.startsWith('#')) {
@@ -264,14 +288,23 @@ function matchesSelectorHeuristic(sourceRef, selector) {
     // Fallback: contains
     return lower.includes(selectorLower);
 }
-function simpleHash(buffer) {
-    // Fast non-crypto hash for screenshot comparison
-    let hash = 0;
-    const step = Math.max(1, Math.floor(buffer.length / 10000));
-    for (let i = 0; i < buffer.length; i += step) {
-        hash = ((hash << 5) - hash + buffer[i]) | 0;
+function sampledBufferDiffRatio(a, b) {
+    const maxLength = Math.max(a.length, b.length);
+    if (maxLength === 0)
+        return 0;
+    const sampleCount = Math.min(10000, maxLength);
+    const step = Math.max(1, Math.floor(maxLength / sampleCount));
+    let checked = 0;
+    let changed = 0;
+    for (let i = 0; i < maxLength; i += step) {
+        checked++;
+        if (a[i] !== b[i])
+            changed++;
     }
-    return hash.toString(36);
+    return checked === 0 ? 0 : changed / checked;
+}
+function normalizeText(value) {
+    return value.replace(/\s+/g, ' ').trim();
 }
 function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));

package/dist/program-signing.d.ts

@@ -608,6 +608,16 @@ export declare const SignedExecutionProgramEnvelopeSchema: z.ZodObject<{
             captureId: z.ZodOptional<z.ZodString>;
             captureName: z.ZodOptional<z.ZodString>;
             elementSelector: z.ZodOptional<z.ZodString>;
+            outscale: z.ZodOptional<z.ZodObject<{
+                padding: z.ZodOptional<z.ZodNumber>;
+                paddingTop: z.ZodOptional<z.ZodNumber>;
+                paddingRight: z.ZodOptional<z.ZodNumber>;
+                paddingBottom: z.ZodOptional<z.ZodNumber>;
+                paddingLeft: z.ZodOptional<z.ZodNumber>;
+                paddingPercent: z.ZodOptional<z.ZodNumber>;
+                clampToViewport: z.ZodOptional<z.ZodBoolean>;
+                backgroundColor: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
             description: z.ZodString;
             postcondition: z.ZodObject<{
                 type: z.ZodEnum<{

package/dist/recovery-chain.js

@@ -12,7 +12,7 @@ import { resolveSelector } from './selector-resolver.js';
 import { evaluatePostcondition } from './postcondition.js';
 import { LLMHealer } from './llm-healer.js';
 import { serializeAKTree } from './ak-tree.js';
-import { executeOpcodeCoreAction, substituteCredentialPlaceholders } from './opcode-actions.js';
+import { executeOpcodeCoreAction } from './opcode-actions.js';
 import { dismissAllOverlays } from './overlay-engine.js';
 import { logger } from './logger.js';
 export class RecoveryChainImpl {
@@ -43,7 +43,7 @@ export class RecoveryChainImpl {
         // Strategy 2: Selector memory + alternate selectors
         if (recovery.useSelectorMemory && hasSelector(failedOpcode)) {
             logger.debug(`[recovery ${opcodeIndex}] strategy 2 (selector memory)`);
-            const result = await trySelectorAlternatives(failedOpcode, opcodeIndex, adapter, this.selectorMemory, this.credentials);
+            const result = await trySelectorAlternatives(failedOpcode, opcodeIndex, adapter, this.selectorMemory, this.credentials, options.currentVariant);
             logger.debug(`[recovery ${opcodeIndex}] strategy 2 → recovered=${result.recovered}, reason=${result.reason}`);
             if (result.recovered)
                 return result;
@@ -109,7 +109,7 @@ async function retryOpcode(opcode, adapter, maxRetries, remainingTimeMs, current
     return { recovered: false, reason: `${maxRetries} retries exhausted` };
 }
 // ── Strategy 2: Selector memory ─────────────────────────────────────
-async function trySelectorAlternatives(opcode, opcodeIndex, adapter, selectorMemory, credentials) {
+async function trySelectorAlternatives(opcode, opcodeIndex, adapter, selectorMemory, credentials, currentVariant) {
     if (!hasSelector(opcode)) {
         return { recovered: false, reason: 'opcode has no selector' };
     }
@@ -129,7 +129,7 @@ async function trySelectorAlternatives(opcode, opcodeIndex, adapter, selectorMem
     }
     // Try the resolved selector
     try {
-        await executeWithSelector(opcode, adapter, resolved.selector, credentials);
+        await executeWithSelector(opcode, adapter, resolved.selector, credentials, currentVariant);
         const postcondition = await evaluatePostcondition(adapter, opcode.postcondition);
         if (postcondition.passed) {
             return {
@@ -312,40 +312,25 @@ async function executeHealerPatchedAction(opcode, adapter, interactionMode, curr
     }
     await executeRawAction(opcode, adapter, currentVariant, credentials, suppressPageReloads);
 }
-async function executeWithSelector(opcode, adapter, newSelector, credentials) {
+async function executeWithSelector(opcode, adapter, newSelector, credentials, currentVariant) {
+    const opcodeWithSelector = cloneOpcodeWithSelector(opcode, newSelector);
+    const result = await executeOpcodeCoreAction(opcodeWithSelector, adapter, {
+        credentials,
+        currentVariant,
+    });
+    if (!result.success) {
+        throw new Error(result.error ?? `selector recovery failed for ${opcode.kind}`);
+    }
+}
+function cloneOpcodeWithSelector(opcode, newSelector) {
     switch (opcode.kind) {
         case 'CLICK':
-            await adapter.click(newSelector, opcode.button ? { button: opcode.button } : undefined);
-            break;
-        case 'TYPE': {
-            const text = substituteCredentialPlaceholders(opcode.text, credentials);
-            await adapter.type(newSelector, text, opcode.clearFirst);
-            break;
-        }
+        case 'TYPE':
         case 'HOVER':
-            if (!adapter.hover)
-                throw new Error('adapter does not support HOVER');
-            await adapter.hover(newSelector);
-            break;
         case 'SELECT_OPTION':
-            if (!adapter.selectOption)
-                throw new Error('adapter does not support SELECT_OPTION');
-            await adapter.selectOption(newSelector, {
-                label: opcode.optionLabel,
-                value: opcode.optionValue,
-                index: opcode.optionIndex,
-            });
-            break;
         case 'CHECK':
-            if (!adapter.check)
-                throw new Error('adapter does not support CHECK');
-            await adapter.check(newSelector, opcode.checked);
-            break;
         case 'DOUBLE_CLICK':
-            if (!adapter.doubleClick)
-                throw new Error('adapter does not support DOUBLE_CLICK');
-            await adapter.doubleClick(newSelector);
-            break;
+            return { ...opcode, selector: newSelector };
         default:
             throw new Error(`cannot swap selector for opcode kind: ${opcode.kind}`);
     }