peachsim 0.1.578 → 0.1.580

package/cli/commands/film.ts

@@ -14,6 +14,7 @@ import { spawnSync } from 'node:child_process'
 import { existsSync, mkdirSync, unlinkSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, extname, join, resolve } from 'node:path'
+import { sleep } from '../../src/sleep'
 import {
   callInBridgeWrite,
   createBridgeFromParsed,
@@ -27,8 +28,6 @@ interface FilmOptions {
   verbose?: boolean
 }
 
-const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))
-
 // flags consumed by film itself; everything else that buildConfigureOptions
 // understands (--background, --colorway, --env-*, --room, --focus*, ...)
 // passes through to the stage configure call.
@@ -142,26 +141,36 @@ examples:
 
     // -- phase 1: record the flow on the flat canvas ----------------------
     console.log(`  film: recording flow ${flowName} on the flat canvas`)
-    const started = await evalInPage<boolean>(
-      bridge,
-      `(async () => !!(await window.SootSim?.bridges?.startRecording?.('video', undefined, { skipEntitlement: true })))()`,
-    )
-    if (!started) {
-      console.error(
-        '  film: engine recording store did not start (is @peach/plugin-recording installed?)',
-      )
-      return 1
-    }
-    const t0 = Date.now()
-    await sleep(500)
-
     const { runFlowPlayback } = await import('./flow')
     const playbackArgs = [flowPath]
     const simFlag = flagValue(args, '--sim')
     if (simFlag) playbackArgs.push('--sim', simFlag)
     const slowFlag = flagValue(args, '--slow')
     if (slowFlag) playbackArgs.push('--slow', slowFlag)
-    const flowCode = await runFlowPlayback(playbackArgs)
+    let t0 = 0
+    const flowCode = await runFlowPlayback(playbackArgs, {
+      beforeSteps: async () => {
+        // the sim can arrive in 3d (left there by --keep-three, or brought back
+        // by the flow's open), and this phase records the flat canvas
+        await evalInPage(
+          bridge,
+          `(() => { const s = window.SootSim?.bridges?.settings
+             s?.set?.('threeRecordingEditor', false)
+             s?.set?.('threeMode', false) })()`,
+        )
+        const started = await evalInPage<boolean>(
+          bridge,
+          `(async () => !!(await window.SootSim?.bridges?.startRecording?.('video', undefined, { skipEntitlement: true })))()`,
+        )
+        if (!started) {
+          throw new Error(
+            'film: engine recording store did not start (is @peach/plugin-recording installed?)',
+          )
+        }
+        t0 = Date.now()
+        await sleep(500)
+      },
+    })
     await sleep(400)
     const durationMs = Math.min(Date.now() - t0, MAX_FILM_MS)
     await evalInPage(bridge, `window.SootSim?.bridges?.stopRecording?.()`)

package/cli/commands/flow.ts

@@ -203,7 +203,13 @@ export async function discoverSootsimUrl(): Promise<string | null> {
   return null
 }
 
-export async function runFlowPlayback(args: string[]): Promise<number> {
+export async function runFlowPlayback(
+  args: string[],
+  // beforeSteps runs once the flow is on its target and about to run its first
+  // step. opening a frontmatter `app:` navigates the sim, which wipes in-page
+  // state, so a caller capturing the run itself (film) starts here.
+  hooks: { beforeSteps?: () => Promise<void> } = {},
+): Promise<number> {
   lastPreviewUploadResult = null
   lastFlowTraceSteps = []
   if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
@@ -269,7 +275,7 @@ options:
   --preview-origin <url>
                        upload target for --preview (default: auto)
   --preview-public-origin <url>
-                       public link origin for --preview (default: rnxsim.com
+                       public link origin for --preview (default: peachsim.com
                        for prod uploads)
   --billing-kind test_run
                        meter the chained preview upload as a test run
@@ -745,6 +751,7 @@ flow extension:
         )
       }
     }
