@delacour/warden-e2e 0.6.0 → 0.7.0

package/types/core/src/builds/install-device.d.ts

@@ -0,0 +1,37 @@
+import { type AsyncResult } from "../../../types/src/result";
+import type { Exec, ExecResult } from "../exec";
+import type { InstalledApp } from "./resolve";
+/** The temp-file effects of a devicectl call. */
+export type DeviceIo = {
+    /** a fresh private directory */
+    tempDir: () => Promise<string>;
+    read: (path: string) => Promise<string>;
+    remove: (dir: string) => Promise<void>;
+};
+export declare const nodeDeviceIo: DeviceIo;
+export type PhoneDeps = {
+    exec: Exec;
+    io?: DeviceIo;
+};
+export declare const phoneInstallArgv: (udid: string, appPath: string, json: string) => string[];
+export declare const phoneUninstallArgv: (udid: string, bundleId: string, json: string) => string[];
+export declare const phoneAppsArgv: (udid: string, bundleId: string, json: string) => string[];
+/**
+ * A failed devicectl call in words: a locked phone, a phone the provisioning profile does not list, or one of the
+ * classified signing / device states (`classifyRunnerOutput`), each with what to do; else devicectl's first line.
+ */
+export declare function describePhoneFailure(what: string, res: ExecResult): string;
+/** Is `bundleId` on the phone, and which `CFBundleVersion` does it have? */
+export declare function probePhone(deps: PhoneDeps, udid: string, bundleId: string): AsyncResult<InstalledApp>;
+/** Install `appPath`, then confirm `bundleId` is there. */
+export declare function installOnPhone(deps: PhoneDeps, udid: string, appPath: string, bundleId: string): AsyncResult<InstalledApp>;
+/** Remove `bundleId` (the app under test) from the phone. */
+export declare function uninstallFromPhone(deps: PhoneDeps, udid: string, bundleId: string): AsyncResult<void>;
+/** `CFBundleVersion` of an `.app` (one `plutil` spawn); undefined when it cannot be read. */
+export declare function appBundleVersion(exec: Exec, appDir: string): Promise<string | undefined>;
+/**
+ * Is the app on the phone the cached build? The install record already named this build's key; this adds the
+ * `CFBundleVersion` the phone reports against the cached `.app`'s. Anything unreadable counts as a mismatch
+ * (a reinstall is the safe side).
+ */
+export declare function phoneAppMatches(exec: Exec, cachedApp: string, installed: InstalledApp): Promise<boolean>;

package/types/core/src/builds/install.d.ts

@@ -1,10 +1,14 @@
 import { type AsyncResult } from "../../../types/src/result";
 import { type Exec } from "../exec";
 import type { Platform } from "../types";
+import { type DeviceIo } from "./install-device";
 import type { InstalledApp } from "./resolve";
 /** Byte size of a file; undefined when it cannot be read. Injected so identity checks need no `stat` spawns. */
 export type FileSize = (path: string) => Promise<number | undefined>;
 export declare const nodeFileSize: FileSize;
+/** Hex sha256 of a file; undefined when it cannot be read (or is a directory). Injected so tests need no real apk. */
+export type FileDigest = (path: string) => Promise<string | undefined>;
+export declare const nodeFileDigest: FileDigest;
 /** `ino:mtime` of a file; undefined when it cannot be read. Injected so tests need no real container. */
 export type FileStamp = (path: string) => Promise<string | undefined>;
 export declare const nodeFileStamp: FileStamp;
@@ -18,12 +22,19 @@ export type InstallerDeps = {
     env: Record<string, string | undefined>;
     /** default: `node:fs` */
     fileSize?: FileSize;
+    /** the temp files of `devicectl` calls on a physical iPhone (default: node:fs) */
+    deviceIo?: DeviceIo;
+    /** sha256 of the cached apk for the Android identity check (default: `node:fs`) */
+    fileDigest?: FileDigest;
 };
