prometeu-runtime/discussion/workflow/decisions/DEC-0028-prometeu-hub-initial-retro-shell-ui-slice.md

id	ticket	title	status	created	ref_agenda	tags
DEC-0028	prometeu-hub-ui-direction	Prometeu Hub Initial Retro Shell UI Slice	accepted	2026-05-15	AGD-0036	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.