@mobilewright/inspector 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import { type MobilewrightLauncher } from './lib/device-manager.js';
+export type { MobilewrightLauncher };
+/** Options passed to {@link start}. */
+export interface InspectorOptions {
+    /** iOS launcher from mobilewright. */
+    ios: MobilewrightLauncher;
+    /** Android launcher from mobilewright. */
+    android: MobilewrightLauncher;
+    /** HTTP port to listen on. Defaults to 4621. */
+    port?: number;
+}
+/** Handle returned by {@link start} to retrieve the server URL and shut it down. */
+export interface InspectorServer {
+    /** The URL the inspector is listening on, e.g. `http://localhost:4621`. */
+    url: string;
+    /** Gracefully close the device connection and stop the HTTP server. */
+    close: () => Promise<void>;
+}
+/**
+ * Start the Mobilewright Inspector HTTP server.
+ * Pass the ios and android launcher objects from mobilewright so the inspector
+ * can list and connect to devices without a circular dependency.
+ */
+export declare function start({ ios, android, port }: InspectorOptions): Promise<InspectorServer>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAiB,KAAK,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAInF,YAAY,EAAE,oBAAoB,EAAE,CAAC;AAErC,uCAAuC;AACvC,MAAM,WAAW,gBAAgB;IAC/B,sCAAsC;IACtC,GAAG,EAAE,oBAAoB,CAAC;IAC1B,0CAA0C;IAC1C,OAAO,EAAE,oBAAoB,CAAC;IAC9B,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,oFAAoF;AACpF,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAC;IACZ,uEAAuE;IACvE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAsB,KAAK,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,IAAW,EAAE,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAwCrG"}

package/dist/index.js

@@ -0,0 +1,46 @@
+import express from 'express';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import http from 'node:http';
+import { DeviceManager } from './lib/device-manager.js';
+import { createDevicesRouter } from './routes/devices.js';
+import { createInspectRouter } from './routes/inspect.js';
+/**
+ * Start the Mobilewright Inspector HTTP server.
+ * Pass the ios and android launcher objects from mobilewright so the inspector
+ * can list and connect to devices without a circular dependency.
+ */
+export async function start({ ios, android, port = 4621 }) {
+    const publicDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'public');
+    const app = express();
+    app.use(express.json());
+    app.use(express.static(publicDir));
+    app.get('/health', (_req, res) => res.json({ ok: true }));
+    const deviceManager = new DeviceManager({ ios, android });
+    app.use('/api/devices', createDevicesRouter(deviceManager));
+    app.use('/api', createInspectRouter(deviceManager));
+    // 4-argument signature is required by Express to treat this as an error handler
+    app.use((err, _req, res, _next) => {
+        res.status(500).json({ error: err.message });
+    });
+    const server = http.createServer(app);
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, '127.0.0.1', () => resolve());
+    });
+    const assignedPort = server.address().port;
+    const url = `http://127.0.0.1:${assignedPort}`;
+    /** Gracefully drain the device connection and shut down the HTTP server. */
+    async function close() {
+        await new Promise(resolve => {
+            server.close(() => resolve());
+            server.closeAllConnections();
+        });
+        await Promise.race([
+            deviceManager.close().catch(() => { }),
+            new Promise(r => setTimeout(r, 3000)),
+        ]);
+    }
+    return { url, close };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/lib/device-manager.d.ts

