@delacour/warden-e2e 0.6.0 → 0.8.0

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/camera-mode.d.ts

@@ -0,0 +1,17 @@
+import { type CameraFacing } from "./conditions/conditions.types";
+/**
+ * Which cameras of an Android `+cam` emulator play a video: facing → the video file's name in the camera dir
+ * (`back.mp4`). A facing left out plays `<facing>.png`. The source kind is fixed when the emulator launches, so
+ * this file records what the RUNNING emulator was launched with; the next launch reads it.
+ */
+export type CameraMode = Partial<Record<CameraFacing, string>>;
+export declare function cameraModePath(dir: string): string;
+/** The recorded mode; a missing or unreadable file is all-image. */
+export declare function readCameraMode(dir: string): CameraMode;
+/** Record `mode` atomically; an all-image mode removes the file. */
+export declare function writeCameraMode(dir: string, mode: CameraMode): void;
+export declare function clearCameraMode(dir: string): void;
+export declare function usesVideo(mode: CameraMode): boolean;
+export declare function sameCameraMode(a: CameraMode, b: CameraMode): boolean;
+/** The emulator's `-camera-back` / `-camera-front` values for `mode`. */
+export declare function cameraSources(dir: string, mode: CameraMode): Record<CameraFacing, string>;

package/types/core/src/camera-placeholder.d.ts

@@ -0,0 +1,9 @@
+/** A 64x48 neutral grey PNG: what a camera emulator's cameras show until a feed is set. */
+export declare const PLACEHOLDER_PNG: Buffer<ArrayBuffer>;
+/**
+ * Put a device's feeds back to the placeholders: both PNGs rewritten atomically (temp + rename, the emulator may be
+ * reading), the staged videos and `mode.json` removed. The emulator itself keeps whatever source it launched with.
+ */
+export declare function resetCameraFeeds(dir: string): void;
+/** Seed `back.png` and `front.png` in `dir` with the grey placeholder, leaving any existing file alone. */
+export declare function seedCameraPlaceholders(dir: string): void;

package/types/core/src/camera-profile.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Camera profiles. An Android profile with `camera: true` is a different device identity from the same profile
+ * without it: the emulator's camera source is fixed at launch (`-camera-back imagefile:…`), so a camera emulator
+ * is never reused as a plain one. The identity is the profile plus `+cam`, after `+bio` when both apply
+ * (`<avd>+bio+cam`); callers that split `+bio` strip `+cam` first.
+ */
+export declare const CAMERA_PROFILE_SUFFIX = "+cam";
+export declare function cameraProfile(profile: string, camera: boolean): string;
+export declare function splitCameraProfile(profile: string): {
+    profile: string;
+    camera: boolean;
+};

package/types/core/src/claim-errors.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The machine codes a failed device claim carries, with the exit code the CLI returns for each and a short fix.
+ * A claim error travels as a string (`Result<…, string>`) through every claim caller, so the code rides at its
+ * front (`NO_DEVICE: …`, `NO_CAPACITY[ram-budget]: …`) and `parseClaimError` reads it back where it is reported.
+ */
+/** Why the host has no room for the boots a claim needs. */
+export type CapacityReason = "ram-budget" | "cpu-budget" | "memory-pressure" | "host-load";
+export type ClaimErrorCode = "QUEUE_TIMEOUT" | "NO_CAPACITY" | "NO_DEVICE" | "REQUESTER_LIMIT" | "RUNTIME_MISSING" | "HEALTH_FAILED" | "LEASE_LOST";
+/** What a claim error says: its code, and for `NO_CAPACITY` which resource ran out. */
+export type ClaimErrorKind = {
+    code: "NO_CAPACITY";
+    capacityReason: CapacityReason;
+} | {
+    code: Exclude<ClaimErrorCode, "NO_CAPACITY">;
+};
+export type ClaimErrorEntry = {
+    exit: number;
+    hint: string;
+};
+/**
+ * Exit codes 5-11 are claim failures; 1 stays the generic failure, 2 someone else's device / an ambiguous pick,
+ * 3 a missing tool, 4 a stale ref, 124 a timed-out job and 130 an interrupt.
+ */
+export declare const CLAIM_ERRORS: Record<ClaimErrorCode, ClaimErrorEntry>;
+/** `NO_DEVICE: <message>` / `NO_CAPACITY[ram-budget]: <message>`. */
+export declare function claimError(kind: ClaimErrorKind, message: string): string;
+/** A claim error read back from its message: the code, its exit code and hint, and the message without the tag. */
+export type ParsedClaimError = ClaimErrorKind & ClaimErrorEntry & {
+    message: string;
+};
+/** The coded claim error at the front of `error`, or undefined for an uncoded failure. */
+export declare function parseClaimError(error: string): ParsedClaimError | undefined;
+/** Is this provider error a missing runtime / AVD (`RUNTIME_MISSING`)? */
+export declare const isRuntimeMissing: (error: string) => boolean;

