@goliapkg/smix 1.0.26 → 2.0.0

package/src/App.ts

@@ -1,18 +1,21 @@
-// v7.5 c3 — App class full wire mirrors Kotlin v7.4 c5 / Swift v7.2.
-
-import { type A11yNode, findById, flatten } from './A11yNode.js'
+// A handle to a running app. Live driving (tap/fill/swipe/...) and live
+// sense (snapshotTree) are pending the napi axis: the TS SDK has no FFI
+// path, so with the fictional HTTP wire deleted there is no way to reach a
+// simulator from here yet. These methods throw SmixNotImplementedError
+// rather than posting to a route the runner never served. What does work is
+// the resolver seam: given a treeJson, `resolver` / `labelsResolver` resolve
+// selectors against the runner's served /select/resolve* routes.
+
+import { type A11yNode, flatten } from './A11yNode.js'
 import { ExpectationFailure } from './ExpectationFailure.js'
 import { Locator, SmixNotImplementedError } from './Locator.js'
-import {
-  encodeSelectorJson,
-  type Selector,
-} from './Selector.js'
-import {
-  type KeyName,
-  type SmixSimRuntime,
-  type SwipeDirection,
-} from './SimRuntime.js'
+import type { NodeDriver, NodeSession } from './NodeDriver.js'
+import { type Selector, encodeSelectorJson } from './Selector.js'
 import type { LabelsResolver, SelectorResolver } from './SelectorResolver.js'
