105 lines
4.3 KiB
Markdown
105 lines
4.3 KiB
Markdown
---
|
|
id: PLN-0134
|
|
ticket: system-run-cart
|
|
title: Wire Home Game List Launch Flow
|
|
status: done
|
|
created: 2026-07-03
|
|
ref_decisions: [DEC-0036]
|
|
tags: []
|
|
---
|
|
|
|
## 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](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/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](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/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`
|