@kraken-e2e/driver-android 1.0.0

package/dist/appium-server.d.ts

@@ -0,0 +1,23 @@
+import type { Logger } from '@kraken-e2e/contracts';
+/**
+ * Idempotent: refreshes symlinks every start (pnpm store paths move); version
+ * bumps change the generated package.json, which changes its md5 and triggers
+ * Appium's manifest re-sync.
+ */
+export declare function prepareAppiumHome(homeDir: string, driverPackages: readonly string[]): void;
+/** Allocates an OS-assigned free port (hazard 1: appium dies on EADDRINUSE). */
+export declare function allocatePort(): Promise<number>;
+export interface AppiumServerHandle {
+    readonly port: number;
+    close(): Promise<void>;
+}
+export interface StartServerOptions {
+    readonly homeDir: string;
+    readonly driverPackages: readonly string[];
+    readonly logFile: string;
+    readonly logger: Logger;
+    /** Appium 3 scoped syntax, e.g. 'uiautomator2:adb_shell'. */
+    readonly allowInsecure?: readonly string[];
+}
+export declare function startAppiumServer(options: StartServerOptions): Promise<AppiumServerHandle>;
+//# sourceMappingURL=appium-server.d.ts.map

package/dist/appium-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appium-server.d.ts","sourceRoot":"","sources":["../src/appium-server.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAWpD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAkC1F;AAED,gFAAgF;AAChF,wBAAsB,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAapD;AAeD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA+DhG"}

package/dist/appium-server.js

