@ishlabs/cli 0.24.1 → 0.25.0

package/dist/lib/local-sim/apk-manifest.js

@@ -0,0 +1,210 @@
+/**
+ * Extract an APK's package name from its binary AndroidManifest.xml — pure,
+ * dependency-free (no aapt, no SDK), so `--app <apk>` resolves the package even
+ * when the apk is ALREADY installed (the install-list diff is empty then).
+ *
+ * Two steps, both on in-memory bytes:
+ *  1. Pull AndroidManifest.xml out of the APK (a ZIP) — find its local file
+ *     header and inflate (raw deflate) or copy (stored).
+ *  2. Parse the binary XML (AXML): read the string pool, find the <manifest>
+ *     START_ELEMENT, and read its `package` attribute's string value.
+ *
+ * We only need the package string, so this is a deliberately minimal AXML
+ * reader (not a general decoder). Returns null on anything unexpected — the
+ * caller falls back to other resolution and never crashes on a weird apk.
+ */
+import { inflateRawSync } from "node:zlib";
+import { readFile } from "node:fs/promises";
+// --- ZIP: pull AndroidManifest.xml bytes ---
+const SIG_EOCD = 0x06054b50; // End Of Central Directory "PK\x05\x06"
+const SIG_CENTRAL = 0x02014b50; // Central directory file header "PK\x01\x02"
+const MANIFEST_NAME = "AndroidManifest.xml";
+const LOCAL_HEADER_FIXED = 30; // bytes before the local header's name field
+/**
+ * Extract AndroidManifest.xml via the CENTRAL DIRECTORY (not local headers).
+ * Modern APKs (v2-signed / zipaligned) flag the manifest entry with a data
+ * descriptor, so its local-header compressed size is 0 — only the central
+ * directory carries the real size. We find the EOCD, walk the central
+ * directory for the manifest entry, then read its data from the local header.
+ */
+function extractManifestBytes(apk) {
+    // EOCD is near the end; scan backward over the (≤64KB) comment for its sig.
+    let eocd = -1;
+    const minEocd = Math.max(0, apk.length - 22 - 0xffff);
+    for (let i = apk.length - 22; i >= minEocd; i--) {
+        if (apk.readUInt32LE(i) === SIG_EOCD) {
+            eocd = i;
+            break;
+        }
+    }
+    if (eocd < 0)
+        return null;
+    const centralCount = apk.readUInt16LE(eocd + 10);
+    const centralOffset = apk.readUInt32LE(eocd + 16);
+    let p = centralOffset;
+    for (let n = 0; n < centralCount; n++) {
+        if (p + 46 > apk.length || apk.readUInt32LE(p) !== SIG_CENTRAL)
+            break;
+        const method = apk.readUInt16LE(p + 10);
+        const compSize = apk.readUInt32LE(p + 20);
+        const nameLen = apk.readUInt16LE(p + 28);
+        const extraLen = apk.readUInt16LE(p + 30);
+        const commentLen = apk.readUInt16LE(p + 32);
+        const localOffset = apk.readUInt32LE(p + 42);
+        const name = apk.toString("utf8", p + 46, p + 46 + nameLen);
+        if (name === MANIFEST_NAME) {
+            // Read the data from the LOCAL header (its name/extra lengths may differ
+            // from the central record, so re-read them at localOffset).
+            const lNameLen = apk.readUInt16LE(localOffset + 26);
+            const lExtraLen = apk.readUInt16LE(localOffset + 28);
+            const dataStart = localOffset + LOCAL_HEADER_FIXED + lNameLen + lExtraLen;
+            const data = apk.subarray(dataStart, dataStart + compSize);
+            try {
+                if (method === 0)
+                    return Buffer.from(data); // stored
+                if (method === 8)
+                    return inflateRawSync(data); // deflate
+            }
+            catch {
+                return null;
+            }
+            return null;
+        }
+        p += 46 + nameLen + extraLen + commentLen;
+    }
+    return null;
+}
+// --- AXML: read the string pool + find <manifest package="..."> ---
+const RES_STRING_POOL_TYPE = 0x0001;
+const RES_XML_START_ELEMENT_TYPE = 0x0102;
+const UTF8_FLAG = 1 << 8;
+/** Parse the AXML string pool chunk at `poolOffset`; returns a lazy accessor. */
+function parseStringPool(buf, poolOffset) {
+    // chunk: type(2) headerSize(2) chunkSize(4) stringCount(4) styleCount(4)
+    //        flags(4) stringsStart(4) stylesStart(4) then stringCount offsets.
+    const type = buf.readUInt16LE(poolOffset);
+    if (type !== RES_STRING_POOL_TYPE)
+        return null;
+    const stringCount = buf.readUInt32LE(poolOffset + 8);
+    const flags = buf.readUInt32LE(poolOffset + 16);
+    const stringsStart = buf.readUInt32LE(poolOffset + 20);
+    const isUtf8 = (flags & UTF8_FLAG) !== 0;
+    const offsetsStart = poolOffset + 28;
+    const stringDataBase = poolOffset + stringsStart;
+    const cache = new Map();
+    return {
+        get(index) {
+            if (index < 0 || index >= stringCount)
+                return null;
+            if (cache.has(index))
+                return cache.get(index);
+            const strOff = stringDataBase + buf.readUInt32LE(offsetsStart + index * 4);
+            let value;
+            if (isUtf8) {
+                // UTF-8: [u16-ish charLen][u16-ish byteLen] then bytes. Lengths use a
+                // high-bit continuation; we only need the byte length to slice.
+                let p = strOff;
+                // skip the char count (1 or 2 bytes)
+                if (buf[p] & 0x80)
+                    p += 2;
+                else
+                    p += 1;
+                let byteLen = buf[p];
+                if (byteLen & 0x80) {
+                    byteLen = ((byteLen & 0x7f) << 8) | buf[p + 1];
+                    p += 2;
+                }
+                else {
+                    p += 1;
+                }
+                value = buf.toString("utf8", p, p + byteLen);
+            }
+            else {
+                // UTF-16LE: [u16 charLen (high-bit continuation)] then 2*len bytes.
+                let p = strOff;
+                let charLen = buf.readUInt16LE(p);
+                p += 2;
+                if (charLen & 0x8000) {
+                    charLen = ((charLen & 0x7fff) << 16) | buf.readUInt16LE(p);
+                    p += 2;
+                }
+                value = buf.toString("utf16le", p, p + charLen * 2);
+            }
+            cache.set(index, value);
+            return value;
+        },
+    };
+}
+/**
+ * Parse binary AXML and return the <manifest> element's `package` attribute.
+ * Returns null if the structure isn't what we expect.
+ */
+export function parseAxmlPackage(axml) {
+    if (axml.length < 8)
+        return null;
+    // file header: type(2) headerSize(2) fileSize(4). String pool follows at 8.
+    const pool = parseStringPool(axml, 8);
+    if (!pool)
+        return null;
+    // Walk chunks from the start of the file, find the first START_ELEMENT named
+    // "manifest", then read its attributes for "package".
+    let off = 8;
+    // Advance past the string pool using its chunkSize.
+    const poolChunkSize = axml.readUInt32LE(8 + 4);
+    off = 8 + poolChunkSize;
+    while (off + 8 <= axml.length) {
+        const type = axml.readUInt16LE(off);
+        const headerSize = axml.readUInt16LE(off + 2);
+        const chunkSize = axml.readUInt32LE(off + 4);
+        if (chunkSize < 8 || off + chunkSize > axml.length)
+            break;
+        if (type === RES_XML_START_ELEMENT_TYPE) {
+            // START_ELEMENT body (after the standard node header lineNo/comment):
+            //   ns(4) name(4) attrStart(2) attrSize(2) attrCount(2) ... then attrs.
+            // The chunk header is `headerSize` bytes; the element fields start there.
+            const base = off + headerSize;
+            const nameIdx = axml.readInt32LE(base + 4);
+            const elementName = nameIdx >= 0 ? pool.get(nameIdx) : null;
+            if (elementName === "manifest") {
+                const attrStart = axml.readUInt16LE(base + 8);
+                const attrSize = axml.readUInt16LE(base + 10);
+                const attrCount = axml.readUInt16LE(base + 12);
+                const attrsBase = base + attrStart;
+                for (let i = 0; i < attrCount; i++) {
+                    const a = attrsBase + i * attrSize;
+                    // attr: ns(4) name(4) rawValue(4) typedValue{size(2) res0(1) type(1) data(4)}
+                    const attrNameIdx = axml.readInt32LE(a + 4);
+                    const attrName = attrNameIdx >= 0 ? pool.get(attrNameIdx) : null;
+                    if (attrName === "package") {
+                        const rawValueIdx = axml.readInt32LE(a + 8);
+                        if (rawValueIdx >= 0) {
+                            const pkg = pool.get(rawValueIdx);
+                            if (pkg)
+                                return pkg;
+                        }
+                        // Fallback: the typed value's data is a string-pool index too.
+                        const dataIdx = axml.readInt32LE(a + 16);
+                        return dataIdx >= 0 ? pool.get(dataIdx) : null;
+                    }
+                }
+                return null; // manifest found but no package attr
+            }
+        }
+        off += chunkSize;
+    }
+    return null;
+}
+/** Read an APK file and return its package name, or null if it can't be parsed. */
+export async function packageNameFromApk(apkPath) {
+    let apk;
+    try {
+        apk = await readFile(apkPath);
+    }
+    catch {
+        return null;
+    }
+    const manifest = extractManifestBytes(apk);
+    if (!manifest)
+        return null;
+    return parseAxmlPackage(manifest);
+}

