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

package/dist/application/ui/cached-ui-snapshot-provider.d.ts

@@ -0,0 +1,45 @@
+import type { CaptureUiSnapshotOptions, UiSnapshot, UiSnapshotProvider, UiSnapshotProviderFactory, OpenUiSnapshotProviderOptions } from "../../ports/ui-snapshot.js";
+import type { UiStabilityProbe, UiStabilitySampleOptions, UiStabilitySampleResult } from "../../ports/ui-stability.js";
+type InvalidationReason = Parameters<NonNullable<UiSnapshotProvider["invalidate"]>>[0];
+export declare class CachedUiSnapshotProviderFactory implements UiSnapshotProviderFactory {
+    private readonly source;
+    private readonly now;
+    private readonly ttlMs;
+    constructor(source: UiSnapshotProviderFactory, now?: () => number, ttlMs?: number);
+    open(options: OpenUiSnapshotProviderOptions): Promise<UiSnapshotProvider>;
+}
+export declare class CachedUiSnapshotProvider implements UiSnapshotProvider, Partial<UiStabilityProbe> {
+    private readonly source;
+    private readonly now;
+    private readonly ttlMs;
+    readonly descriptor: {
+        id: "system-uiautomator" | "android-cli" | "appium-uiautomator2" | "mobile-mcp";
+        adapterVersion: string;
+        configSha256: string;
+        engineVersion?: string | undefined;
+    };
+    readonly supportsStability: boolean;
+    private mutationEpoch;
+    private cached;
+    private inFlight;
+    private closed;
+    private closePromise;
+    private hits;
+    private misses;
+    private capturesSaved;
+    constructor(source: UiSnapshotProvider, now?: () => number, ttlMs?: number);
+    reset(): void;
+    sample(options: UiStabilitySampleOptions): Promise<UiStabilitySampleResult>;
+    capture(options: CaptureUiSnapshotOptions): Promise<UiSnapshot>;
+    invalidate(reason: InvalidationReason): void;
+    close(): Promise<void>;
+    cacheTelemetry(): {
+        hits: number;
+        misses: number;
+        stale: number;
+        relearns: number;
+        capturesSaved: number;
+        validationDurationMs: number;
+    };
+}
+export {};

package/dist/application/ui/cached-ui-snapshot-provider.js