+    await hooks.beforeSteps?.()
     await driver.runFlow(steps, { skipPlan: dryRun })
     if (profile) {
       profileResult = await driver.stopProfile()

package/cli/commands/inspect/actions.ts

@@ -2,7 +2,12 @@ import { inspectTree, type InspectBridge } from './core'
 import { resolveTargetCoords, type ResolvedTargetCoords } from './resolve-target'
 import { waitForSootsimIdle } from './settling'
 import type { SimSemanticNode } from '../../../src/bridge-contract'
-import type { SootSimReplayTarget } from '@peach/globals'
+import type {
+  SootSimAccessibilityState,
+  SootSimNodeInfo,
+  SootSimReplayTarget,
+  SootSimTapTargetInfo,
+} from '@peach/globals'
 
 export type TapFailure = 'not-found' | 'missed' | 'special'
 
@@ -472,6 +477,75 @@ export async function tapByText(
   })
 }
 
+export type TapQuery =
+  | { by: 'label' | 'role' | 'hint'; value: string }
+  | { by: 'state'; value: Partial<SootSimAccessibilityState> }
+
+const TAP_QUERY_FINDERS = {
+  label: 'findByLabel',
+  role: 'findByRole',
+  hint: 'findByHint',
+  state: 'findByA11yState',
+} as const
+
+function isTapNode(value: unknown): value is SootSimNodeInfo {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    typeof Reflect.get(value, 'nodeId') === 'number'
+  )
+}
+
+function isTapTargetInfo(value: unknown): value is SootSimTapTargetInfo {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    typeof Reflect.get(value, 'cx') === 'number' &&
+    typeof Reflect.get(value, 'cy') === 'number' &&
+    isTapNode(Reflect.get(value, 'target'))
+  )
+}
+
+// accessibility-query taps. the test bridge finds the node and names the node
+// a finger activates, then the tap runs exactly as tapById's does: settled
+// first and verified at the point, so a covered target reports target-covered
+// instead of pressing whatever covers it.
+export async function tapByQuery(
+  bridge: InspectBridge,
+  query: TapQuery,
+  opts: { agent?: boolean; timing?: TapTimingOptions } = {},
+): Promise<TapOutcome> {
+  const call = (method: string, arg: unknown): Promise<unknown> =>
+    bridge.send({ type: 'call', path: `SootSim.bridges.test.${method}`, args: [arg] })
+  return tapResolvedTarget(bridge, {
+    agent: opts.agent,
+    timing: opts.timing,
+    textFallback: typeof query.value === 'string' ? query.value : undefined,
+    resolve: async () => {
+      const node = await call(TAP_QUERY_FINDERS[query.by], query.value)
+      if (!isTapNode(node)) return { cx: null }
+      const tap = await call('resolveTapTarget', node.nodeId)
+      if (!isTapTargetInfo(tap)) return { cx: null }
+      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,
+        },
+        {
+          nodeId: node.nodeId,
+          testID: node.testID,
+          text: node.text ?? node.accessibilityLabel,
+          type: node.type,
+        },
+      )
+    },
+  })
+}
+
 export async function tapBest(
   bridge: InspectBridge,
   query: string,

package/cli/commands/inspect/core.ts

@@ -328,6 +328,35 @@ export interface LayoutTextContrast {
   reason?: string
 }
 
+// first family of a bound font stack, so a no-vision agent can verify a
+// custom display family landed on the right nodes. system stacks stay omitted
+// as a boring default. self-contained: the native eval below interpolates
+// this source (mirrored by the web extractor's set in app-bridge webLayout).
+export function layoutBoundFontFamily(style: unknown): string | undefined {
+  const raw =
+    typeof style === 'object' && style !== null
+      ? (style as { fontFamily?: unknown }).fontFamily
+      : undefined
+  if (typeof raw !== 'string') return undefined
+  const first = raw
+    .split(',')[0]
+    .trim()
+    .replace(/^['"]|['"]$/g, '')
+  if (!first) return undefined
+  const systemFamilies = new Set([
+    'system',
+    '-apple-system',
+    'system-ui',
+    'blinkmacsystemfont',
+    'segoe ui',
+    'roboto',
+    'sans-serif',
+    'serif',
+    'monospace',
+  ])
+  return systemFamilies.has(first.toLowerCase()) ? undefined : first
+}
+
 export function scoreLayoutTextContrast(input: {
   normal: { width: number; height: number; data: ArrayLike<number> }
   background: { width: number; height: number; data: ArrayLike<number> }
@@ -476,6 +505,7 @@ export interface LayoutElement {
   text?: string
   // on-screen bounding box in device/viewport px (x/y are absolute).
   box: LayoutBox
+  hitSlop?: number | LayoutPadding
   // box-model fields are available only when the caller opts into styling.
   // measured zero remains distinct from an unavailable field.
   borderRadius?: number
@@ -491,6 +521,15 @@ export interface LayoutElement {
   bg?: string
   opacity?: number
   fontWeight?: number
+  // first family of the bound font stack (web: computed; native: authored
+  // style), so a no-vision agent can verify a custom display family landed on
+  // the right nodes. system stacks stay omitted as a boring default.
+  fontFamily?: string
+  // web extractor only: false when document.fonts reports the bound family
+  // unavailable for this element's own style and weight — the face failed to
+  // load and the browser fell back. omitted otherwise, including all native
+  // rows.
+  fontLoaded?: boolean
   textDecoration?: string
   overflow?: string
   borderWidth?: number
@@ -574,6 +613,7 @@ export function layoutGetNativeEval(opts: LayoutExtractionOptions = {}): string
         const n = w === 'bold' ? 700 : (typeof w === 'number' ? w : (typeof w === 'string' ? parseInt(w, 10) : NaN))
         return Number.isFinite(n) && n >= 600 ? n : undefined
       }
+      const familyOf = ${layoutBoundFontFamily.toString()}
       const decoOf = (style) => {
         const d = style && (style.textDecorationLine || style.textDecoration)
         return d && d !== 'none' && d !== 'normal' ? String(d).split(' ')[0] : undefined
@@ -621,6 +661,27 @@ export function layoutGetNativeEval(opts: LayoutExtractionOptions = {}): string
         const layout = n.layout || { x: 0, y: 0, width: 0, height: 0 }
         const abs = n.absolute || n.absolutePosition || { x: layout.x, y: layout.y }
         const text = typeof n.text === 'string' && n.text.trim() ? n.text.trim() : undefined
+        const rawHitSlop =
+          n.hitSlop != null
+            ? n.hitSlop
+            : (n.props && n.props.hitSlop != null)
+              ? n.props.hitSlop
+              : (n.style && n.style.hitSlop != null)
+                ? n.style.hitSlop
+                : (n.authoredStyle && n.authoredStyle.hitSlop != null)
+                  ? n.authoredStyle.hitSlop
+                  : undefined
+        const hitSlop =
+          typeof rawHitSlop === 'number'
+            ? (rawHitSlop !== 0 ? rawHitSlop : undefined)
+            : rawHitSlop && typeof rawHitSlop === 'object'
+              ? {
+                  t: round(rawHitSlop.top ?? rawHitSlop.t),
+                  r: round(rawHitSlop.right ?? rawHitSlop.r),
+                  b: round(rawHitSlop.bottom ?? rawHitSlop.b),
+                  l: round(rawHitSlop.left ?? rawHitSlop.l),
+                }
+              : undefined
         const base = {
           ...(typeof n.nodeId === 'number'
             ? {
@@ -635,6 +696,7 @@ export function layoutGetNativeEval(opts: LayoutExtractionOptions = {}): string
           type: typeof n.type === 'string' ? n.type : 'node',
           text,
           box: { x: round(abs.x), y: round(abs.y), w: round(layout.width), h: round(layout.height) },
+          ...(hitSlop !== undefined ? { hitSlop } : {}),
         }
         if (!includeStyle) return base
         // computedStyle has the resolved values; style is the curated subset —
@@ -651,6 +713,7 @@ export function layoutGetNativeEval(opts: LayoutExtractionOptions = {}): string
           bg: colorStr(style.backgroundColor),
           opacity: opacityOf(style),
           fontWeight: weightOf(style),
+          fontFamily: text ? familyOf(style) : undefined,
           textDecoration: decoOf(style),
           overflow: overflowOf(style),
           borderWidth,
@@ -773,6 +836,17 @@ export function formatLayoutElements(
       const uniform = p.t === p.r && p.r === p.b && p.b === p.l
       parts.push(uniform ? `pad:${p.t}` : `pad:${p.t},${p.r},${p.b},${p.l}`)
     }
+    if (el.hitSlop !== undefined) {
+      if (typeof el.hitSlop === 'number') {
+        parts.push(`hitSlop:${el.hitSlop}`)
+      } else {
+        const hs = el.hitSlop
+        const uniform = hs.t === hs.r && hs.r === hs.b && hs.b === hs.l
+        parts.push(
+          uniform ? `hitSlop:${hs.t}` : `hitSlop:${hs.t},${hs.r},${hs.b},${hs.l}`,
+        )
+      }
+    }
     if (el.fontSize !== undefined && el.fontSize > 0) {
       parts.push(`font:${el.fontSize}`)
     }
@@ -781,6 +855,8 @@ export function formatLayoutElements(
     // visual quality (contrast, washed-out, garbled/struck, clipping, flat).
     if (opts?.styling) {
       if (el.fontWeight) parts.push(`weight:${el.fontWeight}`)
+      if (el.fontFamily) parts.push(`family:"${el.fontFamily}"`)
+      if (el.fontLoaded === false) parts.push(`fontLoaded:false`)
       if (el.color) parts.push(`color:${el.color}`)
       if (el.bg) parts.push(`bg:${el.bg}`)
       if (el.contrast) {
@@ -824,7 +900,8 @@ export interface AccessibilityTreeNode {
 }
 
 // `get a11y` — flat accessibility summary projected from the visible semantic
-// tree, which already excludes hidden and covered content.
+// tree, which already excludes hidden and covered content, minus the painted
+// content VoiceOver cannot reach.
 export async function inspectAccessibilityTree(
   bridge: InspectBridge,
 ): Promise<AccessibilityTreeNode[]> {
@@ -834,6 +911,7 @@ export async function inspectAccessibilityTree(
   })
   if (!isSemanticQueryResult(result)) return []
   return result.nodes.flatMap((node) => {
+    if (node.accessibilityHidden) return []
     if (!node.role && !node.label && !node.text && !node.pressable) return []
     return [
       {
@@ -985,7 +1063,8 @@ export function scoreInteractive(n: InteractiveNode): number {
 export function tapCommandForNode(n: InteractiveNode): string {
   if (n.testID) return `peach do tap-id ${shellEscape(n.testID)}`
   const text = typeof n.text === 'string' ? n.text.trim() : ''
-  if (text.length > 0 && text.length <= 80) return `peach do tap-text ${shellEscape(text)}`
+  if (text.length > 0 && text.length <= 80)
+    return `peach do tap-text ${shellEscape(text)}`
   const x =
     Math.round(((n.absolutePosition?.x ?? 0) + (n.layout?.width ?? 0) / 2) * 10) / 10
   const y =

package/cli/commands/inspect/describe.ts

@@ -1,13 +1,9 @@
 // `peach describe` — format the pruned visible semantic tree.
 
+import { sleep } from '../../../src/sleep'
 import { maybeHint } from '../../hints'
 import { inspectDescribe, type DescribeDumpOptions } from './core'
-import {
-  maybeWaitForStartedScreenTransitions,
-  printJson,
-  sleep,
-  wantsJson,
-} from './shared'
+import { maybeWaitForStartedScreenTransitions, printJson, wantsJson } from './shared'
 import type { WsBridge } from '../../ws-bridge'
 
 export interface DescribeOptions {

package/cli/commands/inspect/env.ts

@@ -4,7 +4,7 @@
 // flicker the way a human can.
 const AGENT_ENV_VARS = [
   'PEACH_AGENT',
-  'TM_SESSION',
+  'PEACH_CLI_IDENTITY',
   'CLAUDECODE',
   'CLAUDE_CODE_ENTRYPOINT',
   'CLAUDE_CODE_SESSION_ID',

package/cli/commands/inspect/settling.ts

@@ -7,6 +7,10 @@ export type WaitForSootsimIdleOptions = {
   pollMs?: number
   stablePolls?: number
   strict?: boolean
+  // also require no newly painted frame across the window, the way maestro
+  // compares screenshots: a spinner or a rotation repaints without moving
+  // layout or registering as a driven animation.
+  paintStill?: boolean
 }
 
 export type WaitForSootsimIdleResult = {
@@ -25,6 +29,7 @@ export async function waitForSootsimIdle({
   pollMs = 50,
   stablePolls = 3,
   strict = false,
+  paintStill = false,
 }: WaitForSootsimIdleOptions): Promise<WaitForSootsimIdleResult> {
   const result = await bridge.send(
     {
@@ -36,6 +41,7 @@ export async function waitForSootsimIdle({
       const pollMs = ${Math.max(1, Math.round(pollMs))}
       const requiredStablePolls = ${Math.max(1, Math.round(stablePolls))}
       const strict = ${strict ? 'true' : 'false'}
+      const paintStill = ${paintStill ? 'true' : 'false'}
       const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
 
       // route-aware settle: a tap that pushes/pops a screen is async — the
@@ -67,10 +73,12 @@ export async function waitForSootsimIdle({
         let requestTotal = 0
         let requestInFlight = 0
         let renderStatsAvailable = false
+        let frameCount = -1
         try {
           const stats = await window.__sootsimRenderHost?.queryStats?.()
           if (stats) {
             renderStatsAvailable = true
+            frameCount = typeof stats.frameCount === 'number' ? stats.frameCount : -1
             animating =
               stats.hasActiveAnims === true ||
               stats.hasActiveNativeAnimations === true ||
@@ -103,7 +111,7 @@ export async function waitForSootsimIdle({
           }
           walk(root)
         }
-        return { layout: nodes.join(';'), animating, layoutDirty, pendingFetches, renderStatsAvailable, requestTotal, requestInFlight }
+        return { layout: nodes.join(';'), frameCount, animating, layoutDirty, pendingFetches, renderStatsAvailable, requestTotal, requestInFlight }
       }
 
       // how long generic background network is allowed to keep us waiting AFTER
@@ -118,6 +126,8 @@ export async function waitForSootsimIdle({
       // only within this grace once the screen is visually still.
       const networkQuietGraceMs = 1200
       let lastLayout = ''
+      let lastFrameCount = -2
+      let paintedPolls = 0
       let lastRequestTotal = -1
       let stable = 0
       let visuallyStillSince = 0
@@ -134,13 +144,18 @@ export async function waitForSootsimIdle({
         if (snapshot.layoutDirty) dirtyPolls++
         if (snapshot.animating) animatingPolls++
         if (polls > 1 && snapshot.layout !== lastLayout) layoutChangedPolls++
+        const painted = paintStill && snapshot.frameCount !== lastFrameCount
+        if (polls > 1 && painted) paintedPolls++
         const strictOk =
           !strict ||
           (snapshot.renderStatsAvailable && !snapshot.animating && !snapshot.layoutDirty)
         // visually settled: no animations, no image content loading, layout
         // unchanged since the last poll.
         const visuallyStill =
-          strictOk && snapshot.pendingFetches === 0 && snapshot.layout === lastLayout
+          strictOk &&
+          !painted &&
+          snapshot.pendingFetches === 0 &&
+          snapshot.layout === lastLayout
         // generic network quiet: nothing in flight and no new requests issued.
         const networkQuiet =
           snapshot.requestInFlight === 0 && snapshot.requestTotal === lastRequestTotal
@@ -161,6 +176,7 @@ export async function waitForSootsimIdle({
           visuallyStillSince = 0
         }
         lastLayout = snapshot.layout
+        lastFrameCount = snapshot.frameCount
         lastRequestTotal = snapshot.requestTotal
         await sleep(pollMs)
       }
@@ -171,6 +187,7 @@ export async function waitForSootsimIdle({
       if (last.layoutDirty) blockers.push('layout still dirty')
       if (last.pendingFetches > 0) blockers.push(last.pendingFetches + ' image fetches pending')
       if (last.layout !== lastLayout) blockers.push('layout still changing')
+      if (paintStill && last.frameCount !== lastFrameCount) blockers.push('still painting')
       if (last.requestInFlight > 0) blockers.push(last.requestInFlight + ' requests in flight')
       return {
         settled: false,
@@ -178,7 +195,7 @@ export async function waitForSootsimIdle({
         blockedBy:
           (blockers.length ? blockers.join(', ') : 'unknown') +
           ' over ' + polls + ' polls (layout changed ' + layoutChangedPolls +
-          'x, layoutDirty ' + dirtyPolls + 'x, animating ' + animatingPolls + 'x)',
+          'x, layoutDirty ' + dirtyPolls + 'x, animating ' + animatingPolls + 'x, painted ' + paintedPolls + 'x)',
       }
     })()`,
     },

package/cli/commands/inspect/shared.ts

@@ -4,6 +4,7 @@
 // own file without reaching back into a 4000-line switch. everything here is
 // call-agnostic: just bridge-facing helpers that any subcommand can use.
 
+import { sleep } from '../../../src/sleep'
 import {
   callInBridge,
   callInBridgeWrite,
@@ -25,10 +26,6 @@ export const SCREEN_TRANSITION_PREFLIGHT = {
   startWindowMs: 64,
 } as const
 
-export function sleep(ms: number) {
-  return new Promise((resolve) => setTimeout(resolve, ms))
-}
-
 // true when the caller passed --json. read verbs use this to route their
 // payload to stdout-as-json and send everything else (headers, hints,
 // warnings) to stderr so `jq` on stdout never sees framing noise.

package/cli/commands/inspect/sleep.ts

@@ -1,5 +1,5 @@
+import { sleep } from '../../../src/sleep'
 import { rnxExit } from '../../run-rnx'
-import { sleep } from './shared'
 
 export async function runSleepSubcommand(opts: {
   positional: string[]

package/cli/commands/inspect.ts

@@ -5,6 +5,7 @@ import { getCliInspectVerbMeta } from '@peach/skills/cli'
 import { renderCliCommandHelp, renderCliGroupHelp } from '@peach/skills/cli/renderers'
 import { DEFAULT_SOOTSIM_BRIDGE_PORT } from '../../src/bridge-constants'
 import { DEFAULT_SOOTSIM_SHELL_URL } from '../../src/cli-constants'
+import { sleep } from '../../src/sleep'
 import { resetGuestAppStateEval } from '../app-state-reset'
 import { printBridgeStateSummary } from '../bridge-diagnostics'
 import {
@@ -87,7 +88,6 @@ import {
   printJson,
   printWarn,
   type ReloadReadyResult,
-  sleep,
   SCREEN_TRANSITION_PREFLIGHT,
   waitForBridgeConnected,
   wantsJson,
@@ -1148,9 +1148,7 @@ export async function runInspect(args: string[], opts: InspectOptions) {
   if (!subcommand || args.includes('--help') || args.includes('-h')) {
     // all help output comes from the registry in packages/peach-skills
     // so `peach do --help`, `peach get --help`, the website docs, and
-    // the Contrast skill markdown stay in lock-step. a drift check in
-    // test/sootsimCliRegistry.test.ts fails CI if a verb lands without a
-    // matching registry entry.
+    // the Contrast skill markdown stay in lock-step.
     const docContext = {
       bridgePort: DEFAULT_SOOTSIM_BRIDGE_PORT,
       defaultShellUrl: DEFAULT_SOOTSIM_SHELL_URL,
@@ -2859,11 +2857,18 @@ export async function runInspect(args: string[], opts: InspectOptions) {
             type: resolved.type ?? null,
           }
         }
-        const durationArg = target ? positional[1] : positional[3]
+        const durationArg = target
+          ? Number.isFinite(Number(positional[1]))
+            ? positional[1]
+            : positional[2]
+          : positional[3]
         const durationMs = durationArg ? Number(durationArg) : 600
         if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(durationMs)) {
           console.error(
-            inspectUsage('long-press', '<testid> | <x> <y> [durationMs] | --testid <id>'),
+            inspectUsage(
+              'long-press',
+              '<testid> [durationMs] | <x> <y> [durationMs] | --testid <id>',
+            ),
           )
           rnxExit(1)
         }
@@ -2887,50 +2892,12 @@ export async function runInspect(args: string[], opts: InspectOptions) {
       }
 
       case 'touch': {
-        const phase = positional[1]
-        const x = Number(positional[2])
-        const y = Number(positional[3])
-        const pointerId = positional[4] ? Number(positional[4]) : 999
-        const method =
-          phase === 'down'
-            ? 'touchDown'
-            : phase === 'move'
-              ? 'touchMove'
-              : phase === 'up'
-                ? 'touchUp'
-                : phase === 'cancel'
-                  ? 'touchCancel'
-                  : null
-        if (!method) {
-          console.error(
-            inspectUsage('touch', '<down|move|up|cancel> <x> <y> [pointerId]'),
-          )
-          rnxExit(1)
-        }
-        if (phase !== 'cancel' && (!Number.isFinite(x) || !Number.isFinite(y))) {
-          console.error(
-            inspectUsage('touch', '<down|move|up|cancel> <x> <y> [pointerId]'),
-          )
-          rnxExit(1)
-        }
-        // the engine's perform executor emits the matching agent-cursor
-        // action (tap for down, move for move) natively.
-        const roundedPointerId = Math.max(1, Math.round(pointerId))
-        const result = await performSingleStep(
-          bridge,
-          method === 'touchCancel'
-            ? { type: method, pointerId: roundedPointerId }
-            : { type: method, x, y, pointerId: roundedPointerId },
+        // perform batches are self-contained (a pointer never outlives its
+        // batch), so a lone phase could never hold a press between commands.
+        console.error(
+          '  error: a touch lives within one batch; chain its phases, e.g. peach do touch down 200 720 --then touch move 200 400 --then touch up 200 400',
         )
-        if (result?.ok && phase !== 'cancel') {
-          await recordInspectAction(
-            'inspect touch',
-            { tapAtCoords: { x, y } },
-            `touch ${phase} @${x},${y}`,
-          )
-        }
-        console.log(JSON.stringify(result, null, 2))
-        break
+        rnxExit(1)
       }
 
       case 'gesture': {

package/cli/commands/install-desktop.ts

@@ -4,7 +4,7 @@
 // for users who want the Electron-based GUI companion on top of that.
 //
 // fetches the right platform artifact from https://contrast.dev/api/electron-release/
-// and installs it into the OS-native location that findDesktopCompanion() looks for:
+// and installs it into the OS-native location that findInstalledDesktopCompanion() looks for:
 //   macos: ~/Applications/peach.app (or /Applications if writable)
 //   linux: ~/Applications/peach.AppImage
 //   win:   spawns the NSIS installer
@@ -25,7 +25,7 @@ import {
 } from 'fs'
 import { tmpdir } from 'os'
 import { dirname, join, resolve } from 'path'
-import { findDesktopCompanion } from '../desktop-companion'
+import { findInstalledDesktopCompanion } from '../desktop-companion'
 import { confirm } from '../prompt'
 import { rnxExit } from '../run-rnx'
 import { accent, bold, failure, muted, success, withSpinner } from '../ui'
@@ -155,7 +155,7 @@ async function installMacDmg(dmgPath: string): Promise<string> {
   }
 
   // prefer /Applications if writable, otherwise ~/Applications (same paths
-  // findDesktopCompanion checks, so no extra config needed post-install).
+  // findInstalledDesktopCompanion checks, so no extra config needed post-install).
   const systemApps = '/Applications'
   const userApps = resolve(process.env.HOME || '', 'Applications')
   let destRoot = systemApps
@@ -249,7 +249,7 @@ async function installWindowsExe(exePath: string): Promise<string> {
       else rejectPromise(new Error(`installer exited with code ${code}`))
     })
   })
-  const installed = findDesktopCompanion()
+  const installed = findInstalledDesktopCompanion()
   if (!installed) {
     throw new Error('the installer finished but the peach application was not registered')
   }
@@ -286,7 +286,7 @@ examples:
     !process.stdin.isTTY
   const force = args.includes('--force')
 
-  const existing = findDesktopCompanion()
+  const existing = findInstalledDesktopCompanion()
   if (existing && !force) {
     console.log(`  ${success('✓')} Desktop app is already installed at ${existing.path}`)
     console.log(`  ${muted('Pass --force to reinstall.')}`)
@@ -347,7 +347,9 @@ examples:
     console.error(
       '  network blocked the request. Check your connection and try again later.',
     )
-    console.error('  The CLI and daemon work without the desktop app. Run `peach --help`.')
+    console.error(
+      '  The CLI and daemon work without the desktop app. Run `peach --help`.',
+    )
     rnxExit(1)
   }