rnxsim 0.1.313 → 0.1.315

package/cli/commands/inspect/count.ts

@@ -0,0 +1,17 @@
+// `sootsim get count` — total SootSimNode count in the live tree.
+
+import { inspectNodeCount } from './core'
+import { printJson, wantsJson } from './shared'
+import type { WsBridge } from '../../ws-bridge'
+
+export async function runCountSubcommand(
+  bridge: WsBridge,
+  opts: { args: string[] } = { args: [] },
+): Promise<void> {
+  const result = await inspectNodeCount(bridge)
+  if (wantsJson(opts.args)) {
+    printJson(result)
+    return
+  }
+  console.log(`  nodes: ${result.nodes}`)
+}

package/cli/commands/inspect/describe.ts

@@ -0,0 +1,192 @@
+// `sootsim describe` — dump the visible-UI tree with layout + style annotations.
+//
+// see packages/sootsim-engine/src/test-bridge.ts for the actual dumpTree impl
+// that powers this. the CLI-side job is just: optional preflight for in-flight
+// screen transitions, call dumpTree with the right flags, and pretty-print.
+
+import { maybeHint } from '../../hints'
+import { inspectDescribe, type DescribeDumpOptions } from './core'
+import {
+  maybeWaitForStartedScreenTransitions,
+  printJson,
+  sleep,
+  wantsJson,
+} from './shared'
+import type { WsBridge } from '../../ws-bridge'
+
+export interface DescribeOptions {
+  bridge: WsBridge
+  args: string[]
+  positional: string[]
+}
+
+function flagValue(args: string[], name: string): string | null {
+  const i = args.indexOf(name)
+  return i >= 0 && i + 1 < args.length ? args[i + 1] : null
+}
+
+export async function runDescribeSubcommand(opts: DescribeOptions): Promise<void> {
+  const { bridge, args, positional } = opts
+  const verbose = args.includes('--verbose') || args.includes('-v')
+  const jsonOut = wantsJson(args)
+  const verboseDescribeTransitions = verbose && !jsonOut
+  const watch = args.includes('--watch') || args.includes('-w')
+  const watchInterval = 1000
+  const compact = args.includes('--compact')
+  const hideXy = args.includes('--no-xy')
+  // when set, strip rows annotated `(clipped:left|right|top|bottom)` from the
+  // output. dumpTree marks anything that overflows the viewport so search
+  // context is preserved, but the rows balloon the output on screens like
+  // 3pc's profile (off-screen list items + edge-pulled chrome). this flag is
+  // a client-side filter so we don't need a roundtrip to dumpTree.
+  const hideClipped = args.includes('--no-clipped')
+  // by default describe hides nodes that sit fully behind a modal/sheet/popover
+  // scrim — they aren't reachable, and listing them as `(tap)` misleads agents
+  // into tapping content that's actually occluded. --include-occluded surfaces
+  // them annotated `(behind)`.
+  const includeOccluded = args.includes('--include-occluded')
+
+  const testIdLike = flagValue(args, '--testid-like')
+  const onlyGlob = flagValue(args, '--only')
+  const subtreeRoot = flagValue(args, '--subtree')
+
+  // bare positional still works — routes to --only if it looks globby,
+  // otherwise preserves the old substring-match behavior as `filter`. guard
+  // against a flag-looking token leaking in as a filter: an unrecognized
+  // `--flag` that the arg parser didn't strip must never become a text filter
+  // (that's how `describe --compact` used to match nothing).
+  const positionalFilter =
+    positional[1] && !positional[1].startsWith('-') ? positional[1] : undefined
+  const bareIsGlob = positionalFilter ? /[*?]/.test(positionalFilter) : false
+  const filter = !bareIsGlob && !onlyGlob ? positionalFilter : undefined
+  const effectiveOnlyGlob = onlyGlob ?? (bareIsGlob ? positionalFilter : undefined)
+
+  const runOnce = async () => {
+    await maybeWaitForStartedScreenTransitions(bridge, {
+      verbose: verboseDescribeTransitions,
+    })
+    const dumpOpts: DescribeDumpOptions = {
+      describe: true,
+      verbose,
+      filter: filter || '',
+      testIdLike: testIdLike || undefined,
+      onlyGlob: effectiveOnlyGlob || undefined,
+      subtreeRoot: subtreeRoot || undefined,
+      compact,
+      hideXy,
+      includeOccluded,
+      // no terminal to fit, so nothing gets clipped on the way out
+      fullText: jsonOut,
+    }
+    const result = await inspectDescribe(bridge, dumpOpts)
+    const tree = result?.tree
+    const shell = result?.shell
+    const keyboard = result?.keyboard
+
+    if (jsonOut) {
+      printJson({ shell, tree: tree ?? '', keyboard })
+      return
+    }
+
+    // show shell state in header if available
+    if (shell && typeof shell === 'object') {
+      const shellParts = [
+        shell.state ? `state=${shell.state}` : null,
+        shell.activeApp ? `app=${shell.activeApp}` : null,
+        shell.showSwitcher ? 'switcher' : null,
+        shell.switcherPhase && shell.switcherPhase !== 'idle'
+          ? `phase=${shell.switcherPhase}`
+          : null,
+      ].filter(Boolean)
+      if (shellParts.length > 0) {
+        console.log(`  shell: ${shellParts.join(' ')}`)
+      }
+    }
+
+    if (typeof tree === 'string' && tree.startsWith('__SUBTREE_NOT_FOUND__:')) {
+      const missing = tree.slice('__SUBTREE_NOT_FOUND__:'.length)
+      console.log(`  subtree root not found: ${missing}`)
+      maybeHint('subtree-root-not-found', missing)
+      return
+    }
+
+    if (!tree) {
+      const nodeCount = result?.nodeCount ?? 0
+      console.log('  no matching nodes found')
+      const anyFilterActive = filter || testIdLike || effectiveOnlyGlob || subtreeRoot
+      if (!anyFilterActive && nodeCount < 10) {
+        maybeHint('app-still-loading', nodeCount)
+      }
+      return
+    }
+
+    let rendered = tree
+    let hiddenClippedCount = 0
+    if (hideClipped && typeof rendered === 'string') {
+      const lines = rendered.split('\n')
+      const kept: string[] = []
+      for (const line of lines) {
+        if (line.includes('(clipped:')) {
+          hiddenClippedCount += 1
+          continue
+        }
+        kept.push(line)
+      }
+      rendered = kept.join('\n')
+    }
+    console.log(rendered)
+    if (hiddenClippedCount > 0) {
+      console.log(
+        `  ${hiddenClippedCount} clipped row(s) hidden (omit --no-clipped to see)`,
+      )
+    }
+
+    const anyFilterActive = filter || testIdLike || effectiveOnlyGlob || subtreeRoot
+    const searchFilterActive = filter || testIdLike || effectiveOnlyGlob
+    if (searchFilterActive && !watch) {
+      maybeHint('describe-filter-context')
+    }
+
+    // when no filter was active and the tree got long, nudge once per
+    // session toward the narrowing flags — this is exactly the case the
+    // user flagged where "which row is the swap sheet" got buried under
+    // 100+ lines of home content.
+    if (!anyFilterActive && !watch) {
+      const lineCount = tree.split('\n').length
+      if (lineCount >= 80) {
+        maybeHint('describe-use-filters')
+      }
+    }
+
+    // keyboard summary — only when visible. rendered as a footer so it
+    // doesn't bury the tree on forms with non-trivial UI above the input.
+    if (keyboard && keyboard.visible) {
+      const spec = keyboard.spec
+      const kbParts = [
+        spec?.keyboardType ? `type=${spec.keyboardType}` : null,
+        spec?.returnKeyType && spec.returnKeyType !== 'default'
+          ? `return=${spec.returnKeyType}`
+          : null,
+        keyboard.mode !== 'letters' ? `mode=${keyboard.mode}` : null,
+        keyboard.shifted ? 'shift' : null,
+        keyboard.capsLock ? 'caps' : null,
+        spec?.autoCapitalize && spec.autoCapitalize !== 'sentences'
+          ? `autoCap=${spec.autoCapitalize}`
+          : null,
+        keyboard.accessoryBarId ? `accessory=${keyboard.accessoryBarId}` : null,
+      ].filter(Boolean)
+      console.log(`\n  keyboard: ${kbParts.join(' ') || 'visible'}`)
+    }
+  }
+
+  if (watch) {
+    console.log('  watching... (Ctrl+C to stop)\n')
+    while (true) {
+      console.clear()
+      await runOnce()
+      await sleep(watchInterval)
+    }
+  } else {
+    await runOnce()
+  }
+}

