autokap 1.9.10 → 2.0.1

package/dist/execution-schema.js

@@ -132,34 +132,59 @@ const AssertSurfaceOpcodeSchema = z.object({
         path: ['postcondition'],
     });
 });
+/** Locale-keyed strings for multilingual semantic targets ("en", "fr", "fr-FR" …) */
+const localeStringMapSchema = z.record(z.string().min(1).max(16), z.string().min(1));
+const hasLocaleEntries = (map) => Boolean(map && Object.values(map).some((value) => value.trim().length > 0));
 const SemanticTargetSchema = z.object({
     text: z.string().optional(),
+    textByLocale: localeStringMapSchema.optional(),
     role: z.string().optional(),
     label: z.string().optional(),
+    labelByLocale: localeStringMapSchema.optional(),
     near: z.string().optional(),
+    nearByLocale: localeStringMapSchema.optional(),
     placeholder: z.string().optional(),
+    placeholderByLocale: localeStringMapSchema.optional(),
     exact: z.boolean().optional(),
-}).strict().refine((value) => Boolean(value.text || value.role || value.label || value.near || value.placeholder), 'semantic targets need at least one identifying field');
+}).strict().refine((value) => Boolean(value.text || value.role || value.label || value.near || value.placeholder
+    || hasLocaleEntries(value.textByLocale)
+    || hasLocaleEntries(value.labelByLocale)
+    || hasLocaleEntries(value.nearByLocale)
+    || hasLocaleEntries(value.placeholderByLocale)), 'semantic targets need at least one identifying field');
+/**
+ * Interactive opcodes accept `selector` (an attribute that already exists in
+ * the app) or a semantic `target` — at least one is required. Programs
+ * generated without touching the captured app's code are target-first.
+ */
+const requireSelectorOrTarget = (kind) => (value, ctx) => {
+    if (!value.selector && !value.target) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `${kind} requires either \`selector\` or \`target\``,
+            path: ['selector'],
+        });
+    }
+};
 const ClickOpcodeSchema = z.object({
     kind: z.literal('CLICK'),
     ...opcodeBase,
-    selector: z.string().min(1),
+    selector: z.string().min(1).optional(),
     target: SemanticTargetSchema.optional(),
     button: z.enum(['right', 'middle']).optional(),
     fingerprint: z.string().optional(),
     selectorAlternates: z.array(z.string().min(1)).optional(),
-}).strict();
+}).strict().superRefine(requireSelectorOrTarget('CLICK'));
 const TypeOpcodeSchema = z.object({
     kind: z.literal('TYPE'),
     ...opcodeBase,
-    selector: z.string().min(1),
+    selector: z.string().min(1).optional(),
     target: SemanticTargetSchema.optional(),
     text: z.string(),
     textByLocale: z.record(z.string().min(1), z.string()).optional(),
     clearFirst: z.boolean(),
     fingerprint: z.string().optional(),
     selectorAlternates: z.array(z.string().min(1)).optional(),
-}).strict();
+}).strict().superRefine(requireSelectorOrTarget('TYPE'));
 const PressKeyOpcodeSchema = z.object({
     kind: z.literal('PRESS_KEY'),
     ...opcodeBase,
@@ -298,15 +323,15 @@ const EndClipOpcodeSchema = z.object({
 const HoverOpcodeSchema = z.object({
     kind: z.literal('HOVER'),
     ...opcodeBase,
-    selector: z.string().min(1),
+    selector: z.string().min(1).optional(),
     target: SemanticTargetSchema.optional(),
     fingerprint: z.string().optional(),
     selectorAlternates: z.array(z.string().min(1)).optional(),
-}).strict();
+}).strict().superRefine(requireSelectorOrTarget('HOVER'));
 const SelectOptionOpcodeSchema = z.object({
     kind: z.literal('SELECT_OPTION'),
     ...opcodeBase,
-    selector: z.string().min(1),
+    selector: z.string().min(1).optional(),
     target: SemanticTargetSchema.optional(),
     optionLabel: z.string().optional(),
     optionValue: z.string().optional(),
@@ -314,6 +339,7 @@ const SelectOptionOpcodeSchema = z.object({
     fingerprint: z.string().optional(),
     selectorAlternates: z.array(z.string().min(1)).optional(),
 }).strict().superRefine((value, ctx) => {
+    requireSelectorOrTarget('SELECT_OPTION')(value, ctx);
     if (value.optionLabel === undefined && value.optionValue === undefined && value.optionIndex === undefined) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
@@ -324,24 +350,24 @@ const SelectOptionOpcodeSchema = z.object({
 const CheckOpcodeSchema = z.object({
     kind: z.literal('CHECK'),
     ...opcodeBase,
-    selector: z.string().min(1),
+    selector: z.string().min(1).optional(),
     target: SemanticTargetSchema.optional(),
     checked: z.boolean(),
     fingerprint: z.string().optional(),
     selectorAlternates: z.array(z.string().min(1)).optional(),
-}).strict();
+}).strict().superRefine(requireSelectorOrTarget('CHECK'));
 const DoubleClickOpcodeSchema = z.object({
     kind: z.literal('DOUBLE_CLICK'),
     ...opcodeBase,
-    selector: z.string().min(1),
+    selector: z.string().min(1).optional(),
     target: SemanticTargetSchema.optional(),
     fingerprint: z.string().optional(),
     selectorAlternates: z.array(z.string().min(1)).optional(),
-}).strict();
+}).strict().superRefine(requireSelectorOrTarget('DOUBLE_CLICK'));
 const DragOpcodeSchema = z.object({
     kind: z.literal('DRAG'),
     ...opcodeBase,
-    selector: z.string().min(1),
+    selector: z.string().min(1).optional(),
     target: SemanticTargetSchema.optional(),
     fingerprint: z.string().optional(),
     selectorAlternates: z.array(z.string().min(1)).optional(),
@@ -353,6 +379,7 @@ const DragOpcodeSchema = z.object({
         dy: z.number(),
     }).strict().optional(),
 }).strict().superRefine((value, ctx) => {
+    requireSelectorOrTarget('DRAG')(value, ctx);
     const hasElementDest = Boolean(value.toSelector || value.toTarget);
     const hasOffsetDest = Boolean(value.offset);
     if (!hasElementDest && !hasOffsetDest) {

package/dist/execution-types.d.ts

@@ -71,19 +71,36 @@ export interface PostconditionSpec {
  * 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.
+ * This is the primary targeting mechanism for programs generated without
+ * modifying the captured app's source code: the descriptor is grounded in
+ * what is visible on screen (role, accessible name, text) rather than in a
+ * pre-planted automation attribute.
+ *
+ * At least one of text/role/label (or a locale-keyed variant) should be
+ * provided. For multilingual apps, the `*ByLocale` maps carry the per-locale
+ * strings extracted from the app's i18n catalogs; the runtime picks the value
+ * matching the active variant locale (exact tag, then primary subtag) and
+ * falls back to the base field.
  */
 export interface SemanticTarget {
     /** Visible text content of the element (exact or partial match) */
     text?: string;
+    /** Locale-keyed visible text (BCP-47-ish keys: "en", "fr", "fr-FR") */
+    textByLocale?: Record<string, string>;
     /** ARIA role: "button", "link", "textbox", "checkbox", "tab", "menuitem", etc. */
     role?: string;
     /** Accessible name: aria-label, associated label text, or title attribute */
     label?: string;
+    /** Locale-keyed accessible name */
+    labelByLocale?: Record<string, string>;
     /** Nearby text or heading for disambiguation (e.g. "in the pricing section") */
     near?: string;
+    /** Locale-keyed nearby text */
+    nearByLocale?: Record<string, string>;
     /** Placeholder text (for inputs) */
     placeholder?: string;
+    /** Locale-keyed placeholder text */
+    placeholderByLocale?: Record<string, string>;
     /** Whether the text match should be exact. Default: false (substring match) */
     exact?: boolean;
 }
@@ -139,9 +156,13 @@ export interface AssertSurfaceOpcode extends OpcodeBase {
 }
 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 */
+    /**
+     * CSS selector built from attributes that already exist in the app
+     * (id, data-testid, aria-label, href …). Optional — when absent, `target`
+     * drives resolution. At least one of `selector`/`target` is required.
+     */
+    selector?: string;
+    /** Semantic on-screen target — primary when `selector` is absent, fallback when it fails */
     target?: SemanticTarget;
     /** Mouse button: 'right' for context menus, 'middle' for new tab. Default: left click */
     button?: 'right' | 'middle';
@@ -152,9 +173,9 @@ export interface ClickOpcode extends OpcodeBase {
 }
 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 */
+    /** CSS selector from existing attributes. Optional when `target` is provided. */
+    selector?: string;
+    /** Semantic on-screen target — primary when `selector` is absent, fallback when it fails */
     target?: SemanticTarget;
     text: string;
     /** Locale-keyed text overrides. When the current variant has a matching locale key,
@@ -267,14 +288,16 @@ export interface EndClipOpcode extends OpcodeBase {
 }
 export interface HoverOpcode extends OpcodeBase {
     kind: 'HOVER';
-    selector: string;
+    /** Optional when `target` is provided */
+    selector?: string;
     target?: SemanticTarget;
     fingerprint?: string;
     selectorAlternates?: string[];
 }
 export interface SelectOptionOpcode extends OpcodeBase {
     kind: 'SELECT_OPTION';
-    selector: string;
+    /** Optional when `target` is provided */
+    selector?: string;
     target?: SemanticTarget;
     /** Select by visible label text */
     optionLabel?: string;
@@ -287,7 +310,8 @@ export interface SelectOptionOpcode extends OpcodeBase {
 }
 export interface CheckOpcode extends OpcodeBase {
     kind: 'CHECK';
-    selector: string;
+    /** Optional when `target` is provided */
+    selector?: string;
     target?: SemanticTarget;
     /** Desired state: true = checked, false = unchecked */
     checked: boolean;
@@ -296,7 +320,8 @@ export interface CheckOpcode extends OpcodeBase {
 }
 export interface DoubleClickOpcode extends OpcodeBase {
     kind: 'DOUBLE_CLICK';
-    selector: string;
+    /** Optional when `target` is provided */
+    selector?: string;
     target?: SemanticTarget;
     fingerprint?: string;
     selectorAlternates?: string[];
@@ -312,9 +337,9 @@ export interface DoubleClickOpcode extends OpcodeBase {
  */
 export interface DragOpcode extends OpcodeBase {
     kind: 'DRAG';
-    /** CSS selector of the source element (the one being dragged) */
-    selector: string;
-    /** Semantic fallback for the source element */
+    /** CSS selector of the source element (the one being dragged). Optional when `target` is provided. */
+    selector?: string;
+    /** Semantic target for the source element — primary when `selector` is absent */
     target?: SemanticTarget;
     fingerprint?: string;
     selectorAlternates?: string[];
@@ -906,8 +931,18 @@ export interface ClickByTargetOptions {
     selector?: string;
     target?: SemanticTarget;
     selectorAlternates?: string[];
+    /** Active variant locale, used to resolve the target's `*ByLocale` maps */
+    locale?: string;
     onClick?: (timestampMs: number) => void;
 }
+/** Shared options for the semantic `*ByTarget` adapter methods. */
+export interface TargetResolveOptions {
+    selector?: string;
+    target?: SemanticTarget;
+    selectorAlternates?: string[];
+    /** Active variant locale, used to resolve the target's `*ByLocale` maps */
+    locale?: string;
+}
 export interface MouseActionOptions {
     /** Same semantics as `ClickOptions.onClick` — fires right before the
      *  actual click is dispatched (CHECK / DOUBLE_CLICK). */
@@ -1020,29 +1055,23 @@ export interface RuntimeAdapter {
     /** Click an element by semantic target. Falls back to selector if target not found. */
     clickByTarget?(opts: ClickByTargetOptions): Promise<void>;
     /** Type into an element by semantic target. */
-    typeByTarget?(opts: {
-        selector?: string;
-        target?: SemanticTarget;
-        selectorAlternates?: string[];
-    }, text: string, clearFirst?: boolean, typeOpts?: TypeOptions): Promise<void>;
+    typeByTarget?(opts: TargetResolveOptions, text: string, clearFirst?: boolean, typeOpts?: TypeOptions): Promise<void>;
     /** Wait for an element by semantic target. */
-    waitForTarget?(opts: {
-        selector?: string;
-        target?: SemanticTarget;
-        selectorAlternates?: string[];
-    }, timeoutMs?: number): Promise<boolean>;
+    waitForTarget?(opts: TargetResolveOptions, timeoutMs?: number): Promise<boolean>;
     /** Scroll an element into view by semantic target. */
-    scrollIntoViewByTarget?(opts: {
-        selector?: string;
-        target?: SemanticTarget;
-        selectorAlternates?: string[];
+    scrollIntoViewByTarget?(opts: TargetResolveOptions): Promise<void>;
+    /** Select a dropdown option on an element resolved by semantic target. */
+    selectOptionByTarget?(opts: TargetResolveOptions, option: {
+        label?: string;
+        value?: string;
+        index?: number;
     }): Promise<void>;
+    /** Check/uncheck an element resolved by semantic target. */
+    checkByTarget?(opts: TargetResolveOptions, checked: boolean, mouseOpts?: MouseActionOptions): Promise<void>;
+    /** Double-click an element resolved by semantic target. */
+    doubleClickByTarget?(opts: TargetResolveOptions, mouseOpts?: MouseActionOptions): Promise<void>;
     hover?(selector: string): Promise<void>;
-    hoverByTarget?(opts: {
-        selector?: string;
-        target?: SemanticTarget;
-        selectorAlternates?: string[];
-    }): Promise<void>;
+    hoverByTarget?(opts: TargetResolveOptions): Promise<void>;
     selectOption?(selector: string, option: {
         label?: string;
         value?: string;
@@ -1066,6 +1095,8 @@ export interface RuntimeAdapter {
             dx: number;
             dy: number;
         };
+        /** Active variant locale, used to resolve the targets' `*ByLocale` maps */
+        locale?: string;
     }): Promise<void>;
     /** Clone an element N times into a container. Throws if either selector misses. */
     cloneElement?(opts: {

package/dist/llm-healer.js

@@ -59,7 +59,8 @@ export class LLMHealer {
 }
 function buildHealerPrompt(context) {
     const { failedOpcode, errorMessage, akTreeSerialized, currentUrl, surroundingOpcodes } = context;
-    const selector = hasPatchableSelector(failedOpcode) ? failedOpcode.selector : null;
+    const selector = isPatchableOpcode(failedOpcode) ? failedOpcode.selector ?? null : null;
+    const target = isPatchableOpcode(failedOpcode) ? failedOpcode.target ?? null : null;
     const surroundingDesc = surroundingOpcodes
         .map((op, i) => `  ${i + 1}. ${op.kind}: ${sanitizePromptText(op.description)}`)
         .join('\n');
@@ -68,7 +69,8 @@ function buildHealerPrompt(context) {
 ## Failed Opcode
 Kind: ${failedOpcode.kind}
 Description: ${sanitizePromptText(failedOpcode.description)}
-Selector: ${selector ?? '<unsupported>'}
+Selector: ${selector ?? '<none — this opcode targets the element semantically>'}
+Semantic target: ${target ? sanitizePromptText(JSON.stringify(target)) : '<none>'}
 
 ## Error
 <<<ERROR>>>
@@ -90,15 +92,16 @@ ${surroundingDesc}
 1. You MUST NOT emit opcodes or navigation targets.
 2. You may only return a selector patch for the existing opcode.
 3. You may optionally return a bounded interaction mode: default, keyboard, js_dispatch, or coordinates.
-4. Use selectors you can actually see in the AKTree above.
-5. If the opcode kind is unsupported or there is no reliable selector, return cannotHeal=true.
+4. Use selectors you can actually see in the AKTree above — existing ids, data-testid, aria-label, name, href, or text. Do NOT assume the app contains automation attributes (data-ak) unless they appear in the AKTree.
+5. When the failed opcode has a semantic target, pick the element that matches its intent (role, accessible name, text — in any language the page may be displayed in).
+6. If the opcode kind is unsupported or there is no reliable selector, return cannotHeal=true.
 
 ## Response Format
 Respond with a JSON object:
 {
   "cannotHeal": false,
   "reason": "explanation of what you changed",
-  "selector": "[data-ak='submit']",
+  "selector": "#submit-button",
   "selectorAlternates": ["button[type='submit']"],
   "interactionMode": "default"
 }
@@ -155,19 +158,28 @@ function parseHealerResponse(response) {
         return null;
     }
 }
-function hasPatchableSelector(opcode) {
-    return ((opcode.kind === 'CLICK'
-        || opcode.kind === 'TYPE'
-        || opcode.kind === 'WAIT_FOR'
-        || opcode.kind === 'HOVER'
-        || opcode.kind === 'SELECT_OPTION'
-        || opcode.kind === 'CHECK'
-        || opcode.kind === 'DOUBLE_CLICK')
-        && typeof opcode.selector === 'string'
-        && opcode.selector.trim().length > 0);
+/**
+ * An opcode the healer can patch: a supported kind that carries a selector
+ * OR a semantic target. Target-only opcodes are patched by ADDING a concrete
+ * selector resolved from the live AKTree (the original target is kept as
+ * fallback on the replacement opcode).
+ */
+function isPatchableOpcode(opcode) {
+    if (opcode.kind !== 'CLICK'
+        && opcode.kind !== 'TYPE'
+        && opcode.kind !== 'WAIT_FOR'
+        && opcode.kind !== 'HOVER'
+        && opcode.kind !== 'SELECT_OPTION'
+        && opcode.kind !== 'CHECK'
+        && opcode.kind !== 'DOUBLE_CLICK') {
+        return false;
+    }
+    const hasSelector = typeof opcode.selector === 'string' && opcode.selector.trim().length > 0;
+    const hasTarget = Boolean(opcode.target);
+    return hasSelector || hasTarget;
 }
 function buildReplacementOpcode(failedOpcode, parsed) {
-    if (!hasPatchableSelector(failedOpcode) || !parsed.selector) {
+    if (!isPatchableOpcode(failedOpcode) || !parsed.selector) {
         return null;
     }
     switch (failedOpcode.kind) {

package/dist/opcode-actions.js

@@ -44,6 +44,20 @@ export function findUnresolvedCredentialPlaceholders(text, credentials) {
     }
     return missing;
 }
+/**
+ * Guard for selector-less opcodes: the schema guarantees a `target` is
+ * present when `selector` is absent, and the adapter must expose the matching
+ * semantic `*ByTarget` method. Throws a clear error instead of letting a
+ * `undefined selector` crash deep inside Playwright.
+ */
+function requireByTargetSupport(kind, target, byTargetMethod) {
+    if (!target) {
+        throw new Error(`${kind} has neither selector nor target`);
+    }
+    if (typeof byTargetMethod !== 'function') {
+        throw new Error(`adapter does not support semantic targets for ${kind}`);
+    }
+}
 export async function executeOpcodeCoreAction(opcode, adapter, context = {}) {
     try {
         switch (opcode.kind) {
@@ -68,18 +82,26 @@ export async function executeOpcodeCoreAction(opcode, adapter, context = {}) {
                 const onClick = (timestampMs) => {
                     clickTimestampsMs.push(timestampMs);
                 };
-                try {
-                    await adapter.click(opcode.selector, { ...(opcode.button ? { button: opcode.button } : {}), onClick });
+                const byTargetOpts = {
+                    selector: opcode.selector,
+                    target: opcode.target,
+                    selectorAlternates: opcode.selectorAlternates,
+                    locale: context.currentVariant?.locale,
+                    onClick,
+                };
+                if (!opcode.selector) {
+                    requireByTargetSupport('CLICK', opcode.target, adapter.clickByTarget);
+                    await adapter.clickByTarget(byTargetOpts);
                 }
-                catch (error) {
-                    if (!opcode.target || !adapter.clickByTarget)
-                        throw error;
-                    await adapter.clickByTarget({
-                        selector: opcode.selector,
-                        target: opcode.target,
-                        selectorAlternates: opcode.selectorAlternates,
-                        onClick,
-                    });
+                else {
+                    try {
+                        await adapter.click(opcode.selector, { ...(opcode.button ? { button: opcode.button } : {}), onClick });
+                    }
+                    catch (error) {
+                        if (!opcode.target || !adapter.clickByTarget)
+                            throw error;
+                        await adapter.clickByTarget(byTargetOpts);
+                    }
                 }
                 return { success: true, clickTimestampsMs };
             }
@@ -92,17 +114,25 @@ export async function executeOpcodeCoreAction(opcode, adapter, context = {}) {
                 const onKeystroke = (timestampMs) => {
                     keystrokeTimestampsMs.push(timestampMs);
                 };
-                try {
-                    await adapter.type(opcode.selector, text, opcode.clearFirst, { onKeystroke });
+                const byTargetOpts = {
+                    selector: opcode.selector,
+                    target: opcode.target,
+                    selectorAlternates: opcode.selectorAlternates,
+                    locale: context.currentVariant?.locale,
+                };
+                if (!opcode.selector) {
+                    requireByTargetSupport('TYPE', opcode.target, adapter.typeByTarget);
+                    await adapter.typeByTarget(byTargetOpts, text, opcode.clearFirst, { onKeystroke });
                 }
-                catch (error) {
-                    if (!opcode.target || !adapter.typeByTarget)
-                        throw error;
-                    await adapter.typeByTarget({
-                        selector: opcode.selector,
-                        target: opcode.target,
-                        selectorAlternates: opcode.selectorAlternates,
-                    }, text, opcode.clearFirst, { onKeystroke });
+                else {
+                    try {
+                        await adapter.type(opcode.selector, text, opcode.clearFirst, { onKeystroke });
+                    }
+                    catch (error) {
+                        if (!opcode.target || !adapter.typeByTarget)
+                            throw error;
+                        await adapter.typeByTarget(byTargetOpts, text, opcode.clearFirst, { onKeystroke });
+                    }
                 }
                 return { success: true, keystrokeTimestampsMs };
             }
@@ -122,7 +152,7 @@ export async function executeOpcodeCoreAction(opcode, adapter, context = {}) {
                     }
                 }
                 else if (opcode.target && adapter.waitForTarget) {
-                    const found = await adapter.waitForTarget({ target: opcode.target }, opcode.timeoutMs);
+                    const found = await adapter.waitForTarget({ target: opcode.target, locale: context.currentVariant?.locale }, opcode.timeoutMs);
                     if (!found) {
                         return { success: false, error: `target "${opcode.target.text ?? opcode.target.role ?? 'unknown'}" not found within timeout` };
                     }
@@ -150,13 +180,24 @@ export async function executeOpcodeCoreAction(opcode, adapter, context = {}) {
                     await adapter.scrollIntoView(opcode.targetSelector);
                 }
                 else if (opcode.target && adapter.scrollIntoViewByTarget) {
-                    await adapter.scrollIntoViewByTarget({ target: opcode.target });
+                    await adapter.scrollIntoViewByTarget({ target: opcode.target, locale: context.currentVariant?.locale });
                 }
                 else {
                     await adapter.scroll(opcode.direction, opcode.amount);
                 }
                 break;
-            case 'HOVER':
+            case 'HOVER': {
+                const byTargetOpts = {
+                    selector: opcode.selector,
+                    target: opcode.target,
+                    selectorAlternates: opcode.selectorAlternates,
+                    locale: context.currentVariant?.locale,
+                };
+                if (!opcode.selector) {
+                    requireByTargetSupport('HOVER', opcode.target, adapter.hoverByTarget);
+                    await adapter.hoverByTarget(byTargetOpts);
+                    break;
+                }
                 if (!adapter.hover)
                     return { success: false, error: 'adapter does not support HOVER' };
                 try {
@@ -165,38 +206,93 @@ export async function executeOpcodeCoreAction(opcode, adapter, context = {}) {
                 catch (error) {
                     if (!opcode.target || !adapter.hoverByTarget)
                         throw error;
-                    await adapter.hoverByTarget({
-                        selector: opcode.selector,
-                        target: opcode.target,
-                        selectorAlternates: opcode.selectorAlternates,
-                    });
+                    await adapter.hoverByTarget(byTargetOpts);
                 }
                 break;
-            case 'SELECT_OPTION':
-                if (!adapter.selectOption)
-                    return { success: false, error: 'adapter does not support SELECT_OPTION' };
-                await adapter.selectOption(opcode.selector, {
+            }
+            case 'SELECT_OPTION': {
+                const option = {
                     label: opcode.optionLabel,
                     value: opcode.optionValue,
                     index: opcode.optionIndex,
-                });
+                };
+                const byTargetOpts = {
+                    selector: opcode.selector,
+                    target: opcode.target,
+                    selectorAlternates: opcode.selectorAlternates,
+                    locale: context.currentVariant?.locale,
+                };
+                if (!opcode.selector) {
+                    requireByTargetSupport('SELECT_OPTION', opcode.target, adapter.selectOptionByTarget);
+                    await adapter.selectOptionByTarget(byTargetOpts, option);
+                    break;
+                }
+                if (!adapter.selectOption)
+                    return { success: false, error: 'adapter does not support SELECT_OPTION' };
+                try {
+                    await adapter.selectOption(opcode.selector, option);
+                }
+                catch (error) {
+                    if (!opcode.target || !adapter.selectOptionByTarget)
+                        throw error;
+                    await adapter.selectOptionByTarget(byTargetOpts, option);
+                }
                 break;
+            }
             case 'CHECK': {
-                if (!adapter.check)
-                    return { success: false, error: 'adapter does not support CHECK' };
                 const clickTimestampsMs = [];
-                await adapter.check(opcode.selector, opcode.checked, {
+                const mouseOpts = {
                     onClick: (timestampMs) => clickTimestampsMs.push(timestampMs),
-                });
+                };
+                const byTargetOpts = {
+                    selector: opcode.selector,
+                    target: opcode.target,
+                    selectorAlternates: opcode.selectorAlternates,
+                    locale: context.currentVariant?.locale,
+                };
+                if (!opcode.selector) {
+                    requireByTargetSupport('CHECK', opcode.target, adapter.checkByTarget);
+                    await adapter.checkByTarget(byTargetOpts, opcode.checked, mouseOpts);
+                    return { success: true, clickTimestampsMs };
+                }
+                if (!adapter.check)
+                    return { success: false, error: 'adapter does not support CHECK' };
+                try {
+                    await adapter.check(opcode.selector, opcode.checked, mouseOpts);
+                }
+                catch (error) {
+                    if (!opcode.target || !adapter.checkByTarget)
+                        throw error;
+                    await adapter.checkByTarget(byTargetOpts, opcode.checked, mouseOpts);
+                }
                 return { success: true, clickTimestampsMs };
             }
             case 'DOUBLE_CLICK': {
-                if (!adapter.doubleClick)
-                    return { success: false, error: 'adapter does not support DOUBLE_CLICK' };
                 const clickTimestampsMs = [];
-                await adapter.doubleClick(opcode.selector, {
+                const mouseOpts = {
                     onClick: (timestampMs) => clickTimestampsMs.push(timestampMs),
-                });
+                };
+                const byTargetOpts = {
+                    selector: opcode.selector,
+                    target: opcode.target,
+                    selectorAlternates: opcode.selectorAlternates,
+                    locale: context.currentVariant?.locale,
+                };
+                if (!opcode.selector) {
+                    requireByTargetSupport('DOUBLE_CLICK', opcode.target, adapter.doubleClickByTarget);
+                    await adapter.doubleClickByTarget(byTargetOpts, mouseOpts);
+                    return { success: true, clickTimestampsMs };
+                }
+                if (!adapter.doubleClick)
+                    return { success: false, error: 'adapter does not support DOUBLE_CLICK' };
+                try {
+                    await adapter.doubleClick(opcode.selector, mouseOpts);
+                }
+                catch (error) {
+                    if (!opcode.target || !adapter.doubleClickByTarget)
+                        throw error;
+                    await adapter.doubleClickByTarget(byTargetOpts, mouseOpts);
+                }
                 return { success: true, clickTimestampsMs };
             }
             case 'DRAG':
@@ -210,6 +306,7 @@ export async function executeOpcodeCoreAction(opcode, adapter, context = {}) {
                     toTarget: opcode.toTarget,
                     toSelectorAlternates: opcode.toSelectorAlternates,
                     offset: opcode.offset,
+                    locale: context.currentVariant?.locale,
                 });
                 break;
             case 'CLONE_ELEMENT':