prometeu-runtime/discussion/workflow/plans/PLN-0077-composer-buffer-and-game2d-packet.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0077	render-frame-packet-boundary	Composer Buffer and Game2D Packet	done	2026-05-25	DEC-0030	gfx renderer runtime frame-composer architecture ui pipeline

Briefing

Source decision: DEC-0030.

Convert current composer.* frame state into a mutable ComposerBuffer that closes into Game2DFramePacket at frame boundary.

Target

Game 2D scene, camera, sprites, HUD, and frame orchestration are represented as domain-owned state until RenderManager closes them into a typed packet.

Scope

• Add ComposerBuffer.
• Move scene, camera, sprite, HUD, layer ordering, and Game 2D orchestration state into the buffer.
• Close the buffer into Game2DFramePacket.
• Preserve the v1 four-layer scene/sprite composition model and HUD-above-game rule.
• Ensure fade is absent from Game 2D packet state.

Out of Scope

• Primitive gfx2d.* command buffering.
• Shell UI packet work.
• Renderer consumption refactor beyond packet shape.
• New Game 2D features.

Execution Sequence

1. Locate current FrameComposer, composer syscalls, scene/camera/sprite/HUD state, and tests.
2. Introduce ComposerBuffer and migrate composer mutation paths into it.
3. Implement closure into Game2DFramePacket with immutable packet contents.
4. Preserve integer layer ordering across the four Game 2D layers and HUD final composition.
5. Route frame closure through RenderManager.
6. Update tests that currently inspect FrameComposer internals.

Acceptance Criteria

• composer.* owns Game 2D high-level frame state.
• Closed Game2DFramePacket contains all data required by the Game 2D renderer without live VM or Gfx access.
• Scene/sprite layer behavior and HUD ordering are preserved.
• Fade is not represented.

Tests / Validation

• Add unit tests for buffer mutation and packet closure.
• Add composition ordering tests for scene, sprites, and HUD.
• Run current frame composer/render tests and compare existing expected output.

Risks

• Existing composer code may mix orchestration with drawing; split state capture from rendering before deeper migration.
• Layer behavior is user-visible and must not drift.

Affected Artifacts

• Composer/frame-composer modules under crates/
• Game 2D tests