---
id: PLN-0063
ticket: prometeu-hub-ui-direction
title: Hub Mouse Input and Click Routing
status: open
created: 2026-05-15
ref_decisions: [DEC-0028]
tags: [hub, ui, shell, system-apps, lifecycle, design-system]
---

## Briefing

Implement the input path needed by `DEC-0028`: Hub/Home must support mouse/click activation for the two manual Shell launch buttons and, in Shell app view, for the app/window close command.

Source decision: `DEC-0028`.

## Objective

Provide reliable 270p mouse hit testing and click routing for the initial Hub UI slice without introducing controller navigation or a generic input framework.

## Dependencies

- `DEC-0028` must remain accepted.
- This plan should execute before or alongside `PLN-0064`, because the visual buttons need clickable behavior.
- It depends on existing host pointer mapping if available; if unavailable, this plan must add the narrowest input bridge required for Hub clicks.

## Scope

- Confirm how host mouse coordinates are mapped into the internal framebuffer/viewport.
- Expose pointer position and click edge to the Hub update path.
- Add deterministic hit testing for `ShellA`, `ShellB`, and close controls.
- Preserve current game/controller input behavior.

## Non-Goals

- No controller focus navigation in this wave.
- No keyboard navigation beyond existing debug behavior.
- No drag/drop, resize, window move, scroll, hover menus, or double-click behavior.
- No generic retained-mode UI event system.

## Execution Method

1. Inspect current input bridge.
   - What changes: identify existing pointer position and click signals.
   - How: trace host `winit` input into HAL/runtime input signals.
   - Files: `crates/host/prometeu-host-desktop-winit/src/input.rs`, HAL input signal definitions, firmware context wiring.

2. Add or expose a minimal pointer snapshot.
   - What changes: make Hub update code able to read current pointer coordinates in 270p logical space and click pressed/released edge.
   - How: reuse existing `window_to_fb` mapping and input structures if present; add a small field/method only if needed.
   - Files: host input module, HAL input signal structures, firmware context.

3. Define Hub hit-test rectangles.
   - What changes: create explicit rects for `ShellA`, `ShellB`, and close command.
   - How: keep rect definitions close to the local Hub UI slice so visual and hit target stay synchronized.
   - Files: `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`; optional local submodule if the file grows too large.

4. Route click results to Hub actions.
   - What changes: clicking `ShellA` or `ShellB` emits the launch action from `PLN-0062`; clicking close emits close intent.
   - How: hit test only on click edge; avoid repeated launch while button is held.
   - Files: `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`.

5. Add tests around pure hit-test logic.
   - What changes: test button rect boundaries and click-edge behavior without needing a desktop window.
   - How: isolate hit-test/action selection into pure functions where practical.
   - Files: Hub module tests or a local Hub UI submodule test.

## Acceptance Criteria

- [ ] Pointer coordinates are interpreted in the internal 270p coordinate space.
- [ ] Clicking the `ShellA` button emits the `ShellA` launch action exactly once per click.
- [ ] Clicking the `ShellB` button emits the `ShellB` launch action exactly once per click.
- [ ] Clicking the close command emits close intent for the active Shell app.
- [ ] Holding the mouse button does not repeatedly launch apps.
- [ ] Existing controller/game input paths are not regressed.

## Tests

- Unit tests for hit-test rectangles.
- Unit tests for click edge to action mapping.
- Existing host/system tests to ensure input changes compile across crates.
- Manual verification in desktop host: click `ShellA`, close, click `ShellB`, close.

## Affected Artifacts

- `crates/host/prometeu-host-desktop-winit/src/input.rs`
- HAL input signal definitions, if pointer data is not already exposed
- Firmware context/input plumbing, if needed
- `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`