Pocketjs Devtools

Pocket DevTools

Overview

PocketJS is fixed-dt deterministic and its entire per-frame input is one button bitmask, so a recorded input tape replays any session byte-exactly. DevTools (design: repo docs/DEVTOOLS.md) is built into every bundle: a flight recorder is ALWAYS on (36 000-frame ring), and a JSON-line debug channel connects the runtime to a desktop panel over WebSocket (browser host) or the PSPLINK USB mailbox (real PSP).

Prefer the headless tape workflow for agent debugging — every question is answerable from the terminal. Use the panel when a human is co-driving.

Headless workflow (no screen needed)

Keep per-run tapes, hashes, captures, and logs in ignored output. For example:

mkdir -p .pocket-build/validation/devtools
bun run tape record hero-main --frames 180 --input "5:64,40:8192" --out .pocket-build/validation/devtools/t.json
bun run tape replay hero-main .pocket-build/validation/devtools/t.json --hashes .pocket-build/validation/devtools/h.json
bun run tape replay hero-main .pocket-build/validation/devtools/t.json --assert .pocket-build/validation/devtools/h.json --outdir .pocket-build/validation/devtools
bun run tape replay hero-main .pocket-build/validation/devtools/t.json --png 60,120 --outdir .pocket-build/validation/devtools
bun run tape tree   hero-main .pocket-build/validation/devtools/t.json --at 60
bun run tape:check                                       # committed session golden

• Input masks are contracts/spec/spec.ts BTN values (CIRCLE=0x2000=8192, DOWN=0x40=64).
• A regression workflow: record/obtain a tape on the OLD build → --hashes → switch builds → --assert names the exact first frame that changed → --png <that frame> on both builds to see the difference.
• Tapes exported from ANY host (panel "Export", or __pocketDevtools.dumpTape() in the REPL) replay headlessly. startFrame > 0 means the ring wrapped — replay is then an approximation (warned automatically).
• Committed session goldens live in tests/tapes/; regenerate hashes only when a visual change is intended.
• A replay capture or exported session is temporary validation output. Promote it to a committed fixture only when a named regression test consumes it. Put selected screenshots in PR attachments and keep raw captures, logs and receipts outside the tracked tree, following AGENTS.md/CLAUDE.md.

Panel workflow (one command)

bun run devtools            # panel + WS hub + mailbox bridge, one process
bun run devtools cards      # + build, USB-link and launch cards on a real PSP

Panel at http://127.0.0.1:8130/devtools. bun run devtools auto-detects an already-running bun psplink / bun run hw usbhostfs session and bridges into it instead of fighting for the cable (relaunch the app there so it probes the mailbox at boot). Shortcuts: o open panel, r rebuild+relaunch (managed sessions), q quit.

Panel capabilities: hover tree → highlight ON THE DEVICE SCREEN (core-drawn overlay, works on real PSP); click pins; pause/step/resume freeze the whole world; tape strip with click-to-seek (browser host reloads and deterministically fast-forwards); REPL evals in the app global scope between frames; 📷 screenshot button downloads a PNG (browser: canvas; PSP: raw VRAM dump over usbhostfs, converted by the bridge — pixels never cross the JSON channel).

Native desktop (macOS) specifics

• pocket-ui-wgpu hosts (OpenStrike desktop, engine/pocket3d/examples/uihost) carry the same file-mailbox transport as the PSP, pointed at $POCKETJS_DBG_DIR (else the process cwd). Workflow: bun run devtools --dir <root> --port 8131 FIRST (explicit --dir wins over a running PSPLINK session, so a PSP panel and a desktop panel can run side by side), then launch the app with that cwd — e.g. cargo run -p openstrike from the open-strike repo root. The app probes pocketjs-dbg/enable once at mount, like the PSP boot probe.
• Everything except 📷 screenshots works identically (desktop __dbgShot is unimplemented; the panel button logs a warning). hello reports host:"desktop" via ui.__host.

