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

package/dist/adapters/runtime/session-adb-view.d.ts

@@ -0,0 +1,53 @@
+import type { AdbPort, AppIdentity, DeviceIdentity, DeviceInfo, DumpLogcatOptions, LaunchActivityOptions, LogcatOptions, ResolvedActivity, StartActivityByIntentOptions } from "../../ports/adb.js";
+import type { CommandResult, RunningCommand } from "../../ports/process-runner.js";
+import type { RuntimeSession } from "../../ports/runtime-backend.js";
+import type { RuntimeSessionPortViews } from "../../ports/runtime-session-ports.js";
+import type { ScreenshotOptions, ScreenshotPort } from "../../ports/screenshot.js";
+import type { Point } from "../../domain/geometry.js";
+import type { ForegroundComponent } from "../../domain/activity.js";
+import type { AppProcess } from "../../domain/app-process.js";
+import type { WindowTopology } from "../../domain/window-hierarchy.js";
+/**
+ * One borrowed `RuntimeSession` exposed as the legacy `AdbPort`. The view
+ * holds a single already-opened session: the serial in every call must match
+ * the session's bound serial, and device discovery belongs to
+ * `RuntimeBackend.listDevices`. Level 1 session-first orchestrators feed their
+ * `AdbPort`-shaped helpers through this view until Level 2 retypes them.
+ */
+export declare class RuntimeSessionAdbView implements AdbPort {
+    private readonly session;
+    constructor(session: RuntimeSession);
+    devices(): Promise<readonly DeviceInfo[]>;
+    foregroundComponent(identity: AppIdentity): Promise<ForegroundComponent>;
+    currentActivity(identity: AppIdentity): Promise<string>;
+    deviceIdentity(identity: AppIdentity): Promise<DeviceIdentity>;
+    isInstalled(identity: AppIdentity): Promise<boolean>;
+    launchActivity(options: LaunchActivityOptions): Promise<CommandResult>;
+    startActivityByIntent(options: StartActivityByIntentOptions): Promise<CommandResult>;
+    resolveLauncherActivity(): Promise<ResolvedActivity | undefined>;
+    forceStop(identity: AppIdentity): Promise<CommandResult>;
+    appProcesses(identity: AppIdentity): Promise<readonly AppProcess[]>;
+    windowTopology(identity: AppIdentity): Promise<WindowTopology>;
+    tap(point: Point, deviceSerial: string, signal?: AbortSignal): Promise<CommandResult>;
+    longClick(point: Point, durationMs: number, deviceSerial: string, signal?: AbortSignal): Promise<CommandResult>;
+    swipe(from: Point, to: Point, durationMs: number, deviceSerial: string, signal?: AbortSignal): Promise<CommandResult>;
+    back(deviceSerial: string, signal?: AbortSignal): Promise<CommandResult>;
+    inputText(text: string, deviceSerial: string, signal?: AbortSignal): Promise<CommandResult>;
+    startLogcat(options: LogcatOptions): RunningCommand;
+    dumpLogcat(options: DumpLogcatOptions): Promise<CommandResult>;
+    private assertBoundSerial;
+}
+/** One borrowed session exposed as the serial-keyed `ScreenshotPort`. */
+export declare class SessionBoundScreenshotAdapter implements ScreenshotPort {
+    private readonly session;
+    constructor(session: RuntimeSession);
+    capture(options: ScreenshotOptions): Promise<CommandResult>;
+}
+/**
+ * Legacy port views for one borrowed session: the `AdbPort` view above, a
+ * session-bound screenshot port, the session's annotated-screen resolver
+ * (fail-closed when the backend lacks the capability), and the required UI
+ * stability probe. Session-first orchestrators pass these views to helpers
+ * that still speak the legacy port types.
+ */
+export declare function runtimeSessionPortViews(session: RuntimeSession): RuntimeSessionPortViews;

package/dist/adapters/runtime/session-adb-view.js

