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

package/dist/application/recognition/screen-detector.js

@@ -0,0 +1,111 @@
+import { resolveLocatorIdentity } from "../locator/locator-resolver.js";
+function matchesWindow(value, anchor) {
+    return (anchor.title === undefined || value.title === anchor.title)
+        && (anchor.packageName === undefined
+            || value.packageName === anchor.packageName)
+        && (anchor.type === undefined || value.type === anchor.type);
+}
+function matchAnchor(snapshot, anchor) {
+    switch (anchor.identity.kind) {
+        case "activity":
+            return {
+                anchorId: anchor.id,
+                result: snapshot.activity === anchor.identity.activity
+                    ? "matched"
+                    : "missing"
+            };
+        case "window": {
+            const hierarchy = snapshot.windowHierarchy;
+            const identity = anchor.identity;
+            if (hierarchy === undefined || hierarchy.status === "unknown") {
+                return {
+                    anchorId: anchor.id,
+                    result: "unknown",
+                    detail: "Runtime window hierarchy is unavailable"
+                };
+            }
+            const matches = hierarchy.appWindows.filter((window) => matchesWindow(window, identity));
+            return {
+                anchorId: anchor.id,
+                result: matches.length === 0
+                    ? "missing"
+                    : matches.length === 1 ? "matched" : "ambiguous"
+            };
+        }
+        case "element": {
+            const resolution = resolveLocatorIdentity(snapshot.layout, anchor.identity.locator);
+            if (resolution.status === "found") {
+                return { anchorId: anchor.id, result: "matched" };
+            }
+            return {
+                anchorId: anchor.id,
+                result: resolution.code === "LOCATOR_AMBIGUOUS"
+                    ? "ambiguous"
+                    : resolution.code === "LOCATOR_NOT_FOUND" ? "missing" : "unknown",
+                detail: resolution.message
+            };
+        }
+    }
+}
+function predicateResult(predicate, snapshot, evidence) {
+    if (predicate.kind === "activityIs") {
+        return snapshot.activity === predicate.activity ? "match" : "noMatch";
+    }
+    const anchor = evidence.get(predicate.anchorId);
+    if (anchor === undefined || anchor.result === "unknown")
+        return "unknown";
+    if (anchor.result === "ambiguous")
+        return "unknown";
+    if (predicate.kind === "anchorAbsent") {
+        return anchor.result === "missing" ? "match" : "noMatch";
+    }
+    return anchor.result === "matched" ? "match" : "noMatch";
+}
+function screenResult(screen, snapshot, evidence) {
+    let unknown = false;
+    for (const anchorId of screen.requiredAnchors) {
+        const result = evidence.get(anchorId)?.result;
+        if (result === "missing")
+            return "noMatch";
+        if (result !== "matched")
+            unknown = true;
+    }
+    for (const anchorId of screen.forbiddenAnchors) {
+        const result = evidence.get(anchorId)?.result;
+        if (result === "matched")
+            return "noMatch";
+        if (result !== "missing")
+            unknown = true;
+    }
+    for (const predicate of screen.predicates) {
+        const result = predicateResult(predicate, snapshot, evidence);
+        if (result === "noMatch")
+            return "noMatch";
+        if (result === "unknown")
+            unknown = true;
+    }
+    return unknown ? "unknown" : "match";
+}
+export class ScreenDetector {
+    detect = (input) => {
+        const evidence = input.anchors.map((anchor) => matchAnchor(input.snapshot, anchor));
+        const byAnchor = new Map(evidence.map((result) => [result.anchorId, result]));
+        const results = input.screens.map((screen) => ({
+            screen,
+            result: screenResult(screen, input.snapshot, byAnchor)
+        }));
+        const matched = results
+            .filter((result) => result.result === "match")
+            .map((result) => result.screen.id)
+            .sort((left, right) => left.localeCompare(right));
+        const uncertain = results.some((result) => result.result === "unknown");
+        if (matched.length > 1) {
+            return { status: "ambiguous", screenIds: matched, evidence };
+        }
+        const screenId = matched[0];
+        if (screenId !== undefined && !uncertain) {
+            return { status: "matched", screenId, evidence };
+        }
+        return { status: "unknown", evidence };
+    };
+}

package/dist/application/recorder/locator-selector.js

@@ -1,21 +1,130 @@
 import { LOCATOR_FIELDS } from "../../domain/locator.js";
