autokap 1.5.4 → 1.5.7

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" } }
 ```
@@ -382,16 +388,23 @@ Capture a screenshot of the viewport or a specific element.
 | `captureId` | string | no | Stable identifier for Studio/dev links. Should match preset page/element id |
 | `captureName` | string | no | Human-readable label shown in Studio |
 | `elementSelector` | string | no | CSS selector for element-level capture (crops to element bounds) |
+| `outscale` | OutscaleConfig | no | Padding around the captured element (only applied with `elementSelector`). Typically set by the user post-generation. Omit by default. |
 
 **Can:** Full-page viewport capture, element-level capture (cropped), LLM verification (detects blank/error/loading/overlay states), alt text generation, favicon extraction.
 **Cannot:** Capture content below the fold in a single shot (use SCROLL first). Capture cross-origin iframe content.
 
 **Tip:** Without `elementSelector`, captures the full viewport. With `elementSelector`, captures only that element's bounding box — useful for component-level screenshots.
 
+**`outscale` shape:** all fields optional. `padding` is uniform (pixels). `paddingTop/Right/Bottom/Left` override per side. `paddingPercent` (0–100) scales with the element. `clampToViewport` (default `true`) prevents the crop from exceeding the document. `backgroundColor` fills any uncovered area.
+
 ```json
 { "kind": "CAPTURE_SCREENSHOT", "captureId": "dashboard-main", "captureName": "Dashboard", "elementSelector": "[data-ak=\"main-content\"]", "postcondition": { "type": "always" } }
 ```
 
+```json
+{ "kind": "CAPTURE_SCREENSHOT", "captureName": "Pricing card", "elementSelector": "[data-ak=\"pricing\"]", "outscale": { "padding": 24 }, "postcondition": { "type": "always" } }
+```
+
 ## BEGIN_CLIP
 
 Start recording a clip. All interactions between BEGIN_CLIP and END_CLIP are recorded.

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,9 +161,9 @@ 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 |
-| `CAPTURE_SCREENSHOT` | no | `captureId`, `captureName`, `elementSelector?` | `always` | `elementSelector` for element-level crop |
+| `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 |
 | `CLONE_ELEMENT` | yes | `sourceSelector`, `containerSelector`, `count` | `always` | **Non-blocking.** Duplicate a template element N times |
@@ -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

@@ -251,6 +251,7 @@ program
     .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) {

package/dist/execution-schema.d.ts

@@ -29,6 +29,16 @@ export declare const RecoveryPolicySchema: z.ZodObject<{
     allowReload: z.ZodBoolean;
     allowHealer: z.ZodBoolean;
 }, z.core.$strict>;
+export declare const OutscaleConfigSchema: 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>;
 export declare const ExecutionOpcodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     url: z.ZodString;
     description: z.ZodString;
@@ -495,6 +505,16 @@ export declare const ExecutionOpcodeSchema: z.ZodDiscriminatedUnion<[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<{
@@ -1688,6 +1708,16 @@ export declare const ExecutionProgramSchema: 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<{
@@ -2665,6 +2695,16 @@ export declare const HealerPatchSchema: 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<{
@@ -3588,6 +3628,16 @@ export declare const HealerPatchSchema: 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<{
@@ -4151,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: {
@@ -4420,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;
@@ -4610,6 +4660,16 @@ export declare function safeParseProgramResult(data: unknown): z.ZodSafeParseRes
         captureId?: string | undefined;
         captureName?: string | undefined;
         elementSelector?: string | undefined;
+        outscale?: {
+            padding?: number | undefined;
+            paddingTop?: number | undefined;
+            paddingRight?: number | undefined;
+            paddingBottom?: number | undefined;
+            paddingLeft?: number | undefined;
+            paddingPercent?: number | undefined;
+            clampToViewport?: boolean | undefined;
+            backgroundColor?: string | undefined;
+        } | undefined;
         stepId?: string | undefined;
     } | {
         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(),
@@ -242,12 +264,23 @@ const ScrollOpcodeSchema = z.object({
     targetSelector: z.string().optional(),
     target: SemanticTargetSchema.optional(),
 }).strict();
+export const OutscaleConfigSchema = z.object({
+    padding: z.number().min(0).optional(),
+    paddingTop: z.number().min(0).optional(),
+    paddingRight: z.number().min(0).optional(),
+    paddingBottom: z.number().min(0).optional(),
+    paddingLeft: z.number().min(0).optional(),
+    paddingPercent: z.number().min(0).max(100).optional(),
+    clampToViewport: z.boolean().optional(),
+    backgroundColor: z.string().optional(),
+}).strict();
 const CaptureScreenshotOpcodeSchema = z.object({
     kind: z.literal('CAPTURE_SCREENSHOT'),
     ...opcodeBase,
     captureId: z.string().optional(),
     captureName: z.string().optional(),
     elementSelector: z.string().optional(),
+    outscale: OutscaleConfigSchema.optional(),
 }).strict();
 const BeginClipOpcodeSchema = z.object({
     kind: z.literal('BEGIN_CLIP'),

package/dist/execution-types.d.ts

@@ -4,7 +4,7 @@
  * All types for the compiled execution model:
  * preset (natural language) -> ExecutionProgram (typed IR) -> deterministic runtime
  */
-import type { AKTree, BrowserStorageState, BrowserSessionStorageState, VideoCursorTheme, VideoPageSignals } from './types.js';
+import type { AKTree, BrowserStorageState, BrowserSessionStorageState, OutscaleConfig, VideoCursorTheme, VideoPageSignals } from './types.js';
 import type { MockupOptions } from './mockup.js';
 /** Sentinel value that resolves to the current variant's locale or theme at runtime */
 export declare const VARIANT_PLACEHOLDER: "$variant";
@@ -247,6 +247,8 @@ export interface CaptureScreenshotOpcode extends OpcodeBase {
     captureName?: string;
     /** Optional element selector for element-level capture */
     elementSelector?: string;
+    /** Optional padding around the captured element. Only applied when `elementSelector` is set. */
+    outscale?: OutscaleConfig;
 }
 export interface BeginClipOpcode extends OpcodeBase {
     kind: 'BEGIN_CLIP';
@@ -809,7 +811,7 @@ export interface RuntimeAdapter {
         method: string | null;
     }>;
     takeScreenshot(): Promise<Buffer>;
-    takeElementScreenshot?(selector: string): Promise<Buffer>;
+    takeElementScreenshot?(selector: string, outscale?: OutscaleConfig): Promise<Buffer>;
     takeCleanScreenshot(): Promise<Buffer>;
     beginRecording(options: RecordingOptions): Promise<void>;
     endRecording(): Promise<RecordingResult>;