@@ -0,0 +1,193 @@
+import { runtimeCapabilityMissing } from "../../ports/runtime-capability.js";
+import { FailClosedAnnotatedScreenResolver } from "./session-backed-ports.js";
+function appQuery(identity) {
+    return {
+        packageName: identity.packageName,
+        ...(identity.signal === undefined ? {} : { signal: identity.signal }),
+        ...(identity.timeoutMs === undefined
+            ? {}
+            : { timeoutMs: identity.timeoutMs })
+    };
+}
+function launchOptions(options) {
+    return {
+        packageName: options.packageName,
+        activity: options.activity,
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+        ...(options.timeoutMs === undefined
+            ? {}
+            : { timeoutMs: options.timeoutMs })
+    };
+}
+/**
+ * One borrowed `RuntimeSession` exposed as the legacy `AdbPort`. The view
+ * holds a single already-opened session: the serial in every call must match
+ * the session's bound serial, and device discovery belongs to
+ * `RuntimeBackend.listDevices`. Level 1 session-first orchestrators feed their
+ * `AdbPort`-shaped helpers through this view until Level 2 retypes them.
+ */
+export class RuntimeSessionAdbView {
+    session;
+    constructor(session) {
+        this.session = session;
+    }
+    devices() {
+        return Promise.reject(new Error("Device discovery is not available through a runtime session view; "
+            + "use the runtime backend instead"));
+    }
+    async foregroundComponent(identity) {
+        this.assertBoundSerial(identity.deviceSerial);
+        if (this.session.foregroundComponent === undefined) {
+            throw runtimeCapabilityMissing(this.session.descriptor.id, "foregroundComponent");
+        }
+        return this.session.foregroundComponent(appQuery(identity));
+    }
+    async currentActivity(identity) {
+        this.assertBoundSerial(identity.deviceSerial);
+        if (this.session.currentActivity === undefined) {
+            throw runtimeCapabilityMissing(this.session.descriptor.id, "currentActivity");
+        }
+        return this.session.currentActivity(appQuery(identity));
+    }
+    async deviceIdentity(identity) {
+        this.assertBoundSerial(identity.deviceSerial);
+        if (this.session.deviceIdentity === undefined) {
+            throw runtimeCapabilityMissing(this.session.descriptor.id, "deviceIdentity");
+        }
+        return this.session.deviceIdentity(appQuery(identity));
+    }
+    async isInstalled(identity) {
+        this.assertBoundSerial(identity.deviceSerial);
+        return this.session.isInstalled(appQuery(identity));
+    }
+    async launchActivity(options) {
+        this.assertBoundSerial(options.deviceSerial);
+        return this.session.launchApp(launchOptions(options));
+    }
+    async startActivityByIntent(options) {
+        this.assertBoundSerial(options.deviceSerial);
+        if (this.session.startActivityByIntent === undefined) {
+            throw runtimeCapabilityMissing(this.session.descriptor.id, "startActivityByIntent");
+        }
+        return this.session.startActivityByIntent({
+            action: options.action,
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            ...(options.timeoutMs === undefined
+                ? {}
+                : { timeoutMs: options.timeoutMs })
+        });
+    }
+    resolveLauncherActivity() {
+        return Promise.reject(new Error("resolveLauncherActivity is not available through the runtime backend SPI"));
+    }
+    async forceStop(identity) {
+        this.assertBoundSerial(identity.deviceSerial);
+        return this.session.forceStop(appQuery(identity));
+    }
+    async appProcesses(identity) {
+        this.assertBoundSerial(identity.deviceSerial);
+        if (this.session.appProcesses === undefined) {
+            throw runtimeCapabilityMissing(this.session.descriptor.id, "appProcesses");
+        }
+        return this.session.appProcesses(appQuery(identity));
+    }
+    async windowTopology(identity) {
+        this.assertBoundSerial(identity.deviceSerial);
+        if (this.session.windowTopology === undefined) {
+            throw runtimeCapabilityMissing(this.session.descriptor.id, "windowTopology");
+        }
+        return this.session.windowTopology(appQuery(identity));
+    }
+    async tap(point, deviceSerial, signal) {
+        this.assertBoundSerial(deviceSerial);
+        return this.session.tap(point, signal);
+    }
+    async longClick(point, durationMs, deviceSerial, signal) {
+        this.assertBoundSerial(deviceSerial);
+        return this.session.longClick(point, durationMs, signal);
+    }
+    async swipe(from, to, durationMs, deviceSerial, signal) {
+        this.assertBoundSerial(deviceSerial);
+        return this.session.swipe(from, to, durationMs, signal);
+    }
+    async back(deviceSerial, signal) {
+        this.assertBoundSerial(deviceSerial);
+        return this.session.back(signal);
+    }
+    async inputText(text, deviceSerial, signal) {
+        this.assertBoundSerial(deviceSerial);
+        return this.session.inputText(text, signal);
+    }
+    startLogcat(options) {
+        this.assertBoundSerial(options.deviceSerial);
+        if (this.session.startLogcat === undefined) {
+            throw runtimeCapabilityMissing(this.session.descriptor.id, "startLogcat");
+        }
+        const running = this.session.startLogcat({
+            onStdoutLine: options.onStdoutLine,
+            ...(options.onStderrLine === undefined
+                ? {}
+                : { onStderrLine: options.onStderrLine }),
+            ...(options.signal === undefined ? {} : { signal: options.signal })
+        });
+        return {
+            started: running.started,
+            completion: running.completion,
+            stop: () => running.stop()
+        };
+    }
+    async dumpLogcat(options) {
+        this.assertBoundSerial(options.deviceSerial);
+        if (this.session.dumpLogcat === undefined) {
+            throw runtimeCapabilityMissing(this.session.descriptor.id, "dumpLogcat");
+        }
+        return this.session.dumpLogcat({
+            maxLines: options.maxLines,
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            ...(options.timeoutMs === undefined
+                ? {}
+                : { timeoutMs: options.timeoutMs })
+        });
+    }
+    assertBoundSerial(deviceSerial) {
+        if (deviceSerial !== this.session.deviceSerial) {
+            throw new Error(`Runtime session bound to "${this.session.deviceSerial}" cannot `
+                + `serve device "${deviceSerial}"`);
+        }
+    }
+}
+/** One borrowed session exposed as the serial-keyed `ScreenshotPort`. */
+export class SessionBoundScreenshotAdapter {
+    session;
+    constructor(session) {
+        this.session = session;
+    }
+    capture(options) {
+        if (options.deviceSerial !== this.session.deviceSerial) {
+            return Promise.reject(new Error(`Runtime session bound to "${this.session.deviceSerial}" cannot `
+                + `serve device "${options.deviceSerial}"`));
+        }
+        return this.session.captureScreenshot({
+            outputPath: options.outputPath,
+            ...(options.annotate === undefined ? {} : { annotate: options.annotate }),
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs })
+        });
+    }
+}
+/**
+ * Legacy port views for one borrowed session: the `AdbPort` view above, a
+ * session-bound screenshot port, the session's annotated-screen resolver
+ * (fail-closed when the backend lacks the capability), and the required UI
+ * stability probe. Session-first orchestrators pass these views to helpers
+ * that still speak the legacy port types.
+ */
+export function runtimeSessionPortViews(session) {
+    return {
+        adb: new RuntimeSessionAdbView(session),
+        screenshots: new SessionBoundScreenshotAdapter(session),
+        annotatedScreens: session.annotatedScreens
+            ?? new FailClosedAnnotatedScreenResolver(session.descriptor.id),
+        uiStability: session.uiStability
+    };
+}

