sootsim 0.1.169 → 0.1.170

package/skills/sootsim-debug.md

@@ -0,0 +1,384 @@
+---
+name: sootsim-debug
+description: Debug rendering, performance, and accessibility issues in your React Native app under sootsim
+---
+
+# sootsim debug
+
+the foundational skill for "something is wrong with my app in sootsim".
+covers debugging, performance, and accessibility — three branches that
+share the same CLI primitives, the same auto-settling contract, and the
+same diff/snapshot workflow. start here for any rendering, interaction,
+event-order, or correctness question. for pixel-level rendering fidelity
+load `/sootsim-visual` instead.
+
+> needs a connected, pinned sim. if `sootsim describe` errors, load
+> `/sootsim-setup` first.
+
+## route in
+
+- "my app renders wrong / wrong props / wrong tree" → [debugging](#branch--debugging)
+- "feels slow / drops frames / janks on scroll" → [performance](#branch--performance)
+- "screen reader can't find this / wrong label / tap target too small" → [accessibility](#branch--accessibility)
+- "I want to see what just happened" (ephemeral toast, async navigation,
+  fetch + alert sequence) → [the timeline](#the-timeline-what-happened)
+- "I want pixel-level fidelity to iOS" → load `/sootsim-visual`
+- "I want to author a test" → load `/sootsim-test`
+
+## anti-patterns (apply to every branch)
+
+- **`a1`/`a2`/`b0` style ids mean sootsim sims, never browser tabs.** when a user
+  says "look at a3", that's the `sootsim list` sim id. do not open chrome
+  MCP unless the user explicitly says "use chrome" — the canvas has no
+  DOM to inspect anyway.
+- **the CLI auto-settles. don't add `sleep`.** every read waits up to
+  1800 ms for in-flight transitions to start; every write polls layout
+  hash until stable. if a read keeps racing its write, the fix is **never**
+  a blind `sleep` — it's `wait selector`, `wait ready`, `wait idle`, or
+  fixing the underlying animation-completion signal.
+- **prefer `--testid` over text matching.** text drifts under i18n, copy
+  changes, and duplicate strings. add `testID` during implementation and
+  query against it.
+- **pin a sim once.** if more than one is live, an unpinned command
+  hits the first and produces results from the wrong app. `sootsim use
+  <id>` at the start of the workflow.
+- **`debug eval` is an escape hatch.** if a top-level command feels
+  broken or missing, file an issue — every agent after you benefits from
+  a better CLI, not a pile of ad-hoc scripts.
+- **sweep `get errors` and `get requests` after every repro.** the
+  one-line summary tells you the count grew; you still have to *look at
+  them*. a "fixed" behavior with a new console error is not fixed.
+- **"found a testID" is not done.** done is: reliable repro + identified
+  root cause (specific node + prop, or event + handler) + verified fix.
+
+## the timeline ("what happened")
+
+between two CLI calls, things happen invisibly — toasts flash, keyboards
+open and close, screens push and pop, alerts fire and dismiss, async
+fetches resolve. the timeline records them so you can ask "what
+happened" instead of racing the UI with `find`.
+
+```sh
+sootsim timeline start                       # arm recording (cheap kinds default-on)
+# reproduce the flow
+sootsim what-happened                        # events since the last CLI call
+sootsim what-happened --since 10s            # absolute window
+sootsim what-happened --kinds toast,fetch    # filter to a few kinds
+sootsim what-happened --summary              # one-line counts
+sootsim what-happened --flow                 # section events by screen/route
+```
+
+semantic kinds the timeline understands: `keyboard`, `screen`, `route`,
+`alert`, `actionsheet`, `picker`, `notification`, `toast`, `scroll`,
+`gesture`, `text-input`, `reanimated`, `animation`, `fetch`, `console`,
+`app-launch`, `shell`. cheap kinds record by default; heavier kinds
+(scroll, gesture, text-input, reanimated, animation) opt in via
+`sootsim timeline start scroll,gesture,…`.
+
+every other CLI command also prints a one-line footer for events since
+the last call — that's the headline indicator. when the footer is empty,
+there's nothing new to look at; when it says `since last: 1 error · 1
+toast · 1 screen push`, run `sootsim what-happened` to see the detail.
+
+> reach for the timeline first when the question involves *something
+> that appeared briefly and disappeared*. it's faster than a screenshot
+> and tells you the duration too.
+
+## automatic settling — when you actually need a manual wait
+
+every CLI command already participates in a two-phase settle. you only
+need a manual wait when:
+
+1. the CLI explicitly printed `⚠ auto-wait timed out after Nms — next
+   command may see mid-animation state` *and* your next read depends on
+   the animation finishing.
+2. the transition is longer than ~1.2 s (full stack navigation,
+   crossfades, video first-frame, network-backed render).
+3. you want `--strict` settle, which also requires animation flags to
+   clear — only safe for apps with no perpetual background animation
+   (no pulsing dots, no shimmer, no looping Lottie).
+
+```sh
+sootsim do settle 5                # wait up to 5s for layout stability
+sootsim wait idle --max-ms 5000    # same thing under the `wait` verb
+sootsim wait idle --strict         # also require animation flags clear
+sootsim do tap-id play --no-wait   # skip auto-settle on one command
+SOOTSIM_NO_AUTO_WAIT=1 sootsim ... # disable auto-settle for a lane
+```
+
+## branch — debugging
+
+the playbook for "wrong tree / wrong props / wrong handler":
+
+```sh
+sootsim describe                         # what's on screen now
+sootsim get errors 5                     # any console smoke?
+sootsim find --testid <node>             # locate the suspect
+sootsim debug snapshot before
+# reproduce
+sootsim debug snapshot after
+sootsim debug diff before after          # structural diff: what changed?
+sootsim what-happened                    # timeline events during the repro
+```
+
+reading `describe` output:
+
+```
+[button] "Sign in" #loginButton @(0,347) 402x44 [bg:#006AFF fg:#fff] (tap)
+<text> "Forgot?" @(341,287) 55x28 [fg:#666 fontSize:14]
+```
+
+format: `[type] "text" #testID @(x,y) WxH [styles] (flags)`. coordinates
+are points (CSS pixels), origin top-left, parent-relative.
+
+for transitions, alerts, native UI, or anything spanning the shell ↔
+tenant boundary, lean on the timeline before reaching for traces:
+
+```sh
+sootsim timeline start
+# reproduce the launch / dismiss / alert
+sootsim what-happened --kinds shell,alert,screen,animation
+```
+
+you're done when:
+
+1. repro is reliable (same input → same output)
+2. root cause is identified (specific node + prop, or event + handler,
+   not "something in the navigation stack")
+3. fix re-verified through the same `snapshot → reproduce → diff` loop
+
+## branch — performance
+
+```sh
+sootsim debug perf start                  # arm capture (also clears prior frames)
+# reproduce the slow interaction
+sootsim debug perf stop                   # full report
+sootsim debug perf stop --json            # machine-readable summary
+sootsim debug perf frames                 # per-frame ring breakdown
+sootsim debug perf worst                  # the slowest frames first
+```
+
+`debug perf` output:
+
+```
+frames: 847
+total: 14123ms
+avg: 16.7ms
+max: 42ms (⚠ dropped frames)
+p95: 22.3ms
+layout frames: 123
+layout avg: 2.1ms
+```
+
+frame budget: target **8 ms / frame (120 fps)** — render <4 ms, layout
+<2 ms, JS/react <2 ms. heavier paints can fall back to the 16 ms / 60 fps
+budget. **p95 >20 ms is visible jank for a scrolling surface.**
+
+profiling a whole flow:
+
+```sh
+sootsim flow flows/scroll-feed.yaml --profile  # per-step + frame stats
+sootsim cpu-profile --duration 5 --output /tmp/trace.cpuprofile  # sampled CPU
+```
+
+common patterns → first probe:
+
+| symptom | likely | next |
+| --- | --- | --- |
+| scroll jank | layout firing during scroll | `debug enable layout` + `debug recent layout 40` |
+| anim stutter | `Animated.Value` on `width`/`height` | switch to `transform: [{ scale }]` or `translate` |
+| first-tap lag | font / image still loading | `get requests` + `debug state image` |
+| memory growth | live animation drivers not cleaned up | `debug state animations` |
+| slow initial render | many text measurements | `debug recent text` on first paint |
+
+debug channels that help, but cost 1–3 ms/frame on their own — enable
+only what you're investigating:
+
+```sh
+sootsim debug enable layout,onlayout,render,animated
+# reproduce
+sootsim debug recent layout 20            # last 20 layout events
+sootsim debug recent render 20            # last 20 draw passes
+sootsim debug disable layout,onlayout,render,animated
+```
+
+you're done when: a p95 number for the interaction + named hot path +
+remeasured (a fresh `perf start` between runs clears the buffer) and the
+number moved.
+
+watch out for:
+
+- **dynamic format strings bust the text-measurement cache.** `${count}
+  messages` re-measures every change — render the number and the word as
+  separate `<Text>` nodes.
+- **`--strict` settle hangs forever on perpetual animation.** anything
+  with a pulsing dot or looping Lottie will never go quiet under
+  `--strict`. use plain `wait idle` there.
+- **p95 over a single run is noise.** take three runs minimum.
+
+## branch — accessibility
+
+```sh
+sootsim get a11y                          # full a11y tree
+sootsim get a11y --issues                 # only nodes with problems
+sootsim describe --a11y                   # inline a11y info on every node
+```
+
+issue summary format:
+
+```
+[input] "" role=none label=null                ⚠ missing label
+[button] "➜" @(340,280) 20x20 (tap)            ⚠ touch target <44×44
+<text> "Sign in" color=#777 bg=#888            ⚠ contrast 1.4:1 (need 4.5:1)
+```
+
+finding offenders fast:
+
+```sh
+sootsim find --no-label                   # interactive nodes missing label
+sootsim find --no-role                    # interactive nodes missing role
+sootsim find --pressable --max-dim 44     # undersized tap targets
+```
+
+what gets checked:
+
+- **missing labels** — interactive nodes without `accessibilityLabel`
+- **missing roles** — `Pressable`/`Touchable` without `accessibilityRole`
+- **missing hints** — complex interactions without `accessibilityHint`
+- **touch target size** — tappable nodes with hitSlop-expanded rect <44×44
+- **contrast** — text color vs detectable background
+- **label / visible-text mismatch** — label that reads differently from
+  the text VoiceOver would fall back to (often a translation bug)
+- **duplicate labels** — two reachable nodes with identical labels on
+  one screen ("Open" + "Open" leaves no way to disambiguate)
+
+triage order:
+
+- **P0** — interactive node with no label or no role (blocks screen
+  reader entirely)
+- **P1** — tap target <44×44, duplicate labels
+- **P2** — contrast, label/visible-text mismatch
+
+fix → verify loop (the same shape as debugging):
+
+```sh
+sootsim get a11y --issues > before.txt
+# apply the fix
+sootsim get a11y --issues > after.txt
+diff before.txt after.txt
+```
+
+fixing common cases:
+
+```tsx
+// bad: icon button with no accessible name
+<Pressable onPress={onBack}>
+  <ChevronLeftIcon />
+</Pressable>
+
+// good: labeled + roled + hinted + hitSlop'd
+<Pressable
+  onPress={onBack}
+  accessibilityRole="button"
+  accessibilityLabel="Back"
+  accessibilityHint="Returns to the previous screen"
+  hitSlop={12}    // bumps tap target to 44×44 minimum
+>
+  <ChevronLeftIcon />
+</Pressable>
+
+// bad: text input with no programmatic label
+<TextInput placeholder="Email" onChangeText={setEmail} />
+
+// good: label survives even when placeholder is hidden
+<TextInput
+  placeholder="Email"
+  accessibilityLabel="Email address"
+  onChangeText={setEmail}
+/>
+```
+
+watch out for:
+
+- **placeholders are not labels.** they disappear after the user types.
+- **hitSlop expands the a11y rect too.** rarely need to make the
+  rendered button bigger — `hitSlop={12}` is usually enough.
+- **`accessibilityRole="image"` is not an `alt` tag.** pair it with
+  `accessibilityLabel` or VoiceOver reads "image" and nothing else.
+- **`importantForAccessibility="no-hide-descendants"` hides an entire
+  subtree.** useful for decorative chrome, dangerous if you forget it.
+
+run the screen reader on a real device at least once before shipping —
+labels that read fine on paper often sound robotic ("delete_message_btn_v2"
+type names sneak in).
+
+## recovery — common failure modes
+
+- **`describe` returns nothing** — no sim pinned, or the app isn't
+  loaded. load `/sootsim-setup` and re-confirm.
+- **`find` returns multiple matches** — narrow with `--testid`,
+  `--visible`, or both.
+- **`debug perf` reports zero frames** — you didn't run `perf start`
+  first, or the capture window closed before any frame committed.
+- **`get a11y --issues` returns 100+ items** — sort by P0 first; fixing
+  one label often cascades to a parent's a11y subtree.
+- **timeline footer keeps showing 1 error but `get errors` is empty** —
+  the footer reads "since last cursor advance"; `get errors` is absolute.
+  the error already scrolled out of the absolute ring buffer.
+
+## reference
+
+### finding and interacting
+
+```sh
+sootsim describe                          # all visible elements with styles
+sootsim describe button                   # filter by text/role/label/testID
+sootsim describe --testid foo             # only the subtree under a testID
+sootsim describe --verbose                # include every style property
+
+sootsim find "Sign in"                    # by text content
+sootsim find --testid loginButton
+sootsim find --role button
+sootsim find --pressable
+sootsim find --visible                    # only on-screen nodes
+
+sootsim do tap-id loginButton             # tap by testID (preferred)
+sootsim do tap-text "Submit"              # tap by text
+sootsim do tap 196 400                    # tap at coordinates
+sootsim do type "hello world"             # type into focused input
+sootsim do type-into emailInput "a@b"     # focus then type
+sootsim do key return                     # special key (return, backspace, …)
+sootsim do scroll feed-list 0 500         # scroll a testID by dx/dy
+sootsim do swipe feed-list left           # directional swipe
+sootsim do long-press messageRow 800      # ms hold
+```
+
+### errors and requests
+
+```sh
+sootsim get errors 5                      # last 5 console errors
+sootsim get warnings 5
+sootsim get requests 5                    # recent failed requests
+sootsim logs --since 30s                  # recent console output
+sootsim network --since 30s               # recent network traffic
+```
+
+### snapshots and diff
+
+```sh
+sootsim debug snapshot before
+# interact
+sootsim debug snapshot after
+sootsim debug diff before after           # added / removed / changed nodes
+```
+
+### debug channels
+
+useful: `animated`, `layout`, `onlayout`, `render`, `sheets`, `portals`,
+`gesture`, `scroll`, `text`, `image`.
+
+```sh
+sootsim debug enable animated,layout,sheets,portals
+sootsim debug recent layout 20            # last 20 events on the channel
+sootsim debug disable animated,layout,sheets,portals
+```

package/skills/sootsim-setup.md

@@ -0,0 +1,96 @@
+---
+name: sootsim-setup
+description: Get sootsim connected to your React Native app — from `npm install sootsim` to a driveable sim
+---
+
+# sootsim setup
+
+you've installed sootsim into a React Native project and want to drive it
+from the CLI. this skill takes you from zero to a connected, pinned sim
+that every other sootsim skill assumes exists. if `sootsim describe` already
+returns a tree, you're past this skill — load `/sootsim-debug` for
+debugging or `/sootsim-test` for writing tests.
+
+## anti-patterns (read first)
+
+- **never `sootsim claim --force` a sim held by another CLI.** the lease
+  exists for a reason — forcing strands the other agent and corrupts the
+  bridge state. use `sootsim open --new` to start a fresh sim instead.
+- **don't switch sims mid-investigation.** pin once with `sootsim use
+  <id>` and keep it pinned. an unpinned command hits the first sim,
+  which produces baffling results when more than one is live.
+- **an empty `sootsim list` is not "broken sootsim"** — it usually means the
+  daemon is down, the dev server port is wrong, or the runtime is missing.
+  walk the recovery checklist before reinstalling.
+
+## first move
+
+```sh
+sootsim setup                    # one-time — installs daemon, optional repo setup
+sootsim open 8081                # load a metro/expo dev server
+sootsim list                     # confirm exactly one sim is reachable
+sootsim use <id>                 # pin it for the rest of the workflow
+sootsim describe                 # smoke test — should print a render tree
+```
+
+if you do not know the port, run `sootsim open` with no target and pick from
+the detected dev servers. for hosted or unusual targets, pass the URL
+explicitly:
+
+```sh
+sootsim open 8081                # load a metro dev server
+sootsim open https://my-app.local  # load a hosted bundle
+```
+
+## you're done when
+
+- `sootsim list` shows your sim and no orphans
+- `sootsim describe` returns a render tree, not an error
+- the same sim id appears in `sootsim describe`, `sootsim find`, and
+  every subsequent command
+- `sootsim get errors 5` and `sootsim get requests 5` are quiet (or the
+  warnings are ones you understand)
+
+## recovery — common failure modes
+
+**`sootsim list` is empty.** walk this checklist in order:
+
+```sh
+sootsim daemon status            # is the bridge daemon up?
+sootsim runtime list             # is at least one engine runtime installed?
+sootsim open <port>              # does loading explicitly work?
+```
+
+if daemon is down: run `sootsim setup`, or `sootsim serve` in another shell for
+a foreground bridge. if no runtime is installed, `sootsim open` installs it
+before launching. if open errors with "port unreachable": confirm your dev
+server is actually serving — the bundler has to be up before sootsim can
+attach.
+
+**two sims appear unexpectedly.** an earlier `sootsim claim` didn't
+release on exit. close the orphan explicitly:
+
+```sh
+sootsim list                     # note the stale id
+sootsim close <id>               # release it cleanly
+```
+
+**`sootsim open` errors with "no runtime".** the engine binary isn't installed.
+Run `sootsim runtime install`, then retry `sootsim open <port>`.
+
+**bridge disconnects mid-sim.** the WebSocket dropped (laptop slept,
+network blip). re-pin: `sootsim use <id>`. the daemon retries reconnection
+automatically; you usually just need to re-issue the command.
+
+**"sim held by another CLI".** another agent or your own previous CLI
+process has the lease. find it (`sootsim list`), close it (`sootsim close
+<id>`), or start a clean sim (`sootsim open --new`) — do **not**
+`sootsim claim --force`.
+
+## related
+
+- `/sootsim-debug` — once setup is good, this is where you debug
+  rendering, performance, and accessibility issues.
+- `/sootsim-test` — write or run automated flows against the connected
+  sim.
+- `/sootsim-visual` — pixel-level rendering comparisons.