gemba 0.1.1 → 0.2.0

data/test/{test_player.rb → test_app_controller.rb}

@@ -16,7 +16,8 @@ class TestMGBAPlayer < Minitest::Test
       require "gemba"
       require "support/player_helpers"
 
-      player = Gemba::Player.new("#{TEST_ROM}")
+      player = Gemba::AppController.new("#{TEST_ROM}")
+      player.disable_confirmations!
       app = player.app
 
       poll_until_ready(player) { player.running = false }
@@ -33,6 +34,122 @@ class TestMGBAPlayer < Minitest::Test
     assert success, "Player should exit cleanly with ROM loaded (no hang)\n#{output.join("\n")}"
   end
 
+  # Quit hotkey works without a ROM loaded (no viewport/SDL2).
+  def test_quit_hotkey_without_rom
+    code = <<~RUBY
+      require "gemba"
+
+      player = Gemba::AppController.new
+      player.disable_confirmations!
+      app = player.app
+
+      app.after(100) do
+        app.tcl_eval("focus -force .")
+        app.command(:event, 'generate', '.', '<KeyPress>', keysym: 'q')
+      end
+
+      player.run
+      puts "PASS"
+    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, "Quit hotkey should work without ROM loaded\n#{output.join("\n")}"
+    assert_includes stdout, "PASS"
+  end
+
+  # View > Game Library returns to picker after loading a ROM.
+  def test_view_menu_game_library_returns_to_picker
+    code = <<~'RUBY'.sub('ROM_PATH', TEST_ROM)
+      require "gemba"
+      require "support/player_helpers"
+
+      player = Gemba::AppController.new("ROM_PATH")
+      player.disable_confirmations!
+      app = player.app
+
+      poll_until(app, timeout_ms: 5_000,
+                 condition: -> { app.tcl_eval('.menubar.view entrycget 0 -state').strip == 'normal' },
+                 label: "View menu entry never became enabled") do
+        puts "BEFORE=#{player.current_view}"
+        app.tcl_eval('.menubar.view invoke 0')
+        app.after(100) do
+          puts "AFTER=#{player.current_view}"
+          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, "View > Game Library should return to picker\n#{output.join("\n")}"
+    assert_includes stdout, "BEFORE=emulator"
+    assert_includes stdout, "AFTER=picker"
+  end
+
+  # File > Quit menu item exits cleanly (invokes the actual menu command).
+  def test_file_menu_quit_without_rom
+    code = <<~RUBY
+      require "gemba"
+
+      player = Gemba::AppController.new
+      app = player.app
+
+      app.after(100) do
+        app.command('.menubar.file', 'invoke', 'last')
+      end
+
+      player.run
+      puts "PASS"
+    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, "File > Quit should exit cleanly\n#{output.join("\n")}"
+    assert_includes stdout, "PASS"
+  end
+
+  # Escape key quits without a ROM loaded.
+  def test_escape_quits_without_rom
+    code = <<~RUBY
+      require "gemba"
+
+      player = Gemba::AppController.new
+      app = player.app
+
+      app.after(100) do
+        app.tcl_eval("focus -force .")
+        app.command(:event, 'generate', '.', '<KeyPress>', keysym: 'Escape')
+      end
+
+      player.run
+      puts "PASS"
+    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, "Escape should quit without ROM loaded\n#{output.join("\n")}"
+    assert_includes stdout, "PASS"
+  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.
@@ -41,11 +158,12 @@ class TestMGBAPlayer < Minitest::Test
       require "gemba"
       require "support/player_helpers"
 
-      player = Gemba::Player.new("#{TEST_ROM}")
+      player = Gemba::AppController.new("#{TEST_ROM}")
+      player.disable_confirmations!
       app = player.app
 
       poll_until_ready(player) do
-        vp = player.viewport
+        vp = player.frame.viewport
         frame = vp.frame.path
 
         # User presses F11 → fullscreen on
