taphound 0.2.0-dev.1 → 0.2.0-dev.11

package/dist/application/generation/runtime-observer.js

@@ -2,9 +2,14 @@ import { z } from "zod";
 import { primaryAppPid } from "../../domain/app-process.js";
 import { GenerationSessionIdSchema, GenerationSessionSchema } from "../../domain/generation.js";
 import { LayoutElementSchema } from "../../domain/layout.js";
+import { uiBackendIdAsSelection } from "../../domain/ui-backend.js";
 import { ProposalBindingSchema } from "../../domain/proposed-step.js";
 import { RuntimeSnapshotSchema, hashRuntimeSnapshot } from "../../domain/runtime-snapshot.js";
+import { assessWindowHierarchy } from "../../domain/window-hierarchy.js";
+import { withIdleAdvice } from "../wait/idle-advice.js";
 import { GenerationOperationError } from "./generation-starter.js";
+import { closeUiSnapshotProvider } from "../ui/ui-snapshot-lifecycle.js";
+import { uiStabilityProbe } from "../ui/ui-stability-probe.js";
 function failedCapture(result) {
     return result.exitCode !== 0
         || result.timedOut
@@ -15,9 +20,11 @@ function revisionPath(revision) {
     return `evidence/snapshots/revision-${String(revision).padStart(6, "0")}`;
 }
 function assertObservable(session) {
+    if (session.pendingConfirmation !== null) {
+        throw new GenerationOperationError("RISK_CONFIRMATION_REQUIRED", `Generation confirmation ${session.pendingConfirmation.challengeId} must be resolved before observation`, { challenge: session.pendingConfirmation });
+    }
     if (session.state !== "active"
-        || session.inFlight !== null
-        || session.pendingConfirmation !== null) {
+        || session.inFlight !== null) {
         throw new Error("Generation session must be active and idle to observe");
     }
     if (session.revision === Number.MAX_SAFE_INTEGER) {
@@ -30,17 +37,45 @@ async function collectRuntime(dependencies, session, signal) {
         deviceSerial: session.target.deviceSerial,
         ...(signal === undefined ? {} : { signal })
     };
-    const foreground = await dependencies.adb.foregroundComponent(identity);
-    const pid = primaryAppPid(await dependencies.adb.appProcesses(identity), session.target.packageName);
-    const layout = z.array(LayoutElementSchema).parse(await dependencies.androidCli.layout({
-        deviceSerial: session.target.deviceSerial,
-        ...(signal === undefined ? {} : { signal })
-    }));
+    const [foregroundResult, processesResult, topologyResult, snapshotResult] = await Promise.allSettled([
+        dependencies.adb.foregroundComponent(identity),
+        dependencies.adb.appProcesses(identity),
+        dependencies.adb.windowTopology(identity),
+        dependencies.uiSnapshotProvider.capture({
+            reason: "evidence",
+            timeoutMs: dependencies.uiSnapshotTimeoutMs,
+            ...(signal === undefined ? {} : { signal })
+        })
+    ]);
+    const settledValue = (result) => {
+        if (result.status === "fulfilled") {
+            return result.value;
+        }
+        const reason = result.reason;
+        if (reason instanceof Error) {
+            throw reason;
+        }
+        throw new Error("Runtime observation failed");
+    };
+    const foreground = settledValue(foregroundResult);
+    const processes = settledValue(processesResult);
+    const topology = settledValue(topologyResult);
+    const uiSnapshot = settledValue(snapshotResult);
+    const pid = primaryAppPid(processes, session.target.packageName);
+    const layout = z.array(LayoutElementSchema).parse(uiSnapshot.roots);
     return {
         foregroundPackageName: foreground.packageName,
         activity: foreground.activity,
         pid,
-        layout
+        layout,
+        uiSnapshot: {
+            observationId: uiSnapshot.observationId,
+            capturedAt: uiSnapshot.capturedAt,
+            durationMs: uiSnapshot.durationMs,
+            backend: uiSnapshot.backend,
+            viewport: uiSnapshot.viewport
+        },
+        windowHierarchy: assessWindowHierarchy(topology, layout)
     };
 }
 export class RuntimeObserver {
@@ -51,16 +86,101 @@ export class RuntimeObserver {
     observe = async (input) => {
         const current = GenerationSessionSchema.parse(await this.dependencies.store.read(input.generationId));
         assertObservable(current);
-        const runtime = await collectRuntime(this.dependencies, current, input.signal);
+        const idle = current.idlePolicy === undefined
+            ? input.idle
+            : current.idlePolicy;
+        const session = await this.dependencies.sessions.openSession({
+            deviceSerial: current.target.deviceSerial,
+            ...(input.signal === undefined ? {} : { signal: input.signal })
+        });
+        try {
+            const views = this.dependencies.sessionPorts(session);
+            const boundBackendSelection = uiBackendIdAsSelection(current.bindings.uiBackend.id);
+            const uiSnapshotProvider = await session.openUiSnapshots({
+                timeoutMs: idle?.timeoutMs ?? 5000,
+                ...(boundBackendSelection === undefined
+                    ? {}
+                    : { backend: boundBackendSelection }),
+                ...(this.dependencies.uiCacheEnabled === undefined
+                    ? {}
+                    : { cacheEnabled: this.dependencies.uiCacheEnabled }),
+                ...(input.signal === undefined ? {} : { signal: input.signal })
+            });
+            let runtime;
+            try {
+                if (JSON.stringify(current.bindings.uiBackend)
+                    !== JSON.stringify(uiSnapshotProvider.descriptor)) {
+                    throw new GenerationOperationError("CONFIG_INVALID", "Generation UI backend does not match the authoritative session");
+                }
+                if (idle !== undefined
+                    && this.dependencies.waitUntilIdle !== undefined) {
+                    const idleResult = await this.dependencies.waitUntilIdle(current.target.deviceSerial, idle, input.signal, current.target.packageName, uiStabilityProbe(uiSnapshotProvider, views.uiStability), views.adb);
+                    if (idleResult.status !== "stable") {
+                        throw new GenerationOperationError(idleResult.status === "cancelled" ? "RECOVERY_REQUIRED" : "IDLE_TIMEOUT", idleResult.status === "cancelled"
+                            ? "Runtime observation was cancelled while waiting for layout stability"
+                            : withIdleAdvice("Layout did not become stable before observation", idleResult), idleResult.status === "cancelled"
+                            ? undefined
+                            : {
+                                idle: {
+                                    strategy: idleResult.strategy,
+                                    ...(idleResult.backend === undefined
+                                        ? {}
+                                        : { backend: idleResult.backend }),
+                                    polls: idleResult.polls,
+                                    durationMs: idleResult.durationMs,
+                                    samplingDurationMs: idleResult.samplingDurationMs,
+                                    fallbackUsed: idleResult.fallbackUsed,
+                                    frameActivityDetected: idleResult.frameActivityDetected,
+                                    lastDiff: idleResult.lastDiff
+                                }
+                            });
+                    }
+                }
+                runtime = await collectRuntime({
+                    adb: views.adb,
+                    uiSnapshotProvider,
+                    uiSnapshotTimeoutMs: this.dependencies.uiSnapshotTimeoutMs ?? 5000
+                }, current, input.signal);
+            }
+            finally {
+                await closeUiSnapshotProvider(uiSnapshotProvider);
+            }
+            return await this.commit(current, runtime, views, input.signal);
+        }
+        finally {
+            await session.close();
+        }
+    };
+    observeCollected = async (input) => {
+        const current = GenerationSessionSchema.parse(await this.dependencies.store.read(input.generationId));
+        assertObservable(current);
+        if (input.runtime.foregroundPackageName !== current.target.packageName
+            || input.runtime.pid === null) {
+            throw new GenerationOperationError("SNAPSHOT_STALE", "Collected post-action runtime is not a valid target-app state");
+        }
+        const session = await this.dependencies.sessions.openSession({
+            deviceSerial: current.target.deviceSerial,
+            ...(input.signal === undefined ? {} : { signal: input.signal })
+        });
+        try {
+            const views = this.dependencies.sessionPorts(session);
+            return await this.commit(current, input.runtime, views, input.signal);
+        }
+        finally {
+            await session.close();
+        }
+    };
+    async commit(current, runtime, views, signal) {
         const baseRevision = current.revision + 1;
         const attemptId = GenerationSessionIdSchema.parse(this.dependencies.createAttemptId());
         const evidenceDirectory = `${revisionPath(baseRevision)}/${attemptId}`;
         const screenshotPath = `${evidenceDirectory}/screen.png`;
+        const snapshotPath = `${evidenceDirectory}/snapshot.json`;
         await this.dependencies.store.produceEvidence(current.id, screenshotPath, async (temporaryPath) => {
-            const capture = await this.dependencies.androidCli.captureScreen({
+            const capture = await views.screenshots.capture({
                 outputPath: temporaryPath,
                 deviceSerial: current.target.deviceSerial,
-                ...(input.signal === undefined ? {} : { signal: input.signal })
+                ...(signal === undefined ? {} : { signal })
             });
             if (failedCapture(capture)) {
                 throw new Error(capture.stderr.trim()
@@ -68,8 +188,23 @@ export class RuntimeObserver {
                     || "Runtime screenshot capture failed");
             }
         });
+        const identity = {
+            packageName: current.target.packageName,
+            deviceSerial: current.target.deviceSerial,
+            ...(signal === undefined ? {} : { signal })
+        };
+        const [confirmedForeground, confirmedProcesses] = await Promise.all([
+            views.adb.foregroundComponent(identity),
+            views.adb.appProcesses(identity)
+        ]);
+        const confirmedPid = primaryAppPid(confirmedProcesses, current.target.packageName);
+        if (confirmedForeground.packageName !== runtime.foregroundPackageName
+            || confirmedForeground.activity !== runtime.activity
+            || confirmedPid !== runtime.pid) {
+            throw new GenerationOperationError("SNAPSHOT_STALE", "Runtime identity changed while snapshot evidence was captured");
+        }
         const snapshot = RuntimeSnapshotSchema.parse({
-            version: 1,
+            version: 2,
             generationId: current.id,
             baseRevision,
             deviceSerial: current.target.deviceSerial,
@@ -77,21 +212,28 @@ export class RuntimeObserver {
             foregroundPackageName: runtime.foregroundPackageName,
             activity: runtime.activity,
             pid: runtime.pid,
-            capturedAt: this.dependencies.now().toISOString(),
+            capturedAt: runtime.uiSnapshot.capturedAt,
             screenshotPath,
-            layout: runtime.layout
+            layout: runtime.layout,
+            windowHierarchy: runtime.windowHierarchy,
+            uiBackend: runtime.uiSnapshot.backend,
+            uiObservationId: runtime.uiSnapshot.observationId,
+            uiCaptureDurationMs: runtime.uiSnapshot.durationMs,
+            viewport: runtime.uiSnapshot.viewport
         });
         const snapshotHash = hashRuntimeSnapshot(snapshot);
-        await this.dependencies.store.writeEvidence(current.id, `${evidenceDirectory}/snapshot.json`, snapshot);
+        await this.dependencies.store.writeEvidence(current.id, snapshotPath, snapshot);
         const next = GenerationSessionSchema.parse({
             ...current,
             revision: baseRevision,
             bindings: {
                 ...current.bindings,
-                snapshotHash
+                snapshotHash,
+                uiBackend: runtime.uiSnapshot.backend
             }
         });
         await this.dependencies.store.commitSnapshot(current.id, current.revision, next);
+        const snapshotRef = await this.dependencies.store.evidenceReference(current.id, snapshotPath);
         return {
             binding: {
                 generationId: current.id,
@@ -99,16 +241,17 @@ export class RuntimeObserver {
                 snapshotHash
             },
             snapshot,
-            snapshotHash
+            snapshotHash,
+            snapshotRef
         };
-    };
+    }
 }
 export class SnapshotReobservationGuard {
     dependencies;
     constructor(dependencies) {
         this.dependencies = dependencies;
     }
-    assertFresh = async (input, signal, approvedConfirmation) => {
+    assertFresh = async (input, signal, approvedConfirmation, tolerance) => {
         try {
             const binding = ProposalBindingSchema.parse(input);
             const session = GenerationSessionSchema.parse(await this.dependencies.store.read(binding.generationId));
@@ -127,9 +270,17 @@ export class SnapshotReobservationGuard {
                             !== JSON.stringify(approvedConfirmation)))) {
                 throw new GenerationOperationError("SNAPSHOT_STALE", "Proposal snapshot binding is no longer authoritative");
             }
-            const runtime = await collectRuntime(this.dependencies, session, signal);
+            if (JSON.stringify(session.bindings.uiBackend)
+                !== JSON.stringify(this.dependencies.uiSnapshotProvider.descriptor)) {
+                throw new GenerationOperationError("SNAPSHOT_STALE", "Generation UI backend changed after snapshot binding");
+            }
+            const runtime = await collectRuntime({
+                adb: this.dependencies.adb,
+                uiSnapshotProvider: this.dependencies.uiSnapshotProvider,
+                uiSnapshotTimeoutMs: this.dependencies.uiSnapshotTimeoutMs ?? 5000
+            }, session, signal);
             const snapshot = RuntimeSnapshotSchema.parse({
-                version: 1,
+                version: 2,
                 generationId: session.id,
                 baseRevision: binding.baseRevision,
                 deviceSerial: session.target.deviceSerial,
@@ -137,11 +288,29 @@ export class SnapshotReobservationGuard {
                 foregroundPackageName: runtime.foregroundPackageName,
                 activity: runtime.activity,
                 pid: runtime.pid,
-                capturedAt: this.dependencies.now().toISOString(),
+                capturedAt: runtime.uiSnapshot.capturedAt,
                 screenshotPath: "non-authoritative://runtime-reobservation",
-                layout: runtime.layout
+                layout: runtime.layout,
+                windowHierarchy: runtime.windowHierarchy,
+                uiBackend: runtime.uiSnapshot.backend,
+                uiObservationId: runtime.uiSnapshot.observationId,
+                uiCaptureDurationMs: runtime.uiSnapshot.durationMs,
+                viewport: runtime.uiSnapshot.viewport
             });
             if (hashRuntimeSnapshot(snapshot) !== binding.snapshotHash) {
+                // A targetless proposal (wait) does not consume the Layout, so a
+                // pure Layout change (for example a loading indicator that
+                // disappeared between binding and execution) is tolerated when the
+                // caller hands back the authoritative bound Snapshot and every
+                // other hashed field still matches. Any other drift stays
+                // fail-closed.
+                const bound = tolerance?.layoutChangeFrom;
+                if (bound !== undefined
+                    && hashRuntimeSnapshot(bound) === binding.snapshotHash
+                    && hashRuntimeSnapshot({ ...snapshot, layout: [] })
+                        === hashRuntimeSnapshot({ ...bound, layout: [] })) {
+                    return snapshot;
+                }
                 throw new GenerationOperationError("SNAPSHOT_STALE", "Runtime snapshot changed after proposal");
             }
             return snapshot;

package/dist/application/impact/impact-resolver.d.ts

@@ -0,0 +1,32 @@
+import { type ChangeSet, type ImpactSet } from "../../domain/impact.js";
+import type { Journey } from "../../domain/journey.js";
+import type { ProjectContextModule, ResolvedProjectContext } from "../../domain/project-context.js";
+import type { LoadedKnowledgeBundle } from "../../ports/knowledge-registry.js";
+export interface ImpactResolverDependencies {
+    loadContext: (input: {
+        projectRoot: string;
+    }) => Promise<{
+        context: ResolvedProjectContext;
+        modules: ProjectContextModule[];
+    }>;
+    loadKnowledge: (input: {
+        projectRoot: string;
+        packageName: string;
+    }) => Promise<LoadedKnowledgeBundle>;
+    listJourneyPaths: (input: {
+        projectRoot: string;
+    }) => Promise<readonly string[]>;
+    readJourney: (input: {
+        projectRoot: string;
+        path: string;
+    }) => Promise<Journey | null>;
+}
+export declare class ImpactResolver {
+    private readonly dependencies;
+    constructor(dependencies: ImpactResolverDependencies);
+    readonly resolve: (input: {
+        projectRoot: string;
+        packageName: string;
+        changeSet: ChangeSet;
+    }) => Promise<ImpactSet>;
+}

package/dist/application/impact/impact-resolver.js

@@ -0,0 +1,160 @@
+import { createHash } from "node:crypto";
+import { ImpactSetSchema } from "../../domain/impact.js";
+function unique(values) {
+    return [...new Set(values)];
+}
+function contextEvidenceHash(context, modules) {
+    const canonicalModules = modules
+        .map((module) => ({
+        moduleId: module.moduleId,
+        projectDir: module.projectDir,
+        inventory: module.inventory,
+        manifest: module.manifest
+    }))
+        .sort((left, right) => left.moduleId.localeCompare(right.moduleId));
+    const canonical = JSON.stringify({
+        selection: context.selection,
+        modules: canonicalModules
+    });
+    return createHash("sha256").update(canonical).digest("hex");
+}
+function journeyAnchorIds(journey) {
+    return journey.steps
+        .map((step) => ("anchor" in step && step.anchor !== undefined ? step.anchor : undefined))
+        .filter((id) => id !== undefined);
+}
+function moduleForChangedFiles(modules, changeSet) {
+    const changed = changeSet.files.flatMap((file) => [
+        file.path,
+        ...(file.oldPath === undefined ? [] : [file.oldPath])
+    ]);
+    const result = [];
+    for (const module of modules) {
+        const evidencePaths = new Set(module.manifest.files.map((file) => file.path));
+        const touched = changed.some((path) => (evidencePaths.has(path)
+            || (module.projectDir !== "."
+                && path.startsWith(`${module.projectDir}/`))));
+        if (touched) {
+            result.push(module.moduleId);
+        }
+    }
+    return result;
+}
+export class ImpactResolver {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    resolve = async (input) => {
+        const { projectRoot, packageName, changeSet } = input;
+        const [context, knowledge, journeyPaths] = await Promise.all([
+            this.dependencies.loadContext({
+                projectRoot
+            }),
+            this.dependencies.loadKnowledge({
+                projectRoot,
+                packageName
+            }),
+            this.dependencies.listJourneyPaths({
+                projectRoot
+            })
+        ]);
+        const contextModules = context.modules;
+        const changedPathSet = new Set(changeSet.files.flatMap((file) => [
+            file.path,
+            ...(file.oldPath === undefined ? [] : [file.oldPath])
+        ]));
+        const affectedModules = unique(moduleForChangedFiles(contextModules, changeSet));
+        const affectedAnchors = unique(knowledge.anchors
+            .filter((anchor) => ((anchor.sourceFiles ?? []).some((path) => changedPathSet.has(path))))
+            .map((anchor) => anchor.id));
+        const affectedAnchorsSet = new Set(affectedAnchors);
+        const affectedScreens = unique(knowledge.screens
+            .filter((screen) => ((screen.sourceFiles ?? []).some((path) => changedPathSet.has(path))
+            || screen.requiredAnchors.some((id) => affectedAnchorsSet.has(id))
+            || screen.optionalAnchors.some((id) => affectedAnchorsSet.has(id))
+            || screen.forbiddenAnchors.some((id) => affectedAnchorsSet.has(id))
+            || screen.predicates.some((predicate) => ("anchorId" in predicate
+                && affectedAnchorsSet.has(predicate.anchorId)))))
+            .map((screen) => screen.id));
+        const affectedScreensSet = new Set(affectedScreens);
+        const affectedModulesSet = new Set(affectedModules);
+        const affectedFeatures = unique(contextModules
+            .filter((module) => affectedModulesSet.has(module.moduleId))
+            .flatMap((module) => module.summary.features));
+        const p0 = [];
+        const p1 = [];
+        const p2 = [];
+        const skipped = [];
+        for (const path of journeyPaths) {
+            const journey = await this.dependencies.readJourney({
+                projectRoot,
+                path
+            });
+            if (journey === null) {
+                continue;
+            }
+            const anchorsInJourney = journeyAnchorIds(journey);
+            const directAnchor = anchorsInJourney.find((id) => (affectedAnchorsSet.has(id)));
+            if (directAnchor !== undefined) {
+                p0.push({
+                    id: path,
+                    reason: `journey resolves affected Knowledge anchor ${directAnchor}`
+                });
+                continue;
+            }
+            const affectedAnchorByScreen = anchorsInJourney.find((id) => (knowledge.screens.some((screen) => (affectedScreensSet.has(screen.id)
+                && (screen.requiredAnchors.includes(id)
+                    || screen.optionalAnchors.includes(id)
+                    || screen.forbiddenAnchors.includes(id))))));
+            if (affectedAnchorByScreen !== undefined) {
+                p1.push({
+                    id: path,
+                    reason: `journey anchors share a screen with the affected change ${affectedAnchorByScreen}`
+                });
+                continue;
+            }
+            if (anchorsInJourney.length === 0) {
+                if (affectedModules.length > 0) {
+                    p1.push({
+                        id: path,
+                        reason: "affected module requires conservative coverage for a locator-only journey"
+                    });
+                }
+                else {
+                    skipped.push({
+                        id: path,
+                        reason: "journey uses only runtime locators; no semantic anchor binding"
+                    });
+                }
+                continue;
+            }
+            if (affectedModules.length > 0) {
+                p1.push({
+                    id: path,
+                    reason: "affected module requires conservative semantic journey coverage"
+                });
+                continue;
+            }
+            p2.push({
+                id: path,
+                reason: "journey anchors do not resolve affected anchor/screen ids"
+            });
+        }
+        return ImpactSetSchema.parse({
+            version: 1,
+            base: changeSet.base,
+            head: changeSet.head,
+            affectedModules,
+            affectedFeatures,
+            affectedScreens,
+            affectedAnchors,
+            selectedJourneys: { p0, p1, p2 },
+            skippedJourneys: skipped,
+            provenance: {
+                contextHash: contextEvidenceHash(context.context, contextModules),
+                knowledgeHash: knowledge.knowledgeHash
+            }
+        });
+    };
+}

package/dist/application/init/init-service.js

@@ -9,34 +9,47 @@ export class InitService {
         if (input.agents.length === 0) {
             throw new NoAgentsSelectedError();
         }
-        const targets = resolveTargetPaths(input.agents, input.global, this.deps.cwd, this.deps.homedir);
-        const installedPaths = [];
-        const skippedPaths = [];
-        const allAgents = [];
+        const skillNames = await this.deps.installer.listSkillNames();
+        const targets = resolveTargetPaths(skillNames, input.agents, input.global, this.deps.cwd, this.deps.homedir);
+        const groupMap = new Map();
         for (const target of targets) {
-            const result = await this.deps.installer.installTo(target.absolutePath);
+            const result = await this.deps.installer.installTo(target.skillName, target.absolutePath);
+            let group = groupMap.get(target.skillName);
+            if (group === undefined) {
+                group = { name: target.skillName, paths: [], skipped: [] };
+                groupMap.set(target.skillName, group);
+            }
             if (result.skipped) {
-                skippedPaths.push(target.relativePath);
+                group.skipped.push(target.relativePath);
             }
             else {
-                installedPaths.push(target.relativePath);
+                group.paths.push(target.relativePath);
             }
+        }
+        const allAgents = [];
+        for (const target of targets) {
             for (const agent of target.agents) {
                 if (!allAgents.includes(agent)) {
                     allAgents.push(agent);
                 }
             }
         }
-        const result = {
+        const skills = [...groupMap.values()].map((group) => {
+            const skill = {
+                name: group.name,
+                paths: group.paths
+            };
+            if (group.skipped.length > 0) {
+                skill.skipped = group.skipped;
+            }
+            return skill;
+        });
+        return {
             status: "installed",
             exitCode: 0,
             agents: allAgents,
-            paths: installedPaths
+            skills
         };
-        if (skippedPaths.length > 0) {
-            return { ...result, skipped: skippedPaths };
-        }
-        return result;
     }
 }
 export function defaultHomedir() {

package/dist/application/interaction/action-executor.d.ts

@@ -2,7 +2,7 @@ import type { FailureCode } from "../../domain/failure.js";
 import type { JourneyStep } from "../../domain/journey.js";
 import type { Bounds } from "../../domain/layout.js";
 import type { AdbPort } from "../../ports/adb.js";
-import type { Point } from "../../ports/android-cli.js";
+import type { Point } from "../../domain/geometry.js";
 export interface ActionTarget {
     point: Point;
     bounds?: Bounds | undefined;
@@ -17,7 +17,8 @@ export type ActionExecutionResult = {
 export declare class ActionExecutor {
     private readonly adb;
     private readonly deviceSerial;
-    constructor(adb: AdbPort, deviceSerial: string);
+    private readonly beforeMutation?;
+    constructor(adb: AdbPort, deviceSerial: string, beforeMutation?: (() => void) | undefined);
     execute(step: JourneyStep, target?: ActionTarget, signal?: AbortSignal): Promise<ActionExecutionResult>;
     swipeBounds(bounds: Bounds, direction: Extract<JourneyStep, {
         action: "swipe";

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

@@ -52,9 +52,11 @@ function swipePoints(bounds, direction, distancePercent) {
 export class ActionExecutor {
     adb;
     deviceSerial;
-    constructor(adb, deviceSerial) {
+    beforeMutation;
+    constructor(adb, deviceSerial, beforeMutation) {
         this.adb = adb;
         this.deviceSerial = deviceSerial;
+        this.beforeMutation = beforeMutation;
     }
     async execute(step, target, signal) {
         let result;
@@ -63,15 +65,18 @@ export class ActionExecutor {
                 if (target === undefined) {
                     return failed("click requires a resolved target");
                 }
+                this.beforeMutation?.();
                 result = await this.adb.tap(target.point, this.deviceSerial, signal);
                 break;
             case "longClick":
                 if (target === undefined) {
                     return failed("longClick requires a resolved target");
                 }
+                this.beforeMutation?.();
                 result = await this.adb.longClick(target.point, step.durationMs, this.deviceSerial, signal);
                 break;
             case "inputText":
+                this.beforeMutation?.();
                 result = await this.adb.inputText(step.text, this.deviceSerial, signal);
                 break;
             case "swipe": {
@@ -82,12 +87,16 @@ export class ActionExecutor {
                     return failed("swipe requires target bounds from a scrollable element");
                 }
                 const points = swipePoints(target.bounds, step.direction, step.distancePercent);
+                this.beforeMutation?.();
                 result = await this.adb.swipe(points.from, points.to, step.durationMs, this.deviceSerial, signal);
                 break;
             }
             case "scrollTo":
                 return failed("scrollTo is not executed via ActionExecutor");
+            case "bridge":
+                return failed("bridge is not executed via ActionExecutor");
             case "back":
+                this.beforeMutation?.();
                 result = await this.adb.back(this.deviceSerial, signal);
                 break;
             case "wait":
@@ -97,6 +106,7 @@ export class ActionExecutor {
     }
     async swipeBounds(bounds, direction, distancePercent, durationMs, signal) {
         const points = swipePoints(bounds, direction, distancePercent);
+        this.beforeMutation?.();
         const result = await this.adb.swipe(points.from, points.to, durationMs, this.deviceSerial, signal);
         return commandResult(result);
     }

package/dist/application/interaction/action-target.d.ts

@@ -0,0 +1,17 @@
+import type { DisplayViewport } from "../../domain/geometry.js";
+import type { LayoutElement, Locator } from "../../domain/layout.js";
+import { type LocatedTarget, type LocatorFailure } from "../locator/locator-resolver.js";
+import type { ActionTarget } from "./action-executor.js";
+export type TargetedAction = "click" | "longClick" | "swipe";
+export type ActionTargetResolution = {
+    status: "found";
+    target: ActionTarget;
+    located: LocatedTarget;
+} | LocatorFailure;
+/**
+ * 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 declare function resolveActionTarget(layout: readonly LayoutElement[], action: TargetedAction, locator: Locator, viewport: DisplayViewport | undefined): ActionTargetResolution;