prometeu-runtime/discussion/workflow/plans/PLN-0134-wire-home-game-list-launch-flow.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0134	system-run-cart	Wire Home Game List Launch Flow	done	2026-07-03	DEC-0036

Briefing

After PLN-0133, SystemOS can discover a local Game library but Home still does not present or launch those entries. This plan wires the discovered library into Prometeu Hub/Home and routes a selected game to firmware LoadCartridge.

Objective

Make Home display a minimal clickable games list and launch the selected Game through a system-owned firmware/SystemOS path, without reintroducing userland run_cart.

Dependencies

• Source decision: DEC-0036.
• PLN-0132 for documented contract.
• PLN-0133 for --games-root plumbing and the internal library entry model.
• Existing Prometeu Hub Home profile and firmware state transitions.

Scope

• Provide the discovered games library to Prometeu Hub/Home.
• Render a minimal Home list showing title, app_id, and app_version.
• Add Home hit-testing/click handling for game entries.
• Extend the system profile action model with a system-owned game launch action.
• Handle that action in firmware/SystemOS by loading the selected cartridge via the existing cartridge loader and entering LoadCartridge.
• On load failure, log/record the error and keep or return the machine to Home.
• Preserve existing native shell launch behavior.

Non-Goals

• No polished launcher UI.
• No icons, screenshots, search, filtering, or marketplace metadata.
• No return-to-Home while a Game is running.
• No Game A -> Home -> Game B foreground orchestration.
• No .pmc launch support.
• No guest syscall.
• No direct-boot behavior changes.

Execution Method

1. Extend the SystemOS/Hub action type currently represented by SystemProfileAction::LaunchNativeShell with a game-launch action that carries a stable reference to the selected library entry or cartridge path.
2. Update the Prometeu Hub state in crates/console/prometeu-system/src/programs/prometeu_hub.rs or its local modules to accept the discovered game entries.
3. Render the Home games list with stable dimensions and simple clickable rows. Rows must display only title, app_id, and app_version for v1.
4. Add hit-testing so selecting a row emits the game-launch action immediately.
5. Update crates/console/prometeu-firmware/src/firmware/steps/firmware_step_hub_home.rs to consume the new action.
6. In the firmware action handler:
   • call the existing cartridge loader for the selected path;
   • on success, return FirmwareState::LoadCartridge(...);
   • on failure, log/record the error and remain in the Home path.
7. Ensure shell launch still works exactly as before.
8. Add unit or integration tests for:
   • Home list presentation data;
   • click-to-action emission;
   • firmware action handling success;
   • firmware action handling failure.

Acceptance Criteria

• Starting the host with --games-root <dir> exposes valid Game entries in Home.
• The Home list displays title, app_id, and app_version.
• Clicking a listed Game routes through a system action and enters LoadCartridge.
• The launch path does not use a guest syscall and does not mention system.run_cart.
• Invalid or failing launch paths remain in Home and record an error.
• Existing native shell Home actions continue to work.
• Direct --run remains separate and unchanged.

Tests

• Run cargo test -p prometeu-system for Hub action and presentation behavior.
• Run cargo test -p prometeu-firmware for firmware transition behavior.
• Run cargo test -p prometeu-host-desktop-winit if runner integration changes.
• Run discussion validate.

Affected Artifacts

• crates/console/prometeu-system/src/programs/prometeu_hub.rs
• crates/console/prometeu-system/src/services/
• crates/console/prometeu-firmware/src/firmware/steps/firmware_step_hub_home.rs
• crates/console/prometeu-firmware/src/firmware/firmware.rs
• crates/host/prometeu-host-desktop-winit/src/runner.rs
• discussion/workflow/plans/PLN-0134-wire-home-game-list-launch-flow.md