autokap 1.9.10 → 2.0.1

package/dist/opcode-runner.d.ts

@@ -52,11 +52,20 @@ export interface RunOptions {
     dryRun?: boolean;
 }
 export interface ProgressEvent {
-    type: 'variant_start' | 'variant_end' | 'opcode_start' | 'opcode_end' | 'recovery' | 'breaker_trip' | 'upload_start' | 'upload_end';
+    type: 'variant_start' | 'variant_end' | 'opcode_start' | 'opcode_end' | 'recovery' | 'breaker_trip' | 'upload_start' | 'upload_end' | 'tts_progress';
     variantId: string;
     opcodeIndex?: number;
+    /** Total opcode count in the variant program (set on opcode_start). */
+    opcodeTotal?: number;
     opcodeKind?: string;
     status?: OpcodeResultStatus;
     message: string;
+    /** tts_progress only: 'synthesizing' | 'uploading' | 'done'. */
+    stage?: string;
+    /** tts_progress only: 1-based segment index and total. */
+    index?: number;
+    total?: number;
+    /** tts_progress only: the SLEEP anchor / step id being synthesized. */
+    stepId?: string;
 }
 export declare function executeProgram(program: ExecutionProgram, createAdapter: (variant: VariantSpec) => Promise<RuntimeAdapter>, options?: RunOptions): Promise<RunResult>;

package/dist/opcode-runner.js

@@ -318,6 +318,7 @@ async function executeVariant(program, variant, createAdapter, recoveryChain, te
                 type: 'opcode_start',
                 variantId: variant.id,
                 opcodeIndex: i,
+                opcodeTotal: program.steps.length,
                 opcodeKind: opcode.kind,
                 message: opcode.description,
             });

package/dist/program-signing.d.ts

