---
id: PLN-0081
ticket: render-frame-packet-boundary
title: Shell Hub Migration
status: done
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