@@ -0,0 +1,111 @@
+export class CachedUiSnapshotProviderFactory {
+    source;
+    now;
+    ttlMs;
+    constructor(source, now = () => Date.now(), ttlMs = 300) {
+        this.source = source;
+        this.now = now;
+        this.ttlMs = ttlMs;
+    }
+    async open(options) {
+        const provider = await this.source.open(options);
+        return options.cacheEnabled === false
+            ? provider
+            : new CachedUiSnapshotProvider(provider, this.now, this.ttlMs);
+    }
+}
+export class CachedUiSnapshotProvider {
+    source;
+    now;
+    ttlMs;
+    descriptor;
+    supportsStability;
+    mutationEpoch = 0;
+    cached;
+    inFlight;
+    closed = false;
+    closePromise;
+    hits = 0;
+    misses = 0;
+    capturesSaved = 0;
+    constructor(source, now = () => Date.now(), ttlMs = 300) {
+        this.source = source;
+        this.now = now;
+        this.ttlMs = ttlMs;
+        this.descriptor = source.descriptor;
+        const sourceProbe = source;
+        this.supportsStability = typeof sourceProbe.sample === "function"
+            && typeof sourceProbe.reset === "function";
+    }
+    reset() {
+        const sourceProbe = this.source;
+        sourceProbe.reset?.();
+    }
+    sample(options) {
+        const sourceProbe = this.source;
+        const sample = sourceProbe.sample;
+        if (sample === undefined) {
+            return Promise.reject(new Error("Underlying UI snapshot provider does not support stability sampling"));
+        }
+        return sample.call(sourceProbe, options);
+    }
+    capture(options) {
+        if (this.closed) {
+            return Promise.reject(new Error("UI snapshot provider is closed"));
+        }
+        const freshness = options.freshness ?? "forceFresh";
+        const epoch = this.mutationEpoch;
+        if (freshness === "sameMutationEpoch") {
+            if (this.cached?.epoch === epoch
+                && this.now() - this.cached.storedAtMs <= this.ttlMs) {
+                this.hits += 1;
+                this.capturesSaved += 1;
+                return Promise.resolve(this.cached.snapshot);
+            }
+            if (this.inFlight?.epoch === epoch) {
+                this.hits += 1;
+                this.capturesSaved += 1;
+                return this.inFlight.promise;
+            }
+        }
+        this.misses += 1;
+        const promise = this.source.capture(options).then((snapshot) => {
+            if (!this.closed && this.mutationEpoch === epoch) {
+                this.cached = { epoch, storedAtMs: this.now(), snapshot };
+            }
+            return snapshot;
+        }).finally(() => {
+            if (this.inFlight?.promise === promise) {
+                this.inFlight = undefined;
+            }
+        });
+        if (freshness === "sameMutationEpoch") {
+            this.inFlight = { epoch, promise };
+        }
+        return promise;
+    }
+    invalidate(reason) {
+        void reason;
+        this.mutationEpoch += 1;
+        this.cached = undefined;
+        this.inFlight = undefined;
+    }
+    close() {
+        if (this.closePromise !== undefined)
+            return this.closePromise;
+        this.closed = true;
+        this.invalidate("providerClosed");
+        this.closePromise = this.source.close();
+        return this.closePromise;
+    }
+    cacheTelemetry() {
+        return {
+            hits: this.hits,
+            misses: this.misses,
+            stale: 0,
+            relearns: 0,
+            capturesSaved: this.capturesSaved,
+            validationDurationMs: 0
+        };
+    }
+}

package/dist/application/ui/observed-ui-snapshot-provider.d.ts

@@ -0,0 +1,15 @@
+import type { UiCaptureObserver } from "../../ports/diagnostics.js";
+import type { OpenUiSnapshotProviderOptions, UiSnapshotProvider, UiSnapshotProviderFactory } from "../../ports/ui-snapshot.js";
+/**
+ * Reports the duration and outcome of every UI backend read (captures and
+ * stability samples) to an observer. It sits under the snapshot cache, so a
+ * cache hit is not counted as a device read.
+ */
+export declare class ObservedUiSnapshotProviderFactory implements UiSnapshotProviderFactory {
+    private readonly source;
+    private readonly observer;
+    private readonly now;
+    constructor(source: UiSnapshotProviderFactory, observer: UiCaptureObserver, now: () => number);
+    open(options: OpenUiSnapshotProviderOptions): Promise<UiSnapshotProvider>;
+}
+export declare function observeProvider(provider: UiSnapshotProvider, observer: UiCaptureObserver, now: () => number): UiSnapshotProvider;

package/dist/application/ui/observed-ui-snapshot-provider.js

