romdevtools 0.40.2 → 0.41.0

package/src/platforms/_guides/ROMHACKING_PLAYBOOK.md

@@ -334,14 +334,27 @@ what touches an address). The **Rizin/Ghidra analysis engine** carves the progra
   scan misses. Use it to answer "what calls this routine / reads this table?"
 - **`disasm({target:'decompile', path, address})`** — Ghidra **C-like pseudocode**
   for a function. Read it to UNDERSTAND a routine fast; it is NOT the edit path
-  (use `target:'project'`, §7b, to change and rebuild). Quality tracks the CPU —
-  see the `qualityNote` it returns: excellent on ARM (GBA) / 68000 (Genesis),
-  good on SM83 (GB) / Z80 (SMS/GG/MSX), medium on 65816 (SNES) / HuC6280 (PCE),
-  rough on the 6502 family (carry-flag idioms and 16-bit-math-on-8-bit decompile
-  to noise — read the disassembly there, or let an LLM fold the pseudocode).
+  (use `target:'project'`, §7b, to change and rebuild). Hardware-register MMIO is
+  NAMED (`PPUMASK` not `*0x2001`) and on the 6502 family SLEIGH clutter is folded
+  to readable C99 (`uint8_t`, `zp_FD`) — see the `/* hw registers: … */` /
+  `/* 6502 fold: … */` legends. Quality tracks the CPU — see the `qualityNote` it
+  returns: excellent on ARM (GBA) / 68000 (Genesis), good on SM83 (GB) / Z80
+  (SMS/GG/MSX), medium on 65816 (SNES) / HuC6280 (PCE), rough on the 6502 family
+  (carry-flag idioms and 16-bit-math-on-8-bit decompile to noise — read the
+  disassembly there, or let an LLM fold the residual pseudocode).
+- **`breakpoint({on:'jumptable', address})`** — when a routine decompiles to
+  `(*_IRQ)()` + "Could not recover jumptable" (the computed-jump dispatchers —
+  state machines, script/battle VMs — that static analysis structurally can't
+  follow), RESOLVE it live: this breaks at the dispatcher in the running emulator,
+  single-steps through the indirect `JMP (table,X)` / RTS-trick, and returns the
+  COMPUTED targets it actually lands on. Drive more game states (`pressDuring` /
+  `fromState`) to surface rarer arms. `disasm({target:'resolveJumptable'})` is the
+  static-side alias. No static-only tool can do this — it's romdev's live-emulator
+  edge.
 
 **The loop:** `symbols({op:'analyze'})` or `disasm({target:'functions'})` to carve →
-`disasm({target:'cfg'/'xrefs'/'decompile'})` to understand a candidate → then the
+`disasm({target:'cfg'/'xrefs'/'decompile'})` to understand a candidate (→
+`breakpoint({on:'jumptable'})` when it dispatches through a computed jump) → then the
 dynamic tools (memory search, `breakpoint({on:'write'})`, `watch`) to CONFIRM and
 label which carved function owns the value you care about. Static narrows the
 search space; dynamic proves it.
@@ -422,8 +435,9 @@ Once you know WHAT to change, the write loop is a handful of calls — no custom
   and >32KB HuCards (refs carry `romBank`) — so a hit in bank 12 of a 128KB cart shows up,
   not just the first bank. Zero-page direct + indexed operands match, and `#$nn` immediates
   are excluded (values, not addresses). Limitation: direct addressing only —
-  indirect/computed jumps aren't detected (use the runtime `watch`/`breakpoint` tools in
-  §5/§5d for those).
+  indirect/computed jumps aren't detected statically; resolve those LIVE with
+  `breakpoint({on:'jumptable', address})` (runs the emulator to record the computed
+  targets), or the other runtime `watch`/`breakpoint` tools in §5/§5d.
 - **`cart({op:'extract', path, outputDir})`** — split a ROM into standard parts (NES header/
   prg/chr; SNES copier_header+rom+internal header; Genesis vectors/header/body; GB boot/
   header/body) + a `manifest.json` (mapper, mirroring…). **`cart({op:'wrap'})`** is the inverse:
