gemba 0.1.0

data/test/test_player.rb

@@ -0,0 +1,903 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require_relative "shared/tk_test_helper"
+
+class TestMGBAPlayer < Minitest::Test
+  include TeekTestHelper
+
+  TEST_ROM = File.expand_path("fixtures/test.gba", __dir__)
+
+  # Launches the full Player with a ROM loaded, runs a few frames,
+  # then triggers quit. If the process doesn't exit within the timeout
+  # the test fails — catching exit-hang regressions.
+  def test_exit_with_rom_loaded_does_not_hang
+    code = <<~RUBY
+      require "gemba"
+      require "support/player_helpers"
+
+      player = Gemba::Player.new("#{TEST_ROM}")
+      app = player.app
+
+      poll_until_ready(player) { player.running = false }
+
+      player.run
+    RUBY
+
+    success, stdout, stderr, _status = tk_subprocess(code)
+
+    output = []
+    output << "STDOUT:\n#{stdout}" unless stdout.empty?
+    output << "STDERR:\n#{stderr}" unless stderr.empty?
+
+    assert success, "Player should exit cleanly with ROM loaded (no hang)\n#{output.join("\n")}"
+  end
+
+  # Simulate a user pressing F11 twice (fullscreen on → off) then q to quit.
+  # Exercises the wm attributes fullscreen path end-to-end. If the toggle
+  # causes a hang or crash the subprocess will time out.
+  def test_fullscreen_toggle_does_not_hang
+    code = <<~RUBY
+      require "gemba"
+      require "support/player_helpers"
+
+      player = Gemba::Player.new("#{TEST_ROM}")
+      app = player.app
+
+      poll_until_ready(player) do
+        vp = player.viewport
+        frame = vp.frame.path
+
+        # User presses F11 → fullscreen on
+        app.command(:event, 'generate', frame, '<KeyPress>', keysym: 'F11')
+        app.update
+
+        app.after(50) do
+          # User presses F11 → fullscreen off
+          app.command(:event, 'generate', frame, '<KeyPress>', keysym: 'F11')
+          app.update
+
+          app.after(50) do
+            # User presses q → quit
+            app.command(:event, 'generate', frame, '<KeyPress>', keysym: 'q')
+          end
+        end
+      end
+
+      player.run
+    RUBY
+
+    success, stdout, stderr, _status = tk_subprocess(code)
+
+    output = []
+    output << "STDOUT:\n#{stdout}" unless stdout.empty?
+    output << "STDERR:\n#{stderr}" unless stderr.empty?
+
+    assert success, "Player should exit cleanly after fullscreen toggle\n#{output.join("\n")}"
+  end
+
+  # Simulate a user enabling turbo (Tab), running a few frames at 2x speed,
+  # then pressing q to quit. Without the poll_input fix (update_state vs
+  # poll_events), SDL_PollEvent steals Tk keyboard events on macOS and
+  # the quit key never reaches the KeyPress handler — causing a hang.
+  def test_exit_during_turbo_does_not_hang
+    code = <<~RUBY
+      require "gemba"
+      require "support/player_helpers"
+
+      player = Gemba::Player.new("#{TEST_ROM}")
+      app = player.app
+
+      poll_until_ready(player) do
+        vp = player.viewport
+        frame = vp.frame.path
+
+        # User presses Tab → enable turbo (2x default)
+        app.command(:event, 'generate', frame, '<KeyPress>', keysym: 'Tab')
+        app.update
+
+        app.after(50) do
+          # User presses q → quit (while still in turbo)
+          app.command(:event, 'generate', frame, '<KeyPress>', keysym: 'q')
+        end
+      end
+
+      player.run
+    RUBY
+
+    success, stdout, stderr, _status = tk_subprocess(code)
+
+    output = []
+    output << "STDOUT:\n#{stdout}" unless stdout.empty?
+    output << "STDERR:\n#{stderr}" unless stderr.empty?
+
+    assert success, "Player should exit cleanly during turbo mode (no hang)\n#{output.join("\n")}"
+  end
+
+  # E2E: quick save (F5), wait for debounce, quick load (F8).
+  # Verifies state file + screenshot are created, backup rotation works,
+  # and the core remains functional after load.
+  def test_quick_save_and_load_creates_files_and_restores_state
+    skip "Run: ruby gemba/scripts/generate_test_rom.rb" unless File.exist?(TEST_ROM)
+
+    code = <<~RUBY
+      require "gemba"
+      require "tmpdir"
+      require "fileutils"
+      require "support/player_helpers"
+
+      # Use a temp dir for all config/states so we don't pollute the real one
+      states_dir = Dir.mktmpdir("gemba-states-test")
+
+      player = Gemba::Player.new("#{TEST_ROM}")
+      app = player.app
+      config = player.config
+
+      # Override states dir and reduce debounce for test speed
+      config.states_dir = states_dir
+      config.save_state_debounce = 0.1
+
+      poll_until_ready(player) do
+        core = player.save_mgr.core
+        state_dir = player.save_mgr.state_dir
+        vp = player.viewport
+        frame_path = vp.frame.path
+
+        # Quick save (F5)
+        app.command(:event, 'generate', frame_path, '<KeyPress>', keysym: 'F5')
+        app.update
+
+        app.after(50) do
+          # Verify state file and screenshot exist
+          ss_path = File.join(state_dir, "state1.ss")
+          png_path = File.join(state_dir, "state1.png")
+
+          unless File.exist?(ss_path)
+            $stderr.puts "FAIL: state file not created at \#{ss_path}"
+            $stderr.puts "Dir contents: \#{Dir.glob(state_dir + '/**/*').inspect}"
+            exit 1
+          end
+
+          unless File.exist?(png_path)
+            $stderr.puts "FAIL: screenshot not created at \#{png_path}"
+            exit 1
+          end
+
+          ss_size = File.size(ss_path)
+          png_size = File.size(png_path)
+
+          # Save again to test backup rotation (after debounce)
+          app.after(50) do
+            app.command(:event, 'generate', frame_path, '<KeyPress>', keysym: 'F5')
+            app.update
+
+            app.after(50) do
+              bak_path = ss_path + ".bak"
+              png_bak = png_path + ".bak"
+
+              unless File.exist?(bak_path)
+                $stderr.puts "FAIL: backup not created at \#{bak_path}"
+                exit 1
+              end
+
+              unless File.exist?(png_bak)
+                $stderr.puts "FAIL: PNG backup not created at \#{png_bak}"
+                exit 1
+              end
+
+              # Quick load (F8)
+              app.command(:event, 'generate', frame_path, '<KeyPress>', keysym: 'F8')
+              app.update
+
+              app.after(50) do
+                # Verify core is still functional after load
+                begin
+                  core.run_frame
+                  buf = core.video_buffer
+                  unless buf.bytesize == 240 * 160 * 4
+                    $stderr.puts "FAIL: video buffer invalid after state load"
+                    exit 1
+                  end
+                rescue => e
+                  $stderr.puts "FAIL: core error after load: \#{e.message}"
+                  exit 1
+                end
+
+                $stdout.puts "PASS"
+                $stdout.puts "state_size=\#{ss_size}"
+                $stdout.puts "png_size=\#{png_size}"
+
+                # Clean up and quit
+                FileUtils.rm_rf(states_dir)
+                player.running = false
+              end
+            end
+          end
+        end
+      end
+
+      player.run
+    RUBY
+
+    success, stdout, stderr, _status = tk_subprocess(code)
+
+    output = []
+    output << "STDOUT:\n#{stdout}" unless stdout.empty?
+    output << "STDERR:\n#{stderr}" unless stderr.empty?
+
+    assert success, "Quick save/load E2E test failed\n#{output.join("\n")}"
+    assert_includes stdout, "PASS", "Expected PASS in output\n#{output.join("\n")}"
+
+    # Verify state file was non-trivial
+    if stdout =~ /state_size=(\d+)/
+      assert $1.to_i > 1000, "State file should be >1KB (got #{$1} bytes)"
+    end
+
+    # Verify PNG was created
+    if stdout =~ /png_size=(\d+)/
+      assert $1.to_i > 100, "PNG screenshot should be >100 bytes (got #{$1} bytes)"
+    end
+  end
+
+  # E2E: verify debounce blocks rapid-fire saves.
+  def test_quick_save_debounce_blocks_rapid_fire
+    skip "Run: ruby gemba/scripts/generate_test_rom.rb" unless File.exist?(TEST_ROM)
+
+    code = <<~RUBY
+      require "gemba"
+      require "tmpdir"
+      require "fileutils"
+      require "support/player_helpers"
+
+      states_dir = Dir.mktmpdir("gemba-debounce-test")
+
+      player = Gemba::Player.new("#{TEST_ROM}")
+      app = player.app
+      config = player.config
+
+      config.states_dir = states_dir
+      config.save_state_debounce = 5.0  # long debounce
+
+      poll_until_ready(player) do
+        vp = player.viewport
+        frame_path = vp.frame.path
+
+        # First save should succeed
+        app.command(:event, 'generate', frame_path, '<KeyPress>', keysym: 'F5')
+        app.update
+
+        app.after(50) do
+          state_dir = player.save_mgr.state_dir
+          ss_path = File.join(state_dir, "state1.ss")
+
+          first_exists = File.exist?(ss_path)
+          first_mtime = first_exists ? File.mtime(ss_path) : nil
+
+          # Immediate second save should be debounced (within 5s window)
+          app.command(:event, 'generate', frame_path, '<KeyPress>', keysym: 'F5')
+          app.update
+
+          app.after(50) do
+            second_mtime = File.exist?(ss_path) ? File.mtime(ss_path) : nil
+
+            if !first_exists
+              $stderr.puts "FAIL: first save didn't create file"
+              exit 1
+            end
+
+            if first_mtime != second_mtime
+              $stderr.puts "FAIL: debounce didn't block second save (mtime changed)"
+              exit 1
+            end
+
+            $stdout.puts "PASS"
+            FileUtils.rm_rf(states_dir)
+            player.running = false
+          end
+        end
+      end
+
+      player.run
+    RUBY
+
+    success, stdout, stderr, _status = tk_subprocess(code)
+
+    output = []
+    output << "STDOUT:\n#{stdout}" unless stdout.empty?
+    output << "STDERR:\n#{stderr}" unless stderr.empty?
+
+    assert success, "Debounce test failed\n#{output.join("\n")}"
+    assert_includes stdout, "PASS", "Expected PASS in output\n#{output.join("\n")}"
+  end
+
+  # E2E: open Settings via menu, navigate to Save States tab,
+  # change quick save slot from 1 → 10, click Save, verify persisted.
+  def test_settings_change_quick_slot_and_save
+    skip "Run: ruby gemba/scripts/generate_test_rom.rb" unless File.exist?(TEST_ROM)
+
+    code = <<~RUBY
+      require "gemba"
+      require "tmpdir"
+      require "json"
+      require "fileutils"
+      require "support/player_helpers"
+
+      config_dir = Dir.mktmpdir("gemba-settings-test")
+      config_path = File.join(config_dir, "settings.json")
+
+      player = Gemba::Player.new("#{TEST_ROM}")
+      app = player.app
+      config = player.config
+
+      # Redirect config to a temp file so we can verify persistence
+      config.path = config_path
+
+      poll_until_ready(player) do
+        nb       = Gemba::SettingsWindow::NB
+        ss_tab   = Gemba::SettingsWindow::SS_TAB
+        slot_combo = Gemba::SettingsWindow::SS_SLOT_COMBO
+        save_btn = Gemba::SettingsWindow::SAVE_BTN
+        var_slot = Gemba::SettingsWindow::VAR_QUICK_SLOT
+
+        # Open Settings > Save States via the Settings menu (index 3)
+        app.command('.menubar.settings', :invoke, 3)
+        app.update
+
+        # Verify default slot is 1
+        current = app.get_variable(var_slot)
+        unless current == '1'
+          $stderr.puts "FAIL: expected default slot '1', got '\#{current}'"
+          exit 1
+        end
+
+        # Change slot to 10 (simulate user selecting from combobox)
+        app.set_variable(var_slot, '10')
+        app.command(:event, 'generate', slot_combo, '<<ComboboxSelected>>')
+        app.update
+
+        # Click the Save button
+        app.command(save_btn, 'invoke')
+        app.update
+
+        app.after(50) do
+          # Verify config file was written
+          unless File.exist?(config_path)
+            $stderr.puts "FAIL: config file not created at \#{config_path}"
+            exit 1
+          end
+
+          data = JSON.parse(File.read(config_path))
+          saved_slot = data.dig('global', 'quick_save_slot')
+          unless saved_slot == 10
+            $stderr.puts "FAIL: expected quick_save_slot=10, got \#{saved_slot.inspect}"
+            exit 1
+          end
+
+          $stdout.puts "PASS"
+          $stdout.puts "saved_slot=\#{saved_slot}"
+          FileUtils.rm_rf(config_dir)
+          player.running = false
+        end
+      end
+
+      player.run
+    RUBY
+
+    success, stdout, stderr, _status = tk_subprocess(code)
+
+    output = []
+    output << "STDOUT:\n#{stdout}" unless stdout.empty?
+    output << "STDERR:\n#{stderr}" unless stderr.empty?
+
+    assert success, "Settings slot change E2E test failed\n#{output.join("\n")}"
+    assert_includes stdout, "PASS", "Expected PASS in output\n#{output.join("\n")}"
+    assert_match(/saved_slot=10/, stdout)
+  end
+
+  # -- Audio fade ramp (pure function, no Tk/SDL2 needed) --------------------
+
+  def test_fade_ramp_attenuates_first_samples
+    require "gemba/player"
+    # 10 stereo frames of max-amplitude int16
+    pcm = ([32767, 32767] * 10).pack('s*')
+    total = 10
+    result, remaining = Gemba::Player.apply_fade_ramp(pcm, total, total)
+    samples = result.unpack('s*')
+
+    # First stereo pair: gain = 1 - 10/10 = 0.0 → should be 0
+    assert_equal 0, samples[0], "first L sample should be silent"
+    assert_equal 0, samples[1], "first R sample should be silent"
+
+    # Last stereo pair: gain = 1 - 1/10 = 0.9 → should be ~29490
+    assert_in_delta 29490, samples[18], 1, "last L sample should be ~90% volume"
+    assert_in_delta 29490, samples[19], 1, "last R sample should be ~90% volume"
+
+    assert_equal 0, remaining, "counter should be fully consumed"
+  end
+
+  def test_fade_ramp_returns_remaining_when_pcm_shorter_than_fade
+    require "gemba/player"
+    # Only 2 stereo frames but fade wants 10
+    pcm = ([20000, 20000] * 2).pack('s*')
+    _result, remaining = Gemba::Player.apply_fade_ramp(pcm, 10, 10)
+    assert_equal 8, remaining, "should have 8 fade samples remaining"
+  end
+
+  def test_fade_ramp_noop_when_remaining_zero
+    require "gemba/player"
+    pcm = ([10000, -10000] * 4).pack('s*')
+    result, remaining = Gemba::Player.apply_fade_ramp(pcm, 0, 10)
+    assert_equal pcm, result, "should not modify samples when remaining is 0"
+    assert_equal 0, remaining
+  end
+
+  # E2E: verify child windows are modal — only one can be open at a time.
+  # Opens Settings via menu, tries F6 for picker (should be blocked),
+  # closes Settings, opens picker via F6, tries Settings menu (blocked),
+  # closes picker. Checks window visibility via `wm state`.
+  def test_modal_child_blocks_concurrent_windows
+    skip "Run: ruby gemba/scripts/generate_test_rom.rb" unless File.exist?(TEST_ROM)
+
+    code = <<~RUBY
+      require "gemba"
+      require "support/player_helpers"
+
+      sw_top = Gemba::SettingsWindow::TOP
+      sp_top = Gemba::SaveStatePicker::TOP
+
+      player = Gemba::Player.new("#{TEST_ROM}")
+      app = player.app
+
+      poll_until_ready(player) do
+        vp = player.viewport
+        frame = vp.frame.path
+
+        # 1. Open Settings via menu (Settings > Video = index 0)
+        app.command('.menubar.settings', :invoke, 0)
+        app.update
+
+        sw_state = app.command(:wm, 'state', sw_top)
+        unless sw_state == 'normal'
+          $stderr.puts "FAIL: Settings should be visible, got '\#{sw_state}'"
+          exit 1
+        end
+
+        # 2. Try Save States via Emulation menu — should be blocked by @modal_child
+        app.command('.menubar.emu', :invoke, 6)
+        app.update
+
+        # Picker window may not even exist yet (not built), or should be withdrawn
+        sp_state = begin
+          app.command(:wm, 'state', sp_top)
+        rescue
+          'withdrawn'
+        end
+        unless sp_state == 'withdrawn'
+          $stderr.puts "FAIL: Picker should be blocked while Settings is open, got '\#{sp_state}'"
+          exit 1
+        end
+
+        # 3. Close Settings (releases grab + fires on_close)
+        player.settings_window.hide
+        app.update
+
+        sw_state = app.command(:wm, 'state', sw_top)
+        unless sw_state == 'withdrawn'
+          $stderr.puts "FAIL: Settings should be withdrawn after close, got '\#{sw_state}'"
+          exit 1
+        end
+
+        # 4. Now open picker — focus -force needed under xvfb after grab release
+        app.tcl_eval("focus -force \#{frame}")
+        app.update
+        app.command(:event, 'generate', frame, '<KeyPress>', keysym: 'F6')
+        app.update
+
+        sp_state = app.command(:wm, 'state', sp_top)
+        unless sp_state == 'normal'
+          $stderr.puts "FAIL: Picker should be visible after Settings closed, got '\#{sp_state}'"
+          exit 1
+        end
+
+        # 5. Try opening Settings via menu while picker is open — should be blocked
+        app.command('.menubar.settings', :invoke, 0)
+        app.update
+
+        sw_state = app.command(:wm, 'state', sw_top)
+        unless sw_state == 'withdrawn'
+          $stderr.puts "FAIL: Settings should be blocked while Picker is open, got '\#{sw_state}'"
+          exit 1
+        end
+
+        # 6. Close picker via its close button
+        app.command("\#{sp_top}.close_btn", 'invoke')
+        app.update
+
+        sp_state = app.command(:wm, 'state', sp_top)
+        unless sp_state == 'withdrawn'
+          $stderr.puts "FAIL: Picker should be withdrawn after close, got '\#{sp_state}'"
+          exit 1
+        end
+
+        $stdout.puts "PASS"
+        player.running = false
+      end
+
+      player.run
+    RUBY
+
+    success, stdout, stderr, _status = tk_subprocess(code)
+
+    output = []
+    output << "STDOUT:\n#{stdout}" unless stdout.empty?
+    output << "STDERR:\n#{stderr}" unless stderr.empty?
+
+    assert success, "Modal child test failed\n#{output.join("\n")}"
+    assert_includes stdout, "PASS", "Expected PASS in output\n#{output.join("\n")}"
+  end
+
+  # -- File drop (DND) --------------------------------------------------------
+
+  def test_drop_rom_file_loads_game
+    skip "Run: ruby gemba/scripts/generate_test_rom.rb" unless File.exist?(TEST_ROM)
+
+    code = <<~RUBY
+      require "gemba"
+      require "support/player_helpers"
+
+      player = Gemba::Player.new
+      app = player.app
+
+      # Stub tk_messageBox so it never blocks
+      app.tcl_eval('proc tk_messageBox {args} { return "ok" }')
+
+      poll_until_ready(player) do
+        # Simulate dropping a ROM file onto the window
+        app.tcl_eval('event generate . <<DropFile>> -data {#{TEST_ROM}}')
+        app.update
+
+        app.after(50) do
+          core = player.core
+          if core && !core.destroyed?
+            $stdout.puts "TITLE=\#{core.title}"
+          else
+            $stdout.puts "FAIL: no core loaded"
+          end
+          player.running = false
+        end
+      end
+
+      player.run
+    RUBY
+
+    success, stdout, stderr, _status = tk_subprocess(code)
+
+    output = []
+    output << "STDOUT:\n#{stdout}" unless stdout.empty?
+    output << "STDERR:\n#{stderr}" unless stderr.empty?
+
+    assert success, "Drop ROM test failed\n#{output.join("\n")}"
+    assert_includes stdout, "TITLE=GEMBATEST", "Expected ROM to load via drop\n#{output.join("\n")}"
+  end
+
+  def test_drop_unsupported_file_shows_error
+    skip "Run: ruby gemba/scripts/generate_test_rom.rb" unless File.exist?(TEST_ROM)
+
+    code = <<~RUBY
+      require "gemba"
+      require "support/player_helpers"
+
+      player = Gemba::Player.new
+      app = player.app
+
+      # Capture tk_messageBox calls instead of blocking
+      app.tcl_eval('set ::msgbox_calls {}')
+      app.tcl_eval('proc tk_messageBox {args} { lappend ::msgbox_calls $args; return "ok" }')
+
+      poll_until_ready(player) do
+        # Drop a .txt file — should be rejected
+        app.tcl_eval('event generate . <<DropFile>> -data {/tmp/readme.txt}')
+        app.update
+
+        app.after(50) do
+          calls = app.tcl_eval('set ::msgbox_calls')
+          if calls.include?("Unsupported file type")
+            $stdout.puts "PASS"
+          else
+            $stdout.puts "FAIL: no error dialog shown, calls=\#{calls}"
+          end
+          player.running = false
+        end
+      end
+
+      player.run
+    RUBY
+
+    success, stdout, stderr, _status = tk_subprocess(code)
+
+    output = []
+    output << "STDOUT:\n#{stdout}" unless stdout.empty?
+    output << "STDERR:\n#{stderr}" unless stderr.empty?
+
+    assert success, "Drop unsupported file test failed\n#{output.join("\n")}"
+    assert_includes stdout, "PASS", "Expected error dialog for unsupported file type\n#{output.join("\n")}"
+  end
+
+  def test_drop_multiple_files_shows_error
+    skip "Run: ruby gemba/scripts/generate_test_rom.rb" unless File.exist?(TEST_ROM)
+
+    code = <<~RUBY
+      require "gemba"
+      require "support/player_helpers"
+
+      player = Gemba::Player.new
+      app = player.app
+
+      # Capture tk_messageBox calls instead of blocking
+      app.tcl_eval('set ::msgbox_calls {}')
+      app.tcl_eval('proc tk_messageBox {args} { lappend ::msgbox_calls $args; return "ok" }')
+
+      poll_until_ready(player) do
+        # Drop two ROM files — should be rejected
+        app.tcl_eval('event generate . <<DropFile>> -data {#{TEST_ROM} /tmp/other.gba}')
+        app.update
+
+        app.after(50) do
+          calls = app.tcl_eval('set ::msgbox_calls')
+          if calls.include?("single")
+            $stdout.puts "PASS"
+          else
+            $stdout.puts "FAIL: no single-file error dialog, calls=\#{calls}"
+          end
+          player.running = false
+        end
+      end
+
+      player.run
+    RUBY
+
+    success, stdout, stderr, _status = tk_subprocess(code)
+
+    output = []
+    output << "STDOUT:\n#{stdout}" unless stdout.empty?
+    output << "STDERR:\n#{stderr}" unless stderr.empty?
+
+    assert success, "Drop multiple files test failed\n#{output.join("\n")}"
+    assert_includes stdout, "PASS", "Expected error dialog for multiple files\n#{output.join("\n")}"
+  end
+
+  # E2E: press F10 to start recording, run a few frames with the red dot
+  # indicator rendering, press F10 to stop, verify .grec file was created.
+  def test_recording_toggle_creates_trec_file
+    skip "Run: ruby gemba/scripts/generate_test_rom.rb" unless File.exist?(TEST_ROM)
+
+    code = <<~RUBY
+      require "gemba"
+      require "tmpdir"
+      require "fileutils"
+      require "support/player_helpers"
+
+      rec_dir = Dir.mktmpdir("gemba-rec-test")
+
+      begin
+        player = Gemba::Player.new("#{TEST_ROM}")
+        app = player.app
+        config = player.config
+        config.recordings_dir = rec_dir
+
+        poll_until_ready(player) do
+          vp = player.viewport
+          frame = vp.frame.path
+
+          # Press F10 → start recording
+          app.command(:event, 'generate', frame, '<KeyPress>', keysym: 'F10')
+          app.update
+
+          # Let a few frames render with the recording indicator (red dot)
+          app.after(50) do
+            unless player.recording?
+              puts "FAIL: recording never started"
+              player.running = false
+              next
+            end
+
+            # Refocus needed under xvfb after timer callbacks
+            app.tcl_eval("focus -force \#{frame}")
+            # Press F10 → stop recording
+            app.command(:event, 'generate', frame, '<KeyPress>', keysym: 'F10')
+            app.update
+
+            app.after(50) do
+              trec_files = Dir.glob(File.join(rec_dir, "*.grec"))
+              if trec_files.empty?
+                puts "FAIL: no .grec file found"
+              elsif File.size(trec_files.first) < 32
+                puts "FAIL: .grec too small (\#{File.size(trec_files.first)} bytes)"
+              else
+                puts "PASS: \#{File.basename(trec_files.first)} (\#{File.size(trec_files.first)} bytes)"
+              end
+
+              player.running = false
+            end
+          end
+        end
+
+        player.run
+      ensure
+        FileUtils.rm_rf(rec_dir) if rec_dir
+      end
+    RUBY
+
+    success, stdout, stderr, _status = tk_subprocess(code)
+
+    output = []
+    output << "STDOUT:\n#{stdout}" unless stdout.empty?
+    output << "STDERR:\n#{stderr}" unless stderr.empty?
+
+    assert success, "Recording toggle test failed\n#{output.join("\n")}"
+    assert_includes stdout, "PASS", "Expected .grec file to be created\n#{output.join("\n")}"
+  end
+
+  # -- Pause CPU optimization (thread_timer_ms) --------------------------------
+
+  def test_event_loop_constants
+    require "gemba/player"
+    assert_equal 1,  Gemba::Player::EVENT_LOOP_FAST_MS, "fast loop should be 1ms"
+    assert_equal 50, Gemba::Player::EVENT_LOOP_IDLE_MS, "idle loop should be 50ms"
+  end
+
+  # E2E: verify thread_timer_ms switches between idle (50ms) and fast (1ms)
+  # when pausing and unpausing the emulator.
+  def test_pause_switches_event_loop_speed
+    skip "Run: ruby gemba/scripts/generate_test_rom.rb" unless File.exist?(TEST_ROM)
+    # Flaky under xvfb: SDL2 INPUT_FOCUS is unreliable, causing focus_poll_tick
+    # to auto-pause and interfere with manual pause/unpause assertions.
+    skip "Flaky under xvfb (SDL2 INPUT_FOCUS unreliable)" if ENV['CI']
+
+    code = <<~RUBY
+      require "gemba"
+      require "support/player_helpers"
+
+      player = Gemba::Player.new("#{TEST_ROM}")
+      app = player.app
+
+      poll_until_ready(player) do
+        # Wait for focus so focus_poll_tick won't interfere with pause/unpause
+        poll_until_focused(player) do
+        vp = player.viewport
+        frame = vp.frame.path
+
+        # Before pause: should be fast (1ms) since ROM is running
+        ms_running = app.interp.thread_timer_ms
+        unless ms_running == 1
+          $stderr.puts "FAIL: expected thread_timer_ms=1 while running, got \#{ms_running}"
+          exit 1
+        end
+
+        # Pause (p key — default hotkey)
+        app.command(:event, 'generate', frame, '<KeyPress>', keysym: 'p')
+        app.update
+
+        app.after(50) do
+          ms_paused = app.interp.thread_timer_ms
+          unless ms_paused == 50
+            $stderr.puts "FAIL: expected thread_timer_ms=50 while paused, got \#{ms_paused}"
+            exit 1
+          end
+
+          # Unpause (p key again)
+          app.tcl_eval("focus -force \#{frame}")
+          app.command(:event, 'generate', frame, '<KeyPress>', keysym: 'p')
+          app.update
+
+          app.after(50) do
+            ms_resumed = app.interp.thread_timer_ms
+            unless ms_resumed == 1
+              xvfb_screenshot("pause_resume_fail")
+              $stderr.puts "FAIL: expected thread_timer_ms=1 after resume, got \#{ms_resumed}"
+              $stderr.puts "input_focus?=\#{player.viewport.renderer.input_focus?}"
+              $stderr.puts "paused=\#{player.instance_variable_get(:@paused)}"
+              exit 1
+            end
+
+            $stdout.puts "PASS"
+            $stdout.puts "running=\#{ms_running} paused=\#{ms_paused} resumed=\#{ms_resumed}"
+            player.running = false
+          end
+        end
+        end # poll_until_focused
+      end
+
+      player.run
+    RUBY
+
+    success, stdout, stderr, _status = tk_subprocess(code)
+
+    output = []
+    output << "STDOUT:\n#{stdout}" unless stdout.empty?
+    output << "STDERR:\n#{stderr}" unless stderr.empty?
+
+    assert success, "Pause event loop speed test failed\n#{output.join("\n")}"
+    assert_includes stdout, "PASS", "Expected PASS in output\n#{output.join("\n")}"
+    assert_match(/running=1 paused=50 resumed=1/, stdout)
+  end
+
+  # E2E: verify focus loss pauses emulation and focus regain resumes it.
+  # Uses thread_timer_ms as a proxy for paused state (50=idle/paused, 1=fast/running).
+  def test_pause_on_focus_loss
+    skip "Run: ruby gemba/scripts/generate_test_rom.rb" unless File.exist?(TEST_ROM)
+    # Flaky under xvfb: SDL2 INPUT_FOCUS is unreliable, so the window may
+    # never report having focus — making focus-loss detection untestable.
+    skip "Flaky under xvfb (SDL2 INPUT_FOCUS unreliable)" if ENV['CI']
+
+    code = <<~RUBY
+      require "gemba"
+      require "support/player_helpers"
+
+      player = Gemba::Player.new("#{TEST_ROM}")
+      app = player.app
+
+      poll_until_ready(player) do
+        renderer = player.viewport.renderer
+
+        # Ensure the window has focus before testing focus *loss*
+        poll_until_focused(player) do
+
+        # Confirm running (fast event loop)
+        ms_running = app.interp.thread_timer_ms
+        unless ms_running == 1
+          $stderr.puts "FAIL: expected running at 1ms, got \#{ms_running}"
+          exit 1
+        end
+
+        # Hide the SDL2 window to drop input focus
+        renderer.hide_window
+
+        # Wait for focus poll to detect the change (polls every 200ms)
+        app.after(300) do
+          ms_lost = app.interp.thread_timer_ms
+          unless ms_lost == 50
+            xvfb_screenshot("focus_loss_fail")
+            $stderr.puts "FAIL: expected paused (50ms) after focus loss, got \#{ms_lost}"
+            $stderr.puts "input_focus?=\#{renderer.input_focus?}"
+            exit 1
+          end
+
+          # WORKAROUND: SDL_ShowWindow/SDL_RaiseWindow don't update
+          # SDL_WINDOW_INPUT_FOCUS without pumping the Cocoa event loop,
+          # so we can't test auto-resume on focus regain here. Instead
+          # we manually unpause with 'p' to verify the auto-pause state
+          # is correct and resumable. The auto-resume path works in
+          # production (Tk's mainloop pumps Cocoa) but is untested in CI.
+          renderer.show_window
+          renderer.raise_window
+          app.command(:event, 'generate', player.viewport.frame.path, '<KeyPress>', keysym: 'p')
+          app.command(:event, 'generate', player.viewport.frame.path, '<KeyRelease>', keysym: 'p')
+
+          app.after(100) do
+            ms_regained = app.interp.thread_timer_ms
+            unless ms_regained == 1
+              $stderr.puts "FAIL: expected resumed (1ms) after manual unpause, got \#{ms_regained}"
+              exit 1
+            end
+
+            $stdout.puts "PASS"
+            player.running = false
+          end
+        end
+        end # poll_until_focused
+      end
+
+      player.run
+    RUBY
+
+    success, stdout, stderr, _status = tk_subprocess(code)
+
+    output = []
+    output << "STDOUT:\n#{stdout}" unless stdout.empty?
+    output << "STDERR:\n#{stderr}" unless stderr.empty?
+
+    assert success, "Pause on focus loss test failed\n#{output.join("\n")}"
+    assert_includes stdout, "PASS", "Expected PASS in output\n#{output.join("\n")}"
+  end
+end