peachsim 0.1.637 → 0.1.639

package/README.md

@@ -235,11 +235,14 @@ Pass a target to `peach open <port-or-url>` when a script or agent needs an expl
 selection.
 
 The first `peach open` launches an isolated Chrome for Testing sim. The CLI
-resolves Playwright from the current directory or beside its executable, asks that exact package for
-its required browser executable, and runs that package's installer once when
-the executable is absent. It never substitutes another revision found in the
-shared Playwright cache. Later opens reuse that sim and reload it at the
-requested target. Use `peach do reload` when the target has not changed.
+resolves Playwright from the current directory or beside its executable and
+launches the newest installed Chromium revision in its browser cache, honoring
+`PLAYWRIGHT_BROWSERS_PATH`. Set `PEACH_CHROMIUM_EXECUTABLE` to an existing
+executable to select a binary explicitly. Headless and headed launches use that
+same binary. When no installed browser is available, the CLI runs the resolved
+Playwright core's absolute installer entry. 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
 consume memory and CPU on shared machines.
 

package/cli/bridge-flow-runner.ts

@@ -6,7 +6,11 @@ import { REQUIRED_IDENTICAL_FLOW_FRAMES, framesIdentical } from '../detox/proof-
 import { flowTimeoutScale } from '../src/flow-timeout-scale'
 import { composeFramedScreenshot } from '../src/screenshots/frame-compose'
 import { sleep } from '../src/sleep'
-import { inspectWaitReady, waitReadyReason } from './commands/inspect/core'
+import {
+  inspectWaitReady,
+  isPeachAccessibilityTree,
+  waitReadyReason,
+} from './commands/inspect/core'
 import { waitForSootsimIdle } from './commands/inspect/settling'
 import { callShellCommandWhenReady, getShellState } from './commands/inspect/shared'
 import { PERMISSION_KINDS } from './commands/permissions'
@@ -16,7 +20,11 @@ import { MaestroJsContext, scriptConditionIsTruthy } from './maestro-js'
 import { ensureCliRecordingEntitlement } from './recording-access'
 import type { PerformResult, PerformStep, ResetResult } from '../src/bridge-contract'
 import type { WsBridge } from './ws-bridge'