@@ -277,13 +277,17 @@ export declare const SignedExecutionProgramEnvelopeSchema: z.ZodObject<{
             stepId: z.ZodOptional<z.ZodString>;
             kind: z.ZodLiteral<"ASSERT_SURFACE">;
         }, z.core.$strict>, z.ZodObject<{
-            selector: z.ZodString;
+            selector: z.ZodOptional<z.ZodString>;
             target: z.ZodOptional<z.ZodObject<{
                 text: z.ZodOptional<z.ZodString>;
+                textByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 role: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
+                labelByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 near: z.ZodOptional<z.ZodString>;
+                nearByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 placeholder: z.ZodOptional<z.ZodString>;
+                placeholderByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 exact: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
             button: z.ZodOptional<z.ZodEnum<{
@@ -322,13 +326,17 @@ export declare const SignedExecutionProgramEnvelopeSchema: z.ZodObject<{
             stepId: z.ZodOptional<z.ZodString>;
             kind: z.ZodLiteral<"CLICK">;
         }, z.core.$strict>, z.ZodObject<{
-            selector: z.ZodString;
+            selector: z.ZodOptional<z.ZodString>;
             target: z.ZodOptional<z.ZodObject<{
                 text: z.ZodOptional<z.ZodString>;
+                textByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 role: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
+                labelByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 near: z.ZodOptional<z.ZodString>;
+                nearByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 placeholder: z.ZodOptional<z.ZodString>;
+                placeholderByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 exact: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
             text: z.ZodString;
@@ -400,10 +408,14 @@ export declare const SignedExecutionProgramEnvelopeSchema: z.ZodObject<{
             selector: z.ZodOptional<z.ZodString>;
             target: z.ZodOptional<z.ZodObject<{
                 text: z.ZodOptional<z.ZodString>;
+                textByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 role: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
+                labelByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 near: z.ZodOptional<z.ZodString>;
+                nearByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 placeholder: z.ZodOptional<z.ZodString>;
+                placeholderByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 exact: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
             state: z.ZodEnum<{
@@ -579,10 +591,14 @@ export declare const SignedExecutionProgramEnvelopeSchema: z.ZodObject<{
             targetSelector: z.ZodOptional<z.ZodString>;
             target: z.ZodOptional<z.ZodObject<{
                 text: z.ZodOptional<z.ZodString>;
+                textByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 role: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
+                labelByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 near: z.ZodOptional<z.ZodString>;
+                nearByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 placeholder: z.ZodOptional<z.ZodString>;
+                placeholderByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 exact: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
             description: z.ZodString;
@@ -722,13 +738,17 @@ export declare const SignedExecutionProgramEnvelopeSchema: z.ZodObject<{
             stepId: z.ZodOptional<z.ZodString>;
             kind: z.ZodLiteral<"END_CLIP">;
         }, z.core.$strict>, z.ZodObject<{
-            selector: z.ZodString;
+            selector: z.ZodOptional<z.ZodString>;
             target: z.ZodOptional<z.ZodObject<{
                 text: z.ZodOptional<z.ZodString>;
+                textByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 role: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
+                labelByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 near: z.ZodOptional<z.ZodString>;
+                nearByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 placeholder: z.ZodOptional<z.ZodString>;
+                placeholderByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 exact: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
             fingerprint: z.ZodOptional<z.ZodString>;
@@ -763,13 +783,17 @@ export declare const SignedExecutionProgramEnvelopeSchema: z.ZodObject<{
             stepId: z.ZodOptional<z.ZodString>;
             kind: z.ZodLiteral<"HOVER">;
         }, z.core.$strict>, z.ZodObject<{
-            selector: z.ZodString;
+            selector: z.ZodOptional<z.ZodString>;
             target: z.ZodOptional<z.ZodObject<{
                 text: z.ZodOptional<z.ZodString>;
+                textByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 role: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
+                labelByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 near: z.ZodOptional<z.ZodString>;
+                nearByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 placeholder: z.ZodOptional<z.ZodString>;
+                placeholderByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 exact: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
             optionLabel: z.ZodOptional<z.ZodString>;
@@ -807,13 +831,17 @@ export declare const SignedExecutionProgramEnvelopeSchema: z.ZodObject<{
             stepId: z.ZodOptional<z.ZodString>;
             kind: z.ZodLiteral<"SELECT_OPTION">;
         }, z.core.$strict>, z.ZodObject<{
-            selector: z.ZodString;
+            selector: z.ZodOptional<z.ZodString>;
             target: z.ZodOptional<z.ZodObject<{
                 text: z.ZodOptional<z.ZodString>;
+                textByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 role: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
+                labelByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 near: z.ZodOptional<z.ZodString>;
+                nearByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 placeholder: z.ZodOptional<z.ZodString>;
+                placeholderByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 exact: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
             checked: z.ZodBoolean;
@@ -849,13 +877,17 @@ export declare const SignedExecutionProgramEnvelopeSchema: z.ZodObject<{
             stepId: z.ZodOptional<z.ZodString>;
             kind: z.ZodLiteral<"CHECK">;
         }, z.core.$strict>, z.ZodObject<{
-            selector: z.ZodString;
+            selector: z.ZodOptional<z.ZodString>;
             target: z.ZodOptional<z.ZodObject<{
                 text: z.ZodOptional<z.ZodString>;
+                textByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 role: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
+                labelByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 near: z.ZodOptional<z.ZodString>;
+                nearByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 placeholder: z.ZodOptional<z.ZodString>;
+                placeholderByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 exact: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
             fingerprint: z.ZodOptional<z.ZodString>;
@@ -890,13 +922,17 @@ export declare const SignedExecutionProgramEnvelopeSchema: z.ZodObject<{
             stepId: z.ZodOptional<z.ZodString>;
             kind: z.ZodLiteral<"DOUBLE_CLICK">;
         }, z.core.$strict>, z.ZodObject<{
-            selector: z.ZodString;
+            selector: z.ZodOptional<z.ZodString>;
             target: z.ZodOptional<z.ZodObject<{
                 text: z.ZodOptional<z.ZodString>;
+                textByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 role: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
+                labelByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 near: z.ZodOptional<z.ZodString>;
+                nearByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 placeholder: z.ZodOptional<z.ZodString>;
+                placeholderByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 exact: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
             fingerprint: z.ZodOptional<z.ZodString>;
@@ -904,10 +940,14 @@ export declare const SignedExecutionProgramEnvelopeSchema: z.ZodObject<{
             toSelector: z.ZodOptional<z.ZodString>;
             toTarget: z.ZodOptional<z.ZodObject<{
                 text: z.ZodOptional<z.ZodString>;
+                textByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 role: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
+                labelByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 near: z.ZodOptional<z.ZodString>;
+                nearByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 placeholder: z.ZodOptional<z.ZodString>;
+                placeholderByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 exact: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
             toSelectorAlternates: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/recovery-chain.js

@@ -8,7 +8,7 @@
  * 4. Targeted reload (reload page and retry)
  * 5. LLM Healer (last resort)
  */
-import { resolveSelector } from './selector-resolver.js';
+import { resolveSelector, resolveSelectorByFuzzyText, semanticTargetFuzzyText, } from './selector-resolver.js';
 import { evaluatePostcondition, evaluatePostconditionWithProgress } from './postcondition.js';
 import { LLMHealer } from './llm-healer.js';
 import { serializeAKTree } from './ak-tree.js';
@@ -41,7 +41,7 @@ export class RecoveryChainImpl {
                 return result;
         }
         // Strategy 2: Selector memory + alternate selectors
-        if (recovery.useSelectorMemory && hasSelector(failedOpcode)) {
+        if (recovery.useSelectorMemory && (hasSelector(failedOpcode) || hasSemanticTarget(failedOpcode))) {
             logger.debug(`[recovery ${opcodeIndex}] strategy 2 (selector memory)`);
             const result = await trySelectorAlternatives(failedOpcode, opcodeIndex, adapter, this.selectorMemory, this.credentials, options.currentVariant);
             logger.debug(`[recovery ${opcodeIndex}] strategy 2 → recovered=${result.recovered}, reason=${result.reason}`);
@@ -49,7 +49,7 @@ export class RecoveryChainImpl {
                 return result;
         }
         // Strategy 3: Alternative interaction methods
-        if (recovery.useAltInteraction && hasSelector(failedOpcode)) {
+        if (recovery.useAltInteraction && (hasSelector(failedOpcode) || hasSemanticTarget(failedOpcode))) {
             logger.debug(`[recovery ${opcodeIndex}] strategy 3 (alt interaction: keyboard, js_dispatch, coords)`);
             const result = await tryAltInteraction(failedOpcode, adapter, this.credentials);
             logger.debug(`[recovery ${opcodeIndex}] strategy 3 → recovered=${result.recovered}, reason=${result.reason}`);
@@ -114,14 +114,14 @@ async function retryOpcode(opcode, adapter, maxRetries, remainingTimeMs, current
 }
 // ── Strategy 2: Selector memory ─────────────────────────────────────
 async function trySelectorAlternatives(opcode, opcodeIndex, adapter, selectorMemory, credentials, currentVariant) {
-    if (!hasSelector(opcode)) {
-        return { recovered: false, reason: 'opcode has no selector' };
+    if (!hasSelector(opcode) && !hasSemanticTarget(opcode)) {
+        return { recovered: false, reason: 'opcode has no selector or target' };
     }
     const selectorOpcode = opcode;
-    const primarySelector = selectorOpcode.selector ?? '';
-    const stepSignature = `${opcode.kind}:${primarySelector}`;
+    const stepSignature = buildStepSignature(opcode);
     const resolved = await resolveSelector(adapter, {
-        primary: primarySelector,
+        primary: selectorOpcode.selector,
+        target: selectorOpcode.target,
         fingerprint: selectorOpcode.fingerprint,
         alternates: selectorOpcode.selectorAlternates,
         selectorMemory,
@@ -150,11 +150,26 @@ async function trySelectorAlternatives(opcode, opcodeIndex, adapter, selectorMem
 }
 // ── Strategy 3: Alternative interaction ─────────────────────────────
 async function tryAltInteraction(opcode, adapter, _credentials) {
-    if (opcode.kind !== 'CLICK' || !opcode.selector) {
-        return { recovered: false, reason: 'alt interaction only for CLICK opcodes with selectors' };
+    if (opcode.kind !== 'CLICK') {
+        return { recovered: false, reason: 'alt interaction only for CLICK opcodes' };
     }
     const clickOpcode = opcode;
-    const sel = clickOpcode.selector;
+    let sel = clickOpcode.selector;
+    if (!sel && clickOpcode.target) {
+        // Target-only opcode: resolve a concrete selector from the AKTree using
+        // the target's text/label so the alternative interaction methods have
+        // something to act on.
+        try {
+            const tree = await adapter.getAKTree();
+            sel = resolveSelectorByFuzzyText(tree, semanticTargetFuzzyText(clickOpcode.target)) ?? undefined;
+        }
+        catch {
+            // fall through to the guard below
+        }
+    }
+    if (!sel) {
+        return { recovered: false, reason: 'alt interaction needs a selector or a target resolvable in the AKTree' };
+    }
     const methods = [
         { name: 'keyboard', options: { useKeyboard: true } },
         { name: 'js_dispatch', options: { useJsDispatch: true } },
@@ -291,6 +306,30 @@ async function tryHealer(failedOpcode, opcodeIndex, adapter, healer, programStep
 function hasSelector(opcode) {
     return 'selector' in opcode && typeof opcode.selector === 'string' && !!opcode.selector;
 }
+function hasSemanticTarget(opcode) {
+    return 'target' in opcode && Boolean(opcode.target);
+}
+/**
+ * Stable signature for selector-memory lookups. Selector-based opcodes keep
+ * the legacy `KIND:selector` form; target-only opcodes derive a signature
+ * from the semantic descriptor so memory survives across runs.
+ */
+function buildStepSignature(opcode) {
+    const { selector, target } = opcode;
+    if (selector)
+        return `${opcode.kind}:${selector}`;
+    if (target) {
+        const name = target.label
+            ?? target.text
+            ?? target.placeholder
+            ?? Object.values(target.labelByLocale ?? {})[0]
+            ?? Object.values(target.textByLocale ?? {})[0]
+            ?? Object.values(target.placeholderByLocale ?? {})[0]
+            ?? '';
+        return `${opcode.kind}:target:${target.role ?? ''}/${name}`;
+    }
+    return `${opcode.kind}:`;
+}
 async function executeRawAction(opcode, adapter, currentVariant, credentials, suppressPageReloads = false) {
     const result = await executeOpcodeCoreAction(opcode, adapter, {
         currentVariant,
@@ -302,7 +341,7 @@ async function executeRawAction(opcode, adapter, currentVariant, credentials, su
     }
 }
 async function executeHealerPatchedAction(opcode, adapter, interactionMode, currentVariant, credentials, suppressPageReloads = false) {
-    if (opcode.kind === 'CLICK' && interactionMode && interactionMode !== 'default') {
+    if (opcode.kind === 'CLICK' && opcode.selector && interactionMode && interactionMode !== 'default') {
         const options = interactionMode === 'keyboard'
             ? { useKeyboard: true }
             : interactionMode === 'js_dispatch'

package/dist/selector-resolver.d.ts

@@ -7,15 +7,18 @@
  * 3. Selector memory candidates (from Supabase)
  * 4. Fuzzy text match on AKTree nodes
  */
-import type { RuntimeAdapter } from './execution-types.js';
+import type { AKTree } from './types.js';
+import type { RuntimeAdapter, SemanticTarget } from './execution-types.js';
 export interface ResolvedSelector {
     selector: string;
-    strategy: 'primary' | 'fingerprint' | 'memory' | 'fuzzy_text' | 'alternate';
+    strategy: 'primary' | 'fingerprint' | 'memory' | 'fuzzy_text' | 'alternate' | 'target_text';
     confidence: 'high' | 'medium' | 'low';
 }
 export interface SelectorResolverOptions {
-    /** Primary selector from the compiled opcode */
-    primary: string;
+    /** Primary selector from the compiled opcode. Absent for target-only opcodes. */
+    primary?: string;
+    /** Semantic target from the compiled opcode (for text-based AKTree matching) */
+    target?: SemanticTarget;
     /** AKTree fingerprint for fuzzy matching */
     fingerprint?: string;
     /** Alternative selectors from the compiled opcode */
@@ -32,3 +35,15 @@ export interface SelectorResolverOptions {
  * Returns the first working selector, or null if nothing matches.
  */
 export declare function resolveSelector(adapter: RuntimeAdapter, options: SelectorResolverOptions): Promise<ResolvedSelector | null>;
+/**
+ * Flattens a SemanticTarget into the text used for AKTree fuzzy matching:
+ * base label/text/placeholder plus every locale variant. Returns '' when the
+ * target carries no text at all (e.g. role-only).
+ */
+export declare function semanticTargetFuzzyText(target: SemanticTarget): string;
+/**
+ * Resolves a CSS selector for a visible interactive AKTree node matching the
+ * given text. Used by recovery strategies that need a concrete selector for a
+ * target-only opcode (e.g. coordinate clicks).
+ */
+export declare function resolveSelectorByFuzzyText(tree: AKTree, text: string): string | null;

package/dist/selector-resolver.js

@@ -14,7 +14,7 @@
 export async function resolveSelector(adapter, options) {
     const tree = await adapter.getAKTree();
     // 1. Try primary selector
-    if (await selectorExists(adapter, options.primary)) {
+    if (options.primary && await selectorExists(adapter, options.primary)) {
         return { selector: options.primary, strategy: 'primary', confidence: 'high' };
     }
     // 2. Try alternate selectors
@@ -32,7 +32,17 @@ export async function resolveSelector(adapter, options) {
             return { selector: match, strategy: 'fingerprint', confidence: 'medium' };
         }
     }
-    // 4. Try selector memory
+    // 4. Try the semantic target's text/label against the AKTree
+    if (options.target) {
+        const targetText = semanticTargetFuzzyText(options.target);
+        if (targetText) {
+            const match = findNodeByFuzzyText(tree, targetText);
+            if (match) {
+                return { selector: match, strategy: 'target_text', confidence: 'medium' };
+            }
+        }
+    }
+    // 5. Try selector memory
     if (options.selectorMemory && options.stepSignature) {
         const candidates = options.selectorMemory[options.stepSignature];
         if (candidates) {
@@ -43,7 +53,7 @@ export async function resolveSelector(adapter, options) {
             }
         }
     }
-    // 5. Try fuzzy text match
+    // 6. Try fuzzy text match on the opcode description
     if (options.description) {
         const match = findNodeByFuzzyText(tree, options.description);
         if (match) {
@@ -52,6 +62,32 @@ export async function resolveSelector(adapter, options) {
     }
     return null;
 }
+/**
+ * Flattens a SemanticTarget into the text used for AKTree fuzzy matching:
+ * base label/text/placeholder plus every locale variant. Returns '' when the
+ * target carries no text at all (e.g. role-only).
+ */
+export function semanticTargetFuzzyText(target) {
+    const parts = [
+        target.label,
+        target.text,
+        target.placeholder,
+        ...Object.values(target.labelByLocale ?? {}),
+        ...Object.values(target.textByLocale ?? {}),
+        ...Object.values(target.placeholderByLocale ?? {}),
+    ].filter((value) => Boolean(value && value.trim()));
+    return parts.join(' ');
+}
+/**
+ * Resolves a CSS selector for a visible interactive AKTree node matching the
+ * given text. Used by recovery strategies that need a concrete selector for a
+ * target-only opcode (e.g. coordinate clicks).
+ */
+export function resolveSelectorByFuzzyText(tree, text) {
+    if (!text.trim())
+        return null;
+    return findNodeByFuzzyText(tree, text);
+}
 // ── Helpers ─────────────────────────────────────────────────────────
 async function selectorExists(adapter, selector) {
     try {

package/dist/semantic-resolver.d.ts

@@ -25,6 +25,8 @@ export interface ResolveOptions {
     target?: SemanticTarget;
     /** Fallback selectors */
     selectorAlternates?: string[];
+    /** Active variant locale used to resolve the target's `*ByLocale` maps */
+    locale?: string;
     /** Timeout for visibility check (ms). Default: 3000 */
     timeoutMs?: number;
 }
@@ -33,3 +35,9 @@ export interface ResolveOptions {
  * Returns the first visible locator found, or null if nothing matches.
  */
 export declare function resolveTarget(page: Page, options: ResolveOptions): Promise<ResolvedTarget | null>;
+/**
+ * Projects a SemanticTarget onto a single locale: each `*ByLocale` map is
+ * collapsed into its base field. Lookup order: exact locale tag → primary
+ * language subtag → base field → first non-empty map value.
+ */
+export declare function localizeSemanticTarget(target: SemanticTarget, locale?: string): SemanticTarget;

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

@@ -296,13 +296,17 @@ export declare const VideoIngestPayloadSchema: z.ZodObject<{
             stepId: z.ZodOptional<z.ZodString>;
             kind: z.ZodLiteral<"ASSERT_SURFACE">;
         }, z.core.$strict>, z.ZodObject<{
-            selector: z.ZodString;
+            selector: z.ZodOptional<z.ZodString>;
             target: z.ZodOptional<z.ZodObject<{
                 text: z.ZodOptional<z.ZodString>;
+                textByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 role: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
+                labelByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 near: z.ZodOptional<z.ZodString>;
+                nearByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 placeholder: z.ZodOptional<z.ZodString>;
+                placeholderByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 exact: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
             button: z.ZodOptional<z.ZodEnum<{
@@ -341,13 +345,17 @@ export declare const VideoIngestPayloadSchema: z.ZodObject<{
             stepId: z.ZodOptional<z.ZodString>;
             kind: z.ZodLiteral<"CLICK">;
         }, z.core.$strict>, z.ZodObject<{
-            selector: z.ZodString;
+            selector: z.ZodOptional<z.ZodString>;
             target: z.ZodOptional<z.ZodObject<{
                 text: z.ZodOptional<z.ZodString>;
+                textByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 role: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
+                labelByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 near: z.ZodOptional<z.ZodString>;
+                nearByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 placeholder: z.ZodOptional<z.ZodString>;
+                placeholderByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 exact: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
             text: z.ZodString;
@@ -419,10 +427,14 @@ export declare const VideoIngestPayloadSchema: z.ZodObject<{
             selector: z.ZodOptional<z.ZodString>;
             target: z.ZodOptional<z.ZodObject<{
                 text: z.ZodOptional<z.ZodString>;
+                textByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 role: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
+                labelByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 near: z.ZodOptional<z.ZodString>;
+                nearByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 placeholder: z.ZodOptional<z.ZodString>;
+                placeholderByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 exact: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
             state: z.ZodEnum<{
@@ -598,10 +610,14 @@ export declare const VideoIngestPayloadSchema: z.ZodObject<{
             targetSelector: z.ZodOptional<z.ZodString>;
             target: z.ZodOptional<z.ZodObject<{
                 text: z.ZodOptional<z.ZodString>;
+                textByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 role: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
+                labelByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 near: z.ZodOptional<z.ZodString>;
+                nearByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 placeholder: z.ZodOptional<z.ZodString>;
+                placeholderByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 exact: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
             description: z.ZodString;
@@ -741,13 +757,17 @@ export declare const VideoIngestPayloadSchema: z.ZodObject<{
             stepId: z.ZodOptional<z.ZodString>;
             kind: z.ZodLiteral<"END_CLIP">;
         }, z.core.$strict>, z.ZodObject<{
-            selector: z.ZodString;
+            selector: z.ZodOptional<z.ZodString>;
             target: z.ZodOptional<z.ZodObject<{
                 text: z.ZodOptional<z.ZodString>;
+                textByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 role: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
+                labelByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 near: z.ZodOptional<z.ZodString>;
+                nearByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 placeholder: z.ZodOptional<z.ZodString>;
+                placeholderByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 exact: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
             fingerprint: z.ZodOptional<z.ZodString>;
@@ -782,13 +802,17 @@ export declare const VideoIngestPayloadSchema: z.ZodObject<{
             stepId: z.ZodOptional<z.ZodString>;
             kind: z.ZodLiteral<"HOVER">;
         }, z.core.$strict>, z.ZodObject<{
-            selector: z.ZodString;
+            selector: z.ZodOptional<z.ZodString>;
             target: z.ZodOptional<z.ZodObject<{
                 text: z.ZodOptional<z.ZodString>;
+                textByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 role: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
+                labelByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 near: z.ZodOptional<z.ZodString>;
+                nearByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 placeholder: z.ZodOptional<z.ZodString>;
+                placeholderByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 exact: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
             optionLabel: z.ZodOptional<z.ZodString>;
@@ -826,13 +850,17 @@ export declare const VideoIngestPayloadSchema: z.ZodObject<{
             stepId: z.ZodOptional<z.ZodString>;
             kind: z.ZodLiteral<"SELECT_OPTION">;
         }, z.core.$strict>, z.ZodObject<{
-            selector: z.ZodString;
+            selector: z.ZodOptional<z.ZodString>;
             target: z.ZodOptional<z.ZodObject<{
                 text: z.ZodOptional<z.ZodString>;
+                textByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 role: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
+                labelByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 near: z.ZodOptional<z.ZodString>;
+                nearByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 placeholder: z.ZodOptional<z.ZodString>;
+                placeholderByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 exact: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
             checked: z.ZodBoolean;
@@ -868,13 +896,17 @@ export declare const VideoIngestPayloadSchema: z.ZodObject<{
             stepId: z.ZodOptional<z.ZodString>;
             kind: z.ZodLiteral<"CHECK">;
         }, z.core.$strict>, z.ZodObject<{
-            selector: z.ZodString;
+            selector: z.ZodOptional<z.ZodString>;
             target: z.ZodOptional<z.ZodObject<{
                 text: z.ZodOptional<z.ZodString>;
+                textByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 role: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
+                labelByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 near: z.ZodOptional<z.ZodString>;
+                nearByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 placeholder: z.ZodOptional<z.ZodString>;
+                placeholderByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 exact: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
             fingerprint: z.ZodOptional<z.ZodString>;
@@ -909,13 +941,17 @@ export declare const VideoIngestPayloadSchema: z.ZodObject<{
             stepId: z.ZodOptional<z.ZodString>;
             kind: z.ZodLiteral<"DOUBLE_CLICK">;
         }, z.core.$strict>, z.ZodObject<{
-            selector: z.ZodString;
+            selector: z.ZodOptional<z.ZodString>;
             target: z.ZodOptional<z.ZodObject<{
                 text: z.ZodOptional<z.ZodString>;
+                textByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 role: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
+                labelByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 near: z.ZodOptional<z.ZodString>;
+                nearByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 placeholder: z.ZodOptional<z.ZodString>;
+                placeholderByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 exact: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
             fingerprint: z.ZodOptional<z.ZodString>;
@@ -923,10 +959,14 @@ export declare const VideoIngestPayloadSchema: z.ZodObject<{
             toSelector: z.ZodOptional<z.ZodString>;
             toTarget: z.ZodOptional<z.ZodObject<{
                 text: z.ZodOptional<z.ZodString>;
+                textByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 role: z.ZodOptional<z.ZodString>;
                 label: z.ZodOptional<z.ZodString>;
+                labelByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 near: z.ZodOptional<z.ZodString>;
+                nearByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 placeholder: z.ZodOptional<z.ZodString>;
+                placeholderByLocale: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 exact: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strict>>;
             toSelectorAlternates: z.ZodOptional<z.ZodArray<z.ZodString>>;