prometeu-runtime/discussion/workflow/plans/PLN-0078-classic2d-game-renderer-consumer.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0078	render-frame-packet-boundary	Classic2D Game Renderer Consumer	open	2026-05-25	DEC-0030	gfx renderer runtime frame-composer architecture ui pipeline

Briefing

Source decision: DEC-0030.

Refactor the Classic2D renderer path so it consumes Game2DFramePacket instead of being called directly by FrameComposer or logical producers.

Target

Classic2D remains the concrete Game 2D rasterizer, but its input is a closed packet and its visible pixel output remains equivalent.

Scope

• Add a packet consumer entry point for the current Classic2D/Gfx renderer.
• Replace direct FrameComposer to Gfx calls with packet consumption.
• Keep RGBA8888 output unchanged for existing supported scenes.
• Keep renderer implementation below the logical pipeline boundary.

Out of Scope

• Redesigning scene, sprite, HUD, or primitive semantics.
• Shell UI rendering.
• Backend registry or GPU work.
• Dirty region optimization.

Execution Sequence

1. Locate the current Classic2D/Gfx rendering entry points and FrameComposer call graph.
2. Add a Game2DFramePacket consumer API.
3. Move rendering reads from live composer state to packet data.
4. Update frame execution to pass the closed packet into the renderer through the render surface path.
5. Preserve existing framebuffer dimensions, RGBA8888 format, and pixel behavior.
6. Remove direct producer-to-renderer calls that bypass the packet boundary.

Acceptance Criteria

• Classic2D renders from Game2DFramePacket.
• Logical composer code no longer directly mutates Gfx during frame production.
• Existing Game 2D visual fixtures or tests remain pixel-equivalent except where explicitly updated for the new boundary.

Tests / Validation

• Add packet-to-pixels tests for representative scene, sprite, primitive, and HUD cases.
• Run existing render tests.
• Add regression coverage comparing old expected pixel buffers where available.

Risks

• Packet conversion can accidentally alter draw order; keep tests focused on ordering and final pixels.
• Some current code may depend on side effects from direct Gfx mutation; identify and replace those effects explicitly.

Affected Artifacts

• Classic2D/Gfx renderer modules under crates/
• Render tests and fixtures