peachsim 0.1.657 → 0.1.659

package/README.md

@@ -243,7 +243,22 @@ Windows use Playwright's Chromium headless shell instead: the same build and
 software renderer without the desktop browser's printing and service discovery
 libraries (`libcups2`, `libavahi-client3`). Headed launches and every launch on
 a Mac use full Chromium. When the needed browser is not installed, the CLI runs
-the resolved Playwright core's absolute installer entry for just that browser. Later opens reuse that sim and
+the resolved Playwright core's absolute installer entry for just that browser.
+On Linux the CLI checks the browser's shared libraries before launching and,
+when any are missing, exits naming them and the exact `apt-get install` line.
+The headless shell needs these Debian 12 packages (Ubuntu 24.04 and Debian 13
+add a `t64` suffix to `libglib2.0-0`, `libatk1.0-0`, `libatk-bridge2.0-0`,
+`libatspi2.0-0` and `libasound2`):
+
+```sh
+apt-get install --no-install-recommends libglib2.0-0 libnspr4 libnss3 \
+  libatk1.0-0 libatk-bridge2.0-0 libatspi2.0-0 libdbus-1-3 libx11-6 libxcb1 \
+  libxcomposite1 libxdamage1 libxext6 libxfixes3 libxrandr2 libgbm1 libexpat1 \
+  libxkbcommon0 libudev1 libasound2
+```
+
+Headed launches on Linux use full Chromium, which also needs `libcups2`,
+`libcairo2` and `libpango-1.0-0`. Later opens reuse that sim and
 reload it at the requested target. Use `peach do reload` when the target has not
 changed.
 Reserve `--new` for a genuinely concurrent sim; repeated new browser trees
@@ -628,7 +643,11 @@ serves its selected version from a version-specific localhost origin, so a
 background activation cannot mix an already loaded shell with chunks from the
 next runtime. Without config, each new open selects the active stable version.
 When `peach.config.ts` sets `runtimeVersion`, `peach open` installs that
-version without changing the machine default. App config, native-linked fonts,
+version without changing the machine default. The same file replaces an app's own
+native modules (`nativeModules`, `turboModules`) and native views
+(`nativeViews`, keyed by the `requireNativeComponent` name or an Expo view's
+`Module_View` name) with project-local files; the configuration guide in the
+docs lists every slot. App config, native-linked fonts,
 and splash assets all resolve from the project root advertised by the selected
 development server. Bare Metro, which has no Expo manifest project root, uses
 the listening development process's cwd inside that same resolver. The invoking

package/cli/app-config.ts

@@ -27,6 +27,7 @@ function isPeachConfig(value: unknown): value is PeachConfig {
     isOptionalRecord(Reflect.get(value, 'modules')) &&
     isOptionalRecord(Reflect.get(value, 'turboModules')) &&
     isOptionalRecord(Reflect.get(value, 'nativeModules')) &&
+    isOptionalRecord(Reflect.get(value, 'nativeViews')) &&
     isOptionalRecord(Reflect.get(value, 'env')) &&
     isOptionalRecord(network) &&
     isOptionalRecord(Reflect.get(value, 'settings')) &&
@@ -34,22 +35,37 @@ function isPeachConfig(value: unknown): value is PeachConfig {
   )
 }
 