package/dist/lib/local-sim/browser.d.ts

@@ -58,5 +58,27 @@ export declare function resolveNodeToBoundingBox(page: Page, nodeId: string, tre
 export declare function resolveNodeToXPath(page: Page, nodeId: string, treeData: TreeData): Promise<string | null>;
 export declare function takeScreenshot(page: Page): Promise<string>;
 export declare function takeScreenshotJpeg(page: Page, quality?: number): Promise<Buffer>;
+export declare const FULL_PAGE_HEIGHT_CAP_PX_MOBILE = 12000;
+export declare const FULL_PAGE_HEIGHT_CAP_PX_DESKTOP = 16000;
+export interface FullPageJpegResult {
+    base64: string;
+    clipped: boolean;
+}
+/**
+ * Capture a height-capped full-page JPEG, mirroring the hosted backend's
+ * ``take_full_page_with_navbar`` (screenshots.py). Used as the PDQ basis and
+ * stored as the Frame's representative_screenshot.
+ *
+ * Scroll preservation: Playwright's ``page.screenshot({ fullPage: true })``
+ * resets ``window.scrollY`` to 0 on long pages, and the agent is mid-task —
+ * we must not disturb its scroll position. We save scrollY first, capture,
+ * then restore it if it changed (mirrors _safe_scroll_y / _restore_scroll_y
+ * in screenshots.py). Both the save and restore guard against throwing.
+ */
+export declare function takeFullPageJpeg(page: Page, opts: {
+    documentHeight: number;
+    cap: number;
+    viewportWidth: number;
+}, quality?: number): Promise<FullPageJpegResult>;
 export declare function navigateWithRetry(page: Page, url: string, maxRetries?: number): Promise<void>;
 export declare function closeBrowser(session: BrowserSession): Promise<void>;

package/dist/lib/local-sim/browser.js

@@ -304,6 +304,71 @@ export async function takeScreenshot(page) {
 export async function takeScreenshotJpeg(page, quality = 85) {
     return page.screenshot({ type: "jpeg", quality });
 }
+// Height caps (CSS px) for full-page capture, mirroring the hosted backend
+// constants in app/interactive/computers/browser/screenshots.py
+// (FULL_PAGE_HEIGHT_CAP_PX_MOBILE / _DESKTOP). Compared against
+// document.documentElement.scrollHeight exactly like the hosted ``exceeds_cap``
+// branch — clipping at capture time avoids OOMing the renderer on very tall
+// pages.
+export const FULL_PAGE_HEIGHT_CAP_PX_MOBILE = 12_000;
+export const FULL_PAGE_HEIGHT_CAP_PX_DESKTOP = 16_000;
+/**
+ * Capture a height-capped full-page JPEG, mirroring the hosted backend's
+ * ``take_full_page_with_navbar`` (screenshots.py). Used as the PDQ basis and
+ * stored as the Frame's representative_screenshot.
+ *
+ * Scroll preservation: Playwright's ``page.screenshot({ fullPage: true })``
+ * resets ``window.scrollY`` to 0 on long pages, and the agent is mid-task —
+ * we must not disturb its scroll position. We save scrollY first, capture,
+ * then restore it if it changed (mirrors _safe_scroll_y / _restore_scroll_y
+ * in screenshots.py). Both the save and restore guard against throwing.
+ */
+export async function takeFullPageJpeg(page, opts, quality = 85) {
+    // Save scrollY (guard against throw — a failed read means "don't restore").
+    let savedY = null;
+    try {
+        savedY = Math.round(await page.evaluate(() => window.scrollY));
+    }
+    catch {
+        savedY = null;
+    }
+    try {
+        const exceedsCap = opts.documentHeight > opts.cap;
+        let buffer;
+        let clipped = false;
+        if (exceedsCap) {
+            // ``fullPage: true`` makes Playwright's CDP call set
+            // ``captureBeyondViewport`` so the clip can extend past the current
+            // viewport (same as the hosted Python cap-clip branch). Without it the
+            // clip would be intersected with the visible viewport.
+            buffer = await page.screenshot({
+                fullPage: true,
+                type: "jpeg",
+                quality,
+                clip: { x: 0, y: 0, width: opts.viewportWidth, height: opts.cap },
+            });
+            clipped = true;
+        }
+        else {
+            buffer = await page.screenshot({ fullPage: true, type: "jpeg", quality });
+        }
+        return { base64: buffer.toString("base64"), clipped };
+    }
+    finally {
+        // Restore scrollY if Playwright reset it. Never throw out of the restore.
+        if (savedY !== null) {
+            try {
+                const currentY = Math.round(await page.evaluate(() => window.scrollY));
+                if (currentY !== savedY) {
+                    await page.evaluate((y) => window.scrollTo(0, y), savedY);
+                }
+            }
+            catch {
+                // Best-effort restore; a failure here must not unwind the capture.
+            }
+        }
+    }
+}
 export async function navigateWithRetry(page, url, maxRetries = 3) {
     for (let attempt = 1; attempt <= maxRetries; attempt++) {
         try {

package/dist/lib/local-sim/coordinates.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Pure coordinate math for the native (vision) device path.
+ *
+ * The backend's vision locator returns NORMALIZED 0-1000 coordinates. A native
+ * device de-normalizes them against a concrete dimension (screencap pixels for
+ * Android; idb POINTS for the iOS tap, screenshot PIXELS for the iOS record),
+ * and the loop later re-normalizes the recorded coordinate back to 0-1000.
+ *
+ * Pure and side-effect-free so the round-trip can be unit-tested without a
+ * device (FCIS — the I/O lives in adb.ts/simctl.ts, the math lives here).
+ *
+ * ROUND-TRIP IDENTITY: deNormalize→reNormalize is an identity only when the
+ * target dimension is >= the normalized scale (1000). When the dim is finer
+ * (pixels, e.g. 1080/1179 > 1000) the recorded coord round-trips exactly; when
+ * it's coarser (iOS points 393 < 1000) double-rounding can drift by 1 unit —
+ * which is why iOS records in PIXELS and only TAPS in points.
+ */
+export declare const NORMALIZED_SCALE = 1000;
+/** Normalized 0-1000 → a concrete dimension (pixels or points). */
+export declare function deNormalize(n: number, dim: number): number;
+/** A concrete coordinate (pixels or points) → normalized 0-1000 (what the loop records). */
+export declare function reNormalize(coord: number, dim: number): number;
+/** De-normalize a {x,y} against per-axis dimensions. */
+export declare function deNormalizePoint(c: {
+    x: number;
+    y: number;
+}, width: number, height: number): {
+    x: number;
+    y: number;
+};
+/**
+ * De-normalize a drag's start AND end points (each normalized 0-1000) against
+ * one device dimension into the {start,end} pixel/point pair the drivers feed to
+ * a slow swipe. The drag path is a from→to gesture, so BOTH ends de-normalize
+ * against the SAME basis (Android: screencap pixels; iOS: idb POINTS). Pure so
+ * the two-ended de-normalization is unit-testable without a device.
+ */
+export declare function deNormalizeDrag(drag: {
+    startX: number;
+    startY: number;
+    endX: number;
+    endY: number;
+}, width: number, height: number): {
+    start: {
+        x: number;
+        y: number;
+    };
+    end: {
+        x: number;
+        y: number;
+    };
+};
+/**
+ * Scale an iOS POINT coordinate into the PIXEL space, used by the element path:
+ * `idb` reports a11y frames (and so the tappable bounds-center) in POINTS, but
+ * the loop records — and re-normalizes against `dimensions()` — in PIXELS. So
+ * the element path taps the point-center directly (idb consumes points) yet must
+ * RECORD a pixel-center; this converts the one to the other per-axis by the
+ * point→pixel ratio (the @Nx scale). Pure so the conversion is unit-testable
+ * without a simulator. Android needs no analog: its screencap and tap share one
+ * pixel space, so the bounds-center is already a pixel center.
+ */
+export declare function pointToPixel(c: {
+    x: number;
+    y: number;
+}, pointWidth: number, pointHeight: number, pixelWidth: number, pixelHeight: number): {
+    x: number;
+    y: number;
+};

package/dist/lib/local-sim/coordinates.js

@@ -0,0 +1,59 @@
+/**
+ * Pure coordinate math for the native (vision) device path.
+ *
+ * The backend's vision locator returns NORMALIZED 0-1000 coordinates. A native
+ * device de-normalizes them against a concrete dimension (screencap pixels for
+ * Android; idb POINTS for the iOS tap, screenshot PIXELS for the iOS record),
+ * and the loop later re-normalizes the recorded coordinate back to 0-1000.
+ *
+ * Pure and side-effect-free so the round-trip can be unit-tested without a
+ * device (FCIS — the I/O lives in adb.ts/simctl.ts, the math lives here).
+ *
+ * ROUND-TRIP IDENTITY: deNormalize→reNormalize is an identity only when the
+ * target dimension is >= the normalized scale (1000). When the dim is finer
+ * (pixels, e.g. 1080/1179 > 1000) the recorded coord round-trips exactly; when
+ * it's coarser (iOS points 393 < 1000) double-rounding can drift by 1 unit —
+ * which is why iOS records in PIXELS and only TAPS in points.
+ */
+export const NORMALIZED_SCALE = 1000;
+/** Normalized 0-1000 → a concrete dimension (pixels or points). */
+export function deNormalize(n, dim) {
+    return Math.round((n / NORMALIZED_SCALE) * dim);
+}
+/** A concrete coordinate (pixels or points) → normalized 0-1000 (what the loop records). */
+export function reNormalize(coord, dim) {
+    return Math.round((coord / dim) * NORMALIZED_SCALE);
+}
+/** De-normalize a {x,y} against per-axis dimensions. */
+export function deNormalizePoint(c, width, height) {
+    return { x: deNormalize(c.x, width), y: deNormalize(c.y, height) };
+}
+/**
+ * De-normalize a drag's start AND end points (each normalized 0-1000) against
+ * one device dimension into the {start,end} pixel/point pair the drivers feed to
+ * a slow swipe. The drag path is a from→to gesture, so BOTH ends de-normalize
+ * against the SAME basis (Android: screencap pixels; iOS: idb POINTS). Pure so
+ * the two-ended de-normalization is unit-testable without a device.
+ */
+export function deNormalizeDrag(drag, width, height) {
+    return {
+        start: deNormalizePoint({ x: drag.startX, y: drag.startY }, width, height),
+        end: deNormalizePoint({ x: drag.endX, y: drag.endY }, width, height),
+    };
+}
+/**
+ * Scale an iOS POINT coordinate into the PIXEL space, used by the element path:
+ * `idb` reports a11y frames (and so the tappable bounds-center) in POINTS, but
+ * the loop records — and re-normalizes against `dimensions()` — in PIXELS. So
+ * the element path taps the point-center directly (idb consumes points) yet must
+ * RECORD a pixel-center; this converts the one to the other per-axis by the
+ * point→pixel ratio (the @Nx scale). Pure so the conversion is unit-testable
+ * without a simulator. Android needs no analog: its screencap and tap share one
+ * pixel space, so the bounds-center is already a pixel center.
+ */
+export function pointToPixel(c, pointWidth, pointHeight, pixelWidth, pixelHeight) {
+    return {
+        x: Math.round((c.x / pointWidth) * pixelWidth),
+        y: Math.round((c.y / pointHeight) * pixelHeight),
+    };
+}

package/dist/lib/local-sim/device.d.ts

@@ -0,0 +1,143 @@
+/**
+ * SimulationDevice — the target a local simulation drives.
+ *
+ * The observe → reason (remote) → act (local) loop in `loop.ts` used to be
+ * hardwired to a Playwright `Page`. This interface abstracts exactly what the
+ * loop needs from a target so a native Android device (driven by `adb`) can
+ * slot in next to the browser. `BrowserDevice` (below) wraps the existing
+ * Playwright path in `browser.ts`/`actions.ts`/`tabs.ts`; `AndroidDevice`
+ * (added later) implements the same surface via `adb`.
+ *
+ * Multi-tab handling is browser-specific and stays hidden behind the
+ * interface — the loop never touches a `Page` or `TabManager` directly.
+ */
+import type { Browser } from "playwright-core";
+import type { LocalStepAction, LocalSimBrowserOptions, LocalTabInfo, ContextValue } from "./types.js";
+import type { BrowserSession } from "./browser.js";
+/**
+ * One observation of the target's current state.
+ *
+ * `accessibilityTree` is populated by the browser (CDP) and by native targets
+ * (uiautomator / idb describe-all), serialized to the same `[id] role "name"`
+ * format the backend DOMLocator reasons over; it's "" only when a native dump
+ * fails or yields a sparse tree, which makes the backend take its vision branch.
+ * `url` is browser-only ("" for native). `tabs` is browser-only and empty for
+ * native. The node map needed to resolve subsequent actions is kept inside the
+ * device (BrowserDevice.lastTreeData / AndroidDevice.lastNodeMap /
+ * IOSDevice.lastNodeMap), not surfaced here.
+ */
+export interface DeviceObservation {
+    /** base64 PNG of the current screen. */
+    screenshot: string;
+    /** Simplified accessibility tree (browser + native); "" when a native dump degrades to vision. */
+    accessibilityTree: string;
+    /** Current URL (browser); "" for native. */
+    url: string;
+    width: number;
+    height: number;
+    /** Full document height (browser); equals `height` for native screens. */
+    documentHeight: number;
+    /** Open-tab snapshot (browser-only; empty for native). */
+    tabs: LocalTabInfo[];
+}
+/**
+ * Result of executing one action against the target.
+ *
+ * `coordinates` are in the device's own pixel space (browser viewport px or
+ * native screencap px). `openedNewTab` is browser-only and always false for
+ * native.
+ */
+export interface DeviceActionResult {
+    success: boolean;
+    elementName: string | null;
+    coordinates: {
+        x: number;
+        y: number;
+    } | null;
+    openedNewTab: boolean;
+}
+/**
+ * A drivable simulation target. Implementations own their own lifecycle and
+ * (for the browser) tab bookkeeping.
+ */
+export interface SimulationDevice {
+    /**
+     * Launch (or reset to a clean state) and bring the target to `target`:
+     * a URL for the browser, an app id / apk path for native.
+     */
+    launchOrReset(target: string): Promise<void>;
+    /** Capture a full observation of the current screen state. */
+    observe(): Promise<DeviceObservation>;
+    /** base64 PNG — used for cheap no-visible-change detection between steps. */
+    captureScreenshot(): Promise<string>;
+    /** JPEG buffer — used for upload, frame-matching, recording, and debug. */
+    captureScreenshotJpeg(): Promise<Buffer>;
+    /**
+     * Height-capped full-page JPEG (base64) for the backend's PDQ basis +
+     * representative_screenshot. Browser-only: native targets have no scrollable
+     * document, so they omit this and the frame is created from the viewport.
+     */
+    captureFullPageJpeg?(opts: {
+        documentHeight: number;
+        cap: number;
+    }): Promise<string | undefined>;
+    /** Current pixel dimensions of the target (viewport / screencap). */
+    dimensions(): {
+        width: number;
+        height: number;
+    };
+    /** Execute one action and report what happened. */
+    executeAction(action: LocalStepAction): Promise<DeviceActionResult>;
+    /** Current location string for recording (URL for browser; "" for native). */
+    currentUrl(): string;
+    /** Tear down. For shared-browser tabs this closes just the tab. */
+    close(): Promise<void>;
+}
+/**
+ * Browser implementation backed by Playwright. Delegates to the existing
+ * `browser.ts`/`actions.ts`/`tabs.ts` helpers — no logic is rewritten here.
+ *
+ * Owns a `BrowserSession` plus a `TabManager`; the active page can swap when a
+ * popup auto-focuses or the LLM issues switch_tab/close_tab, so every method
+ * re-reads `tabs.activePage()` before acting (matching the previous loop).
+ */
+export declare class BrowserDevice implements SimulationDevice {
+    private readonly session;
+    private readonly tabs;
+    private readonly opts;
+    private readonly contextValues;
+    /** When false this device shares a browser process and only closes its tab. */
+    private readonly ownsBrowser;
+    /** CDP node map from the last observe(), needed to resolve actions. */
+    private lastTreeData;
+    constructor(session: BrowserSession, opts: LocalSimBrowserOptions, contextValues: ContextValue[], ownsBrowser: boolean);
+    launchOrReset(target: string): Promise<void>;
+    observe(): Promise<DeviceObservation>;
+    captureScreenshot(): Promise<string>;
+    captureScreenshotJpeg(): Promise<Buffer>;
+    captureFullPageJpeg(opts: {
+        documentHeight: number;
+        cap: number;
+    }): Promise<string | undefined>;
+    dimensions(): {
+        width: number;
+        height: number;
+    };
+    executeAction(action: LocalStepAction): Promise<DeviceActionResult>;
+    currentUrl(): string;
+    close(): Promise<void>;
+}
+/**
+ * Build the device for a platform. `web`/`browser`/`""` → Playwright
+ * `BrowserDevice`; `android` → `AndroidDevice` (adb); `ios` → `IOSDevice`
+ * (simctl + idb). The native cases are dynamically imported so the browser path
+ * never pulls in the adb/simctl modules.
+ */
+export declare function createDevice(platform: string, opts: {
+    browserOpts: LocalSimBrowserOptions;
+    contextValues: ContextValue[];
+    sharedBrowser?: Browser;
+    /** Native: local .apk/.app path to install or a package/bundle id to launch. */
+    appPath?: string;
+    log?: (msg: string) => void;
+}): Promise<SimulationDevice>;