Switch statement coverage: state-machine tests, mini-sample, docs (#535)

* Initial plan

* Add switch state-machine tests, sample, and update docs

Agent-Logs-Url: https://github.com/jonathanpeppers/dotnes/sessions/75bd402b-4c42-406c-86de-f4a5e97f7589

Co-authored-by: jonathanpeppers <840039+jonathanpeppers@users.noreply.github.com>

* Tighten switch test assertions per review feedback

- SwitchWithDefault: assert the CMP/BNE+JMP trampoline signature
  (C9 imm D0 03 4C) for cases 1..3, plus BNE+JMP (D0 03 4C) for case 0,
  instead of bare 'D0'/'4C' substrings that match unrelated control flow.
- SwitchStateMachine: give the default arm a distinctive sentinel
  (lives = 0xAB) so the test can prove the default body is actually
  emitted, and assert the same trampoline signature for cases 1, 2 and
  the case 0 BEQ-style trampoline.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Replace statemachine sample with SwitchStateMachineWithRendering test

The samples/statemachine project wasn't pulling its weight as a standalone
sample — it just demonstrated the switch dispatch pattern that's already
covered by tests. Convert its content into a dedicated RoslynTests case
that also covers the surrounding rendering setup (per-state pal_col,
NTADR_A + vram_write, ppu_on_all).

- Add SwitchStateMachineWithRendering to ControlFlowTests, asserting both
  the CMP/BNE+JMP trampoline signature and the distinctive per-case pal_col
  immediates (0x02 / 0x0A / 0x06).
- Delete samples/statemachine entirely.
- Update docs/8bitworkshop-samples.md to reference the new test name.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Add SwitchLarge test covering 32-case dense switch

Verifies that a large dense integral switch (Roslyn lowers to the IL
'switch' opcode / jump table) transpiles end-to-end. dotnes expands the
opcode into a linear chain of CMP/BNE+JMP trampolines; this test
asserts the trampoline signature at several case indices (1, 15, 31)
and that the default arm is reachable.

Not an optimization — just a regression guard that the transpiler
doesn't choke on big case counts.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Make STATE_TITLE arm assertion distinctive

The STATE_TITLE case body was setting pal_col(0, 0x02), which is also
called in the setup block — so asserting A902 would pass even if the
case 0 dispatch was broken. Change the arm to pal_col(0, 0x12) and
assert A912 instead, matching the distinctiveness of the other arms.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jonathanpeppers <840039+jonathanpeppers@users.noreply.github.com>
Co-authored-by: jonathanpeppers <jonathan.peppers@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 3 people

docs/8bitworkshop-samples.md

@@ -216,7 +216,6 @@
   - Extensive use of pointers, arrays of structs, bitfields
   - `static` variables, `const` arrays
   - Multiple user-defined functions with complex control flow
-  - `switch/case` statements
   - Far exceeds dotnes's current single-top-level-statement model
 
 ### climber.c
@@ -340,7 +339,7 @@
 Prioritized TODO list of features needed to port climber.c, ordered by dependency and impact:
 
 - [x] **User functions with return values** — byte return values work: the last computed value stays in A through `incsp` parameter cleanup and RTS. The caller's `HasReturnValue` check sets `_runtimeValueInA = true`. Verified with RoslynTests: constant return, parameterized return, return value stored to local.
-- [x] **switch/case** — small switches use branch chains (beq.s, already supported). Larger sequential switches use the IL `switch` opcode (0x45) which emits CMP/BNE+JMP trampolines. Tested with SwitchSmall (3 cases) and SwitchEnum (7 cases with enum).
+- [x] **switch/case** — small switches use branch chains (beq.s, already supported). Larger sequential switches use the IL `switch` opcode (0x45) which emits CMP/BNE+JMP trampolines. `default:` clauses fall through correctly. Tested with SwitchSmall (3 cases), SwitchEnum (7 cases with enum), SwitchWithDefault (5-way byte with default), SwitchStateMachine (title/playing/over game-state pattern), and SwitchStateMachineWithRendering (full pal_col + vram_write rendering loop).
 - [x] **BCD arithmetic** — `bcd_add(ushort, ushort)` built-in NESLib function backed by 6502 subroutine. Software BCD since NES CPU disabled hardware BCD mode. Also fixed: 16-bit return values from built-in functions now correctly store both bytes (STA+STX) to word locals.
 - [x] **Global/static variables** — `stsfld`/`ldsfld` for user-defined static class fields. Allocated at `$0325+` (same region as locals). Both `static class State { public static byte x; }` and local variables work for the same patterns. Tested with store, load, and loop increment.
 - [x] **sbyte (signed char)** — `Ldc_i4_m1`, negative constants via two's complement, `conv.i1`/`conv.i2`/`conv.i4` as no-ops on 8-bit 6502. Signed comparisons work via `Blt_s` (BMI).

src/dotnes.tests/ControlFlowTests.cs

@@ -119,6 +119,208 @@ enum ActorState : byte { Inactive, Standing, Walking, Climbing, Jumping, Falling
         Assert.Contains("C906", hex);
     }
 
+    [Fact]
+    public void SwitchWithDefault()
+    {
+        // switch on byte with 4+ cases and a default clause.
+        // The default must run when the discriminator does not match any case.
+        var bytes = GetProgramBytes(
+            """
+            byte op = 4;
+            byte r = 0;
+            switch (op) {
+                case 0: r = 0x10; break;
+                case 1: r = 0x20; break;
+                case 2: r = 0x30; break;
+                case 3: r = 0x16; break;
+                default: r = 0x26; break;
+            }
+            pal_col(0, r);
+            ppu_on_all();
+            while (true) ;
+            """);
+        Assert.NotNull(bytes);
+        Assert.NotEmpty(bytes);
+
+        var hex = Convert.ToHexString(bytes);
+        // Each non-zero case must emit the BNE+JMP trampoline:
+        //   CMP #imm (C9 imm), BNE +3 (D0 03), JMP target (4C lo hi)
+        // Assert the 5-byte prefix C9 imm D0 03 4C is present for cases 1..3.
+        Assert.Contains("C901D0034C", hex);
+        Assert.Contains("C902D0034C", hex);
+        Assert.Contains("C903D0034C", hex);
+        // Case 0 uses BEQ-style trampoline (no CMP): BNE +3, JMP target.
+        Assert.Contains("D0034C", hex);
+        // The default value 0x26 must appear (LDA #$26 = A926) — this is the
+        // distinctive side effect of the default arm and proves fall-through dispatch.
+        Assert.Contains("A926", hex);
+    }
+
+    [Fact]
+    public void SwitchStateMachine()
+    {
+        // The state-machine pattern from the issue: title / playing / over with a default.
+        // Roslyn lowers a dense byte switch with default into IL `switch` + br to default.
+        // The default arm sets `lives` to a distinctive sentinel value (0xAB) so the
+        // assertions can prove the default arm's body is actually emitted, separate
+        // from the normal state transitions.
+        var bytes = GetProgramBytes(
+            """
+            const byte STATE_TITLE   = 0;
+            const byte STATE_PLAYING = 1;
+            const byte STATE_OVER    = 2;
+
+            byte state = STATE_TITLE;
+            byte lives = 3;
+
+            while (true)
+            {
+                pad_poll(0);
+                switch (state)
+                {
+                    case STATE_TITLE:
+                        if ((pad_trigger(0) & PAD.START) != 0)
+                            state = STATE_PLAYING;
+                        break;
+                    case STATE_PLAYING:
+                        if (lives == 0)
+                            state = STATE_OVER;
+                        break;
+                    case STATE_OVER:
+                        if ((pad_trigger(0) & PAD.START) != 0)
+                            state = STATE_TITLE;
+                        break;
+                    default:
+                        lives = 0xAB;
+                        state = STATE_TITLE;
+                        break;
+                }
+                ppu_wait_nmi();
+            }
+            """);
+        Assert.NotNull(bytes);
+        Assert.NotEmpty(bytes);
+
+        var hex = Convert.ToHexString(bytes);
+        // Each non-zero case must emit the BNE+JMP trampoline signature:
+        //   CMP #imm (C9 imm), BNE +3 (D0 03), JMP target (4C lo hi).
+        // Asserting the 5-byte prefix proves the dispatch is CMP/BNE+JMP, not
+        // unrelated CMP/BNE/JMP from surrounding control flow.
+        Assert.Contains("C901D0034C", hex);
+        Assert.Contains("C902D0034C", hex);
+        // Case 0 uses BEQ-style trampoline (value already in A): BNE +3, JMP target.
+        Assert.Contains("D0034C", hex);
+        // The default arm's distinctive sentinel value 0xAB must appear
+        // (LDA #$AB = A9AB), proving the default body is reachable/emitted.
+        Assert.Contains("A9AB", hex);
+    }
+
+    [Fact]
+    public void SwitchStateMachineWithRendering()
+    {
+        // Full game-style state machine: nametable text setup + per-state background
+        // color via pal_col, driven by START on controller 1. Each case body has a
+        // distinctive pal_col immediate so we can assert the dispatch lands in each arm.
+        var bytes = GetProgramBytes(
+            """
+            const byte STATE_TITLE   = 0;
+            const byte STATE_PLAYING = 1;
+            const byte STATE_OVER    = 2;
+
+            pal_col(0, 0x02);
+            pal_col(1, 0x14);
+            pal_col(2, 0x20);
+            pal_col(3, 0x30);
+
+            vram_adr(NTADR_A(8, 14));
+            vram_write("PRESS START");
+            ppu_on_all();
+
+            byte state = STATE_TITLE;
+
+            while (true)
+            {
+                ppu_wait_nmi();
+                pad_poll(0);
+
+                switch (state)
+                {
+                    case STATE_TITLE:
+                        pal_col(0, 0x12);
+                        if ((pad_trigger(0) & PAD.START) != 0)
+                            state = STATE_PLAYING;
+                        break;
+                    case STATE_PLAYING:
+                        pal_col(0, 0x0A);
+                        if ((pad_trigger(0) & PAD.START) != 0)
+                            state = STATE_OVER;
+                        break;
+                    case STATE_OVER:
+                        pal_col(0, 0x06);
+                        if ((pad_trigger(0) & PAD.START) != 0)
+                            state = STATE_TITLE;
+                        break;
+                    default:
+                        state = STATE_TITLE;
+                        break;
+                }
+            }
+            """);
+        Assert.NotNull(bytes);
+        Assert.NotEmpty(bytes);
+
+        var hex = Convert.ToHexString(bytes);
+        // CMP/BNE+JMP trampolines for cases 1 and 2 (case 0 uses BEQ-style).
+        Assert.Contains("C901D0034C", hex);
+        Assert.Contains("C902D0034C", hex);
+        Assert.Contains("D0034C", hex);
+        // Distinctive per-case pal_col immediates prove each arm's body is emitted.
+        // Each value is chosen to NOT appear in the setup pal_col calls above,
+        // so the assertion can only be satisfied by the switch arm itself.
+        // LDA #imm = A9 imm.
+        Assert.Contains("A912", hex); // STATE_TITLE arm
+        Assert.Contains("A90A", hex); // STATE_PLAYING arm
+        Assert.Contains("A906", hex); // STATE_OVER arm
+    }
+
+    [Fact]
+    public void SwitchLarge()
+    {
+        // Build a dense 32-case switch programmatically. Roslyn lowers a dense
+        // integral switch to the IL `switch` opcode (jump table), which dotnes
+        // expands into a linear chain of CMP/BNE+JMP trampolines. This just
+        // verifies the transpiler doesn't choke on a large case count and that
+        // the dispatch chain is actually emitted.
+        const int caseCount = 32;
+        var sb = new System.Text.StringBuilder();
+        sb.AppendLine("byte op = 17;");
+        sb.AppendLine("byte r = 0;");
+        sb.AppendLine("switch (op) {");
+        for (int i = 0; i < caseCount; i++)
+        {
+            // Distinctive value per case: 0x40 + i (avoids collision with case index).
+            sb.AppendLine($"    case {i}: r = 0x{0x40 + i:X2}; break;");
+        }
+        sb.AppendLine("    default: r = 0xFF; break;");
+        sb.AppendLine("}");
+        sb.AppendLine("pal_col(0, r);");
+        sb.AppendLine("ppu_on_all();");
+        sb.AppendLine("while (true) ;");
+
+        var bytes = GetProgramBytes(sb.ToString());
+        Assert.NotNull(bytes);
+        Assert.NotEmpty(bytes);
+
+        var hex = Convert.ToHexString(bytes);
+        // Spot-check the BNE+JMP trampoline signature at several case indices.
+        // CMP #i, BNE +3, JMP target = C9 ii D0 03 4C.
+        Assert.Contains("C901D0034C", hex);   // case 1
+        Assert.Contains("C90FD0034C", hex);   // case 15
+        Assert.Contains("C91FD0034C", hex);   // case 31 (last)
+        // Default sentinel 0xFF must appear (LDA #$FF = A9FF).
+        Assert.Contains("A9FF", hex);
+    }
+
     [Fact]
     public void DoWhileLoop()
     {