@applitools/nlp-web-runner 5.14.2 → 5.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -36,7 +36,22 @@ type IfControlFlow = {
36
36
  then?: Instruction[];
37
37
  otherwise?: Instruction[];
38
38
  };
39
- type ControlFlow = SetPreinstructionsControlFlow | DropPreinstructionsControlFlow | TryControlFlow | InitializeScopeControlFlow | IfControlFlow;
39
+ type RepeatLoopControlFlow = {
40
+ type: 'loop';
41
+ instructions: Instruction[];
42
+ times?: NumberExpression;
43
+ condition?: Condition;
44
+ wait?: NumberExpression;
45
+ };
46
+ type ForEachLoopControlFlow = {
47
+ type: 'loop';
48
+ instructions: Instruction[];
49
+ iterable: AnyExpression | ElementDescriptor;
50
+ bindings?: string[];
51
+ wait?: NumberExpression;
52
+ };
53
+ type LoopControlFlow = RepeatLoopControlFlow | ForEachLoopControlFlow;
54
+ type ControlFlow = SetPreinstructionsControlFlow | DropPreinstructionsControlFlow | TryControlFlow | InitializeScopeControlFlow | IfControlFlow | LoopControlFlow;
40
55
  type EmptyAction = {
41
56
  type: 'empty';
42
57
  };
