67 lines
2.3 KiB
Markdown
67 lines
2.3 KiB
Markdown
---
|
|
id: PLN-0080
|
|
ticket: render-frame-packet-boundary
|
|
title: Shell UI Packet and GfxUI Domain
|
|
status: open
|
|
created: 2026-05-25
|
|
ref_decisions: [DEC-0030]
|
|
tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
Source decision: `DEC-0030`.
|
|
|
|
Add `gfxui.*` command buffering and `ShellUiFramePacket` for Shell UI primitives while keeping widget/layout policy outside the host/render-surface implementation.
|
|
|
|
## Target
|
|
|
|
Shell UI emits typed UI primitive commands into a Shell-only packet that render-surface implementations can consume without collapsing UI and Game ABI domains.
|
|
|
|
## Scope
|
|
|
|
- Define `gfxui.*` primitive commands.
|
|
- Add a mutable Shell UI command buffer.
|
|
- Close Shell UI commands into `ShellUiFramePacket`.
|
|
- Enforce Shell-only capability and app-mode access.
|
|
- Keep widget/layout policy in Shell/UI code or stdlib layers.
|
|
|
|
## Out of Scope
|
|
|
|
- Migrating all Shell callsites; that is handled by the Shell/Hub migration plan.
|
|
- Game primitive rendering.
|
|
- New widget framework.
|
|
- Host-owned debug overlay.
|
|
|
|
## Execution Sequence
|
|
|
|
1. Define the `gfxui.*` syscall and command vocabulary needed for current Shell UI primitives.
|
|
2. Add a Shell UI command buffer and closure into `ShellUiFramePacket`.
|
|
3. Add capability metadata and resolver enforcement for `GFXUI`.
|
|
4. Add a render-surface consumer path that can rasterize Shell UI commands as an implementation detail.
|
|
5. Keep layout/widget decisions above the packet boundary.
|
|
6. Add tests for closure, app-mode gating, and packet consumption.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- Shell UI commands close into `ShellUiFramePacket`.
|
|
- `gfxui.*` does not contain widget/layout policy.
|
|
- Game mode cannot call `gfxui.*`.
|
|
- Host/render-surface code consumes commands without redefining Shell UI product policy.
|
|
|
|
## Tests / Validation
|
|
|
|
- Add Shell UI command buffer unit tests.
|
|
- Add app-mode rejection tests for Game mode.
|
|
- Add render-surface consumer tests for representative primitives.
|
|
|
|
## Risks
|
|
|
|
- It is easy to migrate widget policy into host rendering while adding UI primitives; keep commands low-level and policy-free.
|
|
- Shell UI and Game primitives may rasterize similarly, but ABI domains must remain distinct.
|
|
|
|
## Affected Artifacts
|
|
|
|
- Shell UI render domain modules under `crates/`
|
|
- Syscall metadata and tests
|