autokap 1.0.7 → 1.0.10

package/assets/cursors/macos.svg

@@ -0,0 +1,4 @@
+<svg width="28" height="29" viewBox="0 0 28 29" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path fill-rule="evenodd" clip-rule="evenodd" d="M14.501 11.8601L22.884 20.2611C23.937 21.3171 23.19 23.1191 21.699 23.1191L20.475 23.119L21.6908 26.0067C21.9038 26.5127 21.9068 27.0727 21.6998 27.5817C21.4918 28.0917 21.0978 28.4897 20.5898 28.7027C20.3338 28.8097 20.0658 28.8637 19.7918 28.8637C18.9608 28.8637 18.2158 28.3687 17.8938 27.6027L16.616 24.565L15.784 25.3031C14.703 26.2591 13 25.4921 13 24.0481V12.4811C13 11.6971 13.947 11.3051 14.501 11.8601Z" fill="white"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M13.9995 13.1292C13.9995 12.9982 14.1585 12.9322 14.2505 13.0252L22.1585 20.9502C22.5895 21.3822 22.2835 22.1192 21.6735 22.1192L18.9695 22.1177L20.7691 26.3936C20.9961 26.9336 20.7421 27.5546 20.2031 27.7806C19.6621 28.0076 19.0421 27.7546 18.8161 27.2156L16.9985 22.8917L15.1385 24.5392C14.7225 24.9072 14.0806 24.6507 14.0066 24.1274L13.9995 24.0262V13.1292Z" fill="black"/>
+</svg>

package/assets/cursors/windows.svg

@@ -0,0 +1,15 @@
+<svg width="28" height="28" viewBox="0 0 28 28" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_575_755)">
+<mask id="mask0_575_755" style="mask-type:luminance" maskUnits="userSpaceOnUse" x="0" y="0" width="28" height="28">
+<path d="M28 0H0V28H28V0Z" fill="white"/>
+</mask>
+<g mask="url(#mask0_575_755)">
+<path d="M15.1388 23.7243L15.1355 23.7274C15.1355 23.7274 15.1322 23.7289 15.1296 23.7298C15.1186 23.7338 15.1046 23.7364 15.0911 23.7364C15.0409 23.7364 15 23.6978 15 23.6505V13.0765C15 13.0631 15.0091 13.0333 15.0565 13.012C15.0948 12.9948 15.1274 12.9974 15.1526 13.0115L23.3195 20.7147C23.3441 20.7458 23.3531 20.7662 23.3565 20.7754C23.3599 20.7848 23.36 20.7895 23.36 20.7926C23.36 20.84 23.3191 20.8786 23.2689 20.8786H19.6763L21.6633 25.2605L19.8237 26.0044L17.7977 21.5384L15.1388 23.7243Z" fill="white" stroke="black"/>
+</g>
+</g>
+<defs>
+<clipPath id="clip0_575_755">
+<rect width="28" height="28" fill="white"/>
+</clipPath>
+</defs>
+</svg>

package/assets/skill/OPCODE-REFERENCE.md

