@lingxia/types 0.17.0 → 0.19.0

package/src/automation/index.ts

@@ -1,9 +1,20 @@
 /**
  * In-process UI/runtime automation — `lx.automation()`.
  *
- * Returns a stable selector root. Selecting the calling lxapp requires the
- * `automation` security privilege; cross-lxapp and host surfaces require
- * `host`. `lingxia dev` sessions and the Runner grant both implicitly.
+ * Two roots share one runtime object:
+ *
+ * - {@link Automation} is what app Logic may call. Selecting the calling lxapp
+ *   requires the `automation` security privilege; cross-lxapp and host
+ *   surfaces require `host`. A session holds one only when the privilege
+ *   class is allowed for the app (the app registry, or its unrestricted
+ *   default) and the native host seals a matching session grant — from a
+ *   product `HostAddon`, or a devtools host such as the Runner, which grants
+ *   the allowed automation privileges and nothing beyond them. Neither
+ *   `lingxia dev` nor the Runner widens what app Logic is allowed.
+ * - {@link HostRunAutomation} is the root of a host automation run
+ *   (`lxdev test`). That context carries the host's own authority, so every
+ *   selector is available without a grant, and it adds the test-run-only
+ *   members: `network`, nav `waitUntil: 'ready'`, and eval call tracing.
  *
  * This mirrors the devtool (`lxdev`) automation surface as a privilege-scoped,
  * product-side API.
@@ -13,30 +24,113 @@ import type { TerminalSettingsValue } from '../generated/logic.js';
 
 // ============================ factory ============================
 
-/** Stable automation root; it grants no capability until one is selected. */
+// ============================ errors ============================
+
+/**
+ * Stable `code`s of automation driver rejections. Anything without a more
+ * specific code rejects with `E_AUTOMATION`. Desktop codes describe OS
+ * automation failures. Match on the code, not the message.
+ */
+export const AUTOMATION_ERROR_CODES = [
+  /** Fallback for a failure with no more specific code. */
+  'E_AUTOMATION',
+  /** A scenario changed only partially or its outcome is unknown; the run is revoked. */
+  'E_SCENARIO_STATE_UNKNOWN',
+  /** The caller lacks the `automation`/`host` privilege the call needs. */
+  'E_AUTOMATION_PRIVILEGE',
+  /** The target page is not the active instance: not open, or replaced. `data: { page, instanceId?, current? }`. */
+  'E_PAGE_NOT_ACTIVE',
+  /** The page has no WebView or current page to act on yet. */
+  'E_PAGE_NOT_READY',
+  /** A page action (`page.action`) rejected without a code of its own. `data: { action, cause }`. */
+  'E_PAGE_ACTION',
+  /** No element matched the selector at dispatch. */
+  'E_ELEMENT_NOT_FOUND',
+  /** The element matched but cannot take the input (disabled, not editable, …). */
+  'E_ELEMENT_NOT_INTERACTABLE',
+  /** A driver wait (`waitFor`, `waitUntil: 'ready'`, …) ran out of time. */
+  'E_AUTOMATION_TIMEOUT',
+  /** The evaluated script threw. */
+  'E_EVAL_SCRIPT',
+  /** The evaluation did not settle within its `timeoutMs`. */
+  'E_EVAL_TIMEOUT',
+  /** Profile rollback outside an isolated run (`lxdev test --profile`), or for an lxapp the run does not isolate. */
+  'E_PROFILE_NOT_ISOLATED',
+  /** A test clock call needs an installed clock and none is; an app that reopened is back on real time. */
+  'E_CLOCK_NOT_INSTALLED',
+  /** `clock.install()` while this lxapp's Logic already runs on a test clock. */
+  'E_CLOCK_INSTALLED',
+  'E_DESKTOP_USAGE',
+  'E_DESKTOP_NOT_FOUND',
+  'E_DESKTOP_AMBIGUOUS',
+  'E_DESKTOP_TIMEOUT',
+  'E_DESKTOP_PERMISSION',
+  'E_DESKTOP_UNSUPPORTED',
+  'E_DESKTOP_UNAVAILABLE',
+  'E_DESKTOP_STALE',
+  'E_DESKTOP_FAILED',
+] as const;
+
+export type AutomationErrorCode = (typeof AUTOMATION_ERROR_CODES)[number];
+
+/** A page as automation error `data` names it. */
+export interface AutomationPageRef {
+  /** Configured page name, else its path. */
+  page?: string;
+  /** The page instance the call resolved to, when it still resolves. */
+  instanceId?: string;
+  /** The page that was current when the call failed. */
+  current?: { name: string | null; path: string; instanceId: string };
+}
+
+/**
+ * Automation root as app Logic sees it (`lx.automation()` in Logic). It grants
+ * no capability until one is selected. Reading a driver property never throws:
+ * each driver method checks the caller and rejects with
+ * `E_AUTOMATION_PRIVILEGE` when it is not allowed.
+ */
 export interface Automation {
-  /** Drive the calling/current lxapp. Requires `automation` outside dev. */
-  lxapp(): LxAppDriver;
-  /** Drive a specific running lxapp. Requires `host` outside dev. */
-  lxapp(appid: string): LxAppDriver;
-  /** Cross-lxapp lifecycle and host-window capture. */
+  /**
+   * Drive the calling lxapp. Requires the `automation` privilege. Evaluating
+   * the calling Logic runtime itself (`eval`) rejects.
+   */
+  lxapp(): LogicLxAppDriver;
+  /** Drive a specific running lxapp. Requires the `host` privilege. */
+  lxapp(appid: string): LogicLxAppDriver;
+  /** Cross-lxapp lifecycle and host-window capture. Requires `host`. */
   readonly lxapps: LxAppManager;
-  /** The host app's browser tabs. */
+  /** The host app's browser tabs. Requires `host`. */
   readonly browser: BrowserDriver;
-  /** Persisted host-shell shortcuts for deterministic test setup/assertion. */
+  /** Persisted host-shell shortcuts for deterministic test setup/assertion. Requires `host`. */
   readonly shell: ShellDriver;
-  /** Simulated-device selection in a host runner. */
+  /** Simulated-device selection in a host runner. Requires `host`. */
   readonly device: DeviceDriver;
   /**
-   * Session-less local-OS desktop automation (`lxdev desktop`). Beyond the
-   * app sandbox, so restricted to dev/test hosts (`lingxia dev` or the
-   * Runner) on top of the `host` privilege. Windows/macOS only.
+   * Session-less local-OS desktop automation (`lxdev desktop`). Windows/macOS
+   * only. Gated by the `host` privilege alone, and present only in hosts
+   * built with desktop automation (the Runner, or a product that enables the
+   * `desktop-automation` feature); elsewhere reading it throws. It drives the
+   * whole OS, beyond the app sandbox — grant `host` only to lxapps you trust
+   * with that.
    */
   readonly desktop: DesktopDriver;
-  /** Native terminal workspace state and pane actions in trusted dev/test hosts. */
+  /** Native terminal workspace state and pane actions. Requires `host`. */
   readonly terminal: TerminalDriver;
 }
 
+/**
+ * Automation root of a host automation run — `rawAutomation()` (and, traced,
+ * `t.automation`) from `@lingxia/test` in an `lxdev test` program. The run
+ * carries host authority, so no selector needs a privilege grant, and the
+ * selected lxapp driver adds the test-run-only members.
+ */
+export interface HostRunAutomation extends Automation {
+  /** Drive the host's current lxapp. */
+  lxapp(): LxAppDriver;
+  /** Drive a specific running lxapp. */
+  lxapp(appid: string): LxAppDriver;
+}
+
 // ========================== terminal tier ==========================
 
 export type TerminalSplitDirection = 'left' | 'right' | 'up' | 'down';
@@ -114,7 +208,10 @@ export interface TerminalSplitOptions extends TerminalSurfaceRef {
   direction: TerminalSplitDirection;
 }
 
