taphound 0.2.0-dev.1 → 0.2.0-dev.12

package/dist/application/interaction/action-target.js

@@ -0,0 +1,40 @@
+import { resolveLocator } from "../locator/locator-resolver.js";
+/**
+ * The element an action acts on, with the capability semantics Generation,
+ * generated Replay, and External Flow steps share: a click or longClick
+ * reaches the nearest ancestor with that capability (touching the matched
+ * element itself), and a swipe needs a scrollable element with bounds.
+ */
+export function resolveActionTarget(layout, action, locator, viewport) {
+    const located = resolveLocator(layout, locator, {
+        viewport,
+        ...(action === "swipe" ? {} : {
+            requiredCapability: action === "click" ? "clickable" : "longClickable"
+        })
+    });
+    if (located.status !== "found") {
+        return located;
+    }
+    const element = located.element;
+    if (action === "click" && element.clickable !== true) {
+        return actionFailure("click target is not clickable");
+    }
+    if (action === "longClick" && element.longClickable !== true) {
+        return actionFailure("longClick target is not longClickable");
+    }
+    if (action === "swipe"
+        && (element.scrollable !== true || element.bounds === undefined)) {
+        return actionFailure("swipe target lacks scrollable bounds");
+    }
+    return {
+        status: "found",
+        located,
+        target: {
+            point: located.point,
+            ...(element.bounds === undefined ? {} : { bounds: element.bounds })
+        }
+    };
+}
+function actionFailure(message) {
+    return { status: "failed", code: "ACTION_FAILED", message };
+}

package/dist/application/interaction/external-step-runner.d.ts

