touchpress 0.0.1

package/dist/preflight--Z-REtl-.d.mts

@@ -0,0 +1,853 @@
+//#region src/core/screen.d.ts
+type Platform = 'ios' | 'android';
+type Rect = {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+};
+/**
+ * One node of a parsed screen, not the driver's snapshot node: `label` becomes
+ * `name`, `identifier` becomes `testId`, and `type` is normalized into `role`
+ * with the platform spelling kept as `rawType`.
+ *
+ * Invariant: `parent` links form a forest rooted at nodes whose `parentIndex`
+ * was absent, built once at parse time so an ancestor walk stays O(depth).
+ */
+type ScreenNode = {
+  readonly ref: string;
+  readonly index: number;
+  readonly parent: ScreenNode | null;
+  readonly depth: number;
+  readonly role: Role;
+  readonly rawType: string;
+  readonly name: string | null;
+  readonly value: string | null;
+  readonly testId: string | null;
+  readonly rect: Rect | null;
+  readonly enabled: boolean;
+  readonly selected: boolean;
+  readonly focused: boolean;
+  /**
+   * The driver's hints that a scroll container holds content out of the window.
+   * The only thing that says which way to scroll on a platform whose raw tree
+   * stops at the window.
+   */
+  readonly hiddenContentAbove: boolean;
+  readonly hiddenContentBelow: boolean;
+};
+/**
+ * A frozen observation of the device at one instant.
+ *
+ * Invariant: a screen is never refreshed in place. Every state-changing
+ * command advances the driver's ref generation, so a screen captured before
+ * one can only mint refs the driver will reject.
+ */
+type Screen = {
+  readonly nodes: readonly ScreenNode[];
+  readonly generation: number | null;
+  readonly appId: string | null;
+  readonly truncated: boolean;
+  readonly capturedAt: number;
+};
+declare const pinnedRefBrand: unique symbol;
+/**
+ * A ref pinned to the generation it was minted from, in the driver's
+ * `@e12~s776575` form. The driver rejects a pin from a superseded generation
+ * before dispatch, which turns a silent mistap into a recoverable failure.
+ */
+type PinnedRef = string & {
+  readonly [pinnedRefBrand]: true;
+};
+type Resolution = {
+  readonly outcome: 'one';
+  readonly node: ScreenNode;
+} | {
+  readonly outcome: 'none';
+  readonly nearest: readonly ScreenNode[];
+} | {
+  readonly outcome: 'many';
+  readonly nodes: readonly ScreenNode[];
+};
+/**
+ * The structural shape of the driver's snapshot response. Declared here rather
+ * than imported so the core never depends on `agent-device`. The real
+ * `CaptureSnapshotResult` satisfies it and so does a JSON fixture.
+ */
+type RawSnapshot = {
+  readonly nodes: ReadonlyArray<{
+    readonly ref: string;
+    readonly index: number;
+    readonly type?: string;
+    readonly role?: string;
+    readonly label?: string;
+    readonly value?: string;
+    readonly identifier?: string;
+    readonly rect?: Rect;
+    readonly enabled?: boolean;
+    readonly selected?: boolean;
+    readonly focused?: boolean;
+    readonly hintShowing?: boolean;
+    readonly hiddenContentAbove?: boolean;
+    readonly hiddenContentBelow?: boolean;
+    readonly depth?: number;
+    readonly parentIndex?: number;
+    readonly inheritsLabel?: true;
+    readonly inheritsIdentifier?: true;
+  }>;
+  readonly truncated?: boolean;
+  readonly appBundleId?: string;
+  readonly refsGeneration?: number;
+};
+/**
+ * The parse boundary. Everything past it trusts its types.
+ *
+ * `inheritsLabel` and `inheritsIdentifier` mean the driver omitted a value that
+ * string-equals the nearest ancestor's, so those are restored here rather than
+ * leaving a hole a matcher would read as absent.
+ */
+declare function parseScreen(raw: RawSnapshot, platform: Platform): Screen;
+/**
+ * The single resolver, shared by actions and assertions so the two can never
+ * disagree about which node was meant. Rule order: match every query field,
+ * apply every `.filter()`, absorb ancestors, then `index`.
+ *
+ * Ancestor absorption drops a match when a descendant match carries the same
+ * string the query matched on. On the sample app an `[other]` container and its
+ * `[text]` child both carry "Live from the cloud", which is one thing on screen.
+ * Matches in disjoint subtrees stay distinct, so "Explore" on the Explore screen
+ * is still the heading and the tab button.
+ */
+declare function resolve(screen: Screen, query: Query): Resolution;
+/**
+ * The one tree renderer, used by failure messages and by the `screen.txt`
+ * attachment so terminal and report agree. The vocabulary is the CLI's own
+ * `[role] "label"` form.
+ */
+declare function renderScreen(screen: Screen, options?: {
+  readonly maxNodes?: number;
+}): string;
+//#endregion
+//#region src/core/query.d.ts
+/**
+ * Spelled the way `agent-device snapshot` prints it, so a failure listing and a
+ * manual snapshot read alike. iOS reports XCUIElement type names and Android
+ * reports widget class names, and both map here.
+ *
+ * Invariant: every raw type maps to exactly one role and an unrecognized type
+ * maps to `other`. `other` is a real role, not a failure signal, because React
+ * Native emits many labelled container views with no semantic type.
+ */
+type Role = 'application' | 'window' | 'button' | 'text' | 'text-field' | 'secure-text-field' | 'link' | 'image' | 'switch' | 'slider' | 'tab-bar' | 'scroll-area' | 'cell' | 'alert' | 'other';
+/** How one string field is compared. */
+type TextMatch = {
+  readonly kind: 'substring';
+  readonly value: string;
+} | {
+  readonly kind: 'exact';
+  readonly value: string;
+} | {
+  readonly kind: 'regex';
+  readonly value: RegExp;
+};
+/** One `.filter()` call. Every field narrows, so an empty filter is a no-op. */
+type Filter = {
+  readonly hasText?: TextMatch;
+  readonly hasNotText?: TextMatch;
+  readonly has?: Query;
+  readonly hasNot?: Query;
+};
+/**
+ * A pure conjunctive description of a node. Building one performs no I/O.
+ *
+ * Invariants: every field narrows, so an empty query matches every node. `name`
+ * is compared against the node's name and its value, which is what makes
+ * `getByText` behave like Playwright's. `filters` holds one entry per
+ * `.filter()` call, conjunctive within and across entries. `index` is the
+ * strictness opt-out set by `.first()` and `.nth(n)`, and without it more than
+ * one distinct match is an error.
+ */
+type Query = {
+  readonly testId?: TextMatch;
+  readonly name?: TextMatch;
+  readonly value?: TextMatch;
+  readonly role?: Role;
+  readonly enabled?: boolean;
+  readonly selected?: boolean;
+  readonly focused?: boolean;
+  readonly where?: (node: ScreenNode) => boolean;
+  readonly filters?: readonly Filter[];
+  readonly index?: number;
+};
+/** Applied to both sides of every string comparison, so a label wrapped across lines still matches one typed on one line. */
+declare function normalizeText(raw: string): string;
+/**
+ * Playwright's default text semantics: case-insensitive substring after
+ * whitespace normalization. `exact` is whole-string and case-sensitive, still
+ * normalized.
+ */
+declare function textMatch(value: string | RegExp, exact?: boolean): TextMatch;
+/**
+ * Renders a query back into the factory call that produces it, so the `Locator:`
+ * line of a failure reads like the line the author wrote.
+ */
+declare function describeQuery(query: Query): string;
+//#endregion
+//#region src/core/checks.d.ts
+/**
+ * An assertion as data. Adapters turn each `name` into a matcher, and the poll
+ * and the message live in `probe`, so two runners produce identical failures.
+ */
+type Check = {
+  readonly name: 'toBeVisible';
+} | {
+  readonly name: 'toHaveText';
+  readonly expected: TextMatch;
+} | {
+  readonly name: 'toHaveValue';
+  readonly expected: TextMatch;
+} | {
+  readonly name: 'toBeEnabled';
+} | {
+  readonly name: 'toBeSelected';
+} | {
+  readonly name: 'toBeFocused';
+} | {
+  readonly name: 'toHaveCount';
+  readonly expected: number;
+};
+type CheckName = Check['name'];
+type Verdict = {
+  readonly pass: boolean;
+  /** What the screen actually held, for the `Received:` line. Null when nothing matched. */
+  readonly actual: string | null;
+};
+/**
+ * A `many` outcome never passes anything but `toHaveCount`. An ambiguous locator
+ * is a strictness violation, and it reports through the same message path as a
+ * plain mismatch rather than guessing which node was meant.
+ */
+declare function evaluate(check: Check, resolution: Resolution): Verdict;
+/** The `Expected:` line. */
+declare function describeCheck(check: Check): string;
+//#endregion
+//#region src/core/driver.d.ts
+type ScrollDirection = 'up' | 'down' | 'left' | 'right';
+/**
+ * A session binds on its first command, so this rides on `open` and on every
+ * command after it. A call sent without selection lands on whichever device the
+ * daemon picks, which is not necessarily the one under test.
+ */
+type DeviceSelection = {
+  readonly platform: Platform;
+  readonly name: string | null;
+};
+/** One device the driver can see. Only the fields preflight needs, so no agent-device device shape crosses here. */
+type DeviceInfo = {
+  readonly id: string;
+  readonly name: string;
+  readonly booted: boolean;
+};
+/** The session name and the device selection ride on the driver itself, so an open cannot name a different one. */
+type OpenRequest = {
+  readonly app: string;
+  readonly relaunch: boolean;
+  /** A deep link to launch the app with, or null to launch it plainly. */
+  readonly url: string | null;
+};
+/** Proof that a device is bound. Only `open` mints one, so a believed binding cannot drift from a real one. */
+type Binding = {
+  readonly session: string;
+  readonly platform: Platform;
+  readonly deviceLabel: string;
+  readonly appId: string;
+  readonly stateDir: string | null;
+};
+type Settled = {
+  readonly settled: boolean;
+  readonly waitedMs: number;
+};
+/**
+ * Why an operation failed, in this library's vocabulary. Translated once, in
+ * `driver/agent-device.ts`, so a test author never reads a raw driver code.
+ */
+type DeviceFailure = {
+  readonly kind: 'device-busy';
+  readonly owner: string | null;
+  readonly detail: string;
+} | {
+  readonly kind: 'device-missing';
+  readonly detail: string;
+} | {
+  readonly kind: 'app-missing';
+  readonly detail: string;
+} | {
+  readonly kind: 'session-rebound';
+  readonly boundTo: string;
+  readonly detail: string;
+} | {
+  readonly kind: 'stale-ref';
+  readonly detail: string;
+} | {
+  readonly kind: 'ambiguous';
+  readonly detail: string;
+} | {
+  readonly kind: 'timeout';
+  readonly detail: string;
+} | {
+  readonly kind: 'unknown';
+  readonly code: string;
+  readonly detail: string;
+  readonly logPath: string | null;
+};
+type SettleOptions = {
+  readonly settleQuietMs: number;
+  readonly timeoutMs: number;
+};
+/**
+ * `default` is the driver's visible-first view, which every locator resolves
+ * against. `raw` is the full provider tree. On iOS it carries the nodes a scroll
+ * container moved out of the window, which is how a target is located before it
+ * is on screen. On Android it carries no off-screen content, only the wrappers
+ * the default view collapses away.
+ */
+type Tree = 'default' | 'raw';
+type CaptureOptions = {
+  readonly timeoutMs: number;
+  readonly tree: Tree;
+};
+/**
+ * Nothing crossing this port is a transport type, which is what lets the core be
+ * unit-tested against a captured snapshot.
+ *
+ * Contract every implementation owes the core. `open` converges when called on
+ * an already-open session. Mutations take a `PinnedRef` and never a selector, so
+ * the driver's own matcher is never a second opinion on which node was meant.
+ * Every failure throws a `TangereError` carrying a `DeviceFailure`.
+ */
+type DeviceDriver = {
+  /** Takes no session, so it is the one call that binds nothing. */
+  listDevices(): Promise<readonly DeviceInfo[]>;
+  open(request: OpenRequest): Promise<Binding>;
+  capture(options: CaptureOptions): Promise<RawSnapshot>;
+  screenshot(path: string): Promise<string>;
+  tap(ref: PinnedRef, options: SettleOptions): Promise<Settled>;
+  longPress(ref: PinnedRef, durationMs: number, options: SettleOptions): Promise<Settled>;
+  fill(ref: PinnedRef, text: string, options: SettleOptions): Promise<Settled>;
+  /** Returns nothing because the driver's scroll response carries no settle observation. */
+  scroll(direction: ScrollDirection, options: SettleOptions): Promise<void>;
+  dismissDevOverlay(): Promise<void>;
+  /** Ends a session. Names one explicitly so a leftover owned by another run can be reclaimed. */
+  close(session: string): Promise<void>;
+};
+//#endregion
+//#region src/core/probe.d.ts
+/** What `probe` needs from a locator. A `Locator` supplies it, and so can a fake. */
+type ProbeTarget = {
+  readonly query: Query;
+  readonly description: string;
+  capture(): Promise<Screen>;
+  /** The failure that broke the session, or null while it is usable. */
+  failure(): DeviceFailure | null;
+};
+type ProbeOptions = {
+  /** True when the caller wrote `.not`. The loop polls for the opposite condition rather than checking once. */
+  readonly negate: boolean;
+  readonly timeoutMs: number;
+  readonly intervalMs?: number;
+};
+type ProbeResult = {
+  /**
+   * Whether the check holds, always from the un-negated point of view. The
+   * adapter hands this to its assertion library, which inverts it for `.not`,
+   * so a `.not` that got what it wanted returns `false` here.
+   */
+  readonly pass: boolean;
+  /** Fully rendered, including the screen listing. Empty when the probe passed. */
+  readonly message: string;
+  readonly actual: string | null;
+  readonly expected: string;
+};
+/**
+ * Polls a fresh screen until the check agrees with `negate`, the budget runs
+ * out, or the session breaks. Never throws for a failed expectation, because the
+ * adapter hands `{ pass, message }` to its assertion library.
+ *
+ * Every early exit reports `pass: options.negate`, the value that fails the
+ * assertion whether or not the caller wrote `.not`. An ambiguous locator and a
+ * dead session are wrong under `.not` too, so neither may pass by inversion.
+ */
+declare function probe(target: ProbeTarget, check: Check, options: ProbeOptions): Promise<ProbeResult>;
+/**
+ * The screen listing comes from `renderScreen`, the same function that writes
+ * `screen.txt`, so terminal and report agree.
+ */
+declare function formatFailure(input: {
+  readonly locator: string;
+  readonly check: Check;
+  readonly negate: boolean;
+  readonly resolution: Resolution;
+  readonly screen: Screen | null;
+  readonly timeoutMs: number;
+  readonly polls: number;
+}): string;
+//#endregion
+//#region src/core/report.d.ts
+/** A file the runner should surface with the test result. */
+type EvidenceFile = {
+  readonly name: string;
+  readonly path: string;
+  readonly contentType: string;
+} | {
+  readonly name: string;
+  readonly body: string;
+  readonly contentType: string;
+};
+/**
+ * The most a step title may say about text that was typed. A secure field never
+ * reports its contents, so a step that wrote to one says how many characters it
+ * typed and nothing else. A caller can ask for the same on a field the platform
+ * did not mark secure, which keeps a credential out of a terminal and a report.
+ */
+type Typed = {
+  readonly kind: 'text';
+  readonly value: string;
+} | {
+  readonly kind: 'hidden';
+  readonly length: number;
+};
+type ActionRecord = {
+  readonly kind: 'open';
+  readonly app: string;
+  readonly device: string;
+  readonly session: string;
+} | {
+  readonly kind: 'tap';
+  readonly query: Query;
+} | {
+  readonly kind: 'long-press';
+  readonly query: Query;
+  readonly durationMs: number;
+} | {
+  readonly kind: 'fill';
+  readonly query: Query;
+} | {
+  readonly kind: 'typed';
+  readonly typed: Typed;
+} | {
+  readonly kind: 'scroll';
+  readonly direction: ScrollDirection;
+} | {
+  readonly kind: 'scroll-into-view';
+  readonly query: Query;
+} | {
+  readonly kind: 'relaunch';
+  readonly app: string;
+} | {
+  readonly kind: 'dismiss-overlay';
+} | {
+  readonly kind: 'screenshot';
+  readonly path: string;
+};
+/** A boxed step reports as one line rather than as something to open. */
+type StepOptions = {
+  readonly box?: boolean;
+};
+/**
+ * A runner with no step concept calls `body()` directly, ignores `options`, and
+ * drops attachments.
+ *
+ * Invariant: `step` invokes `body` exactly once and propagates its result and
+ * its rejection unchanged. It reports, it never decides control flow.
+ */
+type ActionSink = {
+  step<T>(title: string, body: () => Promise<T>, options?: StepOptions): Promise<T>;
+  attach(file: EvidenceFile): Promise<void>;
+  /** A key/value fact about the run, such as which device this worker bound to. */
+  note(key: string, value: string): void;
+  /** A unique path for this test and this retry attempt. */
+  outputPath(fileName: string): string;
+};
+/** Rendered here rather than in an adapter so every runner produces the same text. */
+declare function renderTitle(record: ActionRecord): string;
+/** Discards everything. The default for scripts, unit tests, and runners with no reporting. */
+declare const silentSink: ActionSink;
+//#endregion
+//#region src/core/config.d.ts
+/**
+ * The keys tangere adds to Playwright's `use`. Each is its own option fixture, so
+ * a project overrides one without restating the rest.
+ *
+ * Playwright types `use` as a partial of this, so a config may leave any key out.
+ * `parseDeviceOptions` is what makes `platform`, `app`, and `readyWhen` required.
+ * It runs once at worker start and nothing downstream re-validates.
+ */
+type TangereOptions = {
+  /** Required. */
+  platform: Platform | undefined;
+  /** Required. Bundle id on iOS, package name on Android. Never a path to an artifact. */
+  app: string | undefined;
+  /**
+   * Required. `open` returns as soon as the native process launches, so without
+   * this gate the first assertion would race the JavaScript bundle.
+   */
+  readyWhen: ReadyQuery | undefined;
+  /** Device name. An array is a pool indexed by the runner's worker slot. Unset means the first booted device. */
+  deviceName: string | readonly string[] | undefined;
+  /**
+   * A deep link to open the app with, on the launch and on every relaunch.
+   * Unset launches the app plainly, which is what a release build wants. An
+   * Expo development client needs one, because launching it plainly shows its
+   * own server picker rather than the app.
+   */
+  launchUrl: string | undefined;
+  /** @default 'per-test' */
+  relaunch: 'per-test' | 'per-worker';
+  /** @default 'fail'. Sessions carrying this library's own prefix are always reclaimed. */
+  onDeviceInUse: 'fail' | 'reclaim';
+  /** @default 500 */
+  settleQuietMs: number;
+  /** @default 90_000. Covers `open` plus the ready gate. */
+  launchTimeout: number;
+  /** @default false. Sends agent-device's `react-native dismiss-overlay` after every launch. */
+  dismissDevOverlay: boolean;
+  /** @default 'on-failure' */
+  evidence: 'on-failure' | 'always' | 'off';
+  /** @default 'tangere'. Session names are `${prefix}-${project}-${parallelIndex}`. */
+  sessionPrefix: string;
+};
+/**
+ * The option fixtures declare these as their defaults and the parser falls back
+ * to the same values, so a caller that reaches the parser without the fixtures,
+ * such as `preflight`, resolves identically.
+ */
+declare const TANGERE_DEFAULTS: Omit<TangereOptions, 'platform' | 'app' | 'readyWhen' | 'deviceName' | 'launchUrl'>;
+/** The config-file friendly subset of a locator. Matched by the same rules as any other query. */
+type ReadyQuery = {
+  text: string;
+  exact?: boolean;
+} | {
+  testId: string;
+} | {
+  role: Role;
+  name?: string;
+};
+/**
+ * The three cases are separate because only a pool can serve more than one
+ * worker slot. A single name and "whatever is booted" both resolve to the same
+ * device for every worker, and two workers on one device fight over the claim.
+ */
+type DeviceChoice = {
+  readonly kind: 'first-booted';
+} | {
+  readonly kind: 'named';
+  readonly name: string;
+} | {
+  readonly kind: 'pool';
+  readonly names: readonly string[];
+};
+/** Every optional field resolved. Constructed only by `parseDeviceOptions`, so internal code trusts it. */
+type ResolvedOptions = {
+  readonly platform: Platform;
+  readonly app: string;
+  readonly readyWhen: Query;
+  readonly device: DeviceChoice;
+  readonly launchUrl: string | null;
+  readonly relaunch: 'per-test' | 'per-worker';
+  readonly onDeviceInUse: 'fail' | 'reclaim';
+  readonly actionTimeout: number;
+  readonly settleQuietMs: number;
+  readonly launchTimeout: number;
+  readonly dismissDevOverlay: boolean;
+  readonly evidence: 'on-failure' | 'always' | 'off';
+  readonly sessionPrefix: string;
+};
+/**
+ * The config boundary. Options arrive as `unknown` because a project can omit
+ * any of them, or be written in JavaScript, and because `actionTimeout` rides
+ * along from Playwright's own options. Every message names the key to fix.
+ */
+declare function parseDeviceOptions(raw: unknown): ResolvedOptions;
+/**
+ * Anything but a pool serves slot 0 only. Two workers pointed at one device both
+ * try to claim it, and because leftovers carrying this library's session prefix
+ * are always reclaimed, the second worker would close the first worker's live
+ * session mid-test. That has to be a config error, not a race.
+ */
+declare function deviceNameForSlot(options: ResolvedOptions, slot: number): string | null;
+//#endregion
+//#region src/core/session.d.ts
+/**
+ * There is no unopened or opening variant because `openSession` is the only
+ * constructor and it returns after `open` succeeded and the ready gate passed.
+ * `broken` carries the first failure so a later call reports the root cause
+ * rather than a follow-on symptom.
+ */
+type SessionState = {
+  readonly phase: 'ready';
+  readonly binding: Binding;
+} | {
+  readonly phase: 'closed';
+  readonly reason: 'requested' | 'worker-exit';
+} | {
+  readonly phase: 'broken';
+  readonly failure: DeviceFailure;
+};
+/**
+ * Every mutation takes the budget it has left rather than reading
+ * `actionTimeout` again, so waiting for a target and waiting for the screen to
+ * settle share one allowance instead of each getting a full one.
+ */
+type SessionDevice = {
+  capture(): Promise<Screen>;
+  /**
+   * The driver's full provider tree. Only a scroll search reads it, because it
+   * carries nodes no locator should resolve against: on iOS the rows scrolled
+   * out of the window, and on both platforms the wrappers the default tree
+   * collapses away.
+   */
+  captureRaw(): Promise<Screen>;
+  tap(ref: PinnedRef, budgetMs: number): Promise<Settled>;
+  longPress(ref: PinnedRef, durationMs: number, budgetMs: number): Promise<Settled>;
+  fill(ref: PinnedRef, text: string, budgetMs: number): Promise<Settled>;
+  scroll(direction: ScrollDirection, budgetMs: number): Promise<void>;
+};
+type DeviceSession = {
+  readonly name: string;
+  readonly options: ResolvedOptions;
+  state(): SessionState;
+  /** The failure that broke this session, or null while it is usable. */
+  failure(): DeviceFailure | null;
+  /** Runs `body` as one unit on the session's queue. Nothing else touches the device while it runs. */
+  run<T>(body: (device: SessionDevice) => Promise<T>): Promise<T>;
+  screen(): Promise<Screen>;
+  screenshot(path: string): Promise<string>;
+  /** Relaunches the app and re-runs the ready gate. Reported as one step. */
+  relaunch(sink: ActionSink): Promise<void>;
+  dismissDevOverlay(): Promise<void>;
+  awaitReady(deadline: number): Promise<void>;
+  /** Idempotent. Never shuts the simulator down, and reaches `closed` even when the driver call fails. */
+  close(reason: 'requested' | 'worker-exit'): Promise<void>;
+};
+type OpenSessionInput = {
+  readonly options: ResolvedOptions;
+  /** The runner's stable worker slot. Playwright passes `parallelIndex`, which a replacement worker reuses. */
+  readonly slot: number;
+  /** The runner's project name. Part of the session name so two projects never share one. */
+  readonly scope: string;
+  readonly sink: ActionSink;
+  readonly createDriver: (session: string, selection: DeviceSelection) => DeviceDriver;
+};
+/**
+ * Convergent startup. Running it twice settles on one ready session. In order:
+ * reclaim a leftover session of the same name, open with the selection carried
+ * on that first command, recover once from a device claimed by a leftover or
+ * under `onDeviceInUse: 'reclaim'`, recover once from a session bound to another
+ * device, then hold until `readyWhen` resolves, because `open` returns while the
+ * JavaScript bundle is still loading.
+ */
+declare function openSession(input: OpenSessionInput): Promise<DeviceSession>;
+/** Deterministic, so a worker replaced after a failure reconnects to the session it left behind. */
+declare function sessionName(options: ResolvedOptions, project: string, slot: number): string;
+//#endregion
+//#region src/core/device.d.ts
+type TextOptions = {
+  exact?: boolean;
+};
+type RoleOptions = {
+  name?: string | RegExp;
+  exact?: boolean;
+};
+type ActionOptions = {
+  timeout?: number;
+};
+/**
+ * `hasText` matches the node's own text or any text in its subtree, while
+ * `has` needs a strict descendant. That asymmetry matches Playwright.
+ */
+type FilterOptions = {
+  hasText?: string | RegExp;
+  hasNotText?: string | RegExp;
+  has?: Locator;
+  hasNot?: Locator;
+};
+/**
+ * `secret` reports only a character count, for a credential field the platform
+ * did not mark secure. The write is still confirmed character by character,
+ * because a plain field hands back its exact contents.
+ */
+type FillOptions = ActionOptions & {
+  secret?: boolean;
+};
+type Device = {
+  /** Matches a node's accessibility name or its value. */
+  getByText(text: string | RegExp, options?: TextOptions): Locator;
+  getByRole(role: Role, options?: RoleOptions): Locator;
+  /** Matches the accessibility identifier, which is what a React Native `testID` becomes. */
+  getByTestId(testId: string): Locator;
+  locator(query: Query): Locator;
+  scroll(direction: ScrollDirection): Promise<void>;
+  /** Relaunches the app and waits for the ready gate again. */
+  relaunch(): Promise<void>;
+  /** Never automatic, because hiding the overlay would suppress a warning a test might want to see. */
+  dismissDevOverlay(): Promise<void>;
+  screen(): Promise<Screen>;
+  /** Returns the path. Nothing is attached to the report, so the caller decides whether to. */
+  screenshot(options?: {
+    path?: string;
+  }): Promise<string>;
+};
+/** A query bound to a session. Safe to hold across an action, because it stores a query and never a ref. */
+type Locator = {
+  readonly query: Query;
+  /** The device this locator came from. A screenshot assertion needs the image and the tree, and a locator carries neither. */
+  readonly device: Device;
+  /** The factory call this locator renders back to, used in step titles and failure messages. */
+  readonly description: string;
+  first(): Locator;
+  /** Negative indexes count from the end, so `nth(-1)` is the last match. */
+  nth(index: number): Locator;
+  filter(options: FilterOptions): Locator;
+  tap(options?: ActionOptions): Promise<void>;
+  fill(text: string, options?: FillOptions): Promise<void>;
+  longPress(durationMs?: number, options?: ActionOptions): Promise<void>;
+  /** Actions scroll for themselves, so this is for seeing a node rather than acting on it. */
+  scrollIntoView(options?: ActionOptions): Promise<void>;
+  count(): Promise<number>;
+  /** The matched node's text off one fresh screen. Null when nothing matches. Ambiguity fails the way an action does. */
+  textContent(): Promise<string | null>;
+  expect(check: Check, options: ProbeOptions): Promise<ProbeResult>;
+};
+declare function createDevice(session: DeviceSession, sink: ActionSink): Device;
+//#endregion
+//#region src/core/scroll.d.ts
+/** For a failure message. */
+type ScrollTrail = {
+  readonly steps: number;
+  readonly direction: ScrollDirection;
+};
+/** What a scroll search needs from a session. A `SessionDevice` supplies it. */
+type ScrollDevice = {
+  captureRaw(): Promise<Screen>;
+  scroll(direction: ScrollDirection, budgetMs: number): Promise<void>;
+};
+/**
+ * Two rules. A search never reverses, because a hint pointing back the way it
+ * came means the container ran out rather than that the target is behind, and
+ * reversing turns a finished search into an oscillation that burns the budget.
+ * And it stops at `maxSteps` whatever the clock says, so a screen that scrolls
+ * forever cannot run indefinitely.
+ */
+type ScrollSearch = {
+  /** Null until the first step, then the one direction every later step uses. */
+  trail(): ScrollTrail | null;
+  /**
+   * Scrolls one step toward whatever `query` names. False means the search is
+   * over: nothing on screen says which way to go, the next hint would reverse,
+   * or the step cap is spent.
+   */
+  step(screen: Screen, query: Query, budgetMs: number): Promise<boolean>;
+};
+declare function createScrollSearch(device: ScrollDevice, maxSteps?: number): ScrollSearch;
+/**
+ * Which way the target lies, or null when nothing on screen says.
+ *
+ * The raw tree places the target itself, so when it carries the node, its rect
+ * against the clipping container's rect is an answer rather than a guess. That
+ * is the iOS case. Android's raw tree stops at the window, so the only evidence
+ * left is the container reporting it holds content out of view.
+ */
+declare function directionToward(screen: Screen, raw: Screen | null, query: Query): ScrollDirection | null;
+//#endregion
+//#region src/core/errors.d.ts
+/**
+ * The most a failure may say about the text that was typed. A secure field
+ * reports one masking character per character it holds, so its length is all it
+ * can report, and a field marked secret discloses a length too. A password has
+ * no representation here, which keeps it out of a terminal and an HTML report.
+ */
+type ExpectedValue = {
+  readonly kind: 'exact';
+  readonly value: string;
+} | {
+  readonly kind: 'masked';
+  readonly length: number;
+};
+/**
+ * One class with a closed `info` union, so adapters and test authors switch on
+ * `info.kind` and the compiler names a missing case when a kind is added.
+ */
+type ErrorInfo = {
+  readonly kind: 'config';
+  readonly field: string;
+  readonly detail: string;
+} | {
+  readonly kind: 'device-in-use';
+  readonly owner: string | null;
+  readonly device: string;
+  readonly releaseCommand: string;
+  /** False once `onDeviceInUse: 'reclaim'` is already set, so the message stops suggesting it. */
+  readonly canReclaim: boolean;
+} | {
+  readonly kind: 'launch-failed';
+  readonly app: string;
+  readonly device: string;
+  readonly failure: DeviceFailure;
+} | {
+  readonly kind: 'not-ready';
+  readonly locator: string;
+  readonly timeoutMs: number;
+  readonly screen: string;
+} | {
+  readonly kind: 'session-closed';
+  readonly command: string;
+} | {
+  readonly kind: 'strict-mode';
+  readonly locator: string;
+  readonly matches: readonly string[];
+  readonly screen: string;
+} | {
+  readonly kind: 'not-found';
+  readonly locator: string;
+  readonly timeoutMs: number;
+  readonly screen: string;
+  /** What the search scrolled looking for it, or null when it never scrolled. */
+  readonly scrolled: ScrollTrail | null;
+} | {
+  readonly kind: 'fill-unconfirmed';
+  readonly locator: string;
+  readonly expected: ExpectedValue;
+  readonly actual: ExpectedValue | null;
+  readonly attempts: number;
+  readonly timeoutMs: number;
+  readonly screen: string;
+} | {
+  readonly kind: 'driver';
+  readonly command: string;
+  readonly failure: DeviceFailure;
+};
+declare class TangereError extends Error {
+  readonly info: ErrorInfo;
+  constructor(info: ErrorInfo);
+}
+//#endregion
+//#region src/preflight.d.ts
+type PreflightDevice = {
+  readonly name: string;
+  readonly id: string;
+};
+type PreflightReport = {
+  readonly ok: true;
+  readonly device: PreflightDevice;
+} | {
+  readonly ok: false;
+  readonly problems: readonly string[];
+};
+/**
+ * A device that is not booted is reported as problems rather than thrown, so a
+ * runner names every one of them at once. A malformed config still throws, the
+ * way it does everywhere else. `driver` is the seam tests inject.
+ */
+declare function preflight(options: Partial<TangereOptions>, driver?: DeviceDriver): Promise<PreflightReport>;
+//#endregion
+export { Tree as $, deviceNameForSlot as A, ProbeResult as B, openSession as C, ResolvedOptions as D, ReadyQuery as E, StepOptions as F, CaptureOptions as G, formatFailure as H, Typed as I, DeviceInfo as J, DeviceDriver as K, renderTitle as L, ActionRecord as M, ActionSink as N, TANGERE_DEFAULTS as O, EvidenceFile as P, Settled as Q, silentSink as R, SessionState as S, DeviceChoice as T, probe as U, ProbeTarget as V, Binding as W, OpenRequest as X, DeviceSelection as Y, ScrollDirection as Z, RoleOptions as _, Screen as _t, ExpectedValue as a, Filter as at, DeviceSession as b, renderScreen as bt, ScrollSearch as c, TextMatch as ct, directionToward as d, textMatch as dt, Check as et, ActionOptions as f, PinnedRef as ft, Locator as g, Resolution as gt, FilterOptions as h, Rect as ht, ErrorInfo as i, evaluate as it, parseDeviceOptions as j, TangereOptions as k, ScrollTrail as l, describeQuery as lt, FillOptions as m, RawSnapshot as mt, PreflightReport as n, Verdict as nt, TangereError as o, Query as ot, Device as p, Platform as pt, DeviceFailure as q, preflight as r, describeCheck as rt, ScrollDevice as s, Role as st, PreflightDevice as t, CheckName as tt, createScrollSearch as u, normalizeText as ut, TextOptions as v, ScreenNode as vt, sessionName as w, OpenSessionInput as x, resolve as xt, createDevice as y, parseScreen as yt, ProbeOptions as z };