---
id: PLN-0136
ticket: foreground-stack-game-pause-shell-vm-backed
title: Route Desktop Home Key Outside Guest Input
status: done
created: 2026-07-03
ref_decisions: [DEC-0037]
tags: [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.