+// `{ file }` entries are relative to the config file; the engine loads them by
+// absolute path from the runtime's replacement-module endpoint.
+function resolveFileEntries<T>(
+  entries: Record<string, T> | undefined,
+  configDir: string,
+): Record<string, T> | undefined {
+  if (!entries) return entries
+  return Object.fromEntries(
+    Object.entries(entries).map(([name, resolution]) => [
+      name,
+      resolution &&
+      typeof resolution === 'object' &&
+      'file' in resolution &&
+      typeof resolution.file === 'string'
+        ? { ...resolution, file: path.resolve(configDir, resolution.file) }
+        : resolution,
+    ]),
+  )
+}
+
 function resolveConfigReplacementFiles(
   config: PeachConfig,
   configPath: string,
 ): PeachConfig {
-  if (!config.modules) return config
   const configDir = path.dirname(configPath)
   return {
     ...config,
-    modules: Object.fromEntries(
-      Object.entries(config.modules).map(([name, resolution]) => [
-        name,
-        resolution && typeof resolution === 'object' && 'file' in resolution
-          ? { ...resolution, file: path.resolve(configDir, resolution.file) }
-          : resolution,
-      ]),
-    ),
+    modules: resolveFileEntries(config.modules, configDir),
+    turboModules: resolveFileEntries(config.turboModules, configDir),
+    nativeModules: resolveFileEntries(config.nativeModules, configDir),
+    nativeViews: resolveFileEntries(config.nativeViews, configDir),
   }
 }
 

package/cli/bridge-flow-runner.ts

