prometeu-runtime/discussion/workflow/plans/PLN-0063-hub-mouse-input-and-click-routing.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0063	prometeu-hub-ui-direction	Hub Mouse Input and Click Routing	open	2026-05-15	DEC-0028	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