@@ -0,0 +1,71 @@
+import type { Device } from '@mobilewright/core';
+import type { DeviceInfo } from '@mobilewright/protocol';
+/** Platform launcher injected from mobilewright to avoid a circular dependency. */
+export interface MobilewrightLauncher {
+    /** List all connected/booted devices for this platform. */
+    devices(): Promise<DeviceInfo[]>;
+    /** Launch and connect to a specific device by id. */
+    launch(opts: {
+        deviceId: string;
+        autoStart?: boolean;
+        autoAppLaunch?: boolean;
+    }): Promise<Device>;
+}
+/** Discriminated union of error codes thrown by DeviceManager. */
+export type DeviceErrorCode = 'blocked' | 'in_progress' | 'not_found' | 'connect_failed';
+/** Structured error thrown by DeviceManager for expected failure modes. */
+export declare class DeviceError extends Error {
+    /** Machine-readable error code indicating the failure reason. */
+    readonly code: DeviceErrorCode;
+    /** @param message Human-readable description. @param code Machine-readable failure reason. */
+    constructor(message: string, code: DeviceErrorCode);
+}
+/** DeviceInfo tagged with its platform, returned by listDevices(). */
+export type TaggedDeviceInfo = DeviceInfo & {
+    platform: 'ios' | 'android';
+};
+/** Minimal device identity record held by DeviceManager while a device is active. */
+export type DeviceInfoRecord = {
+    id: string;
+    platform: 'ios' | 'android';
+};
+/**
+ * Manages a single active device connection shared across the inspect lifecycle.
+ * Coordinates concurrent select() and inspect operations via in-flight flags.
+ */
+export declare class DeviceManager {
+    #private;
+    /** @param ios iOS launcher from mobilewright. @param android Android launcher from mobilewright. */
+    constructor({ ios, android }: {
+        ios: MobilewrightLauncher;
+        android: MobilewrightLauncher;
+    });
+    /**
+     * List all connected/booted devices across both platforms.
+     * Each platform is queried independently so a failure on one does not hide the other.
+     */
+    listDevices(): Promise<TaggedDeviceInfo[]>;
+    /**
+     * Connect to a device, closing any previous connection first.
+     * Throws DeviceError if an inspect is in flight, a select is already in progress,
+     * or the previous device cannot be cleanly disconnected.
+     */
+    select(deviceId: string, platform: 'ios' | 'android'): Promise<Device>;
+    /**
+     * Mark the start of an inspect operation.
+     * Returns false if an inspect is already in flight or a device switch is in progress.
+     */
+    beginInspect(): boolean;
+    /** Clear the inspect-in-flight flag set by beginInspect(). */
+    endInspect(): void;
+    /**
+     * Close the active device connection. Safe to call with no active device.
+     * Throws if the underlying driver close fails; state is only cleared on success.
+     */
+    close(): Promise<void>;
+    /** The currently connected device, or null if none selected. */
+    get device(): Device | null;
+    /** Id and platform of the currently connected device, or null if none selected. */
+    get deviceInfo(): DeviceInfoRecord | null;
+}
+//# sourceMappingURL=device-manager.d.ts.map

package/dist/lib/device-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-manager.d.ts","sourceRoot":"","sources":["../../src/lib/device-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGzD,mFAAmF;AACnF,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,OAAO,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IACjC,qDAAqD;IACrD,MAAM,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACnG;AAED,kEAAkE;AAClE,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,aAAa,GAAG,WAAW,GAAG,gBAAgB,CAAC;AAEzF,2EAA2E;AAC3E,qBAAa,WAAY,SAAQ,KAAK;IACpC,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAE/B,8FAA8F;gBAClF,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe;CAKnD;AAED,sEAAsE;AACtE,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG;IAAE,QAAQ,EAAE,KAAK,GAAG,SAAS,CAAA;CAAE,CAAC;AAE5E,qFAAqF;AACrF,MAAM,MAAM,gBAAgB,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,KAAK,GAAG,SAAS,CAAA;CAAE,CAAC;AAE3E;;;GAGG;AACH,qBAAa,aAAa;;IAgBxB,oGAAoG;gBACxF,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE;QAAE,GAAG,EAAE,oBAAoB,CAAC;QAAC,OAAO,EAAE,oBAAoB,CAAA;KAAE;IAK1F;;;OAGG;IACG,WAAW,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAahD;;;;OAIG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IAsC5E;;;OAGG;IACH,YAAY,IAAI,OAAO;IAMvB,8DAA8D;IAC9D,UAAU,IAAI,IAAI;IAIlB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAe5B,gEAAgE;IAChE,IAAI,MAAM,IAAI,MAAM,GAAG,IAAI,CAA+B;IAE1D,mFAAmF;IACnF,IAAI,UAAU,IAAI,gBAAgB,GAAG,IAAI,CAAmC;CAC7E"}

