97 lines
3.4 KiB
Markdown
97 lines
3.4 KiB
Markdown
---
|
|
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.
|