@lingxia/types 0.17.0 → 0.19.0

package/dist/automation/index.d.ts

@@ -1,37 +1,91 @@
 /**
  * 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.
  */
 import type { TerminalSettingsValue } from '../generated/logic.js';
-/** Stable automation root; it grants no capability until one is selected. */
+/**
+ * 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 declare const AUTOMATION_ERROR_CODES: readonly ["E_AUTOMATION", "E_SCENARIO_STATE_UNKNOWN", "E_AUTOMATION_PRIVILEGE", "E_PAGE_NOT_ACTIVE", "E_PAGE_NOT_READY", "E_PAGE_ACTION", "E_ELEMENT_NOT_FOUND", "E_ELEMENT_NOT_INTERACTABLE", "E_AUTOMATION_TIMEOUT", "E_EVAL_SCRIPT", "E_EVAL_TIMEOUT", "E_PROFILE_NOT_ISOLATED", "E_CLOCK_NOT_INSTALLED", "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"];
+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;
+}
 export type TerminalSplitDirection = 'left' | 'right' | 'up' | 'down';
 export interface TerminalSurfaceRef {
     /** Stable id returned by `lx.shell.openDeclared('terminal', { key })`. */
@@ -106,7 +160,10 @@ export interface TerminalWorkspaceSnapshot {
 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. */
@@ -145,6 +202,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.
@@ -154,7 +213,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;
 }
 export interface PageEvalOptions extends PageTarget {
@@ -162,6 +221,14 @@ export interface PageEvalOptions extends PageTarget {
     script: string;
     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;
@@ -182,6 +249,18 @@ export interface PageSelectorOptions extends PageTarget {
 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;
@@ -200,16 +279,24 @@ export interface PageScrollToOptions extends PageTarget {
     /** CSS selector of the element to reveal (first match). */
     css: string;
 }
-export type PageWaitState = 'attached' | 'detached' | 'visible' | 'hidden' | 'enabled' | 'editable'
-/** @deprecated Use `attached`. */
- | 'exists'
-/** @deprecated Use `detached`. */
- | 'gone';
+/**
+ * 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';
 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;
 }
 /**
@@ -225,12 +312,12 @@ 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;
@@ -242,16 +329,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;
 }
 /** Returned when no element matches (single-element mode). */
@@ -260,6 +352,7 @@ export interface PageElementMiss {
     index: number;
     count: number;
     visible: false;
+    inViewport: false;
     enabled: false;
     editable: false;
 }
@@ -278,8 +371,16 @@ 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;
@@ -288,11 +389,13 @@ export interface PageDriver {
     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>;
@@ -306,70 +409,133 @@ export interface PageDriver {
     /** App-window keyboard input (`lxdev lxapp page key`). */
     readonly key: PageKey;
 }
-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>;
+}
 export interface LxAppSummary {
-    appid: string;
+    appId: string;
     currentPage: string | null;
 }
 export interface LxAppPageConfig {
     name: string;
     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';
@@ -479,74 +645,765 @@ export interface SurfaceLayoutSnapshot {
     floats: SurfaceLayoutFloat[];
     tree?: SurfaceLayoutTree;
 }
-/** Capability for one selected running lxapp. */
-export interface LxAppDriver {
+/**
+ * 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[];
+}
+/** 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>;
+}
+/** 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>>;
 }
 /** One configured page in a runtime info payload. */
 export interface LxAppPageEntry {
     name: string;
     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;
     };
 }
 /** Runtime TabBar state exposed for deterministic host-level assertions. */
 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;
     }>;
 }
 /** Selects a running lxapp by id; defaults to the current app. */
@@ -555,13 +1412,13 @@ export interface LxAppRef {
     app?: string;
 }
 export interface LxAppOpenOptions {
-    appid: string;
+    appId: string;
     /** Initial page/path. */
     path?: string;
     channel?: 'release' | 'draft';
 }
 export interface LxAppOpenResult {
-    appid: string;
+    appId: string;
     path: string;
 }
 export interface ApplinkOptions {
@@ -573,17 +1430,18 @@ export interface ApplinkResult {
     code: number;
 }
 /**
- * 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.
      */
@@ -622,9 +1480,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 {
     /** Device preset id (see `list()`); omit to keep the current device. */
@@ -634,8 +1489,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;
 }
 /**
  * Simulated-device control (`lxdev runner`). Only functional in a host
@@ -699,9 +1552,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. */
@@ -717,7 +1570,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;
@@ -726,6 +1579,33 @@ export interface BrowserWaitOptions extends BrowserTabRef {
     /** Timeout in ms (default 10000, capped at 60000). */
     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;
@@ -791,16 +1671,34 @@ 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>;
@@ -1005,10 +1903,13 @@ 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:`). */
     match?: string;
@@ -1084,21 +1985,21 @@ export interface DesktopKey {
     down(options: DesktopKeyNameOptions): Promise<DesktopAck>;
     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 {
     status(options: DesktopWindowSel): Promise<DesktopWindowInfo>;
@@ -1198,13 +2099,22 @@ export interface DesktopAppLaunchOptions {
     timeoutMs?: number;
 }
 /** 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;
-}
+};
 /** App lifecycle. */
 export interface DesktopApp {
     launch(options: DesktopAppLaunchOptions): Promise<DesktopLaunchResult>;
@@ -1258,4 +2168,5 @@ export interface DesktopDriver {
     readonly app: DesktopApp;
     readonly process: DesktopProcess;
 }
+export {};
 //# sourceMappingURL=index.d.ts.map