package/dist/adapters/runtime/session-backed-ports.d.ts

@@ -0,0 +1,21 @@
+import type { Point } from "../../domain/geometry.js";
+import type { AnnotatedScreenResolverPort } from "../../ports/annotated-screen-resolver.js";
+import type { CommandResult } from "../../ports/process-runner.js";
+import type { RuntimeSessionOpener } from "../../ports/runtime-backend.js";
+import type { ScreenshotOptions, ScreenshotPort } from "../../ports/screenshot.js";
+import type { OpenUiSnapshotProviderOptions, UiSnapshotProvider, UiSnapshotProviderFactory } from "../../ports/ui-snapshot.js";
+export declare class SessionBackedScreenshotAdapter implements ScreenshotPort {
+    private readonly sessions;
+    constructor(sessions: RuntimeSessionOpener);
+    capture(options: ScreenshotOptions): Promise<CommandResult>;
+}
+export declare class SessionBackedUiSnapshotProviderFactory implements UiSnapshotProviderFactory {
+    private readonly sessions;
+    constructor(sessions: RuntimeSessionOpener);
+    open(options: OpenUiSnapshotProviderOptions): Promise<UiSnapshotProvider>;
+}
+export declare class FailClosedAnnotatedScreenResolver implements AnnotatedScreenResolverPort {
+    private readonly backendId;
+    constructor(backendId: string);
+    resolve(): Promise<Point>;
+}