@@ -0,0 +1,635 @@
+# AutoKap Opcode Reference
+
+Detailed parameter documentation for all 25 opcodes. For workflow, rules, and examples, see [SKILL.md](SKILL.md).
+
+## Common Fields (all opcodes)
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `kind` | string | yes | — | Opcode type (see sections below) |
+| `description` | string | yes | — | Human-readable description of this step |
+| `postcondition` | PostconditionSpec | yes | — | Condition that must hold after execution |
+| `recovery` | RecoveryPolicy | yes | — | Recovery behavior on failure |
+| `timeoutMs` | number | yes | 15000 | Max time (ms) including recovery |
+| `maxFailures` | number | yes | 3 | Max recovery attempts before fatal |
+
+### RecoveryPolicy
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `retries` | number (0-10) | 2 | Deterministic retry attempts |
+| `useSelectorMemory` | boolean | true | Try known-good selectors from previous runs |
+| `useAltInteraction` | boolean | true | Try keyboard/JS/coordinate click |
+| `allowReload` | boolean | false | Reload page and retry. **Use sparingly** — loses UI state (open modals, form data). Only safe after full page transitions. |
+| `allowHealer` | boolean | true | Allow LLM to rewrite the failing opcode as last resort |
+
+### SemanticTarget (optional on interaction opcodes)
+
+Fallback when CSS selector fails. The runtime resolves via Playwright semantic locators, then AKTree fuzzy matching.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `text` | string | Visible text content (substring match by default) |
+| `role` | string | ARIA role: `"button"`, `"link"`, `"textbox"`, `"checkbox"`, `"tab"`, `"menuitem"` |
+| `label` | string | `aria-label`, associated `<label>` text, or `title` attribute |
+| `near` | string | Nearby text for disambiguation (e.g. `"in the pricing section"`) |
+| `placeholder` | string | Input placeholder text |
+| `exact` | boolean | If `true`, match text exactly. Default: `false` (substring) |
+
+### PostconditionSpec
+
+| Field | Type | Used by | Description |
+|-------|------|---------|-------------|
+| `type` | string | all | One of the 8 postcondition types (see SKILL.md) |
+| `pattern` | string | `route_matches` | URL glob pattern (`*` = segment, `**` = any path) |
+| `selector` | string | `element_visible`, `element_absent`, `text_contains` | CSS selector to check |
+| `text` | string | `text_contains` | Expected text substring |
+| `threshold` | number (0-1) | `screenshot_stable` | Pixel diff tolerance. Default: `0.01` |
+| `waitMs` | number | all except `always` | Max polling time (ms). Default: `5000` |
+
+---
+
+## NAVIGATE
+
+Navigate to a URL.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `url` | string | yes | Full URL to navigate to |
+
+**Can:** Load any URL, follow redirects, handle SPA route changes.
+**Cannot:** Open new tabs/windows. Use CLICK with `button: "middle"` for that.
+
+```json
+{ "kind": "NAVIGATE", "url": "https://app.example.com/pricing", "postcondition": { "type": "route_matches", "pattern": "/pricing" } }
+```
+
+## DISMISS_OVERLAYS
+
+Automatically dismisses cookie banners, newsletter popups, chat widgets, and age gates. Multi-pass: adapter dismissal, Escape key, close-button clicks (multilingual patterns).
+
+No additional parameters.
+
+**Can:** Handle common overlays in any language (en, fr, de, es, it patterns).
+**Cannot:** Dismiss overlays that require form input (e.g. age verification with date entry) or CAPTCHAs.
+
+```json
+{ "kind": "DISMISS_OVERLAYS", "postcondition": { "type": "overlay_dismissed" } }
+```
+
+## CLICK
+
+Click an element.
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `selector` | string | yes | — | CSS selector (use `data-ak` attributes) |
+| `target` | SemanticTarget | no | — | Fallback for recovery chain |
+| `button` | `"right"` \| `"middle"` | no | left | `"right"` = context menu, `"middle"` = new tab |
+| `fingerprint` | string | no | — | AKTree fingerprint for fuzzy matching |
+| `selectorAlternates` | string[] | no | — | Alternative selectors tried in order |
+
+**Can:** Left/right/middle click, trigger navigation, open modals, toggle dropdowns.
+**Cannot:** Drag-and-drop, long-press, touch gestures.
+
+```json
+{ "kind": "CLICK", "selector": "[data-ak=\"pricing-btn\"]", "postcondition": { "type": "element_visible", "selector": "[data-ak=\"pricing-modal\"]", "waitMs": 5000 } }
+```
+
+## TYPE
+
+Type text into a form field.
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `selector` | string | yes | — | CSS selector of the input/textarea |
+| `text` | string | yes | — | Text to type. Use `{{email}}` / `{{password}}` for credentials |
+| `clearFirst` | boolean | yes | true | Clear existing value before typing |
+| `target` | SemanticTarget | no | — | Fallback for recovery chain |
+| `fingerprint` | string | no | — | AKTree fingerprint |
+| `selectorAlternates` | string[] | no | — | Alternative selectors |
+
+**Can:** Type into text inputs, textareas, contenteditable elements. Clear existing values. Use credential placeholders.
+**Cannot:** Type into file inputs (use file upload instead). Paste from clipboard.
+
+```json
+{ "kind": "TYPE", "selector": "[data-ak=\"search-input\"]", "text": "dashboard", "clearFirst": true, "postcondition": { "type": "any_change" } }
+```
+
+## PRESS_KEY
+
+Press a keyboard key.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `key` | string | yes | Key name: `"Enter"`, `"Escape"`, `"Tab"`, `"ArrowDown"`, `"Backspace"`, etc. |
+
+**Can:** Submit forms (Enter), close modals (Escape), navigate focus (Tab), trigger keyboard shortcuts.
+**Cannot:** Key combinations (Ctrl+C, Cmd+V). For shortcuts, use the individual key name that Playwright supports.
+
+```json
+{ "kind": "PRESS_KEY", "key": "Enter", "postcondition": { "type": "any_change" } }
+```
+
+## WAIT_FOR
+
+Wait for an element to appear.
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `selector` | string | no* | — | CSS selector to wait for |
+| `target` | SemanticTarget | no* | — | Semantic target to wait for |
+| `state` | `"visible"` \| `"attached"` | yes | — | `"visible"` = rendered and visible. `"attached"` = in DOM but may be hidden |
+
+*At least one of `selector` or `target` is required.
+
+**Can:** Wait for page content to load, modals to appear, dynamic elements to render.
+**Cannot:** Wait for network requests or API responses directly. Use `state: "attached"` for elements that exist in DOM but are initially hidden (e.g. lazy-loaded tabs).
+
+```json
+{ "kind": "WAIT_FOR", "selector": "[data-ak=\"dashboard\"]", "state": "visible", "postcondition": { "type": "element_visible", "selector": "[data-ak=\"dashboard\"]", "waitMs": 10000 } }
+```
+
+## SCROLL
+
+Scroll the page or scroll an element into view.
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `direction` | `"up"` \| `"down"` \| `"left"` \| `"right"` | yes | — | Scroll direction |
+| `amount` | number | no | viewport height | Pixels to scroll |
+| `targetSelector` | string | no | — | CSS selector to scroll into view |
+| `target` | SemanticTarget | no | — | Semantic target to scroll into view |
+
+**Can:** Scroll page in any direction, scroll specific element into view, scroll by pixel amount.
+**Cannot:** Scroll inside a specific scrollable container (always scrolls the page). For nested scrollable areas, use CLICK to focus the container first.
+
+**Tip:** When `targetSelector` is provided, the runtime scrolls the element into view regardless of `direction`/`amount`. Use `direction` + `amount` for blind scrolling, `targetSelector` for precise positioning.
+
+```json
+{ "kind": "SCROLL", "direction": "down", "targetSelector": "[data-ak=\"pricing\"]", "postcondition": { "type": "element_visible", "selector": "[data-ak=\"pricing\"]" } }
+```
+
+## HOVER
+
+Hover over an element.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `selector` | string | yes | CSS selector |
+| `target` | SemanticTarget | no | Fallback for recovery chain |
+| `fingerprint` | string | no | AKTree fingerprint |
+| `selectorAlternates` | string[] | no | Alternative selectors |
+
+**Can:** Trigger tooltips, dropdown menus, CSS `:hover` states, hover cards.
+**Cannot:** Hover state persists only until the next interaction. If you need to capture a hover state, place CAPTURE_SCREENSHOT immediately after HOVER.
+
+```json
+{ "kind": "HOVER", "selector": "[data-ak=\"nav-products\"]", "postcondition": { "type": "element_visible", "selector": "[data-ak=\"products-dropdown\"]", "waitMs": 3000 } }
+```
+
+## SELECT_OPTION
+
+Select an option in a **native `<select>` element**.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `selector` | string | yes | CSS selector of the `<select>` element |
+| `optionLabel` | string | no* | Select by visible label text |
+| `optionValue` | string | no* | Select by `value` attribute |
+| `optionIndex` | number | no* | Select by zero-based index |
+| `target` | SemanticTarget | no | Fallback for recovery chain |
+| `fingerprint` | string | no | AKTree fingerprint |
+| `selectorAlternates` | string[] | no | Alternative selectors |
+
+*Exactly one of `optionLabel`, `optionValue`, or `optionIndex` must be provided. Prefer `optionLabel` for readability.
+
+**Can:** Select from native `<select>` dropdowns.
+**Cannot:** Select from custom dropdowns (Radix Select, Headless UI Listbox, MUI Select, cmdk). For custom dropdowns, use a CLICK + WAIT_FOR + CLICK sequence: click to open, wait for options, click the option.
+
+```json
+{ "kind": "SELECT_OPTION", "selector": "[data-ak=\"country-select\"]", "optionLabel": "France", "postcondition": { "type": "text_contains", "selector": "[data-ak=\"country-select\"]", "text": "France" } }
+```
+
+## CHECK
+
+Set a checkbox or toggle to a specific state.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `selector` | string | yes | CSS selector of the checkbox/toggle |
+| `checked` | boolean | yes | `true` = checked, `false` = unchecked |
+| `target` | SemanticTarget | no | Fallback for recovery chain |
+| `fingerprint` | string | no | AKTree fingerprint |
+| `selectorAlternates` | string[] | no | Alternative selectors |
+
+**Can:** Idempotently set checkbox state. Safer than CLICK because it sets the desired state directly without toggling.
+**Cannot:** Interact with custom toggle components that don't use native checkbox semantics. For those, use CLICK.
+
+```json
+{ "kind": "CHECK", "selector": "[data-ak=\"terms-checkbox\"]", "checked": true, "postcondition": { "type": "always" } }
+```
+
+## DOUBLE_CLICK
+
+Double-click an element.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `selector` | string | yes | CSS selector |
+| `target` | SemanticTarget | no | Fallback for recovery chain |
+| `fingerprint` | string | no | AKTree fingerprint |
+| `selectorAlternates` | string[] | no | Alternative selectors |
+
+**Can:** Trigger inline editing, text selection, and any UI that responds to `dblclick`.
+**Cannot:** Triple-click (select paragraph). Use TYPE with `clearFirst: true` to replace full text content instead.
+
+```json
+{ "kind": "DOUBLE_CLICK", "selector": "[data-ak=\"editable-title\"]", "postcondition": { "type": "element_visible", "selector": "[data-ak=\"title-editor\"]", "waitMs": 3000 } }
+```
+
+## DRAG
+
+Drag the source element from point A to point B with an animated cursor. In clip recordings the cursor overlay glides along a Bezier curve, shows a pressed state during the drag, and emits a drop pulse at the destination.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `selector` | string | yes | CSS selector of the source element (the one being dragged) |
+| `target` | SemanticTarget | no | Semantic fallback for the source |
+| `fingerprint` | string | no | AKTree fingerprint for the source |
+| `selectorAlternates` | string[] | no | Alternative source selectors |
+| `toSelector` | string | no* | CSS selector of the drop target element |
+| `toTarget` | SemanticTarget | no* | Semantic fallback for the drop target |
+| `toSelectorAlternates` | string[] | no | Alternative destination selectors |
+| `offset` | `{ dx: number, dy: number }` | no* | Pixel offset from the source center (use for sliders, canvas drawing, or any drop that isn't a DOM node) |
+
+*Provide EITHER `toSelector` / `toTarget` (element drag) OR `offset` (relative drag). Not both.
+
+**Can:** Element-to-element drag (Kanban columns, sortable lists), slider adjustments, canvas drawing, any interaction driven by mousedown + mousemove + mouseup. Works with native HTML5 drag, dnd-kit, react-dnd, Radix DnD primitives — `page.mouse.*` fires both mouse and pointer events.
+**Cannot:** Multi-touch gestures, drag between different browser windows, file drops (use a file input instead).
+
+```json
+{ "kind": "DRAG", "selector": "[data-ak=\"task-card-todo-1\"]", "toSelector": "[data-ak=\"column-in-progress\"]", "postcondition": { "type": "element_visible", "selector": "[data-ak=\"column-in-progress\"] [data-ak=\"task-card-todo-1\"]", "waitMs": 3000 } }
+```
+
+```json
+{ "kind": "DRAG", "selector": "[data-ak=\"volume-slider-thumb\"]", "offset": { "dx": 120, "dy": 0 }, "postcondition": { "type": "any_change" } }
+```
+
+## SET_LOCALE
+
+Set the application's locale/language for the current variant.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `locale` | string | yes | BCP-47 locale (e.g. `"fr"`, `"en-US"`). Use `"$variant"` for runtime substitution |
+| `method` | `"browser_context"` \| `"ui_interaction"` \| `"storage"` | yes | How to apply the locale |
+| `selector` | string | no | Element to click (for `ui_interaction` only) |
+| `storageHints` | StorageHint[] | no | Storage writes (for `storage` only) |
+
+**StorageHint:** `{ "storage": "localStorage" | "sessionStorage" | "cookie", "key": string, "value": string }`
+
+**Can:** Switch locale via storage writes (instant, reliable), browser context, or UI click.
+**Cannot:** Handle URL-based routing (e.g. `/fr/page`). For URL-based i18n, use NAVIGATE with the locale path.
+
+**Method decision tree:**
+- **next-intl** -> `method: "storage"`, `storage: "cookie"`, key: `"NEXT_LOCALE"`
+- **i18next / react-intl** -> `method: "storage"`, `storage: "localStorage"`, key: `"i18nextLng"`
+- **URL-based** (e.g. `/fr/page`) -> Use NAVIGATE instead
+- **Browser-level only** -> `method: "browser_context"`
+
+```json
+{ "kind": "SET_LOCALE", "locale": "$variant", "method": "storage", "storageHints": [{ "storage": "cookie", "key": "NEXT_LOCALE", "value": "$variant" }], "postcondition": { "type": "always" } }
+```
+
+## SET_THEME
+
+Set the application's color theme for the current variant.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `theme` | `"light"` \| `"dark"` \| `"$variant"` | yes | Target theme. Use `"$variant"` for runtime substitution |
+| `method` | `"color_scheme"` \| `"ui_interaction"` \| `"storage"` | yes | How to apply the theme |
+| `selector` | string | no | Element to click (for `ui_interaction` only) |
+| `storageHints` | StorageHint[] | no | Storage writes (for `storage` only) |
+
+**Can:** Switch theme via storage writes (instant, reliable), CSS `prefers-color-scheme`, or UI click.
+**Cannot:** Handle complex theme systems with more than light/dark (e.g. "system", "sepia"). For those, use `method: "storage"` with the exact value the app expects.
+
+**Method decision tree:**
+- **next-themes** -> `method: "storage"`, `storage: "localStorage"`, key: `"theme"`
+- **CSS only** (reads `prefers-color-scheme`) -> `method: "color_scheme"`
+- **Custom storage** -> `method: "storage"` with app-specific key
+
+```json
+{ "kind": "SET_THEME", "theme": "$variant", "method": "storage", "storageHints": [{ "storage": "localStorage", "key": "theme", "value": "$variant" }], "postcondition": { "type": "always" } }
+```
+
+## ASSERT_ROUTE
+
+Assert the current URL matches a pattern. Pure validation, no navigation.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `urlPattern` | string | yes | URL glob pattern (`*` = segment, `**` = any path) |
+
+**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.
+
+```json
+{ "kind": "ASSERT_ROUTE", "urlPattern": "/dashboard/**", "postcondition": { "type": "route_matches", "pattern": "/dashboard/**" } }
+```
+
+## ASSERT_SURFACE
+
+Assert that specific elements are visible on the page. Pure validation.
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `selectors` | string[] | yes | — | CSS selectors that must be visible |
+| `matchAll` | boolean | yes | true | `true` = ALL must match, `false` = ANY one suffices |
+
+**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.
+
+```json
+{ "kind": "ASSERT_SURFACE", "selectors": ["[data-ak=\"header\"]", "[data-ak=\"sidebar\"]"], "matchAll": true, "postcondition": { "type": "always" } }
+```
+
+## CAPTURE_SCREENSHOT
+
+Capture a screenshot of the viewport or a specific element.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `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) |
+
+**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.
+
+```json
+{ "kind": "CAPTURE_SCREENSHOT", "captureId": "dashboard-main", "captureName": "Dashboard", "elementSelector": "[data-ak=\"main-content\"]", "postcondition": { "type": "always" } }
+```
+
+## CAPTURE_DOM
+
+Capture a DOM snapshot for an interactive demo state.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `stateName` | string | yes | Stable state identifier used by the interactive demo player |
+| `selector` | string | no | CSS selector of a focused subtree to serialize instead of the whole page |
+
+**Can:** Capture the full page DOM for a state, or a focused subtree when only part of the page matters. Feed the interactive demo player with a state that can later host fragments and transitions.
+**Cannot:** Produce screenshots or clips. Use only when `mediaMode` is `dom`.
+
+**Tip:** Omit `selector` for page-level states. Add it when the interactive demo should ignore surrounding chrome and serialize only a mounted area.
+
+```json
+{ "kind": "CAPTURE_DOM", "stateName": "dashboard-default", "selector": "[data-ak=\"dashboard-shell\"]", "postcondition": { "type": "always" } }
+```
+
+## CAPTURE_FRAGMENT
+
+Capture a local DOM fragment that mounts on top of a previously captured state.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `fragmentName` | string | yes | Stable fragment identifier |
+| `parentState` | string | yes | Name of the CAPTURE_DOM state this fragment belongs to |
+| `selector` | string | yes | CSS selector of the fragment root to serialize |
+| `variantName` | string | no | Optional named fragment variant for in-place swaps |
+| `triggerSelector` | string | no | Selector of the element that should trigger this fragment in the player |
+| `mountStrategy` | `"replace"` \| `"append"` | no | How the player should mount the fragment relative to the parent state |
+
+**Can:** Capture modals, popovers, dropdowns, drawers, or any local subtree that should be replayed on top of a parent state. Capture multiple variants of the same fragment to enable in-place swaps in the player.
+**Cannot:** Stand alone without a `parentState`. Replace full-page routing states; use CAPTURE_DOM for those.
+
+**Tip:** Use `variantName` when the same fragment can appear in multiple visual forms, such as color/theme swaps or alternate content blocks on the same background state.
+
+```json
+{ "kind": "CAPTURE_FRAGMENT", "fragmentName": "pricing-modal", "parentState": "dashboard-default", "selector": "[data-ak=\"pricing-modal\"]", "triggerSelector": "[data-ak=\"open-pricing\"]", "mountStrategy": "append", "postcondition": { "type": "always" } }
+```
+
+## BEGIN_CLIP
+
+Start recording a clip. All interactions between BEGIN_CLIP and END_CLIP are recorded.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `clipId` | string | no | Stable identifier for Studio/dev links. Should match preset clip id |
+| `clipName` | string | no | Human-readable label shown in Studio |
+
+**Can:** Record viewport interactions as a clip.
+**Cannot:** Record element-level clips (always full viewport). Record audio.
+
+```json
+{ "kind": "BEGIN_CLIP", "clipId": "open-modal-flow", "clipName": "Open modal", "postcondition": { "type": "always" } }
+```
+
+## END_CLIP
+
+Stop recording the clip. Must pair with a prior BEGIN_CLIP.
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `clipId` | string | no | Must match the BEGIN_CLIP's `clipId` |
+| `clipName` | string | no | Must match the BEGIN_CLIP's `clipName` |
+
+**Can:** Finalize recording and produce GIF/MP4 artifact.
+**Cannot:** Trim or edit the recording. The full BEGIN_CLIP to END_CLIP duration is captured.
+
+```json
+{ "kind": "END_CLIP", "clipId": "open-modal-flow", "clipName": "Open modal", "postcondition": { "type": "always" } }
+```
+
+## CLONE_ELEMENT
+
+Duplicate a template element N times into a container. **Non-blocking** — if a selector misses, the opcode is skipped and the run continues.
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `sourceSelector` | string | yes | — | CSS selector of the element to clone |
+| `containerSelector` | string | yes | — | CSS selector of the container that receives the clones |
+| `count` | number (1-500) | yes | — | Number of clones to produce |
+| `removeSource` | boolean | no | false | If true, remove the template after cloning (template must be a child of the container) |
+
+**Can:** Duplicate any DOM node including its descendants and attributes. Optionally remove the source after cloning.
+**Cannot:** Clone content from cross-origin iframes. Clone the shadow tree of Web Components (only the host is cloned).
+
+**Soft-failure semantics:** Throws if `sourceSelector` or `containerSelector` is missing. The runner converts the throw into `status: "skipped"` and the variant continues.
+
+```json
+{ "kind": "CLONE_ELEMENT", "description": "Clone customer row 5 times", "sourceSelector": "[data-ak=\"customer-row\"]", "containerSelector": "[data-ak=\"customers-tbody\"]", "count": 5, "postcondition": { "type": "always" }, "recovery": { "retries": 0, "useSelectorMemory": false, "useAltInteraction": false, "allowReload": false, "allowHealer": false }, "timeoutMs": 5000, "maxFailures": 1 }
+```
+
+## INJECT_MOCK_DATA
+
+Orchestrator opcode that fills a fillable region with mock data. Carries fields for **two complementary delivery mechanisms** and applies BOTH whenever they are wired:
+
+- **Clone**: clones a template DOM element N times into a container and writes each slot value into the cloned descendants. Provides instant visual feedback even before any state-driven re-render. Works for any container whose children are pure markup the runtime can mutate.
+- **Trigger**: writes the JSON-encoded `defaultValues` array into a hidden `<input>` the user's app exposed, then clicks a hidden trigger element via `element.click()`. The user's `onClick` handler reads the input, parses the JSON, and re-renders the widget through normal React/Vue/Svelte state updates. Survives any future re-renders that would clobber the cloned DOM, and works for libraries that own their DOM (Chart.js, Recharts, D3).
+
+The two mechanisms are independent and additive. **Wire both whenever possible** — clone for instant paint, trigger to survive re-renders. The runtime applies clone first, then trigger. The opcode is recorded as `applied` if AT LEAST ONE mechanism succeeds.
+
+The named group is looked up from `ExecutionProgram.mockDataGroups` (compiled from `PresetConfig.mockDataInjection.groups`). **Non-blocking** — if both mechanisms fail (or neither was wired), the opcode is recorded as `mockDataGroupResults[groupName] = "skipped"` and the run continues.
+
+### Common params
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `groupName` | string | yes | Name of the MockDataGroup to use (must exist in the preset's `mockDataInjection.groups`) |
+
+### Clone params (optional but typically populated)
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `containerSelector` | string | conditional | — | CSS selector of the container that holds the cloned items. Required if any other clone field is present. |
+| `templateSelector` | string | no | first child of container | CSS selector of the element to clone (defaults to `${containerSelector} > *:first-child`) |
+| `count` | number (1-500) | no | `defaultValues.length` | Override the row count |
+| `removeTemplate` | boolean | no | `false` | If true, remove the template after cloning (use to replace empty-state placeholders) |
+| `slotMappings` | array of `{ slot, selector, attribute? }` | conditional | — | Maps each slot name to a target inside a cloned item. Required if `containerSelector` is present. |
+
+**`slotMappings` entry:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `slot` | string | yes | Name of a slot from the MockDataGroup |
+| `selector` | string | yes | CSS selector RELATIVE to the cloned item |
+| `attribute` | string | no | If present, write to `setAttribute(name, value)`. If absent, write to `textContent`. |
+
+The runtime tags each clone with `data-ak-mock-clone="<i>"` so slot selectors are addressed via the tag rather than `nth-child` math — robust against non-template siblings (placeholders, headers).
+
+### Trigger params (optional but typically populated)
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `inputSelector` | string | conditional | CSS selector of the hidden `<input>` / `<textarea>` / `<select>` that receives the JSON payload. Required if `triggerSelector` is present. Use `[data-ak-fill-input="<group>"]`. |
+| `triggerSelector` | string | conditional | CSS selector of the hidden trigger element AutoKap clicks programmatically. Required if `inputSelector` is present. Use `[data-ak-fill-trigger="<group>"]`. |
+
+The runtime serializes `defaultValues` as a JSON array (`JSON.stringify(group.defaultValues)`) and writes it into the input via the React-aware native value setter, then dispatches `input` and `change` events, then calls `triggerElement.click()` directly. The user's `onClick` handler is responsible for parsing and applying the data.
+
+### Validation
+
+At least one mechanism must be complete (clone = `containerSelector` + `slotMappings`; trigger = `inputSelector` + `triggerSelector`). Partial mechanisms are rejected at compile time.
+
+### Capabilities
+
+**Can:**
+- Apply both mechanisms additively for the same group, in a single opcode.
+- Populate tables, lists, card grids, badge rows, and any container with text or image-source values via the clone mechanism.
+- Re-render charts, maps, calendars, and any programmatic widget via the trigger mechanism, by asking the user's app to handle the seed data through normal state updates.
+
+**Cannot:**
+- Trigger mechanism cannot work without app-side cooperation (the assistant must add a hidden trigger + input + `onClick` handler to the user's source code). The handler must JSON.parse the input value and validate the shape defensively.
+- Clone mechanism cannot persist DOM mutations into React/Vue/Svelte state — on the next render the framework reconciles its virtual tree against the real DOM and overwrites the cloned children. (This is exactly why you should also wire the trigger mechanism — it routes the same data through state, so the next render preserves it.)
+
+### Soft-failure semantics
+
+Returns failure if the group is missing, has no `defaultValues`, the opcode declares neither mechanism, or both wired mechanisms fail at runtime. The runner converts failure into `status: "skipped"` and records `mockDataGroupResults[groupName] = "skipped"`. If at least one mechanism succeeds, the group is recorded as `"applied"` even if the other failed.
+
+### Example — Both mechanisms (recommended)
+
+```json
+{
+  "kind": "INJECT_MOCK_DATA",
+  "description": "Populate preset cards with mock data",
+  "groupName": "preset-cards",
+
+  "containerSelector": "[data-ak=\"preset-card-grid\"]",
+  "templateSelector": "[data-ak=\"preset-card-grid\"] > [data-ak=\"preset-card\"]",
+  "removeTemplate": true,
+  "slotMappings": [
+    { "slot": "title", "selector": "[data-ak=\"preset-card-title\"]" },
+    { "slot": "lastCapture", "selector": "[data-ak=\"preset-card-last-capture\"]" },
+    { "slot": "variantCount", "selector": "[data-ak=\"preset-card-variant-count\"]" },
+    { "slot": "creditCost", "selector": "[data-ak=\"preset-card-credit-cost\"]" },
+    { "slot": "typeBadge", "selector": "[data-ak=\"preset-card-type-badge\"]" }
+  ],
+
+  "inputSelector": "[data-ak-fill-input=\"preset-cards\"]",
+  "triggerSelector": "[data-ak-fill-trigger=\"preset-cards\"]",
+
+  "postcondition": { "type": "always" },
+  "recovery": { "retries": 0, "useSelectorMemory": false, "useAltInteraction": false, "allowReload": false, "allowHealer": false },
+  "timeoutMs": 5000,
+  "maxFailures": 1
+}
+```
+
+### Example — Clone-only (static HTML, no app state)
+
+```json
+{
+  "kind": "INJECT_MOCK_DATA",
+  "description": "Populate static customers table",
+  "groupName": "customers-table",
+  "containerSelector": "[data-ak=\"customers-tbody\"]",
+  "templateSelector": "[data-ak=\"customers-tbody\"] > [data-ak=\"customer-row\"]",
+  "removeTemplate": true,
+  "slotMappings": [
+    { "slot": "name", "selector": "[data-ak=\"customer-name\"]" },
+    { "slot": "avatar", "selector": "[data-ak=\"customer-avatar\"]", "attribute": "src" }
+  ],
+  "postcondition": { "type": "always" },
+  "recovery": { "retries": 0, "useSelectorMemory": false, "useAltInteraction": false, "allowReload": false, "allowHealer": false },
+  "timeoutMs": 5000,
+  "maxFailures": 1
+}
+```
+
+### Example — Trigger-only (pure D3 widget, no DOM template to clone)
+
+```json
+{
+  "kind": "INJECT_MOCK_DATA",
+  "description": "Seed revenue chart with mock data",
+  "groupName": "revenue-chart",
+  "inputSelector": "[data-ak-fill-input=\"revenue-chart\"]",
+  "triggerSelector": "[data-ak-fill-trigger=\"revenue-chart\"]",
+  "postcondition": { "type": "always" },
+  "recovery": { "retries": 0, "useSelectorMemory": false, "useAltInteraction": false, "allowReload": false, "allowHealer": false },
+  "timeoutMs": 5000,
+  "maxFailures": 1
+}
+```
+
+## REMOVE_ELEMENT
+
+Remove all elements matching a CSS selector. **Non-blocking.**
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `selector` | string | yes | CSS selector — every match is removed |
+
+**Can:** Strip empty-state illustrations, debug banners, "powered by" footers, or any visual noise that would distract from the screenshot.
+**Cannot:** Remove an element from a parent that re-renders it via React state — the next render will recreate it.
+
+**Soft-failure semantics:** Throws if the selector matches zero elements. The runner converts the throw into `status: "skipped"`.
+
+```json
+{ "kind": "REMOVE_ELEMENT", "description": "Remove empty-state illustration", "selector": "[data-ak=\"empty-state\"]", "postcondition": { "type": "always" }, "recovery": { "retries": 0, "useSelectorMemory": false, "useAltInteraction": false, "allowReload": false, "allowHealer": false }, "timeoutMs": 3000, "maxFailures": 1 }
+```
+
+## SET_ATTRIBUTE
+
+Set an attribute on the first matching element. **Non-blocking.**
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `selector` | string | yes | CSS selector of the target element (first match only) |
+| `attribute` | string | yes | Attribute name (e.g. `"src"`, `"href"`, `"data-state"`) |
+| `value` | string | yes | Attribute value |
+
+**Can:** Swap an `<img src>`, change a `data-*` flag to trigger CSS state, set `aria-*` for a11y previews, or override `href` on a link.
+**Cannot:** Trigger React state updates — only the DOM attribute changes. Replace `style` reliably (prefer setting a `class` or `data-*` and letting CSS handle the visual).
+
+**Soft-failure semantics:** Throws if the selector is unmatched. The runner converts the throw into `status: "skipped"`.
+
+```json
+{ "kind": "SET_ATTRIBUTE", "description": "Override hero image src", "selector": "[data-ak=\"hero-image\"]", "attribute": "src", "value": "https://picsum.photos/1200/600", "postcondition": { "type": "always" }, "recovery": { "retries": 0, "useSelectorMemory": false, "useAltInteraction": false, "allowReload": false, "allowHealer": false }, "timeoutMs": 3000, "maxFailures": 1 }
+```