@@ -920,7 +920,6 @@ export class SootSimBridgeFlowRunner {
 
   private firstLaunchDone = false
   private appStopped = false
-  private launchArgumentsActive = false
   private profilingEnabled = false
   private recordingEnabled = false
   private recordingAccessChecked = false
@@ -2604,22 +2603,6 @@ export class SootSimBridgeFlowRunner {
     throw new Error('extendedWaitUntil timed out')
   }
 
-  private async reloadGuestApp() {
-    // try the gentle reload first — in-place React re-mount preserves
-    // recording state and avoids the full worker lifecycle tear-down.
-    const reloaded = await this.bridge.send({
-      type: 'call',
-      simId: this.opts.simId,
-      path: 'SootSim.bridges.hotRemount.reloadExternalApp',
-      args: [],
-    })
-    if (reloaded) return
-
-    // fallback for surfaces that don't export the hot-remount bridge: a
-    // hard page reload resets the tenant worker.
-    await this.evaluate('window.location.reload()').catch(() => {})
-  }
-
   private async resetGuestAppData(
     launchOptions?: Pick<
       SootSimExternalAppLifecycleOptions,
@@ -2690,6 +2673,7 @@ export class SootSimBridgeFlowRunner {
     }
     const wantsClear = !!(opts && typeof opts === 'object' && opts.clearState)
     const wantsResetRuntime = readBooleanKey(opts, 'resetRuntime')
+    const wantsForeground = isObjectRecord(opts) && opts.stopApp === false
     await this.setLaunchPermissions(isObjectRecord(opts) ? opts.permissions : undefined)
 
     if (!this.firstLaunchDone) {
@@ -2727,7 +2711,14 @@ export class SootSimBridgeFlowRunner {
         await this.waitForTree(120000)
         await this.waitForTree(30000)
       } else {
-        await this.launchShellAppFromHomeIfNeeded(opts)
+        const launched = await this.launchShellAppFromHomeIfNeeded(opts)
+        if (!launched && !wantsForeground) {
+          await this.waitForTree(120000)
+          await this.reloadGuestAppRuntime({
+            launchArguments: null,
+            initialUrl: null,
+          })
+        }
         await this.waitForTree(120000)
         await this.waitForTree(30000)
       }
@@ -2737,13 +2728,11 @@ export class SootSimBridgeFlowRunner {
           launchArguments: hasLaunchArguments ? launchArguments : null,
           initialUrl: null,
         })
-      } else if (hasLaunchArguments || this.launchArgumentsActive || this.appStopped) {
+      } else if (hasLaunchArguments || this.appStopped || !wantsForeground) {
         await this.reloadGuestAppRuntime({
           launchArguments: hasLaunchArguments ? launchArguments : null,
           initialUrl: null,
         })
-      } else {
-        await this.reloadGuestApp()
       }
       await this.waitForTree(120000)
       if (this.opts.onAfterLaunch) {
@@ -2760,7 +2749,6 @@ export class SootSimBridgeFlowRunner {
     }
 
     this.appStopped = false
-    this.launchArgumentsActive = hasLaunchArguments
 
     if (this.profilingEnabled) {
       await this.startProfile()
@@ -3014,7 +3002,6 @@ export class SootSimBridgeFlowRunner {
       throw new Error(`openLink failed: ${result?.error || 'no test bridge'}`)
     }
     this.appStopped = false
-    this.launchArgumentsActive = false
     this.firstLaunchDone = true
   }
 

package/cli/commands/compat.ts

@@ -1,6 +1,15 @@
-// peach compat — scan dependencies with the shared compatibility engine.
+// peach compat — scan dependencies with the shared compatibility engine, and
+// the app's own native modules and views.
 
-import { relative, resolve } from 'node:path'
+import {
+  existsSync,
+  lstatSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  statSync,
+} from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
 import {
   COMPAT_RESULT_CAVEAT,
   formatDetailedScanLines,
@@ -8,8 +17,11 @@ import {
   scanDeps,
   type ScanResult,
 } from '@peach/compat/web'
+import { rnxPublicBrand } from '../../src/public-brand'
+import { resolveRNXAppConfig } from '../app-config'
 import {
   findProjectRoot,
+  scanRepository,
   scanWorkspace,
   installedManifest,
   readProjectManifest,
@@ -19,7 +31,7 @@ import type { ProjectManifest } from './projectReportContract'
 export async function runCompat(args: string[]): Promise<void> {
   if (args.includes('--help') || args.includes('-h')) {
     console.log(`
-peach compat — check package compatibility
+peach compat — check package compatibility and the app's own native code
 
 usage:
   peach compat [package-name]
@@ -48,13 +60,13 @@ flags:
   }
 
   if (packageName) {
-    report(args, scanOnePackage(appDir, pkg, packageName))
+    report(args, scanOnePackage(appDir, pkg, packageName), null)
     return
   }
 
   const here = scanDeps(installedManifest(appDir, pkg))
   if (here.packages.length > 0 || appIndex >= 0) {
-    report(args, here)
+    report(args, here, await scanLocalNative(appDir, pkg))
     return
   }
 
@@ -67,13 +79,13 @@ flags:
     const manifest = readProjectManifest(app.dir)
     if (!manifest) return []
     const result = scanDeps(installedManifest(app.dir, manifest))
-    return result.packages.length > 0 ? [{ dir: app.dir, result }] : []
+    return result.packages.length > 0 ? [{ dir: app.dir, manifest, result }] : []
   })
 
   if (elsewhere.length === 1) {
     const only = elsewhere[0]
     console.log(`\n  scanning ${relative(appDir, only.dir) || '.'}`)
-    report(args, only.result)
+    report(args, only.result, await scanLocalNative(resolve(only.dir), only.manifest))
     return
   }
   if (elsewhere.length > 1) {
@@ -84,16 +96,20 @@ flags:
     console.log()
     return
   }
-  report(args, here)
+  report(args, here, await scanLocalNative(appDir, pkg))
 }
 
-function report(args: string[], result: ScanResult): void {
+function report(args: string[], result: ScanResult, local: LocalNative[] | null): void {
   if (args.includes('--json')) {
-    console.log(JSON.stringify(result, null, 2))
+    console.log(
+      JSON.stringify(local ? { ...result, localNative: local } : result, null, 2),
+    )
     return
   }
   if (args.includes('--brief')) {
     console.log(`  ${formatScanCounts(result)}`)
+    if (local?.length)
+      console.log(`  the app's own native modules and views: ${local.length}`)
     console.log(`  ${COMPAT_RESULT_CAVEAT}`)
     return
   }
@@ -110,9 +126,217 @@ function report(args: string[], result: ScanResult): void {
   if (result.packages.length === 0) {
     console.log(`    no React Native ecosystem packages detected`)
   }
+  if (local?.length) reportLocalNative(local)
   console.log(`\n  ${COMPAT_RESULT_CAVEAT}\n`)
 }
 
+function reportLocalNative(local: LocalNative[]): void {
+  console.log(`\n  the app's own native modules and views`)
+  console.log(`  Peach does not run an app's native code. until peach.config.ts answers`)
+  console.log(`  for one, a module is an inert stand-in and a view renders empty.\n`)
+  const open = local.filter((item) => !item.answered)
+  const width = Math.max(...local.map((item) => item.name.length))
+  for (const item of local) {
+    const where = item.expoModule
+      ? `${item.path} (Expo module ${item.expoModule}${item.swift ? ', Swift' : ''})`
+      : item.path
+    console.log(
+      `    ${item.kind === 'view' ? 'view  ' : 'module'} ${item.name.padEnd(width)}  ${where}${item.answered ? '  answered in peach.config.ts' : ''}`,
+    )
+  }
+  const modules = open.filter((item) => item.kind === 'module')
+  const views = open.filter((item) => item.kind === 'view')
+  if (open.length) {
+    console.log(
+      `\n  answer ${open.length === local.length ? 'them' : 'the rest'} from peach.config.ts:\n`,
+    )
+    console.log(`    export default defineConfig({`)
+    if (modules.length) {
+      console.log(`      nativeModules: {`)
+      for (const item of modules) {
+        console.log(`        ${item.name}: { file: './peach/${item.name}.ts' },`)
+      }
+      console.log(`      },`)
+    }
+    if (views.length) {
+      console.log(`      nativeViews: {`)
+      for (const item of views) {
+        console.log(`        ${item.name}: { file: './peach/${item.name}.tsx' },`)
+      }
+      console.log(`      },`)
+    }
+    console.log(`    })`)
+  }
+  console.log(`\n  guide: ${rnxPublicBrand.origin}/docs/rnx/compat/custom-stubs`)
+}
+
+// an app's own native code, found from the names its JavaScript asks the native
+// side for and from local Expo modules (a directory with expo-module.config.json).
+// each name is the key the matching peach.config slot takes.
+export interface LocalNative {
+  kind: 'module' | 'view'
+  name: string
+  // first place the name appears, relative to the app, as file:line
+  path: string
+  // the local Expo module directory the name belongs to, relative to the app
+  expoModule: string | null
+  swift: boolean
+  // the app's peach.config.ts already names it
+  answered: boolean
+}
+
+const SOURCE_FILE = /\.[cm]?[jt]sx?$/
+const NATIVE_SOURCE_FILE = /\.(?:swift|kt)$/
+// a requireNativeView(module, view) name is `module_view`, the key the engine
+// registers expo views under.
+const LOOKUPS: { kind: LocalNative['kind']; pattern: RegExp }[] = [
+  {
+    kind: 'view',
+    pattern: /\brequireNativeComponent\s*(?:<[^;]{0,200}?>)?\(\s*['"]([\w$.-]+)['"]/g,
+  },
+  {
+    kind: 'view',
+    pattern:
+      /\brequireNativeView(?:Manager)?\s*(?:<[^;]{0,200}?>)?\(\s*['"](\w+)['"]\s*(?:,\s*['"](\w+)['"])?/g,
+  },
+  {
+    kind: 'module',
+    pattern:
+      /\brequire(?:Optional)?NativeModule\s*(?:<[^;]{0,200}?>)?\(\s*['"](\w+)['"]/g,
+  },
+  {
+    kind: 'module',
+    pattern:
+      /\bTurboModuleRegistry\.get(?:Enforcing)?\s*(?:<[^;]{0,200}?>)?\(\s*['"](\w+)['"]/g,
+  },
+]
+
+async function scanLocalNative(
+  appDir: string,
+  pkg: ProjectManifest,
+): Promise<LocalNative[]> {
+  const { config } = await resolveRNXAppConfig(appDir)
+  const answered = {
+    module: new Set(Object.keys({ ...config?.turboModules, ...config?.nativeModules })),
+    view: new Set(Object.keys(config?.nativeViews ?? {})),
+  }
+  const expoModuleDirs: string[] = []
+  const sourceFiles: string[] = []
+  for (const root of [appDir, ...workspacePackageDirs(appDir, pkg)]) {
+    for (const dir of scanRepository(root).directories) {
+      if (existsSync(join(dir, 'expo-module.config.json'))) expoModuleDirs.push(dir)
+      for (const name of listDir(dir)) {
+        if (SOURCE_FILE.test(name) && !name.endsWith('.d.ts'))
+          sourceFiles.push(join(dir, name))
+      }
+    }
+  }
+  const nativeFilesByModule = new Map(
+    expoModuleDirs.map((dir) => [
+      dir,
+      scanRepository(dir).directories.flatMap((sub) =>
+        listDir(sub)
+          .filter((name) => NATIVE_SOURCE_FILE.test(name))
+          .map((name) => join(sub, name)),
+      ),
+    ]),
+  )
+
+  const found = new Map<string, LocalNative>()
+  const add = (
+    kind: LocalNative['kind'],
+    name: string,
+    file: string,
+    text: string,
+    at = 0,
+  ) => {
+    const key = `${kind}:${name}`
+    if (found.has(key)) return
+    const moduleDir = expoModuleDirs.find((dir) => file.startsWith(`${dir}/`)) ?? null
+    found.set(key, {
+      kind,
+      name,
+      path: `${relative(appDir, file)}:${text.slice(0, at).split('\n').length}`,
+      expoModule: moduleDir ? relative(appDir, moduleDir) || '.' : null,
+      swift: moduleDir
+        ? (nativeFilesByModule.get(moduleDir) ?? []).some((path) =>
+            path.endsWith('.swift'),
+          )
+        : false,
+      answered: answered[kind].has(name),
+    })
+  }
+  for (const file of sourceFiles) {
+    const text = readSmallFile(file)
+    if (!text || !/requireNative|TurboModuleRegistry/.test(text)) continue
+    for (const { kind, pattern } of LOOKUPS) {
+      for (const match of text.matchAll(pattern)) {
+        const name = match[2] ? `${match[1]}_${match[2]}` : match[1]
+        if (name) add(kind, name, file, text, match.index)
+      }
+    }
+  }
+  // a local expo module declares its name in its native definition, Name("X"),
+  // whether or not the app's javascript spells it out.
+  for (const [, files] of nativeFilesByModule) {
+    for (const file of files) {
+      const text = readSmallFile(file)
+      if (!text) continue
+      for (const match of text.matchAll(/\bName\(\s*"(\w+)"\s*\)/g)) {
+        if (match[1]) add('module', match[1], file, text, match.index)
+      }
+    }
+  }
+  return [...found.values()].sort(
+    (a, b) => a.kind.localeCompare(b.kind) || a.name.localeCompare(b.name),
+  )
+}
+
+function listDir(dir: string): string[] {
+  try {
+    return readdirSync(dir)
+  } catch {
+    return []
+  }
+}
+
+function readSmallFile(file: string): string | null {
+  try {
+    return statSync(file).size <= 1024 * 1024 ? readFileSync(file, 'utf8') : null
+  } catch {
+    return null
+  }
+}
+
+// dependencies installed as links to source outside any node_modules are the
+// app's own workspace packages, which hold its native code as often as the app
+// directory does.
+function workspacePackageDirs(appDir: string, pkg: ProjectManifest): string[] {
+  const dirs = new Set<string>()
+  for (const name of Object.keys({ ...pkg.dependencies, ...pkg.devDependencies })) {
+    let current = appDir
+    while (true) {
+      const link = join(current, 'node_modules', name)
+      if (existsSync(link)) {
+        if (lstatSync(link).isSymbolicLink()) {
+          const target = realpathSync(link)
+          if (
+            !target.split('/').includes('node_modules') &&
+            !target.startsWith(`${appDir}/`)
+          ) {
+            dirs.add(target)
+          }
+        }
+        break
+      }
+      const parent = dirname(current)
+      if (parent === current) break
+      current = parent
+    }
+  }
+  return [...dirs]
+}
+
 function scanOnePackage(
   appDir: string,
   pkg: ProjectManifest,

package/cli/commands/do-chain.ts

@@ -313,7 +313,7 @@ export async function runDoChain(
   const { SimPerformError } = simClientModule
   const { checkSimHealth, parseBridgeCliArgs } = bridgeModule
   const { isAgentEnv } = envModule
-  const { resolveTargetCoords } = targetModule
+  const { offscreenTargetRefusal, resolveTargetCoords } = targetModule
   const wantsJson = args.includes('--json')
   const skipSettle = args.includes('--no-wait') || process.env.PEACH_NO_AUTO_WAIT === '1'
   const parsed = parseBridgeCliArgs(args, {
@@ -355,6 +355,10 @@ export async function runDoChain(
           `do chain could not find testID ${JSON.stringify(action.id)}`,
         )
       }
+      const refusal = offscreenTargetRefusal(sim.plane, target)
+      if (refusal) {
+        throw new BridgeInputError(`do chain #${action.id}: ${refusal}`)
+      }
       steps.push(
         action.type === 'targetedDoubleTap'
           ? {

package/cli/commands/inspect/actions.ts

@@ -1,5 +1,11 @@
 import { inspectTree, type InspectBridge } from './core'
-import { resolveTargetCoords, type ResolvedTargetCoords } from './resolve-target'
+import {
+  isOffscreen,
+  isScreenSize,
+  resolveTargetCoords,
+  UNREPORTED_SCREEN_ERROR,
+  type ResolvedTargetCoords,
+} from './resolve-target'
 import { waitForSootsimIdle } from './settling'
 import type { SimSemanticNode } from '../../../src/bridge-contract'
 import type {
@@ -39,54 +45,6 @@ export interface TapTimingOptions {
   retryWaitMs?: number
 }
 
-type ScreenSize = { width: number; height: number }
-
-function isScreenSize(value: unknown): value is ScreenSize {
-  if (value === null || typeof value !== 'object') return false
-  const width = Reflect.get(value, 'width')
-  const height = Reflect.get(value, 'height')
-  return (
-    typeof width === 'number' &&
-    Number.isFinite(width) &&
-    width > 0 &&
-    typeof height === 'number' &&
-    Number.isFinite(height) &&
-    height > 0
-  )
-}
-
-function viewportFromCapture(value: unknown): unknown {
-  if (value === null || typeof value !== 'object') return undefined
-  const tree = Reflect.get(value, 'tree')
-  return tree !== null && typeof tree === 'object'
-    ? Reflect.get(tree, 'viewport')
-    : undefined
-}
-
-// the semantic tree has no covering root, so its first node is often a 64x64
-// icon. capture.tree.viewport is the device layout size on local and cloud.
-//
-// a whole screen capture is the only way to ask for it today, and it is not
-// cheap: the headless runtime forces a full redraw of the tree before it walks
-// it, which measured 3.9-5.5s on a real app in a cloud box against 120-290ms
-// for every other command. that is why this runs on the failure path only.
-async function readScreen(bridge: InspectBridge): Promise<ScreenSize | null> {
-  try {
-    const viewport = viewportFromCapture(
-      await bridge.send({ type: 'capture', includeVisual: false }),
-    )
-    return isScreenSize(viewport)
-      ? { width: viewport.width, height: viewport.height }
-      : null
-  } catch {
-    return null
-  }
-}
-
-function isOffscreen(cx: number, cy: number, screen: ScreenSize): boolean {
-  return !(cx >= 0 && cy >= 0 && cx <= screen.width && cy <= screen.height)
-}
-
 const DEFAULT_AGENT_TIMING: Required<TapTimingOptions> = {
   initialWaitMs: 3000,
   deadlineMs: 5000,
@@ -185,19 +143,24 @@ export async function tapResolvedTarget(
 
   const deadline = Date.now() + timing.deadlineMs
   let lastOffscreenAt: string | null = null
-  // a cloud sim refuses a point outside its screen itself, and says so, so
-  // asking it for a capture first would buy nothing. every other plane still
-  // presses whatever the hit test finds at tree coordinates no finger can
-  // reach, so there the screen has to be read before dispatching.
-  const screen = bridge.plane === 'cloud' ? null : await readScreen(bridge)
   while (Date.now() <= deadline || attempts === 0) {
     attempts++
-    const resolved = await args.resolve()
+    const { screen, ...resolved } = (await args.resolve()) ?? {}
+    // a cloud sim refuses a point outside its screen itself, and says so. every
+    // other plane still presses whatever the hit test finds at tree
+    // coordinates no finger can reach, so the resolved target's screen decides
+    // before dispatching. a runtime too old to report it cannot be checked; a
+    // zero screen is one not laid out yet, so the attempt waits and retries.
+    const checksScreen = bridge.plane !== 'cloud' && typeof resolved.cx === 'number'
+    if (checksScreen && screen === undefined) {
+      throw new Error(UNREPORTED_SCREEN_ERROR)
+    }
+    const unsized = checksScreen && !isScreenSize(screen)
     const payload =
-      resolved &&
+      checksScreen &&
       typeof resolved.cx === 'number' &&
       typeof resolved.cy === 'number' &&
-      screen &&
+      isScreenSize(screen) &&
       isOffscreen(resolved.cx, resolved.cy, screen)
         ? { ...resolved, offscreen: true, screen }
         : resolved
@@ -215,7 +178,10 @@ export async function tapResolvedTarget(
       // don't dispatch a point outside the device screen: the press would do
       // nothing a user could reproduce. report the offscreen miss instead so
       // drivers scroll first rather than getting stuck trusting a phantom hit.
-      if (payload.offscreen) {
+      if (unsized) {
+        lastResult = { hit: false, reason: 'screen-not-laid-out' }
+        lastOffscreenAt = null
+      } else if (payload.offscreen) {
         lastResult = {
           hit: false,
           reason: 'offscreen',
@@ -310,6 +276,7 @@ function payloadFromResolved(
   return {
     cx: resolved.x,
     cy: resolved.y,
+    screen: resolved.viewport,
     match: {
       nodeId: match.nodeId ?? null,
       id: match.testID ?? null,
@@ -489,25 +456,14 @@ async function resolveTextTapTarget(
   if (!picked) return { matched: 0, total }
   const node = picked.node
   // keep the selected handle: re-searching its text or testID can pick a
-  // different control, including a covered tenant behind native UI.
-  const tap: unknown = await bridge.send({
-    type: 'call',
-    path: 'SootSim.bridges.test.resolveTapTarget',
-    args: [node.nodeId],
+  // different control, including a covered tenant behind native UI. resolve by
+  // node is a read, so a remote simulator's driving token can send it.
+  const resolved = await resolveTargetCoords(bridge, {
+    mode: 'node',
+    nodeId: node.nodeId,
   })
-  if (!isTapTargetInfo(tap)) return { matched: 0, total }
-  return payloadFromResolved(
-    {
-      x: tap.cx,
-      y: tap.cy,
-      nodeId: tap.target.nodeId,
-      testID: tap.target.testID,
-      text: tap.target.text ?? tap.target.accessibilityLabel,
-      type: tap.target.type,
-    },
-    node,
-    { total, idx },
-  )
+  if (!resolved) return { matched: 0, total }
+  return payloadFromResolved(resolved, node, { total, idx })
 }
 
 export type TapQuery =
@@ -567,6 +523,7 @@ export async function tapByQuery(
           testID: tap.target.testID,
           text: tap.target.text ?? tap.target.accessibilityLabel,
           type: tap.target.type,
+          viewport: tap.viewport,
         },
         {
           nodeId: node.nodeId,