package/dist/adapters/runtime/session-backed-ports.js

@@ -0,0 +1,43 @@
+import { runtimeCapabilityMissing } from "../../ports/runtime-capability.js";
+export class SessionBackedScreenshotAdapter {
+    sessions;
+    constructor(sessions) {
+        this.sessions = sessions;
+    }
+    capture(options) {
+        return this.sessions.openSession({
+            deviceSerial: options.deviceSerial,
+            ...(options.signal === undefined ? {} : { signal: options.signal })
+        }).then((session) => (session.captureScreenshot({
+            outputPath: options.outputPath,
+            ...(options.annotate === undefined ? {} : { annotate: options.annotate }),
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs })
+        })));
+    }
+}
+export class SessionBackedUiSnapshotProviderFactory {
+    sessions;
+    constructor(sessions) {
+        this.sessions = sessions;
+    }
+    open(options) {
+        return this.sessions.openSession({
+            deviceSerial: options.deviceSerial,
+            ...(options.signal === undefined ? {} : { signal: options.signal })
+        }).then((session) => (session.openUiSnapshots({
+            timeoutMs: options.timeoutMs,
+            ...(options.backend === undefined ? {} : { backend: options.backend }),
+            ...(options.signal === undefined ? {} : { signal: options.signal })
+        })));
+    }
+}
+export class FailClosedAnnotatedScreenResolver {
+    backendId;
+    constructor(backendId) {
+        this.backendId = backendId;
+    }
+    resolve() {
+        return Promise.reject(runtimeCapabilityMissing(this.backendId, "annotated screens"));
+    }
+}

package/dist/adapters/runtime/shared-session-runtime-backend.d.ts

@@ -0,0 +1,12 @@
+import type { DeviceInfo } from "../../domain/runtime.js";
+import type { OpenRuntimeSessionOptions, RuntimeBackend, RuntimeSession } from "../../ports/runtime-backend.js";
+export declare class SharedSessionRuntimeBackend implements RuntimeBackend {
+    private readonly backend;
+    private readonly sessions;
+    constructor(backend: RuntimeBackend);
+    get descriptor(): RuntimeBackend["descriptor"];
+    get capabilities(): RuntimeBackend["capabilities"];
+    listDevices(signal?: AbortSignal): Promise<readonly DeviceInfo[]>;
+    openSession(options: OpenRuntimeSessionOptions): Promise<RuntimeSession>;
+    close(): Promise<void>;
+}

package/dist/adapters/runtime/shared-session-runtime-backend.js

@@ -0,0 +1,64 @@
+function borrowedProvider(provider) {
+    return new Proxy(provider, {
+        get(target, property, receiver) {
+            if (property === "close") {
+                return () => Promise.resolve();
+            }
+            const value = Reflect.get(target, property, receiver);
+            return typeof value === "function"
+                ? value.bind(target)
+                : value;
+        }
+    });
+}
+function borrowedSession(session) {
+    return new Proxy(session, {
+        get(target, property, receiver) {
+            if (property === "close") {
+                return () => Promise.resolve();
+            }
+            if (property === "openUiSnapshots") {
+                return async (options) => borrowedProvider(await target.openUiSnapshots(options));
+            }
+            const value = Reflect.get(target, property, receiver);
+            return typeof value === "function"
+                ? value.bind(target)
+                : value;
+        }
+    });
+}
+export class SharedSessionRuntimeBackend {
+    backend;
+    sessions = new Map();
+    constructor(backend) {
+        this.backend = backend;
+    }
+    get descriptor() {
+        return this.backend.descriptor;
+    }
+    get capabilities() {
+        return this.backend.capabilities;
+    }
+    listDevices(signal) {
+        return this.backend.listDevices(signal);
+    }
+    openSession(options) {
+        const existing = this.sessions.get(options.deviceSerial);
+        if (existing !== undefined) {
+            return existing.then(borrowedSession);
+        }
+        const opened = this.backend.openSession(options);
+        opened.catch(() => {
+            if (this.sessions.get(options.deviceSerial) === opened) {
+                this.sessions.delete(options.deviceSerial);
+            }
+        });
+        this.sessions.set(options.deviceSerial, opened);
+        return opened.then(borrowedSession);
+    }
+    async close() {
+        const sessions = [...this.sessions.values()];
+        this.sessions.clear();
+        await Promise.all(sessions.map((session) => (session.then((opened) => opened.close(), () => undefined))));
+    }
+}

