autokap 1.0.6 → 1.0.8

package/dist/execution-types.d.ts

@@ -0,0 +1,886 @@
+/**
+ * Capture Agent — IR Types
+ *
+ * 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';
+/** Sentinel value that resolves to the current variant's locale or theme at runtime */
+export declare const VARIANT_PLACEHOLDER: "$variant";
+export declare const OPCODE_KINDS: readonly ["NAVIGATE", "DISMISS_OVERLAYS", "ASSERT_ROUTE", "ASSERT_SURFACE", "CLICK", "TYPE", "PRESS_KEY", "WAIT_FOR", "SET_LOCALE", "SET_THEME", "SCROLL", "CAPTURE_SCREENSHOT", "CAPTURE_DOM", "CAPTURE_FRAGMENT", "BEGIN_CLIP", "END_CLIP", "HOVER", "SELECT_OPTION", "CHECK", "DOUBLE_CLICK", "CLONE_ELEMENT", "INJECT_MOCK_DATA", "REMOVE_ELEMENT", "SET_ATTRIBUTE"];
+export type OpcodeKind = (typeof OPCODE_KINDS)[number];
+/**
+ * Soft opcodes are non-blocking — if their action or postcondition fails at
+ * runtime, the runner returns `status: 'skipped'` instead of aborting the
+ * variant. The circuit breaker is not ticked. Used by mock data injection so
+ * a missing template selector logs a warning and the capture proceeds.
+ */
+export declare const SOFT_OPCODE_KINDS: ReadonlySet<OpcodeKind>;
+export declare function isSoftOpcodeKind(kind: OpcodeKind): boolean;
+/** A single fillable field within a mock data group's templated item. */
+export interface MockDataSlot {
+    /** Stable identifier referenced by INJECT_MOCK_DATA.slotMappings[].slot */
+    name: string;
+    /** Human-readable description shown in the Phase 3 editing UI */
+    description: string;
+    /**
+     * Optional hint about how the Phase 3 editing UI should render the input.
+     * Canonical values recognized by the dashboard editor are `text`,
+     * `number`, `image`, `color`, `date`, `url`. Any other string is allowed
+     * and the editor falls back to a plain text input.
+     */
+    hint?: string;
+}
+/** One concrete row of values, keyed by slot name. */
+export type MockDataRow = Record<string, string>;
+/** A mock data group describes one fillable area of the UI (e.g. a table body). */
+export interface MockDataGroup {
+    /** Stable identifier referenced by INJECT_MOCK_DATA.groupName. Kebab-case. */
+    name: string;
+    /** Human-readable description for the editing UI */
+    description: string;
+    /** Schema of each item in this group */
+    slots: MockDataSlot[];
+    /** Default seed values — one row per item the user wants rendered */
+    defaultValues: MockDataRow[];
+    /**
+     * If true, after cloning the runtime removes every existing child of the
+     * container that is not a clone. Used to wipe placeholders / real items so
+     * the mocked dataset is the sole content. Default: false.
+     */
+    replaceExisting?: boolean;
+}
+export type PostconditionType = 'route_matches' | 'element_visible' | 'element_absent' | 'text_contains' | 'overlay_dismissed' | 'screenshot_stable' | 'any_change' | 'always';
+export interface PostconditionSpec {
+    type: PostconditionType;
+    /** URL pattern (glob) for route_matches */
+    pattern?: string;
+    /** CSS/AKTree selector for element_visible, element_absent, text_contains */
+    selector?: string;
+    /** Expected text substring for text_contains */
+    text?: string;
+    /** Pixel diff threshold (0-1) for screenshot_stable. Default: 0.01 */
+    threshold?: number;
+    /** Max wait time (ms) for the postcondition to become true. Default: 5000 */
+    waitMs?: number;
+}
+/**
+ * Describes an element semantically, without requiring a CSS selector.
+ * The runtime resolves the target using Playwright semantic locators
+ * (getByRole, getByText, getByLabel) then falls back to AKTree fuzzy matching.
+ *
+ * At least one of text/role/label should be provided.
+ */
+export interface SemanticTarget {
+    /** Visible text content of the element (exact or partial match) */
+    text?: string;
+    /** ARIA role: "button", "link", "textbox", "checkbox", "tab", "menuitem", etc. */
+    role?: string;
+    /** Accessible name: aria-label, associated label text, or title attribute */
+    label?: string;
+    /** Nearby text or heading for disambiguation (e.g. "in the pricing section") */
+    near?: string;
+    /** Placeholder text (for inputs) */
+    placeholder?: string;
+    /** Whether the text match should be exact. Default: false (substring match) */
+    exact?: boolean;
+}
+export interface RecoveryPolicy {
+    /** Number of deterministic retries before escalating. Default: 2 */
+    retries: number;
+    /** Try selector memory alternatives. Default: true */
+    useSelectorMemory: boolean;
+    /** Try alternative interaction methods (keyboard, JS, coords). Default: true */
+    useAltInteraction: boolean;
+    /** Reload the page and retry from last checkpoint. Default: false */
+    allowReload: boolean;
+    /** Allow LLM healer as last resort. Default: true */
+    allowHealer: boolean;
+}
+export declare const DEFAULT_RECOVERY_POLICY: RecoveryPolicy;
+interface OpcodeBase {
+    kind: OpcodeKind;
+    /** Human-readable description of what this opcode does */
+    description: string;
+    postcondition: PostconditionSpec;
+    recovery: RecoveryPolicy;
+    /** Max time (ms) for this opcode to complete, including recovery. Default: 15000 */
+    timeoutMs: number;
+    /** Max recovery attempts before this opcode is considered failed. Default: 3 */
+    maxFailures: number;
+}
+export interface NavigateOpcode extends OpcodeBase {
+    kind: 'NAVIGATE';
+    url: string;
+}
+export interface DismissOverlaysOpcode extends OpcodeBase {
+    kind: 'DISMISS_OVERLAYS';
+}
+export interface AssertRouteOpcode extends OpcodeBase {
+    kind: 'ASSERT_ROUTE';
+    /** URL pattern (glob or regex) to assert */
+    urlPattern: string;
+}
+export interface AssertSurfaceOpcode extends OpcodeBase {
+    kind: 'ASSERT_SURFACE';
+    /** Selector(s) that must be visible */
+    selectors: string[];
+    /** If true, ALL selectors must match. If false, ANY one suffices. Default: true */
+    matchAll: boolean;
+}
+export interface ClickOpcode extends OpcodeBase {
+    kind: 'CLICK';
+    /** CSS selector — typically a data-ak attribute set by the user's AI assistant */
+    selector: string;
+    /** Semantic target fallback — used by recovery chain when selector fails */
+    target?: SemanticTarget;
+    /** Mouse button: 'right' for context menus, 'middle' for new tab. Default: left click */
+    button?: 'right' | 'middle';
+    /** AKTree fingerprint for fuzzy matching fallback */
+    fingerprint?: string;
+    /** Alternative selectors to try in order */
+    selectorAlternates?: string[];
+}
+export interface TypeOpcode extends OpcodeBase {
+    kind: 'TYPE';
+    /** CSS selector — typically a data-ak attribute set by the user's AI assistant */
+    selector: string;
+    /** Semantic target fallback */
+    target?: SemanticTarget;
+    text: string;
+    /** Locale-keyed text overrides. When the current variant has a matching locale key,
+     *  that value is used instead of `text`. Supports credential placeholders. */
+    textByLocale?: Record<string, string>;
+    /** Clear existing value before typing. Default: true */
+    clearFirst: boolean;
+    fingerprint?: string;
+    selectorAlternates?: string[];
+}
+export interface PressKeyOpcode extends OpcodeBase {
+    kind: 'PRESS_KEY';
+    key: string;
+}
+export interface WaitForOpcode extends OpcodeBase {
+    kind: 'WAIT_FOR';
+    /** CSS selector to wait for — required unless target is provided */
+    selector?: string;
+    /** Semantic target fallback — used when selector is not available */
+    target?: SemanticTarget;
+    /** 'visible' = element visible in viewport, 'attached' = exists in DOM. Default: 'visible' */
+    state: 'visible' | 'attached';
+}
+export interface SetLocaleOpcode extends OpcodeBase {
+    kind: 'SET_LOCALE';
+    /** Target BCP-47 locale (e.g. "fr", "en-US") */
+    locale: string;
+    /** Strategy to set locale */
+    method: 'browser_context' | 'ui_interaction' | 'storage';
+    /** Selector to interact with (for ui_interaction) */
+    selector?: string;
+    /** Storage key/value pairs to set (for storage method) */
+    storageHints?: {
+        storage: 'localStorage' | 'sessionStorage' | 'cookie';
+        key: string;
+        value: string;
+    }[];
+}
+export interface SetThemeOpcode extends OpcodeBase {
+    kind: 'SET_THEME';
+    theme: 'light' | 'dark' | '$variant';
+    method: 'color_scheme' | 'ui_interaction' | 'storage';
+    selector?: string;
+    storageHints?: {
+        storage: 'localStorage' | 'sessionStorage' | 'cookie';
+        key: string;
+        value: string;
+    }[];
+}
+export interface ScrollOpcode extends OpcodeBase {
+    kind: 'SCROLL';
+    direction: 'up' | 'down' | 'left' | 'right';
+    /** Pixels to scroll. Default: viewport height */
+    amount?: number;
+    /** Optional target selector to scroll into view */
+    targetSelector?: string;
+    /** Semantic target to scroll into view (used when targetSelector is absent) */
+    target?: SemanticTarget;
+}
+export interface CaptureScreenshotOpcode extends OpcodeBase {
+    kind: 'CAPTURE_SCREENSHOT';
+    /** Stable preset capture identifier (page id / element name) for Studio and dev links */
+    captureId?: string;
+    /** Human-readable preset capture name */
+    captureName?: string;
+    /** Optional element selector for element-level capture */
+    elementSelector?: string;
+}
+/**
+ * Capture the full serialized DOM of the current page as an interactive demo
+ * state. Produces an HTML artifact (no PNG) that the demo player can replay
+ * client-side. Used by AUT-121 Interactive Demos preset type.
+ *
+ * The runner runs `smartWaitForStability` before serializing, sanitizes the
+ * HTML (strips `<script>`, `on*` attributes, third-party iframes), and pushes
+ * an `ArtifactResult` with `mediaMode: 'dom'`.
+ */
+export interface CaptureDomOpcode extends OpcodeBase {
+    kind: 'CAPTURE_DOM';
+    /**
+     * Stable identifier for this state (kebab-case, e.g. `dashboard`,
+     * `dashboard-chat-open`). Referenced by the interaction script's
+     * `state` / `target` fields and used as the storage filename.
+     */
+    stateName: string;
+    /**
+     * Optional CSS selector of the subtree to serialize instead of the full
+     * page. Use this when the interactive demo should focus on one specific
+     * surface (modal, dashboard shell, pricing calculator, editor panel, ...).
+     *
+     * The adapter keeps the current `<head>` and `<body>` attributes so global
+     * styles/themes still apply, but rewrites the body to contain only the
+     * selected branch (including its ancestor shell) and sizes the captured
+     * viewport to that subtree's bounding box.
+     */
+    selector?: string;
+}
+/**
+ * Capture a single subtree of the current page as a reusable fragment
+ * (modal, popover, dropdown, tooltip, sheet, etc.). Phase 5 of AUT-121.
+ *
+ * Fragments are mounted/unmounted by the player on top of a base state via
+ * `show_fragment` / `hide_fragment` actions, so a single capture can power
+ * many local interactions without swapping the entire DOM.
+ *
+ * The runner optionally clicks `triggerSelector` first (typically a hidden
+ * `data-ak-fragment-trigger="..."` button exposed by the user's app for
+ * fragments that aren't reachable through visible UI), waits for `selector`
+ * to be present, then serializes the matching subtree's `outerHTML`.
+ */
+export interface CaptureFragmentOpcode extends OpcodeBase {
+    kind: 'CAPTURE_FRAGMENT';
+    /**
+     * Stable kebab-case identifier for the fragment, unique within
+     * `parentState`. Mirrors `data-ak-fragment="<name>"` in the source code.
+     *
+     * Multiple `CAPTURE_FRAGMENT` opcodes can target the same `fragmentName`
+     * with different `variantName` values to capture multiple versions of
+     * the same subtree (e.g. "default" / "purple" / "text-bottom"). The
+     * player swaps variants in place at runtime via
+     * `api.fragment.show(name, variantName)`.
+     */
+    fragmentName: string;
+    /**
+     * Variant identifier for this capture, kebab-case. Defaults to `'default'`.
+     * Use distinct variant names when capturing the same fragment in different
+     * states (e.g. with a different background applied). The player can swap
+     * between variants in place without losing scroll/focus/sibling layout.
+     */
+    variantName?: string;
+    /**
+     * The captured base state (`CAPTURE_DOM.stateName`) this fragment lives
+     * on top of. Used to scope the fragment in storage and at runtime.
+     */
+    parentState: string;
+    /** CSS selector of the subtree wrapper. Typically `[data-ak-fragment="<name>"]`. */
+    selector: string;
+    /**
+     * Optional hidden trigger button selector (mirrors the mock data
+     * pattern). If provided, the runner clicks it via `clickHidden()` before
+     * waiting for `selector` to appear — useful for fragments that aren't
+     * reachable via existing UI buttons.
+     */
+    triggerSelector?: string;
+    /**
+     * How the player should mount the fragment back onto the base state at
+     * runtime. Default: `inline` (mount in place of the original wrapper).
+     *  - `overlay`: position absolute at the top-left of the iframe body
+     *  - `inline`: mount in place of the original wrapper
+     *  - `portal:<target>`: mount inside a `[data-ak-mount-target="<target>"]` element
+     */
+    mountStrategy?: 'overlay' | 'inline' | string;
+    /**
+     * Optional override for the base-state element where the fragment
+     * should be mounted (CSS selector). When omitted, the player uses the
+     * fragment's source location (the element matching `selector` in the
+     * captured base state).
+     */
+    mountTargetSelector?: string;
+}
+export interface BeginClipOpcode extends OpcodeBase {
+    kind: 'BEGIN_CLIP';
+    /** Stable preset clip identifier for Studio and dev links */
+    clipId?: string;
+    /** Human-readable preset clip name */
+    clipName?: string;
+}
+export interface EndClipOpcode extends OpcodeBase {
+    kind: 'END_CLIP';
+    /** Stable preset clip identifier for Studio and dev links */
+    clipId?: string;
+    /** Human-readable preset clip name */
+    clipName?: string;
+}
+export interface HoverOpcode extends OpcodeBase {
+    kind: 'HOVER';
+    selector: string;
+    target?: SemanticTarget;
+    fingerprint?: string;
+    selectorAlternates?: string[];
+}
+export interface SelectOptionOpcode extends OpcodeBase {
+    kind: 'SELECT_OPTION';
+    selector: string;
+    target?: SemanticTarget;
+    /** Select by visible label text */
+    optionLabel?: string;
+    /** Select by option value attribute */
+    optionValue?: string;
+    /** Select by zero-based index */
+    optionIndex?: number;
+    fingerprint?: string;
+    selectorAlternates?: string[];
+}
+export interface CheckOpcode extends OpcodeBase {
+    kind: 'CHECK';
+    selector: string;
+    target?: SemanticTarget;
+    /** Desired state: true = checked, false = unchecked */
+    checked: boolean;
+    fingerprint?: string;
+    selectorAlternates?: string[];
+}
+export interface DoubleClickOpcode extends OpcodeBase {
+    kind: 'DOUBLE_CLICK';
+    selector: string;
+    target?: SemanticTarget;
+    fingerprint?: string;
+    selectorAlternates?: string[];
+}
+/**
+ * Duplicate a template element N times into a container. **Soft / non-blocking.**
+ * If the source or container selector is missing, the opcode is skipped and
+ * the variant continues without aborting.
+ */
+export interface CloneElementOpcode extends OpcodeBase {
+    kind: 'CLONE_ELEMENT';
+    /** CSS selector of the element to clone */
+    sourceSelector: string;
+    /** CSS selector of the container that receives the clones */
+    containerSelector: string;
+    /** Number of clones to produce (1-500) */
+    count: number;
+    /** If true, the source template is removed after cloning. Default: false */
+    removeSource?: boolean;
+}
+/**
+ * Orchestrator opcode that fills a fillable area with mock data. Carries
+ * fields for **both** delivery mechanisms simultaneously, and the runtime
+ * applies whichever the opcode declares — typically both:
+ *
+ * - **Clone** (DOM cloning): looks up the group, clones a template element
+ *   once per `defaultValues` row, writes each slot value into the cloned
+ *   descendants. Provides instant visual feedback even before the app
+ *   re-renders. Works for tables, lists, card grids — anything whose children
+ *   are pure markup the runtime can mutate.
+ *
+ * - **Trigger** (hidden button + input): writes the JSON-encoded
+ *   `defaultValues` into a hidden input the user's app exposed, then clicks a
+ *   hidden trigger button. The user's `onClick` handler reads the input value
+ *   and re-renders its own component with the seed data. Survives React
+ *   re-renders that would otherwise clobber the cloned DOM, and works for
+ *   programmatic widgets (Chart.js, Recharts, D3, maps) where the runtime
+ *   can't mutate the DOM directly.
+ *
+ * The two mechanisms are complementary, not mutually exclusive: an opcode
+ * should typically declare BOTH so the runtime applies clone first (instant
+ * paint) and then trigger (state-driven, survives re-renders). At least one
+ * mechanism's required fields must be present.
+ *
+ * **Soft / non-blocking** — if neither mechanism produces a successful
+ * application, the opcode is skipped and the variant continues with
+ * `mockDataGroupResults[groupName] = 'skipped'`. If at least one succeeds,
+ * the group is recorded as `'applied'`.
+ */
+export interface InjectMockDataOpcode extends OpcodeBase {
+    kind: 'INJECT_MOCK_DATA';
+    /** Name of the MockDataGroup in ExecutionProgram.mockDataGroups */
+    groupName: string;
+    /** CSS selector of the container that holds the cloned items */
+    containerSelector?: string;
+    /** CSS selector of the template element. Default: first child of container. */
+    templateSelector?: string;
+    /** Override the row count. If absent, uses defaultValues.length. */
+    count?: number;
+    /** If true, the template element is removed after cloning (empty-state replacement) */
+    removeTemplate?: boolean;
+    /** Maps each slot name to a target inside a cloned item */
+    slotMappings?: Array<{
+        /** Slot name from the MockDataGroup */
+        slot: string;
+        /** CSS selector RELATIVE to the cloned item */
+        selector: string;
+        /** If present, set this attribute. If absent, set textContent. */
+        attribute?: string;
+    }>;
+    /**
+     * CSS selector of the hidden input that receives the JSON-encoded
+     * `defaultValues` array. The user's app reads this value when the trigger
+     * fires. Use a unique `data-ak-fill-input="<group-name>"` attribute.
+     */
+    inputSelector?: string;
+    /**
+     * CSS selector of the hidden button that the runner clicks programmatically
+     * (via `element.click()`, bypassing visibility checks). The button's
+     * `onClick` handler reads the input value and re-renders the widget. Use a
+     * unique `data-ak-fill-trigger="<group-name>"` attribute.
+     */
+    triggerSelector?: string;
+}
+/** Remove all elements matching a selector. **Soft / non-blocking.** */
+export interface RemoveElementOpcode extends OpcodeBase {
+    kind: 'REMOVE_ELEMENT';
+    /** CSS selector — all matches are removed */
+    selector: string;
+}
+/** Set an attribute on the first matching element. **Soft / non-blocking.** */
+export interface SetAttributeOpcode extends OpcodeBase {
+    kind: 'SET_ATTRIBUTE';
+    /** CSS selector of the target element (first match only) */
+    selector: string;
+    /** Attribute name (e.g. "src", "href", "data-state") */
+    attribute: string;
+    /** Attribute value */
+    value: string;
+}
+export type ExecutionOpcode = NavigateOpcode | DismissOverlaysOpcode | AssertRouteOpcode | AssertSurfaceOpcode | ClickOpcode | TypeOpcode | PressKeyOpcode | WaitForOpcode | SetLocaleOpcode | SetThemeOpcode | ScrollOpcode | CaptureScreenshotOpcode | CaptureDomOpcode | CaptureFragmentOpcode | BeginClipOpcode | EndClipOpcode | HoverOpcode | SelectOptionOpcode | CheckOpcode | DoubleClickOpcode | CloneElementOpcode | InjectMockDataOpcode | RemoveElementOpcode | SetAttributeOpcode;
+export interface VariantSpec {
+    id: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    deviceScaleFactor?: number;
+    locale?: string;
+    theme?: 'light' | 'dark';
+    /** Stable target identifier from the preset config */
+    targetId?: string;
+    /** Human-readable target label from the preset config */
+    targetLabel?: string;
+    /** Device frame label (e.g. "iPhone 15 Pro") for mockup rendering */
+    deviceFrame?: string;
+}
+export interface PreconditionSpec {
+    /**
+     * Auth bootstrap is auto-detected from what is configured on the preset:
+     * - If `cookies` / `storageState` / `sessionStorage` are present, the runtime
+     *   injects them into the browser context before any opcode runs.
+     * - If `credentials` (email/password) are present, they are substituted
+     *   into `{{email}}` / `{{password}}` placeholders inside the program's
+     *   `TYPE` opcodes (the program performs the UI login itself).
+     * - If neither is present, the run is anonymous.
+     *
+     * Both mechanisms can coexist (e.g. seed cookies AND fall back to UI login).
+     *
+     * Note: the AI assistant must HARDCODE the login URL directly in the
+     * `NAVIGATE` opcode. The legacy `{{loginUrl}}` placeholder is deprecated
+     * because the field is optional and substituting an empty string crashes
+     * Playwright with a confusing "Cannot navigate to invalid URL" error.
+     */
+    /** Credentials reference ID (resolved at runtime from CLI config) */
+    credentialsId?: string;
+    /**
+     * Plain login credentials (decrypted server-side and bridged into the
+     * program at fetch time). Used to substitute `{{email}}` / `{{password}}`
+     * placeholders in TYPE opcodes. **Do not use `{{loginUrl}}` in new
+     * programs** — it's kept for backwards compat with older presets but
+     * deprecated; the agent should hardcode the login URL in NAVIGATE.
+     */
+    credentials?: {
+        email?: string;
+        password?: string;
+        /** @deprecated Hardcode the login URL directly in NAVIGATE opcodes instead. */
+        loginUrl?: string;
+    };
+    /** Pre-loaded storage state */
+    storageState?: BrowserStorageState;
+    sessionStorage?: BrowserSessionStorageState;
+    /** Cookies to set before execution */
+    cookies?: Array<{
+        name: string;
+        value: string;
+        domain: string;
+        path?: string;
+    }>;
+}
+export declare const MEDIA_MODES: readonly ["screenshot", "clip", "dom"];
+export type MediaMode = (typeof MEDIA_MODES)[number];
+export interface ArtifactSpec {
+    mediaMode: MediaMode;
+    /** Output format preferences */
+    format?: {
+        /** For clips: 'gif' | 'mp4' | 'both'. Default: 'gif' */
+        clipFormat?: 'gif' | 'mp4' | 'both';
+        /** For screenshots: 'png' | 'jpeg'. Default: 'png' */
+        screenshotFormat?: 'png' | 'jpeg';
+    };
+    /** Cursor style for clip recordings. Default: 'minimal'. */
+    cursorTheme?: VideoCursorTheme;
+    /** Max clip duration in seconds. Clips are trimmed if they exceed this. Default: 8. */
+    maxClipDurationSec?: number;
+    /** Whether to apply device frame mockup. Default: false */
+    applyMockup?: boolean;
+    /** Whether to add status bar. Default: false */
+    applyStatusBar?: boolean;
+    /** Options specific to DOM captures (Interactive Demos) */
+    domOptions?: {
+        /** Whether to sanitize the DOM (strip <script>, on*, third-party iframes). Default: true */
+        sanitize?: boolean;
+    };
+}
+export interface ExecutionProgram {
+    presetId: string;
+    programVersion: number;
+    mediaMode: MediaMode;
+    baseUrl: string;
+    /** Server-resolved concurrency cap for this run, derived from the owner's plan. */
+    maxParallelCaptures?: number;
+    variants: VariantSpec[];
+    preconditions: PreconditionSpec;
+    steps: ExecutionOpcode[];
+    artifactPlan: ArtifactSpec;
+    /** Global output scale (device pixel ratio). Applied to all variants that don't set their own deviceScaleFactor. */
+    outputScale?: number;
+    /** Hash of the source preset content, used to detect recompilation needs */
+    compileFingerprint: string;
+    /** Canonical fingerprint of langs+themes at compilation (e.g. "langs:en,fr|themes:dark,light"). Used for staleness detection. */
+    variantFingerprint?: string;
+    /** ISO timestamp of compilation */
+    compiledAt: string;
+    /** Model used for compilation */
+    compiledWith?: string;
+    /**
+     * Mock data groups available to INJECT_MOCK_DATA opcodes.
+     * Compiled from PresetConfig.mockDataInjection.groups by the server.
+     */
+    mockDataGroups?: MockDataGroup[];
+}
+export interface CircuitBreakerConfig {
+    /** Max recovery attempts per opcode. Default: 3 */
+    maxPerOpcode: number;
+    /** Max total failures per page navigation. Default: 5 */
+    maxPerPage: number;
+    /** Max total failures per run. Default: 10 */
+    maxPerRun: number;
+}
+export declare const DEFAULT_CIRCUIT_BREAKER: CircuitBreakerConfig;
+export interface HealerPatch {
+    /** Index of the opcode in the program that was patched */
+    opcodeIndex: number;
+    /** The original opcode before patching */
+    originalOpcode: ExecutionOpcode;
+    /** The replacement opcode(s). Usually 1, max 3. */
+    replacementOpcodes: ExecutionOpcode[];
+    /** Why the healer made this change */
+    reason: string;
+    /** Timestamp */
+    patchedAt: string;
+}
+export type OpcodeResultStatus = 'ok' | 'recovered' | 'skipped' | 'failed';
+export interface OpcodeResult {
+    opcodeIndex: number;
+    kind: OpcodeKind;
+    status: OpcodeResultStatus;
+    /** Time taken for this opcode (ms) */
+    durationMs: number;
+    /** Number of recovery attempts used */
+    recoveryAttempts: number;
+    /** Recovery strategy that succeeded, if any */
+    recoveryStrategy?: 'retry' | 'selector_memory' | 'alt_interaction' | 'reload' | 'healer';
+    /** Error message if failed */
+    error?: string;
+}
+export interface VariantResult {
+    variantId: string;
+    success: boolean;
+    opcodeResults: OpcodeResult[];
+    /** Total duration for this variant (ms) */
+    durationMs: number;
+    /** Artifact buffers produced */
+    artifacts: ArtifactResult[];
+    error?: string;
+}
+export interface ArtifactResult {
+    mediaMode: MediaMode;
+    buffer: Buffer;
+    mimeType: string;
+    durationMs?: number;
+    trimStartMs?: number;
+    /** For screenshots: viewport dimensions of the capture */
+    dimensions?: {
+        width: number;
+        height: number;
+    };
+    /** Generated alt text for accessibility */
+    altText?: string;
+    /** Final URL at the time the artifact was produced */
+    captureUrl?: string;
+    /** Step index that produced the artifact */
+    stepIndex?: number;
+    /** Human-readable label for the artifact */
+    stepDescription?: string;
+    /** Variant metadata used by persistence and gallery views */
+    variantId?: string;
+    /** Stable preset capture identifier for screenshots */
+    captureId?: string;
+    /** Human-readable preset capture name for screenshots */
+    captureName?: string;
+    /** Stable preset clip identifier for clips */
+    clipId?: string;
+    /** Human-readable preset clip name for clips */
+    clipName?: string;
+    captureType?: 'fullpage' | 'element';
+    elementSelector?: string;
+    /** Favicon extracted from the captured page */
+    tabIconData?: Buffer;
+    tabIconMimeType?: string;
+    /** Stable identifier of the captured demo state (kebab-case, from CaptureDomOpcode.stateName) */
+    stateName?: string;
+    /** Sanitized HTML body (also stored as buffer for upload) */
+    domHtml?: string;
+    /** Asset URLs referenced by the captured DOM (img, source, link rel="stylesheet"). Phase 3 will resolve these via CAS. */
+    domAssetUrls?: string[];
+    /** Byte size of the sanitized HTML, for telemetry */
+    domHtmlBytes?: number;
+    /** PNG thumbnail screenshot taken at the time of DOM capture */
+    domThumbnailBuffer?: Buffer;
+    /** Stable kebab-case identifier of the captured fragment, from CaptureFragmentOpcode.fragmentName */
+    fragmentName?: string;
+    /**
+     * Variant of this fragment capture (Phase 8). Same `fragmentName` can be
+     * captured under multiple variants — e.g. "default", "purple-bg",
+     * "text-bottom" — and the player swaps between them in place. Defaults to
+     * `'default'` when the opcode does not specify one.
+     */
+    fragmentVariantName?: string;
+    /** Parent base state this fragment belongs to */
+    parentStateName?: string;
+    /** Where the player should mount the fragment at runtime */
+    mountStrategy?: string;
+    /** Optional override for the base-state element to mount into (CSS selector) */
+    mountTargetSelector?: string;
+}
+export type LLMStepType = 'capture_verification' | 'alt_text_generation' | 'healer_invocation';
+export interface LLMStepUsage {
+    stepType: LLMStepType;
+    generationId: string | null;
+    model: string;
+    promptTokens: number;
+    completionTokens: number;
+}
+export interface RunTelemetry {
+    /** Total LLM calls (compilation excluded) */
+    llmCallCount: number;
+    /** Total LLM cost in EUR */
+    llmCostEur: number;
+    /** Detailed per-call LLM usage for cost logging */
+    llmStepUsages: LLMStepUsage[];
+    /** Total opcodes executed across all variants */
+    totalOpcodes: number;
+    /** Opcodes that needed recovery */
+    recoveredOpcodes: number;
+    /** Opcodes that failed even after recovery */
+    failedOpcodes: number;
+    /** Soft opcodes that were skipped (e.g. mock data injection failures) */
+    skippedOpcodes: number;
+    /** Number of healer invocations */
+    healerInvocations: number;
+    /** Circuit breaker trips */
+    circuitBreakerTrips: number;
+    /** Per-group mock data application result */
+    mockDataGroupResults?: Record<string, 'applied' | 'skipped'>;
+}
+export interface RunResult {
+    programId: string;
+    success: boolean;
+    variantResults: VariantResult[];
+    telemetry: RunTelemetry;
+    /** Healer patches accumulated during the run. Only propagate to server if success=true */
+    healerPatches: HealerPatch[];
+    /** Total run duration (ms) */
+    totalDurationMs: number;
+    error?: string;
+}
+export interface WaitCondition {
+    selector: string;
+    state: 'visible' | 'attached';
+    timeoutMs: number;
+}
+export interface ClickOptions {
+    /** Force click even if element is covered */
+    force?: boolean;
+    /** Use keyboard (Tab + Enter) instead of mouse */
+    useKeyboard?: boolean;
+    /** Use JS dispatch instead of Playwright click */
+    useJsDispatch?: boolean;
+    /** Click by coordinates from bounding box */
+    coordinates?: {
+        x: number;
+        y: number;
+    };
+    /** Mouse button. Default: 'left' */
+    button?: 'left' | 'right' | 'middle';
+}
+export interface RecordingOptions {
+    mediaMode: 'clip';
+}
+export interface RecordingResult {
+    buffer: Buffer;
+    durationMs: number;
+    mimeType: string;
+    trimStartMs?: number;
+}
+export interface RuntimeAdapter {
+    navigate(url: string): Promise<void>;
+    getCurrentUrl(): Promise<string>;
+    getAKTree(): Promise<AKTree>;
+    getPageSignals(): Promise<VideoPageSignals>;
+    click(selector: string, options?: ClickOptions): Promise<void>;
+    type(selector: string, text: string, clearFirst?: boolean): Promise<void>;
+    pressKey(key: string): Promise<void>;
+    scroll(direction: 'up' | 'down' | 'left' | 'right', amount?: number): Promise<void>;
+    scrollIntoView(selector: string): Promise<void>;
+    waitFor(condition: WaitCondition): Promise<boolean>;
+    dismissOverlays(): Promise<{
+        dismissed: boolean;
+        method: string | null;
+    }>;
+    takeScreenshot(): Promise<Buffer>;
+    takeElementScreenshot?(selector: string): Promise<Buffer>;
+    takeCleanScreenshot(): Promise<Buffer>;
+    /**
+     * Serialize the current page DOM into a sanitized HTML string for the
+     * Interactive Demo pipeline. Returns the HTML and the asset URLs found
+     * during sanitization (img/source/link). Optional — adapters that don't
+     * implement this cannot run `CAPTURE_DOM` opcodes.
+     */
+    serializeDom?(selector?: string): Promise<{
+        html: string;
+        assetUrls: string[];
+        viewport: {
+            width: number;
+            height: number;
+        };
+        capturedAt: string;
+    }>;
+    /**
+     * Serialize a single subtree of the page (matched by `selector`) as a
+     * sanitized fragment HTML string. Optional — adapters that don't
+     * implement this cannot run `CAPTURE_FRAGMENT` opcodes. Phase 5 of
+     * AUT-121 Interactive Demos.
+     */
+    serializeFragment?(selector: string): Promise<{
+        html: string;
+        assetUrls: string[];
+        capturedAt: string;
+    }>;
+    beginRecording(options: RecordingOptions): Promise<void>;
+    endRecording(): Promise<RecordingResult>;
+    setLocale(locale: string): Promise<void>;
+    setColorScheme(scheme: 'light' | 'dark'): Promise<void>;
+    reloadPage?(): Promise<void>;
+    writeStorageHint?(params: {
+        storage: 'localStorage' | 'sessionStorage' | 'cookie';
+        key: string;
+        value: string;
+        kind: 'locale' | 'theme';
+    }): Promise<boolean>;
+    /** Extract the page's favicon as a buffer. Returns null if unavailable. */
+    extractFavicon?(): Promise<{
+        buffer: Buffer;
+        mimeType: string;
+    } | null>;
+    close(): Promise<void>;
+    /** Click an element by semantic target. Falls back to selector if target not found. */
+    clickByTarget?(opts: {
+        selector?: string;
+        target?: SemanticTarget;
+        selectorAlternates?: string[];
+    }): Promise<void>;
+    /** Type into an element by semantic target. */
+    typeByTarget?(opts: {
+        selector?: string;
+        target?: SemanticTarget;
+        selectorAlternates?: string[];
+    }, text: string, clearFirst?: boolean): Promise<void>;
+    /** Wait for an element by semantic target. */
+    waitForTarget?(opts: {
+        selector?: string;
+        target?: SemanticTarget;
+        selectorAlternates?: string[];
+    }, timeoutMs?: number): Promise<boolean>;
+    /** Scroll an element into view by semantic target. */
+    scrollIntoViewByTarget?(opts: {
+        selector?: string;
+        target?: SemanticTarget;
+        selectorAlternates?: string[];
+    }): Promise<void>;
+    hover?(selector: string): Promise<void>;
+    hoverByTarget?(opts: {
+        selector?: string;
+        target?: SemanticTarget;
+        selectorAlternates?: string[];
+    }): Promise<void>;
+    selectOption?(selector: string, option: {
+        label?: string;
+        value?: string;
+        index?: number;
+    }): Promise<void>;
+    check?(selector: string, checked: boolean): Promise<void>;
+    doubleClick?(selector: string): Promise<void>;
+    /** Clone an element N times into a container. Throws if either selector misses. */
+    cloneElement?(opts: {
+        sourceSelector: string;
+        containerSelector: string;
+        count: number;
+        removeSource?: boolean;
+    }): Promise<{
+        clonedCount: number;
+    }>;
+    /** Set an attribute on the first matching element. Throws if the selector misses. */
+    setAttribute?(opts: {
+        selector: string;
+        attribute: string;
+        value: string;
+    }): Promise<void>;
+    /** Set the textContent of the first matching element. Throws if the selector misses. */
+    setTextContent?(opts: {
+        selector: string;
+        text: string;
+    }): Promise<void>;
+    /** Remove all matching elements. Throws only if no elements match. */
+    removeElement?(opts: {
+        selector: string;
+    }): Promise<{
+        removedCount: number;
+    }>;
+    /**
+     * Set the `value` of an input/textarea/select via the React-aware native
+     * setter, then dispatch `input` and `change` events so React (and other
+     * controlled-component frameworks) detect the change. Throws if the selector
+     * misses. Used by INJECT_MOCK_DATA strategy='trigger'.
+     */
+    setInputValue?(opts: {
+        selector: string;
+        value: string;
+    }): Promise<void>;
+    /**
+     * Click an element via JavaScript (`element.click()`), bypassing visibility
+     * and enabled checks. Useful for clicking hidden trigger buttons that
+     * `display:none` or `pointer-events:none` would block. Throws if the
+     * selector misses. Used by INJECT_MOCK_DATA strategy='trigger'.
+     */
+    clickHidden?(opts: {
+        selector: string;
+    }): Promise<void>;
+}
+export {};