autokap 1.5.4 → 1.5.5

package/assets/skill/OPCODE-REFERENCE.md

@@ -382,16 +382,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

@@ -163,7 +163,7 @@ interface VariantSpec {
 | `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 |
+| `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 |

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<{
@@ -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

@@ -242,12 +242,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>;

package/dist/opcode-runner.js

@@ -545,7 +545,7 @@ async function executeOpcodeAction(opcode, opcodeIndex, adapter, artifacts, tele
                 const captureUrl = await adapter.getCurrentUrl();
                 const takeBuffer = async () => {
                     if (opcode.elementSelector && adapter.takeElementScreenshot) {
-                        return adapter.takeElementScreenshot(opcode.elementSelector);
+                        return adapter.takeElementScreenshot(opcode.elementSelector, opcode.outscale);
                     }
                     if (opcode.elementSelector) {
                         throw new Error(`element capture requires adapter support for selector "${opcode.elementSelector}"`);

package/dist/program-signing.d.ts

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

package/dist/video-narration-schema.d.ts

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

package/dist/web-playwright-local.d.ts

@@ -5,7 +5,7 @@
  * This is the first (and for now only) RuntimeAdapter implementation.
  */
 import type { Browser } from './browser.js';
-import type { AKTree, VideoPageSignals } from './types.js';
+import type { AKTree, OutscaleConfig, VideoPageSignals } from './types.js';
 import type { RuntimeAdapter, ClickOptions, WaitCondition, RecordingOptions, RecordingResult, SemanticTarget } from './execution-types.js';
 import { type ResolveOptions } from './semantic-resolver.js';
 export declare class WebPlaywrightLocal implements RuntimeAdapter {
@@ -63,7 +63,7 @@ export declare class WebPlaywrightLocal implements 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>;
     getElementBoundingBox(selector: string): Promise<{

package/dist/web-playwright-local.js

@@ -316,8 +316,8 @@ export class WebPlaywrightLocal {
     async takeScreenshot() {
         return this.browser.takeScreenshot();
     }
-    async takeElementScreenshot(selector) {
-        const { buffer } = await this.browser.screenshotBySelector(selector);
+    async takeElementScreenshot(selector, outscale) {
+        const { buffer } = await this.browser.screenshotBySelector(selector, outscale);
         return buffer;
     }
     async takeCleanScreenshot() {

package/package.json

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