package/dist/adapters/ui/auto-ui-snapshot-provider.d.ts

@@ -0,0 +1,8 @@
+import type { OpenUiSnapshotProviderOptions, UiSnapshotProvider, UiSnapshotProviderFactory } from "../../ports/ui-snapshot.js";
+export declare class AutoUiSnapshotProviderFactory implements UiSnapshotProviderFactory {
+    private readonly system;
+    private readonly androidCli;
+    private readonly appium?;
+    constructor(system: UiSnapshotProviderFactory, androidCli: UiSnapshotProviderFactory, appium?: UiSnapshotProviderFactory | undefined);
+    open(options: OpenUiSnapshotProviderOptions): Promise<UiSnapshotProvider>;
+}

package/dist/adapters/ui/auto-ui-snapshot-provider.js

@@ -0,0 +1,48 @@
+import { UiSnapshotError } from "./ui-snapshot-error.js";
+export class AutoUiSnapshotProviderFactory {
+    system;
+    androidCli;
+    appium;
+    constructor(system, androidCli, appium) {
+        this.system = system;
+        this.androidCli = androidCli;
+        this.appium = appium;
+    }
+    async open(options) {
+        if (options.backend === "system-uiautomator") {
+            return this.system.open(options);
+        }
+        if (options.backend === "android-cli") {
+            return this.androidCli.open(options);
+        }
+        if (options.backend === "appium-uiautomator2") {
+            if (this.appium !== undefined)
+                return this.appium.open(options);
+            throw new UiSnapshotError("UI_BACKEND_UNAVAILABLE", "appium-uiautomator2", "Appium UiAutomator2 provider is not installed");
+        }
+        const appium = this.appium;
+        const probe = appium;
+        if (probe?.probe !== undefined && await probe.probe(options.timeoutMs)) {
+            try {
+                return await appium.open(options);
+            }
+            catch (error) {
+                if (!isAutoFallbackable(error))
+                    throw error;
+            }
+        }
+        try {
+            return await this.system.open(options);
+        }
+        catch (error) {
+            if (!isAutoFallbackable(error))
+                throw error;
+        }
+        return this.androidCli.open(options);
+    }
+}
+function isAutoFallbackable(error) {
+    return error instanceof UiSnapshotError
+        && (error.code === "UI_BACKEND_UNAVAILABLE"
+            || error.code === "UI_SNAPSHOT_INVALID");
+}

package/dist/adapters/ui/device-layout-temp.d.ts

@@ -0,0 +1,6 @@
+import type { ProcessRunner } from "../../ports/process-runner.js";
+export declare const DEVICE_LAYOUT_TEMP_PREFIX = "/data/local/tmp/taphound-uiautomator-";
+export declare const DEVICE_LAYOUT_TEMP_GLOB = "/data/local/tmp/taphound-uiautomator-*.xml";
+export declare const DEVICE_LAYOUT_TEMP_SWEEP_TIMEOUT_MS = 5000;
+export declare function createDeviceLayoutPath(): string;
+export declare function sweepDeviceLayoutTemp(runner: ProcessRunner, deviceSerial: string, signal?: AbortSignal): Promise<void>;

package/dist/adapters/ui/device-layout-temp.js

@@ -0,0 +1,18 @@
+import { randomUUID } from "node:crypto";
+export const DEVICE_LAYOUT_TEMP_PREFIX = "/data/local/tmp/taphound-uiautomator-";
+export const DEVICE_LAYOUT_TEMP_GLOB = `${DEVICE_LAYOUT_TEMP_PREFIX}*.xml`;
+export const DEVICE_LAYOUT_TEMP_SWEEP_TIMEOUT_MS = 5000;
+export function createDeviceLayoutPath() {
+    return `${DEVICE_LAYOUT_TEMP_PREFIX}${randomUUID()}.xml`;
+}
+export async function sweepDeviceLayoutTemp(runner, deviceSerial, signal) {
+    if (signal?.aborted === true) {
+        return;
+    }
+    await runner.run({
+        executable: "adb",
+        args: ["-s", deviceSerial, "shell", "rm", "-f", DEVICE_LAYOUT_TEMP_GLOB],
+        timeoutMs: DEVICE_LAYOUT_TEMP_SWEEP_TIMEOUT_MS,
+        ...(signal === undefined ? {} : { signal })
+    }).catch(() => undefined);
+}

