@goliapkg/smix 1.0.27 → 2.0.0

package/src/Pattern.ts

@@ -1,5 +1,5 @@
-// v7.5 c1 — Pattern (literal vs regex) mirror Swift v7.2 c3 + Kotlin v7.4 c4
-// + Rust smix-selector `#[serde(untagged)] enum Pattern`.
+// The wire form of `smix-selector`'s untagged `Pattern` enum. Untagged
+// means the shape alone says which case it is, so these forms are exact:
 //
 // Wire JSON forms (untagged):
 //   Literal: bare string                   e.g. "hello"

package/src/Selector.ts

@@ -1,16 +1,13 @@
-// v7.5 c1 — Selector full 7-case + Modifiers flatten + Pattern + fluent.
+// The wire form of `smix-selector`'s untagged `Selector` enum, with
+// `Modifiers` flattened onto the Text/Id/Label/Role/LocalizedText bases.
+// Focused takes no modifiers; Anchor carries AnchorBox + IndexModifiers.
 //
-// Mirror Swift v7.2 c3 + Kotlin v7.4 c4 + Rust smix-selector
-// `#[serde(untagged)] enum Selector` with full `Modifiers` flatten on
-// Text/Id/Label/Role/LocalizedText bases. Focused has no modifiers.
-// Anchor uses AnchorBox + IndexModifiers.
-//
-// Class-based API (mirrors Kotlin sealed interface 1:1):
 //   sel.id('btn-login')
 //     .below(sel.text(literal('Sign In')))
 //     .nth(0)
 //
-// Each fluent method returns a NEW Selector (immutable copy semantics).
+// Each fluent method returns a NEW Selector, so a partly-built selector
+// can be shared and specialised without the branches affecting each other.
 
 import { type Pattern, patternFromJson, patternToJson } from './Pattern.js'
 

package/src/SelectorResolver.ts

