taphound 0.2.0-dev.11 → 0.2.0-dev.12

package/dist/application/diagnostics/diagnostics-exporter.js

@@ -0,0 +1,283 @@
+import { createHmac } from "node:crypto";
+import { join, resolve } from "node:path";
+import { TapHoundConfigSchema } from "../../domain/config.js";
+import { CommandEventSchema, DiagnosticsBundleSchema } from "../../domain/diagnostics.js";
+import { TapHoundReportSchema } from "../../domain/report.js";
+import { CONFIG_PATH, DEFAULT_ARTIFACTS_DIR } from "../../domain/workspace.js";
+const TOKEN = /^[a-zA-Z][a-zA-Z\d]{0,31}$/;
+const VERSION = /^[\w.+-]{1,64}$/;
+const TOOL_NAMES = ["node", "adb", "android"];
+const LOCATOR_FIELDS = ["resourceId", "text", "contentDescription", "index", "within"];
+/** Stable ordinal names for identifying strings, shared across one bundle. */
+class Aliases {
+    prefix;
+    values = new Map();
+    constructor(prefix) {
+        this.prefix = prefix;
+    }
+    of(value) {
+        let alias = this.values.get(value);
+        if (alias === undefined) {
+            alias = `${this.prefix}#${String(this.values.size + 1)}`;
+            this.values.set(value, alias);
+        }
+        return alias;
+    }
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, entry]) => [key, canonical(entry)]));
+    }
+    return value;
+}
+function parseEvents(lines) {
+    const events = [];
+    let skipped = 0;
+    for (const line of lines) {
+        try {
+            const parsed = CommandEventSchema.safeParse(JSON.parse(line));
+            if (parsed.success) {
+                events.push(parsed.data);
+                continue;
+            }
+        }
+        catch {
+            // A torn or foreign line is counted, never exported.
+        }
+        skipped += 1;
+    }
+    return { events, skipped };
+}
+function configSummary(config) {
+    return {
+        idle: {
+            strategy: config.idle.strategy,
+            pollIntervalMs: config.idle.pollIntervalMs,
+            stablePolls: config.idle.stablePolls,
+            timeoutMs: config.idle.timeoutMs,
+            ...(config.idle.ignoreCursorBlink === undefined
+                ? {}
+                : { ignoreCursorBlink: config.idle.ignoreCursorBlink }),
+            ...(config.idle.ignoreLayoutDrift === undefined
+                ? {}
+                : { ignoreLayoutDrift: config.idle.ignoreLayoutDrift }),
+            deviceProfiles: config.idle.deviceProfiles?.length ?? 0
+        },
+        ...(config.ui === undefined
+            ? {}
+            : {
+                ui: {
+                    backend: config.ui.backend,
+                    ...(config.ui.snapshotTimeoutMs === undefined
+                        ? {}
+                        : { snapshotTimeoutMs: config.ui.snapshotTimeoutMs }),
+                    ...(config.ui.cacheEnabled === undefined
+                        ? {}
+                        : { cacheEnabled: config.ui.cacheEnabled })
+                }
+            }),
+        ...(config.runtime === undefined ? {} : { runtime: { backend: config.runtime.backend } })
+    };
+}
+/**
+ * Builds a feedback bundle from the local journal and the reports it
+ * references. Only allowlisted structural facts survive: identifying strings
+ * become ordinal aliases or salted digests, and everything else is dropped.
+ * The result is validated against the strict bundle schema before return.
+ */
+export class DiagnosticsExporter {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    async export(input) {
+        const { events: allEvents, skipped } = parseEvents(await this.dependencies.journal.readLines(input.projectRoot));
+        const events = allEvents.slice(-Math.max(0, input.eventLimit));
+        const config = await this.readConfig(input.projectRoot);
+        const salt = await this.dependencies.journal.salt(input.projectRoot);
+        const runs = new Aliases("run");
+        const activities = new Aliases("activity");
+        const journeys = new Aliases("journey");
+        const devices = new Aliases("device");
+        const locatorId = (locator) => createHmac("sha256", salt)
+            .update(JSON.stringify(canonical(locator)))
+            .digest("hex")
+            .slice(0, 16);
+        const runIds = [...new Set(events.flatMap((event) => (event.runId === undefined ? [] : [event.runId])))];
+        // Aliases follow journal order, whichever runs end up summarized.
+        for (const runId of runIds)
+            runs.of(runId);
+        const artifactsDir = resolve(input.projectRoot, config?.artifactsDir ?? DEFAULT_ARTIFACTS_DIR);
+        const summaries = [];
+        for (const runId of runIds.slice(-Math.max(0, input.runLimit))) {
+            const report = await this.readReport(join(artifactsDir, runId, "report.json"));
+            if (report === undefined)
+                continue;
+            summaries.push(summarizeRun(report, runs.of(runId), {
+                activity: (value) => activities.of(value),
+                journey: (value) => journeys.of(value),
+                device: (value) => devices.of(value),
+                locatorId
+            }));
+        }
+        return DiagnosticsBundleSchema.parse({
+            version: 1,
+            generatedAt: this.dependencies.now().toISOString(),
+            taphoundVersion: this.dependencies.taphoundVersion,
+            host: this.dependencies.host,
+            ...(config === undefined ? {} : { config: configSummary(config) }),
+            journal: {
+                events: events.map((event) => ({
+                    ...event,
+                    ...(event.runId === undefined ? {} : { runId: runs.of(event.runId) })
+                })),
+                skippedLines: skipped
+            },
+            runs: summaries
+        });
+    }
+    async readConfig(projectRoot) {
+        try {
+            const parsed = TapHoundConfigSchema.safeParse(await this.dependencies.readJson(join(projectRoot, CONFIG_PATH)));
+            return parsed.success ? parsed.data : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async readReport(path) {
+        try {
+            const parsed = TapHoundReportSchema.safeParse(await this.dependencies.readJson(path));
+            return parsed.success ? parsed.data : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+function summarizeStep(step, redact) {
+    const locator = step.locator;
+    const requested = locator?.requested;
+    return {
+        index: step.index,
+        action: step.action,
+        status: step.status,
+        ...(step.device === undefined ? {} : { device: redact.device(step.device) }),
+        durationMs: step.durationMs,
+        ...(locator === undefined
+            ? {}
+            : {
+                locator: {
+                    status: locator.status,
+                    ...(locator.matchedBy === undefined ? {} : { matchedBy: locator.matchedBy }),
+                    requestedFields: requested === undefined
+                        ? []
+                        : LOCATOR_FIELDS.filter((field) => requested[field] !== undefined),
+                    ...(requested === undefined ? {} : { locatorId: redact.locatorId(requested) }),
+                    ...(locator.anchor === undefined ? {} : { anchorStatus: locator.anchor.status }),
+                    fallbackUsed: locator.fallbackUsed
+                }
+            }),
+        ...(step.idle === undefined
+            ? {}
+            : {
+                idle: {
+                    status: step.idle.status,
+                    polls: step.idle.polls,
+                    ...(step.idle.durationMs === undefined ? {} : { durationMs: step.idle.durationMs }),
+                    ...(step.idle.samplingDurationMs === undefined
+                        ? {}
+                        : { samplingDurationMs: step.idle.samplingDurationMs }),
+                    ...(step.idle.strategy === undefined ? {} : { strategy: step.idle.strategy }),
+                    ...(step.idle.backend === undefined ? {} : { backend: step.idle.backend }),
+                    ...(step.idle.fallbackUsed === undefined
+                        ? {}
+                        : { fallbackUsed: step.idle.fallbackUsed }),
+                    ...(step.idle.frameActivityDetected === undefined
+                        ? {}
+                        : { frameActivityDetected: step.idle.frameActivityDetected }),
+                    ...(step.idle.lastDiff === undefined
+                        ? {}
+                        : { lastDiffCount: step.idle.lastDiff.length })
+                }
+            }),
+        ...(step.activity === undefined
+            ? {}
+            : {
+                activity: {
+                    before: activityCheck(step.activity.before, redact),
+                    after: activityCheck(step.activity.after, redact)
+                }
+            }),
+        ...(step.expectation === undefined
+            ? {}
+            : {
+                expectation: {
+                    type: step.expectation.type,
+                    status: step.expectation.status,
+                    ...(step.expectation.code === undefined ? {} : { code: step.expectation.code })
+                }
+            }),
+        ...(step.scroll === undefined ? {} : { scroll: { ...step.scroll } })
+    };
+}
+function activityCheck(check, redact) {
+    return {
+        status: check.status,
+        expected: redact.activity(check.expected),
+        ...(check.actual === undefined ? {} : { actual: redact.activity(check.actual) })
+    };
+}
+function summarizeRun(report, run, redact) {
+    const failure = report.primaryFailure;
+    return {
+        run,
+        status: report.status,
+        durationMs: report.durationMs,
+        journey: redact.journey(report.journey.name),
+        devices: report.environment.devices.map((device) => ({
+            device: redact.device(device.role),
+            ...(device.uiBackend === undefined
+                ? {}
+                : {
+                    uiBackend: {
+                        id: device.uiBackend.id,
+                        adapterVersion: VERSION.test(device.uiBackend.adapterVersion)
+                            ? device.uiBackend.adapterVersion
+                            : "unknown",
+                        ...(device.uiBackend.engineVersion !== undefined
+                            && VERSION.test(device.uiBackend.engineVersion)
+                            ? { engineVersion: device.uiBackend.engineVersion }
+                            : {})
+                    }
+                }),
+            ...(device.uiCache === undefined ? {} : { uiCache: { ...device.uiCache } })
+        })),
+        tools: Object.fromEntries(TOOL_NAMES.flatMap((name) => {
+            const version = report.environment.tools[name];
+            return version !== undefined && VERSION.test(version) ? [[name, version]] : [];
+        })),
+        layers: { ...report.layers },
+        ...(failure === undefined
+            ? {}
+            : {
+                primaryFailure: {
+                    code: failure.code,
+                    phase: TOKEN.test(failure.phase) ? failure.phase : "other",
+                    ...(failure.stepIndex === undefined ? {} : { stepIndex: failure.stepIndex })
+                }
+            }),
+        secondaryErrorCodes: report.secondaryErrors.map((error) => error.code),
+        fallbackUsed: report.fallbackUsed,
+        logcatEvidence: (report.logcatEvidence ?? []).map((entry) => ({
+            device: redact.device(entry.role),
+            droppedLines: entry.droppedLines,
+            droppedBytes: entry.droppedBytes
+        })),
+        steps: report.steps.map((step) => summarizeStep(step, redact))
+    };
+}

package/dist/application/diagnostics/ui-capture-telemetry.d.ts

@@ -0,0 +1,16 @@
+import { type UiBackendTelemetry, type UiCaptureFailureKind } from "../../domain/diagnostics.js";
+import type { UiBackendId } from "../../domain/ui-backend.js";
+import type { UiCaptureObserver } from "../../ports/diagnostics.js";
+/**
+ * Classifies a capture failure from its type and status only, walking the
+ * cause chain. The message is read solely to spot a timeout and is never kept.
+ */
+export declare function classifyCaptureFailure(error: unknown): UiCaptureFailureKind;
+/** Aggregates UI backend captures for one CLI invocation. */
+export declare class UiCaptureTelemetry implements UiCaptureObserver {
+    private readonly backends;
+    captured(backend: UiBackendId, durationMs: number, error?: unknown): void;
+    sessionRecovered(backend: UiBackendId, succeeded: boolean): void;
+    summary(): UiBackendTelemetry[];
+    private entry;
+}

package/dist/application/diagnostics/ui-capture-telemetry.js

@@ -0,0 +1,81 @@
+import { UI_CAPTURE_LATENCY_BUCKETS_MS } from "../../domain/diagnostics.js";
+/**
+ * Classifies a capture failure from its type and status only, walking the
+ * cause chain. The message is read solely to spot a timeout and is never kept.
+ */
+export function classifyCaptureFailure(error) {
+    let current = error;
+    for (let depth = 0; depth < 8 && current !== null && typeof current === "object"; depth += 1) {
+        const record = current;
+        if (record.name === "TimeoutError")
+            return "timeout";
+        if (record.name === "AbortError")
+            return "cancelled";
+        if (typeof record.status === "number") {
+            if (record.status >= 500)
+                return "http5xx";
+            if (record.status >= 400)
+                return "http4xx";
+        }
+        if (typeof record.message === "string" && /timed? ?out/i.test(record.message)) {
+            return "timeout";
+        }
+        current = record.cause;
+    }
+    return "error";
+}
+function emptyTelemetry(backend) {
+    return {
+        backend,
+        captures: 0,
+        failures: { timeout: 0, cancelled: 0, http4xx: 0, http5xx: 0, error: 0 },
+        totalMs: 0,
+        maxMs: 0,
+        latencyBuckets: new Array(UI_CAPTURE_LATENCY_BUCKETS_MS.length + 1).fill(0),
+        sessionRecoveries: 0,
+        sessionRecoveryFailures: 0
+    };
+}
+/** Aggregates UI backend captures for one CLI invocation. */
+export class UiCaptureTelemetry {
+    backends = new Map();
+    captured(backend, durationMs, error) {
+        const entry = this.entry(backend);
+        const duration = Math.max(0, durationMs);
+        entry.captures += 1;
+        entry.totalMs += duration;
+        entry.maxMs = Math.max(entry.maxMs, duration);
+        const bucket = UI_CAPTURE_LATENCY_BUCKETS_MS.findIndex((limit) => duration < limit);
+        const index = bucket === -1 ? UI_CAPTURE_LATENCY_BUCKETS_MS.length : bucket;
+        entry.latencyBuckets[index] = (entry.latencyBuckets[index] ?? 0) + 1;
+        if (error !== undefined) {
+            entry.failures[classifyCaptureFailure(error)] += 1;
+        }
+    }
+    sessionRecovered(backend, succeeded) {
+        const entry = this.entry(backend);
+        if (succeeded) {
+            entry.sessionRecoveries += 1;
+        }
+        else {
+            entry.sessionRecoveryFailures += 1;
+        }
+    }
+    summary() {
+        return [...this.backends.values()].map((entry) => ({
+            ...entry,
+            totalMs: Math.round(entry.totalMs),
+            maxMs: Math.round(entry.maxMs),
+            failures: { ...entry.failures },
+            latencyBuckets: [...entry.latencyBuckets]
+        }));
+    }
+    entry(backend) {
+        let entry = this.backends.get(backend);
+        if (entry === undefined) {
+            entry = emptyTelemetry(backend);
+            this.backends.set(backend, entry);
+        }
+        return entry;
+    }
+}

package/dist/application/report/report-writer.d.ts

@@ -5,6 +5,11 @@ export interface PublishedReport {
     reportPath: string;
     summaryPath: string;
 }
+/**
+ * One line naming dropped Logcat evidence. Logcat-based expectations already
+ * fail closed on a relevant drop; this keeps a passed run from hiding it.
+ */
+export declare function logcatEvidenceWarning(report: Pick<TapHoundReport, "logcatEvidence">): string | undefined;
 export declare class ReportWriter {
     writeAndPublish(session: ArtifactSession, input: TapHoundReport): Promise<PublishedReport>;
 }

package/dist/application/report/report-writer.js

@@ -1,5 +1,17 @@
 import { join } from "node:path";
 import { TapHoundReportSchema } from "../../domain/report.js";
+/**
+ * One line naming dropped Logcat evidence. Logcat-based expectations already
+ * fail closed on a relevant drop; this keeps a passed run from hiding it.
+ */
+export function logcatEvidenceWarning(report) {
+    const entries = report.logcatEvidence ?? [];
+    if (entries.length === 0)
+        return undefined;
+    const lines = entries.reduce((total, entry) => total + entry.droppedLines, 0);
+    return `Warning: Logcat evidence is incomplete (${String(lines)} line(s) dropped); `
+        + "Logcat-based expectations fail closed on drops in their window";
+}
 function renderSummary(report) {
     const lines = [
         `TapHound run ${report.runId}: ${report.status.toUpperCase()}`,
@@ -10,6 +22,10 @@ function renderSummary(report) {
         "Layers:",
         ...Object.entries(report.layers).map(([layer, status]) => `- ${layer}: ${status}`)
     ];
+    const logcatWarning = logcatEvidenceWarning(report);
+    if (logcatWarning !== undefined) {
+        lines.push("", logcatWarning);
+    }
     if (report.primaryFailure !== undefined) {
         lines.push("", `Primary failure: ${report.primaryFailure.code}: ${report.primaryFailure.message}`);
     }

package/dist/application/runtime/verify-runtime.js

@@ -10,6 +10,20 @@ import { logcatStopFailed } from "../collector/logcat-stop.js";
 import { ActivityWaiter } from "./activity-waiter.js";
 import { coldLaunchApp } from "./cold-launch.js";
 import { StepRunner } from "./step-runner.js";
+/**
+ * The first step after a cold launch is the first to see the app's persisted
+ * state. TapHound never clears app data, so a target that is missing there
+ * most often means that state drifted since the Journey was generated.
+ */
+const INITIAL_STATE_FAILURE_CODES = new Set([
+    "LOCATOR_NOT_FOUND",
+    "ANCHOR_NOT_FOUND",
+    "SCROLL_TARGET_NOT_FOUND"
+]);
+const INITIAL_STATE_HINT = "this is the first step after cold launch: "
+    + "TapHound does not reset app data, so check persisted app state such as "
+    + "settings, login, or layout preferences against the state the Journey "
+    + "was generated in before changing the Journey";
 function commandFailed(result) {
     return result.exitCode !== 0
         || result.timedOut
@@ -442,6 +456,7 @@ export class VerifyRuntime {
             if (primaryFailure === undefined) {
                 const soleRole = soleRoleForJourney(input.journey);
                 const runtimeByRole = new Map(runtimes.map((runtime) => [runtime.role, runtime]));
+                const rolesStarted = new Set();
                 for (const [index, step] of input.journey.steps.entries()) {
                     input.progress?.({
                         stage: "replaying",
@@ -455,6 +470,8 @@ export class VerifyRuntime {
                         break;
                     }
                     const result = await runner.run(step, index, input.signal);
+                    const firstStepOnDevice = !rolesStarted.has(role);
+                    rolesStarted.add(role);
                     steps.push(result.report);
                     if (result.status === "manualRequired") {
                         setPrimary("MANUAL_STEP_REQUIRED", `Step ${String(index)} requires manual replay and the run is non-interactive`, "replay", index);
@@ -465,7 +482,10 @@ export class VerifyRuntime {
                         break;
                     }
                     if (result.status === "failed") {
-                        setPrimary(result.failure.code, result.failure.message, result.failure.phase, result.failure.stepIndex);
+                        setPrimary(result.failure.code, firstStepOnDevice
+                            && INITIAL_STATE_FAILURE_CODES.has(result.failure.code)
+                            ? `${result.failure.message} (${INITIAL_STATE_HINT})`
+                            : result.failure.message, result.failure.phase, result.failure.stepIndex);
                         break;
                     }
                     const runtime = runtimeByRole.get(role);
@@ -632,6 +652,8 @@ export class VerifyRuntime {
                     "DEVICE_UNAVAILABLE",
                     "DEVICE_ROLE_UNMAPPED",
                     "APP_NOT_INSTALLED",
+                    "UI_BACKEND_UNAVAILABLE",
+                    "UI_SNAPSHOT_FAILED",
                     "INTERNAL_ERROR"
                 ].includes(failure.code)
                     ? "error"

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-stability-probe.d.ts

@@ -1,3 +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

@@ -1,8 +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;
-    return withCapability.supportsStability !== false
-        && typeof withCapability.sample === "function"
-        && typeof withCapability.reset === "function"
-        ? withCapability
-        : fallback;
+    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-waiter.js

@@ -1,6 +1,14 @@
 import { resolveIdlePolicy } from "./idle-profiles.js";
 const EARLY_BAIL_FRAME_CHANGES = 2;
 const POST_FALLBACK_MIN_STABLE = 2;
+/**
+ * Once frame stats showed no rendering for `stablePolls` polls, the
+ * structural phase only has to confirm the hierarchy did not change between
+ * two captures taken during this wait: one empty diff after at least two
+ * structural samples. Each capture costs a full hierarchy dump.
+ */
+const POST_FRAME_STABLE_CONFIRMATIONS = 1;
+const POST_FRAME_STABLE_MIN_SAMPLES = 2;
 function isEditableWidgetChange(change) {
     if (typeof change !== "object" || change === null) {
         return false;
@@ -92,6 +100,8 @@ export class IdleWaiter {
         let lastLayout;
         let backend;
         let fallbackUsed = false;
+        let frameStable = false;
+        let structuralSamples = 0;
         let frameActivityDetected = false;
         let samplingDurationMs = 0;
         let useStructuralBackend = strategy === "layoutDiff"
@@ -159,6 +169,7 @@ export class IdleWaiter {
                 consecutiveEmpty = 0;
             }
             else if (useStructuralBackend) {
+                structuralSamples += 1;
                 let visibleChanges = meaningfulChanges(diff, config.ignoreCursorBlink === true);
                 if (config.ignoreLayoutDrift === true && visibleChanges.length > 0) {
                     const keys = visibleChanges.map(semanticKeys);
@@ -190,13 +201,17 @@ export class IdleWaiter {
             }
             const isPostFallback = fallbackUsed && strategy === "hybrid";
             const requiredStableObservations = useStructuralBackend
-                ? (isPostFallback
-                    ? Math.max(POST_FALLBACK_MIN_STABLE, config.stablePolls - 1)
-                    : Math.max(2, config.stablePolls))
+                ? (frameStable
+                    ? POST_FRAME_STABLE_CONFIRMATIONS
+                    : isPostFallback
+                        ? Math.max(POST_FALLBACK_MIN_STABLE, config.stablePolls - 1)
+                        : Math.max(2, config.stablePolls))
                 : config.stablePolls;
-            if (consecutiveEmpty >= requiredStableObservations) {
+            if (consecutiveEmpty >= requiredStableObservations
+                && (!frameStable || structuralSamples >= POST_FRAME_STABLE_MIN_SAMPLES)) {
                 if (strategy === "hybrid" && !useStructuralBackend) {
                     useStructuralBackend = true;
+                    frameStable = true;
                     consecutiveEmpty = 0;
                 }
                 else {

package/dist/cli/commands/diagnose.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import type { CliDependencies } from "../dependencies.js";
+export declare function createDiagnoseCommand(dependencies: CliDependencies): Command;