package/dist/adapters/ui/device-ui-environment.d.ts

@@ -0,0 +1,13 @@
+import { type DisplayViewport } from "../../domain/geometry.js";
+import type { UiBackendDescriptor } from "../../domain/ui-backend.js";
+import type { ProcessRunner } from "../../ports/process-runner.js";
+export interface DeviceUiEnvironment {
+    sdkLevel: number;
+    viewport: DisplayViewport;
+}
+export declare function parseDisplayRotation(dumpsysInput: string): DisplayViewport["rotation"] | undefined;
+export declare function readDeviceUiEnvironment(runner: ProcessRunner, backendId: UiBackendDescriptor["id"], options: {
+    deviceSerial: string;
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+}): Promise<DeviceUiEnvironment>;

package/dist/adapters/ui/device-ui-environment.js

@@ -0,0 +1,81 @@
+import { performance } from "node:perf_hooks";
+import { DisplayViewportSchema } from "../../domain/geometry.js";
+import { UiSnapshotError } from "./ui-snapshot-error.js";
+function usable(result) {
+    return result.exitCode === 0
+        && !result.timedOut
+        && !result.cancelled
+        && result.spawnError === undefined;
+}
+function message(result, fallback) {
+    return result.stderr.trim() || result.spawnError || fallback;
+}
+export function parseDisplayRotation(dumpsysInput) {
+    const orientation = /SurfaceOrientation:\s*([0-3])/i.exec(dumpsysInput)?.[1]
+        ?? /Viewport[^\n]*\borientation=([0-3])\b/i.exec(dumpsysInput)?.[1];
+    if (orientation !== undefined) {
+        return [0, 90, 180, 270][Number(orientation)];
+    }
+    const rotationIndex = /\bRotation([0-3])\b/i.exec(dumpsysInput)?.[1];
+    if (rotationIndex !== undefined) {
+        return [0, 90, 180, 270][Number(rotationIndex)];
+    }
+    const degrees = /\bROT_(0|90|180|270)\b/i.exec(dumpsysInput)?.[1];
+    if (degrees === undefined)
+        return undefined;
+    const parsed = Number(degrees);
+    return parsed === 0 || parsed === 90 || parsed === 180 || parsed === 270
+        ? parsed
+        : undefined;
+}
+export async function readDeviceUiEnvironment(runner, backendId, options) {
+    const startedAt = performance.now();
+    const run = async (args) => {
+        const remainingMs = Math.max(1, options.timeoutMs - (performance.now() - startedAt));
+        const result = await runner.run({
+            executable: "adb",
+            args: ["-s", options.deviceSerial, ...args],
+            timeoutMs: remainingMs,
+            ...(options.signal === undefined ? {} : { signal: options.signal })
+        });
+        if (!usable(result)) {
+            throw new UiSnapshotError(result.timedOut || result.cancelled
+                ? "UI_SNAPSHOT_FAILED"
+                : "UI_BACKEND_UNAVAILABLE", backendId, message(result, `Unable to inspect device UI environment`));
+        }
+        return result;
+    };
+    const sdkResult = await run([
+        "shell",
+        "getprop",
+        "ro.build.version.sdk"
+    ]);
+    const sdkLevel = Number(sdkResult.stdout.trim());
+    if (!Number.isSafeInteger(sdkLevel)) {
+        throw new UiSnapshotError("UI_BACKEND_UNAVAILABLE", backendId, "Device returned an invalid Android SDK level");
+    }
+    if (sdkLevel < 26) {
+        throw new UiSnapshotError("UI_BACKEND_UNAVAILABLE", backendId, `UI snapshots require Android API 26 or newer; device is API ${String(sdkLevel)}`);
+    }
+    const sizeResult = await run(["shell", "wm", "size"]);
+    const size = /(?:Physical size:\s*)?(\d+)x(\d+)/i.exec(sizeResult.stdout);
+    const width = Number(size?.[1]);
+    const height = Number(size?.[2]);
+    if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height)) {
+        throw new UiSnapshotError("UI_BACKEND_UNAVAILABLE", backendId, "Device returned an invalid physical display size");
+    }
+    const rotationResult = await run(["shell", "dumpsys", "input"]);
+    const rotation = parseDisplayRotation(rotationResult.stdout);
+    if (rotation === undefined) {
+        throw new UiSnapshotError("UI_BACKEND_UNAVAILABLE", backendId, "Device returned an invalid display rotation");
+    }
+    return {
+        sdkLevel,
+        viewport: DisplayViewportSchema.parse({
+            width,
+            height,
+            rotation,
+            coordinateSpace: "physicalDisplayPixels"
+        })
+    };
+}

