autokap 1.5.5 → 1.6.0

package/assets/skill/OPCODE-REFERENCE.md

@@ -47,6 +47,8 @@ Fallback when CSS selector fails. The runtime resolves via Playwright semantic l
 | `threshold` | number (0-1) | `screenshot_stable` | Pixel diff tolerance. Default: `0.01` |
 | `waitMs` | number | all except `always` | Max polling time (ms). Default: `5000` |
 
+`any_change` is verifier-backed: the runtime must observe a URL, DOM, element state, overlay, or scroll change after the action. No-op actions fail.
+
 ---
 
 ## NAVIGATE
@@ -353,6 +355,8 @@ Assert the current URL matches a pattern. Pure validation, no navigation.
 **Can:** Validate the browser is on the expected page. Useful as a checkpoint before capture.
 **Cannot:** Navigate or change the URL. Use NAVIGATE for that.
 
+`urlPattern` is the assertion source of truth. Use `postcondition: { "type": "always" }` or repeat the same `route_matches` pattern.
+
 ```json
 { "kind": "ASSERT_ROUTE", "urlPattern": "/dashboard/**", "postcondition": { "type": "route_matches", "pattern": "/dashboard/**" } }
 ```
@@ -369,6 +373,8 @@ Assert that specific elements are visible on the page. Pure validation.
 **Can:** Validate page state before capture. Confirm multiple elements are rendered.
 **Cannot:** Interact with elements or wait for them. Use WAIT_FOR for dynamic elements.
 
+`selectors` and `matchAll` are the assertion source of truth. Use `postcondition: { "type": "always" }` or an `element_visible` postcondition for one of the asserted selectors.
+
 ```json
 { "kind": "ASSERT_SURFACE", "selectors": ["[data-ak=\"header\"]", "[data-ak=\"sidebar\"]"], "matchAll": true, "postcondition": { "type": "always" } }
 ```

package/assets/skill/SKILL.md

