rnxsim 0.0.0 → 0.1.313

package/skills/rnx-perf/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: rnx-perf
+description: Optimize rnx engine and app performance — scroll jank, dropped frames, slow animation, idle CPU, memory growth, and "smooth normally but laggy under load" (video calls, busy machines). Covers measuring on the right thread with the right browser, proving each perf tier actually engages via its counters, a CPU-contention test harness, and the map of existing perf machinery so you improve it instead of reinventing it. For general app debugging load /rnx-debug first.
+---
+
+# rnx performance
+
+optimize performance in rnx: the shell frame pipeline, the compositor
+tiers, and the guest app. this skill exists because every real perf win in
+this engine followed the same loop — measure on the right thread, read the
+counters that prove machinery engaged, fix the one thing the counters
+indict, remeasure — and every wasted week came from skipping a step.
+
+> needs a connected, pinned sim (`/rnx-setup`). general "what's wrong"
+> triage lives in `/rnx-debug`; this skill goes deeper on perf only.
+
+## the four laws (each paid for by a real incident)
+
+1. **measure the worker that painted it, in the right browser.** the tenant
+   hasn't painted since the two-worker split, so never read a tenant sampler
+   (the one reporting `avg 0.48ms (2069 fps)` for a visibly janky scroll was
+   removed). but "the shell" is no longer the whole answer either: the
+   compositor worker owns `home`, `app:one` and `app:two`, so **every guest-app
+   draw call, paint boundary and raster-tier decision is in the compositor's
+   render profile, not the shell's.** `perf shell stop` prints both, labelled
+   by worker — read the compositor block for anything inside an app. for
+   months it printed only the shell's, and a uniswap token-list fling
+   therefore reported `raster tier: 0 promotions / 0 blits` while the
+   compositor was blitting ~14 rows a frame; the giveaway was `node visits: 7`
+   next to `app:one 1014 paints`. if a render-profile block describes a
+   handful of nodes while an app surface is painting hundreds of times, you
+   are reading the wrong worker.
+   browser matters just as much: playwright's bundled headless chromium has
+   NO GPU — CanvasKit falls back to software rendering and every number lies
+   high. launch GPU-backed Chrome via `launchReapedChrome` from
+   `scripts/lib/reap-browser`, never a bare `chromium.launch()`. never
+   `channel: 'chrome'` — that is the user's own browser, and automation
+   launching it hijacks their Dock events.
+2. **machinery silently not engaging is the default failure mode.** the
+   raster tier compiled, gated, and did *nothing* for months — zero
+   promotions on its textbook case — until per-gate rejection counters
+   existed. the frame-demand gate was blind to commit storms. the vsync
+   pump flapped 100 msgs/s at rest. never assume a tier works because it's
+   wired; read its counter during the exact workload.
+3. **check free memory and sampled CPU before blaming code.** an OOM or busy
+   machine mimics every perf and infra failure. read `vm_stat`, then take at
+   least two `top -l 2` samples and use the busiest sample for admission.
+   attribute browser processes with `ps -eo pid,ppid,args` before treating
+   one as abandoned or stopping an exact pid. load average is not an
+   admission signal on macOS.
+4. **never trade animation fidelity for CPU.** the home clock sweeps
+   sub-second like real iOS; discrete ticks have been proposed and rejected
+   repeatedly. attack per-frame cost (layers, caching, damage), never
+   cadence or fidelity.
+
+## measuring
+
+### presentation proof must stay outside the simulator
+
+Performance acceptance must not use `rnxsim record`, `liveComposite`,
+`captureBitmaps`, Chrome screencast, or another in-page frame-copy path. Those
+paths add work to the simulator or browser and can change the cadence being
+measured. Record the visible window with the operating system's native screen
+capture instead.
+
+On macOS, use the window-object recorder in `~/screen` so the simulator does
+not copy or encode its own frames:
+
+```sh
+bun ~/screen/src/cli.ts list-windows --owner "Google Chrome for Testing" --json
+bun ~/screen/src/cli.ts run --window-id <id> --duration <seconds> \
+  --out <artifact.mov> -- <operating-system input command>
+```
+
+The visual run contains only normal user input. Do not query the performance,
+debug, or test bridge while it records. Treat that video as visual evidence of
+frame progression. Collect worker paint, flush, delivery, and tier counters in
+a separate run with screen capture off. The two runs answer different questions
+without making the simulator measure its own recording overhead.
+
+Open the sim with `?debug=framestamp` to make that video machine-readable.
+Every surface paint then draws its `Date.now()` low 20 bits as a 23-cell
+barcode — `home` and `app:*` at 45% of the surface height, `shell-overlay` on
+its own row at 55% so overlay paints (keyboard, native UI) are attributable
+separately — and the decoder reports, per presented frame, which paint it
+shows and how late that paint presented:
+
+```sh
+# sim opened with ?debug=framestamp
+bun ~/screen/src/cli.ts run --window-id <id> --duration <seconds> \
+  --out <artifact.mov> -- <operating-system input command>
+bun scripts/debug/decode-framestamp.ts <artifact.mov>
+```
+
+This is the only way to separate a frame the compositor never produced from one
+it produced and the browser never presented.
+
+**Screen capture is not presentation-neutral, so the decoded timing expires.**
+Starting a ScreenCaptureKit window capture flips the 120hz `OffscreenCanvas`
+out of latest-wins presentation into sequential presentation, which falls behind
+roughly 0.5ms for every 1ms of capture. A capture started mid-activity begins
+near zero latency and climbs from there. A recording is therefore truthful about
+content and trajectory for its whole length, and truthful about timing for
+roughly its first 500ms; latency growth past that is the capture, not the
+engine. Live uncaptured presentation stays latest-wins and current. Never report
+a late-recording latency as an engine number, and never compare two recordings
+of different lengths.
+
+Worker counters and presentation are different claims, and a green counter never
+licenses a smoothness claim. A capture can report a perfect 120hz worker cadence
+for motion the user never sees move: the overscroll release shipped exactly that
+way, with the compositor stepping on schedule while the presented frames showed
+a clamped fling instead of the bounce spring. Counters prove a tier engaged;
+only a framestamp decode of an out-of-process recording proves what presented.
+
+When an external transform control is smooth but the simulator is not, inspect
+every animation on the presented element. A separate Web Animation object does
+not isolate paint work: animating `box-shadow`, `filter`, or another paint-only
+property on the transform owner can move the whole trajectory to the browser's
+main thread. Paint stable decoration once or give it a distinct layer.
+
+```sh
+rnxsim perf shell start          # arm shell frame capture (clears prior)
+# reproduce — e.g. 8 fling swipes:
+#   for i in {1..8}; do rnxsim do swipe 196 650 196 250 8 8 --no-wait; sleep 0.9; done
+rnxsim perf shell stop           # report (add --json for scripting)
+```
+
+the report and how to read it:
+
+- `painted frames / avg / p50 p95 p99 / jank` — work-per-painted-frame.
+  budget: 8ms at 120hz, 16.7ms at 60hz; p95 > 20ms is visible jank.
+- `surfaces` — per-surface layout/render/flush split. `layout` spikes on a
+  scroll capture mean shell-side yoga re-layout when virtualized rows
+  materialize (mid-fling commit), not steady-state cost.
+- `boundaries: N records / M replays` — layer compositor health. healthy
+  scroll: replays >> records, record cost near zero. records ≈ replays
+  means invalidation is defeating the cache (the SkPicture attempt-1
+  failure shape: `records: 1525, replays: 35`).
+  the `why recorded` line under it splits those records three ways, and each
+  one is a different bug: `invalidated` means something dirtied the boundary's
+  content (the usual culprit, and usually a style write that did not change a
+  value), `moved` means the boundary's record origin shifted so the cached
+  picture no longer lines up, and `first-record` is a boundary that had no
+  picture yet. a scroll dominated by `invalidated` is an invalidation bug; one
+  dominated by `first-record` is a warm-up problem, so look at whether the
+  idle pre-record reaches that content.
+- `raster tier: promotions / blits` — blits per scrolled frame > 0 or the
+  tier is not firing; `raster skips` names the first gate each candidate
+  failed (rebuild / animated / cacheable). zero blits on a feed scroll is
+  a bug, not a tuning matter — but check you are reading the compositor's
+  block first (law 1), because the shell's is legitimately zero for an app
+  workload.
+  **before widening any skip bucket, read the `also fail a later gate`
+  line under it.** the counters name only the FIRST failed gate, so a big
+  bucket can be entirely blocked a second time and unwidenable: on a uniswap
+  token-list fling all 8298 `animated` skips also carried a style transform
+  or a non-cacheable chunk, and narrowing the animated gate moved 6007 to
+  `transform` and 2350 to `cacheable` while promoting nothing. a bucket is
+  worth attacking when its also-blocked share is small.
+  and blits firing is not the same as the tier paying for itself: on the
+  uniswap token list the tier blits every visible row and costs 70MB of GPU
+  cache for no frame-time change, while the retained row boundaries under it
+  cost 2.4ms a frame. the discriminator is per-row draw density, so check
+  `draw calls` in the same block before concluding a cache is earning its
+  keep.
+- `worst frames` — read the layout/render split of each; they are usually
+  a different problem than the average.
+
+three runs minimum; single-run p95 is noise. a fresh `perf start` between
+runs clears the buffer.
+
+deeper tools when the frame report isn't enough:
+
+```sh
+rnxsim maestro test .maestro/scroll.yaml --profile # per-step + frame stats
+rnxsim perf cpu --duration 5 --output /tmp/t.cpuprofile   # sampled CPU
+rnxsim open 8089 --new --driver playwright --cdp-port 9222 # cpu-profile a driveable sim
+rnxsim debug enable layout,render && rnxsim debug recent layout 40
+```
+
+### the cadence block: frames that never happened
+
+work-per-painted-frame cannot see a frame that was never delivered — host
+rAF starved, shell worker descheduled, vsync message stuck behind a busy
+queue. the report shows low avg and zero jank while the user sees stutter.
+the `cadence` section of `perf shell stop` measures the delivery side and
+attributes a missing frame to its hop:
+
+- `display clock / host rAF interval` — stretch here (gaps >1.5x median)
+  means the page thread's rAF starved or was throttled, upstream of the
+  shell worker entirely.
+- `delivery lag` — vsync postMessage receipt latency above the run's
+  best case; jitter here means the shell worker was descheduled or its
+  queue was busy.
+- `paint interval` — the end-to-end cadence the user perceives.
+- `idle breaks` — gaps >250ms, excluded from all three: demand-gated
+  quiesce is legitimate, not starvation.
+
+compare baseline vs contended captures of the same scripted window; also
+compare **painted-frame counts**, the crudest and most robust signal.
+
+the compositor cadence lines separate worker delivery from work submitted by
+the worker:
+
+- `engine-empty rAF` includes only sustained intervals where adjacent frames
+  have no engine demand, input message, shared-slot demand epoch change,
+  paint, prewarm pass, or CanvasKit flush.
+- `rAF with CanvasKit flush` and `rAF after CanvasKit flush` isolate the frame
+  that called `Surface.flush()` and the next delivered frame.
+- `CanvasKit submission` measures intervals between final `Surface.flush()`
+  completions on frames that submitted at least one surface. The JSON
+  `frameSeries` preserves each phase flag and exact count for correlation.
+
+these are engine-owned boundaries. Playwright exposes raw CDP sessions only
+for Chromium, and WebKit's public Inspector timeline exposes a WebCore
+`Composite` record without a RemoteLayerTree transaction id or commit event.
+Do not label CanvasKit flush or compositor rAF as a RemoteLayerTree commit.
+
+## the contention harness ("smooth alone, laggy on a zoom call")
+
+low-load numbers do not predict feel under real-world CPU pressure. run the
+same scripted capture twice, once with synthetic load, self-terminating so
+it can't leak:
+
+```sh
+# 6 cores of load for 30s, self-terminating
+for i in 1 2 3 4 5 6; do
+  (perl -e 'my $end=time()+30; while(time()<$end){my $x=0; $x+=rand() for 1..10000}' &)
+done
+```
+
+compare: painted-frame count (cadence), avg/p95 (work), layout spikes. the
+diagnostic split:
+
+- **work grows under load** (avg/p95 way up) → paint path too heavy;
+  attack per-frame cost (layers, damage, raster, draw calls).
+- **work flat but frames missing** (counts drop, avg barely moves) →
+  delivery starvation: the host-rAF → postMessage → shell hop chain and
+  worker scheduling. browsers give no thread priorities, so the only
+  levers are fewer hops on the frame-critical path, less work per hop, and
+  keeping motion (scroll, native anims) as close to the paint site as
+  possible.
+- also remember GPU contention is real (video calls encode on the GPU);
+  webkit-lane numbers are Metal, chrome numbers are its GL/Metal stack.
+
+## the perf machinery map (improve, don't reinvent)
+
+every tier below exists and has a counter. before optimizing, identify
+which tier *should* absorb your cost and prove whether it does.
+
+| tier | what it absorbs | proof it engaged |
+| --- | --- | --- |
+| demand-gated frames + visibility re-marking | idle costs nothing; invisible animations quiesce | `+N skipped idle ticks`; `queryStats().needsVsync` false at rest |
+| per-surface dirty scoping | one app's commit/animation repaints only its surface | idle repaints ≈ commit rate, owning surface only |
+| dirty-tracked layout + tiered text measurement | color/opacity/transform commits skip yoga; repeated strings skip shaping | `layout: 0` on steady frames |
+| layer compositor (`paint-boundary.ts`) | animating a child never re-records ancestors | replays >> records |
+| idle boundary pre-record | the first drag replays instead of recording; cold records happen while the surface is quiet | `pre-recorded: N boundaries at idle` in the report, and the first interaction's record cost near its warm cost |
+| damage rects (`damage-rect.ts`) | repaint clips to changed region (opaque-backdrop gated) | worst-frame render bounded during small updates |
+| raster tier | stable rows become GPU textures; scroll skips recording | compositor block: promotions > 0 once warm, blits ≈ one per visible row (uniswap token list: ~13.7/frame) |
+| flood guard, pointer coalescing, vsync hysteresis | message-storm and pump-thrash protection | msgs/s sane during gestures and at rest |
+
+there is no whole-screen scroll blit. one existed for a few hours in June
+2026 and was reverted (`6706f3a014`): it shifted a surface RECTANGLE, so a
+full-surface feed with floating translucent chrome dragged its bars along with
+the content and smeared their old pixels through the feed. scroll rides the
+layer, damage, and raster machinery above instead, and any future blit has to
+own a scroll SUBTREE with provable backdrop correctness rather than a screen
+rect. do not look for `blitBlocked`; it does not exist.
+
+if a workload's cost lands in a tier that shows zero activity, the fix is
+almost always "why didn't it engage" (a gate, a shape, an eligibility
+rule), not new machinery. the area-gate fix that finally made the raster
+tier fire on feeds came entirely from rejection counters.
+
+## guest-app-side causes (fix the app, or fix the engine honestly)
+
+- dynamic format strings (`` `${n} messages` ``) bust the shaping LRU —
+  split number and label into separate `<Text>` nodes.
+- `Animated.Value` on `width`/`height` forces layout per frame — use
+  `transform` (scale/translate).
+- per-frame React work from reanimated-style code is an engine conformance
+  bug (valid worklet apps must not commit per frame) — fix rnx core,
+  never add a divergent fast-path (upstream alignment overrides perf; see
+  the `shouldFreezeOffscreenStackContent` incident).
+- render-storm loops (poll → remount) show up as commit-rate repaints and
+  RSS growth; check `debug state animations` and the timeline.
+
+## closing the loop
+
+done means: a named hot path + the counter or split that indicts it + the
+same capture re-run showing the number moved + no new errors (`get errors`)
++ nothing torn down left running (close sims you opened, kill load loops).
+for engine changes, run the rnx gate (`bun run test:sootsim:gate`) and
+screenshot-stable surfaces you touched.