@@ -58,8 +176,8 @@ class TestMGBAPlayer < Minitest::Test
           app.update
 
           app.after(50) do
-            # User presses q → quit
-            app.command(:event, 'generate', frame, '<KeyPress>', keysym: 'q')
+            # Trigger quit via virtual event — no focus dependency
+            app.command(:event, 'generate', '.', '<<Quit>>')
           end
         end
       end
@@ -85,11 +203,12 @@ class TestMGBAPlayer < Minitest::Test
       require "gemba"
       require "support/player_helpers"
 
-      player = Gemba::Player.new("#{TEST_ROM}")
+      player = Gemba::AppController.new("#{TEST_ROM}")
+      player.disable_confirmations!
       app = player.app
 
       poll_until_ready(player) do
-        vp = player.viewport
+        vp = player.frame.viewport
         frame = vp.frame.path
 
         # User presses Tab → enable turbo (2x default)
@@ -97,8 +216,8 @@ class TestMGBAPlayer < Minitest::Test
         app.update
 
         app.after(50) do
-          # User presses q → quit (while still in turbo)
-          app.command(:event, 'generate', frame, '<KeyPress>', keysym: 'q')
+          # Trigger quit via virtual event — no focus dependency
+          app.command(:event, 'generate', '.', '<<Quit>>')
         end
       end
 
@@ -118,8 +237,6 @@ class TestMGBAPlayer < Minitest::Test
   # 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"
@@ -129,7 +246,7 @@ class TestMGBAPlayer < Minitest::Test
       # 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}")
+      player = Gemba::AppController.new("#{TEST_ROM}")
       app = player.app
       config = player.config
 
@@ -138,13 +255,12 @@ class TestMGBAPlayer < Minitest::Test
       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')
+        core = player.frame.save_mgr.core
+        # Recompute state_dir after overriding config.states_dir
+        player.frame.save_mgr.state_dir = player.frame.save_mgr.state_dir_for_rom(core)
+        state_dir = player.frame.save_mgr.state_dir
+        # Quick save
+        app.command(:event, 'generate', '.', '<<QuickSave>>')
         app.update
 
         app.after(50) do
@@ -168,7 +284,7 @@ class TestMGBAPlayer < Minitest::Test
 
           # Save again to test backup rotation (after debounce)
           app.after(50) do
-            app.command(:event, 'generate', frame_path, '<KeyPress>', keysym: 'F5')
+            app.command(:event, 'generate', '.', '<<QuickSave>>')
             app.update
 
             app.after(50) do
@@ -185,8 +301,8 @@ class TestMGBAPlayer < Minitest::Test
                 exit 1
               end
 
-              # Quick load (F8)
-              app.command(:event, 'generate', frame_path, '<KeyPress>', keysym: 'F8')
+              # Quick load
+              app.command(:event, 'generate', '.', '<<QuickLoad>>')
               app.update
 
               app.after(50) do
@@ -241,8 +357,6 @@ class TestMGBAPlayer < Minitest::Test
 
   # 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"
@@ -251,7 +365,7 @@ class TestMGBAPlayer < Minitest::Test
 
       states_dir = Dir.mktmpdir("gemba-debounce-test")
 
-      player = Gemba::Player.new("#{TEST_ROM}")
+      player = Gemba::AppController.new("#{TEST_ROM}")
       app = player.app
       config = player.config
 
@@ -259,22 +373,22 @@ class TestMGBAPlayer < Minitest::Test
       config.save_state_debounce = 5.0  # long debounce
 
       poll_until_ready(player) do
-        vp = player.viewport
-        frame_path = vp.frame.path
+        # Recompute state_dir after overriding config.states_dir
+        player.frame.save_mgr.state_dir = player.frame.save_mgr.state_dir_for_rom(player.frame.save_mgr.core)
 
         # First save should succeed
