prometeu-runtime/discussion/workflow/plans/PLN-0087-fix-game2d-packet-overlay-composition.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0087	vm-render-parallel-execution-boundary	Fix Game2D Packet Overlay Composition	done	2026-06-05	DEC-0031	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.