-import type { SootSimReplayTarget, SootSimTapResult } from '@peach/globals'
+import type {
+  PeachAccessibilityNode,
+  SootSimReplayTarget,
+  SootSimTapResult,
+} from '@peach/globals'
 import type {
   SootSimExternalAppLifecycleOptions,
   SootSimLaunchArguments,
@@ -46,6 +54,9 @@ type FlowTargetSelector = {
   enabled?: boolean
   selected?: boolean
   checked?: boolean
+  focused?: boolean
+  containsChild?: FlowTargetSelector
+  containsDescendants?: FlowTargetSelector[]
   below?: string | FlowTargetSelector
   above?: string | FlowTargetSelector
   leftOf?: string | FlowTargetSelector
@@ -105,16 +116,10 @@ const SELECTOR_FILTER_KEYS = [
   'leftOf',
   'rightOf',
 ] as const
-// maestro filters without a verified ios reading here yet: `containsChild` and
-// `containsDescendants` walk the ios accessibility hierarchy, which hides the
-// children of an accessible element; `focused` is XCUIElement.hasFocus; `css`
-// is web only.
-const UNSUPPORTED_SELECTOR_KEYS = [
-  'containsChild',
-  'containsDescendants',
-  'focused',
-  'css',
-]
+// maestro filters without a verified ios reading here yet: `css` is web only.
+// `containsChild`, `containsDescendants`, and `focused` read the engine's
+// XCTest accessibility projection (see findElementAccessibilityTree).
+const UNSUPPORTED_SELECTOR_KEYS = ['css']
 // ignoring a key widens the match, so an assertion passes that maestro fails.
 function assertSupportedSelector(selector: unknown) {
   if (!selector || typeof selector !== 'object') return
@@ -125,10 +130,384 @@ function assertSupportedSelector(selector: unknown) {
   if (unsupported.length > 0) {
     throw new Error(`selector ${unsupported.join(', ')} is not supported by peach yet`)
   }
-  for (const key of ['childOf', 'below', 'above', 'leftOf', 'rightOf']) {
+  for (const key of ['childOf', 'below', 'above', 'leftOf', 'rightOf', 'containsChild']) {
     assertSupportedSelector(Reflect.get(selector, key))
   }
+  const descendants = Reflect.get(selector, 'containsDescendants')
+  if (descendants !== undefined) {
+    if (!Array.isArray(descendants)) {
+      throw new Error('selector containsDescendants must be a list of selectors')
+    }
+    for (const descendant of descendants) assertSupportedSelector(descendant)
+  }
+}
+
+// the filters whose meaning is defined on the XCTest accessibility hierarchy.
+// ordinary lookups stay on the faster render tree; these read the engine's
+// accessibility projection through captureAccessibilityTree().
+const ACCESSIBILITY_SELECTOR_KEYS = [
+  'containsChild',
+  'containsDescendants',
+  'focused',
+] as const
+
+function needsAccessibilityProjection(selector: string | FlowTargetSelector): boolean {
+  if (typeof selector === 'string') return false
+  if (ACCESSIBILITY_SELECTOR_KEYS.some((key) => selector[key] != null)) return true
+  return ['childOf', 'below', 'above', 'leftOf', 'rightOf'].some((key) => {
+    const nested: unknown = Reflect.get(selector, key)
+    return isSelectorRecord(nested) && needsAccessibilityProjection(nested)
+  })
+}
+
+type AccessibilityNodePredicate = (node: PeachAccessibilityNode) => boolean
+
+// preorder aggregate, the same order TreeNode.aggregate() walks on ios.
+function accessibilityTreeNodes(
+  tree: readonly PeachAccessibilityNode[],
+): PeachAccessibilityNode[] {
+  const out: PeachAccessibilityNode[] = []
+  const visit = (node: PeachAccessibilityNode): void => {
+    out.push(node)
+    for (const child of node.children) visit(child)
+  }
+  for (const root of tree) visit(root)
+  return out
+}
+
+// a container's own hierarchy: the node plus every descendant, matching
+// ViewHierarchy(element.treeNode).aggregate().
+function accessibilitySubtreeNodes(
+  node: PeachAccessibilityNode,
+): PeachAccessibilityNode[] {
+  return [node, ...node.children.flatMap(accessibilitySubtreeNodes)]
+}
+
+// maestro matches the whole id or text against the selector's regex; the
+// render-tree resolver compiles the same anchored pattern.
+function accessibilityTextMatcher(
+  value: string,
+  kind: 'text' | 'id',
+): (candidate: string | null) => boolean {
+  const pattern = new RegExp(`^(?:${value})$`)
+  return (candidate) => {
+    // IOSDriver emits an empty attribute for absent label, value and id.
+    const native = candidate ?? ''
+    if (kind === 'id')
+      return (
+        pattern.test(native) || pattern.test(native.slice(native.lastIndexOf('/') + 1))
+      )
+    const stripped = native.replaceAll('\n', ' ')
+    return (
+      native === value ||
+      stripped === value ||
+      pattern.test(native) ||
+      pattern.test(stripped)
+    )
+  }
+}
+
+// maestro reads ios frames as integer edges (AXElement.boundsString).
+function accessibilityBounds(node: PeachAccessibilityNode): {
+  x: number
+  y: number
+  width: number
+  height: number
+} {
+  const left = Math.trunc(node.frame.x)
+  const top = Math.trunc(node.frame.y)
+  return {
+    x: left,
+    y: top,
+    width: Math.trunc(node.frame.x + node.frame.width) - left,
+    height: Math.trunc(node.frame.y + node.frame.height) - top,
+  }
+}
+
+const ACCESSIBILITY_TRAIT_FILTERS: Record<string, AccessibilityNodePredicate> = {
+  // IOSDriver sets attributes["text"] on every node, including empty text.
+  TEXT: () => true,
+  SQUARE: (node) => {
+    const bounds = accessibilityBounds(node)
+    return Math.abs(1 - bounds.width / bounds.height) < 0.03
+  },
+  LONG_TEXT: (node) => (node.value?.length ?? 0) > 200,
+}
+
+// Orchestra.buildFilter's basic filters, in its order: text, id, size,
+// traits, enabled, selected, checked, focused. css is refused before this runs.
+function accessibilityBasicFilters(
+  selector: FlowTargetSelector,
+): AccessibilityNodePredicate[] {
+  const filters: AccessibilityNodePredicate[] = []
+  if (selector.text != null) {
+    const matches = accessibilityTextMatcher(selector.text, 'text')
+    // ios textMatches reads attributes text, hintText (the placeholder) and
+    // accessibilityText; the canonical label/value/placeholder carry those.
+    filters.push(
+      (node) => matches(node.label) || matches(node.value) || matches(node.placeholder),
+    )
+  }
+  if (selector.id != null) {
+    const matches = accessibilityTextMatcher(selector.id, 'id')
+    filters.push((node) => matches(node.testID))
+  }
+  if (selector.width != null || selector.height != null) {
+    const tolerance = selector.tolerance ?? 0
+    filters.push((node) => {
+      const bounds = accessibilityBounds(node)
+      return (
+        (selector.width == null ||
+          Math.abs(bounds.width - selector.width) <= tolerance) &&
+        (selector.height == null ||
+          Math.abs(bounds.height - selector.height) <= tolerance)
+      )
+    })
+  }
+  for (const trait of selector.traits ? selector.traits.split(' ') : []) {
+    const filter = ACCESSIBILITY_TRAIT_FILTERS[trait.replaceAll('-', '_').toUpperCase()]
+    if (!filter) throw new Error(`unknown selector trait: ${trait}`)
+    filters.push(filter)
+  }
+  if (selector.enabled != null) {
+    filters.push((node) => node.enabled === selector.enabled)
+  }
+  if (selector.selected != null) {
+    filters.push((node) => node.selected === selector.selected)
+  }
+  if (selector.checked != null) {
+    filters.push((node) => node.checked === selector.checked)
+  }
+  // XCTest may omit hasFocus; the native driver defaults an absent snapshot
+  // key to false, and editing focus is a separate native concept.
+  if (selector.focused != null) {
+    filters.push((node) => (node.hasFocus ?? false) === selector.focused)
+  }
+  return filters
+}
+
+// Filters.deepestMatchingElement: a node contributes its deepest matching
+// descendants when any exist, else itself when it matches.
+function deepestMatchingAccessibilityNodes(
+  nodes: readonly PeachAccessibilityNode[],
+  matches: AccessibilityNodePredicate,
+): PeachAccessibilityNode[] {
+  const out: PeachAccessibilityNode[] = []
+  const included = new Set(nodes)
+  const nested = new Set(
+    nodes.flatMap((node) => node.children.filter((child) => included.has(child))),
+  )
+  for (const node of nodes.filter((node) => !nested.has(node))) {
+    const children = deepestMatchingAccessibilityNodes(node.children, matches)
+    if (children.length > 0) out.push(...children)
+    else if (matches(node)) out.push(node)
+  }
+  return distinctAccessibilityNodes(out)
+}
+
+function distinctAccessibilityNodes(
+  nodes: readonly PeachAccessibilityNode[],
+): PeachAccessibilityNode[] {
+  // TreeNode.distinct compares native fields and children, not engine identity.
+  // bucket by scalar attributes first; full subtree comparisons are only needed
+  // for nodes with identical attributes and the same number of children.
+  const buckets = new Map<string, PeachAccessibilityNode[]>()
+  return nodes.filter((node) => {
+    const key = JSON.stringify([
+      node.testID ?? '',
+      node.label ?? '',
+      node.placeholder ?? '',
+      node.value ?? '',
+      node.enabled,
+      node.selected,
+      node.checked,
+      node.clickable,
+      node.hasFocus ?? false,
+      accessibilityBounds(node),
+      node.children.length,
+    ])
+    const bucket = buckets.get(key)
+    if (bucket?.some((other) => sameNativeAccessibilityShape(node, other))) return false
+    if (bucket) bucket.push(node)
+    else buckets.set(key, [node])
+    return true
+  })
+}
+
+function isSelectorRecord(value: unknown): value is FlowTargetSelector {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function accessibilityAnchorSelector(value: unknown): FlowTargetSelector {
+  if (typeof value === 'string') return { text: value }
+  return isSelectorRecord(value) ? value : {}
+}
+
+// upstream Filters.containsChild compares the resolved child TreeNode against
+// a candidate's immediate children by structural equality: the native
+// attribute map, the boolean flags, and the children, recursively. the native
+// hintText attribute is the placeholder (accessibilityHint is not a TreeNode
+// attribute), and engine identity (elementId/nodeId) plus the projection's own
+// metadata (type, role, isAccessibilityElement, state) are not part of that
+// native shape.
+function sameNativeAccessibilityShape(
+  a: PeachAccessibilityNode,
+  b: PeachAccessibilityNode,
+): boolean {
+  if (
+    (a.testID ?? '') !== (b.testID ?? '') ||
+    (a.label ?? '') !== (b.label ?? '') ||
+    (a.placeholder ?? '') !== (b.placeholder ?? '') ||
+    (a.value ?? '') !== (b.value ?? '') ||
+    a.enabled !== b.enabled ||
+    a.selected !== b.selected ||
+    a.checked !== b.checked ||
+    a.clickable !== b.clickable ||
+    (a.hasFocus ?? false) !== (b.hasFocus ?? false) ||
+    JSON.stringify(accessibilityBounds(a)) !== JSON.stringify(accessibilityBounds(b)) ||
+    a.children.length !== b.children.length
+  ) {
+    return false
+  }
+  for (const [index, child] of a.children.entries()) {
+    const other = b.children[index]
+    if (!other || !sameNativeAccessibilityShape(child, other)) return false
+  }
+  return true
+}
+
+// Filters.containsDescendants: every selector must match inside a child
+// subtree; the node itself is excluded. A selector matches a subtree node by
+// the full filter applied to that single node (Filters' `matches`), which for
+// relative filters resolves anchors against the same one-node list.
+function accessibilitySubtreeMatches(
+  all: readonly PeachAccessibilityNode[],
+  node: PeachAccessibilityNode,
+  selector: FlowTargetSelector,
+): boolean {
+  if (filterAccessibilityNodes(all, [node], selector).length > 0) return true
+  return node.children.some((child) => accessibilitySubtreeMatches(all, child, selector))
+}
+
+// Orchestra's childOf scopes the whole lookup to the container's hierarchy
+// before any filter runs (findElementViewHierarchy + aggregate); a container
+// that does not resolve leaves nothing to search.
+function filterAccessibilityNodes(
+  all: readonly PeachAccessibilityNode[],
+  nodes: readonly PeachAccessibilityNode[],
+  selector: FlowTargetSelector,
+): PeachAccessibilityNode[] {
+  if (selector.childOf == null) {
+    return filterAccessibilityNodesIn(all, nodes, selector)
+  }
+  const container = filterAccessibilityNodes(
+    all,
+    all,
+    accessibilityAnchorSelector(selector.childOf),
+  )[0]
+  if (!container) return []
+  return filterAccessibilityNodesIn(all, accessibilitySubtreeNodes(container), selector)
 }
+
+// Orchestra.buildFilter over the accessibility projection: basic filters
+// through deepestMatching, then the relative filters intersected in
+// buildFilter's order, then index or clickableFirst. `nodes` is the candidate
+// list a relative anchor filter sees, exactly as Filters.intersect applies
+// every filter to the same input list.
+function filterAccessibilityNodesIn(
+  all: readonly PeachAccessibilityNode[],
+  nodes: readonly PeachAccessibilityNode[],
+  selector: FlowTargetSelector,
+): PeachAccessibilityNode[] {
+  const basic = accessibilityBasicFilters(selector)
+  let candidates =
+    basic.length > 0
+      ? deepestMatchingAccessibilityNodes(nodes, (node) =>
+          basic.every((filter) => filter(node)),
+        )
+      : [...nodes]
+
+  const relativeGeometry = {
+    below: (node: PeachAccessibilityNode, other: PeachAccessibilityNode) =>
+      accessibilityBounds(node).y > accessibilityBounds(other).y,
+    above: (node: PeachAccessibilityNode, other: PeachAccessibilityNode) =>
+      accessibilityBounds(node).y < accessibilityBounds(other).y,
+    leftOf: (node: PeachAccessibilityNode, other: PeachAccessibilityNode) =>
+      accessibilityBounds(node).x < accessibilityBounds(other).x,
+    rightOf: (node: PeachAccessibilityNode, other: PeachAccessibilityNode) =>
+      accessibilityBounds(node).x > accessibilityBounds(other).x,
+  } as const
+  for (const key of ['below', 'above', 'leftOf', 'rightOf'] as const) {
+    const anchor = selector[key]
+    if (anchor == null) continue
+    const anchors = filterAccessibilityNodes(
+      all,
+      nodes,
+      accessibilityAnchorSelector(anchor),
+    )
+    candidates = candidates.filter((node) =>
+      anchors.some((other) => relativeGeometry[key](node, other)),
+    )
+  }
+
+  if (selector.containsChild != null) {
+    // Orchestra resolves the child selector globally (findElement with
+    // optional=false) before the predicate runs. an unresolved child matches
+    // nothing, so a caller's retry window still applies.
+    const child = filterAccessibilityNodes(
+      all,
+      all,
+      accessibilityAnchorSelector(selector.containsChild),
+    )[0]
+    candidates = child
+      ? candidates.filter((node) =>
+          node.children.some((candidate) =>
+            sameNativeAccessibilityShape(candidate, child),
+          ),
+        )
+      : []
+  }
+
+  if (selector.containsDescendants != null) {
+    const descendants = selector.containsDescendants.map(accessibilityAnchorSelector)
+    candidates = candidates.filter((node) =>
+      descendants.every((descendant) =>
+        node.children.some((child) =>
+          accessibilitySubtreeMatches(all, child, descendant),
+        ),
+      ),
+    )
+  }
+
+  // Filters.intersect converts every filter result to a TreeNode set,
+  // including selectors containing only structural or relative filters.
+  candidates = distinctAccessibilityNodes(candidates)
+
+  if (selector.index != null) {
+    const index = Math.trunc(Number(selector.index))
+    const sorted = [...candidates].sort((a, b) => {
+      const aBounds = accessibilityBounds(a)
+      const bBounds = accessibilityBounds(b)
+      return aBounds.y - bBounds.y || aBounds.x - bBounds.x
+    })
+    const resolved = index >= 0 ? index : sorted.length + index
+    if (resolved < 0 || resolved >= sorted.length) return []
+    const picked = sorted[resolved]
+    return picked ? [picked] : []
+  }
+  // clickableFirst is a stable descending sort; ios reports no clickable bit,
+  // so every node ties and the filter order survives.
+  return [...candidates].sort((a, b) => Number(b.clickable) - Number(a.clickable))
+}
+
+function resolveAccessibilitySelector(
+  tree: readonly PeachAccessibilityNode[],
+  selector: FlowTargetSelector,
+): PeachAccessibilityNode | null {
+  const all = accessibilityTreeNodes(tree)
+  return filterAccessibilityNodes(all, all, selector)[0] ?? null
+}
+
 type FocusedTextInputInfo = {
   nodeId?: number | null
   id?: string | null
@@ -910,6 +1289,12 @@ export class SootSimBridgeFlowRunner {
 
   private async findElement(opts: FlowTargetSelector) {
     assertSupportedSelector(opts)
+    // the structural filters are defined on the XCTest accessibility
+    // hierarchy, so they resolve against the engine's accessibility
+    // projection instead of the render tree.
+    if (needsAccessibilityProjection(opts)) {
+      return this.findElementAccessibilityTree(opts)
+    }
     // id selectors, patterns and filtered selectors resolve over the full
     // candidate set in maestro's order, so a repeated id (one per list row)
     // means the top row. a literal text selector keeps the direct lookup.
@@ -951,6 +1336,47 @@ export class SootSimBridgeFlowRunner {
     })()`)
   }
 
+  // structural filters (containsChild / containsDescendants / focused) read the
+  // engine's XCTest accessibility projection — one bridge evaluate, then the
+  // same Orchestra.buildFilter semantics the render resolver implements, over
+  // PeachAccessibilityNode instead of the visible semantic tree.
+  private async findElementAccessibilityTree(opts: FlowTargetSelector) {
+    const tree = await this.evaluate(`(async () => {
+      const test = window.__sootsimTest
+      if (!test || typeof test.captureAccessibilityTree !== 'function') throw new Error('engine accessibility snapshot is unavailable')
+      return await test.captureAccessibilityTree()
+    })()`)
+    if (!isPeachAccessibilityTree(tree))
+      throw new Error('engine returned an invalid accessibility snapshot')
+    if (tree.length === 0) return null
+    if (tree.some((node) => node.platform !== 'ios'))
+      throw new Error(
+        'containsChild, containsDescendants and focused require the iOS accessibility hierarchy',
+      )
+    const node = resolveAccessibilitySelector(tree, opts)
+    if (!node) return null
+    const frame = node.frame
+    return {
+      nodeId: Number.isFinite(node.nodeId) ? node.nodeId : null,
+      id: node.testID,
+      testID: node.testID,
+      text: node.label,
+      accessibilityLabel: node.label,
+      absolutePosition: { x: frame.x, y: frame.y },
+      layout: { width: frame.width, height: frame.height },
+      // the engine applies Maestro's integer-frame viewport filter to the
+      // native hierarchy before this lookup; preserve the native bounds.
+      visibleFrame: {
+        x: frame.x,
+        y: frame.y,
+        width: frame.width,
+        height: frame.height,
+        area: frame.width * frame.height,
+      },
+      isTextInput: node.isTextInput,
+    }
+  }
+
   // maestro's selector resolver (Orchestra.buildFilter over Filters.kt):
   // id and text patterns, size, traits, enabled/selected, the relative
   // below/above/leftOf/rightOf filters, `index:` (nth match) and `childOf:`
@@ -1410,7 +1836,9 @@ export class SootSimBridgeFlowRunner {
     // looks up by id or text alone, so a selector that narrows further only
     // takes it for an element its own match already found.
     const narrowed =
-      opts.index != null || SELECTOR_FILTER_KEYS.some((key) => opts[key] != null)
+      opts.index != null ||
+      SELECTOR_FILTER_KEYS.some((key) => opts[key] != null) ||
+      ACCESSIBILITY_SELECTOR_KEYS.some((key) => opts[key] != null)
     const direct = element || !narrowed ? await this.activatePressTarget(opts) : null
     if (direct?.ok) {
       await this.settleAfterInput()

package/cli/command-registry.ts

@@ -42,6 +42,7 @@ const NODE_COMMAND_NAMES = [
   'android',
   'remote',
   'preview',
+  'swift',
   'box',
   'list',
   'use',

package/cli/commands/control.ts

@@ -99,6 +99,14 @@ interface ControlCommandOptions {
   runtimeConfig?: RNXConfig
 }
 
+export interface OpenCommandResources {
+  bridge?: ReturnType<typeof spawn>
+  bridgeReady?: boolean
+  port?: number
+  driver?: DriverLaunchResult & { driverId: DriverId }
+  simId?: string
+}
+
 interface DriverConnectWaitOptions {
   attempts: number
   intervalMs: number
@@ -184,6 +192,7 @@ function normalizeKnownTarget(target: string): string {
 export async function ensureBridgeForOpen(
   preferredPort: number,
   explicitPort = false,
+  resources?: OpenCommandResources,
 ): Promise<number> {
   const lock = readDaemonLockfile()
   assertExplicitBridgeLock(preferredPort, explicitPort, lock)
@@ -218,6 +227,10 @@ export async function ensureBridgeForOpen(
 
   await ensureRuntimeForOpen()
   const child = spawnSootsim(['serve', '--quiet', '--port', String(preferredPort)])
+  if (resources) {
+    resources.bridge = child
+    resources.port = preferredPort
+  }
   let childExit: string | null = null
   child.once('exit', (code, signal) => {
     childExit = String(code ?? signal ?? 'unknown')
@@ -252,6 +265,10 @@ export async function ensureBridgeForOpen(
       console.error(
         `  Started a local bridge on port ${selectedPort}. Run \`peach daemon install\` to keep it ready between commands.`,
       )
+      if (resources) {
+        resources.bridgeReady = true
+        resources.port = selectedPort
+      }
       return selectedPort
     }
     if (childExit) {
@@ -1048,13 +1065,14 @@ export async function waitForSimMatchOrHostExit(
   commandTimeoutMs: number,
   predicate: (sim: BridgeSimInfo) => boolean,
   hostPid: number | undefined,
-  opts: { attempts?: number; intervalMs?: number } = {},
+  opts: { attempts?: number; intervalMs?: number; signal?: AbortSignal } = {},
 ): Promise<WaitForSimMatchOrHostExitResult> {
   const attempts = opts.attempts ?? 30
   const intervalMs = opts.intervalMs ?? 500
   const watchHost = !!hostPid && Number.isInteger(hostPid) && hostPid > 1
   const hostExited = () => watchHost && hostPid !== undefined && !isProcessAlive(hostPid)
   for (let i = 0; i < attempts; i++) {
+    opts.signal?.throwIfAborted()
     if (hostExited()) {
       return { kind: 'host-exit' }
     }
@@ -1430,7 +1448,11 @@ export async function runLinkCommand(args: string[], opts: ControlCommandOptions
 
 export async function runOpenCommand(
   args: string[],
-  opts: ControlCommandOptions = {},
+  opts: ControlCommandOptions & {
+    resources?: OpenCommandResources
+    signal?: AbortSignal
+    ownerPid?: number
+  } = {},
 ): Promise<{ simId: string; launched: boolean } | undefined> {
   const parsed = parseBridgeCliArgs(args, {
     port: opts.port,
@@ -1581,7 +1603,14 @@ export async function runOpenCommand(
     }
   }
 
-  parsed.wsPort = await ensureBridgeForOpen(parsed.wsPort, parsed.explicitPort)
+  opts.signal?.throwIfAborted()
+  parsed.wsPort = await ensureBridgeForOpen(
+    parsed.wsPort,
+    parsed.explicitPort,
+    opts.resources,
+  )
+  if (opts.resources) opts.resources.port = parsed.wsPort
+  opts.signal?.throwIfAborted()
 
   // playwright is the browser-sim launcher. it owns an isolated profile and
   // can reap exactly its own browser tree. electron remains available for the
@@ -1890,7 +1919,7 @@ export async function runOpenCommand(
 
   const configuredBaseUrl = applyRNXConfigToUrl(baseUrl, runtimeConfig)
   const openUrl = await buildOpenUrl(target, configuredBaseUrl, token, buildShellUrlOpts)
-  const ownerPid = getStableOwnerPid()
+  const ownerPid = opts.ownerPid ?? getStableOwnerPid()
   if (!ownerPid) {
     console.error(
       '  could not resolve a stable owning process; refusing unsupervised sim host',
@@ -1903,6 +1932,7 @@ export async function runOpenCommand(
     rnxExit(1)
   }
   const connectWait = resolveDriverConnectWaitOptions()
+  opts.signal?.throwIfAborted()
   const result = await driver.launch({
     url: openUrl,
     // the shell serves the sim page but its WS bridge may have drifted off
@@ -1925,6 +1955,8 @@ export async function runOpenCommand(
         : undefined),
     connectTimeoutMs: connectWait.hostTimeoutMs,
   })
+  if (opts.resources) opts.resources.driver = { ...result, driverId }
+  opts.signal?.throwIfAborted()
   if (!result.launched) {
     console.error(`  ${driver.name} driver: ${result.message}`)
     rnxExit(1)
@@ -1934,7 +1966,11 @@ export async function runOpenCommand(
     parsed.commandTimeoutMs,
     simMatchesToken,
     result.pid,
-    { attempts: connectWait.attempts, intervalMs: connectWait.intervalMs },
+    {
+      attempts: connectWait.attempts,
+      intervalMs: connectWait.intervalMs,
+      signal: opts.signal,
+    },
   )
   if (outcome.kind === 'host-exit') {
     printDriverDiagnosticLogTail(result)
@@ -1955,6 +1991,7 @@ export async function runOpenCommand(
     rnxExit(1)
   }
   const match = outcome.sim
+  if (opts.resources) opts.resources.simId = match.id
   saveCurrentSimId(match.id)
   signalDriverLaunchConnected(result)
   printOpenedSim(openUrl, match, `${driver.name} driver`, quiet)