---
id: PLN-0080
ticket: render-frame-packet-boundary
title: Shell UI Packet and GfxUI Domain
status: done
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