@@ -60,7 +75,7 @@ type SetVariableAction = {
60
75
  type SetValueAction = {
61
76
  type: 'set value';
62
77
  value: StringExpression | NumberExpression | Generator$1 | FileHandle;
63
- element: ElementDescriptor;
78
+ element: ElementDescriptor | ElementReference;
64
79
  };
65
80
  type FetchAction = {
66
81
  type: 'fetch';
@@ -98,32 +113,32 @@ type EvaluateAction = {
98
113
  };
99
114
  type FocusAction = {
100
115
  type: 'focus';
101
- element: ElementDescriptor;
116
+ element: ElementDescriptor | ElementReference;
102
117
  };
103
118
  type CheckAction = {
104
119
  type: 'check';
105
120
  value: boolean;
106
- element: ElementDescriptor;
121
+ element: ElementDescriptor | ElementReference;
107
122
  };
108
123
  type ClearAction = {
109
124
  type: 'clear';
110
- element?: ElementDescriptor;
125
+ element?: ElementDescriptor | ElementReference;
111
126
  };
112
127
  type EraseAction = {
113
128
  type: 'erase';
114
129
  size: NumberExpression;
115
- element?: ElementDescriptor;
130
+ element?: ElementDescriptor | ElementReference;
116
131
  };
117
132
  type TypeAction = {
118
133
  type: 'type';
119
134
  value: AnyExpression | ExtractOperation | Generator$1;
120
135
  secret?: boolean;
121
- element?: ElementDescriptor | ChromeElementDescriptor | DialogElementDescriptor;
136
+ element?: ElementDescriptor | ElementReference | ChromeElementDescriptor | DialogElementDescriptor;
122
137
  };
123
138
  type SearchAction = {
124
139
  type: 'search';
125
140
  value: StringExpression;
126
- element?: ElementDescriptor;
141
+ element?: ElementDescriptor | ElementReference;
127
142
  };
128
143
  type HitKeyAction = {
129
144
  type: 'hit key';
@@ -133,7 +148,7 @@ type HitKeyAction = {
133
148
  type ClickElementAction = {
134
149
  type: 'click';
135
150
  keys?: Key[];
136
- element: ElementDescriptor;
151
+ element: ElementDescriptor | ElementReference;
137
152
  button?: 'left' | 'right';
138
153
  times?: number;
139
154
  };
@@ -147,7 +162,7 @@ type ClickDialogElementAction = {
147
162
  };
148
163
  type HoverAction = {
149
164
  type: 'hover';
150
- element: ElementDescriptor;
165
+ element: ElementDescriptor | ElementReference;
151
166
  };
152
167
  type ScrollByDistanceAction = {
153
168
  type: 'scroll';
@@ -158,23 +173,23 @@ type ScrollByDistanceAction = {
158
173
  type ScrollByFractionAction = {
159
174
  type: 'scroll';
160
175
  fraction: NumberExpression;
161
- element?: ElementDescriptor | ViewportDescriptor;
176
+ element?: ElementDescriptor | ElementReference | ViewportDescriptor;
162
177
  direction?: Direction;
163
178
  times?: NumberExpression;
164
179
  };
165
180
  type ScrollToPositionAction = {
166
181
  type: 'scroll';
167
182
  position: AbsolutePosition;
168
- element?: ElementDescriptor | ViewportDescriptor;
183
+ element?: ElementDescriptor | ElementReference | ViewportDescriptor;
169
184
  times?: NumberExpression;
170
185
  };
171
186
  type ScrollToElementAction = {
172
187
  type: 'scroll';
173
- element: ElementDescriptor;
188
+ element: ElementDescriptor | ElementReference;
174
189
  };
175
190
  type ScrollTheElementAction = {
176
191
  type: 'scroll';
177
- element: ElementDescriptor;
192
+ element: ElementDescriptor | ElementReference;
178
193
  direction?: Direction;
179
194
  distance: NumberExpression;
180
195
  times?: NumberExpression;
@@ -213,7 +228,7 @@ type CreateTargetAction = {
213
228
  };
214
229
  type CloseAction = {
215
230
  type: 'close';
216
- element: ElementDescriptor | DialogDescriptor | ChromeTabDescriptor;
231
+ element: ElementDescriptor | ElementReference | DialogDescriptor | ChromeTabDescriptor;
217
232
  };
218
233
  type SwitchAction = {
219
234
  type: 'switch';
@@ -226,7 +241,7 @@ type WaitAction = {
226
241
  };
227
242
  type FindAction = {
228
243
  type: 'find';
229
- element: ElementDescriptor;
244
+ element: ElementDescriptor | ElementReference;
230
245
  };
231
246
  type VisualCheckAction = {
232
247
  type: 'visual check';
@@ -335,7 +350,7 @@ type NumberOperation = AddOperation | SubOperation | MulOperation | DivOperation
335
350
  type ConditionOperation = ParensOperation | IgnoreCaseOperation | MatchCaseOperation | NotOperation | OrOperation | AndOperation | ComparisonOperation | ValidateOperation | MatchOperation | IncludesOnlyOperation | IncludesOperation | StartsWithOperation | EndsWithOperation | VisibleOperation | ClickableOperation | EnabledOperation | HoveredOperation | CheckedOperation | PopulatedOperation | EveryOperation | SomeOperation;
336
351
  type Operand = {
337
352
  isOperand: true;
338
- value: AnyExpression | ElementDescriptor | DialogDescriptor | ExpressionOperation;
353
+ value: AnyExpression | ElementDescriptor | ElementReference | DialogDescriptor | ExpressionOperation;
339
354
  };
340
355
  type ParensOperation = {
341
356
  operator: 'parens';
@@ -512,15 +527,30 @@ type Selector$1 = {
512
527
  type: 'css' | 'xpath';
513
528
  selector: StringExpression;
514
529
  };
515
- type AnchorDescriptor<TElement = ElementDescriptor> = RelativeAnchorDescriptor<TElement> | AbsoluteAnchorDescriptor<TElement>;
516
- type RelativeAnchorDescriptor<TElement = ElementDescriptor> = {
530
+ type AnchorDescriptor<TElement = ElementDescriptor | ElementReference> = RelativeAnchorDescriptor<TElement> | AbsoluteAnchorDescriptor<TElement>;
531
+ type RelativeAnchorDescriptor<TElement = ElementDescriptor | ElementReference> = {
517
532
  position: RelativePosition | RelativePosition[];
518
533
  element: TElement;
519
534
  };
520
- type AbsoluteAnchorDescriptor<TElement = ElementDescriptor> = {
535
+ type AbsoluteAnchorDescriptor<TElement = ElementDescriptor | ElementReference> = {
521
536
  position: AbsolutePosition | AbsolutePosition[];
522
537
  element?: TElement | ViewportDescriptor | DialogDescriptor;
523
538
  };
539
+ /**
540
+ * A contextual element reference (`it`) in element position. The parser no longer resolves it to
541
+ * a copy of the referenced descriptor - the runner resolves it at runtime against the element the
542
+ * run most recently resolved (a previous action's element, or the current entry of a for-each
543
+ * loop over page elements).
544
+ */
545
+ type ElementReference = {
546
+ isElementReference: true;
547
+ /**
548
+ * The type word the reference was spelled with (`that button`, `the current row`) - surface
549
+ * decoration for readability and round-tripping; resolution ignores it.
550
+ */
551
+ type?: ElementType; /** The referenced element is known at parse time to hold sensitive data, so the value keeps masking. */
552
+ secret?: boolean;
553
+ };
524
554
  type DialogDescriptor = {
525
555
  isDialogDescriptor: true;
526
556
  };
@@ -8274,7 +8304,7 @@ interface AXNodeFlat<TNode> {
8274
8304
  };
8275
8305
  style?: AXStyle;
8276
8306
  scrollable?: 'horizontal' | 'vertical' | 'both';
8277
- role?: 'close' | 'submit' | 'cancel';
8307
+ role?: AXRole;
8278
8308
  collect?: boolean;
8279
8309
  children: number[];
8280
8310
  debugLog?: {
@@ -8282,6 +8312,7 @@ interface AXNodeFlat<TNode> {
8282
8312
  id: string;
8283
8313
  };
8284
8314
  }
8315
+ type AXRole = 'close' | 'submit' | 'cancel';
8285
8316
  interface AXOption {
8286
8317
  value: string;
8287
8318
  label?: string;
@@ -8338,6 +8369,7 @@ type AXNodeViewJSON = {
8338
8369
  } | undefined;
8339
8370
  elevation: number;
8340
8371
  scrollable: ElementScrollDirection | undefined;
8372
+ role: AXRole | undefined;
8341
8373
  children: AXNodeViewJSON[];
8342
8374
  debugLog?: {
8343
8375
  xpath: string;
@@ -8398,7 +8430,7 @@ interface IAXNodeView<TNode = unknown> extends EventTarget<AXNodeEventMap> {
8398
8430
  readonly visibleBorderRect: Rectangle;
8399
8431
  readonly contentRect: Rectangle;
8400
8432
  readonly scrollable: ElementScrollDirection | undefined;
8401
- readonly role: 'close' | 'submit' | 'cancel' | undefined;
8433
+ readonly role: AXRole | undefined;
8402
8434
  readonly rects: {
8403
8435
  border: Rectangle | undefined;
8404
8436
  content: Rectangle | undefined;
@@ -8579,6 +8611,11 @@ interface AXProvider {
8579
8611
  findAXNode<TNode>(nodes: Iterable<IAXNodeView<TNode>>, descriptor: ResolvedElementDescriptor, options?: FindCandidatesOptions): Promise<CandidateMetric | null>;
8580
8612
  /** Optional: remote providers may not support returning the full ranked candidate list. */
8581
8613
  findAXNodes?<TNode>(nodes: Iterable<IAXNodeView<TNode>>, descriptor: ResolvedElementDescriptor, options?: FindCandidatesOptions): Promise<CandidateMetric[]>;
8614
+ /**
8615
+ * Optional: the collection of elements the descriptor describes - the candidates whose match
8616
+ * quality ties with the best one found, in document order.
8617
+ */
8618
+ findAXNodeCollection?<TNode>(nodes: Iterable<IAXNodeView<TNode>>, descriptor: ResolvedElementDescriptor, options?: FindCandidatesOptions): Promise<CandidateMetric[]>;
8582
8619
  } //#endregion
8583
8620
  //#endregion
8584
8621
  //#region src/scope.d.ts
@@ -8607,6 +8644,19 @@ declare class Scope {
8607
8644
  initialize(data: StorageData): void;
8608
8645
  available(id: string): boolean;
8609
8646
  set(name: string, data: StorageData): Storage;
8647
+ /**
8648
+ * Creates bindings in the current scope: an ephemeral, stackable storage that shadows the scope's
8649
+ * own values until it is unbound - what a loop binds for the run of its body. Bindings are not
8650
+ * storages, so they leave the scope chain (and everything keyed off a nested scope, like skipping
8651
+ * assertions in a called test) untouched, and they are immutable through syntax - assigning to a
8652
+ * bound name throws.
8653
+ */
8654
+ bind(values: Record<string, {
8655
+ value: any;
8656
+ secret?: boolean;
8657
+ }>): () => void;
8658
+ /** Removes every binding, so none outlives the run that created it. */
8659
+ unbindAll(): void;
8610
8660
  reset(): void;
8611
8661
  }
8612
8662
  interface Storage {
@@ -9256,6 +9306,8 @@ declare const ErrorCode: {
9256
9306
  readonly OBSCURED_ELEMENT: "OBSCURED_ELEMENT";
9257
9307
  readonly FORBIDDEN_ACTION: "FORBIDDEN_ACTION";
9258
9308
  readonly EXCEEDED_ALLOWED_TIMEOUT: "EXCEEDED_ALLOWED_TIMEOUT";
9309
+ readonly LOOP_LIMIT_EXCEEDED: "LOOP_LIMIT_EXCEEDED";
9310
+ readonly ASSIGNMENT_TO_BINDING: "ASSIGNMENT_TO_BINDING";
9259
9311
  readonly NOT_PDF_VIEWER: "NOT_PDF_VIEWER";
9260
9312
  readonly PDF_PAGE_OUT_OF_RANGE: "PDF_PAGE_OUT_OF_RANGE";
9261
9313
  };
@@ -9274,7 +9326,7 @@ type ResolvedChromeTabDescriptor = {
9274
9326
  declare function activateBrowserTab(automator: Browser, descriptor: ResolvedChromeTabDescriptor): Promise<void>;
9275
9327
  //#endregion
9276
9328
  //#region src/utils/evaluate-expression.d.ts
9277
- type EvaluatedExpression<TValue> = TValue extends ExtractOperation ? Any : TValue extends NumberExpression ? number : TValue extends SizeOperation ? number : TValue extends KeysOperation ? string[] : TValue extends ValuesOperation | EntriesOperation | MapOperation ? Any[] : TValue extends Condition | EveryOperation | SomeOperation ? boolean : TValue extends OTP ? string : TValue extends RandomValue<string> ? string | string[] : TValue extends RandomValue<number> ? number : TValue extends Reference<infer TType extends Any> ? TType : TValue extends JSExpressionReference<infer TType extends Any> ? TType : TValue extends InterpolatedString ? string : TValue extends JSExpression ? string : TValue extends Structure ? Record<string, any> | any[] : TValue extends FileHandle ? string : TValue extends Pattern ? RegExp | Match : TValue extends ChromeTabDescriptor ? ResolvedChromeTabDescriptor : TValue extends ChromeElementDescriptor ? ChromeElementDescriptor : TValue extends ElementDescriptor ? ResolvedElementDescriptor : TValue;
9329
+ type EvaluatedExpression<TValue> = TValue extends ExtractOperation ? Any : TValue extends NumberExpression ? number : TValue extends SizeOperation ? number : TValue extends KeysOperation ? string[] : TValue extends ValuesOperation | EntriesOperation | MapOperation ? Any[] : TValue extends Condition | EveryOperation | SomeOperation ? boolean : TValue extends OTP ? string : TValue extends RandomValue<string> ? string | string[] : TValue extends RandomValue<number> ? number : TValue extends Reference<infer TType extends Any> ? TType : TValue extends JSExpressionReference<infer TType extends Any> ? TType : TValue extends InterpolatedString ? string : TValue extends JSExpression ? string : TValue extends Structure ? Record<string, any> | any[] : TValue extends FileHandle ? string : TValue extends Pattern ? RegExp | Match : TValue extends ChromeTabDescriptor ? ResolvedChromeTabDescriptor : TValue extends ChromeElementDescriptor ? ChromeElementDescriptor : TValue extends ElementDescriptor | ElementReference ? ResolvedElementDescriptor : TValue;
9278
9330
  //#endregion
9279
9331
  //#region src/handler.d.ts
9280
9332
  type HandlerOptions<TAutomator extends Automator, TInstruction extends Instruction> = {
@@ -9282,11 +9334,16 @@ type HandlerOptions<TAutomator extends Automator, TInstruction extends Instructi
9282
9334
  context: RunnerContext;
9283
9335
  instruction: TInstruction;
9284
9336
  signal?: AbortSignal;
9285
- shouldCapture?: boolean; /** @internal for BE usage only */
9337
+ shouldCapture?: boolean; /** The live loop handle a block-form loop body runs under (see `handlers/loop.ts`). */
9338
+ loop?: LoopHandle; /** Stable identity of the instruction in the caller's program, used to key a loop handle. */
9339
+ stepId?: string;
9340
+ stepIndex?: number; /** Opaque id echoed on progress log events so a caller can tie them back to the run it triggered. */
9341
+ correlationId?: string; /** @internal for BE usage only */
9286
9342
  shouldNotThrowOnUnexpectedNavigationStatus?: boolean; /** @internal for BE usage only */
9287
9343
  expectedNavigationStatuses?: number[];
9288
9344
  };
9289
9345
  type RunResult$1<TResult extends HandleResult> = TResult & {
9346
+ /** The text the instruction was parsed from - see {@link getInstructionText}. */text?: string;
9290
9347
  before?: Capture;
9291
9348
  after?: Capture;
9292
9349
  values: UsedValues;
@@ -9350,6 +9407,10 @@ declare abstract class Handler$1<TAutomator extends Automator, TInstruction exte
9350
9407
  readonly instruction: TInstruction;
9351
9408
  readonly signal: AbortSignal;
9352
9409
  readonly shouldCapture: boolean;
9410
+ readonly loop?: LoopHandle;
9411
+ readonly stepId?: string;
9412
+ readonly correlationId?: string;
9413
+ readonly stepIndex?: number;
9353
9414
  readonly shouldNotThrowOnUnexpectedNavigationStatus: boolean;
9354
9415
  readonly expectedNavigationStatuses: number[];
9355
9416
  get action(): TInstruction extends Action<any> ? TInstruction : unknown;
@@ -9365,6 +9426,10 @@ declare abstract class Handler$1<TAutomator extends Automator, TInstruction exte
9365
9426
  instruction,
9366
9427
  signal,
9367
9428
  shouldCapture,
9429
+ loop,
9430
+ stepId,
9431
+ correlationId,
9432
+ stepIndex,
9368
9433
  shouldNotThrowOnUnexpectedNavigationStatus,
9369
9434
  expectedNavigationStatuses
9370
9435
  }: HandlerOptions<TAutomator, TInstruction>);
@@ -9382,6 +9447,8 @@ declare abstract class Handler$1<TAutomator extends Automator, TInstruction exte
9382
9447
  web: IAXNodeView<WebNode> | null;
9383
9448
  mobile: IAXNodeView<IOSNode> | null;
9384
9449
  }[TAutomator["type"]]>;
9450
+ /** The collection of elements the descriptor describes (see {@link AXOps.findNodes}). */
9451
+ elements(descriptor: ElementDescriptor | ResolvedElementDescriptor): Promise<IAXNodeView<any>[]>;
9385
9452
  capture(): Promise<Capture | undefined>;
9386
9453
  /** Best-effort scroll bringing the elements matched by this handler into the viewport, so the
9387
9454
  * `after` capture shows them. Call it after the instruction's page reads are done — the scroll
@@ -9634,6 +9701,57 @@ declare class IfHandler extends Handler$1<Automator, IfControlFlow, IfResult> {
9634
9701
  }>;
9635
9702
  }
9636
9703
  //#endregion
9704
+ //#region src/utils/iterator.d.ts
9705
+ type IterationEntry = {
9706
+ index: number;
9707
+ key: number | string;
9708
+ item: Any;
9709
+ result: Any;
9710
+ };
9711
+ //#endregion
9712
+ //#region src/handlers/loop.d.ts
9713
+ type LoopResult = {
9714
+ status: 'looped';
9715
+ meta: {
9716
+ iteration: number;
9717
+ done: boolean;
9718
+ next?: Instruction[];
9719
+ loop?: LoopHandle;
9720
+ };
9721
+ };
9722
+ type LoopState = {
9723
+ iteration: number; /** The exact iteration count when the loop's shape knows it up front. */
9724
+ total?: number;
9725
+ entries?: IterationEntry[]; /** The element iterable, resolved once per loop - a body that rebinds `it` must not shift it. */
9726
+ iterable?: ResolvedElementDescriptor; /** Removes this loop's bindings from the scope. */
9727
+ unbind?: () => void;
9728
+ };
9729
+ declare class LoopHandler extends Handler$1<Automator, LoopControlFlow, LoopResult> {
9730
+ #private;
9731
+ handle(): Promise<{
9732
+ status: "looped";
9733
+ meta: {
9734
+ iteration: number;
9735
+ done: boolean;
9736
+ loop: LoopHandle;
9737
+ };
9738
+ } | {
9739
+ status: "looped";
9740
+ meta: {
9741
+ iteration: any;
9742
+ done: boolean;
9743
+ next?: undefined;
9744
+ };
9745
+ } | {
9746
+ status: "looped";
9747
+ meta: {
9748
+ iteration: any;
9749
+ done: boolean;
9750
+ next: Instruction[];
9751
+ };
9752
+ }>;
9753
+ }
9754
+ //#endregion
9637
9755
  //#region src/handlers/intent.d.ts
9638
9756
  declare class IntentHandler extends Handler$1<Automator, Action<'intent'>> {
9639
9757
  handle(): Promise<never>;
@@ -9949,6 +10067,7 @@ declare const handlers: {
9949
10067
  'initialize scope': typeof InitializeScopeHandler;
9950
10068
  try: typeof TryHandler;
9951
10069
  if: typeof IfHandler;
10070
+ loop: typeof LoopHandler;
9952
10071
  };
9953
10072
  mobile: {
9954
10073
  check: typeof CheckHandler;
@@ -9970,6 +10089,7 @@ declare const handlers: {
9970
10089
  'initialize scope': typeof InitializeScopeHandler;
9971
10090
  try: typeof TryHandler;
9972
10091
  if: typeof IfHandler;
10092
+ loop: typeof LoopHandler;
9973
10093
  "set value": never;
9974
10094
  evaluate: never;
9975
10095
  clear: never;
@@ -10033,7 +10153,8 @@ type RunnerOptions<TAutomator extends Automator> = {
10033
10153
  screenshotTimeout?: number;
10034
10154
  previewTimeout?: number;
10035
10155
  maxWaitTimeout?: number;
10036
- };
10156
+ }; /** How many iterations a loop may run before it fails; capped by the runner's hard maximum. */
10157
+ loopIterationLimit?: number;
10037
10158
  shouldHideFilepickerDialogs?: boolean;
10038
10159
  shouldSkipInitialNavigationInNestedScope?: boolean;
10039
10160
  shouldSkipAssertionsInNestedScope?: boolean;
@@ -10045,7 +10166,9 @@ type RunnerOptions<TAutomator extends Automator> = {
10045
10166
  };
10046
10167
  };
10047
10168
  type RunOptions = {
10048
- stepIndex?: number;
10169
+ stepIndex?: number; /** Stable identity of this instruction in the caller's program, used to key a loop handle. */
10170
+ stepId?: string; /** The live loop handle when this instruction belongs to the body of a block-form loop. */
10171
+ loop?: LoopHandle;
10049
10172
  signal?: AbortSignal;
10050
10173
  shouldCapture?: boolean;
10051
10174
  /** Opaque id echoed on each `subinstructionExecutionStarted` so a caller can tie the resulting
@@ -10302,6 +10425,14 @@ declare class AXOps<TAutomator extends Automator = Automator> {
10302
10425
  searchCandidates<TNode>(tree: IAXTreeView<TNode>, descriptor: ResolvedElementDescriptor, options?: FindCandidatesOptions): Promise<CandidateMetric[]>;
10303
10426
  describeNode<TNode>(tree: IAXTreeView<TNode>, query: ElementDescriptorQuery<IAXNodeView<TNode>>): Promise<ResolvedElementDescriptor | undefined>;
10304
10427
  findNode(descriptor: ResolvedElementDescriptor, options: FindNodeOptions): Promise<FindNodeResult<TAutomator>>;
10428
+ /**
10429
+ * Resolves an element descriptor to the collection of elements it describes - the candidates
10430
+ * whose match quality ties with the best one found, in document order. Used by for-each loops
10431
+ * over page elements, and by any consumer needing "every element matching the descriptor".
10432
+ * An empty collection is retried until the timeout, since a page mid-load may transiently
10433
+ * match nothing.
10434
+ */
10435
+ findNodes(descriptor: ResolvedElementDescriptor, options: FindNodeOptions): Promise<IAXNodeView<any>[]>;
10305
10436
  }
10306
10437
  //#endregion
10307
10438
  //#region src/types.d.ts
@@ -10326,6 +10457,18 @@ type UsedValues = {
10326
10457
  element?: ResolvedElementDescriptor;
10327
10458
  }>;
10328
10459
  };
10460
+ /**
10461
+ * The state of a running block-form loop, handed to the caller and passed back with every
10462
+ * instruction of the body (see adr/2026-08-21-block-form-loop-handles.md). Opaque to the caller:
10463
+ * store it, echo it, never interpret it.
10464
+ */
10465
+ type LoopHandle = {
10466
+ id: string; /** The head instruction, so bindings can be re-derived without runner-side state. */
10467
+ head: LoopControlFlow; /** The enclosing loop, so a nested body sees both sets of bindings. */
10468
+ parent?: LoopHandle; /** How many iterations have started. */
10469
+ iteration: number; /** When the loop started, for a per-loop wall-clock timeout. */
10470
+ startedAt: number;
10471
+ };
10329
10472
  interface RunnerContext {
10330
10473
  axOps: AXOps;
10331
10474
  scope: Scope;
@@ -10333,6 +10476,14 @@ interface RunnerContext {
10333
10476
  dispatcher?: Dispatcher;
10334
10477
  activeElement?: WebNode;
10335
10478
  preinstructions: Instruction[];
10479
+ /** Bookkeeping for each running loop, kept while the runner re-queues it. */
10480
+ loops?: Map<Instruction, LoopState>;
10481
+ /**
10482
+ * The most recently resolved element node - what an element reference (`it`) resolves to at
10483
+ * runtime. Every successful element find updates it, and a for-each loop over page elements
10484
+ * rebinds it to the current entry at the start of each iteration.
10485
+ */
10486
+ activeAXNode?: IAXNodeView<any>;
10336
10487
  }
10337
10488
  type SelectorElementDescriptor = Required<Pick<ResolvedElementDescriptor, 'selector'>>;
10338
10489
  declare namespace index_d_exports {
@@ -10803,4 +10954,4 @@ declare class HttpRemoteAXProvider extends RemoteAXProvider {
10803
10954
  protected _rqFindAXNode<TNode>(nodes: IAXNodeView<TNode>[], descriptor: ResolvedElementDescriptor, options?: FindCandidatesOptions): Promise<CandidateMetricResponse | null>;
10804
10955
  }
10805
10956
  //#endregion
10806
- export { type AXContentType, type AXControlType, type AXNodeFlat, type AXOption, type AXProvider, AXServerFetch, AXServerRequest, type AXState, type AXStructuralType, type AXStyle, type AXTreeFlat, type AXType, AbortError, type AnchorDescriptor, Automator, AutomatorError, BlockingDialog, BodyConsumedError, Browser, BrowserActivePageChangedEvent, BrowserDisconnectedEvent, BrowserPageClosedEvent, BrowserPageCreatedEvent, BrowserPageNavigatedEvent, BrowserStabilizingLoadEvent, BrowserStabilizingNavigationEvent, BrowserStabilizingOutgoingRequestsEvent, BrowserTargetCrashedEvent, BrowserTargetCreatedEvent, BrowserWindowCreatedEvent, CallableRemoteFunctionHandle, CandidateMetricResponse, CommandTimedOutError, Connection, Cookie, type CustomActions, Debugger, DebuggerPausedEvent, DebuggerResumedEvent, DescribeAXNodeResponse, type DescriptorStrategy, DialogHandledEvent, type ElementDescriptor, type ElementDescriptorQuery, EvaluationArguments, EvaluationExpression, EvaluationFunction, EvaluationOptions, EvaluationResult, Evaluator, EvaluatorDestroyedEvent, EvaluatorLogEvent, Expression, FilepickerDialog, FlagChangedEvent, Flags, FlagsSnapshot, FlushError, Frame, FrameDestroyedEvent, FrameDocumentRequestEvent, FrameDocumentResponseEvent, FrameEvaluatorAttached, FrameFetchError, FrameFetchOptions, FrameLifecycleEvent, FrameNavigatedEvent, FrameNavigatingEvent, FrameSwappedEvent, FrameSwappingEvent, type Har, HarRecorder, HarRecorderOptions, HarRecorderStatsChangedEvent, HarStats, HttpRemoteAXProvider, HttpRemoteAXProviderOptions, type IAXNodeView, type IAXTreeView, Injection, InjectionEvaluatorAttachedEvent, InjectionExpression, InjectionIncommingMessageEvent, InjectionOutgoingMessageEvent, InjectionTargetAttachedEvent, Intercepted, InterceptedRequest, InterceptedResponse, InterceptionHandler, InterceptionPattern, InterceptionPatternMatcher, Keyboard, Loader, LoaderRequestEvent, LoaderResponseEvent, LocalizedRemoteValue, MakeAXTreeResponse, Mouse, NavigationFailedError, NavigationTimedOutError, NoHistoryEntryError, Node, type NodeBackground, Port, PortIncommingMessageEvent, type PortMessageEvent, PortOutgoingMessageEvent, RemoteAXProvider, RemoteFunctionHandle, RemoteObjectHandle, type Request, type ResolvedAnchor, type ResolvedElementDescriptor, ResolvedRemoteValue, type Response$1 as Response, RunOptions, RunResult, Runner, RunnerAXNodeFoundEvent, type RunnerContext, RunnerFilepickerDialogRequestedEvent, RunnerOptions, RunnerStatusChangedEvent, Script, type SelectorElementDescriptor, StaleNodeError, StaleRemoteObjectHandleError, StylesheetHandle, Target, TargetActivatedEvent, TargetActivatingEvent, TargetAttachedEvent, TargetChangedEvent, TargetChildTargetCreatingEvent, TargetClosedEvent, TargetDetachedEvent, TargetDialogEvent, TargetElementSelectedEvent, TargetFilepickerDialogEvent, TargetFrameAttachedEvent, TargetFrameTargetCreatedEvent, TargetMainFrameReadyEvent, TargetNavigatedEvent, TargetVisibilityChangeEvent, type UsedValues, WebNode, Window, WindowDestroyedEvent, WindowTargetAttachedEvent, WindowTargetDetachedEvent, flags, isElementAcceptableInvisible, localizeRemoteValue, makeBlockingDialog, makeBrowser, makeBundledExpression, makeBundledScript, makeConnection, makeDebugger, makeEvaluator, makeExpression, makeFilepickerDialog, makeFrame, makeInjection, makeIntercepted, makeInterceptedRequest, makeInterceptedResponse, makeInterceptionPatternMatcher, makeKeyboard, makeLoader, makeMouse, makePort, makeRunner, makeScript, makeTarget, makeWebNode, makeWindow, provideRolldownConfig, index_d_exports as spec, toCDPPattern };
10957
+ export { type AXContentType, type AXControlType, type AXNodeFlat, type AXOption, type AXProvider, AXServerFetch, AXServerRequest, type AXState, type AXStructuralType, type AXStyle, type AXTreeFlat, type AXType, AbortError, type AnchorDescriptor, Automator, AutomatorError, BlockingDialog, BodyConsumedError, Browser, BrowserActivePageChangedEvent, BrowserDisconnectedEvent, BrowserPageClosedEvent, BrowserPageCreatedEvent, BrowserPageNavigatedEvent, BrowserStabilizingLoadEvent, BrowserStabilizingNavigationEvent, BrowserStabilizingOutgoingRequestsEvent, BrowserTargetCrashedEvent, BrowserTargetCreatedEvent, BrowserWindowCreatedEvent, CallableRemoteFunctionHandle, CandidateMetricResponse, CommandTimedOutError, Connection, Cookie, type CustomActions, Debugger, DebuggerPausedEvent, DebuggerResumedEvent, DescribeAXNodeResponse, type DescriptorStrategy, DialogHandledEvent, type ElementDescriptor, type ElementDescriptorQuery, EvaluationArguments, EvaluationExpression, EvaluationFunction, EvaluationOptions, EvaluationResult, Evaluator, EvaluatorDestroyedEvent, EvaluatorLogEvent, Expression, FilepickerDialog, FlagChangedEvent, Flags, FlagsSnapshot, FlushError, Frame, FrameDestroyedEvent, FrameDocumentRequestEvent, FrameDocumentResponseEvent, FrameEvaluatorAttached, FrameFetchError, FrameFetchOptions, FrameLifecycleEvent, FrameNavigatedEvent, FrameNavigatingEvent, FrameSwappedEvent, FrameSwappingEvent, type Har, HarRecorder, HarRecorderOptions, HarRecorderStatsChangedEvent, HarStats, HttpRemoteAXProvider, HttpRemoteAXProviderOptions, type IAXNodeView, type IAXTreeView, Injection, InjectionEvaluatorAttachedEvent, InjectionExpression, InjectionIncommingMessageEvent, InjectionOutgoingMessageEvent, InjectionTargetAttachedEvent, Intercepted, InterceptedRequest, InterceptedResponse, InterceptionHandler, InterceptionPattern, InterceptionPatternMatcher, Keyboard, Loader, LoaderRequestEvent, LoaderResponseEvent, LocalizedRemoteValue, type LoopHandle, MakeAXTreeResponse, Mouse, NavigationFailedError, NavigationTimedOutError, NoHistoryEntryError, Node, type NodeBackground, Port, PortIncommingMessageEvent, type PortMessageEvent, PortOutgoingMessageEvent, RemoteAXProvider, RemoteFunctionHandle, RemoteObjectHandle, type Request, type ResolvedAnchor, type ResolvedElementDescriptor, ResolvedRemoteValue, type Response$1 as Response, RunOptions, RunResult, Runner, RunnerAXNodeFoundEvent, type RunnerContext, RunnerFilepickerDialogRequestedEvent, RunnerOptions, RunnerStatusChangedEvent, Script, type SelectorElementDescriptor, StaleNodeError, StaleRemoteObjectHandleError, StylesheetHandle, Target, TargetActivatedEvent, TargetActivatingEvent, TargetAttachedEvent, TargetChangedEvent, TargetChildTargetCreatingEvent, TargetClosedEvent, TargetDetachedEvent, TargetDialogEvent, TargetElementSelectedEvent, TargetFilepickerDialogEvent, TargetFrameAttachedEvent, TargetFrameTargetCreatedEvent, TargetMainFrameReadyEvent, TargetNavigatedEvent, TargetVisibilityChangeEvent, type UsedValues, WebNode, Window, WindowDestroyedEvent, WindowTargetAttachedEvent, WindowTargetDetachedEvent, flags, isElementAcceptableInvisible, localizeRemoteValue, makeBlockingDialog, makeBrowser, makeBundledExpression, makeBundledScript, makeConnection, makeDebugger, makeEvaluator, makeExpression, makeFilepickerDialog, makeFrame, makeInjection, makeIntercepted, makeInterceptedRequest, makeInterceptedResponse, makeInterceptionPatternMatcher, makeKeyboard, makeLoader, makeMouse, makePort, makeRunner, makeScript, makeTarget, makeWebNode, makeWindow, provideRolldownConfig, index_d_exports as spec, toCDPPattern };