@@ -150,7 +150,7 @@ interface VariantSpec {
 | `DISMISS_OVERLAYS` | no | — | `overlay_dismissed` | Always after NAVIGATE |
 | `CLICK` | yes | `button?` | `element_visible` / `route_matches` | Postcondition = what CHANGED |
 | `TYPE` | yes | `text`, `clearFirst` | `any_change` | `{{email}}` / `{{password}}` for creds |
-| `PRESS_KEY` | no | `key` | `any_change` | `"Enter"`, `"Escape"`, `"Tab"`, etc. |
+| `PRESS_KEY` | no | `key` | specific result / `any_change` | `"Enter"`, `"Escape"`, `"Tab"`, etc.; use `any_change` only when the key must visibly change state |
 | `WAIT_FOR` | yes* | `state` | `element_visible` | `"visible"` or `"attached"` (DOM only) |
 | `SLEEP` | no | `durationMs` (1..60000), `narrationTextByLocale?` | `always` | Pause N ms. Reserved for video narration anchors. Use `durationMs: 1` as a placeholder; AutoKap rewrites it during `autokap run` after generating TTS. |
 | `SCROLL` | no | `direction`, `targetSelector?`, `amount?` | `element_visible` | Use `targetSelector` for precise scroll |
@@ -161,8 +161,8 @@ interface VariantSpec {
 | `DRAG` | yes | `toSelector?` / `toTarget?` / `offset?` | `element_visible` / `any_change` | Animated cursor A→B. Use `toSelector` for Kanban-style drops, `offset` for sliders / canvas |
 | `SET_LOCALE` | no | `locale`, `method`, `storageHints?` | `always` | Use `"$variant"`. Prefer `method: "storage"` |
 | `SET_THEME` | no | `theme`, `method`, `storageHints?` | `always` | Use `"$variant"`. Prefer `method: "storage"` |
-| `ASSERT_ROUTE` | no | `urlPattern` | `route_matches` | Validation checkpoint |
-| `ASSERT_SURFACE` | no | `selectors[]`, `matchAll` | `always` | Validation checkpoint |
+| `ASSERT_ROUTE` | no | `urlPattern` | `always` / matching `route_matches` | `urlPattern` is the source of truth |
+| `ASSERT_SURFACE` | no | `selectors[]`, `matchAll` | `always` / matching `element_visible` | `selectors` + `matchAll` are the source of truth |
 | `CAPTURE_SCREENSHOT` | no | `captureId`, `captureName`, `elementSelector?`, `outscale?` | `always` | `elementSelector` for element-level crop. `outscale` adds padding around the element (user-edited post-generation; omit by default) |
 | `BEGIN_CLIP` | no | `clipId`, `clipName` | `always` | Start recording |
 | `END_CLIP` | no | `clipId`, `clipName` | `always` | Stop recording. Same `clipId` as BEGIN_CLIP |
@@ -183,7 +183,7 @@ interface VariantSpec {
 | `text_contains` | `selector`, `text` | After TYPE, SELECT_OPTION |
 | `overlay_dismissed` | — | After DISMISS_OVERLAYS |
 | `screenshot_stable` | `threshold?` (0-1), `waitMs?` | Before CAPTURE_SCREENSHOT when page has animations |
-| `any_change` | — | After TYPE, PRESS_KEY, DOUBLE_CLICK (soft check) |
+| `any_change` | — | Verifier-backed state change after TYPE, CLICK, SELECT_OPTION, DOUBLE_CLICK, DRAG, etc.; no-op actions fail |
 | `always` | — | CAPTURE_SCREENSHOT, SET_LOCALE, SET_THEME, CHECK, BEGIN/END_CLIP |
 
 ## What Presets Can and Cannot Do

package/dist/action-verifier.d.ts

@@ -13,7 +13,7 @@ export interface ActionVerification {
     /** Summary for logging */
     summary: string;
 }
-export type ActionChangeKind = 'url_changed' | 'tree_structure_changed' | 'node_appeared' | 'node_disappeared' | 'overlay_changed' | 'no_change';
+export type ActionChangeKind = 'url_changed' | 'tree_structure_changed' | 'node_appeared' | 'node_disappeared' | 'node_state_changed' | 'scroll_changed' | 'overlay_changed' | 'no_change';
 export interface ActionChange {
     kind: ActionChangeKind;
     detail: string;

package/dist/action-verifier.js

@@ -99,6 +99,38 @@ export class ActionVerifier {
                 detail: `title: "${this.beforeTree.page.title}" -> "${afterTree.page.title}"`,
             });
         }
+        // 6. Check focused/value/selection/text state on stable nodes. This is
+        // what makes `any_change` meaningful for TYPE, CHECK, SELECT_OPTION and
+        // tab-like controls that update state without changing the DOM shape.
+        const beforeState = collectVisibleNodeState(this.beforeTree.root);
+        const afterState = collectVisibleNodeState(afterTree.root);
+        const changedStates = [];
+        for (const [key, before] of beforeState) {
+            const after = afterState.get(key);
+            if (!after)
+                continue;
+            if (before !== after) {
+                changedStates.push(key);
+                if (changedStates.length >= 5)
+                    break;
+            }
+        }
+        if (changedStates.length > 0) {
+            changes.push({
+                kind: 'node_state_changed',
+                detail: `${changedStates.length} visible node state change(s)`,
+            });
+        }
+        // 7. Check document or nested scroll movement. SCROLL often changes only
+        // scroll offsets; without this, a valid scroll can look like a no-op.
+        const beforeScroll = collectScrollState(this.beforeTree);
+        const afterScroll = collectScrollState(afterTree);
+        if (beforeScroll !== afterScroll) {
+            changes.push({
+                kind: 'scroll_changed',
+                detail: `${beforeScroll} -> ${afterScroll}`,
+            });
+        }
         // If no changes detected at all
         if (changes.length === 0) {
             changes.push({ kind: 'no_change', detail: 'no detectable changes in URL, tree, or overlays' });
@@ -130,4 +162,40 @@ function collectVisibleInteractiveIds(node) {
     walk(node);
     return ids;
 }
+function collectVisibleNodeState(root) {
+    const states = new Map();
+    function keyFor(node) {
+        return node.sourceRef || node.id;
+    }
+    function walk(node) {
+        if (node.visible) {
+            states.set(keyFor(node), JSON.stringify({
+                label: node.label,
+                value: node.value ?? '',
+                disabled: node.state.disabled,
+                focused: node.state.focused,
+                checked: node.state.checked ?? null,
+                expanded: node.state.expanded ?? null,
+                selected: node.state.selected ?? null,
+                ownText: node.attributes.__ownText ?? '',
+            }));
+        }
+        node.children.forEach(walk);
+    }
+    walk(root);
+    return states;
+}
+function collectScrollState(tree) {
+    const parts = [
+        `page:${tree.page.scroll.scrollTop},${tree.page.scroll.scrollLeft}`,
+    ];
+    function walk(node) {
+        if (node.scroll) {
+            parts.push(`${node.sourceRef || node.id}:${node.scroll.scrollTop},${node.scroll.scrollLeft}`);
+        }
+        node.children.forEach(walk);
+    }
+    walk(tree.root);
+    return parts.join('|');
+}
 //# sourceMappingURL=action-verifier.js.map

package/dist/browser.d.ts

@@ -14,6 +14,8 @@ export interface StableSelectorSnapshot {
     ariaLabel?: string | null;
     title?: string | null;
     placeholder?: string | null;
+    dataAk?: string | null;
+    dataAkInteract?: string | null;
     dataTestId?: string | null;
     dataTest?: string | null;
     dataQa?: string | null;

package/dist/browser.js

@@ -746,6 +746,8 @@ export function buildStableCssSelectorCandidates(snapshot) {
         push(`#${escapeCssIdentifier(snapshot.id)}`);
     }
     for (const [attr, value] of [
+        ['data-ak', snapshot.dataAk],
+        ['data-ak-interact', snapshot.dataAkInteract],
         ['data-testid', snapshot.dataTestId],
         ['data-test', snapshot.dataTest],
         ['data-qa', snapshot.dataQa],
@@ -1740,7 +1742,7 @@ export class Browser {
                 if (id) {
                     push(`#${CSS.escape(id)}`);
                 }
-                for (const attr of ['data-testid', 'data-test', 'data-qa', 'data-cy']) {
+                for (const attr of ['data-ak', 'data-ak-interact', 'data-testid', 'data-test', 'data-qa', 'data-cy']) {
                     const value = node.getAttribute(attr);
                     if (!value)
                         continue;
@@ -1922,7 +1924,7 @@ export class Browser {
         try {
             return await page.evaluate(() => {
                 const SKIP_TAGS = new Set(['STYLE', 'SCRIPT', 'SVG', 'NOSCRIPT', 'LINK', 'META', 'BR', 'HR', 'IFRAME', 'CANVAS', 'VIDEO', 'AUDIO', 'SOURCE', 'PICTURE', 'TEMPLATE']);
-                const KEEP_ATTRS = new Set(['id', 'role', 'aria-label', 'aria-expanded', 'aria-haspopup', 'aria-controls', 'aria-selected', 'aria-checked', 'aria-disabled', 'href', 'type', 'name', 'placeholder', 'alt', 'title', 'value', 'for', 'action', 'method', 'data-testid']);
+                const KEEP_ATTRS = new Set(['id', 'role', 'aria-label', 'aria-expanded', 'aria-haspopup', 'aria-controls', 'aria-selected', 'aria-checked', 'aria-disabled', 'href', 'type', 'name', 'placeholder', 'alt', 'title', 'value', 'for', 'action', 'method', 'data-ak', 'data-ak-interact', 'data-ak-fill-input', 'data-ak-fill-trigger', 'data-testid']);
                 const MAX_CHARS = 4000;
                 let output = '';
                 let stopped = false;
@@ -2335,7 +2337,7 @@ export class Browser {
         const snapshot = await page.evaluate(() => {
             const SKIP_TAGS = new Set(['STYLE', 'SCRIPT', 'LINK', 'META', 'NOSCRIPT', 'SOURCE', 'PATH', 'G', 'DEFS', 'CLIPPATH']);
             const SEMANTIC_TAGS = new Set(['NAV', 'MAIN', 'HEADER', 'FOOTER', 'SECTION', 'ARTICLE', 'ASIDE', 'FORM']);
-            const TEST_ID_ATTRS = ['data-testid', 'data-test', 'data-qa', 'data-cy'];
+            const TEST_ID_ATTRS = ['data-ak', 'data-ak-interact', 'data-testid', 'data-test', 'data-qa', 'data-cy'];
             const quoteForSelector = (value) => value
                 .replace(/\\/g, '\\\\')
                 .replace(/"/g, '\\"');
@@ -2537,7 +2539,8 @@ export class Browser {
                 const attrs = {};
                 const copyAttrs = [
                     'id', 'name', 'type', 'href', 'placeholder', 'title', 'role', 'aria-label',
-                    'aria-controls', 'aria-expanded', 'aria-haspopup', 'aria-modal', 'data-testid',
+                    'aria-controls', 'aria-expanded', 'aria-haspopup', 'aria-modal', 'data-ak',
+                    'data-ak-interact', 'data-ak-fill-input', 'data-ak-fill-trigger', 'data-testid',
                     'data-test', 'data-qa', 'data-cy', 'alt',
                 ];
                 for (const attr of copyAttrs) {
@@ -2983,7 +2986,7 @@ export class Browser {
                 const id = node.getAttribute('id');
                 if (id)
                     return `#${CSS.escape(id)}`;
-                for (const attr of ['data-testid', 'data-test', 'data-qa', 'data-cy']) {
+                for (const attr of ['data-ak', 'data-ak-interact', 'data-testid', 'data-test', 'data-qa', 'data-cy']) {
                     const value = node.getAttribute(attr);
                     if (value)
                         return `[${attr}="${quoteForSelector(value)}"]`;
@@ -4588,7 +4591,7 @@ export class Browser {
                 if (id) {
                     push(`#${CSS.escape(id)}`);
                 }
-                for (const attr of ['data-testid', 'data-test', 'data-qa', 'data-cy']) {
+                for (const attr of ['data-ak', 'data-ak-interact', 'data-testid', 'data-test', 'data-qa', 'data-cy']) {
                     const value = node.getAttribute(attr);
                     if (!value)
                         continue;

package/dist/cli-contract.d.ts

@@ -17,6 +17,7 @@ export declare function buildCliRunCommand(presetId: string, options?: {
     local?: boolean;
     env?: string;
     dry?: boolean;
+    regenerateTts?: boolean;
 }): string;
 export declare function buildCliInstalledSetupCommand(cliKey: string): string;
 export declare const CLI_PUBLIC_COMMANDS: CliPublicCommandDescriptor[];

package/dist/cli-contract.js

@@ -12,6 +12,7 @@ export function buildCliRunCommand(presetId, options = {}) {
         options.local ? " --local" : "",
         options.env ? ` --env ${options.env}` : "",
         options.dry ? " --dry" : "",
+        options.regenerateTts ? " --regenerate-tts" : "",
     ].join("");
     return `autokap run${flags} ${presetId}`;
 }

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

@@ -12,4 +12,5 @@ export declare function runLocal(presetId: string, opts: {
     env?: string;
     allowUploadFailure?: boolean;
     dry?: boolean;
+    regenerateTts?: boolean;
 }): Promise<void>;

package/dist/cli-runner-local.js

@@ -31,6 +31,7 @@ export async function runLocal(presetId, opts) {
         program,
         allowUploadFailure: opts.allowUploadFailure,
         dryRun: opts.dry,
+        regenerateTts: opts.regenerateTts,
         headed: opts.headed,
         onProgress: (event) => {
             const prefix = `[capture][${event.variantId}]`;

package/dist/cli-runner.d.ts

@@ -31,6 +31,12 @@ export interface CLIRunnerOptions {
     allowUploadFailure?: boolean;
     /** Dry run: skip capture opcodes (CAPTURE_SCREENSHOT/BEGIN_CLIP/END_CLIP) and upload. 0 credits charged. */
     dryRun?: boolean;
+    /**
+     * Force fresh TTS synthesis for every narration segment instead of reusing
+     * cached audio. Only meaningful when `mediaMode === 'video'`. Every reused
+     * segment becomes billable at full rate.
+     */
+    regenerateTts?: boolean;
     /** Selector memory map (fetched from server or cached locally) */
     selectorMemory?: Record<string, string[]>;
     /** Show browser window. Default: false (headless) */

package/dist/cli-runner.js

@@ -176,7 +176,7 @@ export async function runCapture(options) {
         return { success: false, runId, error: error instanceof Error ? error.message : String(error) };
     }
     if (!options.program && program.mediaMode === 'video') {
-        const prepareResult = await prepareVideoSpeechForRun(config, options.presetId, runId);
+        const prepareResult = await prepareVideoSpeechForRun(config, options.presetId, runId, options.regenerateTts ?? false);
         if (!prepareResult.success) {
             return { success: false, runId, error: prepareResult.error };
         }
@@ -396,7 +396,10 @@ async function fetchProgram(config, presetId, environmentName) {
     }
     return { success: false, error: 'failed to fetch program: retry attempts exhausted' };
 }
-async function prepareVideoSpeechForRun(config, videoId, runId) {
+async function prepareVideoSpeechForRun(config, videoId, runId, regenerateTts) {
+    if (regenerateTts) {
+        logger.info('[capture] Forcing TTS regeneration — all cached segments will be re-synthesized and billed.');
+    }
     logger.info('[capture] Generating speech, may take a few seconds...');
     const url = `${config.apiBaseUrl}/api/cli/video-prepare`;
     let response;
@@ -408,7 +411,7 @@ async function prepareVideoSpeechForRun(config, videoId, runId) {
                 'Content-Type': 'application/json',
                 [CLI_VERSION_HEADER]: APP_VERSION,
             },
-            body: JSON.stringify({ videoId, runId }),
+            body: JSON.stringify(regenerateTts ? { videoId, runId, regenerateTts: true } : { videoId, runId }),
         });
     }
     catch (err) {

package/dist/cli.js

@@ -240,17 +240,60 @@ program
     }
     process.exit(0);
 });
+async function runOutdatedPresetsLocally(opts) {
+    if (opts.output) {
+        fatal('`--output` is not supported with `--outdated`; run an individual preset when local copies are needed.');
+    }
+    const config = await requireConfig();
+    const search = new URLSearchParams({ freshness: 'outdated' });
+    const data = await requestJson(config, `/api/cli/projects/${opts.project}/auto-recapture-presets`, { headers: authHeaders(config) }, 'Failed to list outdated presets', search);
+    if (data.presets.length === 0) {
+        logger.info(`[capture] No outdated presets found for project ${opts.project}`);
+        process.exit(0);
+    }
+    const { runCapture } = await import('./cli-runner.js');
+    const failures = [];
+    logger.info(`[capture] Running ${data.presets.length} outdated preset(s)`);
+    for (const preset of data.presets) {
+        const label = preset.name ? `${preset.name} (${preset.id})` : preset.id;
+        logger.info(`[capture] Running outdated preset ${label}`);
+        const result = await runCapture({
+            presetId: preset.id,
+            env: opts.env,
+            headed: opts.headed,
+            allowUploadFailure: opts.allowUploadFailure,
+            dryRun: opts.dry,
+            regenerateTts: opts.regenerateTts,
+        });
+        if (!result.success) {
+            failures.push({
+                id: preset.id,
+                name: preset.name,
+                error: result.error ?? result.runResult?.error ?? 'capture failed',
+            });
+        }
+    }
+    if (failures.length > 0) {
+        logger.error(`[capture] ${failures.length}/${data.presets.length} outdated preset(s) failed: ${failures.map((failure) => failure.name ?? failure.id).join(', ')}`);
+        process.exit(1);
+    }
+    logger.success(`[capture] ${data.presets.length} outdated preset(s) captured successfully`);
+    process.exit(0);
+}
 // ── run command (deterministic capture engine) ───────────────────────
 program
-    .command('run <preset-id>')
+    .command('run [preset-id]')
     .description('Run a capture using the deterministic opcode engine (local Playwright)')
     .option('--headed', 'Show browser window for debugging', false)
     .option('--local', `Use the local AutoKap dev server (${LOCAL_API_BASE_URL})`, false)
+    .option('--project <id>', 'Project ID. Required with --outdated.')
+    .option('--outdated', 'Run all outdated presets in the project', false)
     .option('--env <name>', "Project environment to capture against. Falls back to the project's default environment when omitted.")
     .option('--allow-upload-failure', 'Keep a successful capture exit code even if artifact upload fails', false)
     .option('--output <dir>', 'Optional output directory for local artifact copies')
     .option('--program <file>', 'Path to a program JSON file')
     .option('--dry', 'Dry run: execute all opcodes without capturing or uploading artifacts (0 credits charged)', false)
+    .option('--regenerate-tts', 'Force fresh TTS synthesis for video presets — ignore cached audio segments. Reused segments become billable at full rate.', false)
     .option('--debug', 'Verbose logging: per-substep timing, opcode dumps, recovery strategy traces', false)
     .action(async (presetId, opts) => {
     if (opts.debug) {
@@ -263,6 +306,19 @@ program
         process.env[WS_URL_ENV_VAR] = LOCAL_WS_URL;
         logger.info(`Using local AutoKap dev server: ${LOCAL_API_BASE_URL}`);
     }
+    if (opts.outdated) {
+        if (!opts.project) {
+            fatal('Missing --project <id> for `autokap run --outdated`.');
+        }
+        if (opts.program) {
+            fatal('`--program` cannot be combined with `--outdated`.');
+        }
+        await runOutdatedPresetsLocally(opts);
+        return;
+    }
+    if (!presetId) {
+        fatal('Missing preset ID. Use `autokap run <preset-id>` or `autokap run --outdated --project <project-id>`.');
+    }
     const { runLocal } = await import('./cli-runner-local.js');
     await runLocal(presetId, opts);
 });
@@ -278,6 +334,7 @@ program
     .option('--debug', 'Verbose logging: per-substep timing, opcode dumps, recovery strategy traces', false)
     .option('--cloud', 'Cloud runner mode: signals 4+ vCPU available, unblocks the conservative Linux FPS default (8 → 30)', false)
     .option('--preset-ids <ids>', 'Comma-separated preset IDs to capture. When omitted, captures all presets with auto_recapture_enabled=true.')
+    .option('--outdated', 'Capture only outdated auto-recapture presets.', false)
     .action(async (opts) => {
     if (opts.debug) {
         const { setDebugEnabled } = await import('./logger.js');
@@ -392,9 +449,10 @@ program
     // When `--preset-ids` is provided, restrict the run to that subset
     // (per-preset recapture launched from the dashboard).
     const presetIdsArg = opts.presetIds?.trim();
+    const freshnessSuffix = opts.outdated ? '?freshness=outdated' : '';
     const presetsPath = presetIdsArg
         ? `/api/cli/projects/${opts.project}/auto-recapture-presets?preset_ids=${encodeURIComponent(presetIdsArg)}`
-        : `/api/cli/projects/${opts.project}/auto-recapture-presets`;
+        : `/api/cli/projects/${opts.project}/auto-recapture-presets${freshnessSuffix}`;
     let data;
     try {
         const response = await fetch(buildApiUrl(config, presetsPath), {

package/dist/execution-schema.d.ts

@@ -4201,6 +4201,51 @@ export declare function safeParseProgramResult(data: unknown): z.ZodSafeParseRes
         }[] | undefined;
     };
     steps: ({
+        urlPattern: string;
+        description: string;
+        postcondition: {
+            type: "route_matches" | "element_visible" | "element_absent" | "text_contains" | "overlay_dismissed" | "screenshot_stable" | "any_change" | "always";
+            pattern?: string | undefined;
+            selector?: string | undefined;
+            text?: string | undefined;
+            threshold?: number | undefined;
+            waitMs?: number | undefined;
+        };
+        recovery: {
+            retries: number;
+            useSelectorMemory: boolean;
+            useAltInteraction: boolean;
+            allowReload: boolean;
+            allowHealer: boolean;
+        };
+        timeoutMs: number;
+        maxFailures: number;
+        kind: "ASSERT_ROUTE";
+        stepId?: string | undefined;
+    } | {
+        selectors: string[];
+        matchAll: boolean;
+        description: string;
+        postcondition: {
+            type: "route_matches" | "element_visible" | "element_absent" | "text_contains" | "overlay_dismissed" | "screenshot_stable" | "any_change" | "always";
+            pattern?: string | undefined;
+            selector?: string | undefined;
+            text?: string | undefined;
+            threshold?: number | undefined;
+            waitMs?: number | undefined;
+        };
+        recovery: {
+            retries: number;
+            useSelectorMemory: boolean;
+            useAltInteraction: boolean;
+            allowReload: boolean;
+            allowHealer: boolean;
+        };
+        timeoutMs: number;
+        maxFailures: number;
+        kind: "ASSERT_SURFACE";
+        stepId?: string | undefined;
+    } | {
         state: "visible" | "attached";
         description: string;
         postcondition: {
@@ -4470,51 +4515,6 @@ export declare function safeParseProgramResult(data: unknown): z.ZodSafeParseRes
         maxFailures: number;
         kind: "DISMISS_OVERLAYS";
         stepId?: string | undefined;
-    } | {
-        urlPattern: string;
-        description: string;
-        postcondition: {
-            type: "route_matches" | "element_visible" | "element_absent" | "text_contains" | "overlay_dismissed" | "screenshot_stable" | "any_change" | "always";
-            pattern?: string | undefined;
-            selector?: string | undefined;
-            text?: string | undefined;
-            threshold?: number | undefined;
-            waitMs?: number | undefined;
-        };
-        recovery: {
-            retries: number;
-            useSelectorMemory: boolean;
-            useAltInteraction: boolean;
-            allowReload: boolean;
-            allowHealer: boolean;
-        };
-        timeoutMs: number;
-        maxFailures: number;
-        kind: "ASSERT_ROUTE";
-        stepId?: string | undefined;
-    } | {
-        selectors: string[];
-        matchAll: boolean;
-        description: string;
-        postcondition: {
-            type: "route_matches" | "element_visible" | "element_absent" | "text_contains" | "overlay_dismissed" | "screenshot_stable" | "any_change" | "always";
-            pattern?: string | undefined;
-            selector?: string | undefined;
-            text?: string | undefined;
-            threshold?: number | undefined;
-            waitMs?: number | undefined;
-        };
-        recovery: {
-            retries: number;
-            useSelectorMemory: boolean;
-            useAltInteraction: boolean;
-            allowReload: boolean;
-            allowHealer: boolean;
-        };
-        timeoutMs: number;
-        maxFailures: number;
-        kind: "ASSERT_SURFACE";
-        stepId?: string | undefined;
     } | {
         selector: string;
         description: string;

package/dist/execution-schema.js

@@ -102,13 +102,35 @@ const AssertRouteOpcodeSchema = z.object({
     kind: z.literal('ASSERT_ROUTE'),
     ...opcodeBase,
     urlPattern: z.string().min(1),
-}).strict();
+}).strict().superRefine((value, ctx) => {
+    const post = value.postcondition;
+    if (post.type === 'always')
+        return;
+    if (post.type === 'route_matches' && post.pattern === value.urlPattern)
+        return;
+    ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'ASSERT_ROUTE uses `urlPattern` as its source of truth; postcondition must be `always` or `route_matches` with the same pattern',
+        path: ['postcondition'],
+    });
+});
 const AssertSurfaceOpcodeSchema = z.object({
     kind: z.literal('ASSERT_SURFACE'),
     ...opcodeBase,
     selectors: z.array(z.string().min(1)).min(1),
     matchAll: z.boolean(),
-}).strict();
+}).strict().superRefine((value, ctx) => {
+    const post = value.postcondition;
+    if (post.type === 'always')
+        return;
+    if (post.type === 'element_visible' && post.selector && value.selectors.includes(post.selector))
+        return;
+    ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'ASSERT_SURFACE uses `selectors`/`matchAll` as its source of truth; postcondition must be `always` or `element_visible` for one of the asserted selectors',
+        path: ['postcondition'],
+    });
+});
 const SemanticTargetSchema = z.object({
     text: z.string().optional(),
     role: z.string().optional(),

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,15 +586,23 @@ 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) {
@@ -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/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}`);
     }

package/dist/selector-resolver.js

@@ -142,8 +142,20 @@ function findNodeByFuzzyText(tree, description) {
     return null;
 }
 function buildSelectorFromNode(node) {
+    if (isUsableSourceRefSelector(node.sourceRef)) {
+        return node.sourceRef;
+    }
     // Try to build the most specific selector from node attributes
     const ref = node.sourceRef;
+    // Extract data-ak / data-testid-style automation hooks
+    for (const attr of ['data-ak', 'data-ak-interact', 'data-testid', 'data-test', 'data-qa', 'data-cy']) {
+        const attrMatch = ref.match(new RegExp(`${attr}="([^"]+)"`));
+        if (attrMatch)
+            return `[${attr}="${escapeText(attrMatch[1])}"]`;
+        const value = node.attributes[attr];
+        if (value)
+            return `[${attr}="${escapeText(value)}"]`;
+    }
     // Extract data-testid
     const testIdMatch = ref.match(/data-testid="([^"]+)"/);
     if (testIdMatch)
@@ -159,11 +171,20 @@ function buildSelectorFromNode(node) {
     if (role) {
         return `${tag}[role="${role}"]`;
     }
-    // Fallback: use AKNode id as a CSS selector via data attribute
-    if (node.id) {
-        return `[data-ak-id="${node.id}"]`;
+    if (node.label) {
+        return `${tag}:has-text("${escapeText(node.label.slice(0, 50))}")`;
     }
-    return `${tag}:has-text("${escapeText(node.label.slice(0, 50))}")`;
+    return null;
+}
+function isUsableSourceRefSelector(sourceRef) {
+    const ref = (sourceRef ?? '').trim();
+    if (!ref || ref.startsWith('<'))
+        return false;
+    return ref === 'body'
+        || ref.startsWith('#')
+        || ref.startsWith('.')
+        || ref.startsWith('[')
+        || /^[a-z][a-z0-9-]*(?:[#.[\s>:]|$)/i.test(ref);
 }
 function tokenize(text) {
     return text

package/dist/server-credit-usage.d.ts

@@ -1,5 +1,5 @@
 import type { SupabaseClient } from '@supabase/supabase-js';
-export type CreditUsageType = 'screenshot' | 'clip' | 'video' | 'preset_analysis' | 'cloud_recapture' | 'ai_chat' | 'studio_creation' | 'studio_iteration';
+export type CreditUsageType = 'screenshot' | 'clip' | 'video' | 'cloud_recapture' | 'ai_chat' | 'studio_creation' | 'studio_iteration';
 export declare function recordCreditUsage(supabase: SupabaseClient, params: {
     userId: string;
     projectId: string | null;

package/dist/smart-wait.js

@@ -17,6 +17,7 @@ export async function smartWaitForStability(adapter, options) {
     const maxWait = options?.maxWaitMs ?? 10000;
     const startTime = Date.now();
     const waitedFor = [];
+    const unresolvedLoaders = [];
     // 1. Wait for no visible spinners/skeletons
     const spinnerSelectors = [
         '[class*="spinner"]',
@@ -57,6 +58,14 @@ export async function smartWaitForStability(adapter, options) {
                         await sleep(300);
                     }
                 }
+                const stillVisible = await adapter.waitFor({
+                    selector,
+                    state: 'visible',
+                    timeoutMs: 100,
+                }).catch(() => false);
+                if (stillVisible) {
+                    unresolvedLoaders.push(selector);
+                }
             }
         }
         catch {
@@ -70,8 +79,8 @@ export async function smartWaitForStability(adapter, options) {
         waitedFor.push('stability-pause');
     }
     return {
-        stable: true,
-        waitedFor,
+        stable: unresolvedLoaders.length === 0,
+        waitedFor: unresolvedLoaders.length > 0 ? unresolvedLoaders : waitedFor,
         waitedMs: Date.now() - startTime,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autokap",
-  "version": "1.5.5",
+  "version": "1.6.0",
   "description": "AI-powered CLI tool for capturing clean screenshots of websites",
   "type": "module",
   "main": "./dist/index.js",