@@ -0,0 +1,144 @@
+/**
+ * Embedded Appium server lifecycle (ADR-0007, mechanism live-verified against
+ * appium@3.5.2):
+ *
+ * SYNTHESIZED PROJECT-MODE HOME — we generate an APPIUM_HOME whose
+ * package.json declares the EXACT appium+driver versions resolved from THIS
+ * package's own dependency tree (lockfile-governed, ADR-0001 §5.10) and
+ * symlink the resolved packages into its node_modules. Appium's project-mode
+ * manifest auto-discovers them; no `appium driver install` ever runs
+ * (`--source=local` is verified broken: it shells to `npm link`, which fires
+ * the drivers' `prepare` scripts and fails on published tarballs).
+ *
+ * Live-verified hazards handled here:
+ * - EADDRINUSE calls process.exit(1) even with throwInsteadOfExit → we
+ *   allocate the port ourselves immediately before boot.
+ * - main() installs its own SIGINT/SIGTERM handlers that process.exit(0) →
+ *   we strip them so the Kraken CLI owns signals (ADR-0001 §5.11).
+ */
+import { mkdirSync, renameSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { createServer } from 'node:net';
+import { dirname, join } from 'node:path';
+import { KrakenError } from '@kraken-e2e/contracts';
+const require_ = createRequire(import.meta.url);
+function resolvedPackage(name) {
+    const packageJsonPath = require_.resolve(`${name}/package.json`);
+    const { version } = require_(packageJsonPath);
+    return { dir: dirname(packageJsonPath), version };
+}
+/**
+ * Idempotent: refreshes symlinks every start (pnpm store paths move); version
+ * bumps change the generated package.json, which changes its md5 and triggers
+ * Appium's manifest re-sync.
+ */
+export function prepareAppiumHome(homeDir, driverPackages) {
+    const nodeModules = join(homeDir, 'node_modules');
+    mkdirSync(nodeModules, { recursive: true });
+    const appium = resolvedPackage('appium');
+    const dependencies = { appium: appium.version };
+    for (const name of [...driverPackages, 'appium']) {
+        const resolved = name === 'appium' ? appium : resolvedPackage(name);
+        if (name !== 'appium')
+            dependencies[name] = resolved.version;
+        const linkPath = join(nodeModules, name);
+        mkdirSync(dirname(linkPath), { recursive: true });
+        // Concurrent-run-safe replace: symlink to a temp name, rename over the
+        // target (atomic on POSIX) — a plain rm+symlink pair races a sibling run.
+        const tempLink = `${linkPath}.tmp-${process.pid}`;
+        rmSync(tempLink, { force: true });
+        symlinkSync(resolved.dir, tempLink, 'dir');
+        rmSync(linkPath, { recursive: true, force: true });
+        renameSync(tempLink, linkPath);
+    }
+    writeFileSync(join(homeDir, 'package.json'), `${JSON.stringify({
+        name: 'kraken-appium-home',
+        private: true,
+        description: 'Generated by Kraken — appium project-mode home (ADR-0007). Do not edit.',
+        dependencies,
+    }, null, 2)}\n`);
+}
+/** Allocates an OS-assigned free port (hazard 1: appium dies on EADDRINUSE). */
+export async function allocatePort() {
+    return new Promise((resolve, reject) => {
+        const probe = createServer();
+        probe.once('error', reject);
+        probe.listen(0, '127.0.0.1', () => {
+            const address = probe.address();
+            const port = typeof address === 'object' && address !== null ? address.port : undefined;
+            probe.close(() => {
+                if (port === undefined)
+                    reject(new Error('could not allocate a port'));
+                else
+                    resolve(port);
+            });
+        });
+    });
+}
+function stripAddedSignalHandlers(before) {
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+        for (const listener of process.listeners(signal)) {
+            if (!before[signal].includes(listener)) {
+                process.removeListener(signal, listener);
+            }
+        }
+    }
+}
+export async function startAppiumServer(options) {
+    prepareAppiumHome(options.homeDir, options.driverPackages);
+    mkdirSync(dirname(options.logFile), { recursive: true });
+    // Import-safety rule (ADR-0001 §5.5): appium loads HERE, never at top level.
+    // Non-literal specifier: appium ships raw .ts type sources that explode under
+    // strict verbatimModuleSyntax; we type the surface we use by hand instead.
+    const appiumSpecifier = 'appium';
+    // The package is CJS — named ESM imports fail; use the default namespace.
+    const appiumModule = (await import(appiumSpecifier));
+    const main = appiumModule.default?.main ?? appiumModule.main;
+    if (!main) {
+        throw new KrakenError('KRK-DRIVER-START-FAILED', 'appium package has no main() export.');
+    }
+    // Allocate AFTER the (slow, seconds-cold) appium import so the port-reuse
+    // race window stays microseconds — appium process.exit(1)s on EADDRINUSE.
+    const port = await allocatePort();
+    // Hazard 2: strip the SIGINT/SIGTERM handlers main() installs.
+    const before = {
+        SIGINT: process.listeners('SIGINT'),
+        SIGTERM: process.listeners('SIGTERM'),
+    };
+    options.logger.info('starting embedded Appium server', {
+        port,
+        home: options.homeDir,
+        logFile: options.logFile,
+    });
+    let server;
+    try {
+        server = (await main({
+            subcommand: 'server',
+            port,
+            address: '127.0.0.1',
+            appiumHome: options.homeDir,
+            throwInsteadOfExit: true,
+            // Quiet console (the TUI owns stdout), full debug into the log file.
+            loglevel: 'error:debug',
+            logFile: options.logFile,
+            ...(options.allowInsecure !== undefined ? { allowInsecure: [...options.allowInsecure] } : {}),
+        }));
+    }
+    catch (cause) {
+        stripAddedSignalHandlers(before);
+        throw KrakenError.wrap(cause, 'KRK-DRIVER-START-FAILED', 'embedded Appium failed to start');
+    }
+    // Appium registers its handlers in a continuation AFTER main() resolves
+    // (live-verified) — wait one macrotask before stripping.
+    await new Promise((resolve) => setImmediate(resolve));
+    stripAddedSignalHandlers(before);
+    options.logger.info('Appium server ready', { port });
+    return {
+        port,
+        close: async () => {
+            await server.close();
+            options.logger.info('Appium server stopped', { port });
+        },
+    };
+}
+//# sourceMappingURL=appium-server.js.map

