---
id: PLN-0087
ticket: vm-render-parallel-execution-boundary
title: Fix Game2D Packet Overlay Composition
status: done
created: 2026-06-05
ref_decisions: [DEC-0031]
tags: [runtime, renderer, game2d, packet, overlay]
---

## Briefing

`DEC-0031` requires `RenderSubmissionPacket::Game2D` to be a complete frame description. The current active-scene path can bypass the packet and lose `gfx2d` overlay commands.

## Objective

Make Game2D packet consumption identical for active-scene and no-scene frames: scene/layers/sprites first, then `gfx2d` primitives as final overlay.

## Dependencies

- Source decision: `DEC-0031`.
- Existing Game2D packet types in `crates/console/prometeu-hal`.
- Existing publish path in `crates/console/prometeu-drivers`.

## Scope

- Update Game2D render publication so active-scene rendering consumes the packet and applies `gfx2d`.
- Keep Shell UI behavior unchanged.
- Add regression tests for active scene plus primitive overlay.

## Non-Goals

- Do not introduce a render worker.
- Do not change frame pacing, telemetry, lifecycle, or AppMode policy.
- Do not redesign `FrameComposer` beyond what is needed to consume the packet correctly.

## Execution Method

1. Inspect `Hardware::publish_render_submission`, `Gfx::render_game2d_frame_packet`, and `FrameComposer::render_frame`.
2. Replace the active-scene branch that bypasses `Game2DFramePacket` with a packet-consuming path.
3. Ensure `gfx2d` commands are applied after scene/layer/sprite composition in all Game2D branches.
4. Add a test fixture with an active scene and a primitive overlay that would visibly overwrite or mark the composed layer.
5. Add a no-scene regression test if current coverage does not already lock the overlay order.

## Acceptance Criteria

- Active-scene Game2D frames render `gfx2d` after layer/sprite composition.
- No-scene Game2D frames preserve the existing overlay behavior.
- `Hardware::publish_render_submission` does not discard `packet.gfx2d`.
- Tests fail on the old active-scene bypass behavior.

## Tests

- Unit or integration test around Game2D packet publication.
- Pixel/assertion test for overlay-after-scene ordering where practical.
- Existing renderer tests continue to pass.

## Affected Artifacts

- `crates/console/prometeu-drivers/src/hardware.rs`
- `crates/console/prometeu-hal/src/render_submission.rs`
- `crates/console/prometeu-system` or renderer test modules as needed.