From 8f74bd2b229e100c2949a45d5ebb8ff047e0352f Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Fri, 15 May 2026 18:00:05 +0100 Subject: [PATCH] implements PLN-0066 hub ui validation lesson --- discussion/index.ndjson | 4 +- ...ub-ui-slices-should-prove-os-boundaries.md | 106 ++++++++++++++++++ ...0066-hub-ui-slice-validation-and-lesson.md | 36 ++++-- 3 files changed, 135 insertions(+), 11 deletions(-) create mode 100644 discussion/lessons/DSC-0036-prometeu-hub-ui-direction/LSN-0045-hub-ui-slices-should-prove-os-boundaries.md diff --git a/discussion/index.ndjson b/discussion/index.ndjson index a0f9a0b9..74bc40e3 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,4 +1,4 @@ -{"type":"meta","next_id":{"DSC":37,"AGD":37,"DEC":29,"PLN":67,"LSN":45,"CLSN":1}} +{"type":"meta","next_id":{"DSC":37,"AGD":37,"DEC":29,"PLN":67,"LSN":46,"CLSN":1}} {"type":"discussion","id":"DSC-0035","status":"done","ticket":"task-owned-shell-windows","title":"Agenda - Task-Owned Shell Windows","created_at":"2026-05-15","updated_at":"2026-05-15","tags":["runtime","os","task","window-manager","shell","lifecycle"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0044","file":"discussion/lessons/DSC-0035-task-owned-shell-windows/LSN-0044-task-window-liveness-belongs-to-the-task.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]} {"type":"discussion","id":"DSC-0034","status":"done","ticket":"system-os-domain-facades","title":"Agenda - SystemOS Domain Facades","created_at":"2026-05-15","updated_at":"2026-05-15","tags":["runtime","os","services","api-surface","lifecycle","fs"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0043","file":"discussion/lessons/DSC-0034-system-os-domain-facades/LSN-0043-systemos-domain-facades.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]} {"type":"discussion","id":"DSC-0023","status":"done","ticket":"perf-full-migration-to-atomic-telemetry","title":"Agenda - [PERF] Full Migration to Atomic Telemetry","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["perf","runtime","telemetry"],"agendas":[{"id":"AGD-0021","file":"AGD-0021-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0008","file":"DEC-0008-full-migration-to-atomic-telemetry.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"plans":[{"id":"PLN-0007","file":"PLN-0007-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"lessons":[{"id":"LSN-0028","file":"discussion/lessons/DSC-0023-perf-full-migration-to-atomic-telemetry/LSN-0028-converging-to-single-atomic-telemetry-source.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]} @@ -34,4 +34,4 @@ {"type":"discussion","id":"DSC-0031","status":"done","ticket":"runtime-mode-separation-game-system","title":"Agenda - Runtime Mode Separation: Game and System","created_at":"2026-05-11","updated_at":"2026-05-14","tags":["runtime","firmware","hub","system-apps","game-mode","scheduler"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0040","file":"discussion/lessons/DSC-0031-runtime-mode-separation-game-system/LSN-0040-system-pipeline-separation.md","status":"done","created_at":"2026-05-14","updated_at":"2026-05-14"}]} {"type":"discussion","id":"DSC-0032","status":"done","ticket":"system-os-lifecycle-process-task-contract","title":"Agenda - SystemOS Lifecycle, Process and Task Contract","created_at":"2026-05-14","updated_at":"2026-05-15","tags":["runtime","os","lifecycle","process","task","shell","firmware"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0041","file":"discussion/lessons/DSC-0032-system-os-lifecycle-process-task-contract/LSN-0041-systemos-lifecycle-authority.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]} {"type":"discussion","id":"DSC-0033","status":"done","ticket":"system-os-service-ownership-and-module-layout","title":"Agenda - SystemOS Service Ownership and Module Layout","created_at":"2026-05-14","updated_at":"2026-05-15","tags":["runtime","os","services","module-layout","vm","window-manager","logging"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0042","file":"discussion/lessons/DSC-0033-system-os-service-ownership-and-module-layout/LSN-0042-systemos-service-ownership-boundary.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]} -{"type":"discussion","id":"DSC-0036","status":"in_progress","ticket":"prometeu-hub-ui-direction","title":"Agenda - Prometeu Hub UI Direction","created_at":"2026-05-15","updated_at":"2026-05-15","tags":["hub","ui","shell","system-apps","lifecycle","design-system"],"agendas":[{"id":"AGD-0036","file":"AGD-0036-prometeu-hub-ui-direction.md","status":"accepted","created_at":"2026-05-15","updated_at":"2026-05-15"}],"decisions":[{"id":"DEC-0028","file":"DEC-0028-prometeu-hub-initial-retro-shell-ui-slice.md","status":"accepted","created_at":"2026-05-15","updated_at":"2026-05-15","ref_agenda":"AGD-0036"}],"plans":[{"id":"PLN-0062","file":"PLN-0062-native-shell-launch-and-lifecycle-wiring.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15","ref_decisions":["DEC-0028"]},{"id":"PLN-0063","file":"PLN-0063-hub-mouse-input-and-click-routing.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15","ref_decisions":["DEC-0028"]},{"id":"PLN-0064","file":"PLN-0064-retro-hub-home-and-fake-shell-ui.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15","ref_decisions":["DEC-0028"]},{"id":"PLN-0065","file":"PLN-0065-pixel-operator-font-integration.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15","ref_decisions":["DEC-0028"]},{"id":"PLN-0066","file":"PLN-0066-hub-ui-slice-validation-and-lesson.md","status":"open","created_at":"2026-05-15","updated_at":"2026-05-15","ref_decisions":["DEC-0028"]}],"lessons":[]} +{"type":"discussion","id":"DSC-0036","status":"in_progress","ticket":"prometeu-hub-ui-direction","title":"Agenda - Prometeu Hub UI Direction","created_at":"2026-05-15","updated_at":"2026-05-15","tags":["hub","ui","shell","system-apps","lifecycle","design-system"],"agendas":[{"id":"AGD-0036","file":"AGD-0036-prometeu-hub-ui-direction.md","status":"accepted","created_at":"2026-05-15","updated_at":"2026-05-15"}],"decisions":[{"id":"DEC-0028","file":"DEC-0028-prometeu-hub-initial-retro-shell-ui-slice.md","status":"accepted","created_at":"2026-05-15","updated_at":"2026-05-15","ref_agenda":"AGD-0036"}],"plans":[{"id":"PLN-0062","file":"PLN-0062-native-shell-launch-and-lifecycle-wiring.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15","ref_decisions":["DEC-0028"]},{"id":"PLN-0063","file":"PLN-0063-hub-mouse-input-and-click-routing.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15","ref_decisions":["DEC-0028"]},{"id":"PLN-0064","file":"PLN-0064-retro-hub-home-and-fake-shell-ui.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15","ref_decisions":["DEC-0028"]},{"id":"PLN-0065","file":"PLN-0065-pixel-operator-font-integration.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15","ref_decisions":["DEC-0028"]},{"id":"PLN-0066","file":"PLN-0066-hub-ui-slice-validation-and-lesson.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15","ref_decisions":["DEC-0028"]}],"lessons":[{"id":"LSN-0045","file":"discussion/lessons/DSC-0036-prometeu-hub-ui-direction/LSN-0045-hub-ui-slices-should-prove-os-boundaries.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]} diff --git a/discussion/lessons/DSC-0036-prometeu-hub-ui-direction/LSN-0045-hub-ui-slices-should-prove-os-boundaries.md b/discussion/lessons/DSC-0036-prometeu-hub-ui-direction/LSN-0045-hub-ui-slices-should-prove-os-boundaries.md new file mode 100644 index 00000000..70e04eb4 --- /dev/null +++ b/discussion/lessons/DSC-0036-prometeu-hub-ui-direction/LSN-0045-hub-ui-slices-should-prove-os-boundaries.md @@ -0,0 +1,106 @@ +--- +id: LSN-0045 +discussion: DSC-0036 +decision: DEC-0028 +title: Hub UI Slices Should Prove OS Boundaries +status: done +created: 2026-05-15 +tags: [hub, ui, shell, lifecycle, window-manager] +--- + +# Hub UI Slices Should Prove OS Boundaries + +## Context + +The first Prometeu Hub visual slice introduced a retro/minimalist Home surface +with two fake native Shell apps, `ShellA` and `ShellB`. The visible work was +small by design: two launch buttons, simple green/blue app windows, mouse click +activation, and a close affordance. + +The important result was not only the look. The slice proved that a system UI +can become more visual without taking ownership away from `SystemOS` and +Firmware. + +## Key Lessons + +### Keep visual intent separate from OS effects + +The Hub now emits explicit system-profile actions for user intent. Launching a +Shell app is represented as an action; Firmware/SystemOS creates the native +Shell task, process, and task-owned window. + +This preserves the useful split: + +```text +Hub renders and navigates +Hub emits intent +Firmware/SystemOS executes lifecycle, task, process, and window ownership +``` + +That split is more important than the exact shape of the first UI. + +### A small visual slice can validate lifecycle + +The implementation deliberately avoided a generic catalog, toolkit, tabs, +footer bar, and controller navigation. Even with that narrow scope, it proved +the critical flow: + +```text +Hub/Home -> ShellA or ShellB -> task-owned window -> close -> lifecycle close -> Hub/Home +``` + +This is the right kind of first UI milestone: it exercises the OS model instead +of only drawing a mock screen. + +### Existing input may be enough for the first cut + +The desktop host already maps pointer state into the runtime touch bridge. The +Hub slice reused that path for mouse/click hit testing instead of inventing a +new input system. + +The result is intentionally simple: button rectangles in 270p space, click-edge +activation, and a close hit target. Controller focus can build on this later, +but it does not need to be solved before the Shell lifecycle flow is proven. + +### Font assets are not the same as font integration + +Pixel Operator is present as TrueType assets under `assets/pixel-operator/`, +but the current runtime text path is a built-in bitmap glyph renderer exposed +through `GfxBridge::draw_text`. + +Deferring TrueType integration was correct because adding a TTF loader, font +manager, rasterizer, or public font contract would have expanded the UI slice +into unrelated architecture. The existing bitmap text remains compatible with +the retro direction until a dedicated font decision exists. + +## Pitfalls + +- Do not let visual components call task/process managers directly. +- Do not treat window removal as app close; Shell app close must go through + lifecycle. +- Do not turn the first two buttons into a generic app catalog by accident. +- Do not introduce a broad UI toolkit before multiple real Hub surfaces need + shared components. +- Do not interpret the Pixel Operator asset as a completed font system. + +## Evidence + +The implementation evidence for this slice was: + +- `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 firmware tests cover launching Shell apps through Hub actions, creating +task-owned windows, and closing through lifecycle back to Hub. The system tests +cover local hit testing and layout/action coupling for the Hub slice. + +## References + +- `DEC-0028` - Prometeu Hub Initial Retro Shell UI Slice. +- `PLN-0062` - Native Shell Launch and Lifecycle Wiring. +- `PLN-0063` - Hub Mouse Input and Click Routing. +- `PLN-0064` - Retro Hub Home and Fake Shell UI. +- `PLN-0065` - Pixel Operator Font Integration. +- `PLN-0066` - Hub UI Slice Validation and Lesson. diff --git a/discussion/workflow/plans/PLN-0066-hub-ui-slice-validation-and-lesson.md b/discussion/workflow/plans/PLN-0066-hub-ui-slice-validation-and-lesson.md index 7e323695..daa75453 100644 --- a/discussion/workflow/plans/PLN-0066-hub-ui-slice-validation-and-lesson.md +++ b/discussion/workflow/plans/PLN-0066-hub-ui-slice-validation-and-lesson.md @@ -2,7 +2,7 @@ id: PLN-0066 ticket: prometeu-hub-ui-direction title: Hub UI Slice Validation and Lesson -status: open +status: done created: 2026-05-15 ref_decisions: [DEC-0028] tags: [hub, ui, shell, system-apps, lifecycle, design-system] @@ -69,14 +69,32 @@ Prove that the initial Hub retro Shell UI slice satisfies the accepted decision ## Acceptance Criteria -- [ ] Automated tests for affected crates pass or failures are documented as unrelated. -- [ ] Manual flow passes: Hub -> ShellA -> close -> Hub. -- [ ] Manual flow passes: Hub -> ShellB -> close -> Hub. -- [ ] Shell windows are task-owned. -- [ ] App close uses lifecycle close. -- [ ] No complete UI toolkit or catalog was introduced. -- [ ] Pixel font integration outcome is recorded. -- [ ] A post-execution lesson is ready for housekeeping after plans are marked done. +- [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