package/dist/lib/device-manager.js

@@ -0,0 +1,142 @@
+import { logger } from './logger.js';
+/** Structured error thrown by DeviceManager for expected failure modes. */
+export class DeviceError extends Error {
+    /** @param message Human-readable description. @param code Machine-readable failure reason. */
+    constructor(message, code) {
+        super(message);
+        this.name = 'DeviceError';
+        this.code = code;
+    }
+}
+/**
+ * Manages a single active device connection shared across the inspect lifecycle.
+ * Coordinates concurrent select() and inspect operations via in-flight flags.
+ */
+export class DeviceManager {
+    /** iOS launcher instance. */
+    #ios;
+    /** Android launcher instance. */
+    #android;
+    /** Currently connected device driver, or null when no device is selected. */
+    #activeDevice = null;
+    /** Identity of the currently connected device, or null when no device is selected. */
+    #activeDeviceInfo = null;
+    /** True while an inspect operation is in progress; blocks concurrent select(). */
+    #inspectInFlight = false;
+    /** True while a select() call is awaiting launcher.launch(); blocks concurrent select(). */
+    #selecting = false;
+    /** True after close() is called; prevents new connections after shutdown. */
+    #closed = false;
+    /** @param ios iOS launcher from mobilewright. @param android Android launcher from mobilewright. */
+    constructor({ ios, android }) {
+        this.#ios = ios;
+        this.#android = android;
+    }
+    /**
+     * List all connected/booted devices across both platforms.
+     * Each platform is queried independently so a failure on one does not hide the other.
+     */
+    async listDevices() {
+        const [iosResult, androidResult] = await Promise.allSettled([
+            this.#ios.devices(),
+            this.#android.devices(),
+        ]);
+        if (iosResult.status === 'rejected')
+            logger.warn(`iOS device list failed: ${iosResult.reason?.message}`);
+        if (androidResult.status === 'rejected')
+            logger.warn(`Android device list failed: ${androidResult.reason?.message}`);
+        return [
+            ...(iosResult.status === 'fulfilled' ? iosResult.value.map(d => ({ ...d, platform: 'ios' })) : []),
+            ...(androidResult.status === 'fulfilled' ? androidResult.value.map(d => ({ ...d, platform: 'android' })) : []),
+        ];
+    }
+    /**
+     * Connect to a device, closing any previous connection first.
+     * Throws DeviceError if an inspect is in flight, a select is already in progress,
+     * or the previous device cannot be cleanly disconnected.
+     */
+    async select(deviceId, platform) {
+        if (this.#closed)
+            throw new DeviceError('DeviceManager is closed', 'connect_failed');
+        if (this.#inspectInFlight)
+            throw new DeviceError('Device switch blocked: inspect in progress', 'blocked');
+        if (this.#selecting)
+            throw new DeviceError('Device switch already in progress', 'in_progress');
+        this.#selecting = true;
+        try {
+            if (this.#activeDevice) {
+                logger.info(`Closing previous device ${this.#activeDeviceInfo?.id}`);
+                try {
+                    await this.#activeDevice.close();
+                    this.#activeDevice = null;
+                    this.#activeDeviceInfo = null;
+                }
+                catch (err) {
+                    logger.error(`Failed to close device ${this.#activeDeviceInfo?.id}: ${err.message}`);
+                    throw new DeviceError(err.message, 'connect_failed');
+                }
+            }
+            logger.info(`Connecting to ${platform} device ${deviceId}`);
+            const launcher = platform === 'ios' ? this.#ios : this.#android;
+            const launched = await launcher.launch({ deviceId, autoStart: true, autoAppLaunch: false });
+            if (this.#closed) {
+                try {
+                    await launched.close();
+                }
+                catch { }
+                throw new DeviceError('DeviceManager closed during connect', 'connect_failed');
+            }
+            this.#activeDevice = launched;
+            this.#activeDeviceInfo = { id: deviceId, platform };
+            logger.info(`Connected to ${deviceId}`);
+            return this.#activeDevice;
+        }
+        catch (err) {
+            if (err instanceof DeviceError)
+                throw err;
+            logger.error(`Failed to connect to ${deviceId}: ${err.message}`);
+            throw new DeviceError(err.message, 'connect_failed');
+        }
+        finally {
+            this.#selecting = false;
+        }
+    }
+    /**
+     * Mark the start of an inspect operation.
+     * Returns false if an inspect is already in flight or a device switch is in progress.
+     */
+    beginInspect() {
+        if (this.#inspectInFlight || this.#selecting)
+            return false;
+        this.#inspectInFlight = true;
+        return true;
+    }
+    /** Clear the inspect-in-flight flag set by beginInspect(). */
+    endInspect() {
+        this.#inspectInFlight = false;
+    }
+    /**
+     * Close the active device connection. Safe to call with no active device.
+     * Throws if the underlying driver close fails; state is only cleared on success.
+     */
+    async close() {
+        this.#closed = true;
+        if (this.#activeDevice) {
+            logger.info(`Closing device ${this.#activeDeviceInfo?.id}`);
+            try {
+                await this.#activeDevice.close();
+                this.#activeDevice = null;
+                this.#activeDeviceInfo = null;
+            }
+            catch (err) {
+                logger.error(`Failed to close device ${this.#activeDeviceInfo?.id}: ${err.message}`);
+                throw new DeviceError(err.message, 'connect_failed');
+            }
+        }
+    }
+    /** The currently connected device, or null if none selected. */
+    get device() { return this.#activeDevice; }
+    /** Id and platform of the currently connected device, or null if none selected. */
+    get deviceInfo() { return this.#activeDeviceInfo; }
+}
+//# sourceMappingURL=device-manager.js.map

package/dist/lib/device-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-manager.js","sourceRoot":"","sources":["../../src/lib/device-manager.ts"],"names":[],"mappings":"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"}

package/dist/lib/locator-derivation.d.ts

@@ -0,0 +1,30 @@
+import type { ViewNode } from '@mobilewright/protocol';
+/** Discriminated union of the four locator strategies mobilewright supports. */
+export type Locator = {
+    kind: 'testId';
+    value: string;
+} | {
+    kind: 'role';
+    value: string;
+    name: string | undefined;
+} | {
+    kind: 'label';
+    value: string;
+} | {
+    kind: 'text';
+    value: string;
+};
+/**
+ * Derive the best mobilewright locator for a single ViewNode.
+ * Returns null when no supported locator field is present.
+ */
+export declare function deriveLocator(node: ViewNode): Locator | null;
+/**
+ * Flatten a ViewNode tree depth-first and annotate each node with its best locator.
+ * Nodes with no locatable field are included with locator: null.
+ */
+export declare function deriveElementList(roots: ViewNode[]): Array<{
+    node: ViewNode;
+    locator: Locator | null;
+}>;
+//# sourceMappingURL=locator-derivation.d.ts.map

package/dist/lib/locator-derivation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locator-derivation.d.ts","sourceRoot":"","sources":["../../src/lib/locator-derivation.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAkBvD,gFAAgF;AAChF,MAAM,MAAM,OAAO,GACf;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAG,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAG,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAiBtC;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,IAAI,CAgB5D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,QAAQ,EAAE,GAChB,KAAK,CAAC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;CAAE,CAAC,CAapD"}

package/dist/lib/locator-derivation.js

@@ -0,0 +1,69 @@
+// Derives the best mobilewright locator for every node in a ViewNode tree.
+// Priority: Test ID > Role > Label > Text. Mirrors @mobilewright/core query-engine.ts.
+// If mobilewright changes matching rules, update ROLE_TYPE_MAP below to stay in sync.
+/** Maps mobilewright role names to the node type strings that resolve to each role. */
+const ROLE_TYPE_MAP = {
+    button: ['button', 'imagebutton'],
+    textfield: ['textfield', 'securetextfield', 'edittext', 'searchfield', 'reactedittext'],
+    text: ['statictext', 'textview', 'text', 'reacttextview'],
+    image: ['image', 'imageview', 'reactimageview'],
+    switch: ['switch', 'toggle'],
+    checkbox: ['checkbox'],
+    slider: ['slider', 'seekbar'],
+    list: ['table', 'collectionview', 'listview', 'recyclerview', 'scrollview', 'reactscrollview'],
+    listitem: ['cell', 'linearlayout', 'relativelayout'],
+    tab: ['tab', 'tabbar'],
+    link: ['link'],
+    header: ['navigationbar', 'toolbar', 'header'],
+};
+/** Map node.type to a mobilewright role string. Returns null for unmapped types. */
+function deriveRole(node) {
+    const type = (node.type ?? '').toLowerCase();
+    if (type === 'reactviewgroup') {
+        const isClickable = node.raw?.['clickable'] === 'true' || node.raw?.['accessible'] === 'true';
+        return isClickable ? 'button' : null;
+    }
+    for (const [role, types] of Object.entries(ROLE_TYPE_MAP)) {
+        if (types.includes(type))
+            return role;
+    }
+    return null;
+}
+/**
+ * Derive the best mobilewright locator for a single ViewNode.
+ * Returns null when no supported locator field is present.
+ */
+export function deriveLocator(node) {
+    const testId = node.identifier || node.resourceId;
+    if (testId)
+        return { kind: 'testId', value: testId };
+    const role = deriveRole(node);
+    if (role) {
+        const name = node.label || node.text || undefined;
+        return { kind: 'role', value: role, name };
+    }
+    if (node.label)
+        return { kind: 'label', value: node.label };
+    const text = node.text ?? (node.value != null ? String(node.value) : undefined);
+    if (text)
+        return { kind: 'text', value: text };
+    return null;
+}
+/**
+ * Flatten a ViewNode tree depth-first and annotate each node with its best locator.
+ * Nodes with no locatable field are included with locator: null.
+ */
+export function deriveElementList(roots) {
+    const result = [];
+    /** Depth-first recursive walk, pushing each visited node to result. */
+    function walk(nodes) {
+        for (const node of nodes) {
+            result.push({ node, locator: deriveLocator(node) });
+            if (node.children?.length)
+                walk(node.children);
+        }
+    }
+    walk(roots);
+    return result;
+}
+//# sourceMappingURL=locator-derivation.js.map

package/dist/lib/locator-derivation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locator-derivation.js","sourceRoot":"","sources":["../../src/lib/locator-derivation.ts"],"names":[],"mappings":"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"}

package/dist/lib/logger.d.ts

@@ -0,0 +1,10 @@
+/** Structured logger that writes timestamped lines to stderr. */
+export declare const logger: {
+    /** Log an informational message. */
+    info: (msg: string) => void;
+    /** Log a warning. */
+    warn: (msg: string) => void;
+    /** Log an error. */
+    error: (msg: string) => void;
+};
+//# sourceMappingURL=logger.d.ts.map

package/dist/lib/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/lib/logger.ts"],"names":[],"mappings":"AAKA,iEAAiE;AACjE,eAAO,MAAM,MAAM;IACjB,oCAAoC;gBACvB,MAAM;IACnB,qBAAqB;gBACR,MAAM;IACnB,oBAAoB;iBACP,MAAM;CACpB,CAAC"}

package/dist/lib/logger.js

@@ -0,0 +1,14 @@
+/** Write a single timestamped log line to stderr. */
+function log(level, msg) {
+    process.stderr.write(`[${new Date().toISOString()}] ${level} ${msg}\n`);
+}
+/** Structured logger that writes timestamped lines to stderr. */
+export const logger = {
+    /** Log an informational message. */
+    info: (msg) => log('INFO ', msg),
+    /** Log a warning. */
+    warn: (msg) => log('WARN ', msg),
+    /** Log an error. */
+    error: (msg) => log('ERROR', msg),
+};
+//# sourceMappingURL=logger.js.map

package/dist/lib/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/lib/logger.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,SAAS,GAAG,CAAC,KAAa,EAAE,GAAW;IACrC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC,CAAC;AAC1E,CAAC;AAED,iEAAiE;AACjE,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,oCAAoC;IACpC,IAAI,EAAG,CAAC,GAAW,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC;IACzC,qBAAqB;IACrB,IAAI,EAAG,CAAC,GAAW,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC;IACzC,oBAAoB;IACpB,KAAK,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC;CAC1C,CAAC"}

package/dist/routes/devices.d.ts

@@ -0,0 +1,7 @@
+import { DeviceManager } from '../lib/device-manager.js';
+/**
+ * Express router for device listing and selection.
+ * GET /api/devices, POST /api/devices/:id/select
+ */
+export declare function createDevicesRouter(deviceManager: DeviceManager): import("express-serve-static-core").Router;
+//# sourceMappingURL=devices.d.ts.map

package/dist/routes/devices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devices.d.ts","sourceRoot":"","sources":["../../src/routes/devices.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEtE;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,aAAa,8CAsC/D"}

package/dist/routes/devices.js

@@ -0,0 +1,43 @@
+import { Router } from 'express';
+import { DeviceError } from '../lib/device-manager.js';
+/**
+ * Express router for device listing and selection.
+ * GET /api/devices, POST /api/devices/:id/select
+ */
+export function createDevicesRouter(deviceManager) {
+    const router = Router();
+    // GET /api/devices
+    router.get('/', async (_req, res) => {
+        try {
+            const devices = await deviceManager.listDevices();
+            res.json({ devices, activeId: deviceManager.deviceInfo?.id ?? null });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    // POST /api/devices/:id/select  body: { platform: 'ios' | 'android' }
+    router.post('/:id/select', async (req, res) => {
+        const { id } = req.params;
+        const { platform } = (req.body ?? {});
+        if (platform !== 'ios' && platform !== 'android') {
+            res.status(400).json({ error: 'platform must be \'ios\' or \'android\'' });
+            return;
+        }
+        try {
+            const devices = await deviceManager.listDevices();
+            if (!devices.some(d => d.id === id && d.platform === platform)) {
+                res.status(404).json({ error: `Device '${id}' not found` });
+                return;
+            }
+            await deviceManager.select(id, platform);
+            res.json({ ok: true });
+        }
+        catch (err) {
+            const status = err instanceof DeviceError && (err.code === 'blocked' || err.code === 'in_progress') ? 409 : 500;
+            res.status(status).json({ error: err.message });
+        }
+    });
+    return router;
+}
+//# sourceMappingURL=devices.js.map

package/dist/routes/devices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"devices.js","sourceRoot":"","sources":["../../src/routes/devices.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,WAAW,EAAiB,MAAM,0BAA0B,CAAC;AAEtE;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,aAA4B;IAC9D,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC;IAExB,mBAAmB;IACnB,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QAClC,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,WAAW,EAAE,CAAC;YAClD,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,aAAa,CAAC,UAAU,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;QACxE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAG,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,sEAAsE;IACtE,MAAM,CAAC,IAAI,CAAC,aAAa,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QAC5C,MAAM,EAAE,EAAE,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC;QAC1B,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAA0B,CAAC;QAE/D,IAAI,QAAQ,KAAK,KAAK,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YACjD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,yCAAyC,EAAE,CAAC,CAAC;YAC3E,OAAO;QACT,CAAC;QAED,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,WAAW,EAAE,CAAC;YAClD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,EAAE,CAAC;gBAC/D,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,CAAC,CAAC;gBAC5D,OAAO;YACT,CAAC;YACD,MAAM,aAAa,CAAC,MAAM,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;YACzC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;QACzB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,MAAM,GAAG,GAAG,YAAY,WAAW,IAAI,CAAC,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,KAAK,aAAa,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;YAChH,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAG,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/routes/inspect.d.ts

@@ -0,0 +1,7 @@
+import { DeviceManager } from '../lib/device-manager.js';
+/**
+ * Express router for the inspect endpoint.
+ * GET /api/inspect — returns screenshot + element list from the same device moment.
+ */
+export declare function createInspectRouter(deviceManager: DeviceManager): import("express-serve-static-core").Router;
+//# sourceMappingURL=inspect.d.ts.map

package/dist/routes/inspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../src/routes/inspect.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAMzD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,aAAa,8CA2C/D"}

package/dist/routes/inspect.js

@@ -0,0 +1,79 @@
+import { Router } from 'express';
+import { deriveElementList } from '../lib/locator-derivation.js';
+import { logger } from '../lib/logger.js';
+const MAX_RETRIES = 3;
+const RETRY_DELAY_MS = 1500;
+const ATTEMPT_TIMEOUT_MS = 10_000;
+/**
+ * Express router for the inspect endpoint.
+ * GET /api/inspect — returns screenshot + element list from the same device moment.
+ */
+export function createInspectRouter(deviceManager) {
+    const router = Router();
+    // GET /api/inspect
+    // Returns screenshot + element list from the same moment (no drift).
+    router.get('/inspect', async (_req, res) => {
+        const device = deviceManager.device;
+        if (!device) {
+            res.status(409).json({ error: 'No device selected' });
+            return;
+        }
+        if (!deviceManager.beginInspect()) {
+            res.status(503).json({ error: 'Inspect already in progress' });
+            return;
+        }
+        try {
+            const { screenshotBuffer, tree, size } = await attemptWithRetry(device);
+            const elements = deriveElementList(tree).map(({ node, locator }, index) => ({
+                index,
+                type: node.type,
+                label: node.label ?? null,
+                text: node.text ?? null,
+                bounds: node.bounds,
+                isVisible: node.isVisible,
+                locator,
+            }));
+            res.json({
+                screenshot: `data:image/png;base64,${screenshotBuffer.toString('base64')}`,
+                screen: { width: size.width, height: size.height },
+                elements,
+            });
+        }
+        catch (err) {
+            logger.error(`Inspect failed: ${err.message}`);
+            res.status(500).json({ error: err.message });
+        }
+        finally {
+            deviceManager.endInspect();
+        }
+    });
+    return router;
+}
+/** Run screenshot + viewTree + screenSize together, retrying up to MAX_RETRIES times on failure. */
+async function attemptWithRetry(device) {
+    let lastErr;
+    for (let i = 0; i < MAX_RETRIES; i++) {
+        try {
+            return await withTimeout(Promise.all([device.screen.screenshot(), device.screen.viewTree(), device.screenSize()]).then(([screenshotBuffer, tree, size]) => ({ screenshotBuffer, tree, size })), ATTEMPT_TIMEOUT_MS, `Device operation timed out after ${ATTEMPT_TIMEOUT_MS}ms`);
+        }
+        catch (err) {
+            lastErr = err;
+            logger.warn(`Inspect attempt ${i + 1}/${MAX_RETRIES} failed: ${err.message}`);
+            if (i < MAX_RETRIES - 1)
+                await new Promise(r => setTimeout(r, RETRY_DELAY_MS));
+        }
+    }
+    throw lastErr;
+}
+/**
+ * Race promise against a ms deadline. Rejects with message on timeout.
+ * Note: cannot cancel the underlying promise; it continues running until the driver times out.
+ */
+function withTimeout(promise, ms, message) {
+    let timer;
+    return Promise.race([
+        promise,
+        new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(message)), ms); }),
+    ]).finally(() => clearTimeout(timer));
+}
+//# sourceMappingURL=inspect.js.map

package/dist/routes/inspect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.js","sourceRoot":"","sources":["../../src/routes/inspect.ts"],"names":[],"mappings":"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"}