-/** A device to install onto: iOS simulator udid / Android emulator serial. */
+/** A device to install onto: iOS simulator udid / Android emulator or phone serial. `physical`: a real phone (ABI check before installing). */
 export type InstallTarget = {
     platform: Platform;
     deviceId: string;
+    physical?: boolean;
 };
+/** A real iPhone / iPad: installed, probed and removed with `devicectl`, not `simctl`. */
+export declare const isPhoneIos: (target: InstallTarget) => boolean;
 /** `xcrun simctl install <udid> <app>` / `adb -s <serial> install -r <apk>`. */
 export declare function installArgv(target: InstallTarget, appPath: string, env: InstallerDeps["env"]): string[];
 /** `xcrun simctl get_app_container <udid> <bundleId>` / `adb -s <serial> shell pm path <bundleId>`. */
@@ -47,8 +58,9 @@ export declare function appIdentity(deps: InstallerDeps, appDir: string): Promis
  * Is the app on the device the cached `artifactPath` build? iOS: compare `appIdentity` of the
  * installed container with the cached `.app`; pass `installedDir` (the container `probeApp` already
  * found) to skip a second `simctl get_app_container`. Anything unreadable counts as a mismatch
- * (reinstall is the safe side). Android: not checked (always true) — warden's install record is
- * trusted there.
+ * (reinstall is the safe side). Android: the sha256 of the installed `base.apk` (`pm path` + the device's
+ * `sha256sum`) against the cached apk's. The install record is only a hint, never the proof: an emulator
+ * restored from a snapshot, or installed onto by another tool, keeps the record while the app differs.
  */
 export declare function appMatchesArtifact(deps: InstallerDeps, target: InstallTarget, bundleId: string, artifactPath: string, installedDir?: string): AsyncResult<boolean>;
 /** `xcrun simctl uninstall <udid> <bundleId>` / `adb -s <serial> uninstall <bundleId>`. */