package/cli/commands/inspect/env.ts

@@ -0,0 +1,23 @@
+// env vars that indicate the CLI is being driven by an agent/automation rather
+// than a human at a terminal. when any is present, auto-waits get a longer
+// budget and log more aggressively, because an agent can't see mid-animation
+// flicker the way a human can.
+const AGENT_ENV_VARS = [
+  'SOOTSIM_AGENT',
+  'TM_SESSION',
+  'CLAUDECODE',
+  'CLAUDE_CODE_ENTRYPOINT',
+  'CLAUDE_CODE_SESSION_ID',
+  'CODEX_THREAD_ID',
+  'CURSOR_TRACE_ID',
+  'AIDER_MODEL',
+]
+
+export function isAgentEnv(): boolean {
+  if (process.env.SOOTSIM_AGENT === '0') return false
+  for (const name of AGENT_ENV_VARS) {
+    const v = process.env[name]
+    if (v && v.trim() && v !== '0') return true
+  }
+  return false
+}

package/cli/commands/inspect/find.ts

@@ -0,0 +1,171 @@
+import { maybeHint } from '../../hints'
+import { inspectFind, rankInteractive, tapCommandForNode } from './core'
+import { printJson, wantsJson } from './shared'
+import type { WsBridge } from '../../ws-bridge'
+
+// unified finder: one verb for text/testid/role/type/pressable/visible.
+// --testid (not --id) keeps element lookup distinct from target selection.
+// mode resolution + the evaluated JS live in inspect/core.ts (shared with the
+// agent); this handler only parses flags and formats the result for the CLI.
+export async function runFindSubcommand(opts: {
+  bridge: WsBridge
+  args: string[]
+  effectiveArgs: string[]
+  positional: string[]
+  inspectUsage: (name: string, tail: string) => string
+}): Promise<void> {
+  const { bridge, args, effectiveArgs, positional, inspectUsage } = opts
+
+  const findFlag = (name: string): string | null => {
+    const i = effectiveArgs.indexOf(name)
+    return i >= 0 && i + 1 < effectiveArgs.length ? effectiveArgs[i + 1] : null
+  }
+  const hasFlag = (name: string): boolean => effectiveArgs.includes(name)
+
+  const testId = findFlag('--testid') || findFlag('--test-id')
+  const role = findFlag('--role')
+  const typeFlag = findFlag('--type')
+  const textFlag = findFlag('--text')
+  const pressable = hasFlag('--pressable')
+  const visible = hasFlag('--visible')
+  // ranked-tappable list — same data source as --pressable, but the
+  // output prioritises high-signal targets the agent likely wants to
+  // tap next (visible, has text or testID, has accessibilityLabel),
+  // and emits a copy-paste `sootsim do` command per row so the agent
+  // doesn't have to re-form a tap from raw fields.
+  const interactive = hasFlag('--interactive-targets') || hasFlag('--actions')
+  const bareText =
+    !testId && !role && !typeFlag && !textFlag && !pressable && !visible && !interactive
+      ? positional[1]
+      : null
+  const textQuery = textFlag ?? bareText
+
+  const found = await inspectFind(bridge, {
+    testId,
+    role,
+    type: typeFlag,
+    text: textQuery,
+    pressable,
+    visible,
+    interactive,
+  })
+  if (!found) {
+    console.error(
+      inspectUsage(
+        'find',
+        '<text> | --text <t> | --testid <id> | --role <r> | --type <t> | --pressable | --visible | --interactive-targets',
+      ),
+    )
+    process.exit(1)
+  }
+  const { mode, result } = found
+  const jsonOut = wantsJson(args)
+  // --verbose / --dump: emit full node JSON per result instead of just the
+  // one-line summary. the default summary is compact for scannability; when
+  // you already know the match and need to copy testID / layout / a11y
+  // props, --verbose saves the round-trip through `get node <id>`.
+  const verbose = args.includes('--verbose') || args.includes('--dump')
+
+  if (jsonOut) {
+    if (mode === 'interactive-targets' && Array.isArray(result)) {
+      // include the `tap` command per row when emitting JSON for agents
+      // — the human renderer does the same. tooling that drives sootsim
+      // can pick the highest-scored entry and execute its `tap` field.
+      printJson(rankInteractive(result).map((n) => ({ ...n, tap: tapCommandForNode(n) })))
+    } else {
+      printJson(result ?? null)
+    }
+  } else if (Array.isArray(result)) {
+    if (result.length === 0) {
+      console.log(`  no ${mode} nodes found`)
+      const nodeCount = await bridge.send({
+        type: 'evaluate',
+        code: '(async () => (await window.__sootsimTest?.getNodeCount?.()) || 0)()',
+      })
+      if (typeof nodeCount === 'number' && nodeCount < 10) {
+        maybeHint('app-still-loading', nodeCount)
+      }
+    } else if (mode === 'interactive-targets') {
+      const ranked = rankInteractive(result)
+      console.log(
+        `  found ${ranked.length} interactive target${ranked.length === 1 ? '' : 's'} (sorted by score):`,
+      )
+      for (const n of ranked.slice(0, 20)) {
+        const loc = n.absolutePosition
+          ? `@(${Math.round(n.absolutePosition.x)},${Math.round(n.absolutePosition.y)})`
+          : ''
+        const size = n.layout
+          ? `${Math.round(n.layout.width)}x${Math.round(n.layout.height)}`
+          : '?x?'
+        const text = n.text ? ` "${n.text.slice(0, 30)}"` : ''
+        const tid = n.testID ? ` #${n.testID}` : ''
+        const label = n.accessibilityLabel
+          ? ` ⓘ"${String(n.accessibilityLabel).slice(0, 24)}"`
+          : ''
+        const roleName = n.accessibilityRole ? `[${n.accessibilityRole}]` : n.type
+        const tapCmd = tapCommandForNode(n)
+        console.log(`    ${roleName}${text}${label}${tid} ${size} ${loc}`)
+        console.log(`      → ${tapCmd}`)
+        if (verbose) console.log(indent(JSON.stringify(n, null, 2), '      '))
+      }
+      if (ranked.length > 20) console.log(`    ... and ${ranked.length - 20} more`)
+    } else {
+      console.log(
+        `  found ${result.length} node${result.length === 1 ? '' : 's'} (${mode}):`,
+      )
+      for (const n of result.slice(0, 20)) {
+        const loc = n.absolutePosition
+          ? `@(${Math.round(n.absolutePosition.x)},${Math.round(n.absolutePosition.y)})`
+          : ''
+        const size = n.layout
+          ? `${Math.round(n.layout.width)}x${Math.round(n.layout.height)}`
+          : '?x?'
+        const text = n.text ? ` "${n.text.slice(0, 30)}"` : ''
+        const tid = n.testID ? ` #${n.testID}` : ''
+        const tap = n.pressable ? ' (tap)' : ''
+        const roleName = n.accessibilityRole ? `[${n.accessibilityRole}]` : n.type
+        console.log(`    ${roleName}${text}${tid} ${size} ${loc}${tap}`)
+        if (verbose) console.log(indent(JSON.stringify(n, null, 2), '      '))
+      }
+      if (result.length > 20) console.log(`    ... and ${result.length - 20} more`)
+    }
+  } else if (result == null) {
+    const query = textQuery || testId || role || typeFlag || ''
+    console.log(`  not found: ${query || mode}`)
+    if (testId) {
+      maybeHint('wait-selector-for-missing-testid', testId)
+    }
+  } else {
+    interface InspectNode {
+      type?: string
+      absolutePosition?: { x: number; y: number }
+      layout?: { width: number; height: number }
+      text?: string
+      testID?: string
+      pressable?: boolean
+      accessibilityRole?: string
+    }
+    const n = result as InspectNode
+    if (n.type && n.absolutePosition) {
+      const loc = `@(${Math.round(n.absolutePosition.x)},${Math.round(n.absolutePosition.y)})`
+      const size = n.layout
+        ? `${Math.round(n.layout.width)}x${Math.round(n.layout.height)}`
+        : '?x?'
+      const text = n.text ? ` "${n.text.slice(0, 40)}"` : ''
+      const tid = n.testID ? ` #${n.testID}` : ''
+      const tap = n.pressable ? ' (tap)' : ''
+      const roleName = n.accessibilityRole ? `[${n.accessibilityRole}]` : n.type
+      console.log(`  ${roleName}${text}${tid} ${size} ${loc}${tap}`)
+      if (verbose) console.log(indent(JSON.stringify(n, null, 2), '    '))
+    } else {
+      console.log(JSON.stringify(result, null, 2))
+    }
+  }
+}
+
+function indent(text: string, prefix: string): string {
+  return text
+    .split('\n')
+    .map((line) => prefix + line)
+    .join('\n')
+}