@@ -0,0 +1,153 @@
+import type { ExternalStep } from "../../domain/external-flow.js";
+import type { FailureCode } from "../../domain/failure.js";
+import type { DisplayViewport } from "../../domain/geometry.js";
+import { type JourneyStep } from "../../domain/journey.js";
+import type { LayoutElement } from "../../domain/layout.js";
+import type { AdbPort } from "../../ports/adb.js";
+import type { Clock } from "../../ports/clock.js";
+import type { UiSnapshotProvider } from "../../ports/ui-snapshot.js";
+import type { IdleConfig, IdleResult, IdleWaiter } from "../wait/idle-waiter.js";
+import type { ActionExecutor, ActionTarget } from "./action-executor.js";
+/**
+ * The single implementation of External Flow steps and bridge foreground
+ * polling shared by Replay and Generation, so a flow that generates also
+ * replays under exactly the same rules.
+ */
+/** Foreground/layout observation budget inside an escaped app. */
+export declare const EXTERNAL_OBSERVATION_TIMEOUT_MS = 5000;
+export interface ExternalStepFailure {
+    code: FailureCode;
+    message: string;
+    details?: unknown;
+}
+export type ExternalFlowOutcome = {
+    status: "passed";
+} | {
+    status: "cancelled";
+} | ({
+    status: "failed";
+    stepIndex: number;
+} & ExternalStepFailure);
+export interface ExternalStepRunnerDependencies {
+    adb: Pick<AdbPort, "foregroundComponent">;
+    actionExecutor: ActionExecutor;
+    uiSnapshotProvider: UiSnapshotProvider;
+    captureLayout: (reason: "locate" | "expect", timeoutMs: number, signal?: AbortSignal) => Promise<readonly LayoutElement[]>;
+    createIdleWaiter: (packageName: string) => IdleWaiter;
+    idle: IdleConfig;
+    viewport: () => DisplayViewport | undefined;
+    deviceSerial: string;
+    /** Records idle-timeout evidence before the failure is reported. */
+    onIdleTimeout?: ((stepIndex: number, idle: Extract<IdleResult, {
+        status: "timeout";
+    }>) => Promise<void>) | undefined;
+}
+export declare function idleTimeoutDetails(idle: Extract<IdleResult, {
+    status: "timeout";
+}>): Record<string, unknown>;
+export declare function externalStepToJourneyStep(step: ExternalStep): JourneyStep;
+export declare class ExternalStepRunner {
+    private readonly dependencies;
+    constructor(dependencies: ExternalStepRunnerDependencies);
+    run(steps: readonly ExternalStep[], escapedPackageName: string, signal?: AbortSignal): Promise<ExternalFlowOutcome>;
+    private assertForeground;
+    private runStep;
+    private evaluateExpect;
+}
+export type ForegroundPollOutcome = {
+    status: "matched";
+    packageName: string;
+} | {
+    status: "timeout";
+} | {
+    status: "cancelled";
+};
+/**
+ * Polls the foreground package until `until` accepts it: bridge escape
+ * detection (`packageName !== target`) and return detection (`=== target`).
+ */
+export declare function pollForegroundPackage(input: {
+    adb: Pick<AdbPort, "foregroundComponent">;
+    clock: Clock;
+    packageName: string;
+    deviceSerial: string;
+    until: (packageName: string) => boolean;
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+}): Promise<ForegroundPollOutcome>;
+export interface BridgeRunDependencies {
+    adb: Pick<AdbPort, "foregroundComponent">;
+    clock: Clock;
+    actionExecutor: ActionExecutor;
+    externalSteps: ExternalStepRunner;
+    idleWaiter: IdleWaiter;
+    idle: IdleConfig;
+    packageName: string;
+    deviceSerial: string;
+}
+export interface BridgeRunInput {
+    trigger: {
+        step: JourneyStep;
+        target: ActionTarget;
+    };
+    escapeTimeoutMs: number;
+    returnTimeoutMs: number;
+    /** Engine policy for the escaped package; a failure stops the bridge. */
+    acceptEscape: (escapedPackageName: string) => ExternalStepFailure | undefined;
+    external: ExternalPhase;
+    signal?: AbortSignal | undefined;
+}
+/** What happens inside the escaped app between escape and return. */
+export type ExternalPhase = 
+/** Replay and Generation run a known step list, if any. */
+{
+    kind: "steps";
+    steps: (escapedPackageName: string) => Promise<readonly ExternalStep[] | undefined>;
+}
+/**
+ * The Recorder drives the escaped app one chosen step at a time (each
+ * through the same ExternalStepRunner) and reports the steps it ran.
+ */
+ | {
+    kind: "drive";
+    drive: (escapedPackageName: string) => Promise<ExternalDriveOutcome>;
+};
+export type ExternalDriveOutcome = {
+    status: "driven";
+    steps: readonly ExternalStep[];
+} | {
+    status: "cancelled";
+} | ({
+    status: "failed";
+} & ExternalStepFailure);
+export interface BridgeTiming {
+    actionMs: number;
+    waitMs: number;
+}
+export type BridgeOutcome = {
+    status: "returned";
+    escapedPackageName: string;
+    externalSteps?: readonly ExternalStep[] | undefined;
+    idle: Extract<IdleResult, {
+        status: "stable";
+    }>;
+    timing: BridgeTiming;
+} | ({
+    status: "failed";
+    idle?: Extract<IdleResult, {
+        status: "timeout";
+    }> | undefined;
+    timing: BridgeTiming;
+} & ExternalStepFailure) | {
+    status: "cancelled";
+    timing: BridgeTiming;
+};
+/**
+ * The single bridge step flow for Replay and Generation: trigger, escape,
+ * policy check, external steps, return, and settle.
+ */
+export declare class BridgeRunner {
+    private readonly dependencies;
+    constructor(dependencies: BridgeRunDependencies);
+    run(input: BridgeRunInput): Promise<BridgeOutcome>;
+}

package/dist/application/interaction/external-step-runner.js