-function flatten(elements) {
-    return elements.flatMap((element) => [
-        element,
-        ...flatten(element.children)
-    ]);
+import { locatorEvidenceForElement } from "../../domain/locator-evidence.js";
+import { flattenLayout } from "../locator/layout-traversal.js";
+function buildLocatorIndex(entries) {
+    const positions = new Map();
+    const subtreeEnd = new Array(entries.length).fill(entries.length);
+    const byField = {
+        resourceId: new Map(),
+        text: new Map(),
+        contentDescription: new Map()
+    };
+    const open = [];
+    for (const [position, { element, ancestors }] of entries.entries()) {
+        if (!positions.has(element))
+            positions.set(element, position);
+        while (open.length > ancestors.length) {
+            const closed = open.pop();
+            if (closed !== undefined)
+                subtreeEnd[closed] = position;
+        }
+        open.push(position);
+        for (const field of LOCATOR_FIELDS) {
+            const value = element[field];
+            if (value === undefined || value.length === 0)
+                continue;
+            const list = byField[field].get(value);
+            if (list === undefined)
+                byField[field].set(value, [position]);
+            else
+                list.push(position);
+        }
+    }
+    return {
+        entries,
+        positions,
+        subtreeEnd,
+        byField,
+        globalLocators: new Map()
+    };
 }
-export function selectUniqueLocator(target, roots) {
-    const elements = flatten(roots);
+function lowerBound(sorted, value) {
+    let low = 0;
+    let high = sorted.length;
+    while (low < high) {
+        const middle = (low + high) >>> 1;
+        if ((sorted[middle] ?? Infinity) < value)
+            low = middle + 1;
+        else
+            high = middle;
+    }
+    return low;
+}
+function positionsInScope(sorted, scope) {
+    return sorted.slice(lowerBound(sorted, scope.start), lowerBound(sorted, scope.end));
+}
+function selectLocatorInScope(target, index, scope) {
     for (const field of LOCATOR_FIELDS) {
         const value = target[field];
         if (value !== undefined
             && value.length > 0
-            && elements.filter((element) => element[field] === value).length === 1) {
+            && positionsInScope(index.byField[field].get(value) ?? [], scope)
+                .length === 1) {
             return { [field]: value };
         }
     }
-    return undefined;
+    let candidates;
+    let locator = {};
+    for (const field of LOCATOR_FIELDS) {
+        const value = target[field];
+        if (value === undefined || value.length === 0) {
+            continue;
+        }
+        candidates = candidates === undefined
+            ? positionsInScope(index.byField[field].get(value) ?? [], scope)
+            : candidates.filter((position) => index.entries[position]?.element[field] === value);
+        locator = { ...locator, [field]: value };
+        if (candidates.length === 1) {
+            return locator;
+        }
+    }
+    if (candidates === undefined) {
+        return undefined;
+    }
+    const position = candidates.findIndex((candidate) => index.entries[candidate]?.element === target);
+    return position < 0
+        ? undefined
+        : {
+            ...locator,
+            index: position,
+            evidence: locatorEvidenceForElement(target)
+        };
+}
+function globalLocator(target, index) {
+    if (index.globalLocators.has(target)) {
+        return index.globalLocators.get(target);
+    }
+    const locator = selectLocatorInScope(target, index, { start: 0, end: index.entries.length });
+    index.globalLocators.set(target, locator);
+    return locator;
+}
+export function selectUniqueLocator(target, roots) {
+    return selectLocator(target, buildLocatorIndex(flattenLayout(roots)));
+}
+function selectLocator(target, index) {
+    const global = globalLocator(target, index);
+    if (global === undefined || global.index === undefined) {
+        return global === undefined ? undefined : { ...global };
+    }
+    const targetPosition = index.positions.get(target);
+    const ancestors = targetPosition === undefined
+        ? []
+        : index.entries[targetPosition]?.ancestors ?? [];
+    for (const ancestor of [...ancestors].reverse()) {
+        const within = globalLocator(ancestor, index);
+        const ancestorPosition = index.positions.get(ancestor);
+        if (within === undefined || ancestorPosition === undefined) {
+            continue;
+        }
+        const scoped = selectLocatorInScope(target, index, {
+            start: ancestorPosition + 1,
+            end: index.subtreeEnd[ancestorPosition] ?? ancestorPosition + 1
+        });
+        if (scoped !== undefined && scoped.index === undefined) {
+            return { ...scoped, within };
+        }
+    }
+    return { ...global };
 }
 function targetLabel(element, locator) {
     const identity = LOCATOR_FIELDS.find((field) => locator[field] !== undefined);
@@ -23,9 +132,19 @@ function targetLabel(element, locator) {
         return element.id;
     }
     const value = locator[identity] ?? element.id;
-    return `${element.id} — ${identity}: ${value}`;
+    const index = locator.index === undefined
+        ? ""
+        : ` [${String(locator.index)}]`;
+    const scope = locator.within === undefined
+        ? ""
+        : " within scoped container";
+    return `${element.id} — ${identity}: ${value}${index}${scope}`;
 }
 function supportsAction(element, action) {
+    const hasGeometry = element.center !== undefined
+        || element.bounds !== undefined;
+    if (!hasGeometry)
+        return false;
     return action === "click"
         ? element.clickable === true
         : action === "longClick"
@@ -33,11 +152,17 @@ function supportsAction(element, action) {
             : element.scrollable === true && element.bounds !== undefined;
 }
 export function listRecorderTargets(roots, action) {
-    const primary = flatten(roots).flatMap((element) => {
+    const entries = flattenLayout(roots);
+    const index = buildLocatorIndex(entries);
+    const locators = new Map(entries.map(({ element }) => [
+        element,
+        selectLocator(element, index)
+    ]));
+    const primary = entries.flatMap(({ element }) => {
         if (!element.enabled || !supportsAction(element, action)) {
             return [];
         }
-        const locator = selectUniqueLocator(element, roots);
+        const locator = locators.get(element);
         if (locator === undefined) {
             return [];
         }
@@ -53,25 +178,34 @@ export function listRecorderTargets(roots, action) {
     if (action !== "click") {
         return primary;
     }
-    const hasOrphan = flatten(roots).some((element) => element.enabled
+    const hasOrphan = entries.some(({ element }) => element.enabled
         && supportsAction(element, action)
-        && selectUniqueLocator(element, roots) === undefined);
+        && locators.get(element) === undefined);
     if (!hasOrphan) {
         return primary;
     }
     const primaryIds = new Set(primary.map((target) => target.element.id));
-    const relaxed = listLocatableTargets(roots).filter((target) => !supportsAction(target.element, action)
+    const relaxed = listLocatableTargetsFromEntries(entries, locators).filter((target) => !supportsAction(target.element, action)
         && !primaryIds.has(target.element.id)
         && (target.locator.text !== undefined
             || target.locator.contentDescription !== undefined));
     return [...primary, ...relaxed];
 }
 export function listLocatableTargets(roots) {
-    return flatten(roots).flatMap((element) => {
+    const entries = flattenLayout(roots);
+    const index = buildLocatorIndex(entries);
+    const locators = new Map(entries.map(({ element }) => [
+        element,
+        selectLocator(element, index)
+    ]));
+    return listLocatableTargetsFromEntries(entries, locators);
+}
+function listLocatableTargetsFromEntries(entries, locators) {
+    return entries.flatMap(({ element }) => {
         if (!element.enabled) {
             return [];
         }
-        const locator = selectUniqueLocator(element, roots);
+        const locator = locators.get(element);
         if (locator === undefined) {
             return [];
         }

package/dist/application/recorder/recorder-service.d.ts

@@ -1,13 +1,13 @@
 import type { TapHoundConfig } from "../../domain/config.js";
 import { type Journey } from "../../domain/journey.js";
-import type { AdbPort } from "../../ports/adb.js";
-import type { AndroidCliPort } from "../../ports/android-cli.js";
 import type { Clock } from "../../ports/clock.js";
 import type { JourneyWriterPort } from "../../ports/journey-writer.js";
+import type { RuntimeSessionOpener } from "../../ports/runtime-backend.js";
+import type { RuntimeSessionPortViewsFactory } from "../../ports/runtime-session-ports.js";
 import type { RecorderPromptPort } from "../../ports/recorder-prompt.js";
 export interface RecorderDependencies {
-    androidCli: AndroidCliPort;
-    adb: AdbPort;
+    sessions: RuntimeSessionOpener;
+    sessionPorts: RuntimeSessionPortViewsFactory;
     clock: Clock;
     prompt: RecorderPromptPort;
     journeyWriter: JourneyWriterPort;
@@ -38,4 +38,16 @@ export declare class RecorderService {
     record(input: RecordInput): Promise<RecordResult>;
     private prepareAction;
     private prepareScrollTo;
+    private recordBridgeStep;
+    /**
+     * Records External Steps one chosen step at a time. Each step (except
+     * `scrollTo`, which the person already scrolled while choosing it) runs
+     * through the same ExternalStepRunner Replay uses, so only a step that
+     * replays is recorded. Leaving the escaped app ends the list.
+     */
+    private recordExternalSteps;
+    private externalStepRunner;
+    private idleWaiter;
+    private prepareExternalStep;
+    private buildExternalStep;
 }