@delacour/warden-e2e 0.1.1 → 0.2.0

package/types/core/src/providers/android.d.ts

@@ -115,6 +115,14 @@ export declare const GOLDEN_PORT_LABEL = "emulator golden ";
  * and unverified on a device; a successful load logs `Successfully loaded snapshot …`, which does not match.
  */
 export declare function snapshotLoadFailed(log: string): boolean;
+/**
+ * Global settings applied after every boot. On a fresh playstore image the first `adb install` can pop a Play
+ * Protect consent dialog (a GMS activity the e2e alert detector cannot classify), and every adb install otherwise
+ * waits on the GMS verifier (up to the 10 s verifier_timeout). Warden's emulators run `-read-only -no-snapshot-save`,
+ * so /data changes are a per-boot overlay and must be re-applied on each boot.
+ */
+export declare const BOOT_SETTINGS: ReadonlyArray<readonly [key: string, value: string]>;
+export declare function bootSettingsCommand(): string;
 /**
  * Android emulators on `adb` + `emulator`. Warden never boots an existing emulator — it launches a
  * new headless `-read-only` instance of an AVD (so one AVD backs many emulators) on a leased even

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

@@ -1,6 +1,6 @@
 import { Database } from "bun:sqlite";
 import { type PidAlive } from "./liveness";
-import type { Lease, Owner, Platform, Resource } from "./types";
+import type { Lease, Owner, Platform, QueueEntry, Resource } from "./types";
 /** `$WARDEN_HOME`, else `~/.warden`. */
 export declare function wardenHome(env?: Record<string, string | undefined>): string;
 export declare function defaultDbPath(env?: Record<string, string | undefined>): string;
@@ -9,6 +9,8 @@ export declare function defaultDbPath(env?: Record<string, string | undefined>):
  * edit an entry that has shipped.
  */
 export declare const MIGRATIONS: readonly string[];