package/cli/commands/inspect/get-layout.ts

@@ -0,0 +1,39 @@
+// `sootsim get-layout` — bounding boxes for visible meaningful elements on the
+// current screen. focused on the layout numbers a designer checks: on-screen
+// box (x/y/w/h). pass --styling for computed borderRadius, per-side padding,
+// fontSize, visual style fields, and native rendered text contrast. pass
+// --filter <text> to narrow to the elements whose text/testID/role/selector
+// match — fewer rows, full detail on each, which is how you read one area's
+// styling without the whole screen.
+//
+// the extraction + formatting live in the shared `./core` kernel
+// (inspectGetLayout / formatLayoutElements) so this CLI command and the agent's
+// app_get_layout tool produce identical output. the CLI-side job is just:
+// optional preflight for in-flight screen transitions, call the kernel, print.
+
+import { formatLayoutElements, inspectGetLayout } from './core'
+import { maybeWaitForStartedScreenTransitions, printJson, wantsJson } from './shared'
+import type { WsBridge } from '../../ws-bridge'
+
+export async function runGetLayoutSubcommand(opts: {
+  bridge: WsBridge
+  args: string[]
+}): Promise<void> {
+  const { bridge, args } = opts
+  const jsonOut = wantsJson(args)
+  await maybeWaitForStartedScreenTransitions(bridge, { verbose: !jsonOut })
+  const styling = args.includes('--styling')
+  const filterIndex = args.indexOf('--filter')
+  const filter = filterIndex >= 0 ? args[filterIndex + 1] : undefined
+  const elements = await inspectGetLayout(bridge, { styling, filter })
+  if (jsonOut) {
+    printJson({ count: elements.length, elements })
+    return
+  }
+  console.log(
+    `  layout (${elements.length} element${elements.length === 1 ? '' : 's'}):\n`,
+  )
+  // styling fields (including native rendered text contrast) are opt-in via
+  // --styling so the default inspect output stays scannable.
+  console.log(formatLayoutElements(elements, { styling }))
+}