@@ -0,0 +1,66 @@
+/**
+ * Reports the duration and outcome of every UI backend read (captures and
+ * stability samples) to an observer. It sits under the snapshot cache, so a
+ * cache hit is not counted as a device read.
+ */
+export class ObservedUiSnapshotProviderFactory {
+    source;
+    observer;
+    now;
+    constructor(source, observer, now) {
+        this.source = source;
+        this.observer = observer;
+        this.now = now;
+    }
+    async open(options) {
+        return observeProvider(await this.source.open(options), this.observer, this.now);
+    }
+}
+export function observeProvider(provider, observer, now) {
+    const source = provider;
+    const timed = async (read) => {
+        const startedAt = now();
+        try {
+            const value = await read();
+            observer.captured(source.descriptor.id, now() - startedAt);
+            return value;
+        }
+        catch (error) {
+            observer.captured(source.descriptor.id, now() - startedAt, error);
+            throw error;
+        }
+    };
+    const cacheTelemetry = source.cacheTelemetry;
+    const invalidate = source.invalidate;
+    const observed = {
+        descriptor: source.descriptor,
+        capture: (options) => timed(() => source.capture(options)),
+        close: () => source.close(),
+        ...(cacheTelemetry === undefined
+            ? {}
+            : { cacheTelemetry: () => cacheTelemetry.call(source) }),
+        ...(invalidate === undefined
+            ? {}
+            : {
+                invalidate: (reason) => {
+                    invalidate.call(source, reason);
+                }
+            })
+    };
+    const sample = source.sample;
+    const reset = source.reset;
+    if (typeof sample === "function" && typeof reset === "function") {
+        observed.sample = (options) => timed(() => sample.call(source, options));
+        observed.reset = () => {
+            reset.call(source);
+        };
+    }
+    const withSupport = source;
+    if (withSupport.supportsStability !== undefined) {
+        Object.defineProperty(observed, "supportsStability", {
+            value: withSupport.supportsStability,
+            enumerable: true
+        });
+    }
+    return observed;
+}

package/dist/application/ui/ui-snapshot-lifecycle.d.ts

@@ -0,0 +1,2 @@
+import type { UiSnapshotProvider } from "../../ports/ui-snapshot.js";
+export declare function closeUiSnapshotProvider(provider: UiSnapshotProvider, onFailure?: (error: unknown) => void): Promise<void>;

package/dist/application/ui/ui-snapshot-lifecycle.js

@@ -0,0 +1,8 @@
+export async function closeUiSnapshotProvider(provider, onFailure) {
+    try {
+        await provider.close();
+    }
+    catch (error) {
+        onFailure?.(error);
+    }
+}

package/dist/application/ui/ui-stability-probe.d.ts

@@ -0,0 +1,9 @@
+import type { UiSnapshotProvider } from "../../ports/ui-snapshot.js";
+import type { UiStabilityProbe } from "../../ports/ui-stability.js";
+/**
+ * A snapshot provider that samples stability itself (Appium) answers every
+ * structural sample, but frame-stat samples still go to the runtime probe:
+ * the provider only knows page sources, so it would answer a cheap
+ * `dumpsys gfxinfo` request with a full hierarchy capture.
+ */
+export declare function uiStabilityProbe(provider: UiSnapshotProvider, fallback: UiStabilityProbe): UiStabilityProbe;

package/dist/application/ui/ui-stability-probe.js

@@ -0,0 +1,24 @@
+/**
+ * A snapshot provider that samples stability itself (Appium) answers every
+ * structural sample, but frame-stat samples still go to the runtime probe:
+ * the provider only knows page sources, so it would answer a cheap
+ * `dumpsys gfxinfo` request with a full hierarchy capture.
+ */
+export function uiStabilityProbe(provider, fallback) {
+    const withCapability = provider;
+    if (withCapability.supportsStability === false
+        || typeof withCapability.sample !== "function"
+        || typeof withCapability.reset !== "function") {
+        return fallback;
+    }
+    const structural = withCapability;
+    return {
+        reset: () => {
+            structural.reset();
+            fallback.reset();
+        },
+        sample: (options) => (options.stabilityBackend === "frameStats"
+            ? fallback.sample(options)
+            : structural.sample(options))
+    };
+}

package/dist/application/wait/idle-advice.d.ts

@@ -0,0 +1,6 @@
+import type { IdleResult } from "./idle-waiter.js";
+export type IdleTimeoutResult = Extract<IdleResult, {
+    status: "timeout";
+}>;
+export declare function idleTimeoutAdvice(idle: IdleTimeoutResult): string;
+export declare function withIdleAdvice(message: string, idle: IdleTimeoutResult): string;

package/dist/application/wait/idle-advice.js