+/** A queued claim that has not refreshed within this long is dead (its waiter polls every few seconds). */
+export declare const QUEUE_TTL_MS = 60000;
 export declare function ownerKey(owner: Owner): string;
 export type NewLease = {
     resource: Resource;
@@ -17,6 +19,7 @@ export type NewLease = {
     label?: string;
     pid?: number;
     bootedByOwner?: boolean;
+    shared?: boolean;
 };
 /** A device warden created (sim) or launched (emulator). */
 export type DeviceRecord = {
@@ -45,6 +48,8 @@ export declare class Store {
     /** Run `fn` under `BEGIN IMMEDIATE` (write lock taken up front). Nested calls join the outer txn. */
     transaction<T>(fn: () => T): T;
     insertLease(input: NewLease, now: number): Lease;
+    /** Mark leases shared (`Lease.shared`): `warden dev` on the device leases it just claimed. */
+    markShared(ids: readonly string[]): void;
     /** Record that this lease's owner booted its device (claim boot/create, hook saw it shut down). */
     markBootedByOwner(id: string): void;
     /** Record the process a lease now lives with (an emulator launched after its port was leased). */
@@ -65,6 +70,15 @@ export declare class Store {
     heartbeat(ids: readonly string[], now: number, periodMs?: number): number;
     /** Delete leases that are not alive (`isLeaseAlive`: pid dead AND heartbeat expired). Returns reclaimed ids. */
     reclaimStale(now: number, pidAlive: PidAlive): string[];
+    /** Insert a queue row; an existing id keeps its `enqueuedAt` (queue age) and updates the rest. */
+    enqueue(entry: QueueEntry): QueueEntry;
+    /** Stamp `heartbeat_at`; false when the row is gone (reclaimed or dequeued). */
+    refreshQueue(id: string, now: number): boolean;
+    dequeue(id: string): boolean;
+    /** Raw insertion order (`enqueued_at`, id); use `queueOrder` for admission order. */
+    listQueue(): QueueEntry[];
+    /** Delete queue rows whose waiter is gone: pid dead, or heartbeat older than `QUEUE_TTL_MS`. */
+    reclaimStaleQueue(now: number, pidAlive: PidAlive): string[];
     recordDevice(device: Omit<DeviceRecord, "createdAt" | "lastUsedAt">, now: number): void;
     listDevices(platform?: Platform): DeviceRecord[];
     touchDevice(platform: Platform, id: string, now: number): void;

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

@@ -50,6 +50,11 @@ export type Lease = {
      * record their own `pid`). With a pid, a dead pid makes the lease stale after `LOST_HEARTBEATS` periods.
      */
     heartbeatMs?: number;
+    /**
+     * The holding process (`warden dev`) lets its owner's other processes drive the device beside it: `warden ui`
+     * attaches to it instead of refusing with `device_busy`, and never releases it. Other owners still see it as foreign.
+     */
+    shared?: boolean;
 };
 export type DeviceState = "booted" | "shutdown" | "booting";
 /** A device as seen by a provider, enriched with warden's own bookkeeping. */
@@ -104,3 +109,18 @@ export declare function describeOwner(owner: Owner): string;
 /** Owner location for messages: `repo/worktree` when known. */
 export declare function ownerLocation(owner: Owner): string | undefined;
 export declare function sameOwner(a: Owner, b: Owner): boolean;
+/** A claim waiting for host capacity to boot devices (`boot_queue` row). */
+export type QueueEntry = {
+    id: string;
+    platform: Platform;
+    profile: string;
+    /** capacity units the boots need */
+    units: number;
+    /** numeric base priority (see `PRIORITY` in queue.ts); aging adds to it */
+    priority: number;
+    enqueuedAt: number;
+    heartbeatAt: number;
+    owner: Owner;
+    label?: string;
+    pid?: number;
+};

package/types/e2e/src/app.d.ts

@@ -6,7 +6,7 @@ import { type Locator } from "./screen/locator";
 export type OpenWaitUntil = {
     /** a locator made by `screen` that is visible once the app's first screen is up */
     until: Locator;
-    /** how long `until` gets to show; default the assertion timeout (`WARDEN_ASSERTION_TIMEOUT_MS`) */
+    /** how long `until` gets to show; default the assertion timeout (`WARDEN_E2E_ASSERTION_TIMEOUT`) */
     timeout?: number;
 };
 export type OpenOptions = {

package/types/e2e/src/device.d.ts

@@ -3,6 +3,7 @@ import type { Driver, Orientation } from "./driver/driver.types";
 import { type SettleDetail } from "./driver/settle";
 import type { E2eEnv } from "./env";
 import { type Clock, type FixtureSession } from "./fixture-session";
+import { type DevicePerf, type PerfExec } from "./perf/device-perf";
 import type { Locator } from "./screen/locator";
 export type AlertAction = "accept" | "dismiss" | {
     button: string;
@@ -72,11 +73,18 @@ export type Device = {
      * `WARDEN_METRO_URL` (a release build). The first access starts attaching, so console capture begins there.
      */
     readonly devtools: DeviceDevtools | undefined;
+    /**
+     * Perf profiling of the app (`warden perf` over the CLI that started the run): `start`, `mark`, then `stop` for the
+     * typed report. The report is copied under the attempt's `perf/`; budgets from `warden.config.ts` fail `stop`.
+     */
+    readonly perf: DevicePerf;
 };
 export type DeviceDeps = {
     session: FixtureSession;
     driver: Driver;
     env: E2eEnv;
     clock?: Clock;
+    /** runs `warden …` for `device.perf`; default spawns `WARDEN_BIN` */
+    perfExec?: PerfExec;
 };
-export declare function createDevice({ session, driver, env, clock }: DeviceDeps): Device;
+export declare function createDevice({ session, driver, env, clock, perfExec }: DeviceDeps): Device;

package/types/e2e/src/devtools/native-log.d.ts

@@ -0,0 +1,50 @@
+import type { Exec } from "../../../core/src/exec";
+export declare const NATIVE_LOG = "native.log";
+/** The app a failing attempt ran: `native.log` and crash reports are read for it only. */
+export type NativeTarget = {
+    platform: "ios";
+    udid: string;
+    bundleId: string;
+} | {
+    platform: "android";
+    serial: string;
+    pkg: string;
+};
+export type CrashReport = {
+    name: string;
+    mtimeMs: number;
+};
+/** Filesystem seam: where crash reports are read from and `native.log` goes. */
+export type NativeFs = {
+    listReports(dir: string): CrashReport[];
+    copy(from: string, to: string): void;
+    write(path: string, text: string): void;
+};
+export type NativeLogDeps = {
+    exec: Exec;
+    /** path of the `adb` binary */
+    adb: string;
+    fs: NativeFs;
+    /** `~/Library/Logs/DiagnosticReports` */
+    reportsDir: string;
+};
+export type NativeLogWindow = {
+    /** the attempt's directory; files are written into it */
+    dir: string;
+    /** when the attempt started (ms since epoch) */
+    sinceMs: number;
+    nowMs: number;
+    timeoutMs?: number;
+};
+export type NativeCapture = {
+    files: string[];
+    problems: string[];
+};
+export declare function realNativeFs(): NativeFs;
+export declare function realNativeLogDeps(exec: Exec, adb: string): NativeLogDeps;
+/**
+ * `native.log` (and iOS `.ips` crash reports) for a failed attempt, read after the fact: iOS
+ * `simctl spawn log show` for the app's process over the attempt's window, Android `logcat -d` for its pid
+ * plus the crash buffer. Reading afterwards needs no stream to start, stop or leak. Never throws.
+ */
+export declare function captureNativeLog(target: NativeTarget, deps: NativeLogDeps, win: NativeLogWindow): Promise<NativeCapture>;

package/types/e2e/src/driver/android/uiad-backend.d.ts

@@ -5,7 +5,7 @@ import type { Clock } from "./android-device";
 import { type UiadClient } from "./uiad-client";
 import { launchUiad, type PushDex } from "./uiad-device";
 /**
- * The driver's hold on `warden-uiad`: started when the first call that can use it arrives (a flow that only opens
+ * The driver's hold on `warden-uiad`: started when the first call that can use it arrives (a spec that only opens
  * links never pays for it), reused for every call after, and given up on, for this driver, when it cannot be made to
  * work. "Given up" means the driver goes on with `uiautomator dump` and `input`: the server is an accelerator, never a
  * requirement. The one failure that is not answered with a fallback is a busy UiAutomation slot, because the dump needs

package/types/e2e/src/driver/driver.types.d.ts

@@ -1,7 +1,7 @@
 import type { AsyncResult } from "../../../types/src/result";
 /**
  * The device driver contract every layer of warden-e2e builds on: the spec API (`screen`, `device`,
- * `app`), `warden ui`, flows and the devtools facet all talk to a `Driver`. Implementations:
+ * `app`), `warden ui`, specs and the devtools facet all talk to a `Driver`. Implementations:
  * `ios/ios-driver.ts` (warden-simd over NDJSON + `xcrun simctl`) and `android/android-driver.ts`
  * (persistent `adb shell` + uiautomator). `driver.testing.ts` has the scripted FakeDriver for tests.
  *

package/types/e2e/src/driver/ios/hid-recovery.d.ts

@@ -0,0 +1,36 @@
+import type { Exec } from "../../../../core/src/exec";
+import { type AsyncResult } from "../../../../types/src/result";
+import { connectSimd } from "./simd-client";
+export type HidRecoveryDeps = {
+    exec: Exec;
+    log?: (line: string) => void;
+    /** attach to the resident helper's socket (default {@link connectSimd}) */
+    connect?: typeof connectSimd;
+    /** whether the socket file is still there (default: `existsSync`) */
+    socketExists?: (path: string) => boolean;
+    sleep?: (ms: number) => Promise<void>;
+};
+/**
+ * Stops the resident `warden-simd` daemon on `socketPath` (the warm one `warden e2e` started): it is bound to the
+ * boot that just ended, and the reopened driver would otherwise attach to it and hit `E_HID` again. Asks it to
+ * `shutdown` and waits for the socket to go; with no daemon there (a stdio helper dies with its driver) nothing
+ * is done. The next driver open spawns a helper on the new boot.
+ */
+export declare function stopResidentHelper(deps: HidRecoveryDeps, socketPath: string): AsyncResult<"stopped" | "none">;
+/**
+ * The error of a tap/swipe/type on a sim whose HID connection is gone (wrapped as `ACTION_FAILED` or `DRIVER`), or
+ * of a helper that finds the sim shut down: quitting Device Hub normally shuts down every booted sim (DHW-0 V5), and
+ * the next call then fails `E_NOT_BOOTED`.
+ */
+export declare function isHidLost(error: unknown): boolean;
+/**
+ * Shuts the sim down and boots it again: `bootstatus -b` boots a shut-down sim itself and waits for it, and opens
+ * no Simulator.app window (the same windowless path warden claims use). The caller reconnects the helper and
+ * relaunches the app.
+ */
+export declare function rebootSim(deps: HidRecoveryDeps, udid: string): AsyncResult<void>;
+/**
+ * Runs `WARDEN_AFTER_REBOOT` (`{udid}` replaced) once the sim is back — `warden` uses it to reopen the sim's Device
+ * Hub window and tile again. Best effort: a failure is logged, never raised, and never fails the test.
+ */
+export declare function runAfterReboot(deps: HidRecoveryDeps, argv: readonly string[] | undefined, udid: string): Promise<void>;

package/types/e2e/src/driver/ios/simctl.d.ts

@@ -43,6 +43,17 @@ export declare const statusBarClearArgv: (udid: string) => string[];
  * (never interpolated into the script): `printf %s "$1" | xcrun simctl pbcopy "$2"`.
  */
 export declare function pbcopyArgv(udid: string, text: string): string[];
+/**
+ * The same text through `devicectl device pasteboard copy`, the CoreDevice side of the simulator pasteboard.
+ * On Xcode 27.1 (iOS 26.5 runtime) `simctl pbcopy` exits 0 without changing the pasteboard, which then still
+ * holds whatever CoreDevice's `dtpasteboardd` last mirrored from the Mac; `devicectl` writes it in ~350 ms.
+ */
+export declare function devicectlPbcopyArgv(udid: string, text: string): string[];
+/** The channels {@link createSimctl}'s `pbcopy` tries, in order; each write is confirmed with `simctl pbpaste`. */
+export declare const PBCOPY_CHANNELS: readonly {
+    name: string;
+    argv: (udid: string, text: string) => string[];
+}[];
 /** `launchctl list` rows are `PID  STATUS  LABEL`; PID is `-` for loaded-but-not-running jobs. */
 export declare function parseRunning(launchctlOutput: string, bundleId: string): boolean;
 /** Map a failed simctl run to a `DriverError`. `appCommand` marks launch-like calls where "not installed" means the app, not the device. */
@@ -72,6 +83,10 @@ export type Simctl = {
     clearData(bundleId: string, opts?: {
         keychain?: boolean;
     }): DriverResult<void>;
+    /**
+     * Puts `text` on the simulator pasteboard and confirms it with `pbpaste` before answering, trying every
+     * {@link PBCOPY_CHANNELS} entry: `E_IO` when none took, so a paste never lands other text.
+     */
     pbcopy(text: string): DriverResult<void>;
     pbpaste(): DriverResult<string>;
     appearance(set?: "light" | "dark"): DriverResult<"light" | "dark">;

package/types/e2e/src/driver/observation-cache.d.ts

@@ -4,7 +4,7 @@ import type { AlertInfo, Driver, DriverResult, Platform, Snapshot } from "./driv
  * does not walk the screen again (`isVisible()` then `text()` was two snapshots; on Android each one is a ~1.9 s
  * `uiautomator dump`).
  *
- * It is a `Driver` wrapper, because every layer that can change the screen (`screen`, `app`, `device`, flows) shares
+ * It is a `Driver` wrapper, because every layer that can change the screen (`screen`, `app`, `device`, specs) shares
  * the one driver: whatever calls it, an input moves the *generation* on and the kept snapshot dies with the old one.
  * A snapshot is also dropped once it is older than the platform's max age, input or not (the app can change by itself).
  * Which reads may reuse one is the caller's call (`observe({ reuse })`): only the first look of a wait does, so a

package/types/e2e/src/env.d.ts

@@ -1,5 +1,9 @@
 import type { Result } from "../../types/src/result";
-/** The env names `warden e2e` writes and the spec process reads (`apps/cli` imports these). */
+/**
+ * The env names `warden e2e` writes and the spec process reads (`apps/cli` imports these). `WARDEN_HEADLESS` and
+ * `WARDEN_WORKER` are also set for the spec process but are for the spec's own tools (`process.env`): nothing here
+ * reads them, so a bad value cannot fail spec-env validation.
+ */
 export declare const ENV_NAMES: {
     readonly udid: "WARDEN_UDID";
     readonly deviceName: "WARDEN_DEVICE_NAME";
@@ -12,15 +16,24 @@ export declare const ENV_NAMES: {
     readonly timeout: "WARDEN_E2E_TIMEOUT";
     readonly actionTimeout: "WARDEN_E2E_ACTION_TIMEOUT";
     readonly assertionTimeout: "WARDEN_E2E_ASSERTION_TIMEOUT";
-    readonly flowsDir: "WARDEN_E2E_FLOWS_DIR";
+    readonly specsDir: "WARDEN_E2E_SPECS_DIR";
     readonly helperDir: "WARDEN_HELPER_DIR";
     readonly simd: "WARDEN_SIMD";
     readonly simdSocket: "WARDEN_SIMD_SOCKET";
-    readonly headless: "WARDEN_HEADLESS";
     readonly logTimestamps: "WARDEN_LOG_TIMESTAMPS";
-    readonly worker: "WARDEN_WORKER";
+    /**
+     * JSON argv (`{udid}` is replaced) the session runs after it rebooted the sim following a lost HID connection;
+     * `warden` sets it for non-headless runs so the sim's viewer window comes back (packages/e2e cannot import apps/cli)
+     */
+    readonly afterReboot: "WARDEN_AFTER_REBOOT";
     /** the `warden` that started this process: the preload refuses to run when it is not this package's version */
     readonly version: "WARDEN_VERSION";
+    /** JSON argv that re-runs the `warden` that started this process (`device.perf` shells out to it) */
+    readonly bin: "WARDEN_BIN";
+    /** `warden e2e --perf`: the capture flags (`all`, or a comma list like `react,js`) every attempt records */
+    readonly perf: "WARDEN_PERF";
+    /** JSON of the suite's `perf.budgets`; a breach fails the test with `PERF_BUDGET` */
+    readonly perfBudgets: "WARDEN_PERF_BUDGETS";
 };
 export declare const DEFAULT_TIMEOUT_MS = 120000;
 export declare const DEFAULT_ACTION_TIMEOUT_MS = 30000;
@@ -39,18 +52,22 @@ export type E2eEnv = {
     timeoutMs: number;
     actionTimeoutMs: number;
     assertionTimeoutMs: number;
-    flowsDir?: string;
+    specsDir?: string;
     helperDir?: string;
     simd?: string;
     simdSocket?: string;
-    /** nothing in this package reads it: kept for specs and helpers that honour a headless run (`guides/headless`) */
-    headless: boolean;
     /** warden already stamps the log lines: the spec reporter prints no clock of its own */
     logTimestamps: boolean;
-    /** nothing in this package reads it: the 0-based worker index, for specs that shard or name per-worker data (`guides/e2e`) */
-    worker?: string;
+    /** `WARDEN_AFTER_REBOOT`: argv run after a HID-loss reboot, `{udid}` not yet replaced (see `runAfterReboot`) */
+    afterReboot?: string[];
     /** `WARDEN_VERSION`: the warden that started this run */
     wardenVersion?: string;
+    /** `WARDEN_BIN`: argv of the `warden` that started this run */
+    wardenBin?: string[];
+    /** `WARDEN_PERF`: capture names every attempt records (`all`, `react`, `js`…) */
+    perf?: string[];
+    /** `WARDEN_PERF_BUDGETS`: raw JSON of the suite's budgets */
+    perfBudgets?: string;
 };
 /**
  * Reads the spec env contract. `undefined` data = not running under warden (no `WARDEN_UDID`); an

package/types/e2e/src/errors.d.ts

@@ -1,5 +1,5 @@
 import type { ErrorResult } from "../../types/src/result";
-export type E2eErrorCode = "LOCATOR_NOT_FOUND" | "LOCATOR_AMBIGUOUS" | "INVALID_LOCATOR" | "ACTION_FAILED" | "TIMEOUT" | "NOT_ACTIONABLE" | "INVALID_ARGUMENT" | "SESSION" | "DRIVER" | "ASSERTION";
+export type E2eErrorCode = "LOCATOR_NOT_FOUND" | "LOCATOR_AMBIGUOUS" | "INVALID_LOCATOR" | "ACTION_FAILED" | "TIMEOUT" | "NOT_ACTIONABLE" | "INVALID_ARGUMENT" | "SESSION" | "DRIVER" | "ASSERTION" | "PERF_BUDGET";
 /** Plain shape of a spec error: what `e2eErr()` accepts and what a `Result` carries. */
 export type E2eErrorShape = {
     code: E2eErrorCode;

package/types/e2e/src/fixture-session.d.ts

@@ -11,8 +11,12 @@ export type FixtureSession = {
     readonly out: string;
     /** the running attempt's deadline / cancel signal; every driver call honours it */
     readonly signal?: AbortSignal;
-    /** `<out>/<flowId>/<title-slug>-<hash6>` of the running attempt */
+    /** `<out>/<specId>/<title-slug>-<hash6>` of the running attempt */
     readonly attemptDir?: string;
+    /** the running attempt's recorded files (`device.perf` adds its `perf/` ones) */
+    readonly attempt?: {
+        readonly files: Set<string>;
+    };
     /** the running attempt's `trace.jsonl` */
     readonly trace?: {
         write(event: TraceEvent): void;

package/types/e2e/src/index.d.ts

@@ -1,6 +1,9 @@
 export type { OpenOptions, OpenWaitUntil } from "./app";
 export { E2eError } from "./errors";
 export { expect } from "./expect/expect";
+export type { PerfBreach, PerfBudgets } from "./perf/budgets";
+export type { DevicePerf } from "./perf/device-perf";
+export type { PerfMetrics, PerfReport, PerfStartOptions } from "./perf/perf.types";
 export type { App, Device, Screen, SystemAlerts, TestFixtures } from "./runner/fixtures.types";
 export { afterAll, afterEach, beforeAll, beforeEach, describe, test } from "./runner/test";
 export type { Locator, LocatorReading, PinchOptions, RotateOptions, TapOptions, TapUntil } from "./screen/locator";

package/types/e2e/src/perf/budgets.d.ts

@@ -0,0 +1,33 @@
+import type { PerfReport } from "./perf.types";
+/** Ceilings a perf report must stay under; every field is optional and lower-is-better. */
+export type PerfBudgets = {
+    /** cold start, ms */
+    startupColdMs?: number;
+    /** share of janky frames, percent */
+    jankPct?: number;
+    /** the slowest React commit, ms */
+    maxCommitMs?: number;
+    /** 95th percentile app CPU, percent */
+    p95CpuPct?: number;
+    /** peak memory (PSS on Android, RSS on iOS), MB */
+    peakMemoryMb?: number;
+};
+export declare const BUDGET_KEYS: readonly ["startupColdMs", "jankPct", "maxCommitMs", "p95CpuPct", "peakMemoryMb"];
+export type BudgetKey = (typeof BUDGET_KEYS)[number];
+/** One metric over its ceiling. */
+export type PerfBreach = {
+    metric: BudgetKey;
+    value: number;
+    budget: number;
+};
+/** What the report measured for `metric`, or `undefined` when its capture did not run. */
+export declare function measured(report: Pick<PerfReport, "metrics">, metric: BudgetKey): number | undefined;
+/**
+ * Budgets set in `overrides` replace the same key of `base` (config); a metric the report has no number for (its
+ * capture did not run) cannot breach.
+ */
+export declare function checkBudgets(report: Pick<PerfReport, "metrics">, base: PerfBudgets | undefined, overrides?: PerfBudgets): PerfBreach[];
+/** The failure text: each breach, then where the full report is. */
+export declare function describeBreaches(breaches: readonly PerfBreach[], reportPath: string | undefined): string;
+/** Parses the `WARDEN_PERF_BUDGETS` JSON warden writes; unknown keys and non-numbers are dropped. */
+export declare function parseBudgets(raw: string | undefined): PerfBudgets;

package/types/e2e/src/perf/device-perf.d.ts

@@ -0,0 +1,45 @@
+import { type PerfBudgets } from "./budgets";
+import type { PerfReport, PerfStartOptions } from "./perf.types";
+/** One `warden` invocation: argv (without the warden command itself) in, exit code and streams out. */
+export type PerfExec = (argv: readonly string[]) => Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+}>;
+/** Subdirectory of the attempt dir a perf session's report is copied to. */
+export declare const PERF_DIR = "perf";
+export type DevicePerf = {
+    /** opens a perf session on this device; one per device at a time */
+    start(options?: PerfStartOptions): Promise<{
+        sessionId: string;
+    }>;
+    /** drops a label on the session timeline; commits, hangs and jank are tagged with the last mark before them */
+    mark(label: string): Promise<void>;
+    /**
+     * Ends the session and returns its report (`reportPath` is the copy under the attempt's `perf/`). Throws
+     * `PERF_BUDGET` when a metric is over the suite's budget (`warden.config.ts` `perf.budgets`) or `budgets`, which
+     * replaces the suite's per key.
+     */
+    stop(options?: {
+        budgets?: PerfBudgets;
+    }): Promise<PerfReport>;
+    /** a session this device opened and has not stopped */
+    readonly active: boolean;
+};
+export type DevicePerfDeps = {
+    exec: PerfExec;
+    udid: string;
+    /** budgets of the suite (`WARDEN_PERF_BUDGETS`) */
+    budgets: PerfBudgets;
+    /** the running attempt's dir; absent outside an attempt (the report stays in the session dir) */
+    attemptDir: () => string | undefined;
+    /** records a file written into the attempt dir (relative path) so `results.jsonl` lists it */
+    addFile?: (relative: string) => void;
+    /** `warden` is not reachable (no `WARDEN_BIN`) */
+    unavailable?: string;
+};
+export declare function createDevicePerf(deps: DevicePerfDeps): DevicePerf;
+/** `--perf=react,js` (or `all`) as the options `perf.start` takes; an unknown name is ignored, none named = warden's default set. */
+export declare function perfStartFor(names: readonly string[]): PerfStartOptions;
+/** Runs the `warden` that started the spec process (`WARDEN_BIN`). */
+export declare function spawnWarden(bin: readonly string[] | undefined): PerfExec;

package/types/e2e/src/perf/perf.types.d.ts

@@ -0,0 +1,59 @@
+/** The capture switches `device.perf.start` takes (the `warden perf start` flags of the same name). */
+export type PerfStartOptions = {
+    js?: boolean;
+    react?: boolean;
+    native?: boolean | "perfetto" | "simpleperf";
+    metrics?: boolean;
+    frames?: boolean;
+    logs?: boolean;
+    all?: boolean;
+    /** stop the app, arm the captures, launch it: startup and early JS/React are recorded */
+    relaunch?: boolean;
+    /** like `relaunch`, but wipe the app's data first */
+    reset?: boolean;
+    /** hard cap on the session; warden's default is 30 s, the maximum 5 min */
+    maxDurationMs?: number;
+};
+/** The numbers of a report, each lower-is-better (the `metrics` of `report.json`). */
+export type PerfMetrics = {
+    startupColdMs?: number;
+    startupWarmMs?: number;
+    jankPct?: number;
+    fps?: number;
+    cpuP95Pct?: number;
+    peakPssKb?: number;
+    peakRssKb?: number;
+    /** the slowest React commit */
+    topCommitMs?: number;
+    hangCount?: number;
+    hangTotalMs?: number;
+    topFunctions: Array<{
+        name: string;
+        selfPct: number;
+    }>;
+};
+/** `report.json` of a perf session, as far as a spec reads it (the full document is at `reportPath`). */
+export type PerfReport = {
+    version: 1;
+    sessionId: string;
+    app?: string;
+    durationMs: number;
+    stopReason?: string;
+    banners: string[];
+    summary: string[];
+    findings: Array<{
+        kind: string;
+        severity: string;
+        costMs: number;
+        evidence: string;
+        fix: string;
+    }>;
+    metrics: PerfMetrics;
+    marks: Array<{
+        label: string;
+        atMs: number;
+    }>;
+    next: string[];
+    /** where `report.json` is (inside the attempt's `perf/` dir when the spec runs under `warden e2e`) */
+    reportPath?: string;
+};

package/types/e2e/src/preload.d.ts

@@ -14,8 +14,8 @@ export type PreloadDeps = {
     exit: (code: number) => void;
 };
 /**
- * The protocol handshake: `warden e2e` and this package version in lock-step. A mismatch is a warning, not an
- * error (most pairs still work), but the install fix is spelled out. Nothing to compare without `WARDEN_VERSION`
+ * The protocol handshake: `warden e2e` and this package version in lock-step. A mismatch refuses the run (exit 2)
+ * with the install fix spelled out. Nothing to compare without `WARDEN_VERSION`
  * (a by-hand run) or from the workspace sources (not a published build).
  */
 export declare function versionMismatch(wardenVersion: string | undefined, e2eVersion: string): string | undefined;

package/types/e2e/src/runner/artifacts.d.ts

@@ -2,12 +2,12 @@
 export declare function slug(text: string, fallback?: string): string;
 /** First 6 hex chars of a sha1 over the parts: keeps equal slugs from colliding. */
 export declare function hash6(...parts: string[]): string;
-/** `<out>/<flowId>/<title-slug>-<hash6>/` for one test attempt. */
-export declare function attemptDir(out: string, flowId: string, title: readonly string[], hash: string): string;
+/** `<out>/<specId>/<title-slug>-<hash6>/` for one test attempt. */
+export declare function attemptDir(out: string, specId: string, title: readonly string[], hash: string): string;
 /** `<dir>/screenshots/NNN-name.png` (3-digit, 1-based order). */
 export declare function screenshotPath(dir: string, n: number, name: string): string;
 /**
- * Stable per-file id: the path under `flowsDir` without extension (`auth/sign-in.e2e.ts` →
- * `auth/sign-in`), segments slugged. A file outside `flowsDir` (or no `flowsDir`) uses its basename.
+ * Stable per-file id: the path under `specsDir` without extension (`auth/sign-in.e2e.ts` →
+ * `auth/sign-in`), segments slugged. A file outside `specsDir` (or no `specsDir`) uses its basename.
  */
-export declare function flowIdOf(file: string, flowsDir?: string): string;
+export declare function specIdOf(file: string, specsDir?: string): string;

package/types/e2e/src/runner/failure.d.ts

@@ -1,5 +1,7 @@
 import type { DevtoolsFacet } from "../devtools/devtools.types";
+import { type NativeLogDeps, type NativeTarget } from "../devtools/native-log";
 import type { Driver } from "../driver/driver.types";
+import type { E2eEnv } from "../env";
 export declare const FAILURE_PNG = "failure.png";
 export declare const SCREEN_AT_FAILURE = "screen-at-failure.txt";
 export declare const CONSOLE_JSONL = "console.jsonl";
@@ -26,3 +28,13 @@ export declare function captureFailure(driver: Driver, dir: string, timeoutMs?:
  * {@link captureFailure}: never throws, gives up after `timeoutMs` (the network drain talks to the page).
  */
 export declare function captureDevtoolsArtifacts(facet: DevtoolsFacet, dir: string, timeoutMs?: number, budget?: CaptureBudget): Promise<FailureCapture>;
+/** The app a failed attempt ran, from the run's env. */
+export declare function nativeTarget(env: Pick<E2eEnv, "platform" | "udid" | "bundleId">): NativeTarget;
+/**
+ * `native.log` (+ iOS `.ips` crash reports) of the failed attempt, see {@link captureNativeLog}. Best effort
+ * like {@link captureFailure}: never throws, limited by `timeoutMs` and what `budget` has left.
+ */
+export declare function captureNativeArtifacts(target: NativeTarget, deps: NativeLogDeps, win: {
+    dir: string;
+    sinceMs: number;
+}, timeoutMs?: number, budget?: CaptureBudget): Promise<FailureCapture>;

package/types/e2e/src/runner/fixtures.types.d.ts

@@ -46,7 +46,7 @@ export type FixtureFactory = (ctx: FixtureContext) => BaseFixtures | Promise<Bas
 /** The running attempt: where steps, screenshots and failure files go. Read it through the session. */
 export type AttemptContext = {
     readonly signal: AbortSignal;
-    /** `<out>/<flowId>/<title-slug>-<hash6>/` */
+    /** `<out>/<specId>/<title-slug>-<hash6>/` */
     readonly dir: string;
     /** spec name tagging step lines */
     readonly short: string;

package/types/e2e/src/runner/scope.d.ts

@@ -21,8 +21,10 @@ export type ResolvedUse = {
     launch: LaunchMode;
     systemAlerts: SystemAlerts;
 };
-/** `beforeEach`/`afterEach` hooks get the base fixtures (bun's own hooks take no arguments). */
+/** Scope hooks are stored against the base fixtures; `test.extend(...).beforeEach` hooks are narrowed back to theirs by the runner (bun's own hooks take no arguments). */
 export type Hook = (fixtures: BaseFixtures) => void | Promise<void>;
+/** Marks `hook` as belonging to tests built from `fixtures` (entries compared by identity, in definition order). */
+export declare function ownHook(hook: Hook, fixtures: readonly object[]): Hook;
 export type Scope = {
     /** describe titles from the root down to this scope */
     readonly title: readonly string[];
@@ -45,8 +47,8 @@ export declare function createScope(title: string, serial: boolean): Scope;
 export declare function runInScope(scope: Scope, body: () => void): void;
 /** Root first, `scope` last. */
 export declare function scopeChain(scope: Scope): Scope[];
-/** `beforeEach`: outermost first. `afterEach`: innermost first. */
-export declare function hooksFor(scope: Scope, kind: "beforeEach" | "afterEach"): Hook[];
+/** `beforeEach`: outermost first. `afterEach`: innermost first. Hooks owned by another fixture set are left out. */
+export declare function hooksFor(scope: Scope, kind: "beforeEach" | "afterEach", fixtures?: readonly object[]): Hook[];
 /** Session defaults (env contract) under the nearest `test.use`, under the test's own `timeout`. */
 export declare function resolveUse(scope: Scope, defaults: Pick<ResolvedUse, "timeoutMs" | "actionTimeoutMs" | "assertionTimeoutMs">, testTimeout?: number): ResolvedUse;
 /** Timeouts known at collection time: the env when set, else the contract defaults. */

package/types/e2e/src/runner/test.d.ts

@@ -31,6 +31,13 @@ export type TestApi<F extends object> = TestCallable<F> & {
     skipIf(condition: boolean): TestCallable<F>;
     /** applies to every test collected in the current scope (file or `describe`) */
     use(options: UseOptions): void;
+    /**
+     * Like the top-level `beforeEach`, typed with this `test`'s fixtures (the ones `extend` added too). It runs only
+     * for tests made with this `test` or one extended from it, not for the base `test`'s.
+     */
+    beforeEach(hook: (fixtures: F) => void | Promise<void>): void;
+    /** `beforeEach`'s counterpart: runs after each such test, even when it failed. */
+    afterEach(hook: (fixtures: F) => void | Promise<void>): void;
     /** a `test` whose bodies also receive `Extra` */
     extend<Extra extends object>(defs: FixtureDefs<F, Extra>): TestApi<F & Extra>;
 };

package/types/e2e/src/screen/actions.d.ts

@@ -21,7 +21,7 @@ export declare function focusPoint(frame: Rect): Point;
 export declare function swipeVector(direction: SwipeDirection, rect: Rect, momentum?: Momentum): SwipeVector;
 /**
  * The one swipe geometry: the finger path inside `rect`, centred, covering `fraction` (0-1) of it, that scrolls the
- * content `direction` (`down` reveals what is below, so the finger travels up). Spec swipes, flow `swipe`/`scroll` steps
+ * content `direction` (`down` reveals what is below, so the finger travels up). Spec swipes, spec `swipe`/`scroll` steps
  * and `warden ui scroll` use it as is; `warden ui gesture swipe <dir>` names the finger's direction instead and flips it
  * (`fingerPath` in the CLI).
  */