package/dist/appium-server.js.map

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

package/dist/doctor.d.ts

@@ -0,0 +1,18 @@
+import type { DoctorCheck } from '@kraken-e2e/contracts';
+/** Injectable so doctor checks are unit-testable without an Android SDK. */
+export type CommandRunner = (command: string, args: readonly string[]) => {
+    status: number | null;
+    stdout: string;
+};
+export declare const spawnRunner: CommandRunner;
+export interface FsProbe {
+    exists(path: string): boolean;
+}
+/**
+ * Kraken-specific Android checks (ADR-0001 §5.13): the failures Appium's own
+ * doctor does not diagnose for students — missing AVDs, JDK too old for
+ * sdkmanager, deprecated env vars. Wrapping `appium driver doctor uiautomator2`
+ * arrives with the server-lifecycle work (ADR-0007).
+ */
+export declare function androidDoctorChecks(run?: CommandRunner, fs?: FsProbe): readonly DoctorCheck[];
+//# sourceMappingURL=doctor.d.ts.map

package/dist/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD,4EAA4E;AAC5E,MAAM,MAAM,aAAa,GAAG,CAC1B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,KACpB;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/C,eAAO,MAAM,WAAW,EAAE,aAGzB,CAAC;AAEF,MAAM,WAAW,OAAO;IACtB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B;AAID;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,GAAE,aAA2B,EAChC,EAAE,GAAE,OAAgB,GACnB,SAAS,WAAW,EAAE,CAsHxB"}

package/dist/doctor.js