@@ -60,6 +72,8 @@ export declare function uninstallArgv(target: InstallTarget, bundleId: string, e
 export declare function uninstallApp(deps: InstallerDeps, target: InstallTarget, bundleId: string): AsyncResult<void>;
 /** Install `appPath`, then confirm `bundleId` is present. */
 export declare function installApp(deps: InstallerDeps, target: InstallTarget, appPath: string, bundleId: string): AsyncResult<void>;
+/** ABI directories under `lib/` in `unzip -Z1` output; empty for a pure-Java APK. */
+export declare function apkAbis(entries: string): string[];
 /** `installApp`, keeping what the confirming probe found (iOS: the new bundle container, 17-7). */
 export declare function installAndProbe(deps: InstallerDeps, target: InstallTarget, appPath: string, bundleId: string): AsyncResult<InstalledApp>;
 /** Filesystem ops the iOS data wipe needs (injected; tests pass fakes). */

package/types/core/src/builds/kinds.d.ts

@@ -10,6 +10,23 @@ import type { AppFramework } from "./native-ids";
  */
 export type BuildKind = "dev" | "simulator" | "release";
 export declare const BUILD_KINDS: readonly ["dev", "simulator", "release"];
+/**
+ * What a build runs on, separate from its kind: `simulator` builds (every kind so far) run on simulators and
+ * emulators, `device` builds are signed for a physical iPhone. v1: only `dev` and `release` have a device build.
+ */
+export type BuildTarget = "simulator" | "device";
+/**
+ * A device-target build's identity: the signing `team` and a `salt` (the team, plus a hash of the bundle id
+ * override when `projects[].ios.device.bundleIdentifier` is set) that goes into the cache key and the cache path.
+ */
+export type DeviceTarget = {
+    team: string;
+    salt: string;
+};
+/** The device target of `project` signed by `team`: a changed team or bundle id override is a different build. */
+export declare function deviceTarget(project: Project, team: string): DeviceTarget;
+/** `project` with the bundle id a device build installs under (`projects[].ios.device.bundleIdentifier`, else its own). */
+export declare function withDeviceBundleId(project: Project): Project;
 /** The kind `warden e2e` installs when the suite's `app` names none. */
 export declare const DEFAULT_E2E_KIND: BuildKind;
 /** The kind `warden ui open` / `warden dev` use when no `--kind` is given. */
@@ -48,9 +65,10 @@ export declare function kindBuildCommand(kind: BuildKind, platform: Platform, fr
  * (`fingerprint.command`, `build.cache` and `build.prebuiltReactNative` still apply: they are not about the kind).
  * JS inputs: `kinds.<kind>.jsInputs`, else `DEFAULT_JS_INPUTS` (all tracked files but `ios/`, `android/`, `node_modules`).
  */
-export declare function resolveKind(project: Project, kind: BuildKind): KindSettings;
+export declare function resolveKind(project: Project, kind: BuildKind, device?: DeviceTarget): KindSettings;
 /**
  * `project` as `kind` builds it: the build commands, configuration and env of `resolveKind`, and `jsInputs` set only
- * when the kind's cache key covers the JS (`release`), so `runLocalBuild` / `computeCacheKey` run unchanged.
+ * when the kind's cache key covers the JS (`release`), so `runLocalBuild` / `computeCacheKey` run unchanged. With a
+ * `device` target the project builds for a physical iPhone: the signed `xcodebuild` command, the device bundle id.
  */
-export declare function projectForKind(project: Project, kind: BuildKind): Project;
+export declare function projectForKind(project: Project, kind: BuildKind, device?: DeviceTarget): Project;

package/types/core/src/builds/lock.d.ts

@@ -0,0 +1,38 @@
+import { type AsyncResult } from "../../../types/src/result";
+import { type PidAlive } from "../liveness";
+import type { Store } from "../store";
+import { type BuildResource, type Lease, type Owner, type Platform } from "../types";
+/** Lease key serialising work on one (project, platform, fingerprint). */
+export declare function buildLockKey(projectKey: string, platform: Platform, hash: string): string;
+/**
+ * Lease key serialising local builds in one checkout: a build writes the working tree (prebuild, Pods, build/), so two
+ * builds of any fingerprints in one `root` clobber each other, and a fingerprint read while one runs is of a half-written
+ * native dir. `root` should be a realpath, so two spellings of one checkout share it.
+ */
+export declare function buildTreeLockKey(root: string, platform: Platform): string;
+export declare function buildResource(key: string): BuildResource;
+export type BuildLockDeps = {
+    store: Store;
+    owner: Owner;
+    /** pid recorded on the lock — the lock lives while this process does */
+    pid: number;
+    now: () => number;
+    pidAlive: PidAlive;
+    sleep: (ms: number) => Promise<void>;
+    log?: (line: string) => void;
+    /** the one line logged when this starts waiting, given the holder (default: "another warden (…) is fetching/building this app — waiting") */
+    waitLine?: (holder: string) => string;
+    /** called with the holder's lease on every poll while another owner holds the lock (progress, log tailing) */
+    onWait?: (held: Lease) => void;
+    pollMs?: number;
+    waitMs?: number;
+    ttlMs?: number;
+};
+/**
+ * Run `fn` holding the build lease for `key`. While another live owner holds it, poll (up to
+ * `waitMs`); callers re-check the cache inside `fn`, so a waiter ends up with the holder's result
+ * instead of downloading/building again. The lease is always released.
+ */
+export declare function withBuildLock<T>(deps: BuildLockDeps, key: string, fn: () => AsyncResult<T>): AsyncResult<T>;
+/** Keys of build leases currently alive (prune never deletes these). */
+export declare function liveBuildLocks(store: Store, now: number, pidAlive: PidAlive): Set<string>;

package/types/core/src/builds/resolve.d.ts

@@ -41,10 +41,20 @@ export type EasStepOutcome = {
     kind: "miss";
     reason: string;
 };
+/** What the local build step produced: its own build, or (after waiting on the checkout) another warden's, from the cache. */
+export type BuildStepOutcome = {
+    kind: "built";
+    path: string;
+} | {
+    kind: "cached";
+    path: string;
+};
 /** What the device probe found: is the app there, and (iOS) its container so `matches` need not ask again. */
 export type InstalledApp = {
     present: boolean;
     container?: string;
+    /** a physical iPhone: the `CFBundleVersion` devicectl reports for the installed app */
+    version?: string;
 };
 /** Device half of the resolver — absent when only the artifact is wanted. */
 export type DeviceSteps = {
@@ -84,8 +94,8 @@ export type ResolveSteps = {
     flightKey?: string;
     /** EAS: download into the cache, or miss */
     eas?: () => AsyncResult<EasStepOutcome>;
-    /** local build into the cache; path */
-    build?: () => AsyncResult<string>;
+    /** local build into the cache (or the build another warden just made in this checkout) */
+    build?: () => AsyncResult<BuildStepOutcome>;
     log: (line: string) => void;
     /** progress: where this resolve is (see `AppPhase`) */
     onPhase?: (phase: AppPhase) => void;

package/types/core/src/conditions/conditions.config.d.ts

@@ -0,0 +1,117 @@
+import { type Result } from "../../../types/src/result";
+import { z } from "zod";
+import { type A11yCondition, type ClockCondition, type LocationCondition, type NetworkCondition, type NetworkPreset, type PermissionName, type PermissionState } from "./conditions.types";
+/** `network: { latencyMs, ... }`: the same fields as a `custom` network condition, without its `kind`. */
+declare const customNetworkSchema: z.ZodObject<{
+    latencyMs: z.ZodOptional<z.ZodNumber>;
+    jitterMs: z.ZodOptional<z.ZodNumber>;
+    downKbps: z.ZodOptional<z.ZodNumber>;
+    upKbps: z.ZodOptional<z.ZodNumber>;
+    lossPct: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+/**
+ * `conditions` (top level, or per `e2e.<suite>`): what every spec of the suite starts from. `network`, `location`
+ * and `clock` are applied before the app launches and put back after each spec, as are `permissions`, `locale`,
+ * `timezone` and `a11y`.
+ */
+export declare const conditionsConfigSchema: z.ZodObject<{
+    network: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        edge: "edge";
+        "3g": "3g";
+        "4g": "4g";
+        lte: "lte";
+        wifi: "wifi";
+        slow: "slow";
+        lossy: "lossy";
+        online: "online";
+        offline: "offline";
+    }>, z.ZodObject<{
+        latencyMs: z.ZodOptional<z.ZodNumber>;
+        jitterMs: z.ZodOptional<z.ZodNumber>;
+        downKbps: z.ZodOptional<z.ZodNumber>;
+        upKbps: z.ZodOptional<z.ZodNumber>;
+        lossPct: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>]>>;
+    location: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        "city-run": "city-run";
+        "city-bike": "city-bike";
+        freeway: "freeway";
+    }>, z.ZodObject<{
+        lat: z.ZodNumber;
+        lon: z.ZodNumber;
+        altM: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>]>>;
+    clock: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        at: z.ZodString;
+        frozen: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>, z.ZodObject<{
+        offset: z.ZodString;
+    }, z.core.$strict>]>>;
+    permissions: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        location: "location";
+        locationAlways: "locationAlways";
+        camera: "camera";
+        photos: "photos";
+        photosAdd: "photosAdd";
+        contacts: "contacts";
+        contactsLimited: "contactsLimited";
+        notifications: "notifications";
+        microphone: "microphone";
+        calendar: "calendar";
+        reminders: "reminders";
+        motion: "motion";
+        mediaLibrary: "mediaLibrary";
+        siri: "siri";
+    }> & z.core.$partial, z.ZodEnum<{
+        granted: "granted";
+        denied: "denied";
+        unset: "unset";
+    }>>>;
+    locale: z.ZodOptional<z.ZodString>;
+    timezone: z.ZodOptional<z.ZodString>;
+    a11y: z.ZodOptional<z.ZodObject<{
+        textSize: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            "extra-small": "extra-small";
+            small: "small";
+            medium: "medium";
+            large: "large";
+            "extra-large": "extra-large";
+            "extra-extra-large": "extra-extra-large";
+            "extra-extra-extra-large": "extra-extra-extra-large";
+            "accessibility-medium": "accessibility-medium";
+            "accessibility-large": "accessibility-large";
+            "accessibility-extra-large": "accessibility-extra-large";
+            "accessibility-extra-extra-large": "accessibility-extra-extra-large";
+            "accessibility-extra-extra-extra-large": "accessibility-extra-extra-extra-large";
+        }>, z.ZodNumber]>>;
+        boldText: z.ZodOptional<z.ZodBoolean>;
+        contrast: z.ZodOptional<z.ZodEnum<{
+            increased: "increased";
+            normal: "normal";
+        }>>;
+        reduceMotion: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ConditionsConfig = z.input<typeof conditionsConfigSchema>;
+/** What a spec's `device.network.set` takes: a condition, or its word. */
+export type NetworkInput = NetworkCondition | "online" | "offline" | NetworkPreset;
+/** A word, a custom shape (config) or a ready condition, as a `NetworkCondition`. */
+export declare function toNetworkCondition(input: NetworkInput | z.infer<typeof customNetworkSchema>): Result<NetworkCondition>;
+export type SuiteConditions = {
+    network?: NetworkCondition;
+    location?: LocationCondition;
+    clock?: ClockCondition;
+    permissions?: Partial<Record<PermissionName, PermissionState>>;
+    locale?: string;
+    timezone?: string;
+    a11y?: A11yCondition;
+};
+/** A config as conditions: shaped values, with a text size resolved. */
+export declare function normalizeConditions(config: ConditionsConfig): Result<{
+    conditions: SuiteConditions;
+}>;
+/** The suite's `conditions` over the top-level ones, per area; undefined when neither sets any. */
+export declare function mergeConditionsConfig(top: ConditionsConfig | undefined, own: ConditionsConfig | undefined): ConditionsConfig | undefined;
+/** `WARDEN_CONDITIONS`: the JSON of a suite's config, checked again on the spec side. */
+export declare function parseConditionsEnv(raw: string): Result<ConditionsConfig>;
+export {};

package/types/core/src/conditions/conditions.d.ts

@@ -0,0 +1,22 @@
+import { type Result } from "../../../types/src/result";
+import type { Store } from "../store";
+import { type ConditionArea, type ConditionRecord, type ConditionValues, type OwnedProcess } from "./conditions.types";
+export type ConditionRow = {
+    area: ConditionArea;
+    json: string;
+    owned: string;
+    set_at: number;
+};
+export declare function toConditionRecord(row: ConditionRow): ConditionRecord;
+/**
+ * Persist what a lease has set on its device so release, gc and a crashed process can undo it. One
+ * slot per area: recording again replaces the value. `owned` (processes undo must stop) is kept as
+ * is when omitted and replaced when given — a caller swapping a proxy kills the old one itself.
+ */
+export declare function recordCondition<A extends ConditionArea>(store: Store, leaseId: string, area: A, value: ConditionValues[A], now: number, owned?: readonly OwnedProcess[]): Result<ConditionRecord>;
+/** Forget one area of a lease; false when it was not set. */
+export declare function clearCondition(store: Store, leaseId: string, area: ConditionArea): boolean;
+/** Forget every area of a lease; returns how many were set. */
+export declare function clearConditions(store: Store, leaseId: string): number;
+/** What a lease currently has set, in `CONDITION_AREAS` order. */
+export declare function activeConditions(store: Store, leaseId: string): ConditionRecord[];

package/types/core/src/conditions/conditions.types.d.ts

@@ -0,0 +1,141 @@
+export type NetworkPreset = "edge" | "3g" | "4g" | "lte" | "wifi" | "slow" | "lossy";
+export type NetworkCondition = {
+    kind: "online";
+} | {
+    kind: "offline";
+} | {
+    kind: "preset";
+    preset: NetworkPreset;
+} | {
+    kind: "custom";
+    latencyMs?: number;
+    jitterMs?: number;
+    downKbps?: number;
+    upKbps?: number;
+    lossPct?: number;
+} | {
+    kind: "flap";
+    upMs: number;
+    downMs: number;
+    jitterPct?: number;
+    base?: NetworkCondition;
+};
+/** A per-host fault the lease's shaping proxy applies; `match` is a host glob. */
+export type HostFault = {
+    match: string;
+    action: {
+        kind: "status";
+        code: number;
+    } | {
+        kind: "reset";
+    } | {
+        kind: "delay";
+        ms: number;
+    } | {
+        kind: "blackhole";
+    };
+};
+export type LatLon = {
+    lat: number;
+    lon: number;
+};
+export type LocationScenario = "city-run" | "city-bike" | "freeway";
+export type LocationCondition = {
+    kind: "point";
+    lat: number;
+    lon: number;
+    altM?: number;
+} | {
+    kind: "route";
+    points: readonly LatLon[];
+    speedMps?: number;
+    intervalS?: number;
+    loop?: boolean;
+} | {
+    kind: "gpx";
+    path: string;
+    speedMps?: number;
+} | {
+    kind: "scenario";
+    name: LocationScenario;
+} | {
+    kind: "clear";
+};
+export type ClockCondition = {
+    kind: "real";
+} | {
+    kind: "offset";
+    ms: number;
+} | {
+    kind: "fixed";
+    at: string;
+} | {
+    kind: "frozen";
+    at: string;
+};
+export type PermissionState = "granted" | "denied" | "unset";
+/** The permission names a spec, `warden ui permission` and a suite's `conditions.permissions` use; each maps to platform services in the driver. */
+export declare const PERMISSION_NAMES: readonly ["location", "locationAlways", "camera", "photos", "photosAdd", "contacts", "contactsLimited", "notifications", "microphone", "calendar", "reminders", "motion", "mediaLibrary", "siri"];
+export type PermissionName = (typeof PERMISSION_NAMES)[number];
+export declare const isPermissionName: (v: string) => v is PermissionName;
+/** Runtime permission grants applied to apps on the device. */
+export type PermissionCondition = {
+    grants: readonly {
+        bundleId: string;
+        permission: PermissionName;
+        state: PermissionState;
+    }[];
+};
+/** Locale applies to one app (`bundleId`); timezone to the device (Android) or the next launch (iOS). */
+export type LocaleCondition = {
+    locale?: string;
+    timezone?: string;
+    bundleId?: string;
+    /** Android: the timezone before the first change, put back on release */
+    previousTimezone?: string;
+};
+/** A named text size (iOS content size categories) or a font scale where 1 is the default. */
+export type TextSize = (typeof TEXT_SIZE_NAMES)[number] | number;
+export declare const TEXT_SIZE_NAMES: readonly ["extra-small", "small", "medium", "large", "extra-large", "extra-extra-large", "extra-extra-extra-large", "accessibility-medium", "accessibility-large", "accessibility-extra-large", "accessibility-extra-extra-large", "accessibility-extra-extra-extra-large"];
+export type A11yCondition = {
+    textSize?: TextSize;
+    /** resolved font scale of `textSize` (1 = default) */
+    fontScale?: number;
+    reduceMotion?: boolean;
+    boldText?: boolean;
+    contrast?: "increased" | "normal";
+};
+/** `cosmetic`: the status bar says so, the OS and the app still see the real battery (iOS simulators) */
+export type BatteryCondition = {
+    level?: number;
+    charging?: boolean;
+    cosmetic?: boolean;
+};
+/** Everything a lease can have set on its device, one slot per area. */
+export type ConditionValues = {
+    network: NetworkCondition;
+    location: LocationCondition;
+    clock: ClockCondition;
+    permission: PermissionCondition;
+    locale: LocaleCondition;
+    a11y: A11yCondition;
+    battery: BatteryCondition;
+};
+export type ConditionArea = keyof ConditionValues;
+/** Display/iteration order; also the order undo resets areas in. */
+export declare const CONDITION_AREAS: readonly ConditionArea[];
+/** A process warden spawned to hold a condition (shaping proxy, route ticker); undo kills it. */
+export type OwnedProcess = {
+    kind: "pid";
+    pid: number;
+};
+/** One active condition on a lease, discriminated by `area`. */
+export type ConditionRecord = {
+    [A in ConditionArea]: {
+        area: A;
+        value: ConditionValues[A];
+        /** processes undo must stop */
+        owned: readonly OwnedProcess[];
+        setAt: number;
+    };
+}[ConditionArea];

package/types/core/src/conditions/inject-state.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The state file an iOS app launched with `libwarden-inject.dylib` watches (offline flag, wall-clock offset /
+ * freeze). The e2e driver owns the full format (`packages/e2e/src/driver/ios/inject.ts`); core only knows where it
+ * lives and how to put it back to neutral on release, so a still-running injected app stops seeing the lease's
+ * offline or shifted clock.
+ */
+export declare function injectStatePath(wardenHome: string, udid: string): string;
+/**
+ * Write `{ seq: previous + 1, offline: false, clockOffsetMs: 0 }` (no freeze) when a state file exists; the dylib
+ * applies any higher `seq`. No file = no injected app was ever launched on the device: nothing to do.
+ * Returns an error message, or undefined.
+ */
+export declare function neutralizeInjectState(path: string): string | undefined;

package/types/core/src/conditions/launch-settings.d.ts

@@ -0,0 +1,14 @@
+/**
+ * What the next launch of an app on an iOS simulator should carry: a simulator has no per-device timezone or
+ * locale, so both ride on the app's launch (`TZ` env, `-AppleLanguages` / `-AppleLocale` args). `warden ui` sets
+ * them in one process and launches in another, so they are staged in a file per device; release removes it.
+ */
+export type LaunchSettings = {
+    timezone?: string;
+    locale?: string;
+};
+export declare function launchSettingsPath(wardenHome: string, udid: string): string;
+/** The staged settings; none (or an unreadable file) is `{}`. */
+export declare function readLaunchSettings(path: string): LaunchSettings;
+/** Replace the staged settings; an empty one removes the file. Returns an error message, or undefined. */
+export declare function writeLaunchSettings(path: string, settings: LaunchSettings): string | undefined;

package/types/core/src/conditions/network.presets.d.ts

@@ -0,0 +1,42 @@
+import type { NetworkCondition, NetworkPreset } from "./conditions.types";
+/**
+ * One table for every layer that applies a network condition: the Android emulator console (`emu network
+ * speed|delay`, COND-3), the per-lease shaping proxy (COND-4) and the iOS per-app routing (COND-5).
+ *
+ * Shaping units: `latencyMs` is the added round-trip time, `jitterMs` the +/- spread on it, kbps are
+ * kilobits per second (0 = unlimited), `lossPct` is 0-100. The emulator console's `delay` is per packet, so
+ * its `min:max` is half the round trip, widened by the jitter.
+ *
+ * Sources: Apple Network Link Conditioner profiles (edge, 3g, lte, wifi, lossy = "Very Bad Network"),
+ * Chrome DevTools "Slow 3G" (400 kbps both ways, 2000 ms), WebPageTest "4G" (9 Mbps, 170 ms RTT).
+ */
+export type NetworkShaping = {
+    latencyMs: number;
+    jitterMs: number;
+    downKbps: number;
+    upKbps: number;
+    lossPct: number;
+};
+/** Arguments for `adb emu network speed <speed>` and `... delay <delay>`. */
+export type EmuNetwork = {
+    speed: string;
+    delay: string;
+};
+export type NetworkPresetSpec = {
+    emu: EmuNetwork;
+    shaping: NetworkShaping;
+};
+export declare const NETWORK_PRESET_NAMES: readonly NetworkPreset[];
+export declare const NETWORK_PRESETS: Readonly<Record<NetworkPreset, NetworkPresetSpec>>;
+/** What a condition means for a device: no network at all, or shaped (all zeros = unshaped) with the emulator args. */
+export type NetworkPlan = {
+    online: false;
+} | ({
+    online: true;
+} & NetworkPresetSpec);
+/**
+ * The effective parameters of a condition. `custom` names only what it changes (the rest is unshaped, a
+ * direction left out takes the other's rate for the emulator); `flap` resolves to its up phase, because the
+ * scheduler (COND-6) drives the transitions as plain online/offline conditions.
+ */
+export declare function resolveNetwork(condition: NetworkCondition): NetworkPlan;

package/types/core/src/conditions/text-size.d.ts

@@ -0,0 +1,19 @@
+import { type Result } from "../../../types/src/result";
+import { TEXT_SIZE_NAMES, type TextSize } from "./conditions.types";
+/** Approximate font scale of each iOS content size category (UIFontMetrics body text; 1 = `large`, the default). */
+export declare const TEXT_SIZE_SCALE: Record<(typeof TEXT_SIZE_NAMES)[number], number>;
+/** The largest `font_scale` Android's own settings offer; asking for more is clamped to it. */
+export declare const ANDROID_MAX_FONT_SCALE = 2;
+export declare const ANDROID_MIN_FONT_SCALE = 0.5;
+export type ResolvedTextSize = {
+    /** iOS content size category (the nearest one for a number) */
+    category: (typeof TEXT_SIZE_NAMES)[number];
+    /** font scale (the category's for a name) */
+    scale: number;
+};
+/** A name or a scale as both: the category iOS needs and the scale Android needs. */
+export declare function resolveTextSize(size: TextSize): Result<ResolvedTextSize>;
+/** Android's `font_scale` for `scale`, clamped to what the platform takes. */
+export declare const androidFontScale: (scale: number) => number;
+/** The part of an a11y request the platform applied (a skipped setting is not on the device, so not recorded). */
+export declare function appliedA11y<T extends object>(op: T, applied: readonly string[]): Partial<T>;

package/types/core/src/golden/android-biometrics.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Android fingerprint enrollment for the golden build emulator: set a screen-lock PIN, open the system
+ * enrollment wizard, answer its screens (PIN entry, Next/Agree/Done) and present the virtual finger until
+ * `dumpsys fingerprint` reports one enrolled. Slow (tens of seconds), so it runs once in the snapshot build
+ * and claims start enrolled. Idempotent: an already enrolled device is left alone. Emulator serials only.
+ */
+import { type AsyncResult } from "../../../types/src/result";
+import type { Exec } from "../exec";
+/**
+ * Whether `dumpsys fingerprint` lists an enrolled fingerprint: the JSON `"prints":[{"id":0,"count":N,…}]` of Android 10+
+ * (`count` = fingerprints enrolled for that user) or the older `Enrolled fingerprints: N` / `prints: N` lines.
+ */
+export declare function parseFingerprintEnrolled(dump: string): boolean;
+export type TapTarget = {
+    label: string;
+    x: number;
+    y: number;
+};
+/** Centre of the first wizard button in a `uiautomator dump`. */
+export declare function findTapTarget(xml: string): TapTarget | undefined;
+/** The lock-screen credential entry the wizard asks before it starts. */
+export declare function isPinEntry(xml: string): boolean;
+export type EnrollDeps = {
+    exec: Exec;
+    sleep: (ms: number) => Promise<void>;
+    /** the adb binary (`androidTools(env).adb`) */
+    adb: string;
+    /** wizard rounds before giving up (default 60) */
+    maxSteps?: number;
+    /** pause after each round (default 700 ms) */
+    stepMs?: number;
+};
+export declare function enrollFingerprint(deps: EnrollDeps, serial: string): AsyncResult<{
+    alreadyEnrolled: boolean;
+}>;

package/types/core/src/ios-runner/classify.d.ts

@@ -0,0 +1,7 @@
+import type { RunnerBuildError } from "./runner-build.types";
+/** `Unlock Chris's iPhone to Continue`: xcodebuild waits for the passcode and never says it is locked any other way. */
+export declare const UNLOCK_LINE: RegExp;
+/** The known failure in xcodebuild's / devicectl's output, or undefined for one warden has no fix for. */
+export declare function classifyRunnerOutput(text: string): RunnerBuildError | undefined;
+/** The last `lines` lines of the output: what `build_failed` shows when nothing classifies. */
+export declare function outputTail(text: string, lines?: number): string;