@@ -0,0 +1,332 @@
+import { JourneyStepSchema } from "../../domain/journey.js";
+import { elementPredicateMismatch } from "../assertion/expectation-evaluator.js";
+import { resolveLocator } from "../locator/locator-resolver.js";
+import { withIdleAdvice } from "../wait/idle-advice.js";
+import { resolveActionTarget } from "./action-target.js";
+import { ScrollToExecutor } from "./scroll-to-executor.js";
+/**
+ * The single implementation of External Flow steps and bridge foreground
+ * polling shared by Replay and Generation, so a flow that generates also
+ * replays under exactly the same rules.
+ */
+/** Foreground/layout observation budget inside an escaped app. */
+export const EXTERNAL_OBSERVATION_TIMEOUT_MS = 5000;
+const BRIDGE_POLL_INTERVAL_MS = 500;
+class ExternalStepStop extends Error {
+    failure;
+    constructor(failure) {
+        super(failure === "cancelled" ? "cancelled" : failure.message);
+        this.failure = failure;
+    }
+}
+function stop(code, message, details) {
+    throw new ExternalStepStop({
+        code,
+        message,
+        ...(details === undefined ? {} : { details })
+    });
+}
+function cancelled() {
+    throw new ExternalStepStop("cancelled");
+}
+function checkCancelled(signal) {
+    if (signal?.aborted === true)
+        cancelled();
+}
+export function idleTimeoutDetails(idle) {
+    return {
+        idle: {
+            strategy: idle.strategy,
+            ...(idle.backend === undefined ? {} : { backend: idle.backend }),
+            polls: idle.polls,
+            durationMs: idle.durationMs,
+            samplingDurationMs: idle.samplingDurationMs,
+            fallbackUsed: idle.fallbackUsed,
+            frameActivityDetected: idle.frameActivityDetected,
+            lastDiff: idle.lastDiff
+        }
+    };
+}
+export function externalStepToJourneyStep(step) {
+    const { expectedActivity, ...rest } = step;
+    return JourneyStepSchema.parse({
+        ...rest,
+        activity: { before: expectedActivity, after: expectedActivity }
+    });
+}
+function requireExternalTarget(layout, step, viewport) {
+    if (step.action !== "click"
+        && step.action !== "longClick"
+        && step.action !== "swipe") {
+        return undefined;
+    }
+    const resolution = resolveActionTarget(layout, step.action, step.locator, viewport);
+    if (resolution.status !== "found") {
+        stop(resolution.code, resolution.message);
+    }
+    return resolution.target;
+}
+export class ExternalStepRunner {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    async run(steps, escapedPackageName, signal) {
+        for (const [stepIndex, step] of steps.entries()) {
+            try {
+                checkCancelled(signal);
+                await this.runStep(stepIndex, step, escapedPackageName, signal);
+            }
+            catch (error) {
+                if (!(error instanceof ExternalStepStop))
+                    throw error;
+                return error.failure === "cancelled"
+                    ? { status: "cancelled" }
+                    : { status: "failed", stepIndex, ...error.failure };
+            }
+        }
+        return { status: "passed" };
+    }
+    async assertForeground(escapedPackageName, expectedActivity, phase, signal) {
+        const foreground = await this.dependencies.adb.foregroundComponent({
+            packageName: escapedPackageName,
+            deviceSerial: this.dependencies.deviceSerial,
+            ...(signal === undefined ? {} : { signal }),
+            timeoutMs: EXTERNAL_OBSERVATION_TIMEOUT_MS
+        });
+        checkCancelled(signal);
+        if (foreground.packageName !== escapedPackageName) {
+            stop("EXTERNAL_PACKAGE_MISMATCH", `External app foreground changed ${phase}: expected "${escapedPackageName}", got "${foreground.packageName}"`);
+        }
+        if (foreground.activity !== expectedActivity) {
+            stop("EXTERNAL_ACTIVITY_MISMATCH", `External Activity mismatch ${phase}: expected "${expectedActivity}", got "${foreground.activity}"`);
+        }
+    }
+    async runStep(stepIndex, step, escapedPackageName, signal) {
+        const { dependencies } = this;
+        await this.assertForeground(escapedPackageName, step.expectedActivity, "before the step", signal);
+        const layout = await dependencies.captureLayout("locate", EXTERNAL_OBSERVATION_TIMEOUT_MS, signal);
+        checkCancelled(signal);
+        if (step.action === "scrollTo") {
+            const scroll = await new ScrollToExecutor({
+                uiSnapshotProvider: dependencies.uiSnapshotProvider,
+                actionExecutor: dependencies.actionExecutor,
+                idleWaiter: dependencies.createIdleWaiter(escapedPackageName),
+                deviceSerial: dependencies.deviceSerial,
+                idle: dependencies.idle,
+                viewport: dependencies.viewport,
+                beforeSwipe: async () => {
+                    await this.assertForeground(escapedPackageName, step.expectedActivity, "during scrolling", signal);
+                    return dependencies.captureLayout("locate", EXTERNAL_OBSERVATION_TIMEOUT_MS, signal);
+                },
+                beforeMutation: () => this.assertForeground(escapedPackageName, step.expectedActivity, "before mutation", signal),
+                requireLiveContainerCapability: true
+            }).execute(externalStepToJourneyStep(step), signal, layout);
+            if (scroll.status === "cancelled")
+                cancelled();
+            if (scroll.status === "failed") {
+                stop(scroll.code, scroll.message, scroll.idle === undefined ? undefined : { idle: scroll.idle });
+            }
+        }
+        else {
+            const target = requireExternalTarget(layout, step, dependencies.viewport());
+            const action = await dependencies.actionExecutor.execute(externalStepToJourneyStep(step), target, signal);
+            if (action.status === "failed")
+                stop(action.code, action.message);
+        }
+        const idle = await dependencies
+            .createIdleWaiter(escapedPackageName)
+            .waitUntilIdle(dependencies.idle, signal);
+        if (idle.status === "cancelled")
+            cancelled();
+        if (idle.status === "timeout") {
+            await dependencies.onIdleTimeout?.(stepIndex, idle);
+            stop(idle.code, withIdleAdvice("External app layout did not become stable after step", idle), idleTimeoutDetails(idle));
+        }
+        checkCancelled(signal);
+        await this.evaluateExpect(step, escapedPackageName, signal);
+    }
+    async evaluateExpect(step, escapedPackageName, signal) {
+        const expect = step.expect;
+        if (expect === undefined)
+            return;
+        if (expect.type === "activity") {
+            const foreground = await this.dependencies.adb.foregroundComponent({
+                packageName: expect.packageName ?? escapedPackageName,
+                deviceSerial: this.dependencies.deviceSerial,
+                ...(signal === undefined ? {} : { signal }),
+                timeoutMs: expect.timeoutMs
+            });
+            checkCancelled(signal);
+            if (foreground.activity !== expect.value) {
+                stop("EXTERNAL_STEP_FAILED", `External expect Activity mismatch: expected "${expect.value}", got "${foreground.activity}"`);
+            }
+            return;
+        }
+        if (expect.type !== "element") {
+            stop("EXTERNAL_STEP_FAILED", "Logcat expectations are not supported for external steps");
+        }
+        const layout = await this.dependencies.captureLayout("expect", expect.timeoutMs, signal);
+        checkCancelled(signal);
+        const resolution = resolveLocator(layout, expect.locator, {
+            requireEnabled: false
+        });
+        if (expect.absent === true) {
+            if (resolution.status !== "failed"
+                || resolution.code !== "LOCATOR_NOT_FOUND"
+                || resolution.evidenceMismatch === true) {
+                stop("EXTERNAL_STEP_FAILED", resolution.status === "found"
+                    ? "External expect expected an absent element but it was found"
+                    : `External expect expected an absent element: ${resolution.message}`);
+            }
+            return;
+        }
+        if (resolution.status !== "found") {
+            stop("EXTERNAL_STEP_FAILED", `External expect element not found: ${resolution.message}`);
+        }
+        const mismatch = elementPredicateMismatch(resolution.element, expect);
+        if (mismatch !== undefined) {
+            stop("EXTERNAL_STEP_FAILED", `External expect element predicate mismatch: ${mismatch}`);
+        }
+    }
+}
+/**
+ * Polls the foreground package until `until` accepts it: bridge escape
+ * detection (`packageName !== target`) and return detection (`=== target`).
+ */
+export async function pollForegroundPackage(input) {
+    const deadline = input.clock.now() + input.timeoutMs;
+    while (input.clock.now() < deadline) {
+        if (input.signal?.aborted === true)
+            return { status: "cancelled" };
+        const foreground = await input.adb.foregroundComponent({
+            packageName: input.packageName,
+            deviceSerial: input.deviceSerial,
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+            timeoutMs: EXTERNAL_OBSERVATION_TIMEOUT_MS
+        });
+        if (input.until(foreground.packageName)) {
+            return { status: "matched", packageName: foreground.packageName };
+        }
+        await input.clock.sleep(Math.min(BRIDGE_POLL_INTERVAL_MS, Math.max(0, deadline - input.clock.now())), input.signal);
+    }
+    return { status: "timeout" };
+}
+/**
+ * The single bridge step flow for Replay and Generation: trigger, escape,
+ * policy check, external steps, return, and settle.
+ */
+export class BridgeRunner {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    async run(input) {
+        const { clock } = this.dependencies;
+        const timing = { actionMs: 0, waitMs: 0 };
+        const failed = (failure, idle) => ({
+            status: "failed",
+            ...failure,
+            ...(idle === undefined ? {} : { idle }),
+            timing
+        });
+        const cancelledOutcome = () => ({ status: "cancelled", timing });
+        const actionStartedAt = clock.now();
+        const action = await this.dependencies.actionExecutor.execute(input.trigger.step, input.trigger.target, input.signal);
+        timing.actionMs = clock.now() - actionStartedAt;
+        if (input.signal?.aborted === true)
+            return cancelledOutcome();
+        if (action.status === "failed") {
+            return failed({ code: action.code, message: action.message });
+        }
+        const waitStartedAt = clock.now();
+        const escaped = await pollForegroundPackage({
+            adb: this.dependencies.adb,
+            clock,
+            packageName: this.dependencies.packageName,
+            deviceSerial: this.dependencies.deviceSerial,
+            until: (packageName) => packageName !== this.dependencies.packageName,
+            timeoutMs: input.escapeTimeoutMs,
+            signal: input.signal
+        });
+        timing.waitMs += clock.now() - waitStartedAt;
+        if (escaped.status === "cancelled")
+            return cancelledOutcome();
+        if (escaped.status === "timeout") {
+            return failed({
+                code: "BRIDGE_NO_ESCAPE",
+                message: "Bridge trigger did not cause a package escape"
+            });
+        }
+        const rejected = input.acceptEscape(escaped.packageName);
+        if (rejected !== undefined)
+            return failed(rejected);
+        let externalSteps;
+        if (input.external.kind === "drive") {
+            const driven = await input.external.drive(escaped.packageName);
+            if (driven.status === "cancelled")
+                return cancelledOutcome();
+            if (driven.status === "failed") {
+                return failed({
+                    code: driven.code,
+                    message: driven.message,
+                    ...(driven.details === undefined ? {} : { details: driven.details })
+                });
+            }
+            externalSteps = driven.steps;
+        }
+        else {
+            externalSteps = await input.external.steps(escaped.packageName);
+            if (externalSteps !== undefined) {
+                const external = await this.dependencies.externalSteps.run(externalSteps, escaped.packageName, input.signal);
+                if (external.status === "cancelled")
+                    return cancelledOutcome();
+                if (external.status === "failed") {
+                    return failed({
+                        code: external.code,
+                        message: external.message,
+                        ...(external.details === undefined ? {} : { details: external.details })
+                    });
+                }
+            }
+        }
+        const returnStartedAt = clock.now();
+        const returned = await pollForegroundPackage({
+            adb: this.dependencies.adb,
+            clock,
+            packageName: this.dependencies.packageName,
+            deviceSerial: this.dependencies.deviceSerial,
+            until: (packageName) => packageName === this.dependencies.packageName,
+            timeoutMs: input.returnTimeoutMs,
+            signal: input.signal
+        });
+        timing.waitMs += clock.now() - returnStartedAt;
+        if (returned.status === "cancelled")
+            return cancelledOutcome();
+        if (returned.status === "timeout") {
+            return failed({
+                code: "BRIDGE_NOT_RETURNED",
+                message: "Foreground did not return to target package within the timeout"
+            });
+        }
+        const idleStartedAt = clock.now();
+        const idle = await this.dependencies.idleWaiter.waitUntilIdle(this.dependencies.idle, input.signal);
+        timing.waitMs += clock.now() - idleStartedAt;
+        if (idle.status === "cancelled")
+            return cancelledOutcome();
+        if (idle.status === "timeout") {
+            return failed({
+                code: idle.code,
+                message: withIdleAdvice("Layout did not become stable after bridge return", idle),
+                details: idleTimeoutDetails(idle)
+            }, idle);
+        }
+        return {
+            status: "returned",
+            escapedPackageName: escaped.packageName,
+            ...(externalSteps === undefined ? {} : { externalSteps }),
+            idle,
+            timing
+        };
+    }
+}

