154 lines
8.8 KiB
Markdown
154 lines
8.8 KiB
Markdown
---
|
|
id: DEC-0028
|
|
ticket: prometeu-hub-ui-direction
|
|
title: Prometeu Hub Initial Retro Shell UI Slice
|
|
status: accepted
|
|
created: 2026-05-15
|
|
ref_agenda: AGD-0036
|
|
tags: [hub, ui, shell, system-apps, lifecycle, design-system]
|
|
---
|
|
|
|
## Context
|
|
|
|
AGD-0036 resolved the first visual direction for Prometeu Hub after the runtime gained the basic SystemOS, lifecycle, task, process, and task-owned window contracts.
|
|
|
|
The target is not a general UI toolkit yet. The target is the first executable Hub/Shell UI slice that establishes the Prometeu OS visual identity and validates the existing lifecycle flow with native fake Shell apps.
|
|
|
|
The accepted agenda narrowed the original "channel grid/list" idea into a smaller wave:
|
|
|
|
- a manual Hub/Home surface rendered in the full 270p viewport;
|
|
- two clickable entries, one for `ShellA` and one for `ShellB`;
|
|
- `ShellA` as a simple green native Shell fake app;
|
|
- `ShellB` as a simple blue native Shell fake app;
|
|
- mouse/click input first;
|
|
- app close initiated from the app/window itself;
|
|
- no Footer/help bar, Tabs, generic List, or complete Channel/Card system in this wave;
|
|
- use of the existing SystemOS session, lifecycle, and window facades unless implementation proves a narrower helper is required.
|
|
|
|
The decision depends on the existing operating model captured by the related lessons:
|
|
|
|
- System apps belong to the Runtime/Hub system pipeline, not the game pipeline.
|
|
- SystemOS owns lifecycle semantics.
|
|
- SystemOS owns shared OS services through domain facades.
|
|
- Shell window liveness is tied to a task-owned focused window.
|
|
|
|
## Decision
|
|
|
|
Prometeu Hub SHALL implement the first retro Shell UI as a narrow, local Hub slice rather than a reusable UI toolkit.
|
|
|
|
The first slice SHALL provide a full-viewport 270p Hub/Home with a retro/minimalist visual style inspired by portable console and fantasy-console UI: low-resolution composition, pixel-style typography, limited color use, strong borders, simple panels, and clear clickable affordances.
|
|
|
|
The first Hub/Home SHALL expose exactly two manual launch buttons:
|
|
|
|
- `ShellA`
|
|
- `ShellB`
|
|
|
|
The first slice SHALL launch two native fake Shell apps:
|
|
|
|
- `ShellA` SHALL render as a simple green app/window.
|
|
- `ShellB` SHALL render as a simple blue app/window.
|
|
|
|
The first slice SHALL use mouse/click input as the initial navigation and activation mechanism. Controller-first focus navigation MAY be added later, but it is not part of this decision's first acceptance surface.
|
|
|
|
The first slice SHALL treat app close as an app/window command. Closing a Shell app MUST result in the corresponding Shell task being closed through SystemOS lifecycle semantics and returning to Hub/Home.
|
|
|
|
The first slice MUST NOT introduce a complete UI toolkit, generic app catalog, channel grid, Tabs, List, Status bar, or Footer/help bar. Small local primitives such as button, panel/frame, text drawing, hover/active highlight, and simple window chrome MAY be created when needed to implement the slice.
|
|
|
|
The Hub MUST remain a visual Shell/Home program:
|
|
|
|
- Hub SHALL render and handle local UI navigation.
|
|
- Hub SHALL emit user-intent actions such as "launch ShellA", "launch ShellB", or "close current Shell app".
|
|
- SystemOS/Firmware SHALL execute lifecycle, task, process, and window ownership effects.
|
|
- Hub MUST NOT directly own VM execution, task/process lifecycle policy, or final window ownership semantics outside SystemOS facades.
|
|
|
|
The implementation SHOULD first attempt to use the existing `sessions()`, `lifecycle()`, and `windows()` facades. A new high-level facade is not required by this decision, but if implementation starts duplicating cross-domain launch/close policy in Hub components, the plan MUST introduce a small SystemOS/Firmware helper instead of spreading that policy through visual code.
|
|
|
|
## Rationale
|
|
|
|
This decision keeps the first UI wave small enough to execute while still validating the important architecture.
|
|
|
|
Building a complete toolkit now would force abstractions before there are enough Hub surfaces to justify them. A local slice lets the project discover real component needs from a concrete Home and two Shell apps.
|
|
|
|
Skipping lifecycle integration would validate only aesthetics and would not prove the console OS model. The first UI slice must exercise the route from Hub/Home to a native Shell task, task-owned window liveness, app close, lifecycle close, and return to Hub.
|
|
|
|
Starting with mouse/click is acceptable because this wave is primarily about visual identity and lifecycle integration. Controller navigation remains part of the broader Hub direction, but making it a hard requirement now would expand the first slice beyond the accepted agenda.
|
|
|
|
Using the existing facades respects the current architecture and avoids inventing a new OS API prematurely. The guardrail is that the Hub may compose calls at a local boundary, but visual components must not become lifecycle or ownership authorities.
|
|
|
|
## Invariants / Contract
|
|
|
|
- The internal composition target for this UI slice is the current 270p viewport.
|
|
- `assets/pixel_operator.zip` or its already-extracted content SHOULD be used for pixel-style typography when the existing rendering/font path can support it without unrelated architecture work.
|
|
- `ShellA` and `ShellB` are fake native Shell apps for lifecycle and UI validation. They MUST NOT be treated as a final app model or plugin/catalog contract.
|
|
- A launched Shell app MUST have task/process state created through SystemOS session/lifecycle pathways.
|
|
- A Shell app window used for liveness MUST be owned by `WindowOwner::Task(task_id)`, not by `WindowOwner::Hub`.
|
|
- Returning to Hub after app close MUST follow lifecycle closure. Removing a window alone is not a valid app-close semantic.
|
|
- The first wave MAY use local Hub UI primitives. Those primitives MUST remain scoped to the slice until a later decision defines a shared toolkit.
|
|
- Game cartridges MUST NOT be pulled into this windowed Shell model by implication. This decision applies to native fake Shell apps only.
|
|
|
|
## Impacts
|
|
|
|
### Specs
|
|
|
|
No canonical runtime spec change is required before the first implementation unless the plan introduces a new public SystemOS, Shell, or asset/font contract. If a new public contract is introduced, the canonical specs must be updated in English.
|
|
|
|
### Runtime / SystemOS
|
|
|
|
Implementation may need small integration work around native Shell launch and task-owned windows. The preferred path is:
|
|
|
|
1. Hub emits a launch intent for `ShellA` or `ShellB`.
|
|
2. Firmware/SystemOS creates the native Shell task through `sessions().create_native_shell_task(...)`.
|
|
3. The launch flow creates/focuses a window owned by `WindowOwner::Task(task_id)`.
|
|
4. `ShellRunningStep` drives the Shell app and returns to Hub when lifecycle/window liveness says the app is closed.
|
|
|
|
If this cannot be expressed cleanly with current facades, the plan may add a narrow helper/facade that coordinates session creation and task-owned window creation.
|
|
|
|
### Hub UI
|
|
|
|
The Hub UI should be reshaped from the current button-to-window debug surface into a first-person Shell/Home surface with:
|
|
|
|
- retro background/panel treatment;
|
|
- two clickable launch buttons;
|
|
- simple hover/active visual state for mouse input;
|
|
- app/window chrome sufficient to expose close from the app/window;
|
|
- clear visual distinction between Hub/Home and an opened Shell app.
|
|
|
|
### Host / Input
|
|
|
|
The first wave relies on existing host mouse mapping/click input if available. Keyboard/controller focus is not required by this decision.
|
|
|
|
### Firmware
|
|
|
|
Firmware remains the coordinator for state transitions between Hub/Home and Shell-running state. It must not delegate lifecycle authority to visual components.
|
|
|
|
### Tooling / Tests
|
|
|
|
Tests should cover the behavior that matters architecturally:
|
|
|
|
- launch `ShellA` creates a native Shell task and task-owned window;
|
|
- launch `ShellB` creates a native Shell task and task-owned window;
|
|
- closing the app closes lifecycle state rather than only removing the window;
|
|
- closed Shell returns to Hub/Home;
|
|
- Hub UI actions do not require direct task/process manager access.
|
|
|
|
## Propagation Targets
|
|
|
|
- specs: only if a new public Shell/SystemOS/font contract is introduced.
|
|
- plans: create an execution plan from this decision before code changes.
|
|
- code: `crates/console/prometeu-system`, `crates/console/prometeu-firmware`, and possibly host/input/rendering code if mouse/font integration requires it.
|
|
- tests: SystemOS/Firmware tests for launch/close/return behavior; UI rendering tests only if the repository already has an appropriate surface.
|
|
- docs: post-execution lesson in English after the implementation is complete.
|
|
|
|
## References
|
|
|
|
- Agenda: AGD-0036
|
|
- `LSN-0040` - System Pipeline Separation
|
|
- `LSN-0041` - SystemOS Lifecycle Authority
|
|
- `LSN-0042` - SystemOS Service Ownership Boundary
|
|
- `LSN-0043` - SystemOS Domain Facades
|
|
- `LSN-0044` - Task Window Liveness Belongs to the Task
|
|
|
|
## Revision Log
|
|
|
|
- 2026-05-15: Initial decision draft from AGD-0036.
|