---
id: PLN-0028
ticket: deferred-overlay-and-primitive-composition
title: Plan - Runtime Frame-End Overlay Integration and Parity
status: accepted
created: 2026-04-18
completed:
tags: [runtime, overlay, frame-composer, no-scene, regression, stress]
---

## Objective

Integrate deferred overlay/debug draining into the runtime frame-end sequence so scene-bound and no-scene frames both present the same final `gfx.*` primitive behavior after `hud_fade`.

## Background

After `PLN-0027`, the overlay/debug subsystem will exist but still needs to be drained in the correct place relative to `FrameComposer.render_frame()`, fades, and present/present-adjacent behavior. This plan closes the observable runtime semantics required by `DEC-0016`.

## Scope

### Included
- runtime frame-end ordering changes
- scene-bound and no-scene parity
- regression coverage for overlay visibility above the canonical game frame
- stress-cartridge adjustments if needed to prove text/primitives now survive frame composition

### Excluded
- broad renderer optimization work
- final repository-wide CI

## Execution Steps

### Step 1 - Insert overlay/debug drain into the frame-end path

**What:**
Drain deferred overlay/debug after canonical game composition is complete.

**How:**
- Update the runtime frame-end path so overlay/debug drain occurs after:
  - `FrameComposer.render_frame()`
  - `scene_fade`
  - `hud_fade`
- Ensure the same ordering is respected in the no-scene path.

**File(s):**
- `crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs`
- `crates/console/prometeu-drivers/src/hardware.rs`
- `crates/console/prometeu-drivers/src/gfx.rs`
- any bridge traits needed by the runtime/hardware path

### Step 2 - Add runtime and driver regressions for final visual ordering

**What:**
Lock the new visible behavior.

**How:**
- Add tests proving `gfx.draw_text(...)` remains visible after scene-backed frame composition.
- Add tests proving the same behavior with no scene bound.
- Add tests proving overlay/debug sits above the canonical game frame rather than being erased by it.

**File(s):**
- `crates/console/prometeu-system/src/virtual_machine_runtime/tests.rs`
- driver-level render tests where helpful

### Step 3 - Update stress/integration fixtures if needed

**What:**
Restore or improve stress scenarios that rely on visible text/primitives.

**How:**
- Update `pbxgen-stress` or related stress fixtures so text/primitives are once again a valid visible overlay signal.
- Keep the stress focused on the new model rather than reintroducing obsolete immediate-write assumptions.

**File(s):**
- `crates/tools/pbxgen-stress/src/lib.rs`
- `test-cartridges/stress-console/*`

## Test Requirements

### Unit Tests
- local ordering tests where runtime integration depends on helper sequencing

### Integration Tests
- runtime tests for scene-bound overlay/debug visibility
- runtime tests for no-scene parity
- stress/tooling validation that text or primitives are visible again as final overlay/debug

### Manual Verification
- run the stress path and visually confirm overlay/debug survives on top of scene/sprites after frame composition

## Acceptance Criteria

- [ ] The runtime drains deferred overlay/debug after canonical game composition and after `hud_fade`.
- [ ] Scene-bound and no-scene paths expose the same overlay/debug semantics.
- [ ] Regression tests prove `draw_text(...)` is no longer erased by scene-backed frame composition.
- [ ] Stress/integration fixtures reflect the new final-overlay semantics where applicable.

## Dependencies

- Source decision: `DEC-0016`
- Depends on `PLN-0027`

## Risks

- If fades are still applied after overlay/debug drain, the visible contract will contradict `DEC-0016`.
- Incomplete parity between scene-bound and no-scene paths would leave runtime behavior mode-dependent.