@@ -0,0 +1,130 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+export const spawnRunner = (command, args) => {
+    const result = spawnSync(command, [...args], { encoding: 'utf8', timeout: 20_000 });
+    return { status: result.status, stdout: `${result.stdout ?? ''}${result.stderr ?? ''}` };
+};
+const realFs = { exists: (path) => existsSync(path) };
+/**
+ * Kraken-specific Android checks (ADR-0001 §5.13): the failures Appium's own
+ * doctor does not diagnose for students — missing AVDs, JDK too old for
+ * sdkmanager, deprecated env vars. Wrapping `appium driver doctor uiautomator2`
+ * arrives with the server-lifecycle work (ADR-0007).
+ */
+export function androidDoctorChecks(run = spawnRunner, fs = realFs) {
+    return [
+        {
+            id: 'android.sdk-home',
+            title: 'ANDROID_HOME points at an Android SDK',
+            run: async (host) => {
+                const home = host.env['ANDROID_HOME'];
+                const legacy = host.env['ANDROID_SDK_ROOT'];
+                if (!home && legacy) {
+                    return {
+                        status: 'warn',
+                        detail: `only ANDROID_SDK_ROOT is set (${legacy}) — deprecated by Google`,
+                        fix: 'Set ANDROID_HOME to the same directory (Google deprecated ANDROID_SDK_ROOT).',
+                    };
+                }
+                if (!home) {
+                    return {
+                        status: 'fail',
+                        detail: 'ANDROID_HOME is not set',
+                        fix: 'Install the Android SDK and export ANDROID_HOME (usually ~/Library/Android/sdk on macOS).',
+                    };
+                }
+                if (!fs.exists(home)) {
+                    return {
+                        status: 'fail',
+                        detail: `ANDROID_HOME=${home} does not exist`,
+                        fix: 'Point ANDROID_HOME at the actual SDK directory.',
+                    };
+                }
+                return { status: 'ok', detail: home };
+            },
+        },
+        {
+            id: 'android.jdk',
+            title: 'JDK 17+ (sdkmanager requires it; uiautomator2 needs a JDK)',
+            run: async (host) => {
+                if (!host.env['JAVA_HOME']) {
+                    return {
+                        status: 'fail',
+                        detail: 'JAVA_HOME is not set',
+                        fix: 'Install a JDK (17+; 21 LTS recommended) and export JAVA_HOME.',
+                    };
+                }
+                const result = run('java', ['--version']);
+                const major = Number.parseInt(/(?:openjdk|java)\s+(\d+)/i.exec(result.stdout)?.[1] ?? '0', 10);
+                if (result.status !== 0 || major === 0) {
+                    return {
+                        status: 'fail',
+                        detail: 'java is not runnable',
+                        fix: 'Ensure $JAVA_HOME/bin is on PATH.',
+                    };
+                }
+                if (major < 17) {
+                    return {
+                        status: 'fail',
+                        detail: `JDK ${major} found`,
+                        fix: 'Android SDK tooling is compiled for JDK 17+ (class file 61) — upgrade (21 LTS recommended).',
+                    };
+                }
+                return { status: 'ok', detail: `JDK ${major}` };
+            },
+        },
+        {
+            id: 'android.adb',
+            title: 'adb (platform-tools) is runnable',
+            run: async (host) => {
+                const home = host.env['ANDROID_HOME'];
+                const adb = home ? join(home, 'platform-tools', 'adb') : 'adb';
+                const result = run(adb, ['--version']);
+                if (result.status !== 0) {
+                    return {
+                        status: 'fail',
+                        detail: 'adb did not run',
+                        fix: 'Install platform-tools: sdkmanager "platform-tools" (or via Android Studio).',
+                    };
+                }
+                return { status: 'ok', detail: result.stdout.split('\n')[0] ?? 'adb ok' };
+            },
+        },
+        {
+            id: 'android.target',
+            title: 'A device is connected or an AVD exists',
+            run: async (host) => {
+                const home = host.env['ANDROID_HOME'];
+                const adb = home ? join(home, 'platform-tools', 'adb') : 'adb';
+                const devices = run(adb, ['devices'])
+                    .stdout.split('\n')
+                    .slice(1)
+                    .filter((line) => line.trim().endsWith('device'));
+                if (devices.length > 0) {
+                    return { status: 'ok', detail: `${devices.length} device(s)/emulator(s) connected` };
+                }
+                const emulator = home ? join(home, 'emulator', 'emulator') : 'emulator';
+                const avds = run(emulator, ['-list-avds'])
+                    .stdout.split('\n')
+                    .map((line) => line.trim())
+                    .filter((line) => line.length > 0 && !line.startsWith('INFO'));
+                if (avds.length > 0) {
+                    return {
+                        status: 'ok',
+                        detail: `no device connected; ${avds.length} AVD(s) available for auto-boot: ${avds.join(', ')}`,
+                    };
+                }
+                const armNote = host.platform === 'darwin' && host.arch === 'arm64'
+                    ? ' On Apple Silicon only arm64-v8a system images boot (API 26+ required by uiautomator2).'
+                    : '';
+                return {
+                    status: 'fail',
+                    detail: 'no connected device and no AVD',
+                    fix: `Create an AVD (Android Studio → Device Manager) or connect a device with USB debugging.${armNote}`,
+                };
+            },
+        },
+    ];
+}
+//# sourceMappingURL=doctor.js.map

