---
id: PLN-0027
ticket: deferred-overlay-and-primitive-composition
title: Plan - Deferred GFX Overlay Subsystem
status: accepted
created: 2026-04-18
completed:
tags: [gfx, runtime, overlay, primitives, text, drivers]
---

## Objective

Introduce a dedicated deferred overlay/debug subsystem for `gfx.*` primitives outside `FrameComposer`, with command capture for `draw_text(...)` and the primitive family selected for the first migration.

## Background

`DEC-0016` requires primitive/text overlay ownership to remain outside `FrameComposer` while still allowing shared raster helpers and low-level optimizations internally. The new subsystem must preserve semantic separation from scene/sprite/HUD composition.

## Scope

### Included
- introduce an overlay/debug command queue or equivalent subsystem outside `FrameComposer`
- route `gfx.draw_text(...)` into deferred command capture instead of stable direct framebuffer writes
- route the chosen V1 primitive family into the same deferred overlay/debug path
- keep raster helper reuse allowed without merging semantic ownership

### Excluded
- runtime frame-end sequencing
- no-scene/scene parity tests at the runtime level
- final repository-wide CI

## Execution Steps

### Step 1 - Define overlay/debug state ownership in drivers

**What:**
Create the subsystem that owns deferred `gfx.*` overlay/debug commands.

**How:**
- Add a dedicated owner adjacent to `Gfx`/`Hardware`, but not inside `FrameComposer`.
- Define the minimal command model required for V1 operations.
- Keep the subsystem screen-space and explicitly pipeline-agnostic relative to `composer.*`.

**File(s):**
- `crates/console/prometeu-drivers/src/*`
- `crates/console/prometeu-hal/src/*` if bridge traits need extension

### Step 2 - Route text and selected primitives into deferred capture

**What:**
Stop treating text/primitives as stable direct writes.

**How:**
- Change `gfx.draw_text(...)` to enqueue deferred overlay/debug work.
- Migrate the selected V1 primitive set into the same deferred path.
- Keep any remaining unmigrated primitives either explicitly out of scope or routed consistently if they are already part of the accepted V1 set.
- Preserve internal raster helper reuse where useful.

**File(s):**
- `crates/console/prometeu-drivers/src/gfx.rs`
- runtime dispatch call sites that submit `gfx.*` primitives

### Step 3 - Add local driver-level tests for deferred capture semantics

**What:**
Prove that overlay/debug commands are captured separately from game composition state.

**How:**
- Add tests that assert text/primitives do not need direct stable writes to `back` to survive until overlay drain.
- Add tests that assert the overlay owner is independent from `FrameComposer` state.

**File(s):**
- `crates/console/prometeu-drivers/src/gfx.rs`
- new or existing driver test modules

## Test Requirements

### Unit Tests
- command capture tests for `draw_text(...)`
- tests for each migrated V1 primitive class
- tests proving overlay/debug state is owned outside `FrameComposer`

### Integration Tests
- none in this plan; runtime-level ordering is covered by the next plan

### Manual Verification
- inspect driver ownership boundaries to confirm `FrameComposer` does not gain overlay/debug state

## Acceptance Criteria

- [ ] A dedicated deferred overlay/debug subsystem exists outside `FrameComposer`.
- [ ] `gfx.draw_text(...)` is captured as deferred overlay/debug work.
- [ ] The selected V1 primitive family is captured through the same subsystem.
- [ ] Driver-level tests prove overlay/debug state is operationally separate from canonical game composition state.

## Dependencies

- Source decision: `DEC-0016`
- Prefer to execute after `PLN-0026`

## Risks

- Accidentally reusing `FrameComposer` storage or state would violate the accepted ownership boundary.
- Migrating only part of the primitive family without explicit scoping could create inconsistent semantics across `gfx.*`.