Hub Suspended Game Kill Affordance
This commit is contained in:
@@ -0,0 +1,85 @@
|
||||
---
|
||||
id: PLN-0163
|
||||
ticket: hub-suspended-game-kill-affordance
|
||||
title: Render Hub Suspended Game Kill Control
|
||||
status: open
|
||||
created: 2026-07-05
|
||||
ref_decisions: [DEC-0040]
|
||||
tags: [hub, lifecycle, game, ui]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
DEC-0040 requires the Hub to show a red bottom-right control when a `Game` cartridge is resident/suspended, displaying only the game title and killing the game immediately on click.
|
||||
|
||||
## Objective
|
||||
|
||||
Render and handle the Hub suspended-game kill control using the lifecycle operation from PLN-0164.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: DEC-0040.
|
||||
- Depends on PLN-0164 for the callable resident-game termination operation.
|
||||
|
||||
## Scope
|
||||
|
||||
- Show a red box in the bottom-right of the Hub only when a `Game` is resident/suspended.
|
||||
- Render only the suspended game's title in that box.
|
||||
- Register a click/hitbox for the box.
|
||||
- On click, call the canonical resident-game termination operation.
|
||||
- Keep the Hub active after the click.
|
||||
- Remove the indicator immediately after the resident game is no longer present.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not add confirmation or two-click arming.
|
||||
- Do not show shell/system apps in this control.
|
||||
- Do not redesign the Hub layout beyond the minimal bottom-right control.
|
||||
- Do not add save-state or suspend-state management.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Identify the Hub rendering and input code.
|
||||
- Primary target: `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`.
|
||||
- Determine how Hub cards/buttons currently compute layout and hit testing.
|
||||
|
||||
2. Add resident-game status to the Hub view model.
|
||||
- Read only `Game` resident/suspended state.
|
||||
- Include the game title needed for display.
|
||||
- Keep the value absent for shell/system apps and for no resident game.
|
||||
|
||||
3. Render the kill control.
|
||||
- Position it in the bottom-right of the internal viewport.
|
||||
- Use a red filled box with restrained dimensions.
|
||||
- Draw only the game title.
|
||||
- Keep the text inside the box for long titles by truncating or fitting according to existing Hub text conventions.
|
||||
|
||||
4. Add click handling.
|
||||
- Use the box hit region.
|
||||
- On click, call the resident-game termination operation from PLN-0164.
|
||||
- Do not navigate away from Hub.
|
||||
- Ensure the next Hub frame no longer renders the control when the resident game is gone.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] The control appears in Hub only while a `Game` resident/suspended game exists.
|
||||
- [ ] The control displays only the game title.
|
||||
- [ ] The control is visually red and placed in the bottom-right of the Hub.
|
||||
- [ ] Clicking the control kills the resident game immediately.
|
||||
- [ ] The Hub remains in Hub after the click.
|
||||
- [ ] The control disappears after the game is killed.
|
||||
- [ ] Shell/system apps do not appear in this control.
|
||||
|
||||
## Tests
|
||||
|
||||
- Hub render/unit test for presence when a resident `Game` exists.
|
||||
- Hub render/unit test for absence when no resident game exists.
|
||||
- Hub render/unit test for absence for non-Game app modes.
|
||||
- Hub click/hitbox test proving the termination operation is invoked.
|
||||
- Test for long title handling if existing Hub layout tests cover text bounds.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`
|
||||
- Any Hub facade/view-model modules used by the program
|
||||
- Hub rendering/input tests
|
||||
@@ -0,0 +1,93 @@
|
||||
---
|
||||
id: PLN-0164
|
||||
ticket: hub-suspended-game-kill-affordance
|
||||
title: Expose Resident Game Termination Contract
|
||||
status: open
|
||||
created: 2026-07-05
|
||||
ref_decisions: [DEC-0040]
|
||||
tags: [hub, lifecycle, game, ui]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
DEC-0040 requires the Hub kill affordance to reuse the same resident-game termination path used by cartridge switching. This plan creates the lifecycle/runtime contract that the Hub UI can call without duplicating cleanup logic.
|
||||
|
||||
## Objective
|
||||
|
||||
Expose a single SystemOS/Firmware operation that terminates the current resident `Game` cartridge from Hub context and performs the complete cleanup required by DEC-0040.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: DEC-0040.
|
||||
- Related lifecycle behavior: DSC-0043 / DEC-0039 cartridge switch orchestrator.
|
||||
- Must be completed before PLN-0163 can wire the Hub UI click.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add or reuse a resident-game termination operation in SystemOS lifecycle/facade code.
|
||||
- Ensure the operation closes task/process lifecycle state.
|
||||
- Ensure the operation removes the VM session and resident game state.
|
||||
- Ensure render ownership returns to Shell/Hub.
|
||||
- Ensure game audio pause/lifecycle state is cleared.
|
||||
- Ensure Game2D composer scene binding/cache state is cleared.
|
||||
- Ensure cartridge asset manager state and physical memory banks are cleared.
|
||||
- Emit an explicit `INFO` log for manual Hub kill.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not change cartridge switching semantics except to reuse the same termination path.
|
||||
- Do not add Hub UI rendering or hit testing; that belongs to PLN-0163.
|
||||
- Do not add confirmation semantics; DEC-0040 explicitly rejects confirmation for this version.
|
||||
- Do not support shell/system app killing through this affordance.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Locate the current game switch termination path in firmware/SystemOS lifecycle code.
|
||||
- Files: `crates/console/prometeu-firmware/src/firmware/`, `crates/console/prometeu-system/src/`.
|
||||
- Confirm which function currently closes the resident game before switching cartridges.
|
||||
|
||||
2. Extract or expose a named resident-game termination operation.
|
||||
- The operation must be callable from Hub context without a target cartridge.
|
||||
- It must return an explicit status: no resident game, terminated game, or failure if the lifecycle cannot close cleanly.
|
||||
- It must preserve existing switch behavior by making switch call the same operation or a shared internal helper.
|
||||
|
||||
3. Wire complete cleanup into that operation.
|
||||
- Close task/process lifecycle state.
|
||||
- Remove the VM session and resident game state.
|
||||
- Transition render ownership to Shell/Hub.
|
||||
- Clear game lifecycle audio pause state.
|
||||
- Unbind `Game2D` scene/composer state.
|
||||
- Shutdown cartridge assets and clear physical memory banks.
|
||||
|
||||
4. Emit the manual kill log.
|
||||
- Source must be `HUB` or `POS`.
|
||||
- Level must be `INFO`.
|
||||
- Message must include the killed title, equivalent to `Resident game killed from Hub: <title>`.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] There is one canonical resident-game termination path used by both cartridge switching and Hub manual kill.
|
||||
- [ ] Calling the operation with no resident game is harmless and does not mutate unrelated Hub state.
|
||||
- [ ] Calling the operation with a suspended `Game` closes the task/process and removes the VM session.
|
||||
- [ ] The runtime cannot resume the killed game after the operation.
|
||||
- [ ] Render ownership is Shell/Hub after the operation.
|
||||
- [ ] Game audio pause/lifecycle state is not left active after the operation.
|
||||
- [ ] Composer and cartridge asset/bank state are cleared.
|
||||
- [ ] An explicit INFO log is emitted for Hub manual kill.
|
||||
|
||||
## Tests
|
||||
|
||||
- Unit or integration test around the lifecycle operation:
|
||||
- no resident game is a no-op;
|
||||
- resident game is terminated;
|
||||
- VM session lookup returns none after kill;
|
||||
- resident game state returns none after kill;
|
||||
- render owner is Shell/Hub after kill.
|
||||
- Regression test proving cartridge switch still terminates through the same cleanup behavior.
|
||||
- Asset/composer cleanup assertions should mirror the recent Stress/Dummy switch tests where applicable.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-system/src/`
|
||||
- `crates/console/prometeu-firmware/src/`
|
||||
- Existing switch tests under firmware/SystemOS test modules
|
||||
@@ -0,0 +1,92 @@
|
||||
---
|
||||
id: PLN-0165
|
||||
ticket: hub-suspended-game-kill-affordance
|
||||
title: Validate Hub Kill Flow End To End
|
||||
status: open
|
||||
created: 2026-07-05
|
||||
ref_decisions: [DEC-0040]
|
||||
tags: [hub, lifecycle, game, ui]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
DEC-0040 requires that the Hub kill affordance fully terminates the suspended game and prevents resume. PLN-0164 and PLN-0163 provide the operation and UI; this plan validates the full flow end to end.
|
||||
|
||||
## Objective
|
||||
|
||||
Add deterministic tests that exercise Home -> suspended game indicator -> Hub kill -> no resume/no residue.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: DEC-0040.
|
||||
- Depends on PLN-0164 for the termination operation.
|
||||
- Depends on PLN-0163 for Hub UI and click behavior.
|
||||
|
||||
## Scope
|
||||
|
||||
- Cover a real game launch, Home/ESC return to Hub, indicator visibility, click-to-kill, and post-kill cleanup.
|
||||
- Verify task/session/resident state are gone.
|
||||
- Verify render ownership and Hub state are correct.
|
||||
- Verify assets/composer cleanup where observable.
|
||||
- Verify log emission.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not test OS-native window manager shell app closure here.
|
||||
- Do not create new cartridges unless existing Stress/Dummy cartridges cannot cover the scenario.
|
||||
- Do not use timing sleeps or visual/manual assertions as primary evidence.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Extend firmware/SystemOS end-to-end tests.
|
||||
- Primary file: `crates/console/prometeu-firmware/src/firmware/firmware.rs` or a focused SystemOS runtime test if the existing test harness fits better.
|
||||
- Launch `Stress Console` or a simple test cartridge.
|
||||
- Return to Hub through the real Home path.
|
||||
- Assert the resident game remains suspended before kill.
|
||||
|
||||
2. Simulate Hub click on the bottom-right kill control.
|
||||
- Use deterministic coordinates from the Hub layout.
|
||||
- Avoid hard-coded magic numbers if the Hub exposes layout constants/helpers.
|
||||
|
||||
3. Assert lifecycle cleanup.
|
||||
- Resident game task is closed.
|
||||
- Process is stopped.
|
||||
- VM session lookup returns none.
|
||||
- Resident game state returns none.
|
||||
- Foreground owner remains Hub/Shell.
|
||||
- Render owner is Shell/Hub.
|
||||
|
||||
4. Assert resource cleanup.
|
||||
- Composer is unbound.
|
||||
- Cartridge asset slots and physical banks are cleared where existing platform test access permits.
|
||||
- Audio lifecycle pause is not active.
|
||||
|
||||
5. Assert no resume path remains.
|
||||
- Clicking the old resume area or querying resident state must not restore the killed game.
|
||||
- The Hub control must be absent on the next frame.
|
||||
|
||||
6. Assert log evidence.
|
||||
- Recent logs contain an INFO event equivalent to `Resident game killed from Hub: <title>`.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] End-to-end test launches a game and returns to Hub with resident game suspended.
|
||||
- [ ] Test confirms the kill control is present before click.
|
||||
- [ ] Test clicks the control and remains in Hub.
|
||||
- [ ] Test proves the game cannot be resumed after kill.
|
||||
- [ ] Test proves task/session/resident/render/audio/assets/composer cleanup.
|
||||
- [ ] Test proves the explicit INFO log exists.
|
||||
- [ ] Existing cartridge switch tests still pass.
|
||||
|
||||
## Tests
|
||||
|
||||
- `cargo test -p prometeu-firmware`
|
||||
- `cargo test -p prometeu-system`
|
||||
- `cargo test -p prometeu-host-desktop-winit` if host presentation behavior is touched by implementation.
|
||||
- `cargo clippy -p prometeu-system -p prometeu-firmware --all-targets -- -D warnings`
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- Firmware/SystemOS end-to-end tests
|
||||
- Hub tests
|
||||
- Lifecycle/runtime tests
|
||||
@@ -0,0 +1,78 @@
|
||||
---
|
||||
id: PLN-0166
|
||||
ticket: hub-suspended-game-kill-affordance
|
||||
title: Publish Hub Kill Contract Spec And Lesson Hooks
|
||||
status: open
|
||||
created: 2026-07-05
|
||||
ref_decisions: [DEC-0040]
|
||||
tags: [hub, lifecycle, game, ui]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
DEC-0040 introduces a user-visible Hub lifecycle control. Any canonical spec covering Hub, lifecycle, resident games, or cartridge switching must reflect the accepted contract before implementation is considered complete.
|
||||
|
||||
## Objective
|
||||
|
||||
Publish the Hub suspended-game kill contract in the appropriate canonical spec location and prepare the discussion thread for post-execution lessons.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: DEC-0040.
|
||||
- Should run after PLN-0164, PLN-0163, and PLN-0165 identify the exact final module boundaries.
|
||||
|
||||
## Scope
|
||||
|
||||
- Locate canonical specs for Hub behavior, SystemOS lifecycle, resident game state, and cartridge switching.
|
||||
- Add English normative text for the red bottom-right kill affordance.
|
||||
- Document the cleanup contract at the spec level.
|
||||
- Document required log/event behavior.
|
||||
- Leave lesson creation for post-execution housekeeping.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not create lessons before implementation is complete.
|
||||
- Do not move discussion artifacts into legacy docs paths.
|
||||
- Do not reopen DEC-0040 semantics unless implementation proves the contract insufficient.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Locate canonical specs.
|
||||
- Search existing `specs/`, runtime docs, or repository-approved spec paths.
|
||||
- Do not write new normative text under `discussion/lessons/`.
|
||||
|
||||
2. Update Hub spec text.
|
||||
- State that Hub shows a bottom-right red control when a `Game` resident/suspended cartridge exists.
|
||||
- State that the control displays only the game title.
|
||||
- State that click kills immediately and keeps the user in Hub.
|
||||
|
||||
3. Update lifecycle/spec text.
|
||||
- State that manual Hub kill uses the same resident-game termination path as cartridge switching.
|
||||
- State cleanup obligations: task/process, VM session, resident state, render ownership, audio lifecycle, composer, assets, physical banks.
|
||||
- State that the killed game cannot be resumed.
|
||||
|
||||
4. Update logging/spec text if a logging contract exists.
|
||||
- Record the required INFO event and message shape.
|
||||
|
||||
5. Prepare housekeeping note.
|
||||
- After implementation and validation, run discussion housekeeping for DSC-0044 with an English lesson if the implementation yields durable knowledge.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Canonical spec text exists for the Hub kill affordance.
|
||||
- [ ] Spec text is in English.
|
||||
- [ ] Spec text includes visibility, layout, click behavior, cleanup, no-resume behavior, and log event requirements.
|
||||
- [ ] No normative text is added to `discussion/lessons/`.
|
||||
- [ ] `discussion validate` passes after artifact/spec updates.
|
||||
|
||||
## Tests
|
||||
|
||||
- `discussion validate`
|
||||
- Documentation/spec review against DEC-0040
|
||||
- Any repository doc lint/check if present
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- Canonical specs location, to be identified during execution
|
||||
- `discussion/workflow/plans/`
|
||||
- Later `discussion/lessons/` only through housekeeping after implementation
|
||||
Reference in New Issue
Block a user