package/dist/doctor.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export interface AndroidDriverOptions {
+    /** Default AVD to boot for actors that don't specify a device (appium:avd). */
+    readonly avd?: string;
+    /** Appium 3 scoped insecure features, e.g. ['uiautomator2:adb_shell']. */
+    readonly allowInsecure?: readonly string[];
+    /** Extra capabilities merged into every session (appium:* keys included). */
+    readonly capabilities?: Readonly<Record<string, unknown>>;
+}
+export declare const android: (opts?: AndroidDriverOptions | undefined) => import("@kraken-e2e/contracts").KrakenDriver<AndroidDriverOptions>;
+export default android;
+export { allocatePort, prepareAppiumHome, startAppiumServer } from './appium-server.js';
+export { androidDoctorChecks } from './doctor.js';
+export { keyCodeFor, toAndroidSelector } from './locators.js';
+export { manifest } from './manifest.js';
+export { AndroidUserSession } from './wdio-session.js';
+//# 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":"AAeA,MAAM,WAAW,oBAAoB;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC3D;AAED,eAAO,MAAM,OAAO,iHAwFlB,CAAC;AAEH,eAAe,OAAO,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACxF,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,96 @@
+/**
+ * @kraken-e2e/driver-android — Android driver (Appium 3 + UiAutomator2, ADR-0007).
+ *
+ * IMPORT-SAFETY RULE (ADR-0001 §5.5): this entry must be importable on every
+ * host — appium and webdriverio load DYNAMICALLY inside start()/createSession().
+ */
+import { join } from 'node:path';
+import { defineDriver } from '@kraken-e2e/contracts';
+import { allocatePort, startAppiumServer } from './appium-server.js';
+import { androidDoctorChecks } from './doctor.js';
+import { manifest } from './manifest.js';
+import { AndroidUserSession } from './wdio-session.js';
+export const android = defineDriver((opts = {}) => {
+    let server;
+    return {
+        manifest,
+        doctor: androidDoctorChecks(),
+        async start(host, services) {
+            if (server) {
+                // Double start would silently leak the first embedded server.
+                throw new Error('driver-android: already started — call stop() first.');
+            }
+            const projectRoot = host.projectRoot ?? process.cwd();
+            server = await startAppiumServer({
+                homeDir: join(projectRoot, '.kraken', 'appium', 'android-home'),
+                driverPackages: ['appium-uiautomator2-driver'],
+                logFile: join(services.artifactsDir, 'appium-android.log'),
+                logger: services.logger,
+                ...(opts.allowInsecure !== undefined ? { allowInsecure: opts.allowInsecure } : {}),
+            });
+        },
+        async createSession(actor, services) {
+            if (!server) {
+                throw new Error('driver-android: start() must run before createSession().');
+            }
+            const config = actor.config;
+            // OS-assigned free port: process-local counters over a fixed base collide
+            // across CONCURRENT kraken runs on one machine (uia2 accepts any port).
+            const systemPort = await allocatePort();
+            const capabilities = {
+                platformName: 'Android',
+                'appium:automationName': 'UiAutomator2',
+                'appium:systemPort': systemPort,
+                'appium:newCommandTimeout': 300,
+                // Cold emulator boots on a laptop take a while — be generous.
+                'appium:avdLaunchTimeout': 180_000,
+                'appium:avdReadyTimeout': 180_000,
+                'appium:adbExecTimeout': 60_000,
+                // Laptop-class default: the 20s upstream default flakes on loaded
+                // machines (observed live: server-APK install timeout mid-demo).
+                'appium:uiautomator2ServerInstallTimeout': 120_000,
+                ...(typeof config['udid'] === 'string' ? { 'appium:udid': config['udid'] } : {}),
+                ...(typeof config['avd'] === 'string' || opts.avd !== undefined
+                    ? { 'appium:avd': config['avd'] ?? opts.avd }
+                    : {}),
+                ...(typeof config['app'] === 'string' ? { 'appium:app': config['app'] } : {}),
+                ...(typeof config['appPackage'] === 'string'
+                    ? { 'appium:appPackage': config['appPackage'] }
+                    : {}),
+                ...(typeof config['appActivity'] === 'string'
+                    ? { 'appium:appActivity': config['appActivity'] }
+                    : {}),
+                ...opts.capabilities,
+                ...(typeof config['capabilities'] === 'object' && config['capabilities'] !== null
+                    ? config['capabilities']
+                    : {}),
+            };
+            services.logger.info('creating Android session', { actor: actor.id, systemPort });
+            // Import-safety rule: webdriverio loads here, not at the top level.
+            const { remote } = await import('webdriverio');
+            const browser = await remote({
+                hostname: '127.0.0.1',
+                port: server.port,
+                capabilities: capabilities,
+                logLevel: 'error',
+                connectionRetryTimeout: 300_000,
+                connectionRetryCount: 1,
+            });
+            const appPackage = typeof capabilities['appium:appPackage'] === 'string'
+                ? capabilities['appium:appPackage']
+                : undefined;
+            return new AndroidUserSession(browser, actor, services, appPackage);
+        },
+        async stop() {
+            await server?.close();
+            server = undefined;
+        },
+    };
+});
+export default android;
+export { allocatePort, prepareAppiumHome, startAppiumServer } from './appium-server.js';
+export { androidDoctorChecks } from './doctor.js';
+export { keyCodeFor, toAndroidSelector } from './locators.js';
+export { manifest } from './manifest.js';
+export { AndroidUserSession } from './wdio-session.js';
+//# 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/locators.d.ts

