openuispec 0.2.18 → 0.2.20

package/dist/mcp-server/preview.js

@@ -0,0 +1,233 @@
+/**
+ * preview.ts — Orchestrates spec loading, mock data, and HTML rendering
+ * for the openuispec_preview tool.
+ */
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import YAML from "yaml";
+import { findProjectDir } from "../drift/index.js";
+import { getBrowser } from "./screenshot-shared.js";
+import { renderPage } from "./preview-render.js";
+// ── viewport defaults per size class ────────────────────────────────
+const SIZE_CLASS_VIEWPORTS = {
+    compact: { width: 390, height: 844 },
+    regular: { width: 820, height: 1180 },
+    expanded: { width: 1280, height: 800 },
+};
+// ── spec loading helpers ────────────────────────────────────────────
+function loadManifest(projectDir) {
+    const manifestPath = join(projectDir, "openuispec.yaml");
+    if (!existsSync(manifestPath)) {
+        throw new Error(`Manifest not found at ${manifestPath}`);
+    }
+    return YAML.parse(readFileSync(manifestPath, "utf-8"));
+}
+function loadScreen(projectDir, manifest, screenName) {
+    const screensDir = resolve(projectDir, manifest.includes?.screens ?? "./screens/");
+    // Try exact filename first
+    const candidates = [
+        join(screensDir, `${screenName}.yaml`),
+        join(screensDir, `${screenName}.yml`),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            return YAML.parse(readFileSync(candidate, "utf-8"));
+        }
+    }
+    // Scan all screen files for matching screen name key
+    if (existsSync(screensDir)) {
+        for (const file of readdirSync(screensDir)) {
+            if (!file.endsWith(".yaml") && !file.endsWith(".yml"))
+                continue;
+            const content = YAML.parse(readFileSync(join(screensDir, file), "utf-8"));
+            if (content && typeof content === "object" && screenName in content) {
+                return content;
+            }
+        }
+    }
+    throw new Error(`Screen "${screenName}" not found in ${screensDir}. ` +
+        `Available: ${existsSync(screensDir) ? readdirSync(screensDir).filter(f => f.endsWith(".yaml")).map(f => f.replace(".yaml", "")).join(", ") : "none"}`);
+}
+function loadAllTokens(projectDir, manifest) {
+    const tokensDir = resolve(projectDir, manifest.includes?.tokens ?? "./tokens/");
+    const tokens = {};
+    if (!existsSync(tokensDir))
+        return tokens;
+    for (const file of readdirSync(tokensDir)) {
+        if (!file.endsWith(".yaml") && !file.endsWith(".yml"))
+            continue;
+        const category = file.replace(/\.ya?ml$/, "");
+        try {
+            tokens[category] = YAML.parse(readFileSync(join(tokensDir, file), "utf-8"));
+        }
+        catch {
+            // Skip malformed token files
+        }
+    }
+    return tokens;
+}
+function loadLocale(projectDir, manifest, localeName) {
+    const localesDir = resolve(projectDir, manifest.includes?.locales ?? "./locales/");
+    const candidates = [
+        join(localesDir, `${localeName}.json`),
+        join(localesDir, `${localeName}.yaml`),
+        join(localesDir, `${localeName}.yml`),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            const content = readFileSync(candidate, "utf-8");
+            if (candidate.endsWith(".json")) {
+                return JSON.parse(content);
+            }
+            return YAML.parse(content) ?? {};
+        }
+    }
+    // Fallback to default locale
+    const defaultLocale = manifest.i18n?.default_locale ?? "en";
+    if (localeName !== defaultLocale) {
+        return loadLocale(projectDir, manifest, defaultLocale);
+    }
+    return {};
+}
+function loadContractDefs(projectDir, manifest) {
+    const contractsDir = resolve(projectDir, manifest.includes?.contracts ?? "./contracts/");
+    const defs = {};
+    if (!existsSync(contractsDir))
+        return defs;
+    for (const file of readdirSync(contractsDir)) {
+        if (!file.endsWith(".yaml") && !file.endsWith(".yml"))
+            continue;
+        try {
+            const content = YAML.parse(readFileSync(join(contractsDir, file), "utf-8"));
+            if (content && typeof content === "object") {
+                const name = file.replace(/\.ya?ml$/, "");
+                defs[name] = content;
+            }
+        }
+        catch {
+            // Skip malformed contract files
+        }
+    }
+    return defs;
+}
+function loadComponentDefs(projectDir, manifest) {
+    const componentsDir = resolve(projectDir, manifest.includes?.components ?? "./components/");
+    const defs = {};
+    if (!existsSync(componentsDir))
+        return defs;
+    for (const file of readdirSync(componentsDir)) {
+        if (!file.endsWith(".yaml") && !file.endsWith(".yml"))
+            continue;
+        try {
+            const content = YAML.parse(readFileSync(join(componentsDir, file), "utf-8"));
+            if (content && typeof content === "object") {
+                for (const [name, def] of Object.entries(content)) {
+                    defs[name] = def;
+                }
+            }
+        }
+        catch {
+            // Skip malformed component files
+        }
+    }
+    return defs;
+}
+function loadMockData(projectDir, screenName) {
+    const mockDir = join(projectDir, "mock");
+    const candidates = [
+        join(mockDir, `${screenName}.yaml`),
+        join(mockDir, `${screenName}.yml`),
+        join(mockDir, `${screenName}.json`),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            const content = readFileSync(candidate, "utf-8");
+            let parsed;
+            if (candidate.endsWith(".json")) {
+                parsed = JSON.parse(content);
+            }
+            else {
+                parsed = YAML.parse(content);
+            }
+            return {
+                data: parsed?.data ?? parsed ?? {},
+                params: parsed?.params ?? {},
+            };
+        }
+    }
+    return { data: {}, params: {} };
+}
+// ── main preview function ───────────────────────────────────────────
+export async function renderPreview(projectCwd, options) {
+    const { screen, size_class = "compact", theme = "light", locale: localeName = "en", viewport, include_html = false, } = options;
+    // 1. Find project directory
+    const projectDir = findProjectDir(projectCwd);
+    // 2. Load specs
+    const manifest = loadManifest(projectDir);
+    const screenSpec = loadScreen(projectDir, manifest, screen);
+    const tokens = loadAllTokens(projectDir, manifest);
+    const locale = loadLocale(projectDir, manifest, localeName);
+    // 3. Load contract definitions (project extensions) and component definitions
+    const contractDefs = loadContractDefs(projectDir, manifest);
+    manifest._contractDefs = contractDefs;
+    const componentDefs = loadComponentDefs(projectDir, manifest);
+    manifest._componentDefs = componentDefs;
+    // 4. Load mock data
+    const { data: mockData, params: mockParams } = loadMockData(projectDir, screen);
+    // 5. Build render context
+    const ctx = {
+        manifest,
+        screen: screenSpec,
+        screenName: screen,
+        tokens,
+        locale,
+        mockData,
+        mockParams,
+        sizeClass: size_class,
+        theme,
+    };
+    // 6. Render HTML
+    const html = renderPage(ctx);
+    // 7. Screenshot with Puppeteer
+    const vp = viewport ?? SIZE_CLASS_VIEWPORTS[size_class];
+    const browser = await getBrowser();
+    const page = await browser.newPage();
+    try {
+        await page.setViewport({
+            width: vp.width,
+            height: vp.height,
+            deviceScaleFactor: 2,
+        });
+        if (theme === "dark") {
+            await page.emulateMediaFeatures([
+                { name: "prefers-color-scheme", value: "dark" },
+            ]);
+        }
+        await page.setContent(html, { waitUntil: "load", timeout: 10_000 });
+        // Small delay for CSS to settle
+        await new Promise((r) => setTimeout(r, 200));
+        const buffer = await page.screenshot({ type: "png", fullPage: true });
+        const base64 = buffer.toString("base64");
+        const content = [
+            { type: "image", data: base64, mimeType: "image/png" },
+            {
+                type: "text",
+                text: JSON.stringify({
+                    screen,
+                    size_class,
+                    theme,
+                    locale: localeName,
+                    viewport: vp,
+                    mock_data_loaded: Object.keys(mockData).length > 0,
+                }, null, 2),
+            },
+        ];
+        if (include_html) {
+            content.push({ type: "text", text: html });
+        }
+        return { content };
+    }
+    finally {
+        await page.close();
+    }
+}

