|
| 1 | +import type { ActingPipelinePolicy } from '@agent-device/selectors/selector-pipeline-policy'; |
| 2 | +import type { PreresolvedInteractionTarget } from '@agent-device/contracts/interaction'; |
| 3 | +import type { ReplayTargetGuardDenotation } from '@agent-device/contracts/replay'; |
| 4 | + |
| 5 | +/** |
| 6 | + * ADR 0012 migration step 4, post-resolution guard: the LOCAL identity AND |
| 7 | + * the STRUCTURAL denotation (pre-order document index + same-parent sibling |
| 8 | + * ordinal) of the element replay's pre-action verification isolated. Set ONLY |
| 9 | + * by the replay step loop (via `DaemonRequest.internal.replayTargetGuard`) for |
| 10 | + * annotated verified actions — never on live interactive commands. |
| 11 | + * |
| 12 | + * Local identity alone is insufficient: ADR path 6 isolates ONE member among |
| 13 | + * several nodes that share the same `{id, role, label}` using sibling / |
| 14 | + * region-scoped viewportOrder. If verification isolates duplicate A but |
| 15 | + * dispatch's occlusion/visibility filtering selects duplicate B with the same |
| 16 | + * local identity, a local-identity-only guard would pass and tap the wrong |
| 17 | + * element. The structural denotation is the discriminator that catches that |
| 18 | + * split BEFORE the device action. |
| 19 | + */ |
| 20 | +export type ExpectedResolvedTarget = ReplayTargetGuardDenotation; |
| 21 | + |
| 22 | +export type InteractionAction = |
| 23 | + | 'click' |
| 24 | + | 'press' |
| 25 | + | 'fill' |
| 26 | + | 'focus' |
| 27 | + | 'longPress' |
| 28 | + | 'hover' |
| 29 | + | 'scroll' |
| 30 | + | 'swipe' |
| 31 | + | 'pinch' |
| 32 | + | 'pan' |
| 33 | + | 'drag' |
| 34 | + | 'fling' |
| 35 | + | 'rotate' |
| 36 | + | 'transform'; |
| 37 | + |
| 38 | +export type ResolveInteractionTargetParams = { |
| 39 | + action: InteractionAction; |
| 40 | + requireInteractive: boolean; |
| 41 | + /** |
| 42 | + * The structural pipeline this action runs (#1656): occlusion, off-screen, |
| 43 | + * and hittable-ancestor promotion are the row's decisions. `promotedTarget` |
| 44 | + * for tap-shaped actions, `resolvedTarget` for the actions that must keep |
| 45 | + * the element they resolved. |
| 46 | + */ |
| 47 | + pipeline: ActingPipelinePolicy; |
| 48 | + /** |
| 49 | + * How long a `promotedTarget` row may poll for a target that does not exist yet (never model- or |
| 50 | + * CLI-writable); `resolveSelectorInteractionTarget` caps it at the row's `maxTimeoutMs`. Anything |
| 51 | + * other than a positive integer, and every `resolvedTarget` row, takes one attempt. |
| 52 | + */ |
| 53 | + readinessTimeoutMs?: number; |
| 54 | + /** |
| 55 | + * `--verify` (#1047): also capture the pre-action node set for a `point` target |
| 56 | + * so `changedFromBefore` evidence has a baseline. Ref/selector targets already |
| 57 | + * capture a snapshot to resolve the target, so this is a no-op cost for them — |
| 58 | + * their nodes are attached below regardless of this flag. For point targets, |
| 59 | + * which normally skip capture entirely, this opts into one extra capture, only |
| 60 | + * when the caller explicitly asked for verify evidence. Defaults to false. |
| 61 | + */ |
| 62 | + captureEvidenceBaseline?: boolean; |
| 63 | + /** ADR 0012 step 4 post-resolution guard; see `ExpectedResolvedTarget`. */ |
| 64 | + expectedResolvedTarget?: ExpectedResolvedTarget; |
| 65 | + /** Identifies one endpoint when a multi-target replay guard refuses. */ |
| 66 | + replayTargetRole?: 'source' | 'destination'; |
| 67 | + /** |
| 68 | + * #1654: the caller already resolved this `@ref` against its own capture, so |
| 69 | + * the ref branch adopts that node instead of looking the ref up again. Ref |
| 70 | + * targets only — a selector target has nothing pre-resolved to adopt. |
| 71 | + */ |
| 72 | + preresolvedTarget?: PreresolvedInteractionTarget; |
| 73 | +}; |
0 commit comments