68 lines
2.3 KiB
Markdown
68 lines
2.3 KiB
Markdown
---
|
|
id: PLN-0081
|
|
ticket: render-frame-packet-boundary
|
|
title: Shell Hub Migration
|
|
status: open
|
|
created: 2026-05-25
|
|
ref_decisions: [DEC-0030]
|
|
tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
Source decision: `DEC-0030`.
|
|
|
|
Move Prometeu Hub, shell windows, splash/crash UI, and Shell drawing away from `gfx_mut()` into `gfxui.*` and Shell UI command buffers.
|
|
|
|
## Target
|
|
|
|
Shell-facing UI no longer draws directly into `Gfx`; it produces Shell UI commands that close into `ShellUiFramePacket`.
|
|
|
|
## Scope
|
|
|
|
- Migrate Prometeu Hub UI drawing.
|
|
- Migrate shell windows and window-manager drawing.
|
|
- Migrate splash and crash UI drawing.
|
|
- Remove direct Shell access to `gfx_mut()` for render production.
|
|
- Preserve visible Shell output where behavior is not intentionally changed.
|
|
|
|
## Out of Scope
|
|
|
|
- Designing new Hub visuals.
|
|
- New widget/layout framework.
|
|
- Game mode migration.
|
|
- Debug console replacement.
|
|
|
|
## Execution Sequence
|
|
|
|
1. Inventory Shell, Hub, splash, crash, and firmware drawing callsites that use `gfx_mut()` or direct framebuffer access.
|
|
2. Replace direct primitive drawing with `gfxui.*` buffer writes.
|
|
3. Route Shell frame closure through `RenderManager`.
|
|
4. Ensure Shell UI packets are consumed by the render-surface implementation.
|
|
5. Remove now-unused direct Shell rendering hooks.
|
|
6. Update tests and snapshots for unchanged visible behavior.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- Shell UI production no longer requires mutable `Gfx` access.
|
|
- Hub, shell windows, splash, and crash UI can render through `ShellUiFramePacket`.
|
|
- Shell mode does not use `composer.*` or `gfx2d.*`.
|
|
- Visible UI output is preserved except for approved fixture updates caused by boundary-only refactoring.
|
|
|
|
## Tests / Validation
|
|
|
|
- Add integration tests for Hub/shell frame production.
|
|
- Add tests for splash and crash UI packet output.
|
|
- Run host smoke tests where available.
|
|
- Use pixel or snapshot comparisons for representative Shell screens.
|
|
|
|
## Risks
|
|
|
|
- Firmware and Shell code may mix lifecycle side effects with drawing; split command production without changing lifecycle semantics.
|
|
- Some host tests may assume immediate framebuffer writes; update them to observe submissions or final pixels.
|
|
|
|
## Affected Artifacts
|
|
|
|
- Shell, Hub, firmware, and host integration modules under `crates/`
|
|
- Shell UI tests and fixtures
|