package/cli/commands/inspect/keyboard.ts

@@ -0,0 +1,52 @@
+// `sootsim get keyboard` — prints the current iOS keyboard's full state.
+//
+// shows visibility, keyboardType, returnKeyType, autoCapitalize policy,
+// active QWERTY sub-mode, shift + capsLock, and the mounted accessory bar
+// id (if any). reads from `__sootsimKeyboard.getLayout()`, which is
+// populated by shell-worker `keyboard.layout` broadcasts.
+
+import { inspectKeyboard } from './core'
+import type { WsBridge } from '../../ws-bridge'
+
+export async function runKeyboardSubcommand(
+  bridge: WsBridge,
+  opts: { json?: boolean } = {},
+): Promise<void> {
+  const result = await inspectKeyboard(bridge)
+
+  if ('error' in result) {
+    console.error(result.error)
+    process.exit(1)
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2))
+    return
+  }
+
+  const { visible, spec, mode, shifted, capsLock, accessoryBarId } = result
+  const lines: string[] = []
+  lines.push(`keyboard: ${visible ? 'visible' : 'hidden'}`)
+  if (spec) {
+    lines.push(`  type:          ${spec.keyboardType}`)
+    lines.push(`  returnKey:     ${spec.returnKeyType}`)
+    lines.push(`  autoCap:       ${spec.autoCapitalize}`)
+    lines.push(`  autoCorrect:   ${spec.autoCorrect ? 'on' : 'off'}`)
+    lines.push(`  appearance:    ${spec.keyboardAppearance}`)
+    if (spec.secureTextEntry) lines.push(`  secureTextEntry: true`)
+    if (spec.enablesReturnKeyAutomatically) {
+      lines.push(
+        `  return:        ${spec.currentTextIsEmpty ? 'disabled (empty)' : 'enabled'}`,
+      )
+    }
+  } else {
+    lines.push(`  spec:          <none> (shown via dev-tools with no TextInput)`)
+  }
+  lines.push(
+    `  mode:          ${mode}${shifted ? ' (shifted)' : ''}${capsLock ? ' (caps)' : ''}`,
+  )
+  if (accessoryBarId) {
+    lines.push(`  accessoryBar:  ${accessoryBarId}`)
+  }
+  console.log(lines.join('\n'))
+}