@@ -528,6 +542,7 @@ For sprite/tile edits (not text), don't hand-roll the tile-format math:
 | Re-inject edited bytes the game accepts | `romPatch({op:'makeStored'})` (verbatim-expand block) → `romPatch({op:'findFree'})` → `romPatch({op:'relocate'})` |
 | Find the pointer that loads an asset | `romPatch({op:'findPointer', romOffset})` |
 | FIND the unknown routine touching X | `watch({on:'range', start,end})` (all hits) / `watch({on:'pc'})` (coverage) |
+| Resolve a computed-jump dispatcher (decompiles to `(*_IRQ)()`) | `breakpoint({on:'jumptable', address})` (live — records the real switch arms) |
 | Which DMA wrote a VRAM tile + its source (Genesis) | `watch({on:'dma', precision:'exact', vramDest})` |
 | Where did a VRAM graphic come from (Genesis) | `watch({on:'dma', precision:'sampled'})` (ROM offset of the DMA source) |
 | Drive a menu fast | `input({op:'navigate'})` (advances on screen change) |

package/src/toolchains/_worker/pool.js

@@ -57,6 +57,7 @@ function spawnWorker() {
     pendingResolve: null,
     pendingReject: null,
     pendingJobId: null,
+    timedOut: false,  // set true when we kill it for exceeding a job timeout
   };
 
   w.child.on("message", (msg) => {
@@ -108,10 +109,13 @@ function spawnWorker() {
       w.pendingResolve = null;
       w.pendingReject = null;
       const err = new Error(
-        `worker ${w.id} exited unexpectedly (code=${code} signal=${signal}) ` +
-        `while running job ${w.pendingJobId}`
+        w.timedOut
+          ? `worker ${w.id} killed after job ${w.pendingJobId} exceeded its timeout`
+          : `worker ${w.id} exited unexpectedly (code=${code} signal=${signal}) ` +
+            `while running job ${w.pendingJobId}`
       );
       /** @type {any} */(err).crash = { exitCode: code, signal: signal ?? null };
+      /** @type {any} */(err).timedOut = !!w.timedOut;
       w.pendingJobId = null;
       reject(err);
     }
@@ -184,12 +188,31 @@ export async function runInWorker(job) {
   const w = await acquire();
   const id = nextJobId++;
   return new Promise((resolve, reject) => {
+    let done = false;
+    let timer = null;
+    const finish = () => {
+      if (timer) { clearTimeout(timer); timer = null; }
+    };
     const settle = (result, err) => {
+      if (done) return;
+      done = true;
+      finish();
       if (err) reject(err); else resolve(result);
     };
     w.pendingResolve = (result) => settle(result);
     w.pendingReject = (err) => {
-      if (err && err.crash) {
+      if (err && err.crash && /** @type {any} */ (err).timedOut) {
+        // A timeout we triggered — report it cleanly, not as a generic crash.
+        settle({
+          exitCode: -1,
+          log: `[timeout] analysis exceeded ${job.timeoutMs}ms and was killed; the WASM worker was ` +
+            `recycled (pool not wedged). For a multi-MB ROM use a scoped pass (analyze one function/bank, ` +
+            `not whole-ROM 'aaa').\n`,
+          outputs: {},
+          timedOut: true,
+          crash: err.crash,
+        });
+      } else if (err && err.crash) {
         // Convert crash to a normal result so callers don't have to catch.
         settle({
           exitCode: err.crash.exitCode ?? -1,
@@ -202,6 +225,21 @@ export async function runInWorker(job) {
       }
     };
     w.pendingJobId = id;
+
+    // Per-call timeout (A5 reliability): a hung WASM analysis (whole-ROM `aaa` on
+    // a multi-MB ROM) never exits the worker, so without this the pending job
+    // wedges the slot forever. On timeout we KILL the worker — the exit handler
+    // (which sees `w.timedOut`) rejects this job with a clear timeout result and
+    // respawns a fresh worker, so the pool keeps its capacity.
+    if (job.timeoutMs && job.timeoutMs > 0) {
+      timer = setTimeout(() => {
+        if (done) return;
+        w.timedOut = true;
+        try { w.child.kill("SIGKILL"); } catch { /* already gone */ }
+      }, job.timeoutMs);
+      if (typeof timer.unref === "function") timer.unref();
+    }
+
     w.child.send({ type: "run", id, job });
   });
 }