package/dist/mcp-server/screenshot-android.js

@@ -0,0 +1,458 @@
+/**
+ * Android screenshot tool — builds the app, installs on an emulator,
+ * and captures real screenshots via adb screencap.
+ *
+ * Gives pixel-perfect results with real navigation, images, themes,
+ * and all runtime behavior. Requires a running Android emulator.
+ */
+import { exec as execCb, execSync } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync, readFileSync, unlinkSync, mkdirSync, copyFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { findPlatformAppDir, buildScreenshotResponse, } from "./screenshot-shared.js";
+const exec = promisify(execCb);
+const androidScreenshotQueues = new Map();
+// ── constants ───────────────────────────────────────────────────────
+const ADB_SCREENSHOT_PATH = "/sdcard/openuispec_screenshot.png";
+// ── Android app directory discovery ─────────────────────────────────
+function isAndroidProject(dir) {
+    return existsSync(join(dir, "gradlew")) ||
+        existsSync(join(dir, "app", "build.gradle.kts")) ||
+        existsSync(join(dir, "app", "build.gradle"));
+}
+export function findAndroidAppDir(projectCwd, directDir) {
+    return findPlatformAppDir(projectCwd, "android", isAndroidProject, directDir);
+}
+// ── app module auto-detection ────────────────────────────────────────
+export function detectAppModule(androidDir) {
+    // Read settings.gradle.kts or settings.gradle to find included modules
+    for (const settingsFile of ["settings.gradle.kts", "settings.gradle"]) {
+        const settingsPath = join(androidDir, settingsFile);
+        if (!existsSync(settingsPath))
+            continue;
+        try {
+            const content = readFileSync(settingsPath, "utf-8");
+            // Match include(":app"), include(":module1", ":module2"), include ":app"
+            const modules = [];
+            const includeMatches = content.matchAll(/include\s*\(?([^)\n]+)\)?/g);
+            for (const m of includeMatches) {
+                const args = m[1];
+                const moduleNames = args.matchAll(/[":]+([^",:)\s]+)/g);
+                for (const mn of moduleNames) {
+                    modules.push(mn[1]);
+                }
+            }
+            // For each module, check if its build.gradle.kts/.gradle has com.android.application
+            for (const mod of modules) {
+                const modDir = join(androidDir, mod);
+                for (const buildFile of ["build.gradle.kts", "build.gradle"]) {
+                    const buildPath = join(modDir, buildFile);
+                    if (!existsSync(buildPath))
+                        continue;
+                    try {
+                        const buildContent = readFileSync(buildPath, "utf-8");
+                        if (buildContent.includes("com.android.application")) {
+                            return mod;
+                        }
+                    }
+                    catch { /* skip */ }
+                }
+            }
+        }
+        catch { /* skip */ }
+    }
+    return "app"; // fallback
+}
+function readBuildFile(androidDir, moduleName) {
+    for (const filename of ["build.gradle.kts", "build.gradle"]) {
+        try {
+            return readFileSync(join(androidDir, moduleName, filename), "utf-8");
+        }
+        catch { /* skip */ }
+    }
+    return null;
+}
+export function extractAppInfo(androidDir, moduleOverride) {
+    const moduleName = moduleOverride ?? detectAppModule(androidDir);
+    // Try to get applicationId from build.gradle.kts or build.gradle
+    let applicationId = "";
+    const buildContent = readBuildFile(androidDir, moduleName);
+    if (buildContent) {
+        // Kotlin DSL: applicationId = "..."
+        const appIdMatch = buildContent.match(/applicationId\s*=\s*"([^"]+)"/);
+        if (appIdMatch)
+            applicationId = appIdMatch[1];
+        if (!applicationId) {
+            // Groovy DSL: applicationId "..." or applicationId '...'
+            const groovyMatch = buildContent.match(/applicationId\s+['"]([^'"]+)['"]/);
+            if (groovyMatch)
+                applicationId = groovyMatch[1];
+        }
+        if (!applicationId) {
+            const nsMatch = buildContent.match(/namespace\s*=?\s*['"]([^'"]+)['"]/);
+            if (nsMatch)
+                applicationId = nsMatch[1];
+        }
+    }
+    // Get launch activity from AndroidManifest.xml
+    let launchActivity = ".MainActivity";
+    const manifestPath = join(androidDir, moduleName, "src", "main", "AndroidManifest.xml");
+    try {
+        const manifest = readFileSync(manifestPath, "utf-8");
+        // Find activity with MAIN/LAUNCHER intent filter
+        const activityMatch = manifest.match(/<activity[^>]*android:name="([^"]+)"[^]*?action android:name="android\.intent\.action\.MAIN"/);
+        if (activityMatch)
+            launchActivity = activityMatch[1];
+        // If applicationId still empty, try manifest package
+        if (!applicationId) {
+            const pkgMatch = manifest.match(/package="([^"]+)"/);
+            if (pkgMatch)
+                applicationId = pkgMatch[1];
+        }
+    }
+    catch { /* use defaults */ }
+    if (!applicationId) {
+        throw new Error(`Could not determine applicationId from ${moduleName}/build.gradle.kts (or .gradle) or AndroidManifest.xml`);
+    }
+    // Resolve relative activity name
+    const fullActivity = launchActivity.startsWith(".")
+        ? `${applicationId}${launchActivity}`
+        : launchActivity;
+    return { applicationId, launchActivity: fullActivity, moduleName };
+}
+// ── adb helpers ─────────────────────────────────────────────────────
+export function findAdb() {
+    // Check ANDROID_HOME first
+    const androidHome = process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT;
+    if (androidHome) {
+        const adbPath = join(androidHome, "platform-tools", "adb");
+        if (existsSync(adbPath))
+            return adbPath;
+    }
+    // Fall back to PATH
+    try {
+        execSync("which adb", { stdio: "pipe" });
+        return "adb";
+    }
+    catch {
+        throw new Error("adb not found. Set ANDROID_HOME or add platform-tools to PATH.\n" +
+            "Install via Android Studio or: sdkmanager 'platform-tools'");
+    }
+}
+export async function getConnectedEmulator(adb) {
+    try {
+        const { stdout } = await exec(`${adb} devices`);
+        const lines = stdout.trim().split("\n").slice(1); // skip header
+        for (const line of lines) {
+            const [serial, state] = line.split("\t");
+            if (state === "device" && (serial.startsWith("emulator-") || serial.includes(":"))) {
+                return serial;
+            }
+        }
+        // Also accept physical devices if no emulator
+        for (const line of lines) {
+            const [serial, state] = line.split("\t");
+            if (state === "device")
+                return serial;
+        }
+    }
+    catch { /* fall through */ }
+    throw new Error("No connected Android device or emulator found.\n" +
+        "Start an emulator from Android Studio or run: emulator -avd <avd_name>");
+}
+export async function adbShell(adb, serial, cmd) {
+    const { stdout } = await exec(`${adb} -s ${serial} shell ${cmd}`, { timeout: 30_000 });
+    return stdout.trim();
+}
+export async function adbExec(adb, serial, args) {
+    const { stdout } = await exec(`${adb} -s ${serial} ${args}`, { timeout: 60_000 });
+    return stdout.trim();
+}
+// ── emulator storage cleanup ─────────────────────────────────────────
+export async function cleanEmulatorStorage(adb, serial) {
+    const cmds = [
+        `pm trim-caches 2G`, // aggressively trim package cache
+        `rm -rf /data/local/tmp/*.apk`, // leftover APKs from previous installs
+        `rm -f /sdcard/openuispec_screenshot.png /sdcard/ui_dump.xml /sdcard/screenshot.png`,
+    ];
+    for (const cmd of cmds) {
+        try {
+            await adbShell(adb, serial, cmd);
+        }
+        catch { /* ignore */ }
+    }
+}
+// ── build APK ───────────────────────────────────────────────────────
+export async function buildApk(androidDir, moduleName) {
+    if (!existsSync(join(androidDir, "gradlew"))) {
+        throw new Error(`No gradlew found in ${androidDir}. Initialize the Gradle wrapper first.`);
+    }
+    try {
+        await exec(`./gradlew :${moduleName}:assembleDebug`, {
+            cwd: androidDir,
+            timeout: 300_000,
+            env: { ...process.env, JAVA_OPTS: "-Xmx2g" },
+        });
+    }
+    catch (err) {
+        const output = ((err.stderr ?? "") + "\n" + (err.stdout ?? "")).slice(-500);
+        throw new Error(`APK build failed:\n${output}`);
+    }
+    // Find the built APK
+    const apkCandidates = [
+        join(androidDir, moduleName, "build", "outputs", "apk", "debug", `${moduleName}-debug.apk`),
+        join(androidDir, moduleName, "build", "outputs", "apk", "debug", `${moduleName}-debug-unsigned.apk`),
+        // Common fallback names
+        join(androidDir, moduleName, "build", "outputs", "apk", "debug", "app-debug.apk"),
+        join(androidDir, moduleName, "build", "outputs", "apk", "debug", "app-debug-unsigned.apk"),
+    ];
+    for (const apk of apkCandidates) {
+        if (existsSync(apk))
+            return apk;
+    }
+    throw new Error(`APK not found after build in ${moduleName}/build/outputs/. Check Gradle output.`);
+}
+// ── install & launch ────────────────────────────────────────────────
+export async function installAndLaunch(adb, serial, apkPath, appInfo, route) {
+    // Force-stop and uninstall to free storage + wipe saved nav state
+    await adbShell(adb, serial, `am force-stop ${appInfo.applicationId}`);
+    try {
+        await adbShell(adb, serial, `pm uninstall ${appInfo.applicationId}`);
+    }
+    catch { /* not installed */ }
+    // Install fresh (not -r replace, since we uninstalled)
+    await adbExec(adb, serial, `install "${apkPath}"`);
+    if (route) {
+        await adbShell(adb, serial, `am start -W -a android.intent.action.VIEW -d '${route}' ` +
+            `${appInfo.applicationId}/${appInfo.launchActivity}`);
+    }
+    else {
+        await adbShell(adb, serial, `am start -W -n ${appInfo.applicationId}/${appInfo.launchActivity}`);
+    }
+}
+export async function launchInstalledApp(adb, serial, appInfo, route) {
+    await adbShell(adb, serial, `am force-stop ${appInfo.applicationId}`);
+    // Clear saved nav state so deep links route correctly
+    try {
+        await adbShell(adb, serial, `pm clear ${appInfo.applicationId}`);
+    }
+    catch { /* ignore */ }
+    if (route) {
+        await adbShell(adb, serial, `am start -W -a android.intent.action.VIEW -d '${route}' ` +
+            `${appInfo.applicationId}/${appInfo.launchActivity}`);
+    }
+    else {
+        await adbShell(adb, serial, `am start -W -n ${appInfo.applicationId}/${appInfo.launchActivity}`);
+    }
+}
+// ── theme control ───────────────────────────────────────────────────
+export async function setTheme(adb, serial, theme) {
+    const mode = theme === "dark" ? "yes" : "no";
+    await adbShell(adb, serial, `cmd uimode night ${mode}`);
+}
+// ── UI navigation via tap ───────────────────────────────────────────
+export async function tapByText(adb, serial, text) {
+    // Dump UI hierarchy
+    await adbShell(adb, serial, `uiautomator dump /sdcard/ui_dump.xml`);
+    const xml = await adbShell(adb, serial, `cat /sdcard/ui_dump.xml`);
+    await adbShell(adb, serial, `rm /sdcard/ui_dump.xml`);
+    const lowerText = text.toLowerCase();
+    // Parse each <node .../> extracting text, content-desc, and bounds
+    const nodeRegex = /<node\s[^>]+>/g;
+    const nodes = [];
+    let nodeMatch;
+    while ((nodeMatch = nodeRegex.exec(xml)) !== null) {
+        const attrs = nodeMatch[0];
+        const textMatch = attrs.match(/\btext="([^"]*)"/);
+        const descMatch = attrs.match(/\bcontent-desc="([^"]*)"/);
+        const boundsMatch = attrs.match(/\bbounds="\[(\d+),(\d+)\]\[(\d+),(\d+)\]"/);
+        if (!boundsMatch)
+            continue;
+        nodes.push({
+            text: textMatch?.[1] ?? "",
+            desc: descMatch?.[1] ?? "",
+            cx: Math.round((parseInt(boundsMatch[1]) + parseInt(boundsMatch[3])) / 2),
+            cy: Math.round((parseInt(boundsMatch[2]) + parseInt(boundsMatch[4])) / 2),
+        });
+    }
+    // Exact match on text or content-desc
+    for (const node of nodes) {
+        if (node.text.toLowerCase() === lowerText || node.desc.toLowerCase() === lowerText) {
+            await adbShell(adb, serial, `input tap ${node.cx} ${node.cy}`);
+            return;
+        }
+    }
+    // Partial/contains match
+    for (const node of nodes) {
+        if (node.text.toLowerCase().includes(lowerText) || node.desc.toLowerCase().includes(lowerText)) {
+            await adbShell(adb, serial, `input tap ${node.cx} ${node.cy}`);
+            return;
+        }
+    }
+    throw new Error(`UI element with text "${text}" not found on screen.`);
+}
+export async function navigateByTaps(adb, serial, steps) {
+    for (const step of steps) {
+        await tapByText(adb, serial, step);
+        // Wait for navigation animation
+        await new Promise(r => setTimeout(r, 800));
+    }
+}
+// ── screenshot capture ──────────────────────────────────────────────
+export async function captureScreenshot(adb, serial, localPath) {
+    try {
+        await exec(`${adb} -s ${serial} exec-out screencap -p > "${localPath}"`, { timeout: 60_000, shell: "/bin/bash" });
+    }
+    catch (err) {
+        const output = ((err.stderr ?? "") + "\n" + (err.stdout ?? "")).trim();
+        throw new Error(`Android screenshot capture failed${output ? `:\n${output}` : "."}`);
+    }
+}
+// ── wait for app ready ──────────────────────────────────────────────
+async function waitForAppReady(adb, serial, applicationId, waitMs) {
+    // Wait for the activity to be in resumed state
+    const startTime = Date.now();
+    const timeout = Math.min(waitMs, 15_000);
+    while (Date.now() - startTime < timeout) {
+        try {
+            const output = await adbShell(adb, serial, `dumpsys activity activities | grep -E "mResumedActivity|topResumedActivity"`);
+            if (output.includes(applicationId)) {
+                // App is in foreground, wait the remaining time for content to load
+                const elapsed = Date.now() - startTime;
+                const remaining = Math.max(waitMs - elapsed, 500);
+                await new Promise(r => setTimeout(r, remaining));
+                return;
+            }
+        }
+        catch { /* activity not ready yet */ }
+        await new Promise(r => setTimeout(r, 500));
+    }
+    // Fallback: just wait the full duration
+    await new Promise(r => setTimeout(r, waitMs));
+}
+async function takeSingleAndroidCapture(adb, serial, androidDir, appInfo, capture, theme, defaultOutputDir) {
+    await launchInstalledApp(adb, serial, appInfo, capture.route);
+    await waitForAppReady(adb, serial, appInfo.applicationId, capture.wait_for ?? 3000);
+    if (capture.nav && capture.nav.length > 0) {
+        await navigateByTaps(adb, serial, capture.nav);
+    }
+    const themeLabel = theme ?? "default";
+    const filename = `${capture.screen}_${themeLabel}.png`;
+    const tmpPath = join(androidDir, `.openuispec-screenshot-${capture.screen}.png`);
+    await captureScreenshot(adb, serial, tmpPath);
+    let savedPath = filename;
+    if (defaultOutputDir) {
+        const outDir = resolve(androidDir, defaultOutputDir);
+        mkdirSync(outDir, { recursive: true });
+        savedPath = join(outDir, filename);
+        copyFileSync(tmpPath, savedPath);
+    }
+    try {
+        const data = readFileSync(tmpPath).toString("base64");
+        return {
+            screen: capture.screen,
+            path: savedPath,
+            data,
+        };
+    }
+    finally {
+        try {
+            unlinkSync(tmpPath);
+        }
+        catch { /* ignore */ }
+    }
+}
+// ── main entry point ────────────────────────────────────────────────
+export async function takeAndroidScreenshot(projectCwd, options) {
+    const { screen, route, nav, theme, wait_for = 3000, output_dir, project_dir, module, } = options;
+    // 1. Find Android project
+    const androidDir = findAndroidAppDir(projectCwd, project_dir);
+    const appInfo = extractAppInfo(androidDir, module);
+    // 2. Find adb and emulator
+    const adb = findAdb();
+    const serial = await getConnectedEmulator(adb);
+    const previousRun = androidScreenshotQueues.get(serial) ?? Promise.resolve();
+    let releaseQueue;
+    const currentRun = new Promise((resolve) => {
+        releaseQueue = resolve;
+    });
+    const queuedRun = previousRun.then(() => currentRun);
+    androidScreenshotQueues.set(serial, queuedRun);
+    await previousRun;
+    try {
+        // 3. Free emulator storage before build/install
+        await cleanEmulatorStorage(adb, serial);
+        // 4. Build APK
+        const apkPath = await buildApk(androidDir, appInfo.moduleName);
+        // 5. Set theme if requested
+        if (theme) {
+            await setTheme(adb, serial, theme);
+        }
+        // 6. Install fresh once, then capture
+        await installAndLaunch(adb, serial, apkPath, appInfo, route);
+        const snapshot = await takeSingleAndroidCapture(adb, serial, androidDir, appInfo, { screen: screen ?? "main", route, nav, wait_for }, theme, output_dir);
+        return buildScreenshotResponse([snapshot], (s) => ({
+            screen: s.screen,
+            path: snapshot.path ?? null,
+            emulator: serial,
+            theme: theme ?? "default",
+            applicationId: appInfo.applicationId,
+        }));
+    }
+    finally {
+        releaseQueue?.();
+        if (androidScreenshotQueues.get(serial) === queuedRun) {
+            androidScreenshotQueues.delete(serial);
+        }
+    }
+}
+export async function takeAndroidScreenshotBatch(projectCwd, options) {
+    const { captures, theme, output_dir, project_dir, module } = options;
+    if (captures.length === 0) {
+        return {
+            content: [{ type: "text", text: "No Android captures specified." }],
+            isError: true,
+        };
+    }
+    const androidDir = findAndroidAppDir(projectCwd, project_dir);
+    const appInfo = extractAppInfo(androidDir, module);
+    const adb = findAdb();
+    const serial = await getConnectedEmulator(adb);
+    const previousRun = androidScreenshotQueues.get(serial) ?? Promise.resolve();
+    let releaseQueue;
+    const currentRun = new Promise((resolve) => {
+        releaseQueue = resolve;
+    });
+    const queuedRun = previousRun.then(() => currentRun);
+    androidScreenshotQueues.set(serial, queuedRun);
+    await previousRun;
+    try {
+        await cleanEmulatorStorage(adb, serial);
+        const apkPath = await buildApk(androidDir, appInfo.moduleName);
+        if (theme) {
+            await setTheme(adb, serial, theme);
+        }
+        await installAndLaunch(adb, serial, apkPath, appInfo);
+        // Pre-create output dir once
+        if (output_dir)
+            mkdirSync(resolve(androidDir, output_dir), { recursive: true });
+        const snapshots = [];
+        for (let index = 0; index < captures.length; index += 1) {
+            const capture = captures[index];
+            snapshots.push(await takeSingleAndroidCapture(adb, serial, androidDir, appInfo, capture, theme, output_dir));
+        }
+        return buildScreenshotResponse(snapshots, (snapshot) => ({
+            screen: snapshot.screen,
+            path: snapshot.path,
+            emulator: serial,
+            theme: theme ?? "default",
+            applicationId: appInfo.applicationId,
+        }));
+    }
+    finally {
+        releaseQueue?.();
+        if (androidScreenshotQueues.get(serial) === queuedRun) {
+            androidScreenshotQueues.delete(serial);
+        }
+    }
+}