peachsim 0.1.627 → 0.1.629

package/LICENSE

@@ -3,7 +3,7 @@ Proprietary Software License
 Copyright (c) Tamagui LLC. All rights reserved.
 
 This package (peachsim) is proprietary software of Tamagui LLC, licensed under
-the rnx Software License Agreement: https://peachsim.com/legal/license
+the Peach Software License Agreement: https://peachsim.com/legal/license
 
 In summary (the agreement governs): personal, non-commercial use is free;
 commercial use requires an active Pro subscription after a single 30-day

package/cli/bin.ts

@@ -10,7 +10,7 @@
 // whole process, so the CLI itself lives in `./main` and is imported only once
 // none of them has claimed the run.
 
-import { RNX_INTERNAL_COMMAND } from './internal-child'
+import { RNX_FORKED_SCRIPT_ENV, RNX_INTERNAL_COMMAND } from './internal-child'
 
 if (process.argv[2] === '__shell-init') {
   const { renderRnxShellInit } = await import('./shell-init')
@@ -51,7 +51,11 @@ if (process.argv[2] === '__cloud-confirm') {
 // are still working when their handler returns, and the process ends when that
 // work does. so this is the branch that must skip the CLI rather than the CLI
 // that must skip it.
-if (process.argv[2] === RNX_INTERNAL_COMMAND) {
+const forkedScript = process.argv[2]
+if (process.env[RNX_FORKED_SCRIPT_ENV] === '1' && forkedScript?.endsWith('.js')) {
+  const { runScript } = await import('./internal-child')
+  runScript(forkedScript, process.argv.slice(3))
+} else if (process.argv[2] === RNX_INTERNAL_COMMAND) {
   const { runInternalChild } = await import('./internal-child')
   await runInternalChild(process.argv.slice(3))
 } else {

package/cli/bridge-flow-runner.ts

@@ -30,8 +30,6 @@ const DEFAULT_TIMEOUT = 10000
 const ASSERTION_LOOKUP_MS = 17_000
 const FLOW_TIMEOUT_SCALE = flowTimeoutScale()
 const scaledTimeout = (ms: number) => Math.round(ms * FLOW_TIMEOUT_SCALE)
-const SCREEN_W = 393
-const SCREEN_H = 852
 type FlowScreenshotPathMode = 'dir' | 'flow'
 type ReplayTapTarget = SootSimReplayTarget
 
@@ -472,18 +470,16 @@ export function normalizeFlowScreenshotSpec(
 
 function parsePoint(
   value: string,
-  bounds?: { x: number; y: number; width: number; height: number },
+  bounds: { x: number; y: number; width: number; height: number },
 ) {
   const [rawX, rawY] = value.split(',').map((part) => part.trim())
   const parseCoord = (coord: string, max: number) =>
     coord.endsWith('%')
       ? (Number.parseFloat(coord) / 100) * max
       : Number.parseFloat(coord)
-  const originX = bounds?.x ?? 0
-  const originY = bounds?.y ?? 0
   return {
-    x: originX + parseCoord(rawX, bounds?.width ?? SCREEN_W),
-    y: originY + parseCoord(rawY, bounds?.height ?? SCREEN_H),
+    x: bounds.x + parseCoord(rawX, bounds.width),
+    y: bounds.y + parseCoord(rawY, bounds.height),
   }
 }
 
@@ -624,6 +620,28 @@ export class SootSimBridgeFlowRunner {
     }) as Promise<T>
   }
 
+  private async screenBounds() {
+    const snapshot = await this.callTest<Record<string, unknown> | null>(
+      'getSurfaceMetricsSnapshot',
+    )
+    const window = snapshot?.window
+    if (
+      !window ||
+      typeof window !== 'object' ||
+      !('width' in window) ||
+      !('height' in window) ||
+      typeof window.width !== 'number' ||
+      typeof window.height !== 'number' ||
+      !Number.isFinite(window.width) ||
+      !Number.isFinite(window.height) ||
+      window.width <= 0 ||
+      window.height <= 0
+    ) {
+      throw new Error('live screen dimensions are unavailable')
+    }
+    return { x: 0, y: 0, width: window.width, height: window.height }
+  }
+
   // ordered input batch executed inside the page in one round-trip; the
   // engine emits agent-cursor actions for every step natively.
   private async perform(steps: PerformStep[]): Promise<PerformResult> {
@@ -939,6 +957,7 @@ export class SootSimBridgeFlowRunner {
   // (match scoped to a container). a nested selector resolves the same way,
   // and a relative filter holds when ANY match of its anchor satisfies it.
   private async findElementScoped(opts: FlowTargetSelector) {
+    const screen = await this.screenBounds()
     const needsEveryNode =
       !opts.id ||
       opts.childOf != null ||
@@ -1045,7 +1064,7 @@ export class SootSimBridgeFlowRunner {
         // paints nothing, and maestro's hierarchy never holds it.
         const onScreen = candidates.filter((n) => {
           const cy = n.absolutePosition.y + n.layout.height / 2
-          return cy > 0 && cy < ${SCREEN_H}
+          return cy > 0 && cy < ${screen.height}
         })
         if (candidates.some(painted)) candidates = candidates.filter(painted)
         else if (onScreen.length > 0) candidates = onScreen
@@ -1263,7 +1282,7 @@ export class SootSimBridgeFlowRunner {
       !opts.childOf
     ) {
       return {
-        ...parsePoint(opts.point),
+        ...parsePoint(opts.point, await this.screenBounds()),
         element: null,
         target: undefined,
       }
@@ -1903,34 +1922,21 @@ export class SootSimBridgeFlowRunner {
     return outputDir
   }
 
-  async swipe(direction: string = 'UP', duration: number = 300) {
-    const centerX = SCREEN_W / 2
-    const centerY = SCREEN_H / 2
-    const distance = 200
-    let fromX = centerX
-    let fromY = centerY
-    let toX = centerX
-    let toY = centerY
-
-    switch (direction.toUpperCase()) {
-      case 'UP':
-        fromY += distance
-        toY -= distance
-        break
-      case 'DOWN':
-        fromY -= distance
-        toY += distance
-        break
-      case 'LEFT':
-        fromX += distance
-        toX -= distance
-        break
-      case 'RIGHT':
-        fromX -= distance
-        toX += distance
-        break
-    }
-
+  // maestro's ios driver: a directional swipe spans the screen, from 90% to
+  // 10% for UP, 20% to 90% for DOWN, and 10% to 90% across for LEFT/RIGHT,
+  // over the command's 400ms default.
+  async swipe(direction: string = 'UP', duration: number = 400) {
+    const screen = await this.screenBounds()
+    const midX = screen.width / 2
+    const midY = screen.height / 2
+    const [fromX, fromY, toX, toY] =
+      direction.toUpperCase() === 'DOWN'
+        ? [midX, screen.height * 0.2, midX, screen.height * 0.9]
+        : direction.toUpperCase() === 'LEFT'
+          ? [screen.width * 0.9, midY, screen.width * 0.1, midY]
+          : direction.toUpperCase() === 'RIGHT'
+            ? [screen.width * 0.1, midY, screen.width * 0.9, midY]
+            : [midX, screen.height * 0.9, midX, screen.height * 0.1]
     const steps = Math.max(10, Math.round(duration / 16))
     await this.drag(fromX, fromY, toX, toY, steps, 16)
   }
@@ -1960,39 +1966,34 @@ export class SootSimBridgeFlowRunner {
     await this.settleAfterInput()
   }
 
-  async swipeCoords(start: string, end: string, duration = 300) {
-    const from = parsePoint(start)
-    const to = parsePoint(end)
+  async swipeCoords(start: string, end: string, duration = 400) {
+    const screen = await this.screenBounds()
+    const from = parsePoint(start, screen)
+    const to = parsePoint(end, screen)
     const steps = Math.max(10, Math.round(duration / 16))
     await this.drag(from.x, from.y, to.x, to.y, steps, 16)
   }
 
+  // maestro's ios driver swipes from the element's center to the 10% or 90%
+  // edge in the swipe's direction.
   async swipeFrom(
     from: { id?: string; text?: string },
     direction: string = 'UP',
-    duration = 300,
+    duration = 400,
   ) {
     const element = await this.findElement(from)
     if (!element) throw new Error(`swipeFrom: element not found: ${JSON.stringify(from)}`)
     const startX = element.absolutePosition.x + element.layout.width / 2
     const startY = element.absolutePosition.y + element.layout.height / 2
-    const distance = 180
-    let endX = startX
-    let endY = startY
-    switch (direction.toUpperCase()) {
-      case 'UP':
-        endY -= distance
-        break
-      case 'DOWN':
-        endY += distance
-        break
-      case 'LEFT':
-        endX -= distance
-        break
-      case 'RIGHT':
-        endX += distance
-        break
-    }
+    const screen = await this.screenBounds()
+    const [endX, endY] =
+      direction.toUpperCase() === 'DOWN'
+        ? [startX, screen.height * 0.9]
+        : direction.toUpperCase() === 'LEFT'
+          ? [screen.width * 0.1, startY]
+          : direction.toUpperCase() === 'RIGHT'
+            ? [screen.width * 0.9, startY]
+            : [startX, screen.height * 0.1]
     const steps = Math.max(10, Math.round(duration / 16))
     await this.drag(startX, startY, endX, endY, steps, 16)
   }
@@ -2103,24 +2104,24 @@ export class SootSimBridgeFlowRunner {
     )
     const deadline = Date.now() + (opts.timeout || 20000)
     const direction = opts.direction?.toUpperCase() || 'DOWN'
-    const centerX = SCREEN_W / 2
-    const centerY = SCREEN_H / 2
-    const swipeEnd =
-      direction === 'UP'
-        ? { x: centerX, y: SCREEN_H * 0.9 }
-        : direction === 'LEFT'
-          ? { x: SCREEN_W * 0.9, y: centerY }
-          : direction === 'RIGHT'
-            ? { x: SCREEN_W * 0.1, y: centerY }
-            : { x: centerX, y: SCREEN_H * 0.1 }
-
     while (Date.now() < deadline) {
+      const screen = await this.screenBounds()
+      const centerX = screen.width / 2
+      const centerY = screen.height / 2
+      const swipeEnd =
+        direction === 'UP'
+          ? { x: centerX, y: screen.height * 0.9 }
+          : direction === 'LEFT'
+            ? { x: screen.width * 0.9, y: centerY }
+            : direction === 'RIGHT'
+              ? { x: screen.width * 0.1, y: centerY }
+              : { x: centerX, y: screen.height * 0.1 }
       const element = await this.findElement(target)
       if (element) {
         const { x, y } = element.absolutePosition
         const { width, height } = element.layout
-        const shownX = Math.max(0, Math.min(x + width, SCREEN_W) - Math.max(x, 0))
-        const shownY = Math.max(0, Math.min(y + height, SCREEN_H) - Math.max(y, 0))
+        const shownX = Math.max(0, Math.min(x + width, screen.width) - Math.max(x, 0))
+        const shownY = Math.max(0, Math.min(y + height, screen.height) - Math.max(y, 0))
         const share = width * height > 0 ? (shownX * shownY) / (width * height) : 0
         if (share >= required) {
           if (opts.centerElement) {
@@ -2839,7 +2840,13 @@ export class SootSimBridgeFlowRunner {
         await this.swipe(step.swipe.direction, step.swipe.duration)
       }
     } else if (step.scroll) {
-      await this.swipe(step.scroll.direction === 'DOWN' ? 'UP' : 'DOWN')
+      // maestro's scrollVertical drags 50% to 10% of the screen over 333ms;
+      // scrollUp mirrors it
+      const screen = await this.screenBounds()
+      const midX = screen.width / 2
+      const toY =
+        step.scroll.direction === 'UP' ? screen.height * 0.9 : screen.height * 0.1
+      await this.drag(midX, screen.height / 2, midX, toY, Math.round(333 / 16), 16)
     } else if (step.scrollTo) {
       const target =
         typeof step.scrollTo.nodeId === 'number'

package/cli/commands/cleanup.ts

@@ -58,13 +58,13 @@ export async function runCleanup(args: string[]): Promise<number> {
   if (args.length === 1 && args[0] === '--automatic-worker') {
     try {
       const result = applyAutomaticSootsimCleanup()
-      if (result.status === 'complete') {
+      // a run that found nothing stays silent: this worker writes to the
+      // user's terminal after the command that spawned it has returned.
+      if (result.status === 'complete' && result.reclaimedBytes > 0) {
         process.stderr.write(
-          result.reclaimedBytes > 0
-            ? `  peach automatic cleanup reclaimed ${formatSootsimBytes(
-                result.reclaimedBytes,
-              )}; active runtimes and app data were kept.\n`
-            : '  peach automatic cleanup found no obsolete local data.\n',
+          `  peach automatic cleanup reclaimed ${formatSootsimBytes(
+            result.reclaimedBytes,
+          )}; active runtimes and app data were kept.\n`,
         )
       } else if (result.status === 'deferred') {
         process.stderr.write(

package/cli/commands/control.ts

@@ -835,7 +835,8 @@ export interface BuildShellUrlOptions {
   // host page URL at boot (syncProofModeFromInitUrl) and pin everything that
   // would otherwise differ frame to frame: the TextInput caret stops blinking
   // and stays visible, and notifications stop auto-dismissing. capture-frame
-  // also reads the raw param and stops clipping the device corners, so a
+  // also reads the raw param and stops clipping the device corners, and the
+  // shell leaves out the Dynamic Island, which is hardware, so a
   // capture matches simctl's rectangular framebuffer. without it a
   // screen holding a focused text field never reaches three identical idle
   // frames, so the screenshot guard burns all 12 attempts and then fails.
@@ -1611,16 +1612,14 @@ export async function runOpenCommand(
     rnxExit(1)
   }
   // the window fits the box the browser stage fits the device into, which for
-  // a foldable spans every posture and orientation, so the device draws at its
-  // natural size in the pose it opens in instead of shrinking into a window
-  // sized for one pose.
+  // a foldable spans both postures, so the device draws at its natural size in
+  // the posture it opens in instead of shrinking into a window sized for one.
   const deviceFitBox = deviceArg
     ? resolveDeviceFitBox(
         deviceArg as DeviceModel,
         false,
         undefined,
         postureArg === 'open' ? 'open' : 'closed',
-        true,
       )
     : undefined
 

package/cli/commands/detox.ts

@@ -13,7 +13,6 @@ import {
   unlinkSync,
 } from 'fs'
 import { createRequire } from 'module'
-import { fileURLToPath } from 'node:url'
 import { tmpdir } from 'os'
 import { dirname, resolve, join, relative } from 'path'
 import { rnxPublicBrand } from '../../src/public-brand'
@@ -34,15 +33,17 @@ peach detox — run detox-style tests against a peach shell
 
 usage:
   peach detox [testFiles...]        run all tests under e2e/, test/e2e/, or detox/
+  peach detox --app <port|url>      the app each device.launchApp() opens
   peach detox --config <path>       use a specific jest config
   peach detox init                  scaffold rnx-detox.config.cjs + sample test
   peach detox --watch               jest watch mode
   peach detox --headed              keep the peach shell window visible
   peach detox -t <pattern>          pass a jest --testNamePattern
-  peach detox --no-launch           skip auto-launching a peach shell
+  peach detox --no-launch           skip the running-shell check
 
-peach detox auto-launches a peach shell if none is running on the
-expected port. disable with --no-launch if you're managing the shell yourself.
+peach detox needs a running peach shell: start your app and run
+\`peach open <app-port>\` first (the background service keeps one ready).
+it warns when none is reachable; --no-launch skips that check.
 `
 
 export async function runDetox(args: string[], opts: RunDetoxOpts = {}): Promise<void> {
@@ -140,9 +141,25 @@ export async function runDetox(args: string[], opts: RunDetoxOpts = {}): Promise
   }
   testDir ??= process.cwd()
 
-  // auto-launch: make sure a peach shell is reachable before running jest.
-  // Reuse the Maestro discovery path: scan local dev servers.
-  // and `peach open` the first match.
+  // jest runs from the project, so the preset must resolve from it too; the
+  // standalone binary has no package directory of its own to point at.
+  let presetPath = ''
+  if (!localConfig) {
+    try {
+      presetPath = createRequire(join(process.cwd(), 'package.json')).resolve(
+        `${rnxPublicBrand.packageName}/detox/jest-preset`,
+      )
+    } catch {
+      console.error(
+        `  error: ${rnxPublicBrand.commandName} detox runs Jest from this project, which needs its dev dependencies:\n` +
+          `    npm i -D ${rnxPublicBrand.packageName} jest`,
+      )
+      rnxExit(1)
+    }
+  }
+
+  // the driver navigates to a running peach shell; warn before jest starts
+  // when none is reachable.
   if (!noLaunch) {
     await ensureShellRunning(port)
   }
@@ -162,9 +179,6 @@ export async function runDetox(args: string[], opts: RunDetoxOpts = {}): Promise
     // subpath exports, so we generate a real config file instead.
     // scope roots + testMatch to the discovered test dir so jest doesn't
     // scan the entire repo (which causes haste collisions in monorepos).
-    const presetPath = fileURLToPath(
-      import.meta.resolve(`${rnxPublicBrand.packageName}/detox/jest-preset`),
-    )
     // an external suite may optionally declare its own ignore patterns via e2e/jest-ignore.cjs
     const suiteIgnoreFile = testDir ? join(testDir, 'e2e', 'jest-ignore.cjs') : null
     let suiteIgnorePatterns: string[] = []
@@ -483,7 +497,7 @@ describe('example', () => {
   }
 
   console.log(`\n  next:`)
-  console.log(`    peach detox        # run the sample`)
+  console.log(`    peach detox --app <dev-server-port>   # run the sample`)
   console.log(`    peach detox --watch`)
   rnxExit(0)
 }

package/cli/commands/flow.ts

@@ -268,8 +268,9 @@ options:
                        headless or stale
   --proof              deterministic-capture mode: pin the TextInput caret
                        visible instead of blinking, stop notifications
-                       auto-dismissing, and leave the device corners unclipped
-                       to match a native simctl framebuffer. a screen holding a
+                       auto-dismissing, leave the device corners unclipped and
+                       leave out the Dynamic Island, to match a
+                       native simctl framebuffer. a screen holding a
                        focused text field cannot reach three identical idle
                        frames without this, so its screenshot fails after 12
                        tries. use it for any run whose screenshots get

package/cli/commands/inspect/core.ts

@@ -544,6 +544,11 @@ export interface LayoutElement {
   lastLineWords?: number
   // last line width relative to the widest line (0-1).
   lastLineWidthRatio?: number
+  // first display-size word (24px and up, space-delimited scripts) the browser
+  // split across two lines mid-letter. words with a legal break point
+  // (hyphen, dash, slash, soft hyphen, zero-width space) and domains or emails
+  // are never reported.
+  brokenWord?: string
   ellipsisActive?: boolean
 }
 

package/cli/commands/inspect.ts

@@ -17,6 +17,7 @@ import { getCliIdentityKey } from '../current-sim'
 import { rememberFlowCandidate } from '../flow-session'
 import { maybeHint } from '../hints'
 import { shouldPrintInspectNotice } from '../inspect-notice-state'
+import { levenshtein } from '../levenshtein'
 import { TOP_LEVEL_RUNTIME_COMMANDS } from '../parse-args'
 import { rethrowIfExit, rnxExit } from '../run-rnx'
 import {
@@ -191,6 +192,24 @@ async function probeSimResponsive(bridge: WsBridge): Promise<boolean> {
   }
 }
 
+// a bare `do tap <x>` resolves a testID; users coming from maestro's
+// `tapOn: <text>` pass visible text there, so point them at `--text`.
+async function reportMissingTarget(
+  bridge: WsBridge,
+  verb: 'tap' | 'double-tap' | 'long-press',
+  target: { mode: 'testid' | 'text'; value: string },
+): Promise<void> {
+  console.error(`  not found: ${target.value}`)
+  if (target.mode !== 'testid') return
+  const byText = await inspectFind(bridge, { text: target.value }).catch(() => null)
+  if (byText?.result) {
+    console.error(`  that is visible text: peach do ${verb} --text "${target.value}"`)
+    return
+  }
+  await printSimilarTestIds(bridge, target.value)
+  maybeHint('wait-selector-for-missing-testid', target.value)
+}
+
 // surface the 5 closest candidates so callers can fix the typo without
 // dumping the full tree. uses a cheap prefix + Levenshtein score so a
 // trailing digit or near-miss casing still bubbles to the top.
@@ -243,34 +262,6 @@ function scoreIdSimilarity(needle: string, candidate: string): number {
   return levenshtein(needle, candidate) - prefix
 }
 
-function levenshtein(a: string, b: string): number {
-  if (a === b) return 0
-  if (!a.length) return b.length
-  if (!b.length) return a.length
-  // standard two-row dp: prev[] is the previous row, cur[] is the row being
-  // computed; swap pointers per outer iteration. the earlier in-place rolling
-  // version overwrote prev[j-1] twice per cell and never set prev[0]=i, so
-  // distance(`kitten`,`sitting`) returned 8 instead of 3 and the fuzzy-suggest
-  // ranking was effectively random.
-  let prev = new Array<number>(b.length + 1)
-  let cur = new Array<number>(b.length + 1)
-  for (let j = 0; j <= b.length; j++) prev[j] = j
-  for (let i = 1; i <= a.length; i++) {
-    cur[0] = i
-    for (let j = 1; j <= b.length; j++) {
-      cur[j] = Math.min(
-        prev[j] + 1,
-        cur[j - 1] + 1,
-        prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),
-      )
-    }
-    const tmp = prev
-    prev = cur
-    cur = tmp
-  }
-  return prev[b.length]
-}
-
 function formatNetworkStatus(e: NetworkEntryPayload): string {
   if (e.error) return 'err'
   if (e.status == null) return ' … '
@@ -2026,10 +2017,7 @@ export async function runInspect(args: string[], opts: InspectOptions) {
           })
           const payload = outcome.payload
           if (!payload || typeof payload.cx !== 'number') {
-            console.error(`  not found: ${target.value}`)
-            if (target.mode === 'testid') {
-              maybeHint('wait-selector-for-missing-testid', target.value)
-            }
+            await reportMissingTarget(bridge, 'tap', target)
             rnxExit(1)
           }
           if (!isTapSuccess(outcome.result)) {
@@ -2800,10 +2788,7 @@ export async function runInspect(args: string[], opts: InspectOptions) {
         if (target) {
           const resolved = await resolveTargetCoords(bridge, target)
           if (!resolved) {
-            console.error(`  not found: ${target.value}`)
-            if (target.mode === 'testid') {
-              maybeHint('wait-selector-for-missing-testid', target.value)
-            }
+            await reportMissingTarget(bridge, 'double-tap', target)
             rnxExit(1)
           }
           x = resolved.x
@@ -2843,10 +2828,7 @@ export async function runInspect(args: string[], opts: InspectOptions) {
         if (target) {
           const resolved = await resolveTargetCoords(bridge, target)
           if (!resolved) {
-            console.error(`  not found: ${target.value}`)
-            if (target.mode === 'testid') {
-              maybeHint('wait-selector-for-missing-testid', target.value)
-            }
+            await reportMissingTarget(bridge, 'long-press', target)
             rnxExit(1)
           }
           x = resolved.x
@@ -3539,7 +3521,16 @@ export async function runInspect(args: string[], opts: InspectOptions) {
           if (reloadResult && reloadResult.engineStale) {
             console.log('  engine build changed since page load — full page reload')
           }
-        } catch {
+        } catch (error) {
+          // no sim at all is not a reload in flight: report it rather than
+          // waiting out the reconnect budget.
+          const message = error instanceof Error ? error.message : String(error)
+          if (
+            message === 'no sim connected' ||
+            message.startsWith('could not connect to ws://')
+          ) {
+            throw error
+          }
           // the sim may already be in the middle of reloading; fall through to reconnect wait
         }
         console.log('  reloading...')
@@ -3623,7 +3614,7 @@ export async function runInspect(args: string[], opts: InspectOptions) {
             // ignore errors checking for errors
           }
         }
-        if (readyResult && !readyResult.ready) {
+        if (!readyResult?.ready) {
           rnxExit(1)
         }
         break
@@ -4655,15 +4646,18 @@ export async function runInspect(args: string[], opts: InspectOptions) {
     // single 15s timeout into ~60s of apparent hang (QA F19-1). there is
     // nothing useful to fetch from a sim that just timed out, so skip them.
     const timedOut = /^command timed out after (\d+)s$/.exec(message)
-    // a disconnected / never-connected bridge is genuinely gone; recover is
-    // right and probing it would just re-incur a full timeout.
+    // a disconnected bridge is genuinely gone; recover is right and probing
+    // it would just re-incur a full timeout. no bridge at all means there is
+    // no sim to recover, only one to open.
     const disconnected =
       message.startsWith('sim disconnected:') ||
-      message.startsWith('bridge never reconnected') ||
-      message.startsWith('could not connect to ws://')
+      message.startsWith('bridge never reconnected')
     if (unknownSim) {
       await printUnknownSimHint(bridge, wsPort, unknownSim[1])
-    } else if (/^no sim connected$/.test(message)) {
+    } else if (
+      /^no sim connected$/.test(message) ||
+      message.startsWith('could not connect to ws://')
+    ) {
       printMissingSimHint(wsPort)
     } else if (timedOut) {
       // a command timeout alone does not mean a wedged sim — a large screen
@@ -4677,9 +4671,9 @@ export async function runInspect(args: string[], opts: InspectOptions) {
         process.stderr.write(
           `  the sim is still responsive — '${cmd}' just exceeded the ${timedOut[1]}s command budget.\n` +
             `  the screen's node tree is large; narrow the query or raise the budget:\n` +
-            `    peach  --testid <id>     # scope to one subtree\n` +
+            `    peach ${cmd} --subtree <id>   # scope to one subtree\n` +
             `    peach find --testid <id>       # targeted single-node lookup\n` +
-            `    peach  --timeout 60000   # raise per-command budget (ms)\n`,
+            `    peach ${cmd} --timeout 60000  # raise per-command budget (ms)\n`,
         )
       } else {
         printRecoverHint()

package/cli/commands/mode.ts

@@ -1,5 +1,6 @@
 import { rnxExit } from '../run-rnx'
 import { runScreenshotMode } from './screenshot-mode'
+import { runShowTouchesMode } from './show-touches-mode'
 import { runThreeMode } from './three-mode'
 
 interface ModeOptions {
@@ -8,7 +9,7 @@ interface ModeOptions {
 }
 
 const VALUE_FLAGS = new Set(['--sim', '--port', '-p'])
-const SUBCOMMANDS = new Set(['screenshot', 'three'])
+const SUBCOMMANDS = new Set(['screenshot', 'three', 'show-touches', 'touches'])
 
 function findSubcommand(args: string[]): { name: string; index: number } | null {
   for (let i = 0; i < args.length; i++) {
@@ -32,21 +33,20 @@ peach mode — toggle live display modes
 
 usage:
   peach mode screenshot [on|off|toggle]
+  peach mode show-touches [on|off|toggle]
   peach mode three [on|off|toggle]
   peach mode three configure [options]
 `)
 }
 
 export async function runMode(args: string[], opts: ModeOptions): Promise<void> {
-  if (args.includes('--help') || args.includes('-h')) {
-    printHelp()
-    return
-  }
-
   const sub = findSubcommand(args)
   if (!sub) {
     printHelp()
-    rnxExit(1)
+    if (!args.includes('--help') && !args.includes('-h')) {
+      rnxExit(1)
+    }
+    return
   }
 
   const rest = withoutSubcommand(args, sub.index)
@@ -54,5 +54,9 @@ export async function runMode(args: string[], opts: ModeOptions): Promise<void>
     await runScreenshotMode(rest, opts)
     return
   }
+  if (sub.name === 'show-touches' || sub.name === 'touches') {
+    await runShowTouchesMode(rest, opts)
+    return
+  }
   await runThreeMode(rest, opts)
 }

package/cli/commands/report-issue.ts

@@ -260,7 +260,7 @@ export async function runReportIssue(
       return 2
     }
     const approved = await dependencies.confirmSubmission(
-      'send this compatibility report to the peach team??',
+      'send this compatibility report to the peach team?',
       false,
     )
     if (!approved) {