-        app.command(:event, 'generate', frame_path, '<KeyPress>', keysym: 'F5')
+        app.command(:event, 'generate', '.', '<<QuickSave>>')
         app.update
 
         app.after(50) do
-          state_dir = player.save_mgr.state_dir
+          state_dir = player.frame.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.command(:event, 'generate', '.', '<<QuickSave>>')
           app.update
 
           app.after(50) do
@@ -313,8 +427,6 @@ class TestMGBAPlayer < Minitest::Test
   # 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"
@@ -325,7 +437,7 @@ class TestMGBAPlayer < Minitest::Test
       config_dir = Dir.mktmpdir("gemba-settings-test")
       config_path = File.join(config_dir, "settings.json")
 
-      player = Gemba::Player.new("#{TEST_ROM}")
+      player = Gemba::AppController.new("#{TEST_ROM}")
       app = player.app
       config = player.config
 
@@ -397,11 +509,11 @@ class TestMGBAPlayer < Minitest::Test
   # -- Audio fade ramp (pure function, no Tk/SDL2 needed) --------------------
 
   def test_fade_ramp_attenuates_first_samples
-    require "gemba/player"
+    require "gemba/headless"
     # 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)
+    result, remaining = Gemba::EmulatorFrame.apply_fade_ramp(pcm, total, total)
     samples = result.unpack('s*')
 
     # First stereo pair: gain = 1 - 10/10 = 0.0 → should be 0
@@ -416,17 +528,17 @@ class TestMGBAPlayer < Minitest::Test
   end
 
   def test_fade_ramp_returns_remaining_when_pcm_shorter_than_fade
-    require "gemba/player"
+    require "gemba/headless"
     # Only 2 stereo frames but fade wants 10
     pcm = ([20000, 20000] * 2).pack('s*')
-    _result, remaining = Gemba::Player.apply_fade_ramp(pcm, 10, 10)
+    _result, remaining = Gemba::EmulatorFrame.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"
+    require "gemba/headless"
     pcm = ([10000, -10000] * 4).pack('s*')
-    result, remaining = Gemba::Player.apply_fade_ramp(pcm, 0, 10)
+    result, remaining = Gemba::EmulatorFrame.apply_fade_ramp(pcm, 0, 10)
     assert_equal pcm, result, "should not modify samples when remaining is 0"
     assert_equal 0, remaining
   end
@@ -436,8 +548,6 @@ class TestMGBAPlayer < Minitest::Test
   # 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"
@@ -445,11 +555,11 @@ class TestMGBAPlayer < Minitest::Test
       sw_top = Gemba::SettingsWindow::TOP
       sp_top = Gemba::SaveStatePicker::TOP
 
-      player = Gemba::Player.new("#{TEST_ROM}")
+      player = Gemba::AppController.new("#{TEST_ROM}")
       app = player.app
 
       poll_until_ready(player) do
-        vp = player.viewport
+        vp = player.frame.viewport
         frame = vp.frame.path
 
         # 1. Open Settings via menu (Settings > Video = index 0)
@@ -539,13 +649,11 @@ class TestMGBAPlayer < Minitest::Test
   # -- 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
+      player = Gemba::AppController.new
       app = player.app
 
       # Stub tk_messageBox so it never blocks
@@ -557,7 +665,7 @@ class TestMGBAPlayer < Minitest::Test
         app.update
 
         app.after(50) do
-          core = player.core
+          core = player.frame.core
           if core && !core.destroyed?
             $stdout.puts "TITLE=\#{core.title}"
           else
@@ -581,13 +689,11 @@ class TestMGBAPlayer < Minitest::Test
   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
+      player = Gemba::AppController.new
       app = player.app
 
       # Capture tk_messageBox calls instead of blocking
@@ -624,13 +730,11 @@ class TestMGBAPlayer < Minitest::Test
   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
+      player = Gemba::AppController.new
       app = player.app
 
       # Capture tk_messageBox calls instead of blocking
