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

package/dist/domain/report.js

@@ -1,21 +1,45 @@
 import { createHash } from "node:crypto";
 import { z } from "zod";
 import { FAILURE_CODES } from "./failure.js";
-const ResultStatusSchema = z.enum(["passed", "failed", "notRun"]);
-const RunStatusSchema = z.enum(["passed", "failed", "error"]);
+import { KnowledgeIdSchema } from "./knowledge.js";
+import { DeviceRoleSchema } from "./journey.js";
+import { LocatorSchema } from "./layout.js";
+import { LogcatEventExpectSchema, LogcatEventWindowSchema } from "./logcat-event.js";
+import { UiBackendDescriptorSchema } from "./ui-backend.js";
+import { UiCacheTelemetrySchema } from "./ui-cache.js";
+const ResultStatusSchema = z.enum(["passed", "failed", "notRun", "manualRequired"]);
+const RunStatusSchema = z.enum(["passed", "failed", "error", "manualRequired"]);
 export const ReportFailureSchema = z.strictObject({
     code: z.enum(FAILURE_CODES),
     message: z.string().min(1),
     phase: z.string().min(1),
     stepIndex: z.number().int().nonnegative().optional()
 });
+const AnchorLocatorReportSchema = z.strictObject({
+    status: z.enum(["resolved", "locatorFallback", "failed"]),
+    resolvedBy: z.strictObject({
+        kind: z.enum([
+            "composeSemantics",
+            "resourceId",
+            "contentDescription",
+            "visibleText",
+            "visualMatch"
+        ]),
+        confidence: z.enum(["primary", "fallback"])
+    }).optional(),
+    message: z.string().trim().min(1).optional()
+});
 const LocatorReportSchema = z.strictObject({
     status: z.enum(["found", "failed", "notRun"]),
     matchedBy: z.enum([
         "resourceId",
         "text",
-        "contentDescription"
+        "contentDescription",
+        "anchor"
     ]).optional(),
+    requested: LocatorSchema.optional(),
+    anchorId: z.string().trim().min(1).optional(),
+    anchor: AnchorLocatorReportSchema.optional(),
     fallbackUsed: z.boolean(),
     fallbackLabel: z.string().regex(/^#\d+$/).optional(),
     annotatedScreenshotPath: z.string().min(1).optional(),
@@ -33,6 +57,18 @@ const LocatorReportSchema = z.strictObject({
 const IdleReportSchema = z.strictObject({
     status: z.enum(["stable", "timeout", "cancelled", "notRun"]),
     polls: z.number().int().nonnegative(),
+    durationMs: z.number().nonnegative().optional(),
+    samplingDurationMs: z.number().nonnegative().optional(),
+    strategy: z.enum(["hybrid", "layoutDiff", "frameStats", "structural"]).optional(),
+    backend: z.enum([
+        "uiautomator",
+        "androidCli",
+        "gfxFrameStats",
+        "mobileMcp"
+    ]).optional(),
+    backendId: z.string().trim().min(1).optional(),
+    fallbackUsed: z.boolean().optional(),
+    frameActivityDetected: z.boolean().optional(),
     lastDiff: z.array(z.unknown()).optional()
 });
 const ActivityCheckSchema = z.strictObject({
@@ -41,10 +77,43 @@ const ActivityCheckSchema = z.strictObject({
     actual: z.string().min(1).optional()
 });
 const StepExpectationSchema = z.strictObject({
-    type: z.enum(["activity", "element", "logcat"]),
+    type: z.enum(["activity", "element", "logcat", "logcatEvent"]),
     status: ResultStatusSchema,
     code: z.enum(FAILURE_CODES).optional(),
-    message: z.string().min(1).optional()
+    message: z.string().min(1).optional(),
+    logcatEvent: z.strictObject({
+        matchedCount: z.number().int().nonnegative(),
+        matchedLineSha256: z.string().regex(/^[a-f\d]{64}$/).optional(),
+        window: LogcatEventWindowSchema,
+        startedAtMs: z.number().nonnegative(),
+        requestErrorClass: z.enum(["client", "auth", "network", "server"]).optional()
+    }).optional(),
+    capture: z.strictObject({
+        name: z.string().regex(/^[a-z][a-zA-Z0-9_]{0,31}$/),
+        valueType: z.enum(["string", "integer", "identifier"]),
+        length: z.number().int().positive().max(128),
+        sourceStepIndex: z.number().int().nonnegative(),
+        window: LogcatEventWindowSchema,
+        startedAtMs: z.number().nonnegative(),
+        evidenceSha256: z.string().regex(/^[a-f\d]{64}$/)
+    }).optional()
+}).superRefine((expectation, context) => {
+    if (expectation.capture !== undefined && (expectation.type !== "logcatEvent" || expectation.status !== "passed"
+        || expectation.logcatEvent?.matchedLineSha256 !== expectation.capture.evidenceSha256
+        || expectation.logcatEvent.startedAtMs !== expectation.capture.startedAtMs)) {
+        context.addIssue({
+            code: "custom", path: ["capture"],
+            message: "Capture requires a passed digest-bound structured event"
+        });
+    }
+    if (expectation.logcatEvent?.requestErrorClass !== undefined && (expectation.logcatEvent.matchedCount !== 1
+        || expectation.logcatEvent.matchedLineSha256 === undefined
+        || expectation.status !== "passed")) {
+        context.addIssue({
+            code: "custom", path: ["logcatEvent", "requestErrorClass"],
+            message: "Request error class requires one matched digest-bound event"
+        });
+    }
 });
 export const StepReportSchema = z.strictObject({
     index: z.number().int().nonnegative(),
@@ -55,9 +124,12 @@ export const StepReportSchema = z.strictObject({
         "swipe",
         "scrollTo",
         "back",
-        "wait"
+        "wait",
+        "bridge"
     ]),
     status: ResultStatusSchema,
+    device: DeviceRoleSchema.optional(),
+    replayMode: z.enum(["auto", "manual"]).optional(),
     startedAtMs: z.number().nonnegative(),
     finishedAtMs: z.number().nonnegative(),
     durationMs: z.number().nonnegative(),
@@ -72,8 +144,86 @@ export const StepReportSchema = z.strictObject({
         after: ActivityCheckSchema
     }).optional(),
     expectation: StepExpectationSchema.optional(),
+    marker: z.strictObject({
+        id: KnowledgeIdSchema,
+        startedAtMs: z.number().nonnegative()
+    }).optional(),
     logcatPath: z.string().min(1).optional()
 });
+export const CheckpointConditionReportSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        kind: z.literal("activity"),
+        status: z.enum(["passed", "failed", "unresolved"]),
+        expected: z.string().trim().min(1),
+        actual: z.string().trim().min(1).optional(),
+        message: z.string().trim().min(1).optional(),
+        startedAtMs: z.number().nonnegative().optional(),
+        matchedAtMs: z.number().nonnegative().optional(),
+        evidenceRef: z.string().trim().min(1).optional()
+    }),
+    z.strictObject({
+        kind: z.literal("screen"),
+        status: z.enum(["passed", "failed", "unresolved"]),
+        expected: KnowledgeIdSchema,
+        actual: KnowledgeIdSchema.optional(),
+        message: z.string().trim().min(1).optional(),
+        startedAtMs: z.number().nonnegative().optional(),
+        matchedAtMs: z.number().nonnegative().optional(),
+        evidenceRef: z.string().trim().min(1).optional()
+    }),
+    z.strictObject({
+        kind: z.enum(["visibleElement", "absentElement"]),
+        status: z.enum(["passed", "failed", "unresolved"]),
+        locator: LocatorSchema,
+        message: z.string().trim().min(1).optional(),
+        startedAtMs: z.number().nonnegative().optional(),
+        matchedAtMs: z.number().nonnegative().optional(),
+        evidenceRef: z.string().trim().min(1).optional()
+    }),
+    z.strictObject({
+        kind: z.literal("logcatEvent"),
+        status: z.enum(["passed", "failed", "unresolved"]),
+        expect: LogcatEventExpectSchema.omit({ timeoutMs: true }),
+        matchedCount: z.number().int().nonnegative(),
+        matchedLineSha256: z.string().regex(/^[a-f\d]{64}$/).optional(),
+        startedAtMs: z.number().nonnegative(),
+        matchedAtMs: z.number().nonnegative().optional(),
+        evidenceRef: z.string().trim().min(1).optional(),
+        message: z.string().trim().min(1).optional()
+    })
+]);
+export const CheckpointReportSchema = z.strictObject({
+    id: KnowledgeIdSchema,
+    stepIndex: z.number().int().nonnegative().optional(),
+    status: z.enum(["passed", "failed", "unresolved"]),
+    conditions: z.array(CheckpointConditionReportSchema).min(1)
+}).superRefine((checkpoint, context) => {
+    for (const [index, condition] of checkpoint.conditions.entries()) {
+        if (condition.kind === "logcatEvent" && condition.status === "passed"
+            && (condition.matchedCount !== 1
+                || condition.matchedLineSha256 === undefined
+                || condition.matchedAtMs === undefined
+                || condition.evidenceRef === undefined)) {
+            context.addIssue({
+                code: "custom",
+                path: ["conditions", index],
+                message: "Passed Logcat events need exactly one digest-bound artifact match"
+            });
+        }
+    }
+    const status = checkpoint.conditions.some((condition) => condition.status === "failed")
+        ? "failed"
+        : checkpoint.conditions.some((condition) => condition.status === "unresolved")
+            ? "unresolved"
+            : "passed";
+    if (checkpoint.status !== status) {
+        context.addIssue({
+            code: "custom",
+            path: ["status"],
+            message: "Checkpoint status must reflect all condition results"
+        });
+    }
+});
 const LayersSchema = z.strictObject({
     run: ResultStatusSchema,
     structural: ResultStatusSchema,
@@ -81,16 +231,20 @@ const LayersSchema = z.strictObject({
     explicitExpect: ResultStatusSchema,
     collection: ResultStatusSchema
 });
+const ArtifactRolePathSchema = z.strictObject({
+    role: DeviceRoleSchema,
+    path: z.string().min(1)
+});
 const ArtifactsSchema = z.strictObject({
     directory: z.string().min(1),
     report: z.string().min(1),
     summary: z.string().min(1),
-    screenshot: z.string().min(1).optional(),
-    logcat: z.string().min(1).optional(),
+    screenshots: z.array(ArtifactRolePathSchema),
+    uiHierarchies: z.array(ArtifactRolePathSchema).optional(),
+    logcats: z.array(ArtifactRolePathSchema),
     stepLogs: z.array(z.string().min(1))
 });
-export const TapHoundReportSchema = z.strictObject({
-    schemaVersion: z.literal(2),
+const ReportFields = {
     runId: z.string().min(1),
     status: RunStatusSchema,
     startedAt: z.string().min(1),
@@ -105,17 +259,60 @@ export const TapHoundReportSchema = z.strictObject({
         name: z.string().min(1),
         sha256: z.string().regex(/^[a-f\d]{64}$/)
     }),
-    environment: z.strictObject({
-        deviceSerial: z.string().min(1),
-        tools: z.record(z.string(), z.string())
-    }),
     layers: LayersSchema,
     steps: z.array(StepReportSchema),
+    logcatEvidence: z.array(z.strictObject({
+        role: DeviceRoleSchema,
+        status: z.literal("incomplete"),
+        droppedLines: z.number().int().positive(),
+        droppedBytes: z.number().int().positive(),
+        lastDroppedAtMs: z.number().nonnegative().optional()
+    })).optional(),
+    checkpoints: z.array(CheckpointReportSchema).optional(),
+    screens: z.array(z.strictObject({
+        screen: z.string().trim().min(1),
+        status: z.enum(["matched", "ambiguous", "unresolved"])
+    })).optional(),
     artifacts: ArtifactsSchema,
     primaryFailure: ReportFailureSchema.optional(),
     secondaryErrors: z.array(ReportFailureSchema),
     fallbackUsed: z.boolean()
+};
+const ReportDeviceSchema = z.strictObject({
+    role: DeviceRoleSchema,
+    deviceSerial: z.string().min(1),
+    uiBackend: UiBackendDescriptorSchema.optional(),
+    uiCache: UiCacheTelemetrySchema.optional()
+});
+export const TapHoundReportV4Schema = z.strictObject({
+    schemaVersion: z.literal(4),
+    ...ReportFields,
+    environment: z.strictObject({
+        devices: z.array(ReportDeviceSchema).min(1),
+        tools: z.record(z.string(), z.string())
+    })
+}).superRefine((report, context) => {
+    const roles = new Set(report.environment.devices.map((device) => device.role));
+    if (roles.size !== report.environment.devices.length) {
+        context.addIssue({
+            code: "custom",
+            message: "Device roles must be unique within a report"
+        });
+        return;
+    }
+    const unknownArtifactRole = [
+        ...report.artifacts.screenshots,
+        ...(report.artifacts.uiHierarchies ?? []),
+        ...report.artifacts.logcats
+    ].some((entry) => !roles.has(entry.role));
+    if (unknownArtifactRole) {
+        context.addIssue({
+            code: "custom",
+            message: "Artifacts reference an unknown device role"
+        });
+    }
 });
+export const TapHoundReportSchema = TapHoundReportV4Schema;
 function canonicalize(value) {
     if (Array.isArray(value)) {
         return value.map(canonicalize);

package/dist/domain/runtime-snapshot.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 export declare const RuntimeSnapshotSchema: z.ZodObject<{
-    version: z.ZodLiteral<1>;
+    version: z.ZodLiteral<2>;
     generationId: z.ZodString;
     baseRevision: z.ZodNumber;
     deviceSerial: z.ZodString;
@@ -11,6 +11,63 @@ export declare const RuntimeSnapshotSchema: z.ZodObject<{
     capturedAt: z.ZodISODateTime;
     screenshotPath: z.ZodOptional<z.ZodString>;
     layout: z.ZodArray<z.ZodType<import("./layout.js").LayoutElement, unknown, z.core.$ZodTypeInternals<import("./layout.js").LayoutElement, unknown>>>;
+    windowHierarchy: z.ZodOptional<z.ZodObject<{
+        status: z.ZodEnum<{
+            unknown: "unknown";
+            complete: "complete";
+            incomplete: "incomplete";
+        }>;
+        appWindows: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodString;
+            packageName: z.ZodString;
+            type: z.ZodOptional<z.ZodString>;
+            layer: z.ZodOptional<z.ZodNumber>;
+            bounds: z.ZodOptional<z.ZodObject<{
+                left: z.ZodNumber;
+                top: z.ZodNumber;
+                right: z.ZodNumber;
+                bottom: z.ZodNumber;
+            }, z.core.$strict>>;
+            touchable: z.ZodBoolean;
+            focusable: z.ZodOptional<z.ZodBoolean>;
+            focused: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        semanticWindowIds: z.ZodArray<z.ZodString>;
+        diagnostics: z.ZodArray<z.ZodObject<{
+            code: z.ZodEnum<{
+                WINDOW_TOPOLOGY_UNAVAILABLE: "WINDOW_TOPOLOGY_UNAVAILABLE";
+                SEMANTIC_WINDOW_IDS_UNAVAILABLE: "SEMANTIC_WINDOW_IDS_UNAVAILABLE";
+                APP_WINDOW_WITHOUT_SEMANTIC_ROOT: "APP_WINDOW_WITHOUT_SEMANTIC_ROOT";
+                APP_WINDOW_NOT_ACCESSIBILITY_READABLE: "APP_WINDOW_NOT_ACCESSIBILITY_READABLE";
+            }>;
+            message: z.ZodString;
+        }, z.core.$strict>>;
+        recovery: z.ZodArray<z.ZodEnum<{
+            REOBSERVE: "REOBSERVE";
+            LAYOUT_INSPECTOR: "LAYOUT_INSPECTOR";
+            DEBUG_WINDOW_INSPECTOR: "DEBUG_WINDOW_INSPECTOR";
+        }>>;
+    }, z.core.$strict>>;
+    uiBackend: z.ZodObject<{
+        id: z.ZodEnum<{
+            "system-uiautomator": "system-uiautomator";
+            "android-cli": "android-cli";
+            "appium-uiautomator2": "appium-uiautomator2";
+            "mobile-mcp": "mobile-mcp";
+        }>;
+        adapterVersion: z.ZodString;
+        engineVersion: z.ZodOptional<z.ZodString>;
+        configSha256: z.ZodString;
+    }, z.core.$strict>;
+    uiObservationId: z.ZodString;
+    uiCaptureDurationMs: z.ZodNumber;
+    viewport: z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        rotation: z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<90>, z.ZodLiteral<180>, z.ZodLiteral<270>]>;
+        coordinateSpace: z.ZodLiteral<"physicalDisplayPixels">;
+    }, z.core.$strict>;
 }, z.core.$strict>;
 export type RuntimeSnapshot = z.infer<typeof RuntimeSnapshotSchema>;
 export declare function hashRuntimeSnapshot(snapshot: unknown): string;

package/dist/domain/runtime-snapshot.js

@@ -1,9 +1,12 @@
 import { createHash } from "node:crypto";
 import { z } from "zod";
 import { LayoutElementSchema } from "./layout.js";
+import { DisplayViewportSchema } from "./geometry.js";
+import { UiBackendDescriptorSchema } from "./ui-backend.js";
+import { WindowHierarchySchema } from "./window-hierarchy.js";
 const QualifiedNameSchema = z.string().regex(/^(?:[A-Za-z_$][\w$]*\.)+[A-Za-z_$][\w$]*$/, "Value must be fully qualified");
 export const RuntimeSnapshotSchema = z.strictObject({
-    version: z.literal(1),
+    version: z.literal(2),
     generationId: z.string().trim().min(1),
     baseRevision: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
     deviceSerial: z.string().trim().min(1),
@@ -13,7 +16,12 @@ export const RuntimeSnapshotSchema = z.strictObject({
     pid: z.number().int().positive().max(Number.MAX_SAFE_INTEGER).nullable(),
     capturedAt: z.iso.datetime(),
     screenshotPath: z.string().trim().min(1).optional(),
-    layout: z.array(LayoutElementSchema)
+    layout: z.array(LayoutElementSchema),
+    windowHierarchy: WindowHierarchySchema.optional(),
+    uiBackend: UiBackendDescriptorSchema,
+    uiObservationId: z.string().trim().min(1),
+    uiCaptureDurationMs: z.number().nonnegative(),
+    viewport: DisplayViewportSchema
 });
 function canonicalize(value) {
     if (Array.isArray(value)) {
@@ -38,7 +46,10 @@ export function hashRuntimeSnapshot(snapshot) {
         foregroundPackageName: parsed.foregroundPackageName,
         activity: parsed.activity,
         pid: parsed.pid,
-        layout: parsed.layout
+        layout: parsed.layout,
+        windowHierarchy: parsed.windowHierarchy,
+        uiBackend: parsed.uiBackend,
+        viewport: parsed.viewport
     };
     return createHash("sha256")
         .update(JSON.stringify(canonicalize(content)))

package/dist/domain/runtime.d.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+export declare const RuntimeBackendIdSchema: z.ZodEnum<{
+    adb: "adb";
+    "mobile-mcp": "mobile-mcp";
+}>;
+export declare const RuntimeBackendChoiceSchema: z.ZodEnum<{
+    adb: "adb";
+    "mobile-mcp": "mobile-mcp";
+    auto: "auto";
+}>;
+export declare const RuntimeCapabilitiesSchema: z.ZodObject<{
+    layoutSnapshot: z.ZodBoolean;
+    screenshot: z.ZodBoolean;
+    annotatedScreens: z.ZodBoolean;
+    frameStatsIdle: z.ZodBoolean;
+    logs: z.ZodBoolean;
+    processDiscovery: z.ZodBoolean;
+    windowTopology: z.ZodBoolean;
+    intentStart: z.ZodBoolean;
+    foregroundActivity: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const RuntimeBackendDescriptorSchema: z.ZodObject<{
+    id: z.ZodEnum<{
+        adb: "adb";
+        "mobile-mcp": "mobile-mcp";
+    }>;
+    adapterVersion: z.ZodString;
+    engineVersion: z.ZodOptional<z.ZodString>;
+    configSha256: z.ZodString;
+    capabilities: z.ZodObject<{
+        layoutSnapshot: z.ZodBoolean;
+        screenshot: z.ZodBoolean;
+        annotatedScreens: z.ZodBoolean;
+        frameStatsIdle: z.ZodBoolean;
+        logs: z.ZodBoolean;
+        processDiscovery: z.ZodBoolean;
+        windowTopology: z.ZodBoolean;
+        intentStart: z.ZodBoolean;
+        foregroundActivity: z.ZodBoolean;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export interface DeviceInfo {
+    serial: string;
+    status: string;
+}
+export type RuntimeBackendId = z.infer<typeof RuntimeBackendIdSchema>;
+export type RuntimeBackendChoice = z.infer<typeof RuntimeBackendChoiceSchema>;
+export type RuntimeCapabilities = z.infer<typeof RuntimeCapabilitiesSchema>;
+export type RuntimeBackendDescriptor = z.infer<typeof RuntimeBackendDescriptorSchema>;
+export declare function resolveRuntimeBackendId(selection: RuntimeBackendChoice): RuntimeBackendId;

package/dist/domain/runtime.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+export const RuntimeBackendIdSchema = z.enum([
+    "adb",
+    "mobile-mcp"
+]);
+export const RuntimeBackendChoiceSchema = z.enum([
+    "auto",
+    "adb",
+    "mobile-mcp"
+]);
+export const RuntimeCapabilitiesSchema = z.strictObject({
+    layoutSnapshot: z.boolean(),
+    screenshot: z.boolean(),
+    annotatedScreens: z.boolean(),
+    frameStatsIdle: z.boolean(),
+    logs: z.boolean(),
+    processDiscovery: z.boolean(),
+    windowTopology: z.boolean(),
+    intentStart: z.boolean(),
+    foregroundActivity: z.boolean()
+});
+export const RuntimeBackendDescriptorSchema = z.strictObject({
+    id: RuntimeBackendIdSchema,
+    adapterVersion: z.string().min(1),
+    engineVersion: z.string().min(1).optional(),
+    configSha256: z.string().regex(/^[a-f\d]{64}$/),
+    capabilities: RuntimeCapabilitiesSchema
+});
+const RUNTIME_BACKEND_RESOLUTION = {
+    auto: "adb",
+    adb: "adb",
+    "mobile-mcp": "mobile-mcp"
+};
+export function resolveRuntimeBackendId(selection) {
+    return RUNTIME_BACKEND_RESOLUTION[selection];
+}

package/dist/domain/system-app-profiles.d.ts

@@ -0,0 +1,6 @@
+declare const SYSTEM_SCENARIOS: readonly ["photoCapture", "pickImage", "pickFile"];
+type SystemScenario = (typeof SYSTEM_SCENARIOS)[number];
+export declare const SYSTEM_APP_PACKAGES: Record<SystemScenario, readonly string[]>;
+export declare function isKnownSystemPackage(scenario: SystemScenario, packageName: string): boolean;
+export declare function isSystemScenario(scenario: string): scenario is SystemScenario;
+export {};

package/dist/domain/system-app-profiles.js

@@ -0,0 +1,43 @@
+const SYSTEM_SCENARIOS = ["photoCapture", "pickImage", "pickFile"];
+export const SYSTEM_APP_PACKAGES = {
+    photoCapture: [
+        "com.android.camera",
+        "com.android.camera2",
+        "com.google.android.GoogleCamera",
+        "com.sec.android.app.camera",
+        "com.huawei.camera",
+        "com.miui.camera",
+        "com.oppo.camera",
+        "com.vivo.camera",
+        "com.oneplus.camera"
+    ],
+    pickImage: [
+        "com.android.gallery",
+        "com.android.gallery3d",
+        "com.google.android.apps.photos",
+        "com.google.android.apps.photos.go",
+        "com.sec.android.gallery3d",
+        "com.miui.gallery",
+        "com.oppo.gallery",
+        "com.vivo.gallery",
+        "com.android.documentsui",
+        "com.google.android.documentsui",
+        "com.google.android.providers.media.module",
+        "com.android.providers.media.module"
+    ],
+    pickFile: [
+        "com.android.documentsui",
+        "com.google.android.documentsui",
+        "com.android.fileexplorer",
+        "com.mi.android.globalFileexplorer",
+        "com.sec.android.app.myfiles",
+        "com.coloros.filemanager",
+        "com.vivo.filemanager"
+    ]
+};
+export function isKnownSystemPackage(scenario, packageName) {
+    return SYSTEM_APP_PACKAGES[scenario].includes(packageName);
+}
+export function isSystemScenario(scenario) {
+    return SYSTEM_SCENARIOS.includes(scenario);
+}

package/dist/domain/ui-backend.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+export declare const UiBackendIdSchema: z.ZodEnum<{
+    "system-uiautomator": "system-uiautomator";
+    "android-cli": "android-cli";
+    "appium-uiautomator2": "appium-uiautomator2";
+    "mobile-mcp": "mobile-mcp";
+}>;
+export declare const UiBackendSelectionSchema: z.ZodEnum<{
+    "system-uiautomator": "system-uiautomator";
+    "android-cli": "android-cli";
+    "appium-uiautomator2": "appium-uiautomator2";
+    auto: "auto";
+}>;
+export declare const UiBackendDescriptorSchema: z.ZodObject<{
+    id: z.ZodEnum<{
+        "system-uiautomator": "system-uiautomator";
+        "android-cli": "android-cli";
+        "appium-uiautomator2": "appium-uiautomator2";
+        "mobile-mcp": "mobile-mcp";
+    }>;
+    adapterVersion: z.ZodString;
+    engineVersion: z.ZodOptional<z.ZodString>;
+    configSha256: z.ZodString;
+}, z.core.$strict>;
+export type UiBackendDescriptor = z.infer<typeof UiBackendDescriptorSchema>;
+export type UiBackendId = z.infer<typeof UiBackendIdSchema>;
+export type UiBackendSelection = z.infer<typeof UiBackendSelectionSchema>;
+export declare function uiBackendIdAsSelection(id: UiBackendId): UiBackendSelection | undefined;

package/dist/domain/ui-backend.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+export const UiBackendIdSchema = z.enum([
+    "system-uiautomator",
+    "android-cli",
+    "appium-uiautomator2",
+    "mobile-mcp"
+]);
+// Selection stays narrower than descriptor ids: "mobile-mcp" layouts arrive
+// only through the Runtime Backend SPI (runtime.backend), never as a direct
+// ui.backend choice, so AutoUiSnapshotProviderFactory never sees it.
+export const UiBackendSelectionSchema = z.enum([
+    "auto",
+    "system-uiautomator",
+    "android-cli",
+    "appium-uiautomator2"
+]);
+export const UiBackendDescriptorSchema = z.strictObject({
+    id: UiBackendIdSchema,
+    adapterVersion: z.string().min(1),
+    engineVersion: z.string().min(1).optional(),
+    configSha256: z.string().regex(/^[a-f\d]{64}$/)
+});
+// Descriptor ids can name runtime-bound backends ("mobile-mcp") that never
+// participate in direct ui.backend selection. Return undefined for those ids
+// so callers keep the runtime-owned snapshot provider; their descriptor
+// equality checks still reject a genuine backend mismatch.
+export function uiBackendIdAsSelection(id) {
+    if (id === "system-uiautomator" || id === "android-cli"
+        || id === "appium-uiautomator2") {
+        return id;
+    }
+    return undefined;
+}

package/dist/domain/ui-cache.d.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+/** In-memory UI snapshot cache telemetry reported by observe and verify. */
+export declare const UiCacheTelemetrySchema: z.ZodObject<{
+    hits: z.ZodNumber;
+    misses: z.ZodNumber;
+    stale: z.ZodNumber;
+    relearns: z.ZodNumber;
+    capturesSaved: z.ZodNumber;
+    validationDurationMs: z.ZodNumber;
+}, z.core.$strict>;
+export type UiCacheTelemetry = z.infer<typeof UiCacheTelemetrySchema>;

package/dist/domain/ui-cache.js

@@ -0,0 +1,10 @@
+import { z } from "zod";
+/** In-memory UI snapshot cache telemetry reported by observe and verify. */
+export const UiCacheTelemetrySchema = z.strictObject({
+    hits: z.number().int().nonnegative(),
+    misses: z.number().int().nonnegative(),
+    stale: z.number().int().nonnegative(),
+    relearns: z.number().int().nonnegative(),
+    capturesSaved: z.number().int().nonnegative(),
+    validationDurationMs: z.number().nonnegative()
+});