sootsim

CLI + framework plugins for soot's iOS simulator.

this package is the public, publishable face of sootsim. it contains:

• sootsim CLI (bridge client — drives a running sootsim instance over WebSocket for describing UI, tapping elements, recording flows, etc.)
• sootsim/vite — vite plugin for wrapping an app bundler with sootsim
• sootsim/metro — metro plugin for wrapping a react native bundler
• sootsim/skills — registry for soot-flavored automation skills

the rendering engine itself (canvas renderer, yoga layout, ios shell, wasm, electron shell) lives in the private sootsim-engine workspace package and is not published.

getting started

npm i -g sootsim
cd my-app && sootsim setup-repo
sootsim open 8081          # load a running metro/expo dev server

that's the canonical path — CLI first. the bridge daemon registers itself on first use; you don't need to run anything to install it. a desktop GUI (Electron) is optional on top of that, see sootsim install-desktop.

CLI

the CLI is the primary debugging surface for sootsim. use it first for runtime inspection, interaction, animation debugging, shell tracing, screenshots, and flow capture instead of treating it as a test-only tool.

bun sootsim list              # connected tabs
bun sootsim open 8081         # load a running metro/expo dev server
bun sootsim describe          # dump UI tree
bun sootsim get errors 5      # recent runtime failures
bun sootsim find --testid cta # inspect one node deeply
bun sootsim debug enable animated,layout
bun sootsim debug trace shell on 240
bun sootsim do tap-text "..." # interact
bun sootsim debug snapshot before
bun sootsim debug snapshot after
bun sootsim debug diff before after
bun sootsim flow start        # begin a draft
bun sootsim flow keep         # persist the last action
bun sootsim flow end --output flows/login.yaml
bun sootsim test --detox      # shared Detox-style parity suite against sootsim

see the full command reference via bun sootsim --help or at src/features/site/docs/sootsim/cli/ in the soot repo.

coming from detox

sootsim ships a drop-in detox driver. your existing detox test files (import { by, element, expect, device } from 'detox') run against sootsim with no code changes — just add one line to your jest config:

// jest config
{ preset: 'sootsim/detox/jest-preset' }

or use the CLI directly:

bun sootsim detox            # auto-discovers e2e/ tests and launches a shell
bun sootsim detox init       # scaffold a config + sample test

see docs/migrating-from-detox.md for details.

coming from maestro

sootsim's flow runner natively speaks maestro's YAML format. point it at your existing .maestro/ directory:

bun sootsim maestro                      # discover .maestro/ and run all flows
bun sootsim maestro test .maestro/       # explicit
bun sootsim maestro --list-compat        # see the verb support matrix

most maestro verbs work out of the box (tapOn, assertVisible, inputText, scrollUntilVisible, launchApp, when:, repeat, runFlow, …). verbs that need real device hardware (GPS, radio, photo library) throw a clear error.

see docs/migrating-from-maestro.md for the full compat matrix.

for animation-heavy debugging, the useful path is usually:

bun sootsim debug enable animated
bun sootsim debug trace shell on 240
bun sootsim debug snapshot before
# reproduce the transition
bun sootsim debug snapshot after
bun sootsim debug diff before after
bun sootsim screenshot --with-frame --output /tmp/sootsim-framed.png
bun sootsim record --duration 5 --output /tmp/sootsim-anim.mp4

sootsim screenshot --with-frame composes the real sootsim shell device chrome around the raw screen bitmap. it reuses the shell bezel/button geometry and still excludes the electron top bar, rail gutter, and other window chrome.

flows can use the same framed export path without changing normal maestro syntax:

- takeScreenshot: hero
- takeScreenshot:
    path: marketing/hero
    withFrame: true

for plan-driven app-store exports, use sootsim screenshots:

app: 8081
device: iphone-14

capture:
  flow: .maestro/capture-app-store-screenshots.yaml
  mode: raw+framed

compose:
  canvases: [iphone-6-9, iphone-6-1]
  background: cyan
  text:
    preset: bold-top
  slides:
    - id: splash-hero
      screenshot: apple/iphone/en/01-splash.png
      headline: First punch.
      subheadline: Every pick in one place.

bun sootsim screenshots --plan .sootsim/app-store.yaml

the plan runner can reuse a visible session for capture (--session tab-9), stop after raw/framed intermediates (--capture-only), or rerender final marketing canvases from an existing raw directory (--compose-only).

if your flow already writes screenshots to explicit project paths, set:

capture:
  flow: .maestro/capture-app-store-screenshots.yaml
  from: ./apps/app-store-screenshots/public/screenshots/apple/iphone/en
  pathMode: flow

that tells sootsim screenshots to respect the flow's own takeScreenshot paths instead of prepending --screenshots <rawDir>.

in the browser shell, Screenshot Mode now turns the live shell into a simple DOM composition surface: the rail + mac menu bar disappear, the device shifts down with a short transition, and editable title/subtitle fields appear above the frame for quick art-direction passes.

registry and docs source of truth

the published CLI registry and the generated website docs both come from packages/sootsim-skills/.

• packages/sootsim/cli/registry.ts re-exports the shared CLI metadata
• packages/sootsim/skills/soot.md is generated from that registry
• src/features/site/docs/sootsim/cli/* is generated output, not hand-edited source

when command docs or examples drift, update packages/sootsim-skills/ and run:

bun run generate:sootsim-docs

usage in a framework

// vite.config.ts
import { sootsimPlugin } from 'sootsim/vite'

export default {
  plugins: [sootsimPlugin()],
}

// metro.config.js
const { withSootsim } = require('sootsim/metro')

module.exports = withSootsim({ /* your metro config */ })

development

this package is part of the soot monorepo. to build the CLI bundle:

bun run build:cli

the output is dist-cli/bin.js, a single esbuild output that gets published as the sootsim npm bin.