Menu narration + code-driven testbed

Pulls menu focus narration forward from Phase 4: it was a blocker, since the
screen name was spoken but not the selected option, so the game could not be
started at all.

Game-file footprint unchanged: still one line in main.lua.

- menus.lua: descriptor driver supporting both D3 backends (upvalue probe and
  patched-announce), sharing one render per screen. Probe self-test included.
- Descriptors for main_menu, settings_menu, load_game, new_game, narration.
- testbed.lua: drives the game by code via love.event.push, so input takes the
  same path as a human keypress. Coroutine-based, and navigates by READING focus
  rather than counting keypresses, which drifts when options are disabled.

Three bugs found by the testbed and fixed:

1. love.keypressed was still bound to the pre-wrapper states.keypressed.
   states.setup() captures love[callback] by value and runs before us, and
   main.lua does not define love.keypressed itself, so wrapping the states table
   field alone had no effect. Now reassigns love.keypressed/textinput.

2. Focus can move with no keypress: main_menu.mousemoved assigns selectedOption
   from cursor position, silently overriding selection including at startup.
   Focus is now polled in the update hook instead of announced only on keypress.

3. Probes sometimes need chaining. narration.keypressed only calls
   continueNarration(), so the text locals are upvalues of that inner function.

Verified: main menu -> new game -> name entry -> intro narration -> gameplay,
8/8 checks passing, including console.print capture and its (x2) fold.

Known gap: ingame_dialogue announces 'Game' and reads no dialogue text.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

accessibility/init.lua

@@ -17,6 +17,19 @@ local speech = require("accessibility.speech")
 local stateNames = require("accessibility.stateNames")
 local hotkeys = require("accessibility.hotkeys")
 local walltones = require("accessibility.walltones")
+local menus = require("accessibility.menus")
+local testbed = require("accessibility.testbed")
+
+local testbedActive = false
+
+-- States we ship focus descriptors for. Also the list the self-test walks.
+local describedStates = {
+	"main_menu",
+	"settings_menu",
+	"load_game",
+	"new_game",
+	"narration",
+}
 
 local initialized = false
 
@@ -59,6 +72,16 @@ function accessibility.selfTest()
 	for name, result in pairs(patchResults) do
 		print("[accessibility] patch " .. name .. ": " .. result)
 	end
+
+	-- Menu focus probes. A renamed local in a future game version surfaces here at
+	-- startup rather than as silence mid-playthrough.
+	local ok, results = pcall(menus.selfTest, describedStates)
+	if ok then
+		for _, stateName in ipairs(describedStates) do
+			print("[accessibility] menu " .. stateName .. ": " .. tostring(results[stateName]))
+		end
+	end
+
 	print("[accessibility] --- end self test ---")
 end
 
@@ -74,10 +97,19 @@ local function hookStates()
 	states.switch = function(newState, params)
 		local result = realSwitch(newState, params)
 
-		-- After the switch, so a state's open() has already set up its focus.
+		-- After the switch, so the state's open() has already set up its focus --
+		-- main_menu, for one, only picks selectedOption inside open().
 		pcall(function()
-			local name = stateNames[newState] or newState
-			speech.say(name, true)
+			local descriptor = menus.loadDescriptor(newState)
+
+			if descriptor then
+				menus.announceScreen(newState)
+				if descriptor.onOpen then
+					speech.say(descriptor.onOpen, false)
+				end
+			else
+				speech.say(stateNames[newState] or newState, true)
+			end
 		end)
 
 		return result
@@ -88,8 +120,25 @@ local function hookStates()
 	local realUpdate = states.update
 	states.update = function(dt)
 		local result = realUpdate(dt)
+
+		-- Poll focus rather than relying on keypress alone.
+		--
+		-- Focus can move with no key involved: main_menu.mousemoved assigns
+		-- selectedOption straight from the cursor position, so wherever the mouse
+		-- happens to rest silently overrides the selection -- including at startup,
+		-- before the player has touched anything. Polling also closes the race
+		-- where a state's open() sets focus after we have already announced.
+		--
+		-- Cheap: two debug.getupvalue lookups, and only for states we describe.
+		pcall(function()
+			menus.announceFocusIfChanged(states.getCurrent())
+		end)
+
 		pcall(walltones.update)
 		pcall(speech.flush)
+		if testbedActive then
+			pcall(testbed.update, dt)
+		end
 		return result
 	end
 
@@ -108,8 +157,43 @@ local function hookStates()
 		end
 
 		pcall(hotkeys.onGameKey)
-		return realKeypressed(key, scancode)
+
+		local keyResult = realKeypressed(key, scancode)
+
+		-- After the game handler, so we read the focus it just moved to.
+		pcall(function()
+			menus.announceFocusIfChanged(states.getCurrent())
+		end)
+
+		return keyResult
 	end
+
+	-- Text entry (character naming) arrives via textinput, not keypressed.
+	local realTextinput = states.textinput
+	states.textinput = function(text)
+		local result = realTextinput(text)
+
+		pcall(function()
+			menus.announceFocusIfChanged(states.getCurrent())
+		end)
+
+		return result
+	end
+
+	-- CRITICAL: re-point the love callbacks at our wrappers.
+	--
+	-- states.setup() runs before us and does:
+	--     love[callback] = love[callback] or states[callback]
+	-- which captures the function BY VALUE. main.lua defines love.load, update,
+	-- mousepressed, mousereleased and quit itself, but NOT keypressed/textinput --
+	-- so those were bound to the original states.keypressed at setup time.
+	-- Replacing the states table field alone leaves love.keypressed pointing at
+	-- the old function and our wrapper never runs.
+	--
+	-- states.switch and states.update are unaffected because they are looked up on
+	-- the table at call time (from state files and from main.lua's love.update).
+	love.keypressed = states.keypressed
+	love.textinput = states.textinput
 end
 
 --------------------------------------------------------------------------------
@@ -137,6 +221,11 @@ function accessibility.initialize()
 	end
 
 	accessibility.selfTest()
+
+	if testbed.isEnabled() then
+		testbedActive = true
+		testbed.start()
+	end
 end
 
 return accessibility