prometeu-runtime/discussion/workflow/plans/PLN-0136-route-desktop-home-key-outside-guest-input.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0136	foreground-stack-game-pause-shell-vm-backed	Route Desktop Home Key Outside Guest Input	done	2026-07-03	DEC-0037	host input systemos keyboard lifecycle

Briefing

DEC-0037 makes desktop Esc the primary Home/SystemOS request and allows the physical Home key as an alias. This request must be intercepted by the host/SystemOS and must not appear as a guest pad button or input intrinsic.

This plan adds the host input route for the Home request without changing the guest-visible pad surface.

Decisions of Origin

• DEC-0037 - Foreground Stack and Game Pause Contract.

Target

Route desktop Esc and optional physical Home key to a SystemOS Home request outside InputSignals.

Scope

• Extend crates/host/prometeu-host-desktop-winit/src/input.rs or a nearby host input module with a host/system control signal separate from prometeu_hal::InputSignals.
• Map KeyCode::Escape to Home/SystemOS request.
• Map KeyCode::Home as an alias.
• Ensure neither key mutates start_signal, select_signal, or any pad field.
• Route the request through crates/host/prometeu-host-desktop-winit/src/runner.rs into firmware/SystemOS.
• Add tests proving Esc and Home do not affect guest pad state.

Out of Scope

• No pause/resume lifecycle implementation.
• No render ownership gating.
• No guest-visible Home button.
• No gamepad hardware Home mapping unless a future plan defines controller system controls separately.

Execution Plan

1. Define host control state. Add a small host-only type such as HostSystemControls with a home_requested edge or event. Store it in HostInputHandler or in the runner next to the existing input handler.

2. Update keyboard handling. In HostInputHandler::handle_event, recognize KeyCode::Escape and KeyCode::Home on press. Set the host control event and return without modifying InputSignals.

3. Preserve pad mapping. Keep existing pad mappings unchanged: arrows, A/D/W/S, Q/E, Z, and Shift. Do not reuse Start or Select for Home.

4. Route to firmware/SystemOS. In crates/host/prometeu-host-desktop-winit/src/runner.rs, consume the host Home event before or during about_to_wait and call the firmware or SystemOS method introduced by PLN-0137 / PLN-0140.

5. Add tests. Add host input tests for Esc, physical Home, and existing pad mappings. Tests must prove Home produces a system event and no guest pad mutation.

Acceptance Criteria

• Pressing desktop Esc emits a Home/SystemOS host control event.
• Pressing physical Home emits the same event.
• Neither key affects InputSignals.
• Existing guest pad keyboard mappings still work.
• The runner consumes the Home request as a system action.
• The implementation does not add a guest syscall, intrinsic, or pad button.

Tests / Validation

• Add unit tests in prometeu-host-desktop-winit for host input mapping.
• Run cargo test -p prometeu-host-desktop-winit input.
• Run cargo test -p prometeu-hal input if pad signal behavior changes.
• Run discussion validate.

Risks

• Esc may conflict with debugger or window-close expectations. Keep debugger start handling on D unchanged and do not map Esc to process exit.
• Physical Home is not available on every keyboard, so it must remain an alias rather than the primary portable mapping.