-/** Native terminal automation; available only to trusted dev/test hosts. */
+/**
+ * Native terminal automation. Requires the `host` privilege from app Logic
+ * (a host automation run needs none) and a host with a native terminal.
+ */
 export interface TerminalDriver {
   snapshot(options: TerminalSurfaceRef): Promise<TerminalWorkspaceSnapshot>;
   /** Send text to the focused pane, as if typed into its PTY. */
@@ -162,6 +259,8 @@ export type SetAutomationShellPinOptions = AutomationShellPin & {
 export interface ShellDriver {
   /** Ordered shortcuts exactly as projected into the host sidebar. */
   pins(): Promise<AutomationShellPin[]>;
+  /** Submit every current Pin exactly once, in the desired mixed order. */
+  reorderPins(items: AutomationShellPin[]): Promise<AutomationShellPin[]>;
   /**
    * Idempotently persist or remove one shortcut. New Pins append to the
    * existing order; adding beyond the host limit rejects without mutation.
@@ -174,7 +273,7 @@ export interface ShellDriver {
 
 /** Fields common to every page action; `page` defaults to the current page. */
 export interface PageTarget {
-  /** Configured page name (from lxapp.json); defaults to the current page. */
+  /** Configured page name or live instance_id; defaults to the current page. */
   page?: string;
 }
 
@@ -184,6 +283,15 @@ export interface PageEvalOptions extends PageTarget {
   timeoutMs?: number;
 }
 
+export interface PageActionOptions extends PageTarget {
+  /** Name of a unary action of the page's `Page({...})`; stream (generator) actions are refused. */
+  name: string;
+  /** The action's one JSON argument, passed as is; omit for none. */
+  payload?: unknown;
+  /** Budget for the page to become ready and the action to settle (default 5000). */
+  timeoutMs?: number;
+}
+
 export interface PageQueryOptions extends PageTarget {
   /** CSS selector. */
   css: string;
@@ -207,6 +315,20 @@ export interface PageTypeOptions extends PageSelectorOptions {
   text: string;
 }
 
+export interface PageClickOptions extends PageSelectorOptions {
+  /**
+   * Dispatch to the element itself, without the in-viewport and hit-test
+   * checks; it must still exist and be enabled. For content no scroll can
+   * bring under the pointer, such as the lower part of an overflowing sheet.
+   */
+  force?: boolean;
+}
+
+export interface PageFillOptions extends PageTypeOptions {
+  /** Write without the in-viewport check; see `PageClickOptions.force`. */
+  force?: boolean;
+}
+
 export interface PagePressOptions extends PageTarget {
   /** Key name, e.g. `Enter`, `Escape`, `Tab`. */
   key: string;
@@ -228,23 +350,31 @@ export interface PageScrollToOptions extends PageTarget {
   css: string;
 }
 
+/**
+ * Raw `page.waitFor` states check the first match of `css`:
+ * - `attached`: at least one match.
+ * - `detached`: no match (also while the page is not yet active).
+ * - `visible`: the first match is rendered (a non-empty box, not
+ *   `display:none`, `visibility:hidden` or `opacity:0`), in the viewport or
+ *   scrolled out of it.
+ * - `hidden`: the first match exists and is not rendered; no match does not
+ *   satisfy it (wait for `detached`).
+ * - `enabled` / `editable`: the first match exists and is enabled / editable.
+ * `@lingxia/test` locators apply stricter, uniqueness-aware states.
+ */
 export type PageWaitState =
   | 'attached'
   | 'detached'
   | 'visible'
   | 'hidden'
   | 'enabled'
-  | 'editable'
-  /** @deprecated Use `attached`. */
-  | 'exists'
-  /** @deprecated Use `detached`. */
-  | 'gone';
+  | 'editable';
 
 export interface PageWaitForOptions extends PageTarget {
   css: string;
   /** Condition to await (default `visible`). */
   state?: PageWaitState;
-  /** Timeout in ms (default 10000, capped at 60000). */
+  /** Timeout in ms (default 30000, capped at 60000). */
   timeoutMs?: number;
 }
 
@@ -261,13 +391,13 @@ export interface ElementRect {
   height: number;
   right: number;
   bottom: number;
-  center_x: number;
-  center_y: number;
-  viewport_width: number;
-  viewport_height: number;
+  centerX: number;
+  centerY: number;
+  viewportWidth: number;
+  viewportHeight: number;
 }
 
-/** A matched element. Keys are the raw automation payload (snake_case). */
+/** A matched element. Uses JavaScript field names. */
 export interface PageElement {
   exists: true;
   index: number;
@@ -279,16 +409,21 @@ export interface PageElement {
   id: string | null;
   name: string | null;
   role: string | null;
-  aria_label: string | null;
+  ariaLabel: string | null;
   placeholder: string | null;
-  /** Viewport-aware visibility (size, style, and in-viewport). */
+  /**
+   * Rendered: a non-empty box that is not `display:none`,
+   * `visibility:hidden` or `opacity:0`, wherever it is scrolled.
+   */
   visible: boolean;
+  /** Rendered and intersecting the viewport. */
+  inViewport: boolean;
   enabled: boolean;
   editable: boolean;
   text: string;
-  text_truncated: boolean;
+  textTruncated: boolean;
   value: string | null;
-  value_truncated: boolean;
+  valueTruncated: boolean;
   rect: ElementRect;
 }
 
@@ -298,6 +433,7 @@ export interface PageElementMiss {
   index: number;
   count: number;
   visible: false;
+  inViewport: false;
   enabled: false;
   editable: false;
 }
@@ -320,17 +456,27 @@ export interface Screenshot {
 
 /** Element-level automation of the selected lxapp's page WebViews. */
 export interface PageDriver {
-  /** Evaluate JavaScript in the page WebView; resolves to the returned value. */
-  eval(options: PageEvalOptions): Promise<unknown>;
+  /** Evaluate in the page WebView. T describes the expected JSON result; it is not runtime validation. */
+  eval<T = unknown>(options: PageEvalOptions): Promise<T>;
+  /**
+   * Invoke a page action as the View would and resolve to its JSON result.
+   * Waits for the page's runtime within `timeoutMs`. A rejection keeps the
+   * action's own `code` and message (`data.cause` has what it rejected with);
+   * `E_PAGE_NOT_READY` if the page never loaded its actions,
+   * `E_AUTOMATION_TIMEOUT` if the action did not settle in time.
+   */
+  action<T = unknown>(options: PageActionOptions): Promise<T>;
   /** Query one element's info. */
   query(options: PageQueryOptions & { all?: false }): Promise<PageQueryResult>;
   /** Query every matching element. */
   query(options: PageQueryOptions & { all: true }): Promise<PageQueryAll>;
-  click(options: PageSelectorOptions): Promise<void>;
+  query(options: PageQueryOptions): Promise<PageQueryResult | PageQueryAll>;
+  /** Single dispatch; test locators provide actionability waiting. */
+  click(options: PageClickOptions): Promise<void>;
   /** Type text into an element without clearing existing content. */
   type(options: PageTypeOptions): Promise<void>;
   /** Replace an element's current value. */
-  fill(options: PageTypeOptions): Promise<void>;
+  fill(options: PageFillOptions): Promise<void>;
   press(options: PagePressOptions): Promise<void>;
   /** Scroll the first matching element into view. */
   scrollTo(options: PageScrollToOptions): Promise<void>;
@@ -347,56 +493,104 @@ export interface PageDriver {
 
 // ============================ nav tier ============================
 
-export interface NavOptions {
+/**
+ * When a nav action resolves. `'commit'` (default) resolves once the page
+ * stack changed, before the landed page is ready. `'ready'` also waits for its
+ * `onReady` and rejects if the page is disposed or replaced first (e.g. by the
+ * app's own `lx.reLaunch`); it is available only in a host automation run
+ * ({@link NavDriver}), since app Logic awaiting its own `onReady` would
+ * deadlock. The `@lingxia/test` fixture's `t.app.nav` defaults to `'ready'`.
+ */
+export type NavWaitUntil = 'commit' | 'ready';
+
+/** Nav wait options available to app Logic: only `'commit'`. */
+export interface LogicNavWaitOptions {
+  waitUntil?: 'commit';
+}
+
+/** Nav wait options of a host automation run. */
+export interface NavWaitOptions {
+  waitUntil?: NavWaitUntil;
+  /** Bound for `waitUntil: 'ready'` in ms (default 15000, capped at 60000). */
+  timeoutMs?: number;
+}
+
+interface NavTargetFields {
   /** Configured page name (from lxapp.json). */
   page: string;
   /** Query forwarded to the destination page. */
   query?: Record<string, unknown>;
 }
 
-export interface NavBackOptions {
+interface NavBackFields {
   /** Number of pages to pop (default 1). */
   delta?: number;
 }
 
+export interface LogicNavOptions extends NavTargetFields, LogicNavWaitOptions {}
+export interface LogicNavBackOptions extends NavBackFields, LogicNavWaitOptions {}
+export interface NavOptions extends NavTargetFields, NavWaitOptions {}
+export interface NavBackOptions extends NavBackFields, NavWaitOptions {}
+
 /** A page's runtime position. */
 export interface PageInfo {
   path: string;
   /** Configured page name, if the path maps to one. */
   name: string | null;
+  /**
+   * The page instance. Navigation that replaces a page (even with the same
+   * path) gives it a new id. `null` when no live instance backs a stack
+   * entry.
+   */
+  instanceId: string | null;
   current: boolean;
   inStack: boolean;
-  /** Whether the page has an attached WebView. */
+  /** Whether the page has dispatched `onReady` (what `waitUntil: 'ready'` awaits). */
   ready: boolean;
+  /** Whether the page currently has an attached WebView; precedes `ready`. */
+  webviewAttached: boolean;
 }
 
 /**
- * Page-stack navigation for the selected lxapp. Action verbs take a configured
- * page name (`redirect` rejects a tab-bar page); `back` pops; `current`/`stack`
- * read. Unlike the JS `lx.navigateTo` family this returns the landed page, but
- * like it does not wait for the destination WebView (awaiting in-process would
- * deadlock the logic thread).
+ * Page-stack navigation for the selected lxapp, as app Logic sees it. Action
+ * verbs take a configured page name (`redirect` rejects a tab-bar page);
+ * `back` pops; `current`/`stack` read. Unlike the JS `lx.navigateTo` family
+ * this returns the landed page. It resolves once the stack changed, before the
+ * destination is ready.
  */
-export interface NavDriver {
+export interface LogicNavDriver {
   /** Push a page onto the stack. */
-  to(options: NavOptions): Promise<PageInfo>;
+  to(options: LogicNavOptions): Promise<PageInfo>;
   /** Replace the current page (rejects tab-bar targets). */
-  redirect(options: NavOptions): Promise<PageInfo>;
+  redirect(options: LogicNavOptions): Promise<PageInfo>;
   /** Switch to a configured tab page. */
-  switchTab(options: NavOptions): Promise<PageInfo>;
-  /** Clear the stack and relaunch at a page. */
-  relaunch(options: NavOptions): Promise<PageInfo>;
-  back(options?: NavBackOptions): Promise<PageInfo>;
+  switchTab(options: LogicNavOptions): Promise<PageInfo>;
+  /** Unload every page (cached tab pages included) and open a fresh instance of a page. */
+  relaunch(options: LogicNavOptions): Promise<PageInfo>;
+  back(options?: LogicNavBackOptions): Promise<PageInfo>;
   current(): Promise<PageInfo>;
   /** Status of a configured page by name; omit `page` for the current page. */
   info(options?: PageTarget): Promise<PageInfo>;
   stack(): Promise<PageInfo[]>;
 }
 
+/**
+ * Page-stack navigation in a host automation run. Same verbs as
+ * {@link LogicNavDriver}; pass `waitUntil: 'ready'` to also wait for the
+ * landed page's `onReady`.
+ */
+export interface NavDriver extends LogicNavDriver {
+  to(options: NavOptions): Promise<PageInfo>;
+  redirect(options: NavOptions): Promise<PageInfo>;
+  switchTab(options: NavOptions): Promise<PageInfo>;
+  relaunch(options: NavOptions): Promise<PageInfo>;
+  back(options?: NavBackOptions): Promise<PageInfo>;
+}
+
 // ============================ lxapp driver ============================
 
 export interface LxAppSummary {
-  appid: string;
+  appId: string;
   currentPage: string | null;
 }
 
@@ -405,21 +599,39 @@ export interface LxAppPageConfig {
   path: string;
 }
 
-export interface LxAppEvalOptions {
+/**
+ * Envelope `eval` resolves to with `captureCalls: true`.
+ *
+ * @internal Report plumbing for the test runner; the `@lingxia/test` fixture
+ * unwraps it, and specs never see it.
+ */
+export interface LxAppEvalTrace<T = unknown> {
+  __lxEval: 1;
+  value: T;
+  calls: string[];
+}
+
+/** Logic-runtime eval options available to app Logic. */
+export interface LogicLxAppEvalOptions {
   /** JavaScript expression or function body run in the selected Logic runtime. */
   script: string;
   timeoutMs?: number;
+}
+
+/** Logic-runtime eval options of a host automation run. */
+export interface LxAppEvalOptions extends LogicLxAppEvalOptions {
   /**
    * Resolve to `{ value, calls }`, where `calls` lists the `lx.*` members the
    * script reached, instead of the bare value.
    *
-   * The test runner sets this so a report can tell a capability a spec
-   * exercised from one it merely declared. Only the evaluated script is
+   * @internal The test runner sets this so a report can tell a capability a
+   * spec exercised from one it merely declared. Only the evaluated script is
    * observed — the lxapp's own concurrent work is not.
    */
   captureCalls?: boolean;
 }
 
+/** Shell admission class. Content `lx.surface.watchContext` uses `compact` | `regular`. */
 export type SurfaceLayoutSizeClass = 'compact' | 'medium' | 'expanded';
 export type SurfaceLayoutSwitcherForm = 'none' | 'sidebar' | 'rail';
 export type SurfaceLayoutSplitForm = 'none' | 'split' | 'collapsible' | 'fullScreen';
@@ -517,18 +729,711 @@ export interface SurfaceLayoutSnapshot {
   tree?: SurfaceLayoutTree;
 }
 
-/** Capability for one selected running lxapp. */
-export interface LxAppDriver {
+// ======================= test network routing =======================
+
+/**
+ * Which Logic `fetch` requests a route handles: a URL glob over the whole URL
+ * (`**` any characters, `*` any except `/`, `{a,b}` alternatives; `?` is
+ * literal), a `RegExp` searched like `RegExp.test` (Rust regex syntax: no
+ * lookaround or backreferences), or either plus a method and a match budget.
+ */
+export type NetworkRoutePattern =
+  | string
+  | RegExp
+  | {
+    url: string | RegExp;
+    /** Case-insensitive HTTP method; omit or `'*'` for any. */
+    method?: string;
+    /** Remove the route after this many matched requests. */
+    times?: number;
+  };
+
+type NetworkRouteFulfillKey =
+  | 'status'
+  | 'statusText'
+  | 'headers'
+  | 'contentType'
+  | 'body'
+  | 'json'
+  | 'delay';
+type NetworkRouteForbid<K extends string> = Partial<Record<K, never>>;
+
+interface NetworkRouteFulfillFields {
+  /** 200..=599. Default 200. */
+  status?: number;
+  statusText?: string;
+  headers?: Record<string, string>;
+  /** Sets `content-type` unless `headers` already has one. */
+  contentType?: string;
+  /**
+   * Milliseconds to wait before the response resolves, 0..=30000; an
+   * `AbortSignal` passed to `fetch` still rejects it early.
+   */
+  delay?: number;
+}
+
+/**
+ * Answer the request without touching the network. The body is either `body`
+ * (text or bytes, sent verbatim) or `json` (serialized, implies
+ * `content-type: application/json`), never both.
+ */
+export type NetworkRouteFulfill = NetworkRouteFulfillFields &
+  NetworkRouteForbid<'abort' | 'continue' | 'patchJson' | 'hang' | 'sse' | 'sequence'> &
+  (
+    | { body?: string | ArrayBuffer | Uint8Array; json?: never }
+    | { json: unknown; body?: never }
+  );
+
+/**
+ * Reject the `fetch` like a transport failure (`TypeError: fetch failed`).
+ * `'failed'` is the only failure the wrapper emulates.
+ */
+export type NetworkRouteAbort = { abort: 'failed' } &
+  NetworkRouteForbid<NetworkRouteFulfillKey | 'continue' | 'patchJson' | 'hang' | 'sse' | 'sequence'>;
+
+/**
+ * Let the request reach the network, shadowing older matching routes. With
+ * `patchJson`, the real response's JSON body is rewritten host-side by that
+ * RFC 7396 merge patch: object keys merge, `null` deletes a key, and any
+ * other value (arrays included) replaces what it patches. Status and headers
+ * stay the real ones. A body that is not JSON rejects the `fetch` with a
+ * `TypeError` naming the URL; an empty body passes through. The patched
+ * body is re-serialized, so object keys come back sorted.
+ */
+export type NetworkRouteContinue = { continue: true; patchJson?: unknown } &
+  NetworkRouteForbid<NetworkRouteFulfillKey | 'abort' | 'hang' | 'sse' | 'sequence'>;
+
+/**
+ * Never answer: the `fetch` stays pending until the route is removed (the
+ * spec ends, `unroute()`, or the run ends), then rejects like a transport
+ * failure. An `AbortSignal` passed to `fetch` still rejects it early. For
+ * loading states and client-side timeouts. `times` limits which requests are
+ * held, not how long.
+ */
+export type NetworkRouteHang = { hang: true } &
+  NetworkRouteForbid<NetworkRouteFulfillKey | 'abort' | 'continue' | 'patchJson' | 'sse' | 'sequence'>;
+
+/**
+ * One item of an SSE answer, played in order: an event (`data` that is not a
+ * string is sent as JSON; multi-line data becomes several `data:` lines), a
+ * `comment` line, a pause of `delayMs` (0..=30000), or `drop`, which closes
+ * the stream as a server dropping the connection would and must come last.
+ */
+export type NetworkSseItem =
+  | { event?: string; data: unknown; id?: string; retry?: number }
+  | { comment: string }
+  | { delayMs: number }
+  | { drop: true };
+
+/**
+ * Answer with a `text/event-stream` (status 200) that plays `sse`. Without a
+ * final `{ drop: true }` the stream stays open after its last item, like a
+ * live server, until the route is removed. `Rong.SSE` in Logic receives the
+ * events and, after a drop, reconnects with `Last-Event-ID`, which the next
+ * answer of a `sequence` can serve. `delay` (0..=30000 ms) holds the response
+ * before it opens.
+ */
+export type NetworkRouteSse = {
+  sse: NetworkSseItem[];
+  headers?: Record<string, string>;
+  delay?: number;
+} & NetworkRouteForbid<
+  'status' | 'statusText' | 'contentType' | 'body' | 'json' | 'abort' | 'continue' | 'patchJson' | 'hang' | 'sequence'
+>;
+
+/** Exactly one of fulfill, abort, continue, hang, or sse. */
+export type NetworkRouteAnswer =
+  | NetworkRouteFulfill
+  | NetworkRouteAbort
+  | NetworkRouteContinue
+  | NetworkRouteHang
+  | NetworkRouteSse;
+
+/**
+ * Answers served in call order: the first matched request gets the first
+ * answer, and the last answer repeats. Answers take text or `json` bodies,
+ * not bytes. Combine with a pattern's `times` to stop matching.
+ */
+export type NetworkRouteSequence = { sequence: NetworkRouteAnswer[] } &
+  NetworkRouteForbid<NetworkRouteFulfillKey | 'abort' | 'continue' | 'patchJson' | 'hang' | 'sse'>;
+
+/**
+ * One answer, or a `sequence` of them. String values may contain
+ * relative-time templates rendered each time the answer is served:
+ * `{{now}}`, `{{now-2h}}`, `{{now+30m}}` (ISO-8601 UTC, like
+ * `Date.prototype.toISOString`; units `ms`, `s`, `m`, `h`, `d`) and
+ * `{{nowMs}}` (epoch milliseconds, as text).
+ */
+export type NetworkRouteHandler = NetworkRouteAnswer | NetworkRouteSequence;
+
+/** `bodyBase64` answers: bytes in a file, instead of `body` or `json`. */
+export type ScenarioHttpBinary = NetworkRouteFulfillFields & { bodyBase64: string } &
+  NetworkRouteForbid<'body' | 'json'>;
+
+/**
+ * A `match` value: objects match when every listed key is present and
+ * matches (other keys are ignored), arrays match element by element with the
+ * same length, a `"/regex/flags"` string (flags among `imsu`) matches a
+ * scalar whose text it finds, and any other value matches an equal value.
+ */
+export type ScenarioMatchValue = unknown;
+
+/** Fields every rule may have. */
+type ScenarioRuleCommon = {
+  /** Answer this many matching calls, then stand aside. */
+  times?: number;
+  /** Free text, ignored. */
+  note?: string;
+};
+
+/**
+ * A rule for the app's Logic `fetch` / `Rong.SSE`: `http` is
+ * `"METHOD url-glob"` (`*` for any method; the URL may be `/regex/flags`),
+ * and the answer is a route handler (or `bodyBase64`).
+ */
+export type ScenarioHttpRule = ScenarioRuleCommon & {
+  http: string;
+  function?: never;
+  /** Match the request's JSON body. */
+  match?: { json: ScenarioMatchValue };
+} & (NetworkRouteHandler | ScenarioHttpBinary);
+
+/** How a `function` rule answers one call. */
+export type ScenarioFunctionAnswer = { delay?: number } & (
+  | { result: unknown; error?: never; fault?: never }
+  | { error: { code: string; [key: string]: unknown }; result?: never; fault?: never }
+  | { fault: 'notRun' | 'unknown'; result?: never; error?: never }
+);
+
+/**
+ * A rule for a Worker Function call, answered by the dev session's
+ * companion: `result`, a declared `error`, or a transport `fault`.
+ */
+export type ScenarioFunctionRule = ScenarioRuleCommon & {
+  function: string;
+  http?: never;
+  /** Match the call's arguments. */
+  match?: { args: ScenarioMatchValue };
+} & (
+  | (ScenarioFunctionAnswer & { sequence?: never })
+  | { sequence: ScenarioFunctionAnswer[]; result?: never; error?: never; fault?: never; delay?: never }
+);
+
+export type ScenarioRule = ScenarioHttpRule | ScenarioFunctionRule;
+
+/**
+ * A scenario file: rules tried in file order (the first match answers;
+ * nothing matched goes to the real backend), and named variants whose rules
+ * go before the shared ones. Unknown fields are rejected.
+ */
+export type ScenarioDefinition = {
+  $schema?: string;
+  name?: string;
+  description?: string;
+  rules?: ScenarioRule[];
+  variants?: Record<string, { description?: string; rules: ScenarioRule[] }>;
+};
+
+/**
+ * What `scenario()` accepts: a typed definition, or an imported JSON file,
+ * whose literal types TypeScript widens. Either is validated by the host.
+ */
+export type ScenarioInput =
+  | ScenarioDefinition
+  | { readonly rules: readonly object[]; readonly [key: string]: unknown }
+  | { readonly variants: { readonly [variant: string]: { readonly rules: readonly object[] } }; readonly [key: string]: unknown };
+
+/** One rule of an installed scenario. */
+export interface ScenarioRuleInfo {
+  /** 1-based, in precedence order (the variant's rules first). */
+  index: number;
+  /** `GET **\/wifi/main`, `function orders.submit`. */
+  target: string;
+  kind: 'http' | 'function';
+  /** Calls it answered (`http` rules); `null` for `function` rules. */
+  hits: number | null;
+}
+
+/** One call that reached a scenario. */
+export interface ScenarioCall {
+  /**
+   * Increasing and never reused within its log: the scenario's for `http`
+   * calls, the dev companion's for `function` calls. Calls in one
+   * millisecond differ by it.
+   */
+  seq: number;
+  /** Epoch milliseconds. */
+  time: number;
+  kind: 'http' | 'function';
+  /** `http`: upper-case method and URL. */
+  method?: string;
+  url?: string;
+  /** `http`: the request body, parsed when it is JSON. */
+  body?: unknown;
+  /** `http`: the answered status, `null` for abort/continue/hang or no answer. */
+  status?: number | null;
+  /** `function`: its name, arguments, and `result`/`error`/`fault`/`default`. */
+  function?: string;
+  args?: unknown;
+  outcome?: string;
+  /** The rule that answered, or `null` when none did. */
+  rule: number | null;
+  /** `rule 2 (name:variant)`, `real`, or `companion default`. */
+  answeredBy: string;
+  /** Why no rule matched, when rules targeted the call. */
+  noMatch?: string;
+}
+
+/** `calls()` filter: one rule's target, or its number. */
+export type ScenarioCallFilter = { http: string } | { function: string } | { rule: number };
+
+/**
+ * Calls of one bounded log with a `seq` above the one asked for, oldest
+ * first. The logs drop their oldest entries first: `droppedThrough` is the
+ * highest `seq` a trim took (0 when none), so a reader whose last `seq` is
+ * below it may have missed calls.
+ */
+export interface CallWindow<T> {
+  calls: T[];
+  droppedThrough: number;
+}
+
+/** `mock.reset()` result. */
+export interface MockResetResult {
+  /** The app's new handler generation; `null` when it has no mocks loaded. */
+  generation: number | null;
+  /**
+   * The companion's answer for the run's Functions, `null` when it does not
+   * switch mocks.
+   */
+  function: { reset: boolean; reason?: string } | null;
+}
+
+/** `lx.automation().lxapp().mock` in a host run. */
+export interface MockDriver {
+  /**
+   * Install a scenario file (with one of its variants) for the host run:
+   * `http` rules answer Logic `fetch` before the mock selection, `function`
+   * rules go to the dev session's companion. Validated as a whole; it
+   * replaces the scenario the run installed before (including another app), and the
+   * run's end removes it. Routes added with `network.route()` take
+   * precedence over it.
+   */
+  use(definition: ScenarioInput, variant?: string): Promise<Scenario>;
+  /**
+   * Start the app's mock handler state over: the next intercepted call
+   * evaluates `mocks/index.ts` again. A companion that switches mocks is
+   * asked to do the same for the run.
+   */
+  reset(): Promise<MockResetResult>;
+}
+
+/** Handle returned by `mock.use()`. */
+export interface Scenario {
+  readonly name: string | null;
+  readonly variant: string | null;
+  /** Its rules with their hit counts, read when accessed. */
+  readonly rules: ScenarioRuleInfo[];
+  /** Calls that reached the scenario since it was installed, oldest first. */
+  calls(filter?: ScenarioCallFilter): Promise<ScenarioCall[]>;
+  /**
+   * Calls to one target with a `seq` above `after`. `droppedThrough` counts
+   * the log the target's kind reads (HTTP: the scenario's 200 calls;
+   * Function: the companion's log, across every Function).
+   */
+  callsAfter(target: ScenarioCallFilter, after: number): Promise<CallWindow<ScenarioCall>>;
+  /** Remove the scenario; resolves how many rules were still installed. */
+  unroute(): Promise<number>;
+}
+
+/** One request a route handled, as the app sent it. */
+export interface NetworkRouteRequest {
+  /**
+   * Increasing across the host's request log and never reused: requests in
+   * one millisecond differ by it, and a trim leaves a gap.
+   */
+  seq: number;
+  routeId: number;
+  /** The route's glob or `/source/flags`. */
+  pattern: string;
+  /** Upper-case method. */
+  method: string;
+  url: string;
+  /** Request headers with lower-case names. */
+  headers: Record<string, string>;
+  /**
+   * Request body as UTF-8 text, cut to 64 KiB. `null` when there is none or
+   * it cannot be read without consuming it: a stream, `Blob`, `FormData`, or
+   * the body of a `Request` object passed as `fetch`'s first argument.
+   */
+  body: string | null;
+  /** `body` was cut to the 64 KiB (65536-byte) limit. */
+  bodyTruncated: boolean;
+  /**
+   * `continue` also covers a `patchJson` pass-through; `fulfill` also covers
+   * an `sse` answer.
+   */
+  action: 'fulfill' | 'abort' | 'continue' | 'hang';
+  /** Fulfilled status (200 for `sse`); `null` for abort/continue/hang. */
+  status: number | null;
+  /** Epoch milliseconds. */
+  timestamp: number;
+}
+
+export interface NetworkRoute {
+  readonly id: number;
+  readonly pattern: string;
+  /** Resolves `false` when the route already expired or was removed. */
+  unroute(): Promise<boolean>;
+  /** Requests this route handled, oldest first. */
+  requests(): Promise<NetworkRouteRequest[]>;
+  /**
+   * Requests this route handled with a `seq` above `after`; `droppedThrough`
+   * is the highest `seq` of this route's requests the host log (1000
+   * entries, 16 MiB of bodies, shared by every app and run) dropped.
+   */
+  requestsAfter(after: number): Promise<{ requests: NetworkRouteRequest[]; droppedThrough: number }>;
+}
+
+/**
+ * One Logic `fetch` response recorded by `NetworkDriver.captureResponses()`.
+ * Headers are never recorded, and `url` keeps only scheme, host and path.
+ *
+ * @internal Test-runner plumbing for `lxdev test --openapi`.
+ */
+export interface NetworkResponseRecord {
+  /** Increasing across the run; pass it as `since` to read only newer ones. */
+  seq: number;
+  /** Upper-case method. */
+  method: string;
+  /** `scheme://host[:port]/path`: userinfo, query and fragment removed. */
+  url: string;
+  /**
+   * `route`: a route fulfilled it. `patch`: the real server answered and a
+   * route merge-patched the body. `network`: the real server answered.
+   */
+  source: 'route' | 'patch' | 'network';
+  /** The route's pattern for `route` and `patch`. */
+  pattern: string | null;
+  status: number;
+  contentType: string | null;
+  /** JSON body text, cut to `maxBodyBytes`; `null` for other content types. */
+  body: string | null;
+  bodyTruncated: boolean;
+  /** Epoch milliseconds. */
+  timestamp: number;
+}
+
+/** @internal `NetworkDriver.captureResponses()` options. */
+export interface NetworkCaptureOptions {
+  /** Body bytes kept per response, 1..=1048576. Default 262144. */
+  maxBodyBytes?: number;
+}
+
+/**
+ * Test-only routing of the selected lxapp's Logic `fetch` and `Rong.SSE`.
+ * Available only in a host automation run (`lxdev test`); every route is
+ * removed when that run ends. The newest matching route handles a request; unmatched requests are
+ * untouched. A fulfillment never answers a host the app's network policy
+ * refuses — the request goes to the real `fetch`, which rejects it.
+ * WebView page requests are not routed.
+ */
+export interface NetworkDriver {
+  route(pattern: NetworkRoutePattern, handler: NetworkRouteHandler): Promise<NetworkRoute>;
+  /** Remove every route this run installed for the app; resolves the count. */
+  unrouteAll(): Promise<number>;
+  /**
+   * Run-scoped: requests any route of this automation run handled for the
+   * app, oldest first, across every spec. `t.app.network.calls()` narrows
+   * this to the current spec.
+   */
+  requests(): Promise<NetworkRouteRequest[]>;
+  /**
+   * Record the app's Logic `fetch` responses — status, content type and
+   * JSON body, never headers — until the run ends. A buffered body is read
+   * from a clone without delaying the app's fetch; a streamed one (no or a
+   * large Content-Length) is read once and the app gets an equivalent
+   * buffered `Response`.
+   *
+   * @internal Test-runner plumbing for `lxdev test --openapi`.
+   */
+  captureResponses(options?: NetworkCaptureOptions): Promise<void>;
+  /**
+   * Responses captured for the app in this run, oldest first; `since` skips
+   * records up to that `seq`. `waitMs` (0..3000) first waits for captures
+   * already in flight; one still unfinished is returned by a later read.
+   * Rejects once when unread responses were lost. At most 500 records and
+   * 8 MiB of bodies are kept; the oldest go first.
+   *
+   * @internal Test-runner plumbing for `lxdev test --openapi`.
+   */
+  responses(options?: { since?: number; waitMs?: number }): Promise<NetworkResponseRecord[]>;
+}
+
+/**
+ * Checkpoint and roll back the isolated data profile of a host automation run
+ * (`lxdev test --profile`). Each call rejects with `E_PROFILE_NOT_ISOLATED`
+ * unless the selected lxapp runs on this run's profile, so it can never touch
+ * the app's real data.
+ *
+ * `checkpoint` and `restore` close the app, copy or swap its closed data and
+ * reopen it at its initial page: a driver selected before the call is bound to
+ * the closed instance, so select the lxapp again afterwards.
+ */
+export interface ProfileDriver {
+  /** Snapshot the profile; resolves the checkpoint id. */
+  checkpoint(): Promise<string>;
+  /**
+   * Replace the profile with checkpoint `id`. With `keep`, the storage keys
+   * those globs match keep their current values across the rollback.
+   */
+  restore(id: string, options?: ProfileRestoreOptions): Promise<ProfileRestoreResult>;
+  /** Discard checkpoint `id`; the app keeps running. */
+  drop(id: string): Promise<void>;
+}
+
+/** `ProfileDriver.restore` options. */
+export interface ProfileRestoreOptions {
+  /**
+   * `lx.getStorage()` keys whose current state survives the rollback: globs
+   * over the whole key, `*` any run of characters (dots included), `?` one
+   * character, anything else literal (at most 64 patterns). A matching key
+   * keeps its current value, one added since the checkpoint stays, and one
+   * deleted since stays deleted. Files (`lx://userdata`, …) always roll back.
+   */
+  keep?: string[];
+}
+
+export interface ProfileRestoreResult {
+  /** Kept keys that currently exist and were carried into the restored data. */
+  kept: string[];
+}
+
+// ============================ test clock ============================
+
+/** A time for the test clock: epoch milliseconds, a `Date.parse` string, or a `Date`. */
+export type ClockTime = number | string | Date;
+
+export interface ClockInstallOptions {
+  /** What Logic's `Date` reads at install. Default: the real current time. */
+  now?: ClockTime;
+}
+
+export interface ClockRunAllOptions {
+  /** Reject once this many timers fired and more are pending. Default 1000. */
+  maxTimers?: number;
+}
+
+/** Logic's test time after a clock call. */
+export interface ClockState {
+  /** Logic's `Date.now()` afterwards. */
+  now: number;
+  /** Timers still scheduled on the test clock. */
+  pending: number;
+}
+
+/** What `tick` / `runAll` did. */
+export interface ClockAdvance extends ClockState {
+  /** Timers fired by this call. */
+  fired: number;
+}
+
+export interface ClockUninstallResult {
+  /** `false` when no clock was installed (never, or the app reopened since). */
+  uninstalled: boolean;
+  /** Timers still pending on the test clock; they are discarded, never fired. */
+  dropped: number;
+}
+
+/**
+ * Test clock for the selected lxapp's Logic context, scoped to the host
+ * automation run (`lxdev test`); outside one every call rejects with
+ * `E_AUTOMATION`. While installed, Logic's `Date` (no-argument
+ * construction, `Date()`, `Date.now()`), `setTimeout` / `setInterval` and
+ * their `clear*`, and `performance.now()` read test time, and those timers
+ * fire only from `tick` / `runAll`, in time order. The page WebView, native
+ * work, real network requests, test route `delay` / `hang` and timers started
+ * before `install` keep real time. The run's end, or the app reopening,
+ * returns the app to real time.
+ */
+export interface ClockDriver {
+  /**
+   * Put Logic on test time; resolves its state (`pending` is 0: timers
+   * started before `install` keep real time). Rejects with
+   * `E_CLOCK_INSTALLED` when a clock is already installed.
+   */
+  install(options?: ClockInstallOptions): Promise<ClockState>;
+  /**
+   * Advance by `ms`, firing each timer due on the way at its own time. After
+   * every firing, promise chains the callback started settle before the next
+   * timer fires. Rejects with `E_CLOCK_NOT_INSTALLED` without a clock.
+   */
+  tick(ms: number): Promise<ClockAdvance>;
+  /**
+   * Fire timers, including those they schedule, until none is left; rejects
+   * once `maxTimers` fired (an interval never lets the queue empty).
+   */
+  runAll(options?: ClockRunAllOptions): Promise<ClockAdvance>;
+  /**
+   * Change what `Date` reads without firing timers; timer due times and
+   * `performance.now()` are unaffected. Resolves the new state.
+   */
+  setSystemTime(time: ClockTime): Promise<ClockState>;
+  /** Return Logic to real time; pending test timers are dropped. */
+  uninstall(): Promise<ClockUninstallResult>;
+}
+
+// ============================== dialogs ==============================
+
+/** A toast Logic presented while watched; the host drew it as usual. */
+export interface ToastRecord {
+  title: string;
+  /** `success` / `error` / `loading` / `none`. */
+  icon: string;
+  /** Milliseconds the toast asked to stay. */
+  duration: number;
+  /** Epoch milliseconds it was presented. */
+  at: number;
+}
+
+export interface ModalAnswer {
+  confirm: boolean;
+}
+
+/**
+ * A modal Logic opened while watched: drawn (`drawn: true`) until the spec
+ * queued a modal answer, answered from the queue after.
+ */
+export interface ModalRecord {
+  title: string;
+  content: string;
+  /** Only when the app set it (the default is localized). */
+  confirmText?: string;
+  /** Only when the modal has a cancel button and the app set its text. */
+  cancelText?: string;
+  /**
+   * The queued answer it got, or the user's choice when drawn. `null`: a
+   * drawn one still open or that failed to present, or (answering) no answer
+   * was queued, so the call rejected and the spec failed.
+   */
+  answer: ModalAnswer | null;
+  /** Drawn for the user, not answered from the queue. */
+  drawn?: true;
+}
+
+/** `{ index }` picks that item; `{ cancel: true }` dismisses the sheet. */
+export type ActionSheetAnswer = { index: number } | { cancel: true };
+
+/** An `lx.showActionSheet` while watched: drawn, or answered like modals. */
+export interface ActionSheetRecord {
+  /** Item labels, in order. */
+  items: string[];
+  answer: ActionSheetAnswer | null;
+  drawn?: true;
+}
+
+export interface DialogUnwatchResult {
+  /** Modal answers queued that no modal used. */
+  modalAnswers: number;
+  /** Action sheet answers queued that no sheet used. */
+  actionSheetAnswers: number;
+}
+
+/**
+ * The dialogs the selected lxapp's Logic opens while a spec of a host
+ * automation run (`lxdev test`) watches it; outside one every call rejects
+ * with `E_AUTOMATION`. Toasts, modals (`showModal`, `alert`, `confirm`) and
+ * `showActionSheet` are recorded and drawn. A queued answer applies once;
+ * later dialogs are drawn unless strict mode explicitly requires an answer.
+ * An unwatched app presents every dialog as usual.
+ */
+export interface DialogDriver {
+  /** Start watching for the open spec attempt, with nothing recorded or queued. */
+  watch(): void;
+  /** Stop watching; returns the queued answers no dialog used. */
+  unwatch(): DialogUnwatchResult;
+  /** The first dialog that found no answer, or `null` once the watch ends. */
+  unanswered(): Promise<string | null>;
+  toasts(): ToastRecord[];
+  modals(): ModalRecord[];
+  actionSheets(): ActionSheetRecord[];
+  answerNextModal(answer: ModalAnswer): void;
+  answerNextActionSheet(answer: ActionSheetAnswer): void;
+  /** Strict mode refuses an unqueued dialog; returns the previous modes. */
+  setAnswerMode(mode: { modals?: "draw" | "strict"; actionSheets?: "draw" | "strict" }):
+    { modals: "draw" | "strict"; actionSheets: "draw" | "strict" };
+}
+
+/** Capability for one selected running lxapp, as app Logic sees it. */
+export interface LogicLxAppDriver {
   readonly page: PageDriver;
-  readonly nav: NavDriver;
+  readonly nav: LogicNavDriver;
   /** Complete runtime snapshot of the selected lxapp. */
   info(): Promise<LxAppRuntimeInfo>;
   /** Configured pages of the selected lxapp. */
   pages(): Promise<LxAppPageConfig[]>;
   /** Authoritative host surface render plan, for end-to-end assertions. */
   surfaceLayout(): Promise<SurfaceLayoutSnapshot>;
-  /** Logic-runtime eval; self-eval from that Logic runtime is rejected. */
-  eval(options: LxAppEvalOptions): Promise<unknown>;
+  /**
+   * Logic-runtime eval of another lxapp; evaluating the calling Logic runtime
+   * itself rejects. `T` describes the expected JSON result; it is not
+   * runtime validation.
+   */
+  eval<T = unknown>(options: LogicLxAppEvalOptions): Promise<T>;
+}
+
+/**
+ * Capability for one selected running lxapp in a host automation run
+ * (`HostRunAutomation.lxapp()`): the Logic driver plus test-run-only members.
+ */
+export interface LxAppDriver extends LogicLxAppDriver {
+  readonly nav: NavDriver;
+  /**
+   * Test-only Logic `fetch` routing, scoped to the host automation run.
+   *
+   * @remarks Reading the property always works, but every call rejects with
+   * `E_AUTOMATION` outside a host test run (`lxdev test`) — from app Logic,
+   * or in a host built without the automation runtime.
+   */
+  readonly network: NetworkDriver;
+  /**
+   * The app's mocks in the host run: scenario states on top of the mock
+   * selection, and a fresh handler state.
+   *
+   * @remarks Reading the property always works, but every call rejects with
+   * `E_AUTOMATION` outside a host test run (`lxdev test`).
+   */
+  readonly mock: MockDriver;
+  /**
+   * Isolated data profile rollback, scoped to the host automation run.
+   *
+   * @remarks Reading the property always works; every call rejects with
+   * `E_PROFILE_NOT_ISOLATED` outside an isolated run.
+   */
+  readonly profile: ProfileDriver;
+  /**
+   * Test clock for the selected lxapp's Logic, scoped to the host automation
+   * run.
+   *
+   * @remarks Reading the property always works, but every call rejects with
+   * `E_AUTOMATION` outside a host test run (`lxdev test`).
+   */
+  readonly clock: ClockDriver;
+  /**
+   * The dialogs this lxapp's Logic opens while a spec watches it.
+   *
+   * @remarks Reading the property always works, but every call rejects with
+   * `E_AUTOMATION` outside a host test run (`lxdev test`).
+   */
+  readonly dialogs: DialogDriver;
+  /** @internal Test-runner plumbing: resolves to the call-trace envelope. */
+  eval<T = unknown>(options: LxAppEvalOptions & { captureCalls: true }): Promise<LxAppEvalTrace<T>>;
+  /**
+   * Logic-runtime eval; evaluating the calling Logic runtime itself rejects.
+   * `T` describes the expected JSON result; it is not runtime validation.
+   */
+  eval<T = unknown>(options: LxAppEvalOptions & { captureCalls?: false }): Promise<T>;
+  eval<T = unknown>(options: LxAppEvalOptions): Promise<T | LxAppEvalTrace<T>>;
 }
 
 // ======================= lxapp manager (host) =======================
@@ -539,38 +1444,40 @@ export interface LxAppPageEntry {
   path: string;
 }
 
-/** Runtime snapshot of a running lxapp (raw payload, snake_case keys). */
+/** Runtime snapshot of a running lxapp. */
 export interface LxAppRuntimeInfo {
-  appid: string;
-  app_name: string;
+  appId: string;
+  appName: string;
   version: string;
-  release_type: string;
-  session_id: number;
+  releaseType: string;
+  sessionId: number;
   status: string;
   /** True while the lxapp holds a place in the host's page stack. */
-  in_stack: boolean;
-  is_home: boolean;
-  current_page: string | null;
-  initial_route: string;
-  pages_count: number;
-  page_entries: LxAppPageEntry[];
-  page_stack: string[];
-  tab_bar: LxAppRuntimeTabBarInfo | null;
-  navigation_bar: LxAppRuntimeNavigationBarInfo | null;
-  lxapp_dir: string;
-  data_dir: string;
-  cache_dir: string;
+  inStack: boolean;
+  isHome: boolean;
+  currentPage: string | null;
+  initialRoute: string;
+  pagesCount: number;
+  pageEntries: LxAppPageEntry[];
+  pageStack: string[];
+  tabBar: LxAppRuntimeTabBarInfo | null;
+  navigationBar: LxAppRuntimeNavigationBarInfo | null;
+  lxappDir: string;
+  dataDir: string;
+  cacheDir: string;
+  /** Supported features keyed by Logic context id. */
+  logicFeatures: Record<string, string[]>;
 }
 
 /** Runtime NavigationBar state exposed for deterministic host-level assertions. */
 export interface LxAppRuntimeNavigationBarInfo {
   title: string;
-  home_button: 'auto' | 'hidden';
-  home_button_visible: boolean;
-  runtime_style: {
-    background_color: string | null;
-    foreground_color: string | null;
-    divider_color: string | null;
+  homeButton: 'auto' | 'hidden';
+  homeButtonVisible: boolean;
+  runtimeStyle: {
+    backgroundColor: string | null;
+    foregroundColor: string | null;
+    dividerColor: string | null;
   };
 }
 
@@ -578,19 +1485,15 @@ export interface LxAppRuntimeNavigationBarInfo {
 export interface LxAppRuntimeTabBarInfo {
   presentation: 'standard' | 'immersive';
   visibility: 'auto' | 'visible' | 'hidden';
-  route_visible: boolean;
-  effective_visible: boolean;
-  selected_index: number;
-  runtime_style: {
-    foreground_color: string | null;
-    selected_foreground_color: string | null;
-  };
+  routeVisible: boolean;
+  effectiveVisible: boolean;
+  selectedIndex: number;
   items: Array<{
     index: number;
     text: string | null;
-    icon_path: string | null;
+    iconPath: string | null;
     badge: string | null;
-    red_dot: boolean;
+    redDot: boolean;
   }>;
 }
 
@@ -601,14 +1504,14 @@ export interface LxAppRef {
 }
 
 export interface LxAppOpenOptions {
-  appid: string;
+  appId: string;
   /** Initial page/path. */
   path?: string;
   channel?: 'release' | 'draft';
 }
 
 export interface LxAppOpenResult {
-  appid: string;
+  appId: string;
   path: string;
 }
 
@@ -623,17 +1526,18 @@ export interface ApplinkResult {
 }
 
 /**
- * Cross-lxapp lifecycle and host-window access. Requires `host` outside dev.
+ * Cross-lxapp lifecycle and host-window access. Requires the `host` privilege
+ * from app Logic; a host automation run needs no grant.
  *
  * `close`, `restart`, and `uninstall` reject when they target the calling app
- * itself. Use `lx.app.exit()` to self-exit.
+ * itself. Use `lx.host.exit()` to self-exit.
  */
 export interface LxAppManager {
   list(): Promise<LxAppRuntimeInfo[]>;
   current(): Promise<LxAppSummary>;
   open(options: LxAppOpenOptions): Promise<LxAppOpenResult>;
   /**
-   * Inject an App Link (`lxdev app applink`). Warm `onShow`, `scene === 8003`.
+   * Inject an App Link (`lxdev host applink`). Warm `onShow`, `scene === 8003`.
    * Host must match `appLinks.hosts`. Resolves when accepted, not when
    * navigation finishes.
    */
@@ -676,9 +1580,6 @@ export interface DeviceState {
   landscape: boolean;
   /** Simulated system appearance of the device screen. */
   appearance: "system" | "light" | "dark";
-  /** Whether the simulated host capsule is enabled (the setting, not
-   * per-device visibility: desktop presets draw no phone chrome either way). */
-  capsule: boolean;
 }
 
 export interface DeviceSetOptions {
@@ -689,8 +1590,6 @@ export interface DeviceSetOptions {
   landscape?: boolean;
   /** Simulated appearance; omit to keep. */
   appearance?: "system" | "light" | "dark";
-  /** Show (`true`) or hide (`false`) the simulated host capsule; omit to keep. */
-  capsule?: boolean;
 }
 
 /**
@@ -767,9 +1666,9 @@ export interface BrowserScrollOptions extends BrowserTabRef {
  * A browser wait condition — pass **exactly one** of the condition fields.
  * `navigation` may add `complete` to wait for load completion.
  */
-export interface BrowserWaitOptions extends BrowserTabRef {
+interface BrowserWaitFields extends BrowserTabRef {
   /** Wait for page load. */
-  loaded?: boolean;
+  loaded?: true;
   /** Wait for a selector to exist. */
   exists?: string;
   /** Wait for a selector to be visible. */
@@ -785,7 +1684,7 @@ export interface BrowserWaitOptions extends BrowserTabRef {
   /** Wait for the URL to contain this. */
   urlContains?: string;
   /** Wait for a navigation. */
-  navigation?: boolean;
+  navigation?: true;
   /** With `navigation`: baseline URL to detect a change from (default: any
    *  navigation satisfies it). */
   fromUrl?: string;
@@ -795,6 +1694,39 @@ export interface BrowserWaitOptions extends BrowserTabRef {
   timeoutMs?: number;
 }
 
+type BrowserWaitConditionKey = 'loaded' | 'exists' | 'visible' | 'hidden' | 'editable' | 'js' | 'url' | 'urlContains' | 'navigation';
+
+/** Exactly one condition; ambiguous and empty waits are rejected by the runtime. */
+export type BrowserWaitOptions = Pick<BrowserWaitFields, 'tab' | 'timeoutMs' | 'fromUrl' | 'complete'> & {
+  [K in BrowserWaitConditionKey]: Required<Pick<BrowserWaitFields, K>> &
+    Partial<Record<Exclude<BrowserWaitConditionKey, K>, never>>;
+}[BrowserWaitConditionKey];
+
+/** Browser query payload; it does not carry lxapp-only identity/index fields. */
+export interface BrowserElementInfo {
+  exists: boolean;
+  visible: boolean;
+  enabled: boolean;
+  editable: boolean;
+  text?: string;
+  textTruncated?: boolean;
+  value?: string;
+  valueTruncated?: boolean;
+  rect?: ElementRect;
+}
+
+export interface BrowserWaitResult {
+  elapsed_ms: number;
+  current_url?: string;
+  element?: BrowserElementInfo;
+  value?: unknown;
+}
+
+export interface BrowserEvalResult<T = unknown> {
+  value: T;
+  navigation: BrowserWaitResult;
+}
+
 export interface BrowserTab {
   tab_id: string;
   path: string;
@@ -868,16 +1800,22 @@ export interface BrowserDriver {
   back(options?: BrowserTabRef): Promise<void>;
   forward(options?: BrowserTabRef): Promise<void>;
   /** Evaluate JS; with `waitNavigation` resolves to `{ value, navigation }`. */
-  eval(options: BrowserEvalOptions): Promise<unknown>;
-  query(options: BrowserQueryOptions): Promise<PageElement | PageElementMiss>;
+  eval<T = unknown>(options: BrowserEvalOptions & {waitNavigation: true}): Promise<BrowserEvalResult<T>>;
+  eval<T = unknown>(options: BrowserEvalOptions & {waitNavigation?: false}): Promise<T>;
+  eval<T = unknown>(options: BrowserEvalOptions): Promise<T | BrowserEvalResult<T>>;
+  query(options: BrowserQueryOptions): Promise<BrowserElementInfo>;
   /** Wait for a condition (pass exactly one condition field). */
-  wait(options: BrowserWaitOptions): Promise<unknown>;
+  wait(options: BrowserWaitOptions): Promise<BrowserWaitResult>;
   /** Click; with `waitNavigation` resolves to the navigation payload else `null`. */
-  click(options: BrowserClickOptions): Promise<unknown>;
+  click(options: BrowserClickOptions & { waitNavigation: true }): Promise<BrowserWaitResult>;
+  click(options: BrowserClickOptions & { waitNavigation?: false }): Promise<null>;
+  click(options: BrowserClickOptions): Promise<BrowserWaitResult | null>;
   type(options: BrowserTypeOptions): Promise<void>;
   fill(options: BrowserTypeOptions): Promise<void>;
   /** Press; with `waitNavigation` resolves to the navigation payload else `null`. */
-  press(options: BrowserPressOptions): Promise<unknown>;
+  press(options: BrowserPressOptions & { waitNavigation: true }): Promise<BrowserWaitResult>;
+  press(options: BrowserPressOptions & { waitNavigation?: false }): Promise<null>;
+  press(options: BrowserPressOptions): Promise<BrowserWaitResult | null>;
   scroll(options: BrowserScrollOptions): Promise<void>;
   scrollTo(options: BrowserSelectorOptions): Promise<void>;
   screenshot(options?: BrowserTabRef): Promise<Screenshot>;
@@ -971,7 +1909,7 @@ export interface PageKey {
   press(options: KeyPressOptions): Promise<InputResult>;
 }
 
-// ======================= desktop (host, dev/test only) =======================
+// ======================= desktop (host) =======================
 
 /** A rectangle in backend-native global desktop coordinates. */
 export interface DesktopRect {
@@ -1115,10 +2053,9 @@ export interface DesktopLaunchResult {
  * `match` (query `text | title: | class: | process: | pid:`, must resolve to
  * exactly one window).
  */
-export interface DesktopWindowSel {
-  window?: string;
-  match?: string;
-}
+export type DesktopWindowSel =
+  | { window: string; match?: never }
+  | { window?: never; match: string };
 
 export interface DesktopWindowsOptions {
   /** Match query (`text | title: | class: | process: | pid:`). */
@@ -1209,24 +2146,24 @@ export interface DesktopKey {
   up(options: DesktopKeyNameOptions): Promise<DesktopAck>;
 }
 
-export interface DesktopWindowMoveOptions extends DesktopWindowSel {
+export type DesktopWindowMoveOptions = DesktopWindowSel & {
   /** Target position as `[x, y]` in desktop coordinates. */
   to: Point;
-}
+};
 
-export interface DesktopWindowResizeOptions extends DesktopWindowSel {
+export type DesktopWindowResizeOptions = DesktopWindowSel & {
   width: number;
   height: number;
-}
+};
 
-export interface DesktopWindowMoveDisplayOptions extends DesktopWindowSel {
+export type DesktopWindowMoveDisplayOptions = DesktopWindowSel & {
   /** Display id from `displays()`. */
   display: string;
-}
+};
 
-export interface DesktopWindowAlwaysOnTopOptions extends DesktopWindowSel {
+export type DesktopWindowAlwaysOnTopOptions = DesktopWindowSel & {
   on: boolean;
-}
+};
 
 /** Window management; every verb resolves to the resulting window state. */
 export interface DesktopWindowDriver {
@@ -1340,10 +2277,11 @@ export interface DesktopAppLaunchOptions {
 }
 
 /** Quit target — exactly one of `match` / `pid` / `window`. */
-export interface DesktopAppQuitOptions {
-  match?: string;
-  pid?: number;
-  window?: string;
+export type DesktopAppQuitOptions = (
+  | { match: string; pid?: never; window?: never }
+  | { match?: never; pid: number; window?: never }
+  | { match?: never; pid?: never; window: string }
+) & {
   /** Terminate instead of a graceful close. */
   force?: boolean;
 }