---
id: PLN-0079
ticket: render-frame-packet-boundary
title: Gfx2D Primitive 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`.

Replace primitive Game drawing paths with `gfx2d.*` command buffering while keeping `gfx2d` limited to primitives only.

## Target

Game primitive drawing becomes a Game-mode ABI domain that records commands into a buffer consumed as part of Game 2D rendering.

## Scope

- Add `gfx2d.*` syscall domain and command buffer.
- Migrate primitive Game drawing calls from old `gfx.*` behavior to `gfx2d.*`.
- Ensure `gfx2d` contains primitives only.
- Integrate `gfx2d` commands into the Game 2D packet/render path without taking ownership of scene, camera, sprites, HUD, or frame orchestration.

## Out of Scope

- Shell UI primitive domain.
- `composer.*` high-level Game state.
- Widget/layout policy.
- Compatibility with old primitive `gfx.*` ABI names.

## Execution Sequence

1. Inventory old primitive `gfx.*` syscalls and direct drawing callsites used by Game mode.
2. Define the `gfx2d.*` command enum and mutable command buffer.
3. Route Game primitive syscalls into the buffer.
4. Add app-mode and capability enforcement for Game-only access.
5. Integrate buffered primitives into Game 2D packet closure or renderer consumption at the DEC-0030-approved layer.
6. Remove or retire old primitive `gfx.*` ABI registrations.

## Acceptance Criteria

- Game primitive commands are buffered as `gfx2d.*`.
- `gfx2d` does not own scene, camera, sprites, HUD, or frame orchestration.
- Shell mode cannot call `gfx2d.*`.
- No logical primitive path directly mutates framebuffer during production.

## Tests / Validation

- Add syscall tests for each migrated primitive.
- Add command buffer ordering tests.
- Add capability rejection tests for Shell mode.
- Run pixel-equivalence tests for unchanged primitive output.

## Risks

- The old `gfx` naming may appear in PBS wrappers; distinguish author API names from ABI domain names.
- Primitive ordering relative to composer output must be explicit.

## Affected Artifacts

- Syscall registry and runtime render domain modules under `crates/`
- Game primitive tests