@@ -0,0 +1,27 @@
+const SLOW_CAPTURE_BUDGET_RATIO = 0.8;
+export function idleTimeoutAdvice(idle) {
+    if (idle.frameActivityDetected) {
+        return `frame activity never settled under idle.strategy "${idle.strategy}"; `
+            + "if the screen animates continuously, set idle.strategy to "
+            + "\"layoutDiff\" in .taphound/config.json";
+    }
+    if (idle.lastDiff.length > 0) {
+        return "layout differences kept appearing (see lastDiff in the step "
+            + "report); raise idle.timeoutMs in .taphound/config.json if the "
+            + "change is expected to settle, or set idle.strategy to "
+            + "\"layoutDiff\" if the screen animates continuously";
+    }
+    if (idle.durationMs > 0
+        && idle.samplingDurationMs >= idle.durationMs * SLOW_CAPTURE_BUDGET_RATIO) {
+        return "UI snapshot captures consumed most of the idle budget; raise "
+            + "idle.timeoutMs in .taphound/config.json so idle.stablePolls "
+            + "consecutive polls fit, and raise ui.snapshotTimeoutMs if "
+            + "individual dumps are slow";
+    }
+    return "no layout change was detected but the idle budget ended before "
+        + "idle.stablePolls consecutive stable polls; raise idle.timeoutMs or "
+        + "lower idle.stablePolls/pollIntervalMs in .taphound/config.json";
+}
+export function withIdleAdvice(message, idle) {
+    return `${message} (${idleTimeoutAdvice(idle)})`;
+}

package/dist/application/wait/idle-profiles.d.ts

@@ -0,0 +1,15 @@
+import type { DeviceIdleProfile } from "../../domain/config.js";
+import type { AdbPort, AppIdentity, DeviceIdentity } from "../../ports/adb.js";
+export type IdleStrategyName = "hybrid" | "layoutDiff" | "frameStats" | "structural";
+export interface IdleSettings {
+    strategy?: IdleStrategyName | undefined;
+    pollIntervalMs: number;
+    stablePolls: number;
+    timeoutMs: number;
+    ignoreCursorBlink?: boolean | undefined;
+    ignoreLayoutDrift?: boolean | undefined;
+}
+export declare function resolveIdlePolicy(idle: IdleSettings & {
+    deviceProfiles?: readonly DeviceIdleProfile[] | undefined;
+}, identity: DeviceIdentity | undefined): IdleSettings;
+export declare function deviceIdentityResolver(adb: Pick<AdbPort, "deviceIdentity">, identity: Omit<AppIdentity, "signal">): () => Promise<DeviceIdentity | undefined>;

package/dist/application/wait/idle-profiles.js

@@ -0,0 +1,75 @@
+function matchesDevice(profile, identity) {
+    const match = profile.match;
+    if (match.manufacturer !== undefined
+        && match.manufacturer.toLowerCase() !== identity.manufacturer.toLowerCase()) {
+        return false;
+    }
+    if (match.model !== undefined
+        && match.model.toLowerCase() !== identity.model.toLowerCase()) {
+        return false;
+    }
+    if (match.sdkLevel !== undefined && match.sdkLevel !== identity.sdkLevel) {
+        return false;
+    }
+    return true;
+}
+export function resolveIdlePolicy(idle, identity) {
+    if (identity === undefined || idle.deviceProfiles === undefined) {
+        return idle;
+    }
+    const matches = idle.deviceProfiles.filter((profile) => matchesDevice(profile, identity));
+    if (matches.length === 0) {
+        return idle;
+    }
+    const merged = {
+        strategy: idle.strategy,
+        pollIntervalMs: idle.pollIntervalMs,
+        stablePolls: idle.stablePolls,
+        timeoutMs: idle.timeoutMs,
+        ...(idle.ignoreCursorBlink === undefined
+            ? {}
+            : { ignoreCursorBlink: idle.ignoreCursorBlink }),
+        ...(idle.ignoreLayoutDrift === undefined
+            ? {}
+            : { ignoreLayoutDrift: idle.ignoreLayoutDrift })
+    };
+    for (const profile of matches) {
+        if (profile.ignoreCursorBlink !== undefined) {
+            merged.ignoreCursorBlink = profile.ignoreCursorBlink;
+        }
+        if (profile.ignoreLayoutDrift !== undefined) {
+            merged.ignoreLayoutDrift = profile.ignoreLayoutDrift;
+        }
+        if (profile.strategy !== undefined) {
+            merged.strategy = profile.strategy;
+        }
+        if (profile.pollIntervalMs !== undefined) {
+            merged.pollIntervalMs = profile.pollIntervalMs;
+        }
+        if (profile.stablePolls !== undefined) {
+            merged.stablePolls = profile.stablePolls;
+        }
+        if (profile.timeoutMs !== undefined) {
+            merged.timeoutMs = profile.timeoutMs;
+        }
+    }
+    return merged;
+}
+export function deviceIdentityResolver(adb, identity) {
+    // Device identity is immutable for a run; only a successful lookup is
+    // memoized so a transient getprop failure is retried on the next wait.
+    let resolved;
+    return async () => {
+        if (resolved !== undefined) {
+            return resolved;
+        }
+        const current = adb.deviceIdentity;
+        if (current === undefined) {
+            return undefined;
+        }
+        const requested = { ...identity };
+        resolved = await current.call(adb, requested)
+            .catch(() => undefined);
+        return resolved;
+    };
+}