+import type { SystemPopup } from './SystemPopup.js'
+
+type KeyName = 'return' | 'delete' | 'space' | 'tab' | 'escape' | 'enter'
+type SwipeDirection = 'up' | 'down' | 'left' | 'right'
 
 /**
  * A handle to a running app on the simulator / emulator.
@@ -20,13 +23,16 @@ import type { LabelsResolver, SelectorResolver } from './SelectorResolver.js'
 export class App {
   constructor(
     public readonly bundleId: string,
-    public readonly runtime: SmixSimRuntime,
+    /** The napi driver (act + sense); a mock in tests, the real addon in prod. */
+    public readonly driver: NodeDriver,
+    /** The napi session this app was launched in (lifecycle verbs). */
+    public readonly session: NodeSession,
     public readonly resolver: SelectorResolver,
     /**
-     * v7.6 c1 — wraps Rust `resolve_selector_labels` (each match's
-     * `.label`). Used by Locator.toHaveCount + toHaveLabel. Defaults
-     * to a stub that throws — tests + production should pass a real
-     * impl (HttpSimRuntime.labelsResolver or MockLabelsResolver.resolve).
+     * Wraps `resolve_selector_labels`, backing toHaveCount and
+     * toHaveLabel. The default throws rather than guessing: there is no
+     * sensible answer without a resolver, and a silent empty list would
+     * read as "no matches".
      */
     public readonly labelsResolver: LabelsResolver = async () => {
       throw new Error('labelsResolver not configured; pass one to Smix.launchApp or App constructor')
@@ -35,100 +41,81 @@ export class App {
 
   // ---- act methods --------------------------------------------------
 
-  async tap(selector: Selector, _opts: { timeoutMs?: number } = {}): Promise<void> {
-    const tree = await this.runtime.snapshotTree()
+  /**
+   * Snapshot the tree, resolve `selector` against it, and return the first
+   * matching id. Selectors resolve to an id on this side; only the id crosses
+   * the napi boundary. No match throws ELEMENT_NOT_FOUND with the visible
+   * elements so the failure is AI-readable.
+   */
+  private async resolveFirstOrThrow(selector: Selector): Promise<string> {
+    const treeJson = await this.driver.snapshotTree()
     const selectorJson = encodeSelectorJson(selector)
-    const treeJson = JSON.stringify(tree)
-
-    let matches: readonly string[]
-    try {
-      matches = await this.resolver(treeJson, selectorJson)
-    } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e)
-      throw new ExpectationFailure({
-        code: 'unknown',
-        message: `FFI resolveSelector raised: ${msg}`,
-        selectorJson,
-      })
-    }
-
-    const firstId = matches[0]
-    const node = firstId !== undefined ? findById(tree, firstId) : null
-    if (node === null) {
+    const ids = await this.resolver(treeJson, selectorJson)
+    const first = ids[0]
+    if (first === undefined) {
+      const tree = JSON.parse(treeJson) as A11yNode
       throw new ExpectationFailure({
-        code: 'notFound',
-        message: 'no candidates after spatial + index filters',
+        code: 'ELEMENT_NOT_FOUND',
+        message: `no element matched selector ${selectorJson}`,
         selectorJson,
         visibleElements: flatten(tree).slice(0, 20),
-        suggestions: [
-          'check `accessibilityIdentifier` is set on the target view',
-          'consider relaxing to text(...) if the label is more stable than the id',
-        ],
       })
     }
+    return first
+  }
 
-    await this.runtime.synthesizeTap(
-      node.bounds.x + node.bounds.w / 2,
-      node.bounds.y + node.bounds.h / 2,
-    )
+  async tap(selector: Selector, _opts: { timeoutMs?: number } = {}): Promise<void> {
+    await this.driver.tapById(await this.resolveFirstOrThrow(selector))
   }
 
-  /**
-   * Resolve [selector], tap to focus, then type [text]. Mirror
-   * Kotlin App.fill from v7.4 c3.
-   */
   async fill(selector: Selector, text: string): Promise<void> {
-    await this.tap(selector)
-    await this.runtime.sendString(text)
+    const id = await this.resolveFirstOrThrow(selector)
+    await this.driver.tapById(id)
+    await this.driver.inputText(text)
   }
 
   async pressKey(key: KeyName): Promise<void> {
-    await this.runtime.pressKey(key)
+    await this.driver.pressKey(key === 'enter' ? 'return' : key)
   }
 
   async swipe(direction: SwipeDirection): Promise<void> {
-    await this.runtime.swipe(direction)
+    await this.driver.swipe(direction)
   }
 
   async screenshot(): Promise<Uint8Array> {
-    return this.runtime.screenshot()
+    // No runner wire route yet — singled out to a later checkpoint (v2.md
+    // decision, 2026-07-24). The blocker is the wire, not napi.
+    throw new SmixNotImplementedError('wire', 'App.screenshot')
   }
 
-  /**
-   * Tap at a normalized coordinate (0..1) — escape hatch per §9 #3.
-   * Out-of-range values throw ExpectationFailure code=wrongState.
-   */
+  /** Tap at a normalized coordinate (0..1) — escape hatch per §9 #3. */
   async tapAtCoord(nx: number, ny: number): Promise<void> {
     if (nx < 0 || nx > 1 || ny < 0 || ny > 1) {
       throw new ExpectationFailure({
-        code: 'wrongState',
-        message: `tapAtCoord arguments out of [0,1] range: nx=${nx}, ny=${ny}`,
-        suggestions: ['use normalized 0..1 — for raw points, divide by viewport size'],
+        code: 'ASSERTION_FAILED',
+        message: `tapAtCoord expects normalized 0..1 coordinates, got (${nx}, ${ny})`,
       })
     }
-    await this.runtime.synthesizeTapAtNormalized(nx, ny)
+    await this.driver.tapAtCoord(nx, ny)
   }
 
   async terminate(): Promise<void> {
-    await this.runtime.terminate(this.bundleId)
+    await this.session.terminateApp()
   }
 
   async relaunch(): Promise<void> {
-    await this.runtime.terminate(this.bundleId)
-    await this.runtime.launch(this.bundleId)
+    await this.session.relaunchApp()
   }
 
-  async launchFresh(opts: {
+  async launchFresh(_opts: {
     clearState?: boolean
     clearKeychain?: boolean
     appPath?: string
   } = {}): Promise<void> {
-    await this.runtime.launchFresh({
-      bundleId: this.bundleId,
-      clearState: opts.clearState ?? false,
-      clearKeychain: opts.clearKeychain ?? false,
-      appPath: opts.appPath,
-    })
+    // Clearing state / installing an appPath is host-side (simctl), with no
+    // runner wire — singled out to a later checkpoint. The blocker is the
+    // host, not napi.
+    throw new SmixNotImplementedError('host', 'App.launchFresh')
   }
 
   // ---- sense methods ------------------------------------------------
@@ -137,16 +124,26 @@ export class App {
     return new Locator(this, selector)
   }
 
+  /**
+   * The tree seam Locator polls. Pending napi: without an FFI path there is
+   * no live simulator to snapshot. Lands with the napi axis.
+   */
+  async snapshotTree(): Promise<A11yNode> {
+    return JSON.parse(await this.driver.snapshotTree()) as A11yNode
+  }
+
   async tree(): Promise<A11yNode> {
-    return this.runtime.snapshotTree()
+    return this.snapshotTree()
   }
 
-  async systemPopups(): Promise<A11yNode[]> {
-    return this.runtime.systemPopups()
+  async systemPopups(): Promise<SystemPopup[]> {
+    return JSON.parse(await this.driver.systemPopups()) as SystemPopup[]
   }
 
-  async openUrl(url: string): Promise<void> {
-    await this.runtime.openUrl(url)
+  async openUrl(_url: string): Promise<void> {
+    // No runner wire route yet — singled out to a later checkpoint. The
+    // blocker is the wire, not napi.
+    throw new SmixNotImplementedError('wire', 'App.openUrl')
   }
 }
 

package/src/ExpectationFailure.ts

@@ -1,23 +1,33 @@
-// v7.5 c1 — ExpectationFailure + FailureCode mirror Swift v7.2 c4 +
-// Kotlin v7.4 c1 + Rust smix-error.
+// The wire form of `smix-error`'s failure surface.
 //
-// AI-readable JSON contract: toJson() emits sorted-keys, ISO-8601
-// timestamp single-line JSON matching Swift errorDescription contract
-// (per design.md §9 #11).
+// toJson() emits sorted keys and an ISO-8601 timestamp on one line. Every
+// SDK emits the same bytes for the same failure, so a reader — human or
+// model — sees one format whichever language raised it.
 
 import type { A11yNode } from './A11yNode.js'
 
+/**
+ * Rust `smix_error::FailureCode`'s wire strings verbatim —
+ * `crates/smix-error/tests/sdk_failure_code_parity.rs` reads this
+ * declaration and fails if the two sets ever diverge.
+ */
 export type FailureCode =
-  | 'notFound'
-  | 'ambiguous'
-  | 'notInteractable'
-  | 'timeout'
-  | 'wrongState'
-  | 'unknown'
+  | 'ELEMENT_NOT_FOUND'
+  | 'NOT_VISIBLE'
+  | 'NOT_ENABLED'
+  | 'AMBIGUOUS'
+  | 'TIMEOUT'
+  | 'ASSERTION_FAILED'
+  | 'APP_NOT_RUNNING'
+  | 'SIMULATOR_NOT_BOOTED'
+  /** The touch was synthesised, and it did not land inside the element the selector matched. Distinct from element-not-found: not-found means fix the selector, missed means the element was there and the touch went elsewhere. */
+  | 'TAP_MISSED'
+  | 'DRIVER_ERROR'
 
 export const FAILURE_CODES: readonly FailureCode[] = [
-  'notFound', 'ambiguous', 'notInteractable',
-  'timeout', 'wrongState', 'unknown',
+  'ELEMENT_NOT_FOUND', 'NOT_VISIBLE', 'NOT_ENABLED',
+  'AMBIGUOUS', 'TIMEOUT', 'ASSERTION_FAILED',
+  'APP_NOT_RUNNING', 'SIMULATOR_NOT_BOOTED', 'TAP_MISSED', 'DRIVER_ERROR',
 ] as const
 
 /**

package/src/HttpRunner.ts

@@ -1,42 +1,10 @@
-// v7.5 c3 — HTTP-based SmixSimRuntime + SelectorResolver implementations.
-//
-// Per R-7.5-B HTTP-runtime decision: TS SDK communicates with smix-runner
-// via fetch JSON-RPC-ish API (one POST per call). Default endpoint
-// matches existing smix-runner-client conventions; consumers override
-// via base URL constructor param.
-//
-// Wire contract (mirrors smix-runner-client v3+):
-//   POST /sim/launch         { bundleId }                                  → 200
-//   POST /sim/terminate      { bundleId }                                  → 200
-//   POST /sim/launch-fresh   { bundleId, clearState, clearKeychain, appPath? } → 200
-//   POST /sim/launch-from-path { appPath }                                 → 200
-//   POST /sim/screenshot     {}                                            → 200 { png: base64 }
-//   POST /sim/system-popups  {}                                            → 200 { nodes: A11yNode[] }
-//   POST /sim/open-url       { url }                                       → 200
-//   POST /a11y/snapshot      {}                                            → 200 { tree: A11yNode }
-//   POST /input/tap          { x, y }                                      → 200
-//   POST /input/tap-normalized { nx, ny }                                  → 200
-//   POST /input/swipe        { direction }                                 → 200
-//   POST /input/send-string  { text }                                      → 200
-//   POST /input/press-key    { key }                                       → 200
-//   POST /select/resolve     { treeJson, selectorJson }                    → 200 { ids: string[] }
-//
-// v7.7 c1 contract additions (server impl deferred):
-//   POST /select/resolve-count   { treeJson, selectorJson }                → 200 { count: u32 }
-//   POST /select/resolve-labels  { treeJson, selectorJson }                → 200 { labels: string[] }
-//
-// The exact endpoint shapes are negotiated with smix-runner-server in
-// follow-up Swift work; for v7.5-v7.7 c1 we wire the TS-side fetch +
-// decode and a MockHttpRunnerClient stub that lets vitest exercise the
-// runtime without booting a real server.
+// The HTTP-backed SelectorResolver + session client: one POST per call
+// against a running smix-runner. Every route it sends is one the runner
+// serves — /select/resolve{,-count,-labels} for resolution and /session/*
+// (driven by the Session class through this client's fetch + Session-Id
+// plumbing). Live driving and sense (launch / tap / snapshot) are not here;
+// they are pending the napi axis.
 
-import { type A11yNode } from './A11yNode.js'
-import type {
-  KeyName,
-  LaunchFreshCall,
-  SmixSimRuntime,
-  SwipeDirection,
-} from './SimRuntime.js'
 import type { LabelsResolver, SelectorResolver } from './SelectorResolver.js'
 
 /**
@@ -56,16 +24,16 @@ export type HttpFetch = (
 }>
 
 /**
- * SmixSimRuntime + SelectorResolver wrapper around the smix-runner HTTP
- * server. Used in production RN/Expo test targets via fetch.
+ * SelectorResolver + session client over the smix-runner HTTP server.
+ * Resolves selectors against a treeJson supplied by the caller and carries
+ * the `Session-Id` header for the {@link Session} lifecycle. Used in
+ * production RN/Expo test targets via fetch.
  */
-export class HttpSimRuntime implements SmixSimRuntime {
+export class HttpSimRuntime {
   readonly resolver: SelectorResolver
   /**
-   * v7.7 c1 — labels resolver wrapping Rust `resolve_selector_labels`
-   * via smix-runner-server `/select/resolve-labels` endpoint. Used by
-   * `Locator.toHaveCount` (count = labels.length) + Locator.toHaveLabel.
-   * Pass directly to App constructor or Smix.launchApp.
+   * Backs toHaveCount (count = labels.length) and toHaveLabel. Pass it to
+   * the App constructor or to Smix.launchApp.
    */
   readonly labelsResolver: LabelsResolver
 
@@ -128,82 +96,14 @@ export class HttpSimRuntime implements SmixSimRuntime {
   }
 
   /**
-   * v7.7 c1 — direct match-count via dedicated FFI fn (avoid allocating
-   * the full ids list when callers only need count). Mirrors Rust
-   * `resolve_selector_count`. Locator.toHaveCount can prefer this over
-   * `labelsResolver` if it needs only count, not the labels themselves.
+   * Counts matches without building the id list, for callers that want a
+   * count and nothing else.
    */
   async resolveCount(treeJson: string, selectorJson: string): Promise<number> {
     const r = await this.post('/select/resolve-count', { treeJson, selectorJson })
     return (r as { count: number }).count
   }
 
-  async launch(bundleId: string): Promise<void> {
-    await this.post('/sim/launch', { bundleId })
-  }
-
-  async terminate(bundleId: string): Promise<void> {
-    await this.post('/sim/terminate', { bundleId })
-  }
-
-  async snapshotTree(): Promise<A11yNode> {
-    const r = await this.post('/a11y/snapshot', {})
-    return (r as { tree: A11yNode }).tree
-  }
-
-  async synthesizeTap(x: number, y: number): Promise<void> {
-    await this.post('/input/tap', { x, y })
-  }
-
-  async sendString(text: string): Promise<void> {
-    await this.post('/input/send-string', { text })
-  }
-
-  async pressKey(key: KeyName): Promise<void> {
-    await this.post('/input/press-key', { key })
-  }
-
-  async swipe(direction: SwipeDirection): Promise<void> {
-    await this.post('/input/swipe', { direction })
-  }
-
-  async screenshot(): Promise<Uint8Array> {
-    const r = await this.post('/sim/screenshot', {}) as { png: string }
-    return base64ToBytes(r.png)
-  }
-
-  async systemPopups(): Promise<A11yNode[]> {
-    const r = await this.post('/sim/system-popups', {}) as { nodes: A11yNode[] }
-    return r.nodes
-  }
-
-  async openUrl(url: string): Promise<void> {
-    await this.post('/sim/open-url', { url })
-  }
-
-  async launchFresh(opts: {
-    bundleId: string
-    clearState: boolean
-    clearKeychain: boolean
-    appPath?: string | undefined
-  }): Promise<void> {
-    const payload: LaunchFreshCall = {
-      bundleId: opts.bundleId,
-      clearState: opts.clearState,
-      clearKeychain: opts.clearKeychain,
-      appPath: opts.appPath,
-    }
-    await this.post('/sim/launch-fresh', payload)
-  }
-
-  async launchFromPath(appPath: string): Promise<void> {
-    await this.post('/sim/launch-from-path', { appPath })
-  }
-
-  async synthesizeTapAtNormalized(nx: number, ny: number): Promise<void> {
-    await this.post('/input/tap-normalized', { nx, ny })
-  }
-
   private async post(path: string, body: unknown): Promise<unknown> {
     const url = `${this.baseUrl}${path}`
     const headers: Record<string, string> = {
@@ -247,14 +147,3 @@ export class HttpSimRuntime implements SmixSimRuntime {
 
 /** v1.0.4 §D7 — re-export from Session.ts so this file's use compiles. */
 export type SessionState = 'healthy' | 'degraded' | 'cycling' | 'dead'
-
-function base64ToBytes(b64: string): Uint8Array {
-  if (typeof globalThis.atob === 'function') {
-    const bin = globalThis.atob(b64)
-    const out = new Uint8Array(bin.length)
-    for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i)
-    return out
-  }
-  // Node fallback
-  return Uint8Array.from(Buffer.from(b64, 'base64'))
-}

package/src/Locator.ts

@@ -1,5 +1,3 @@
-// v7.5 c3 — Locator poll loop, mirror Kotlin v7.4 c3 + Swift v7.1 c3.
-//
 // 250ms tick over a millisecond deadline. On timeout, throws
 // ExpectationFailure with the last tree's first-20 visible elements
 // populated for AI agent diagnosis.
@@ -53,10 +51,9 @@ export class Locator {
   }
 
   /**
-   * v7.6 c1 — Resolve [selector] until at least one match exists AND
-   * that match's label equals [label]. Polls via standard resolver +
-   * findById path (label is on the snapshot node, not on FFI's labels
-   * resolver which is more useful for count-based assertions).
+   * Resolve [selector] until a match exists and its label equals
+   * [label]. Reads the label off the snapshot node rather than the
+   * labels resolver, which answers about the whole match set.
    */
   async toHaveLabel(label: string, opts: { timeoutMs?: number } = {}): Promise<void> {
     return this.pollUntil({
@@ -68,10 +65,9 @@ export class Locator {
   }
 
   /**
-   * v7.6 c1 — Resolve [selector] until the labels resolver returns
-   * exactly [n] matches. Uses dedicated `app.labelsResolver` (wraps
-   * Rust `resolve_selector_labels`) so count semantics skip index
-   * modifier per Playwright "match all" behavior.
+   * Resolve [selector] until the labels resolver returns exactly [n]
+   * matches. Goes through the labels resolver so the count ignores any
+   * index modifier — counting asks about all matches, as in Playwright.
    */
   async toHaveCount(n: number, opts: { timeoutMs?: number } = {}): Promise<void> {
     const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
@@ -80,7 +76,7 @@ export class Locator {
     let lastTree: A11yNode | null = null
     const selectorJson = encodeSelectorJson(this.selector)
     while (true) {
-      const tree = await this.app.runtime.snapshotTree()
+      const tree = await this.app.snapshotTree()
       lastTree = tree
       let labels: readonly string[]
       try {
@@ -88,7 +84,7 @@ export class Locator {
       } catch (e) {
         const msg = e instanceof Error ? e.message : String(e)
         throw new ExpectationFailure({
-          code: 'unknown',
+          code: 'DRIVER_ERROR',
           message: `FFI resolveSelectorLabels raised during poll: ${msg}`,
           selectorJson,
         })
@@ -99,7 +95,7 @@ export class Locator {
       await delay(POLL_INTERVAL_MS)
     }
     throw new ExpectationFailure({
-      code: 'wrongState',
+      code: 'ASSERTION_FAILED',
       message: `expected ${n} matches, last poll saw ${lastCount}`,
       selectorJson,
       visibleElements: lastTree !== null ? flatten(lastTree).slice(0, 20) : [],
@@ -115,7 +111,7 @@ export class Locator {
    * app's runtime + resolver, then check predicates.
    *
    * - [successPredicate] returns true → return immediately
-   * - [wrongStatePredicate] returns true → throw wrongState
+   * - [wrongStatePredicate] returns true → throw NOT_VISIBLE
    * - Otherwise, continue polling.
    *
    * On timeout, throws timeout with the last tree's first-20 nodes.
@@ -130,7 +126,7 @@ export class Locator {
     let lastTree: A11yNode | null = null
 
     while (true) {
-      const tree = await this.app.runtime.snapshotTree()
+      const tree = await this.app.snapshotTree()
       lastTree = tree
       const selectorJson = encodeSelectorJson(this.selector)
       let matches: readonly string[]
@@ -139,7 +135,7 @@ export class Locator {
       } catch (e) {
         const msg = e instanceof Error ? e.message : String(e)
         throw new ExpectationFailure({
-          code: 'unknown',
+          code: 'DRIVER_ERROR',
           message: `FFI resolveSelector raised during poll: ${msg}`,
           selectorJson,
         })
@@ -149,7 +145,10 @@ export class Locator {
 
       if (opts.wrongStatePredicate(node)) {
         throw new ExpectationFailure({
-          code: 'wrongState',
+          // toBeVisible is the only caller that supplies a firing
+          // wrongStatePredicate, so this branch always means
+          // "matched, but not visible".
+          code: 'NOT_VISIBLE',
           message: 'element matched but predicate failed (e.g. not visible)',
           selectorJson,
           visibleElements: node !== null ? [node, ...flatten(tree).slice(0, 19)] : flatten(tree).slice(0, 20),
@@ -162,7 +161,7 @@ export class Locator {
     }
 
     throw new ExpectationFailure({
-      code: 'timeout',
+      code: 'TIMEOUT',
       message: opts.timeoutMessage,
       selectorJson: encodeSelectorJson(this.selector),
       visibleElements: lastTree !== null ? flatten(lastTree).slice(0, 20) : [],

package/src/NodeDriver.ts

@@ -0,0 +1,109 @@
+// The seam where live driving is supplied. The real driver is the napi
+// addon (`@goliapkg/smix-node`, wired in with the prebuild matrix — the C4
+// axis); its `SmixNodeDriver` / `SmixNodeSession` classes satisfy these
+// interfaces structurally. The mocks answer from memory so the App's
+// assembly logic (snapshot -> resolve -> tapById, range checks, enter ->
+// return) is unit-tested without the native addon and without a device —
+// the same seam-injection pattern as SelectorResolver.
+//
+// Every method returns what `crates/smix-node/index.d.ts` returns; the tree
+// and popups cross as JSON strings, parsed on this side.
+
+/** A live driver: the stateless act + sense verbs, plus session opening. */
+export interface NodeDriver {
+  tapById(id: string): Promise<boolean>
+  inputText(text: string): Promise<void>
+  pressKey(key: string): Promise<void>
+  swipe(direction: string): Promise<void>
+  tapAtCoord(nx: number, ny: number): Promise<string>
+  snapshotTree(): Promise<string>
+  systemPopups(): Promise<string>
+  openSession(bundleId: string): Promise<NodeSession>
+}
+
+/** A handle to an open session: the lifecycle verbs. */
+export interface NodeSession {
+  launchApp(): Promise<void>
+  terminateApp(): Promise<void>
+  relaunchApp(): Promise<void>
+}
+
+/** A recorded call: the verb name and the arguments it was given. */
+export interface RecordedCall {
+  readonly verb: string
+  readonly args: readonly unknown[]
+}
+
+/**
+ * Mock session for vitest. Records every lifecycle call; resolves them all.
+ */
+export class MockNodeSession implements NodeSession {
+  readonly calls: RecordedCall[] = []
+
+  async launchApp(): Promise<void> {
+    this.calls.push({ verb: 'launchApp', args: [] })
+  }
+
+  async terminateApp(): Promise<void> {
+    this.calls.push({ verb: 'terminateApp', args: [] })
+  }
+
+  async relaunchApp(): Promise<void> {
+    this.calls.push({ verb: 'relaunchApp', args: [] })
+  }
+}
+
+/**
+ * Mock driver for vitest. Pre-set the tree / popups JSON it returns; records
+ * every call; `tapById` reports a hit by default. `openSession` hands back a
+ * fresh (or supplied) MockNodeSession so lifecycle calls are inspectable.
+ */
+export class MockNodeDriver implements NodeDriver {
+  readonly calls: RecordedCall[] = []
+  treeJson =
+    '{"rawType":"application","enabled":true,"selected":false,"hasFocus":false,"visible":true,"bounds":{"x":0,"y":0,"w":0,"h":0}}'
+  popupsJson = '[]'
+  tapByIdResult = true
+  readonly session: MockNodeSession
+
+  constructor(session: MockNodeSession = new MockNodeSession()) {
+    this.session = session
+  }
+
+  async tapById(id: string): Promise<boolean> {
+    this.calls.push({ verb: 'tapById', args: [id] })
+    return this.tapByIdResult
+  }
+
+  async inputText(text: string): Promise<void> {
+    this.calls.push({ verb: 'inputText', args: [text] })
+  }
+
+  async pressKey(key: string): Promise<void> {
+    this.calls.push({ verb: 'pressKey', args: [key] })
+  }
+
+  async swipe(direction: string): Promise<void> {
+    this.calls.push({ verb: 'swipe', args: [direction] })
+  }
+
+  async tapAtCoord(nx: number, ny: number): Promise<string> {
+    this.calls.push({ verb: 'tapAtCoord', args: [nx, ny] })
+    return '{"chain":[]}'
+  }
+
+  async snapshotTree(): Promise<string> {
+    this.calls.push({ verb: 'snapshotTree', args: [] })
+    return this.treeJson
+  }
+
+  async systemPopups(): Promise<string> {
+    this.calls.push({ verb: 'systemPopups', args: [] })
+    return this.popupsJson
+  }
+
+  async openSession(bundleId: string): Promise<NodeSession> {
+    this.calls.push({ verb: 'openSession', args: [bundleId] })
+    return this.session
+  }
+}