moved app_mode to its own file

This commit is contained in:
2026-05-22 09:07:10 +01:00
parent 70c6bd17c8
commit 88ac752d9e
20 changed files with 24 additions and 886 deletions
@@ -1,107 +0,0 @@
---
id: PLN-0062
ticket: prometeu-hub-ui-direction
title: Native Shell Launch and Lifecycle Wiring
status: done
created: 2026-05-15
ref_decisions: [DEC-0028]
tags: [hub, ui, shell, system-apps, lifecycle, design-system]
---
## Briefing
Implement the OS/Firmware wiring required by `DEC-0028` so the Hub can emit a launch intent for `ShellA` or `ShellB`, and SystemOS/Firmware can create a native Shell task, create a task-owned window, run the Shell state, close through lifecycle, and return to Hub/Home.
Source decision: `DEC-0028`.
## Objective
Make the launch/close path architecturally correct before the visual slice depends on it:
- Hub emits launch intent.
- SystemOS/Firmware creates native Shell task/process.
- The Shell app has a `WindowOwner::Task(task_id)` window.
- Close uses `os.lifecycle().close_task(task_id)`.
- `ShellRunningStep` returns to Hub/Home after close.
## Dependencies
- `DEC-0028` must remain accepted.
- This plan should execute before `PLN-0064`, because the UI buttons need a real launch target.
- This plan may execute before or alongside `PLN-0063` if tests can trigger Hub actions without mouse input.
## Scope
- Update the Hub update result shape so it can report launch/close actions, not only crashes.
- Add native fake Shell app identity for `ShellA` and `ShellB`.
- Wire Firmware/SystemOS launch handling from Hub intent to `sessions().create_native_shell_task(...)`.
- Create and focus a task-owned window for the launched native Shell task.
- Ensure app close routes to lifecycle close, not only window removal.
- Preserve the existing task-owned window liveness rule in `ShellRunningStep`.
## Non-Goals
- No generic app catalog.
- No reusable UI toolkit.
- No game cartridge window model.
- No background/minimize/overlay preservation semantics.
- No controller focus navigation.
- No public spec change unless implementation introduces a new public API.
## Execution Method
1. Inspect current launch state.
- What changes: identify the exact update path from `HubHomeStep` to `PrometeuHub::update_shell_profile` and `ShellRunningStep`.
- How: read the current firmware state transitions and Hub update result.
- Files: `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`, `crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs`, `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`.
2. Replace crash-only Hub output with an action-bearing result.
- What changes: extend or replace `SystemProfileUpdate` so it can carry `LaunchNativeShell(ShellA|ShellB)` and close intent while preserving crash reporting.
- How: add a small enum local to the Hub/system profile boundary; keep visual components free of lifecycle mutation.
- Files: `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs` and firmware call sites.
3. Handle launch in Firmware/SystemOS.
- What changes: when Hub emits launch intent, create the native Shell task through `os.sessions().create_native_shell_task(app_id, title)`.
- How: map `ShellA` and `ShellB` to stable local app ids/titles for this fake-app slice.
- Files: `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`; add helper code in `prometeu-system` only if needed to avoid duplication.
4. Create the task-owned Shell window.
- What changes: after task creation, create and focus a window with `WindowOwner::Task(task_id)`.
- How: use the existing window facade first; introduce a narrow helper only if the launch sequence becomes duplicated or leaks into visual components.
- Files: `crates/console/prometeu-system/src/os/facades/sessions.rs`, `crates/console/prometeu-system/src/os/facades/window.rs`, or firmware step depending on the smallest clean integration point.
5. Route close through lifecycle.
- What changes: app/window close must call `os.lifecycle().close_task(task_id)` or emit an equivalent action handled by Firmware/SystemOS.
- How: keep window removal separate from lifecycle semantics; do not treat `close_window` as app close.
- Files: `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`, `crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs`.
6. Add behavior tests.
- What changes: add tests proving launch creates native Shell task/window and close returns to Hub.
- How: test at SystemOS/Firmware boundary rather than only manager internals.
- Files: existing firmware/system test modules, preferably near current lifecycle/window tests.
## Acceptance Criteria
- [x] Launching `ShellA` creates a native Shell task/process.
- [x] Launching `ShellB` creates a native Shell task/process.
- [x] Each launched Shell app receives a focused `WindowOwner::Task(task_id)` window.
- [x] Closing the Shell app closes lifecycle state through `os.lifecycle().close_task(task_id)`.
- [x] Closing the Shell app returns firmware to `HubHome`.
- [x] Hub visual code does not directly mutate task/process managers.
- [x] Existing shell liveness behavior remains intact.
## Tests
- Unit tests for any new Hub action enum or mapping logic.
- SystemOS tests for any new helper/facade that creates native Shell task plus task-owned window.
- Firmware tests for HubHome launch to ShellRunning and ShellRunning close to HubHome.
- Regression tests for `focused_window_belongs_to_task(task_id)` behavior if touched.
## Affected Artifacts
- `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs`
- `crates/console/prometeu-system/src/os/facades/sessions.rs`
- `crates/console/prometeu-system/src/os/facades/window.rs`
- Existing SystemOS/Firmware tests
@@ -1,89 +0,0 @@
---
id: PLN-0063
ticket: prometeu-hub-ui-direction
title: Hub Mouse Input and Click Routing
status: done
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
- [x] Pointer coordinates are interpreted in the internal 270p coordinate space.
- [x] Clicking the `ShellA` button emits the `ShellA` launch action exactly once per click.
- [x] Clicking the `ShellB` button emits the `ShellB` launch action exactly once per click.
- [x] Clicking the close command emits close intent for the active Shell app.
- [x] Holding the mouse button does not repeatedly launch apps.
- [x] 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`
@@ -1,100 +0,0 @@
---
id: PLN-0064
ticket: prometeu-hub-ui-direction
title: Retro Hub Home and Fake Shell UI
status: done
created: 2026-05-15
ref_decisions: [DEC-0028]
tags: [hub, ui, shell, system-apps, lifecycle, design-system]
---
## Briefing
Implement the visible Hub/Home and fake Shell app surfaces required by `DEC-0028`: a retro/minimalist 270p Hub with two manual buttons, plus green `ShellA` and blue `ShellB` native fake app/window views.
Source decision: `DEC-0028`.
## Objective
Replace the current debug-style window surface with the first Prometeu OS visual identity slice while keeping all UI primitives local and avoiding a reusable toolkit.
## Dependencies
- `PLN-0062` should provide the launch/close/lifecycle wiring.
- `PLN-0063` should provide click routing.
- `PLN-0065` may provide pixel font rendering; this plan must still remain executable with current text rendering if font integration is deferred.
## Scope
- Full 270p Hub/Home composition.
- Retro/minimalist palette, borders, panels, and two clickable launch buttons.
- Local drawing primitives for panel/frame/button/highlight only when needed.
- `ShellA` fake app view as green.
- `ShellB` fake app view as blue.
- App/window chrome with close affordance.
- Clear visual separation between Hub/Home and Shell app state.
## Non-Goals
- No full UI toolkit.
- No generic app catalog.
- No Tabs/List/Status bar/Footer/help bar.
- No controller focus UI.
- No production app plugin model.
- No game cartridge visual changes.
## Execution Method
1. Define the 270p layout constants.
- What changes: establish local coordinates for Hub background, title area, two buttons, and optional simple panel/frame.
- How: use fixed 480x270 logical viewport coordinates consistent with the runtime viewport.
- Files: `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs` or local Hub UI submodule.
2. Add local retro drawing primitives.
- What changes: add small helper functions for panel/frame, button, highlight, and simple text placement.
- How: keep them private/local to the Hub slice; do not expose as a toolkit.
- Files: Hub module or `crates/console/prometeu-system/src/programs/prometeu_hub/` submodules.
3. Render Hub/Home.
- What changes: draw a consistent retro/minimalist Home surface with exactly two launch buttons.
- How: use low-resolution composition, strong outlines, limited color use, and button labels `ShellA` and `ShellB`.
- Files: Hub render path.
4. Render native fake Shell app views.
- What changes: draw `ShellA` as a green app/window and `ShellB` as a blue app/window, with a visible close command.
- How: use the task-owned window information and app identity established by `PLN-0062`.
- Files: Hub render path and any local fake-app state/mapping.
5. Keep visual state separate from lifecycle state.
- What changes: UI code may know the current view/app identity but must not mutate lifecycle directly.
- How: return actions to the boundary defined by `PLN-0062`.
- Files: Hub update/render code.
6. Add lightweight tests for layout/action coupling.
- What changes: ensure visible button rects match clickable rects from `PLN-0063`.
- How: put button definitions in a shared local data structure used by render and hit testing.
- Files: Hub module tests.
## Acceptance Criteria
- [x] Hub/Home renders full-screen in the 270p viewport.
- [x] Hub/Home shows exactly two manual launch buttons: `ShellA` and `ShellB`.
- [x] The visual style is retro/minimalist with strong borders and limited palette.
- [x] `ShellA` renders as a simple green native fake Shell app/window.
- [x] `ShellB` renders as a simple blue native fake Shell app/window.
- [x] Each Shell app view exposes a visible close command.
- [x] Local primitives are not exported as a general toolkit.
- [x] No Tabs/List/Status bar/Footer/help bar are added in this wave.
## Tests
- Unit tests for shared local layout/button definitions.
- Compile and runtime tests from `PLN-0062` and `PLN-0063`.
- Manual desktop verification of the full flow: Hub -> ShellA -> close -> Hub -> ShellB -> close -> Hub.
- Screenshot/manual visual check at 480x270 internal composition if repository tooling supports it.
## Affected Artifacts
- `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`
- Possible local modules under `crates/console/prometeu-system/src/programs/prometeu_hub/`
- Tests colocated with Hub module
@@ -1,103 +0,0 @@
---
id: PLN-0065
ticket: prometeu-hub-ui-direction
title: Pixel Operator Font Integration
status: done
created: 2026-05-15
ref_decisions: [DEC-0028]
tags: [hub, ui, shell, system-apps, lifecycle, design-system]
---
## Briefing
Integrate the already-available Pixel Operator font asset into the first Hub UI slice when the existing rendering path can support it without creating a new public font system.
Source decision: `DEC-0028`.
## Objective
Use pixel-style typography for the Hub/Home and fake Shell app labels while keeping font work scoped to the initial UI slice.
## Dependencies
- `DEC-0028` must remain accepted.
- `PLN-0064` can proceed without this plan if font integration exposes unrelated architecture work.
- The asset is expected to exist already under `assets/pixel_operator` or from `assets/pixel_operator.zip`.
## Scope
- Locate and verify the extracted Pixel Operator asset.
- Determine the current text rendering path available to Hub/System UI.
- Add a local font binding or asset loading path if one already fits the runtime.
- Use the font for Hub button labels and simple Shell app text.
- Document any reason this must be deferred.
## Non-Goals
- No general font manager unless one already exists and only needs registration.
- No text layout engine.
- No multilingual shaping.
- No public asset/font spec change unless implementation requires a durable contract.
- No dependency download.
## Execution Method
1. Verify the asset.
- What changes: confirm exact files and format under `assets/pixel_operator`.
- How: inspect asset directory and identify usable font/bitmap files.
- Files: `assets/pixel_operator*`.
2. Inspect current text rendering.
- What changes: determine whether Hub can draw text through existing HAL/GFX primitives or asset-backed glyph rendering.
- How: search current text/glyph/font rendering APIs and examples.
- Files: `crates/console/prometeu-hal`, `crates/console/prometeu-system`, current asset/glyph code.
3. Add the narrowest local integration.
- What changes: make Hub text use Pixel Operator if the path is straightforward.
- How: register/load the asset in the same style as existing assets; keep code local to Hub UI if there is no general font contract.
- Files: Hub module and asset-loading modules identified in step 2.
4. Add fallback behavior.
- What changes: if font rendering is not currently suitable, keep the visual slice working with existing text/primitive rendering and record a follow-up.
- How: do not block `PLN-0064` on broad font architecture.
- Files: Hub module and this plan's execution notes.
5. Validate typography use.
- What changes: button labels and simple Shell app labels render legibly in 270p.
- How: manual visual verification plus any available render tests.
- Files: Hub render path.
## Acceptance Criteria
- [x] Pixel Operator asset location and format are verified.
- [x] Hub text rendering uses Pixel Operator when the existing rendering path supports it.
- [x] If deferred, the reason is recorded and `PLN-0064` remains executable.
- [x] No broad font/text toolkit is introduced.
- [x] Text remains legible at 270p.
## Tests
- Compile tests for any asset/font binding.
- Unit tests only if new parsing/registration logic is added.
- Manual visual verification of button labels and Shell labels.
## Affected Artifacts
- `assets/pixel_operator*`
- `crates/console/prometeu-system/src/programs/prometeu_hub/`
- Existing HAL/GFX/asset modules if they already host font or glyph rendering
## Execution Notes
The asset is present under `assets/pixel-operator/` as TrueType files, including:
- `PixelOperator.ttf`
- `PixelOperator8.ttf`
- `PixelOperatorMono.ttf`
- `PixelOperatorMono8.ttf`
The included license is CC0 1.0 Universal.
The current runtime text path does not have a TTF loader, font manager, glyph rasterizer, or asset-backed font registration path. Hub/System UI currently reaches text through `GfxBridge::draw_text`, backed by the built-in 3x5 bitmap glyph path in `crates/console/prometeu-drivers/src/gfx.rs`.
Because `DEC-0028` explicitly forbids expanding this wave into a broad toolkit and this plan forbids introducing a general font manager/text engine, Pixel Operator rendering is deferred. `PLN-0064` remains executable and tested with the existing bitmap text path, which is already pixel-style and legible at 270p.
@@ -1,114 +0,0 @@
---
id: PLN-0066
ticket: prometeu-hub-ui-direction
title: Hub UI Slice Validation and Lesson
status: done
created: 2026-05-15
ref_decisions: [DEC-0028]
tags: [hub, ui, shell, system-apps, lifecycle, design-system]
---
## Briefing
Validate the completed `DEC-0028` implementation family, collect evidence, and prepare the post-execution lesson required by the repository workflow.
Source decision: `DEC-0028`.
## Objective
Prove that the initial Hub retro Shell UI slice satisfies the accepted decision and leave the discussion workflow ready for housekeeping after implementation.
## Dependencies
- `PLN-0062` must be implemented.
- `PLN-0063` must be implemented or explicitly documented as unnecessary because mouse/click was already available.
- `PLN-0064` must be implemented.
- `PLN-0065` must be implemented or explicitly deferred with evidence.
## Scope
- Run relevant crate tests.
- Perform manual desktop verification of the end-to-end flow.
- Check that no forbidden scope leaked into implementation.
- Record evidence in plan execution notes or final implementation summary.
- Draft an English lesson after execution is complete.
## Non-Goals
- No new UI implementation work except small fixes required to satisfy acceptance criteria.
- No new architecture decisions.
- No lesson before code/spec state is published.
- No housekeeping until plans are done.
## Execution Method
1. Run automated tests.
- What changes: execute the crates affected by plans `PLN-0062` through `PLN-0065`.
- How: run targeted cargo tests for firmware/system/host crates.
- Files: test output only; no source changes unless failures expose implementation bugs.
2. Verify end-to-end desktop behavior.
- What changes: manually exercise Hub -> ShellA -> close -> Hub -> ShellB -> close -> Hub.
- How: run the desktop host or project runner used for Hub boot, click the buttons, and observe lifecycle return.
- Files: none, unless bugs are found.
3. Check decision compliance.
- What changes: inspect implementation against `DEC-0028` invariants.
- How: verify no toolkit, no catalog, no Tabs/List/Footer, no direct task/process manager mutation from visual components, and task-owned Shell windows.
- Files: implementation files from the prior plans.
4. Record validation evidence.
- What changes: update the relevant plans or implementation summary with commands run, manual checks, failures, and fixes.
- How: keep evidence concise and tied to acceptance criteria.
- Files: plan artifacts if the workflow records execution notes there.
5. Prepare post-execution lesson.
- What changes: create an English lesson only after implementation is complete and published.
- How: use `discussion-housekeep` when all plans are done; lesson should explain how to think about Hub visual slices without making lessons normative.
- Files: `discussion/lessons/DSC-0036-prometeu-hub-ui-direction/...`.
## Acceptance Criteria
- [x] Automated tests for affected crates pass or failures are documented as unrelated.
- [x] Manual flow passes: Hub -> ShellA -> close -> Hub.
- [x] Manual flow passes: Hub -> ShellB -> close -> Hub.
- [x] Shell windows are task-owned.
- [x] App close uses lifecycle close.
- [x] No complete UI toolkit or catalog was introduced.
- [x] Pixel font integration outcome is recorded.
- [x] A post-execution lesson is ready for housekeeping after plans are marked done.
## Execution Notes
Validation evidence:
- `cargo test -p prometeu-system`: 83 passed.
- `cargo test -p prometeu-firmware`: 17 passed.
- `cargo test -p prometeu-host-desktop-winit`: 25 passed, 5 ignored.
- `discussion validate`: passed.
The ShellA/ShellB flows were verified through firmware integration tests that
simulate Hub click input and Shell close input. A live desktop manual click
session was not run in this environment; the host crate still compiles and its
test suite passes.
Lesson prepared:
- `discussion/lessons/DSC-0036-prometeu-hub-ui-direction/LSN-0045-hub-ui-slices-should-prove-os-boundaries.md`
## Tests
- `cargo test -p prometeu-system`
- `cargo test -p prometeu-firmware`
- `cargo test -p prometeu-host-desktop-winit` if host/input code changed
- Manual desktop host verification
- `discussion validate` after marking plans and housekeeping artifacts
## Affected Artifacts
- Implementation files touched by `PLN-0062` through `PLN-0065`
- `discussion/workflow/plans/PLN-0062-native-shell-launch-and-lifecycle-wiring.md`
- `discussion/workflow/plans/PLN-0063-hub-mouse-input-and-click-routing.md`
- `discussion/workflow/plans/PLN-0064-retro-hub-home-and-fake-shell-ui.md`
- `discussion/workflow/plans/PLN-0065-pixel-operator-font-integration.md`
- Future lesson under `discussion/lessons/DSC-0036-prometeu-hub-ui-direction/`