package/dist/application/wait/idle-waiter.d.ts

@@ -1,30 +1,54 @@
 import type { FailureCode } from "../../domain/failure.js";
-import type { AndroidCliPort } from "../../ports/android-cli.js";
+import type { LayoutElement } from "../../domain/layout.js";
+import type { DeviceIdleProfile } from "../../domain/config.js";
+import type { DeviceIdentity } from "../../ports/adb.js";
+import type { UiStabilityProbe } from "../../ports/ui-stability.js";
 import type { Clock } from "../../ports/clock.js";
+export type IdleStrategy = "hybrid" | "layoutDiff" | "frameStats" | "structural";
+export type IdleBackend = "uiautomator" | "androidCli" | "gfxFrameStats" | "mobileMcp";
 export interface IdleConfig {
+    strategy?: IdleStrategy | undefined;
     pollIntervalMs: number;
     stablePolls: number;
     timeoutMs: number;
+    ignoreCursorBlink?: boolean | undefined;
+    ignoreLayoutDrift?: boolean | undefined;
+    deviceProfiles?: readonly DeviceIdleProfile[] | undefined;
 }
 export type IdleResult = {
     status: "stable";
     polls: number;
     durationMs: number;
+    layout?: readonly LayoutElement[] | undefined;
+    backend?: IdleBackend | undefined;
+    strategy: IdleStrategy;
+    fallbackUsed: boolean;
+    frameActivityDetected: boolean;
+    samplingDurationMs: number;
 } | {
     status: "timeout";
     code: Extract<FailureCode, "IDLE_TIMEOUT">;
     polls: number;
     durationMs: number;
     lastDiff: readonly unknown[];
+    backend?: IdleBackend | undefined;
+    strategy: IdleStrategy;
+    fallbackUsed: boolean;
+    frameActivityDetected: boolean;
+    samplingDurationMs: number;
 } | {
     status: "cancelled";
     polls: number;
     durationMs: number;
 };
 export declare class IdleWaiter {
-    private readonly androidCli;
+    private readonly stability;
     private readonly clock;
     private readonly deviceSerial;
-    constructor(androidCli: AndroidCliPort, clock: Clock, deviceSerial: string);
-    waitUntilIdle(config: IdleConfig, signal?: AbortSignal): Promise<IdleResult>;
+    private readonly packageName?;
+    private readonly resolveDeviceIdentity?;
+    private transientKeys;
+    constructor(stability: UiStabilityProbe, clock: Clock, deviceSerial: string, packageName?: string | undefined, resolveDeviceIdentity?: (() => Promise<DeviceIdentity | undefined>) | undefined);
+    waitUntilIdle(input: IdleConfig, signal?: AbortSignal): Promise<IdleResult>;
+    private effectiveConfig;
 }