@@ -669,8 +773,6 @@ class TestMGBAPlayer < Minitest::Test
   # 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"
@@ -680,31 +782,26 @@ class TestMGBAPlayer < Minitest::Test
       rec_dir = Dir.mktmpdir("gemba-rec-test")
 
       begin
-        player = Gemba::Player.new("#{TEST_ROM}")
+        player = Gemba::AppController.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')
+          # Start recording via virtual event (no focus needed)
+          app.command(:event, 'generate', '.', '<<RecordToggle>>')
           app.update
 
           # Let a few frames render with the recording indicator (red dot)
           app.after(50) do
-            unless player.recording?
+            unless player.frame.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')
+            # Stop recording via virtual event
+            app.command(:event, 'generate', '.', '<<RecordToggle>>')
             app.update
 
             app.after(50) do
@@ -738,33 +835,76 @@ class TestMGBAPlayer < Minitest::Test
     assert_includes stdout, "PASS", "Expected .grec file to be created\n#{output.join("\n")}"
   end
 
+  # -- Frame stack show/hide ---------------------------------------------------
+
+  # Loads a ROM, verifies the emulator viewport is visible (packed),
+  # then hides it and confirms it's gone. Catches missing show/hide on frames.
+  def test_emulator_frame_show_hide_round_trip
+    code = <<~RUBY
+      require "gemba"
+      require "support/player_helpers"
+
+      player = Gemba::AppController.new("#{TEST_ROM}")
+      app = player.app
+
+      poll_until_ready(player) do
+        vp_path = player.frame.viewport.frame.path
+
+        # Viewport should be visible after ROM load
+        info = app.tcl_eval("pack info \#{vp_path}") rescue ""
+        abort "FAIL: viewport not packed after load" if info.empty?
+
+        # Hide the frame, viewport should disappear
+        player.frame.hide
+        info_after = app.tcl_eval("pack info \#{vp_path}") rescue ""
+        abort "FAIL: viewport still packed after hide" unless info_after.empty?
+
+        # Show it again
+        player.frame.show
+        info_restored = app.tcl_eval("pack info \#{vp_path}") rescue ""
+        abort "FAIL: viewport not packed after show" if info_restored.empty?
+
+        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, "Frame show/hide round-trip failed\n#{output.join("\n")}"
+    assert_includes stdout, "PASS"
+  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"
+    require "gemba/headless"
+    assert_equal 1,  Gemba::AppController::EVENT_LOOP_FAST_MS, "fast loop should be 1ms"
+    assert_equal 50, Gemba::AppController::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']
+    skip "Flaky under xvfb: SDL2 INPUT_FOCUS is unreliable"
 
     code = <<~RUBY
       require "gemba"
       require "support/player_helpers"
 
-      player = Gemba::Player.new("#{TEST_ROM}")
+      player = Gemba::AppController.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
+        vp = player.frame.viewport
         frame = vp.frame.path
 
         # Before pause: should be fast (1ms) since ROM is running
@@ -795,8 +935,8 @@ class TestMGBAPlayer < Minitest::Test
             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)}"
+              $stderr.puts "input_focus?=\#{player.frame.viewport.renderer.input_focus?}"
+              $stderr.puts "paused=\#{player.frame.paused?}"
               exit 1
             end
 
@@ -825,20 +965,17 @@ class TestMGBAPlayer < Minitest::Test
   # 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']
+    skip "Flaky under xvfb: SDL2 INPUT_FOCUS is unreliable"
 
     code = <<~RUBY
       require "gemba"
       require "support/player_helpers"
 
-      player = Gemba::Player.new("#{TEST_ROM}")
+      player = Gemba::AppController.new("#{TEST_ROM}")
       app = player.app
 
       poll_until_ready(player) do
-        renderer = player.viewport.renderer
+        renderer = player.frame.viewport.renderer
 
         # Ensure the window has focus before testing focus *loss*
         poll_until_focused(player) do
