square-repaint-triage

name: square-repaint-triage description: Use watched-cell repaint tracing when a parity bug is localized to one screen square and you need the runtime write order for that exact terminal cell across a short step range.

Square Repaint Triage

Use this after first divergence is already localized and the remaining question is runtime repaint order for one terminal cell.

Read docs/SQUARE_REPAINT_TRACE.md for the exact command syntax and guardrails.

When To Use

Use it when:

1. RNG/events already match, or the visible bug is clearly local
2. dbgmapdump has narrowed the issue to one square or a tiny cluster
3. you need to know which runtime write last touched the bad cell

Do not use it as a first-pass localization tool. Use:

1. session_test_runner
2. dbgmapdump
3. repaint traces

first.

Core Command

node scripts/debug/repaint_square_trace.mjs <session.json> --cell <col,row> --steps <from-to> --stack

This uses the real active display runtime:

1. js/display.js during parity/session replay
2. js/display.js during browser/runtime debugging

Interpretation

• kind=write: a changed cell payload was written
• prev=... next=...: the visible overwrite happened here
• kind=cursor: cursor ownership moved onto the watched cell
• caller=...: use this to identify the owning runtime path

Standard Workflow

1. find first bad screen step
2. capture nearby settled state with dbgmapdump
3. watch the exact bad screen cell over step-1 .. step+1
4. identify the final wrong writer
5. fix core JS runtime/display behavior

Guardrails

1. keep the trace range short
2. watch one cell unless there is a strong reason not to
3. do not patch harness/comparator based on this output
4. remove any temporary extra diagnostics once the root cause is proven