package/dist/adapters/ui/layout-normalization.d.ts

@@ -0,0 +1,9 @@
+import { type Bounds } from "../../domain/layout.js";
+export declare function normalizeResourceId(value: string | undefined): string | undefined;
+/**
+ * Hot-path variant for already-numeric edges (one call per parsed node).
+ * Enforces the same contract as `RawBoundsSchema` plus `BoundsSchema`
+ * without allocating Zod issues for valid input.
+ */
+export declare function normalizeBoundsEdges(left: number, top: number, right: number, bottom: number): Bounds | undefined;
+export declare function normalizeBounds(value: unknown): Bounds | undefined;

package/dist/adapters/ui/layout-normalization.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { BoundsSchema } from "../../domain/layout.js";
+const RawBoundsSchema = z.strictObject({
+    left: z.number().int().nonnegative(),
+    top: z.number().int().nonnegative(),
+    right: z.number().int().nonnegative(),
+    bottom: z.number().int().nonnegative()
+});
+export function normalizeResourceId(value) {
+    if (value === undefined || value.length === 0)
+        return undefined;
+    const separator = value.lastIndexOf(":id/");
+    return separator >= 0 ? value.slice(separator + 4) : value;
+}
+function isEdge(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}
+/**
+ * Hot-path variant for already-numeric edges (one call per parsed node).
+ * Enforces the same contract as `RawBoundsSchema` plus `BoundsSchema`
+ * without allocating Zod issues for valid input.
+ */
+export function normalizeBoundsEdges(left, top, right, bottom) {
+    if (!isEdge(left) || !isEdge(top) || !isEdge(right) || !isEdge(bottom)) {
+        return normalizeBounds({ left, top, right, bottom });
+    }
+    if (right < left || bottom < top) {
+        throw new Error("Bounds edges are reversed");
+    }
+    if (right === left || bottom === top) {
+        return undefined;
+    }
+    return { left, top, right, bottom };
+}
+export function normalizeBounds(value) {
+    const raw = RawBoundsSchema.parse(value);
+    if (raw.right < raw.left || raw.bottom < raw.top) {
+        throw new Error("Bounds edges are reversed");
+    }
+    if (raw.right === raw.left || raw.bottom === raw.top) {
+        return undefined;
+    }
+    return BoundsSchema.parse(raw);
+}

package/dist/adapters/ui/ui-snapshot-error.d.ts

@@ -0,0 +1,11 @@
+import type { UiBackendDescriptor } from "../../domain/ui-backend.js";
+export type UiSnapshotErrorCode = "UI_BACKEND_UNAVAILABLE" | "UI_SNAPSHOT_FAILED" | "UI_SNAPSHOT_INVALID";
+export declare class UiSnapshotError extends Error {
+    readonly code: UiSnapshotErrorCode;
+    readonly backendId: UiBackendDescriptor["id"];
+    readonly name = "UiSnapshotError";
+    readonly terminal: boolean;
+    constructor(code: UiSnapshotErrorCode, backendId: UiBackendDescriptor["id"], message: string, options?: ErrorOptions & {
+        terminal?: boolean | undefined;
+    });
+}

package/dist/adapters/ui/ui-snapshot-error.js

@@ -0,0 +1,12 @@
+export class UiSnapshotError extends Error {
+    code;
+    backendId;
+    name = "UiSnapshotError";
+    terminal;
+    constructor(code, backendId, message, options) {
+        super(message, options);
+        this.code = code;
+        this.backendId = backendId;
+        this.terminal = options?.terminal ?? false;
+    }
+}