@@ -871,8 +1008,8 @@ class TestMGBAPlayer < Minitest::Test
           # 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.command(:event, 'generate', player.frame.viewport.frame.path, '<KeyPress>', keysym: 'p')
+          app.command(:event, 'generate', player.frame.viewport.frame.path, '<KeyRelease>', keysym: 'p')
 
           app.after(100) do
             ms_regained = app.interp.thread_timer_ms
@@ -900,4 +1037,135 @@ class TestMGBAPlayer < Minitest::Test
     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
+
+  # Regression: on Linux/Windows the window may not have focus at startup,
+  # causing focus_poll_tick to immediately pause the emulator. Loading a ROM
+  # should always start in a running (unpaused) state regardless of focus.
+  def test_rom_does_not_start_paused
+    code = <<~RUBY
+      require "gemba"
+      require "support/player_helpers"
+
+      player = Gemba::AppController.new("#{TEST_ROM}")
+      app = player.app
+
+      poll_until_ready(player) do
+        # Give focus poll a chance to fire (polls every 200ms)
+        app.after(400) do
+          ms = app.interp.thread_timer_ms
+          paused = player.frame.paused?
+          if paused
+            $stderr.puts "FAIL: ROM started paused (thread_timer_ms=\#{ms})"
+            exit 1
+          end
+          $stdout.puts "PASS"
+          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, "ROM started paused\n#{output.join("\n")}"
+    assert_includes stdout, "PASS", "Expected PASS in output\n#{output.join("\n")}"
+  end
+
+  def test_question_hotkey_shows_help_window
+    code = <<~RUBY
+      require "gemba"
+
+      player = Gemba::AppController.new
+      app = player.app
+
+      app.after(100) do
+        app.command(:event, 'generate', '.', '<<ToggleHelpWindow>>')
+        app.update
+        state = app.tcl_eval("wm state .help_window")
+        puts state == 'normal' ? "PASS" : "FAIL: help window not visible (state=\#{state})"
+        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, "? hotkey should show help window\n#{output.join("\n")}"
+    assert_includes stdout, "PASS", "Expected PASS in output\n#{output.join("\n")}"
+  end
+
+  def test_question_hotkey_toggles_help_window
+    code = <<~RUBY
+      require "gemba"
+
+      player = Gemba::AppController.new
+      app = player.app
+
+      app.after(100) do
+        # First press — show
+        app.command(:event, 'generate', '.', '<<ToggleHelpWindow>>')
+        app.update
+        # Second press — hide
+        app.command(:event, 'generate', '.', '<<ToggleHelpWindow>>')
+        app.update
+        state = app.tcl_eval("wm state .help_window")
+        puts state == 'withdrawn' ? "PASS" : "FAIL: help window still visible after second ? press (state=\#{state})"
+        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, "second ? press should hide help window\n#{output.join("\n")}"
+    assert_includes stdout, "PASS", "Expected PASS in output\n#{output.join("\n")}"
+  end
+
+  def test_help_window_hidden_in_fullscreen
+    code = <<~RUBY
+      require "gemba"
+
+      player = Gemba::AppController.new
+      app = player.app
+
+      app.after(100) do
+        # Go fullscreen via bus
+        Gemba.bus.emit(:request_fullscreen)
+        app.update
+        # Toggle help — should be suppressed in fullscreen
+        app.command(:event, 'generate', '.', '<<ToggleHelpWindow>>')
+        app.update
+        exists = app.tcl_eval("winfo exists .help_window")
+        state = exists == '1' ? app.tcl_eval("wm state .help_window") : 'withdrawn'
+        puts state != 'normal' ? "PASS" : "FAIL: help window visible in fullscreen"
+        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, "? hotkey should be suppressed in fullscreen\n#{output.join("\n")}"
+    assert_includes stdout, "PASS", "Expected PASS in output\n#{output.join("\n")}"
+  end
 end