@@ -0,0 +1,17 @@
+import { type SemanticKey, type TargetLocator } from '@kraken-e2e/contracts';
+/**
+ * Portable locator strategies → UiAutomator2 selectors (ADR-0002 D1 mapping:
+ * testId → resource-id, a11y → content-desc, text → visible text).
+ *
+ * Unqualified resource ids ("composer") are matched with a regex against the
+ * `<package>:id/<value>` convention, so feature files stay package-agnostic.
+ */
+export declare function toAndroidSelector(target: TargetLocator): string;
+/**
+ * Android key codes for the semantic keys (contract 2.0). KEYCODE_BACK (4)
+ * is intentionally absent — 'back' left SemanticKey (Android-only concept);
+ * it remains reachable via { by: 'native' } flows or native() (ADR-0007).
+ */
+export declare const ANDROID_KEY_CODES: Readonly<Record<SemanticKey, number>>;
+export declare function keyCodeFor(key: SemanticKey): number;
+//# sourceMappingURL=locators.d.ts.map

package/dist/locators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locators.d.ts","sourceRoot":"","sources":["../src/locators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE1F;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAgB/D;AAMD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAInE,CAAC;AAEF,wBAAgB,UAAU,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CASnD"}

package/dist/locators.js

@@ -0,0 +1,46 @@
+import { KrakenError } from '@kraken-e2e/contracts';
+/**
+ * Portable locator strategies → UiAutomator2 selectors (ADR-0002 D1 mapping:
+ * testId → resource-id, a11y → content-desc, text → visible text).
+ *
+ * Unqualified resource ids ("composer") are matched with a regex against the
+ * `<package>:id/<value>` convention, so feature files stay package-agnostic.
+ */
+export function toAndroidSelector(target) {
+    switch (target.by) {
+        case 'testId':
+            return target.value.includes(':id/')
+                ? `android=new UiSelector().resourceId("${target.value}")`
+                : `android=new UiSelector().resourceIdMatches(".*:id/${escapeForUiSelector(target.value)}")`;
+        case 'text':
+            return target.exact
+                ? `android=new UiSelector().text("${escapeForUiSelector(target.value)}")`
+                : `android=new UiSelector().textContains("${escapeForUiSelector(target.value)}")`;
+        case 'a11y':
+            return `~${target.value}`;
+        case 'native':
+            // Explicitly non-portable: any raw WebdriverIO/Appium selector string.
+            return target.value;
+    }
+}
+function escapeForUiSelector(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+/**
+ * Android key codes for the semantic keys (contract 2.0). KEYCODE_BACK (4)
+ * is intentionally absent — 'back' left SemanticKey (Android-only concept);
+ * it remains reachable via { by: 'native' } flows or native() (ADR-0007).
+ */
+export const ANDROID_KEY_CODES = {
+    enter: 66, // KEYCODE_ENTER
+    escape: 111, // KEYCODE_ESCAPE
+    tab: 61, // KEYCODE_TAB
+};
+export function keyCodeFor(key) {
+    const code = ANDROID_KEY_CODES[key];
+    if (code === undefined) {
+        throw new KrakenError('KRK-SESSION-OP-UNSUPPORTED', `Unknown semantic key "${key}" for Android.`);
+    }
+    return code;
+}
+//# sourceMappingURL=locators.js.map

package/dist/locators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locators.js","sourceRoot":"","sources":["../src/locators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAwC,MAAM,uBAAuB,CAAC;AAE1F;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAqB;IACrD,QAAQ,MAAM,CAAC,EAAE,EAAE,CAAC;QAClB,KAAK,QAAQ;YACX,OAAO,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC;gBAClC,CAAC,CAAC,wCAAwC,MAAM,CAAC,KAAK,IAAI;gBAC1D,CAAC,CAAC,qDAAqD,mBAAmB,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;QACjG,KAAK,MAAM;YACT,OAAO,MAAM,CAAC,KAAK;gBACjB,CAAC,CAAC,kCAAkC,mBAAmB,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI;gBACzE,CAAC,CAAC,0CAA0C,mBAAmB,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;QACtF,KAAK,MAAM;YACT,OAAO,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QAC5B,KAAK,QAAQ;YACX,uEAAuE;YACvE,OAAO,MAAM,CAAC,KAAK,CAAC;IACxB,CAAC;AACH,CAAC;AAED,SAAS,mBAAmB,CAAC,KAAa;IACxC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AAC3D,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAA0C;IACtE,KAAK,EAAE,EAAE,EAAE,gBAAgB;IAC3B,MAAM,EAAE,GAAG,EAAE,iBAAiB;IAC9B,GAAG,EAAE,EAAE,EAAE,cAAc;CACxB,CAAC;AAEF,MAAM,UAAU,UAAU,CAAC,GAAgB;IACzC,MAAM,IAAI,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,WAAW,CACnB,4BAA4B,EAC5B,yBAAyB,GAAG,gBAAgB,CAC7C,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/manifest.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The /manifest subpath (ADR-0001 §5.5): ZERO heavy imports — the registry
+ * host-gates string-form registrations by importing THIS module before the
+ * main entry ever loads. Keep it dependency-light forever.
+ */
+import { type DriverManifest } from '@kraken-e2e/contracts';
+export declare const manifest: DriverManifest;
+export default manifest;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAoB,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE9E,eAAO,MAAM,QAAQ,EAAE,cActB,CAAC;AAEF,eAAe,QAAQ,CAAC"}

package/dist/manifest.js

@@ -0,0 +1,23 @@
+/**
+ * The /manifest subpath (ADR-0001 §5.5): ZERO heavy imports — the registry
+ * host-gates string-form registrations by importing THIS module before the
+ * main entry ever loads. Keep it dependency-light forever.
+ */
+import { CONTRACT_VERSION } from '@kraken-e2e/contracts';
+export const manifest = {
+    kind: 'kraken-driver',
+    id: 'android',
+    platforms: ['android'],
+    version: '0.0.0',
+    contract: CONTRACT_VERSION,
+    platformLabel: 'Android (UiAutomator2 via Appium 3)',
+    // No hostRequirements: Android automation runs on macOS, Linux and Windows.
+    setupHints: [
+        'Install the Android SDK and set ANDROID_HOME',
+        'Install a JDK (17+) and set JAVA_HOME',
+        'Create an arm64-v8a AVD at API 26+ (on Apple Silicon) or connect a device',
+        'Run: kraken doctor',
+    ],
+};
+export default manifest;
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,gBAAgB,EAAuB,MAAM,uBAAuB,CAAC;AAE9E,MAAM,CAAC,MAAM,QAAQ,GAAmB;IACtC,IAAI,EAAE,eAAe;IACrB,EAAE,EAAE,SAAS;IACb,SAAS,EAAE,CAAC,SAAS,CAAC;IACtB,OAAO,EAAE,OAAO;IAChB,QAAQ,EAAE,gBAAgB;IAC1B,aAAa,EAAE,qCAAqC;IACpD,4EAA4E;IAC5E,UAAU,EAAE;QACV,8CAA8C;QAC9C,uCAAuC;QACvC,2EAA2E;QAC3E,oBAAoB;KACrB;CACF,CAAC;AAEF,eAAe,QAAQ,CAAC"}