Real-PSP specifics

• Transport = pocketjs-dbg/{enable,in,out}.jsonl on the usbhostfs share (host0:). The app probes enable ONCE at boot — start the bridge before launching the app, or relaunch after. No PSPLINK → zero cost.
• Shim polls every 10 frames on PSP (~166 ms hover latency); every frame on other hosts.
• console.log on PSP: the shim installs a safe no-op console at mount (QuickJS has none) and upgrades it to a channel mirror when a transport attaches.
• PPSSPP finds the mailbox via host0: = the EBOOT's own directory (so bun run devtools <app> bridging the target dir works for PPSSPP loading that EBOOT too); the ms0: fallback also exists (memstick root).

Protocol quick reference (JSON lines)

Panel→device: inspect{id} (0 clears) · pause · resume · step · getTree · eval{id,code} · dumpTape · screenshot · seek{frame} / replay{tape} (browser host-level). Device→panel: hello{app,host,frame} · tree{root:{i,t,n,c,x,k}} · inspect{id,rect|null} · stats{frame,nodes,tapeLen,paused} · log · error{frame,message} · evalResult{id,ok,value} · tape{tape} · screenshot{frame,data}.

Gotchas

• rect: null / debugRectXY() === -1 = the node is never painted (display:none, detached, or inside a paint_3d perspective subtree — 3D interiors aren't captured; the perspective ROOT is).
• Adding spec ops: edit contracts/spec/spec.ts → bun contracts/spec/gen-rust.ts → implement on Ui + BOTH hosts (hosts/psp/src/ffi.rs, engine/wasm/src/lib.rs) + hosts/web/ wasm-ops.js + HostOps (optional members) — tests/contract.ts locks the spec halves together.
• debugName / <Named> are JS-mirror-only: provably zero pixel impact (goldens + tape hashes unchanged). Name every function component's root element; the tree panel and tape tree output read like the source.
• Shim tests live in tests/devtools.test.ts (mock ops + in-process transport; --conditions=browser required). Core pause/inspect tests in engine/core/src/tests.rs.
• Missing QuickJS symbols (vendored libquickjs-sys is minimal): declare a local extern "C" block — precedent in hosts/psp/src/main.rs and ffi.rs.
• NEVER hand VRAM addresses (0x4xxxxxxx uncached mirror) to usbhostfs IO: its send path runs dcache writeback + USB bulk DMA on the caller's buffer and hangs the device on the first 64 KB block (frozen PSP, 0-byte file). Bounce through a cached-RAM buffer in chunks (dbg::shot). ms0: (Memory Stick driver) tolerates VRAM-direct writes — that's why cap_dump_frame gets away with it and why PPSSPP won't reproduce the hang.
• The GE writes framebuffer alpha as 0: any raw-framebuffer consumer must force alpha opaque (bridge convertShot, e2e's -alpha off) or the PNG renders fully transparent.
• When hardware behavior "mysteriously regresses" after running e2e scripts, check WHICH build is on disk before debugging anything else: e2e capture specs rebuild the EBOOT/PRX in place, and capture builds sceKernelExitGame() after their window — reloading one on the PSP looks exactly like a freeze/hang a few seconds after boot. Rebuild your intended feature set first; only then trust symptoms. (Cost an hour on the OpenStrike bring-up: a phantom "mailbox freeze" was a self-exiting e2e build the whole time.)
• The whole device-side path (eval, console, screenshot) is testable without hardware, at host0: fidelity: PPSSPP maps the EBOOT's own directory as host0:, so a mailbox in hosts/psp/target/mipsel-sony-psp/debug/pocketjs-dbg/ is found by the SAME probe hardware uses. Create enable/in/out there, run PPSSPPHeadless with a timeout, append commands to in.jsonl mid-run, read out.jsonl. (This also means a stale hardware-session mailbox hijacks emulator runs — tests/e2e/ppsspp.ts removes it before each golden run.)