@@ -1,8 +1,6 @@
-// v7.5 c1 — SelectorResolver injection boundary.
-//
-// Mirror Kotlin v7.4 c2 R-Kotlin-A: real impl wraps Rust FFI core
-// (in TS via HTTP runner or future ffi-napi binding); mock impl for
-// vitest. Lambda-style fn interface keeps the abstraction minimal.
+// The seam where selector resolution is supplied: the real one wraps the
+// Rust core over the HTTP runner, the mock answers from a table. A bare
+// function type keeps that seam as small as it can be.
 
 export type SelectorResolver = (
   treeJson: string,
@@ -10,9 +8,8 @@ export type SelectorResolver = (
 ) => Promise<readonly string[]>
 
 /**
- * v7.6 c1 — labels resolver wrapping Rust `resolve_selector_labels`
- * (each match's `.label`; empty string when None). Used by
- * Locator.toHaveCount + Locator.toHaveLabel.
+ * Wraps `resolve_selector_labels`: each match's label, empty string where
+ * it has none.
  */
 export type LabelsResolver = (
   treeJson: string,
@@ -22,7 +19,6 @@ export type LabelsResolver = (
 /**
  * Mock resolver for vitest unit tests. Pre-registered selectorJson →
  * id list mappings; falls back to empty list for unknown selectors.
- * Mirrors Kotlin MockSelectorResolver from v7.4 c2.
  */
 export class MockSelectorResolver {
   readonly returnMap = new Map<string, readonly string[]>()
@@ -51,8 +47,8 @@ export class MockSelectorResolver {
 }
 
 /**
- * v7.6 c1 — Mock labels resolver for vitest tests. Pre-registered
- * selectorJson → label list mappings. Mirrors Kotlin MockLabelsResolver.
+ * Mock labels resolver for unit tests. Pre-registered selectorJson →
+ * label list mappings.
  */
 export class MockLabelsResolver {
   readonly returnMap = new Map<string, readonly string[]>()

package/src/Smix.ts

@@ -1,15 +1,13 @@
-// v7.5 c1 — Smix top-level entry. Mirror Kotlin / Swift Smix.launchApp.
-//
-// Per R-7.5-B HTTP-runtime decision, the default SelectorResolver for
-// production points at the smix-runner HTTP server (lands v7.5 c3 in
-// src/HttpRunner.ts). For c1 MVP, callers must pass an explicit
-// SelectorResolver (e.g. MockSelectorResolver in tests; HttpSelectorResolver
-// in c3 production).
+// The entry point. Launching an app opens a napi session on the driver,
+// launches the app in it, and hands back a wired App. `appPath` targets need
+// a host-side install (no runner wire), so they throw a clear host-side error
+// rather than pretending; the bundleId path is the golden path.
 
 import { App } from './App.js'
+import { loadNodeDriver, loadNodeResolver } from './loadNodeDriver.js'
 import { SmixNotImplementedError } from './Locator.js'
+import type { NodeDriver } from './NodeDriver.js'
 import type { LabelsResolver, SelectorResolver } from './SelectorResolver.js'
-import type { SmixSimRuntime } from './SimRuntime.js'
 
 export type AppTarget =
   | { kind: 'bundleId'; value: string }
@@ -19,30 +17,36 @@ export const bundleId = (value: string): AppTarget => ({ kind: 'bundleId', value
 export const appPath = (path: string): AppTarget => ({ kind: 'appPath', path })
 
 /**
- * Top-level entry. Launches the target app via [runtime] and returns
- * an [App] handle wired with the given [resolver] for selector queries.
+ * Top-level entry. Opens a session bound to the target's bundle id, launches
+ * its app, and returns an [App] handle. Everything defaults to the real napi
+ * addon: the driver drives through it and the resolver resolves host-side
+ * through it (like the Swift / Kotlin SDKs through UniFFI). Inject `driver`,
+ * `resolver`, or `labelsResolver` for tests or a custom transport —
+ * `smix.launchApp(bundleId('com.acme.app'))` alone is the golden path.
  */
 export const Smix = {
   async launchApp(
     target: AppTarget,
-    runtime: SmixSimRuntime,
-    resolver: SelectorResolver,
-    labelsResolver?: LabelsResolver,
+    options?: {
+      driver?: NodeDriver
+      resolver?: SelectorResolver
+      labelsResolver?: LabelsResolver
+    },
   ): Promise<App> {
-    switch (target.kind) {
-      case 'bundleId': {
-        await runtime.launch(target.value)
-        return labelsResolver !== undefined
-          ? new App(target.value, runtime, resolver, labelsResolver)
-          : new App(target.value, runtime, resolver)
-      }
-      case 'appPath': {
-        await runtime.launchFromPath(target.path)
-        return labelsResolver !== undefined
-          ? new App(target.path, runtime, resolver, labelsResolver)
-          : new App(target.path, runtime, resolver)
-      }
+    if (target.kind !== 'bundleId') {
+      throw new SmixNotImplementedError('host', 'Smix.launchApp(appPath)')
     }
+    const driver = options?.driver ?? (await loadNodeDriver())
+    let resolver = options?.resolver
+    let labelsResolver = options?.labelsResolver
+    if (resolver === undefined || labelsResolver === undefined) {
+      const node = await loadNodeResolver()
+      resolver = resolver ?? node.resolver
+      labelsResolver = labelsResolver ?? node.labelsResolver
+    }
+    const session = await driver.openSession(target.value)
+    await session.launchApp()
+    return new App(target.value, driver, session, resolver, labelsResolver)
   },
 } as const
 

package/src/SystemPopup.ts

@@ -0,0 +1,24 @@
+// A system popup as the runner reports it — the TS mirror of
+// `smix_runner_wire::SystemPopup`. `App.systemPopups()` returns these
+// verbatim from the wire; it is NOT an A11yNode (a popup has `id` / `type` /
+// `source`, not accessibility geometry), so it carries its own type rather
+// than being cast to one.
+
+export interface SystemPopupButton {
+  readonly id: string
+  readonly label: string
+  /** Semantic role, e.g. "cancel" / "destructive" / "default". */
+  readonly role: string
+  readonly destructive: boolean
+}
+
+export interface SystemPopup {
+  readonly id: string
+  /** Discriminator, e.g. "alert" / "sheet" / "banner". */
+  readonly type: string
+  /** Originator, e.g. a bundle id or system framework name. */
+  readonly source: string
+  readonly title: string
+  readonly body: string
+  readonly buttons: readonly SystemPopupButton[]
+}

package/src/__tests__/AppDriving.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest'
+import { App } from '../App.js'
+import { MockNodeDriver, MockNodeSession } from '../NodeDriver.js'
+import { MockSelectorResolver } from '../SelectorResolver.js'
+import { Selector, encodeSelectorJson } from '../Selector.js'
+import { Smix, bundleId } from '../Smix.js'
+import { ExpectationFailure } from '../ExpectationFailure.js'
+
+function makeApp(driver = new MockNodeDriver(), resolver = new MockSelectorResolver()) {
+  return {
+    driver,
+    resolver,
+    app: new App('bid', driver, driver.session, resolver.resolve),
+  }
+}
+
+describe('App live sense (C3)', () => {
+  it('snapshotTree returns the parsed tree from the driver', async () => {
+    const driver = new MockNodeDriver()
+    driver.treeJson = '{"rawType":"application","identifier":"root","enabled":true,"selected":false,"hasFocus":false,"visible":true,"bounds":{"x":0,"y":0,"w":0,"h":0}}'
+    const { app } = makeApp(driver)
+    const tree = await app.snapshotTree()
+    expect(tree.identifier).toBe('root')
+    expect((await app.tree()).identifier).toBe('root')
+  })
+
+  it('systemPopups returns the wire SystemPopup list', async () => {
+    const driver = new MockNodeDriver()
+    driver.popupsJson = '[{"id":"p1","type":"alert","source":"SpringBoard","title":"","body":"","buttons":[]}]'
+    const { app } = makeApp(driver)
+    const popups = await app.systemPopups()
+    expect(popups).toHaveLength(1)
+    expect(popups[0]?.id).toBe('p1')
+    expect(popups[0]?.type).toBe('alert')
+  })
+})
+
+describe('App act verbs (C3)', () => {
+  it('tap resolves the selector to an id and taps it', async () => {
+    const { app, driver, resolver } = makeApp()
+    resolver.registerHit(encodeSelectorJson(Selector.id('btn-ok')), 'btn-ok')
+    await app.tap(Selector.id('btn-ok'))
+    expect(driver.calls.find((c) => c.verb === 'tapById')?.args[0]).toBe('btn-ok')
+  })
+
+  it('tap throws ELEMENT_NOT_FOUND with visibleElements when nothing resolves', async () => {
+    const { app } = makeApp()
+    await expect(app.tap(Selector.id('missing'))).rejects.toSatisfy(
+      (e: unknown) =>
+        e instanceof ExpectationFailure &&
+        e.code === 'ELEMENT_NOT_FOUND' &&
+        e.visibleElements.length > 0,
+    )
+  })
+
+  it('fill focuses then types', async () => {
+    const { app, driver, resolver } = makeApp()
+    resolver.registerHit(encodeSelectorJson(Selector.id('inp')), 'inp')
+    await app.fill(Selector.id('inp'), 'hello')
+    const verbs = driver.calls.map((c) => c.verb)
+    expect(verbs).toEqual(expect.arrayContaining(['tapById', 'inputText']))
+    expect(driver.calls.find((c) => c.verb === 'inputText')?.args[0]).toBe('hello')
+  })
+
+  it('pressKey maps enter to return and passes others through', async () => {
+    const { app, driver } = makeApp()
+    await app.pressKey('enter')
+    await app.pressKey('escape')
+    const keys = driver.calls.filter((c) => c.verb === 'pressKey').map((c) => c.args[0])
+    expect(keys).toEqual(['return', 'escape'])
+  })
+
+  it('swipe passes the direction through', async () => {
+    const { app, driver } = makeApp()
+    await app.swipe('up')
+    expect(driver.calls.find((c) => c.verb === 'swipe')?.args[0]).toBe('up')
+  })
+
+  it('tapAtCoord range-checks then taps', async () => {
+    const { app, driver } = makeApp()
+    await expect(app.tapAtCoord(1.5, 0.5)).rejects.toSatisfy(
+      (e: unknown) => e instanceof ExpectationFailure && e.code === 'ASSERTION_FAILED',
+    )
+    await app.tapAtCoord(0.5, 0.5)
+    expect(driver.calls.find((c) => c.verb === 'tapAtCoord')?.args).toEqual([0.5, 0.5])
+  })
+
+  it('terminate and relaunch fire on the session', async () => {
+    const { app, driver } = makeApp()
+    await app.terminate()
+    await app.relaunch()
+    const verbs = driver.session.calls.map((c) => c.verb)
+    expect(verbs).toEqual(['terminateApp', 'relaunchApp'])
+  })
+})
+
+describe('Smix.launchApp (C3 entry)', () => {
+  it('opens a session, launches, and returns a wired App', async () => {
+    const driver = new MockNodeDriver()
+    const resolver = new MockSelectorResolver()
+    const app = await Smix.launchApp(bundleId('com.acme.app'), { driver, resolver: resolver.resolve })
+    expect(app).toBeInstanceOf(App)
+    expect(driver.calls.find((c) => c.verb === 'openSession')?.args[0]).toBe('com.acme.app')
+    expect(driver.session.calls.filter((c) => c.verb === 'launchApp')).toHaveLength(1)
+  })
+})

package/src/__tests__/MvpApiShape.test.ts

@@ -1,37 +1,40 @@
-// v7.5 c1 — MVP shape JVM vitest tests.
-//
-// Mirror Kotlin MvpApiShapeTest + Swift MvpApiShapeTests. Verifies
-// the SDK exposes the right TypeScript types + constructors and that
-// stub surface throws SmixNotImplementedError with explicit stage
-// markers.
+// API-shape tests. Verifies the SDK exposes the right TypeScript types +
+// constructors, and that the live driving / sense surface — pending the
+// napi axis — throws SmixNotImplementedError rather than posting to a
+// route the runner never served.
 
 import { describe, expect, test } from 'vitest'
 import {
   App,
+  encodeSelectorJson,
   ExpectationFailure,
   FAILURE_CODES,
   literal,
+  MockNodeDriver,
   MockSelectorResolver,
-  MockSimRuntime,
   Selector,
   Smix,
   SmixNotImplementedError,
-  appPath,
   bundleId,
   type A11yRole,
   type FailureCode,
 } from '../index.js'
 
 describe('Selector base cases', () => {
-  test('selector base cases exhaustive', () => {
-    const cases: Selector[] = [
-      Selector.id('btn-login'),
-      Selector.text(literal('Sign In')),
-      Selector.label('Settings'),
-      Selector.role('button'),
-      Selector.role('button', literal('Submit')),
+  // Each constructor is asserted by the wire JSON it encodes to — a
+  // previous version built the five selectors and asserted the array
+  // had five elements, which a broken encoder passes.
+  test('every base constructor encodes its wire discriminator', () => {
+    const byWire: Array<[Selector, Record<string, unknown>]> = [
+      [Selector.id('btn-login'), { id: 'btn-login' }],
+      [Selector.text(literal('Sign In')), { text: 'Sign In' }],
+      [Selector.label('Settings'), { label: 'Settings' }],
+      [Selector.role('button'), { role: 'button' }],
+      [Selector.role('button', literal('Submit')), { role: 'button', name: 'Submit' }],
     ]
-    expect(cases.length).toBe(5)
+    for (const [sel, wire] of byWire) {
+      expect(JSON.parse(encodeSelectorJson(sel))).toEqual(wire)
+    }
   })
 
   test('Selector.id encodes as {"id":...}', () => {
@@ -51,23 +54,34 @@ describe('A11yRole', () => {
       'scrollView', 'segmentedControl', 'table', 'collectionView',
       'webView', 'keyboard',
     ]
-    expect(roles.length).toBe(28)
+    // The list's value is the type annotation above — each string must
+    // typecheck as A11yRole. The runtime assertion is only that the
+    // fixture has no duplicate entries; asserting its length proved
+    // nothing (the old `toBe(28)` passed with 28 wrong strings).
+    expect(new Set(roles).size).toBe(roles.length)
   })
 })
 
 describe('FailureCode', () => {
-  test('6 cases exposed', () => {
-    expect(FAILURE_CODES.length).toBe(6)
-    const expected = new Set<FailureCode>([
-      'notFound', 'ambiguous', 'notInteractable',
-      'timeout', 'wrongState', 'unknown',
-    ])
-    expect(new Set(FAILURE_CODES)).toEqual(expected)
+  // The vocabulary is Rust's — smix_error::FailureCode. Rust is the
+  // source; crates/smix-error/tests/sdk_failure_code_parity.rs reads
+  // this SDK's declaration and fails if the two ever diverge.
+  // The count is not hard-coded here. It used to be, and adding
+  // TAP_MISSED to the vocabulary left this asserting 9 against 10 — a
+  // second copy of the list that Rust's sdk_failure_code_parity gate
+  // could not see, because that gate reads FAILURE_CODES, not this
+  // test. So this checks the shape of FAILURE_CODES (no duplicates, a
+  // couple of anchors present) and leaves the count to parity.
+  test('the vocabulary is a set and carries its anchors', () => {
+    expect(new Set(FAILURE_CODES).size).toBe(FAILURE_CODES.length)
+    for (const code of ['ELEMENT_NOT_FOUND', 'TAP_MISSED', 'DRIVER_ERROR'] as FailureCode[]) {
+      expect(FAILURE_CODES).toContain(code)
+    }
   })
 
   test('toJson() emits stable keys', () => {
     const failure = new ExpectationFailure({
-      code: 'notFound',
+      code: 'ELEMENT_NOT_FOUND',
       message: 'no candidates',
       selectorJson: '{"id":"btn"}',
       suggestions: ['check id'],
@@ -80,7 +94,7 @@ describe('FailureCode', () => {
     }
   })
 
-  test('toJson() camelCase FailureCode raw value', () => {
+  test('toJson() emits the Rust wire FailureCode value', () => {
     for (const code of FAILURE_CODES) {
       const f = new ExpectationFailure({ code, message: '' })
       expect(f.toJson()).toContain(`"${code}"`)
@@ -88,30 +102,48 @@ describe('FailureCode', () => {
   })
 })
 
-// v7.6 c1 update: toHaveLabel + toHaveCount stubs replaced with real
-// wires via dedicated FFI resolve_selector_count / resolve_selector_labels.
-// All SDK API stubs from v7.5 c1 are now wired.
+describe('the driving surface works through the node seam; only host/wire gaps throw', () => {
+  const makeApp = () => {
+    const driver = new MockNodeDriver()
+    return new App('dev.smix.target', driver, driver.session, new MockSelectorResolver().resolve)
+  }
 
-describe('Smix.launchApp wire (v7.5 c1)', () => {
-  test('launchApp(.bundleId) calls runtime.launch', async () => {
-    const runtime = new MockSimRuntime()
-    await Smix.launchApp(bundleId('dev.smix.target'), runtime, new MockSelectorResolver().resolve)
-    expect(runtime.launchCalls).toEqual(['dev.smix.target'])
+  test('Smix.launchApp drives through the node driver and returns an App', async () => {
+    const app = await Smix.launchApp(bundleId('dev.smix.target'), {
+      driver: new MockNodeDriver(),
+      resolver: new MockSelectorResolver().resolve,
+    })
+    expect(app).toBeInstanceOf(App)
   })
 
-  test('launchApp(.appPath) dispatches to launchFromPath (mirror Swift v7.2 c5)', async () => {
-    const runtime = new MockSimRuntime()
-    const app = await Smix.launchApp(appPath('/tmp/Foo.apk'), runtime, new MockSelectorResolver().resolve)
-    expect(runtime.launchFromPathCalls).toEqual(['/tmp/Foo.apk'])
-    expect(runtime.launchCalls).toEqual([])
-    expect(app.bundleId).toBe('/tmp/Foo.apk')
+  test('retired act + sense methods no longer throw SmixNotImplementedError', async () => {
+    const app = makeApp()
+    // tap with an empty resolver fails ELEMENT_NOT_FOUND — a real failure,
+    // NOT SmixNotImplementedError. That distinction is the whole point.
+    await expect(app.tap(Selector.id('x'))).rejects.not.toBeInstanceOf(SmixNotImplementedError)
+    await expect(app.snapshotTree()).resolves.toBeDefined()
+    await expect(app.tree()).resolves.toBeDefined()
+    await expect(app.systemPopups()).resolves.toBeDefined()
+  })
+
+  test('screenshot / openUrl / launchFresh still throw, re-labeled off napi', async () => {
+    const app = makeApp()
+    const gaps: Array<[() => Promise<unknown>, string]> = [
+      [() => app.screenshot(), 'wire'],
+      [() => app.openUrl('https://x'), 'wire'],
+      [() => app.launchFresh(), 'host'],
+    ]
+    for (const [call, stage] of gaps) {
+      await expect(call()).rejects.toSatisfy(
+        (e: unknown) => e instanceof SmixNotImplementedError && e.stage === stage,
+      )
+    }
   })
 
-  test('relaunch issues terminate + launch', async () => {
-    const runtime = new MockSimRuntime()
-    const app = await Smix.launchApp(bundleId('dev.smix.target'), runtime, new MockSelectorResolver().resolve)
-    await app.relaunch()
-    expect(runtime.launchCalls).toEqual(['dev.smix.target', 'dev.smix.target'])
-    expect(runtime.terminateCalls).toEqual(['dev.smix.target'])
+  test('Locator polls the real tree seam rather than throwing napi', async () => {
+    const app = makeApp()
+    await expect(
+      app.find(Selector.id('x')).toBeVisible({ timeoutMs: 50 }),
+    ).rejects.not.toBeInstanceOf(SmixNotImplementedError)
   })
 })

package/src/__tests__/ReadmeSnippets.test.ts

@@ -0,0 +1,132 @@
+// The package README's code, type-checked and run.
+//
+// Nothing compiled these: the repo README's Rust snippet is now pinned
+// by a compiled copy, but this package's four blocks — the ones an npm
+// visitor reads first — had no such tie. The blocks below are the
+// README's verbatim; the string test proves the README still says what
+// this file compiles, and `tsc` proves this file matches the source.
+
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import {
+  App,
+  ExpectationFailure,
+  HttpSimRuntime,
+  MockNodeDriver,
+  MockSelectorResolver,
+  Selector,
+  Session,
+  SmixNotImplementedError,
+  literal,
+  regex,
+} from '../index'
+
+const README = readFileSync(join(__dirname, '..', '..', 'README.md'), 'utf8')
+
+/** The README's "Selector" block, verbatim. */
+function selectorBlock(): void {
+Selector.id('btn-login')
+Selector.text(literal('Sign In'))
+Selector.text(regex('^Sub', 'i'))
+Selector.label('Settings')
+Selector.role('button', literal('Submit'))
+Selector.localizedText({ en: 'Submit', ja: '送信' })
+
+// Fluent modifier chaining (returns a new Selector)
+Selector.id('btn').below(Selector.text(literal('Address'))).nth(0)
+Selector.role('button').near(Selector.text(literal('Confirm')))
+}
+
+/** The README's "Session lifecycle" block, verbatim. */
+async function sessionBlock(): Promise<void> {
+const runtime = new HttpSimRuntime('http://127.0.0.1:22087')
+const session = await Session.open(runtime, 'com.example.app')
+await session.relaunchApp()
+await session.close()
+}
+
+describe('the README compiles', () => {
+  it('has the selector block this file type-checks', () => {
+    // Referencing them keeps the compiler honest about the block being
+    // real code rather than dead text; neither needs a runner to exist.
+    expect(typeof selectorBlock).toBe('function')
+    expect(typeof sessionBlock).toBe('function')
+  })
+
+  it('every non-comment line of the README code appears in this file', () => {
+    const thisFile = readFileSync(__filename, 'utf8')
+    const blocks = [...README.matchAll(/```typescript\n([\s\S]*?)```/g)].map(
+      (m) => m[1] ?? '',
+    )
+    expect(blocks.length).toBeGreaterThanOrEqual(3)
+    const missing: string[] = []
+    for (const block of blocks) {
+      for (const line of block.split('\n')) {
+        const t = line.trim()
+        // Skip blank lines, imports (rewritten to a relative path
+        // here), and the ExpectationFailure block's illustrative body.
+        if (!t || t.startsWith('import') || t.startsWith('//')) continue
+        if (t.startsWith('e.') || t === 'try {' || t === '} catch (e) {') continue
+        if (t.startsWith('if (e instanceof') || t === '}') continue
+        if (!thisFile.includes(t)) missing.push(t)
+      }
+    }
+    expect(missing, 'README lines with no compiled counterpart').toEqual([])
+  })
+})
+
+describe('the README\'s claims about this package', () => {
+  it('exports ExpectationFailure with the documented shape', () => {
+    const f = new ExpectationFailure({
+      code: 'ELEMENT_NOT_FOUND',
+      message: 'no such element',
+    })
+    // The README tells readers to reach for exactly these.
+    expect(f.code).toBe('ELEMENT_NOT_FOUND')
+    expect(Array.isArray(f.visibleElements)).toBe(true)
+    expect(Array.isArray(f.suggestions)).toBe(true)
+    expect(typeof f.toJson()).toBe('string')
+    expect(f.toJson()).not.toContain('\n')
+  })
+})
+
+describe('the README\'s throw-warning is true', () => {
+  // The warning is the first thing an npm visitor reads. It must not lie in
+  // either direction: a method it says still throws must throw, and a method
+  // it shows driving must no longer throw SmixNotImplementedError.
+  const makeApp = () => {
+    const driver = new MockNodeDriver()
+    return new App('com.example.app', driver, driver.session, new MockSelectorResolver().resolve)
+  }
+
+  it('names exactly the three surfaces that still throw, and they do', async () => {
+    const gaps = new Set(
+      [...README.matchAll(/`App\.(screenshot|openUrl|launchFresh)`/g)].map((m) => m[1]),
+    )
+    expect(gaps, 'README must name screenshot, openUrl, launchFresh as still-throwing').toEqual(
+      new Set(['screenshot', 'openUrl', 'launchFresh']),
+    )
+    const app = makeApp()
+    const calls: Array<() => Promise<unknown>> = [
+      () => app.screenshot(),
+      () => app.openUrl('https://x'),
+      () => app.launchFresh(),
+    ]
+    for (const call of calls) {
+      await expect(call()).rejects.toBeInstanceOf(SmixNotImplementedError)
+    }
+  })
+
+  it('the driving methods the README shows working no longer throw napi', async () => {
+    const app = makeApp()
+    // Empty resolver -> tap fails ELEMENT_NOT_FOUND, a real failure, NOT
+    // SmixNotImplementedError; snapshotTree drives and resolves.
+    await expect(app.tap(Selector.id('x'))).rejects.not.toBeInstanceOf(SmixNotImplementedError)
+    await expect(app.fill(Selector.id('x'), 't')).rejects.not.toBeInstanceOf(
+      SmixNotImplementedError,
+    )
+    await expect(app.snapshotTree()).resolves.toBeDefined()
+  })
+})