package/types/core/src/conditions/a11y-keys.d.ts

@@ -0,0 +1,45 @@
+import type { A11yCondition } from "./conditions.types";
+/**
+ * Accessibility settings that live in `defaults` / `settings` rather than `simctl ui` or `font_scale`. Shared by the
+ * e2e driver (apply) and condition undo (reset), so the two can never name different keys.
+ */
+export declare const IOS_A11Y_DOMAIN = "com.apple.Accessibility";
+/** Condition field to the `com.apple.Accessibility` key it sets on a simulator (applied live, no relaunch). */
+export declare const IOS_A11Y_DEFAULTS: {
+    readonly reduceMotion: "ReduceMotionEnabled";
+    readonly boldText: "EnhancedTextLegibilityEnabled";
+    readonly reduceTransparency: "EnhancedBackgroundContrastEnabled";
+    readonly buttonShapes: "ButtonShapesEnabled";
+    readonly differentiateWithoutColor: "DifferentiateWithoutColor";
+    readonly onOffLabels: "IncreaseButtonLegibilityEnabled";
+    readonly screenReader: "VoiceOverTouchEnabled";
+};
+export type IosDefaultsField = keyof typeof IOS_A11Y_DEFAULTS;
+export declare const IOS_DEFAULTS_FIELDS: IosDefaultsField[];
+/**
+ * One `simctl spawn <udid> defaults write` per entry. Not batched through `sh -c`: `simctl spawn` runs the
+ * simulator's own `defaults` only when it resolves the bare name itself (verified on iOS 26: `/usr/bin/defaults` and a
+ * shell both fail with "Could not write domain" / a dyld abort).
+ */
+export declare function iosDefaultsWriteArgvs(udid: string, entries: readonly (readonly [IosDefaultsField, boolean])[]): string[][];
+/** `defaults delete` per field; a key that is not there exits 1, which the caller must tolerate (`iosDefaultsMissing`). */
+export declare function iosDefaultsDeleteArgvs(udid: string, fields: readonly IosDefaultsField[]): string[][];
+/**
+ * `defaults delete` of a key that is not there exits 1: "does not exist" (older Xcode), "Could not find key" (Xcode
+ * 27), or "Domain not found" when the whole domain is empty. Already as wanted.
+ */
+export declare const iosDefaultsMissing: (stderr: string) => boolean;
+/** The defaults-backed fields a recorded condition holds, i.e. the keys warden wrote (and may delete). */
+export declare function iosDefaultsFields(record: A11yCondition): IosDefaultsField[];
+/** `settings put` argvs (no `adb shell` prefix) that undo the Android-only fields a recorded condition holds. */
+export declare function androidA11yResets(record: A11yCondition): string[][];
+/** Android setting names TalkBack mode writes. */
+export declare const ANDROID_SERVICES_KEY = "enabled_accessibility_services";
+export declare const ANDROID_A11Y_ENABLED_KEY = "accessibility_enabled";
+/** The `settings` argv (no `adb shell` prefix) that sets a secure key to `value`, or deletes it when it was unset. */
+export declare function androidSecureRestoreArgv(key: string, value: string | null): string[];
+/**
+ * TalkBack mode on Android: put back the accessibility services and master switch that were there before. Nothing
+ * when the record has no `screenReaderPrevious` (warden did not turn a screen reader on, so it has nothing to restore).
+ */
+export declare function androidScreenReaderResets(record: A11yCondition): string[][];

package/types/core/src/conditions/camera-media.d.ts

