@ceraph/react-native-mcp 0.2.2 → 0.3.2

package/dist/screen.js

@@ -1,67 +1,90 @@
-/**
- * WebDriverAgent client with pixel ratio correction.
- *
- * Talks to the WDA HTTP server running on localhost:8100 to perform
- * taps and element lookups on a connected iOS device.
- */
-const WDA_BASE_URL = "http://localhost:8100";
+import { DEFAULT_DEVICE_WDA_BASE_URL, TargetResolver } from "./target.js";
 const WDA_TIMEOUT_MS = 5000;
-/**
- * Fetch wrapper with timeout for WDA requests.
- */
-async function wdaFetch(path, options = {}) {
-    const url = `${WDA_BASE_URL}${path}`;
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), WDA_TIMEOUT_MS);
-    try {
-        const response = await fetch(url, {
-            ...options,
-            signal: controller.signal,
-            headers: {
-                "Content-Type": "application/json",
-                ...options.headers,
-            },
-        });
-        return response;
-    }
-    finally {
-        clearTimeout(timeout);
-    }
-}
 export class ScreenManager {
     sessionId = null;
     pixelRatio = null;
-    /**
-     * Check whether WebDriverAgent is reachable.
-     */
+    targetResolver;
+    sessionBaseUrl = null;
+    constructor(opts = {}) {
+        this.targetResolver = opts.targetResolver ?? new TargetResolver();
+    }
+    async snapshotTarget() {
+        try {
+            const info = await this.targetResolver.resolve();
+            return { baseUrl: info.baseUrl, ready: info.wdaReady };
+        }
+        catch {
+            return { baseUrl: DEFAULT_DEVICE_WDA_BASE_URL, ready: true };
+        }
+    }
+    async wdaFetchAt(baseUrl, path, options = {}, timeoutMs = WDA_TIMEOUT_MS) {
+        const url = `${baseUrl}${path}`;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetch(url, {
+                ...options,
+                signal: controller.signal,
+                headers: {
+                    "Content-Type": "application/json",
+                    ...options.headers,
+                },
+            });
+            return response;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async wdaFetch(path, options = {}, timeoutMs = WDA_TIMEOUT_MS) {
+        const snapshot = await this.snapshotTarget();
+        if (!snapshot.ready) {
+            throw new Error("WebDriverAgent is not ready for the selected target. If you " +
+                "set CERAPH_TARGET=simulator (or are using a simulator with " +
+                "auto-detection), call `rn_wda_start` first to build and " +
+                "launch WDA against the simulator.");
+        }
+        const baseUrl = this.sessionBaseUrl ?? snapshot.baseUrl;
+        return this.wdaFetchAt(baseUrl, path, options, timeoutMs);
+    }
     async isAvailable() {
+        const snapshot = await this.snapshotTarget();
+        if (!snapshot.ready)
+            return false;
         try {
-            const res = await wdaFetch("/status");
+            const res = await this.wdaFetchAt(snapshot.baseUrl, "/status");
             return res.ok;
         }
         catch {
             return false;
         }
     }
-    /**
-     * Get or create a WDA session. Sessions are cached and revalidated.
-     */
     async ensureSession() {
-        // Try to reuse cached session
+        const snapshot = await this.snapshotTarget();
+        if (!snapshot.ready) {
+            throw new Error("WebDriverAgent is not ready for the selected target. If you " +
+                "set CERAPH_TARGET=simulator (or are using a simulator with " +
+                "auto-detection), call `rn_wda_start` first to build and " +
+                "launch WDA against the simulator.");
+        }
+        const currentBaseUrl = snapshot.baseUrl;
+        if (this.sessionBaseUrl && this.sessionBaseUrl !== currentBaseUrl) {
+            this.sessionId = null;
+            this.pixelRatio = null;
+        }
+        this.sessionBaseUrl = currentBaseUrl;
         if (this.sessionId) {
             try {
-                const res = await wdaFetch(`/session/${this.sessionId}`);
+                const res = await this.wdaFetchAt(currentBaseUrl, `/session/${this.sessionId}`);
                 if (res.ok)
                     return this.sessionId;
             }
             catch {
-                // Session is stale, create a new one
             }
             this.sessionId = null;
         }
-        // Try to find an existing session from /status
         try {
-            const statusRes = await wdaFetch("/status");
+            const statusRes = await this.wdaFetchAt(currentBaseUrl, "/status");
             if (statusRes.ok) {
                 const statusData = (await statusRes.json());
                 const existingId = statusData.sessionId || statusData.value?.sessionId;
@@ -72,10 +95,8 @@ export class ScreenManager {
             }
         }
         catch {
-            // Fall through to session creation
         }
-        // Create a new session
-        const res = await wdaFetch("/session", {
+        const res = await this.wdaFetchAt(currentBaseUrl, "/session", {
             method: "POST",
             body: JSON.stringify({
                 capabilities: {
@@ -95,63 +116,51 @@ export class ScreenManager {
         this.sessionId = sessionId;
         return sessionId;
     }
-    /**
-     * Determine the pixel ratio between screenshot coordinates and
-     * device logical coordinates.
-     *
-     * Screenshot images are in physical pixels; WDA taps use logical points.
-     * The ratio is typically 2 (for @2x Retina) or 3 (for @3x).
-     */
     async getPixelRatio() {
         if (this.pixelRatio)
             return this.pixelRatio;
         const sessionId = await this.ensureSession();
-        // Get the logical window size from WDA
-        const windowRes = await wdaFetch(`/session/${sessionId}/window/size`);
+        const windowRes = await this.wdaFetch(`/session/${sessionId}/window/size`);
         if (!windowRes.ok) {
             throw new Error(`Failed to get window size: ${windowRes.status}`);
         }
         const windowData = (await windowRes.json());
         const logicalWidth = windowData.value.width;
-        // Get a screenshot to measure actual pixel dimensions
-        const screenshotRes = await wdaFetch(`/session/${sessionId}/screenshot`);
+        const screenshotRes = await this.wdaFetch(`/session/${sessionId}/screenshot`);
         if (!screenshotRes.ok) {
-            // Fallback: assume 3x for modern iPhones
             this.pixelRatio = 3;
             return this.pixelRatio;
         }
         const screenshotData = (await screenshotRes.json());
         const base64 = screenshotData.value;
-        // Decode the PNG header to get image width.
-        // PNG stores width as a big-endian 32-bit int at byte offset 16.
         const pngBuffer = Buffer.from(base64, "base64");
         if (pngBuffer.length < 24) {
-            // Not enough data to read PNG header; fallback
             this.pixelRatio = 3;
             return this.pixelRatio;
         }
         const imageWidth = pngBuffer.readUInt32BE(16);
         this.pixelRatio = Math.round(imageWidth / logicalWidth);
-        // Sanity check
         if (this.pixelRatio < 1 || this.pixelRatio > 4) {
-            this.pixelRatio = 3; // safe default for modern iPhones
+            this.pixelRatio = 3;
         }
         return this.pixelRatio;
     }
-    /**
-     * Tap at the given coordinates.
-     *
-     * When `fromScreenshot` is true (the default), the coordinates are
-     * assumed to come from a screenshot image and are divided by the
-     * pixel ratio to convert to logical device points.
-     */
+    async getWindowSize() {
+        const sessionId = await this.ensureSession();
+        const res = await this.wdaFetch(`/session/${sessionId}/window/size`);
+        if (!res.ok) {
+            throw new Error(`Failed to get window size: ${res.status}`);
+        }
+        const data = (await res.json());
+        return data.value;
+    }
     async tap(x, y, fromScreenshot = true) {
         try {
             const sessionId = await this.ensureSession();
             const ratio = await this.getPixelRatio();
             const correctedX = fromScreenshot ? x / ratio : x;
             const correctedY = fromScreenshot ? y / ratio : y;
-            const res = await wdaFetch(`/session/${sessionId}/wda/tap/0`, {
+            const res = await this.wdaFetch(`/session/${sessionId}/wda/tap/0`, {
                 method: "POST",
                 body: JSON.stringify({ x: correctedX, y: correctedY }),
             });
@@ -186,14 +195,10 @@ export class ScreenManager {
             };
         }
     }
-    /**
-     * Find an element in the UI tree and tap its center.
-     */
     async findAndTap(query) {
         try {
             const sessionId = await this.ensureSession();
-            // Fetch the full element source tree
-            const sourceRes = await wdaFetch(`/session/${sessionId}/source?format=json`);
+            const sourceRes = await this.wdaFetch(`/session/${sessionId}/source?format=json`);
             if (!sourceRes.ok) {
                 return {
                     success: false,
@@ -202,10 +207,8 @@ export class ScreenManager {
             }
             const sourceData = (await sourceRes.json());
             const root = sourceData.value;
-            // Find matching elements
             const matches = this.searchElements(root, query);
             if (matches.length === 0) {
-                // Collect a summary of visible elements for debugging
                 const visible = this.collectVisibleElements(root, 50);
                 return {
                     success: false,
@@ -213,7 +216,6 @@ export class ScreenManager {
                     error: `No element found matching query: ${JSON.stringify(query)}`,
                 };
             }
-            // Select the element (by index or first match)
             const index = query.index ?? 0;
             if (index >= matches.length) {
                 return {
@@ -234,11 +236,9 @@ export class ScreenManager {
                     error: "Matched element has no bounds/rect information.",
                 };
             }
-            // Calculate center point (already in device/logical coordinates)
             const centerX = rect.x + rect.width / 2;
             const centerY = rect.y + rect.height / 2;
-            // Tap at center -- these are already logical coordinates, no correction
-            const tapRes = await wdaFetch(`/session/${sessionId}/wda/tap/0`, {
+            const tapRes = await this.wdaFetch(`/session/${sessionId}/wda/tap/0`, {
                 method: "POST",
                 body: JSON.stringify({ x: centerX, y: centerY }),
             });
@@ -274,9 +274,593 @@ export class ScreenManager {
             };
         }
     }
-    /**
-     * Recursively search the WDA element tree for elements matching the query.
-     */
+    async findElement(query) {
+        try {
+            const sessionId = await this.ensureSession();
+            const sourceRes = await this.wdaFetch(`/session/${sessionId}/source?format=json`);
+            if (!sourceRes.ok) {
+                return {
+                    success: false,
+                    error: `Failed to get element tree: ${sourceRes.status}`,
+                };
+            }
+            const sourceData = (await sourceRes.json());
+            const matches = this.searchElements(sourceData.value, query);
+            if (matches.length === 0) {
+                return { success: false, matchCount: 0 };
+            }
+            const index = query.index ?? 0;
+            if (index >= matches.length) {
+                return { success: false, matchCount: matches.length };
+            }
+            return { success: true, element: matches[index], matchCount: matches.length };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : "Unknown error during findElement",
+            };
+        }
+    }
+    async swipe(opts) {
+        try {
+            const sessionId = await this.ensureSession();
+            const windowSize = await this.getWindowSize();
+            const ratio = await this.getPixelRatio();
+            const fromScreenshot = (opts.coordinateSource ?? "device") === "screenshot";
+            let fromX = opts.from?.x ?? windowSize.width / 2;
+            let fromY = opts.from?.y ?? windowSize.height / 2;
+            if (fromScreenshot) {
+                fromX = fromX / ratio;
+                fromY = fromY / ratio;
+            }
+            const axis = opts.direction === "up" || opts.direction === "down"
+                ? windowSize.height
+                : windowSize.width;
+            const distance = opts.distancePx ?? Math.floor(axis * 0.6);
+            let toX = fromX;
+            let toY = fromY;
+            switch (opts.direction) {
+                case "up":
+                    toY = fromY - distance;
+                    break;
+                case "down":
+                    toY = fromY + distance;
+                    break;
+                case "left":
+                    toX = fromX - distance;
+                    break;
+                case "right":
+                    toX = fromX + distance;
+                    break;
+            }
+            toX = Math.max(0, Math.min(windowSize.width - 1, toX));
+            toY = Math.max(0, Math.min(windowSize.height - 1, toY));
+            fromX = Math.max(0, Math.min(windowSize.width - 1, fromX));
+            fromY = Math.max(0, Math.min(windowSize.height - 1, fromY));
+            const durationMs = opts.durationMs ?? 300;
+            const res = await this.wdaFetch(`/session/${sessionId}/wda/dragfromtoforduration`, {
+                method: "POST",
+                body: JSON.stringify({
+                    fromX,
+                    fromY,
+                    toX,
+                    toY,
+                    duration: durationMs / 1000,
+                }),
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => "unknown");
+                return {
+                    success: false,
+                    from: { x: fromX, y: fromY },
+                    to: { x: toX, y: toY },
+                    durationMs,
+                    error: `WDA swipe failed: ${res.status} ${text}`,
+                };
+            }
+            return {
+                success: true,
+                from: { x: fromX, y: fromY },
+                to: { x: toX, y: toY },
+                durationMs,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                from: { x: 0, y: 0 },
+                to: { x: 0, y: 0 },
+                durationMs: opts.durationMs ?? 300,
+                error: err instanceof Error ? err.message : "Unknown error during swipe",
+            };
+        }
+    }
+    async scrollToElement(query, opts = {}) {
+        const maxSwipes = opts.maxSwipes ?? 10;
+        const direction = opts.direction ?? "up";
+        for (let i = 0; i <= maxSwipes; i++) {
+            const found = await this.findElement(query);
+            if (found.success && found.element?.rect) {
+                return {
+                    success: true,
+                    swipes: i,
+                    element: {
+                        type: found.element.type ?? "unknown",
+                        label: found.element.label ?? found.element.name ?? "",
+                        bounds: found.element.rect,
+                    },
+                };
+            }
+            if (i === maxSwipes)
+                break;
+            const swipeRes = await this.swipe({
+                direction,
+                distancePx: opts.distancePx,
+            });
+            if (!swipeRes.success) {
+                return {
+                    success: false,
+                    swipes: i,
+                    error: swipeRes.error ?? "Swipe failed during scrollToElement",
+                };
+            }
+        }
+        return {
+            success: false,
+            swipes: maxSwipes,
+            error: `Element not found after ${maxSwipes} swipes: ${JSON.stringify(query)}`,
+        };
+    }
+    async longPress(x, y, durationMs = 1000, fromScreenshot = false) {
+        try {
+            const sessionId = await this.ensureSession();
+            let pressX = x;
+            let pressY = y;
+            if (fromScreenshot) {
+                const ratio = await this.getPixelRatio();
+                pressX = x / ratio;
+                pressY = y / ratio;
+            }
+            const res = await this.wdaFetch(`/session/${sessionId}/wda/touchAndHold`, {
+                method: "POST",
+                body: JSON.stringify({
+                    x: pressX,
+                    y: pressY,
+                    duration: durationMs / 1000,
+                }),
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => "unknown");
+                return {
+                    success: false,
+                    error: `WDA touchAndHold failed: ${res.status} ${text}`,
+                };
+            }
+            return { success: true, details: { x: pressX, y: pressY, durationMs } };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : "Unknown error during longPress",
+            };
+        }
+    }
+    async longPressElement(query, durationMs = 1000) {
+        const found = await this.findElement(query);
+        if (!found.success || !found.element?.rect) {
+            return {
+                success: false,
+                error: found.error ?? `No element found matching ${JSON.stringify(query)}`,
+            };
+        }
+        const rect = found.element.rect;
+        const centerX = rect.x + rect.width / 2;
+        const centerY = rect.y + rect.height / 2;
+        const res = await this.longPress(centerX, centerY, durationMs, false);
+        return {
+            ...res,
+            element: {
+                type: found.element.type ?? "unknown",
+                label: found.element.label ?? found.element.name ?? "",
+                bounds: rect,
+            },
+        };
+    }
+    async type(text, opts = {}) {
+        try {
+            const sessionId = await this.ensureSession();
+            const chars = Array.from(text);
+            const res = await this.wdaFetch(`/session/${sessionId}/wda/keys`, {
+                method: "POST",
+                body: JSON.stringify({ value: chars }),
+            });
+            if (!res.ok) {
+                const t = await res.text().catch(() => "unknown");
+                return {
+                    success: false,
+                    error: `WDA keys failed: ${res.status} ${t}`,
+                };
+            }
+            if (opts.hideKeyboardAfter) {
+                await this.wdaFetch(`/session/${sessionId}/wda/keys`, {
+                    method: "POST",
+                    body: JSON.stringify({ value: ["\n"] }),
+                }).catch(() => undefined);
+            }
+            return { success: true };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : "Unknown error during type",
+            };
+        }
+    }
+    async clearText(query) {
+        try {
+            const found = await this.findElement(query);
+            if (!found.success || !found.element?.rect) {
+                return {
+                    success: false,
+                    error: found.error ?? `No element found matching ${JSON.stringify(query)}`,
+                };
+            }
+            const rect = found.element.rect;
+            const currentValue = String(found.element.value ?? "");
+            const tapRes = await this.tap(rect.x + rect.width / 2, rect.y + rect.height / 2, false);
+            if (!tapRes.success) {
+                return {
+                    success: false,
+                    error: tapRes.error ?? "Failed to focus element before clearing",
+                };
+            }
+            const backspaces = new Array(Math.max(1, currentValue.length)).fill("\uE003");
+            const sessionId = await this.ensureSession();
+            const res = await this.wdaFetch(`/session/${sessionId}/wda/keys`, {
+                method: "POST",
+                body: JSON.stringify({ value: backspaces }),
+            });
+            if (!res.ok) {
+                const t = await res.text().catch(() => "unknown");
+                return {
+                    success: false,
+                    error: `WDA keys (backspace) failed: ${res.status} ${t}`,
+                };
+            }
+            return { success: true, details: { cleared: currentValue.length } };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : "Unknown error during clearText",
+            };
+        }
+    }
+    async pressKey(key) {
+        try {
+            const sessionId = await this.ensureSession();
+            if (key === "lock") {
+                const res = await this.wdaFetch(`/session/${sessionId}/wda/lock`, {
+                    method: "POST",
+                    body: JSON.stringify({}),
+                });
+                if (!res.ok) {
+                    const t = await res.text().catch(() => "unknown");
+                    return { success: false, error: `WDA lock failed: ${res.status} ${t}` };
+                }
+                return { success: true };
+            }
+            const name = key === "home" ? "home" : key === "volumeUp" ? "volumeup" : "volumedown";
+            const res = await this.wdaFetch(`/session/${sessionId}/wda/pressButton`, {
+                method: "POST",
+                body: JSON.stringify({ name }),
+            });
+            if (!res.ok) {
+                const t = await res.text().catch(() => "unknown");
+                return {
+                    success: false,
+                    error: `WDA pressButton failed: ${res.status} ${t}`,
+                };
+            }
+            return { success: true };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : "Unknown error during pressKey",
+            };
+        }
+    }
+    async unlock() {
+        try {
+            const sessionId = await this.ensureSession();
+            const res = await this.wdaFetch(`/session/${sessionId}/wda/unlock`, {
+                method: "POST",
+                body: JSON.stringify({}),
+            });
+            if (!res.ok) {
+                const t = await res.text().catch(() => "unknown");
+                return { success: false, error: `WDA unlock failed: ${res.status} ${t}` };
+            }
+            return { success: true };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : "Unknown error during unlock",
+            };
+        }
+    }
+    async isLocked() {
+        try {
+            const sessionId = await this.ensureSession();
+            const res = await this.wdaFetch(`/session/${sessionId}/wda/locked`);
+            if (!res.ok)
+                return null;
+            const data = (await res.json());
+            return typeof data.value === "boolean" ? data.value : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async screenshot() {
+        try {
+            const sessionId = await this.ensureSession();
+            const res = await this.wdaFetch(`/session/${sessionId}/screenshot`);
+            if (!res.ok) {
+                const t = await res.text().catch(() => "unknown");
+                return { success: false, error: `WDA screenshot failed: ${res.status} ${t}` };
+            }
+            const data = (await res.json());
+            return { success: true, base64: data.value };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : "Unknown error during screenshot",
+            };
+        }
+    }
+    async getSource() {
+        try {
+            const sessionId = await this.ensureSession();
+            const res = await this.wdaFetch(`/session/${sessionId}/source?format=json`);
+            if (!res.ok) {
+                const t = await res.text().catch(() => "unknown");
+                return {
+                    success: false,
+                    error: `WDA source failed: ${res.status} ${t}`,
+                };
+            }
+            const data = (await res.json());
+            return { success: true, source: data.value };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : "Unknown error during getSource",
+            };
+        }
+    }
+    async waitFor(query, opts = {}) {
+        const timeoutMs = opts.timeoutMs ?? 5000;
+        const pollIntervalMs = opts.pollIntervalMs ?? 500;
+        const disappear = opts.disappear ?? false;
+        const start = Date.now();
+        while (Date.now() - start < timeoutMs) {
+            const found = await this.findElement(query);
+            const matched = found.success && !!found.element;
+            if (!disappear && matched) {
+                const rect = found.element.rect;
+                return {
+                    success: true,
+                    found: true,
+                    elapsedMs: Date.now() - start,
+                    element: rect
+                        ? {
+                            type: found.element.type ?? "unknown",
+                            label: found.element.label ?? found.element.name ?? "",
+                            bounds: rect,
+                        }
+                        : undefined,
+                };
+            }
+            if (disappear && !matched) {
+                return {
+                    success: true,
+                    found: false,
+                    elapsedMs: Date.now() - start,
+                };
+            }
+            await new Promise((r) => setTimeout(r, pollIntervalMs));
+        }
+        return {
+            success: false,
+            found: !disappear,
+            elapsedMs: Date.now() - start,
+            error: disappear
+                ? `Element still visible after ${timeoutMs}ms: ${JSON.stringify(query)}`
+                : `Element not visible after ${timeoutMs}ms: ${JSON.stringify(query)}`,
+        };
+    }
+    async assertVisible(query) {
+        const found = await this.findElement(query);
+        if (found.error) {
+            return { success: false, visible: false, error: found.error };
+        }
+        if (found.success && found.element?.rect) {
+            return {
+                success: true,
+                visible: true,
+                element: {
+                    type: found.element.type ?? "unknown",
+                    label: found.element.label ?? found.element.name ?? "",
+                    bounds: found.element.rect,
+                },
+            };
+        }
+        return { success: true, visible: false };
+    }
+    async assertNotVisible(query) {
+        const found = await this.findElement(query);
+        if (found.error) {
+            return { success: false, visible: false, error: found.error };
+        }
+        const visible = found.success && !!found.element;
+        return { success: true, visible };
+    }
+    async getOrientation() {
+        try {
+            const sessionId = await this.ensureSession();
+            const res = await this.wdaFetch(`/session/${sessionId}/orientation`);
+            if (!res.ok)
+                return null;
+            const data = (await res.json());
+            return data.value ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async setOrientation(orientation) {
+        try {
+            const sessionId = await this.ensureSession();
+            const res = await this.wdaFetch(`/session/${sessionId}/orientation`, {
+                method: "POST",
+                body: JSON.stringify({
+                    orientation: orientation.toUpperCase(),
+                }),
+            });
+            if (!res.ok) {
+                const t = await res.text().catch(() => "unknown");
+                return {
+                    success: false,
+                    error: `WDA setOrientation failed: ${res.status} ${t}`,
+                };
+            }
+            return { success: true };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error
+                    ? err.message
+                    : "Unknown error during setOrientation",
+            };
+        }
+    }
+    async getActiveAppInfo() {
+        try {
+            const sessionId = await this.ensureSession();
+            const res = await this.wdaFetch(`/session/${sessionId}/wda/activeAppInfo`);
+            if (!res.ok) {
+                const t = await res.text().catch(() => "unknown");
+                return {
+                    success: false,
+                    error: `WDA activeAppInfo failed: ${res.status} ${t}`,
+                };
+            }
+            const data = (await res.json());
+            return {
+                success: true,
+                bundleId: data.value?.bundleId,
+                pid: data.value?.pid,
+                name: data.value?.name,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error
+                    ? err.message
+                    : "Unknown error during getActiveAppInfo",
+            };
+        }
+    }
+    async activateApp(bundleId) {
+        try {
+            const sessionId = await this.ensureSession();
+            const res = await this.wdaFetch(`/session/${sessionId}/wda/apps/launch`, {
+                method: "POST",
+                body: JSON.stringify({ bundleId }),
+            });
+            if (!res.ok) {
+                const t = await res.text().catch(() => "unknown");
+                return {
+                    success: false,
+                    error: `WDA apps/launch failed: ${res.status} ${t}`,
+                };
+            }
+            return { success: true };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error
+                    ? err.message
+                    : "Unknown error during activateApp",
+            };
+        }
+    }
+    async openUrl(url) {
+        try {
+            const sessionId = await this.ensureSession();
+            const res = await this.wdaFetch(`/session/${sessionId}/url`, {
+                method: "POST",
+                body: JSON.stringify({ url }),
+            });
+            if (!res.ok) {
+                const t = await res.text().catch(() => "unknown");
+                return {
+                    success: false,
+                    error: `WDA openUrl failed: ${res.status} ${t}`,
+                };
+            }
+            return { success: true };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : "Unknown error during openUrl",
+            };
+        }
+    }
+    async terminateAppViaWDA(bundleId) {
+        try {
+            const sessionId = await this.ensureSession();
+            const res = await this.wdaFetch(`/session/${sessionId}/wda/apps/terminate`, {
+                method: "POST",
+                body: JSON.stringify({ bundleId }),
+            });
+            if (!res.ok) {
+                const t = await res.text().catch(() => "unknown");
+                return {
+                    success: false,
+                    error: `WDA apps/terminate failed: ${res.status} ${t}`,
+                };
+            }
+            return { success: true };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error
+                    ? err.message
+                    : "Unknown error during terminateAppViaWDA",
+            };
+        }
+    }
+    async pingStatus() {
+        try {
+            const res = await this.wdaFetch("/status", {}, 2000);
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
+    }
     searchElements(element, query) {
         const results = [];
         if (this.elementMatches(element, query)) {
@@ -290,9 +874,6 @@ export class ScreenManager {
         }
         return results;
     }
-    /**
-     * Check whether a single element matches the given query.
-     */
     elementMatches(element, query) {
         if (query.text !== undefined) {
             const searchText = query.text.toLowerCase();
@@ -317,14 +898,10 @@ export class ScreenManager {
                 return false;
             }
         }
-        // At least one query field must be specified
         return (query.text !== undefined ||
             query.accessibilityLabel !== undefined ||
             query.type !== undefined);
     }
-    /**
-     * Collect a summary of visible elements for debugging (when no match found).
-     */
     collectVisibleElements(element, limit) {
         const results = [];
         if (limit <= 0)
@@ -332,7 +909,6 @@ export class ScreenManager {
         const label = String(element.label ?? element.name ?? "");
         const text = String(element.value ?? "");
         const type = String(element.type ?? "");
-        // Only include elements that have some identifying info
         if (label || text) {
             results.push({ type, label, text });
         }
@@ -347,11 +923,9 @@ export class ScreenManager {
         }
         return results;
     }
-    /**
-     * Invalidate cached session and pixel ratio (e.g., after app restart).
-     */
     reset() {
         this.sessionId = null;
         this.pixelRatio = null;
+        this.sessionBaseUrl = null;
     }
 }