package/cli/commands/inspect/list.ts

@@ -0,0 +1,58 @@
+// `sootsim list` — connected sims, with the active one marked.
+
+import { printConnectedSims } from '../control'
+import { printJson, wantsJson } from './shared'
+import type { WsBridge } from '../../ws-bridge'
+
+export async function runListSubcommand(opts: {
+  bridge: WsBridge
+  simId: string | undefined
+  args: string[]
+}): Promise<void> {
+  const sims = await opts.bridge.listSims()
+
+  // filter sims:
+  //   --all                       show every sim including empty shells (default
+  //                               hides sims that have no bundle URL — they're
+  //                               usually idle host shells that overflow the
+  //                               list when several demos are open at once)
+  //   --bundle <substring>        only sims whose loaded url contains the substring
+  //   --app-port <port>           shorthand for `--bundle :<port>/`. NOT `--port`
+  //                               which is taken by the global bridge-port flag
+  //                               (see ws-bridge.ts parseBridgeCliArgs) — using
+  //                               --port here used to silently set the bridge
+  //                               port too, sending the WS connect to the wrong
+  //                               place and failing with "daemon is not running"
+  //   --primary                   only the primary sim
+  const showAll = opts.args.includes('--all')
+  const bundleArg = opts.args.find((_, i) => opts.args[i - 1] === '--bundle')
+  const portArg = opts.args.find((_, i) => opts.args[i - 1] === '--app-port')
+  const primaryOnly = opts.args.includes('--primary')
+  const filtered = sims.filter((sim) => {
+    if (primaryOnly && !sim.isPrimary) return false
+    if (bundleArg && !(sim.url ?? '').includes(bundleArg)) return false
+    // a sim url looks like `http://localhost:5173/rn/8085?bundle=...` where
+    // `8085` is the metro/vite port the app is loaded from. the bundle url
+    // inside the `?bundle=` param is itself percent-encoded (`:8085/` ->
+    // `%3A8085%2F`), so the previous literal `:${port}/` substring check
+    // never matched. match the canonical `/rn/<port>` path segment instead.
+    if (portArg && !(sim.url ?? '').includes(`/rn/${portArg}`)) return false
+    if (!showAll && !bundleArg && !portArg && !primaryOnly) {
+      // hide host shells (no bundle loaded — only origin) unless they're
+      // the currently-selected sim
+      const hasBundle =
+        sim.url && (sim.url.includes('bundle=') || sim.url.includes('/index.bundle'))
+      if (!hasBundle && sim.id !== opts.simId) return false
+    }
+    return true
+  })
+
+  if (wantsJson(opts.args)) {
+    printJson(filtered.map((b) => ({ ...b, active: b.id === opts.simId })))
+    return
+  }
+  printConnectedSims(filtered, opts.simId)
+  if (filtered.length < sims.length && !wantsJson(opts.args)) {
+    console.log(`  (${sims.length - filtered.length} more hidden — pass --all to show)`)
+  }
+}