package/skills/rnx-setup/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: rnx-setup
+description: Get rnx connected to your React Native app — from `rnxsim setup` to a driveable sim
+---
+
+# rnxsim setup
+
+you want to drive a React Native app with rnx from the CLI. this skill
+takes you from `rnxsim setup` to a connected, pinned sim that every other
+rnxsim skill assumes exists. no per-app rnx install is required. if
+`rnxsim describe` already
+returns a tree, you're past this skill — load `/rnx-debug` for
+debugging or `/rnx-test` for writing tests.
+
+## anti-patterns (read first)
+
+- **never `rnxsim 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 `rnxsim open --new` to start a fresh sim instead.
+- **don't switch sims mid-investigation.** pin once with `rnxsim use
+  <id>` and keep it pinned. an unpinned command refuses to choose when more
+  than one driveable sim is live.
+- **an empty `rnxsim list` is not "broken rnx".** it usually means the
+  daemon is down, the dev server port is wrong, or the runtime is missing.
+  walk the recovery checklist before reinstalling.
+- **keep one sim for your whole session.** the first `rnxsim open <port>`
+  launches Chrome for Testing with an isolated profile. later opens reuse the
+  saved sim and navigate it in place. use `rnxsim do reload` when the target
+  has not changed:
+
+  ```sh
+  rnxsim open 8086                 # first call creates your isolated sim
+  rnxsim open 8090                 # same sim, different app
+  rnxsim do reload                 # same sim, same app
+  rnxsim close <id>                # dispose it when you are done
+  ```
+
+  `--new`, `--profile`, and `--ephemeral` create another isolated browser
+  tree. use them only when separate storage or a genuinely concurrent sim is
+  required. repeated new trees consume enough memory and CPU to starve other
+  work on a shared machine.
+- **pin the sim before driving it.** `rnxsim open` records the new sim for the
+  current CLI identity. read its id and pin it explicitly before a longer flow:
+
+  ```sh
+  rnxsim open 8086
+  rnxsim list
+  rnxsim use <id>
+  rnxsim describe --sim <id>
+  ```
+
+- **never retry-loop `rnxsim open` against a wedged or slow stack.** a
+  connect timeout means diagnose the stack. do not retry. if the first launch
+  never connects, each retry can create another browser tree before there is a
+  saved sim to reuse. verify the development server and rnx runtime, then
+  retry once after fixing the cause.
+
+## first move
+
+```sh
+rnxsim setup                    # one-time guided setup; installs daemon
+rnxsim compat --json            # scan the app's native package compatibility
+rnxsim open 8081                # load a metro/expo dev server
+rnxsim list                     # confirm exactly one sim is reachable
+rnxsim use <id>                 # pin it for the rest of the workflow
+rnxsim describe                 # smoke test — should print a render tree
+```
+
+if you do not know the port, run `rnxsim open` with no target and pick from
+the detected dev servers. for hosted or unusual targets, pass the URL
+explicitly:
+
+```sh
+rnxsim open 8081                  # load a metro dev server
+rnxsim open https://my-app.local  # load a hosted bundle
+```
+
+## you're done when
+
+- `rnxsim list` shows your sim and no orphans
+- `rnxsim describe` returns a render tree, not an error
+- the same sim id appears in `rnxsim describe`, `rnxsim find`, and
+  every subsequent command
+- `rnxsim get errors 5` and `rnxsim get requests 5` are quiet (or the
+  warnings are ones you understand)
+- the compatibility scan's partial, unsupported, unknown, and version-mismatched
+  packages have been summarized without treating its aggregate score as a pass/fail gate
+
+## compatibility feedback requires approval
+
+run `rnxsim compat --json` from the app project root during setup. if the scan
+identifies a plausible missing rnx seam, or the running app gives concrete
+evidence that behavior is missing or broken specifically in rnx, summarize
+the package, expected behavior, actual behavior, and runtime evidence for the
+user. then offer to send that finding with `rnxsim report-issue`.
+
+**never submit a report automatically or behind the user's back.** wait for an
+explicit yes. only then run this from the app project root:
+
+```sh
+rnxsim report-issue --yes "<package; expected behavior; actual behavior; runtime evidence>"
+```
+
+the command automatically attaches the local compatibility scan plus bounded
+CLI, runtime, operating-system, and architecture metadata. it does not attach
+source files, environment variables, terminal output, logs, screenshots, git
+data, or app data. `--dry-run` previews the attachment summary without sending.
+do not use `--yes` merely because the agent believes a report would be useful;
+it records the user's approval after the offer.
+
+## recovery — common failure modes
+
+**`rnxsim list` is empty.** walk this checklist in order:
+
+```sh
+rnxsim daemon status            # is the bridge daemon up?
+rnxsim runtime list             # is at least one engine runtime installed?
+rnxsim open <port>              # does loading explicitly work?
+```
+
+if daemon is down: run `rnxsim setup`, or `rnxsim serve` in another shell for
+a foreground bridge. if no runtime is installed, `rnxsim 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 rnxsim can
+attach.
+
+**two sims appear unexpectedly.** an earlier `rnxsim claim` didn't
+release on exit. close the orphan explicitly:
+
+```sh
+rnxsim list                     # note the stale id
+rnxsim close <id>               # release it cleanly
+```
+
+**`rnxsim open` errors with "no runtime".** the engine binary isn't installed.
+Run `rnxsim runtime install`, then retry `rnxsim open <port>`.
+
+**`rnxsim open` times out ("timed out waiting for opened sim to connect").**
+do not retry in a loop. verify the development server first: `__soot/` must
+respond and the engine watchers must be running. inspect the driver diagnostic
+path printed by the failed command. restart the broken development stack at its
+supervisor, then retry once. rnx owns the isolated browser profile and its
+process tree; do not open the shell URL through an operating-system browser.
+
+**bridge disconnects mid-sim.** the WebSocket dropped (laptop slept,
+network blip). re-pin: `rnxsim 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 (`rnxsim list`), close it (`rnxsim close
+<id>`), or start a clean sim (`rnxsim open --new`) — do **not**
+`rnxsim claim --force`.
+
+## related
+
+- `/rnx-debug` — once setup is good, this is where you debug
+  rendering, performance, and accessibility issues.
+- `/rnx-test` — write or run automated flows against the connected
+  sim.
+- `/rnx-visual` — pixel-level rendering comparisons.