package/dist/application/interaction/fallback-resolver.d.ts

@@ -1,6 +1,8 @@
 import type { FailureCode } from "../../domain/failure.js";
 import type { JourneyStep } from "../../domain/journey.js";
-import type { AndroidCliPort, Point } from "../../ports/android-cli.js";
+import type { Point } from "../../domain/geometry.js";
+import type { AnnotatedScreenResolverPort } from "../../ports/annotated-screen-resolver.js";
+import type { ScreenshotPort } from "../../ports/screenshot.js";
 export type FallbackResolution = {
     status: "unavailable";
 } | {
@@ -17,8 +19,9 @@ export type FallbackResolution = {
     annotatedScreenshotPath?: string | undefined;
 };
 export declare class FallbackResolver {
-    private readonly androidCli;
+    private readonly screenshots;
+    private readonly annotatedScreens;
     private readonly deviceSerial;
-    constructor(androidCli: AndroidCliPort, deviceSerial: string);
+    constructor(screenshots: ScreenshotPort, annotatedScreens: AnnotatedScreenResolverPort, deviceSerial: string);
     resolve(step: JourneyStep, annotatedScreenshotPath: string, signal?: AbortSignal): Promise<FallbackResolution>;
 }

package/dist/application/interaction/fallback-resolver.js

@@ -1,8 +1,10 @@
 export class FallbackResolver {
-    androidCli;
+    screenshots;
+    annotatedScreens;
     deviceSerial;
-    constructor(androidCli, deviceSerial) {
-        this.androidCli = androidCli;
+    constructor(screenshots, annotatedScreens, deviceSerial) {
+        this.screenshots = screenshots;
+        this.annotatedScreens = annotatedScreens;
         this.deviceSerial = deviceSerial;
     }
     async resolve(step, annotatedScreenshotPath, signal) {
@@ -10,7 +12,7 @@ export class FallbackResolver {
             || step.fallback === undefined) {
             return { status: "unavailable" };
         }
-        const capture = await this.androidCli.captureScreen({
+        const capture = await this.screenshots.capture({
             outputPath: annotatedScreenshotPath,
             annotate: true,
             deviceSerial: this.deviceSerial,
@@ -24,7 +26,7 @@ export class FallbackResolver {
             };
         }
         try {
-            const point = await this.androidCli.resolveScreen(annotatedScreenshotPath, step.fallback.label, signal);
+            const point = await this.annotatedScreens.resolve(annotatedScreenshotPath, step.fallback.label, signal);
             return {
                 status: "found",
                 point,

package/dist/application/interaction/scroll-to-executor.d.ts

@@ -1,39 +1,53 @@
 import type { FailureCode } from "../../domain/failure.js";
 import type { JourneyStep } from "../../domain/journey.js";
 import type { LayoutElement } from "../../domain/layout.js";
-import type { AndroidCliPort } from "../../ports/android-cli.js";
-import type { IdleConfig, IdleWaiter } from "../wait/idle-waiter.js";
+import type { DisplayViewport } from "../../domain/geometry.js";
+import type { AnchorResolverPort } from "../../ports/anchor-resolver.js";
+import type { UiSnapshotProvider } from "../../ports/ui-snapshot.js";
+import type { IdleBackend, IdleConfig, IdleStrategy, IdleWaiter } from "../wait/idle-waiter.js";
 import type { ActionExecutor } from "./action-executor.js";
 export type ScrollToExecutionResult = {
     status: "found";
     swipesUsed: number;
+    idleDurationMs: number;
 } | {
     status: "failed";
     code: FailureCode;
     message: string;
     swipesUsed: number;
+    idleDurationMs: number;
     idle?: {
         polls: number;
+        durationMs: number;
+        samplingDurationMs: number;
+        strategy: IdleStrategy;
+        backend?: IdleBackend | undefined;
+        fallbackUsed: boolean;
+        frameActivityDetected: boolean;
         lastDiff: readonly unknown[];
     };
 } | {
     status: "cancelled";
     swipesUsed: number;
+    idleDurationMs: number;
 };
 export interface ScrollToExecutorOptions {
-    androidCli: Pick<AndroidCliPort, "layout">;
+    uiSnapshotProvider: UiSnapshotProvider;
     actionExecutor: Pick<ActionExecutor, "swipeBounds">;
     idleWaiter: Pick<IdleWaiter, "waitUntilIdle">;
     deviceSerial: string;
     idle: IdleConfig;
+    anchorResolver?: AnchorResolverPort | undefined;
     readLayout?: (() => Promise<readonly LayoutElement[]>) | undefined;
     beforeSwipe?: (() => Promise<readonly LayoutElement[]>) | undefined;
     beforeMutation?: (() => Promise<void>) | undefined;
     requireLiveContainerCapability?: boolean | undefined;
+    viewport?: (() => DisplayViewport | undefined) | undefined;
 }
 export declare class ScrollToExecutor {
     private readonly options;
     constructor(options: ScrollToExecutorOptions);
+    private resolveTarget;
     execute(step: Extract<JourneyStep, {
         action: "scrollTo";
     }>, signal?: AbortSignal, initialLayout?: readonly LayoutElement[]): Promise<ScrollToExecutionResult>;