@@ -0,0 +1,30 @@
+import { type Result } from "../../../types/src/result";
+import type { CameraFacing, CameraFeed } from "./conditions.types";
+export type CameraMediaKind = CameraFeed["kind"];
+export type CameraMediaExt = "png" | "jpg" | "heic" | "mp4" | "mov";
+export type CameraMediaError = {
+    code: "E_CAMERA_NOT_FOUND" | "E_CAMERA_MEDIA";
+    message: string;
+};
+/** The kind of a camera asset from its leading bytes (the extension is ignored): png / jpg / heic image, mp4 / mov video. */
+export declare function sniffCameraMedia(path: string): Result<{
+    kind: CameraMediaKind;
+    ext: CameraMediaExt;
+}, CameraMediaError>;
+/** Where a device's staged camera feeds live; the simulator / emulator reads them straight off the host filesystem. */
+export declare function cameraFeedDir(wardenHome: string, udid: string): string;
+export type StageCameraFeedInput = {
+    wardenHome: string;
+    udid: string;
+    facing: CameraFacing;
+    source: string;
+    /** video only: play again from the start at the end (default true where the caller has no opinion) */
+    loop: boolean;
+};
+/**
+ * Copy a camera asset to `<camera dir>/<facing>-<content hash>.<ext>`. The name changes with the content, so a
+ * consumer that compares paths (the iOS dylib, the Android swap) sees every new asset as new.
+ */
+export declare function stageCameraFeed(input: StageCameraFeedInput): Result<CameraFeed, CameraMediaError>;
+/** Remove every staged feed of a device (release / reset). Missing dir is fine. */
+export declare function clearCameraFeeds(wardenHome: string, udid: string): void;

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

@@ -0,0 +1,141 @@
+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>;
+/**
+ * A suite's `camera` key: the asset each facing plays from the first `app.open()` on. A path, or `{ path, loop }`
+ * (`loop` applies to a video, default true). Paths are relative to the config file.
+ */
+export declare const cameraConfigSchema: z.ZodObject<{
+    back: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        path: z.ZodString;
+        loop: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>]>>;
+    front: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        path: z.ZodString;
+        loop: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>]>>;
+}, z.core.$strict>;
+export type CameraConfig = z.input<typeof cameraConfigSchema>;
+/** A suite's camera with absolute paths and a loop flag per facing: what `WARDEN_CAMERA_FEEDS` carries. */
+export type CameraSuiteFeeds = Partial<Record<"back" | "front", {
+    path: string;
+    loop: boolean;
+}>>;
+/** `camera` as absolute paths (against `baseDir`, the config file's directory) with `loop` defaulted to true. */
+export declare function resolveCameraConfig(config: CameraConfig, baseDir: string): CameraSuiteFeeds;
+/** `WARDEN_CAMERA_FEEDS`: the JSON of a suite's resolved camera, checked again on the spec side. */
+export declare function parseCameraFeedsEnv(raw: string): Result<CameraSuiteFeeds>;
+/** 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,171 @@
+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";
+    reduceTransparency?: boolean;
+    buttonShapes?: boolean;
+    differentiateWithoutColor?: boolean;
+    onOffLabels?: boolean;
+    highContrastText?: boolean;
+    colorInversion?: boolean;
+    screenReader?: boolean;
+    /**
+     * Android TalkBack: the `enabled_accessibility_services` and `accessibility_enabled` values (`null` = unset) the
+     * device had before warden turned TalkBack on, so undo puts back exactly those and never drops a service warden
+     * did not add. Present only while `screenReader` is true on Android.
+     */
+    screenReaderPrevious?: {
+        services: string | null;
+        enabled: string | null;
+    };
+};
+/** `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;
+};
+export type CameraFacing = "back" | "front";
+export declare const CAMERA_FACINGS: readonly CameraFacing[];
+/** A staged asset the simulated camera plays; `path` is the staged copy under the device's camera dir. */
+export type CameraFeed = {
+    kind: "image";
+    path: string;
+} | {
+    kind: "video";
+    path: string;
+    loop: boolean;
+};
+/** The simulated camera per facing; a facing left out has no camera (iOS) or the emulator's default (Android). */
+export type CameraCondition = Partial<Record<CameraFacing, CameraFeed>>;
+/** 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;
+    camera: CameraCondition;
+};
+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, camera: {} }` (no freeze, no camera feeds) 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;