prometeu-runtime/discussion/workflow/plans/PLN-0084-host-debug-overlay-removal.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0084	render-frame-packet-boundary	Host Debug Overlay Removal	done	2026-05-25	DEC-0030	gfx renderer runtime frame-composer architecture ui pipeline

Briefing

Source decision: DEC-0030.

Remove the current host-owned debug overlay from the render path. Any future console/debug UI is a separate product/domain discussion.

Target

Host rendering no longer injects an inherited debug overlay into Game or Shell output.

Scope

• Identify host-owned debug overlay code and render hooks.
• Remove overlay rendering from the host render path.
• Remove overlay toggles/tests that assume inherited host drawing.
• Preserve non-render telemetry and logging where they are not tied to overlay drawing.

Out of Scope

• Designing a replacement debug console.
• Moving debug UI into gfxui.*.
• Changing telemetry collection.
• Removing unrelated developer diagnostics.

Execution Sequence

1. Inventory debug overlay rendering callsites and tests.
2. Remove host overlay injection from Game and Shell render paths.
3. Delete overlay-specific drawing state, toggles, and fixture expectations.
4. Keep telemetry/logging APIs that do not render overlay pixels.
5. Update docs/specs to state that future debug UI requires a separate decision.
6. Run host and render tests.

Acceptance Criteria

• Host render path does not draw debug overlay pixels.
• Game and Shell output do not depend on host overlay state.
• Remaining diagnostics do not violate the render pipeline boundary.
• Docs do not preserve host overlay as an architectural requirement.

Tests / Validation

• Run host render tests.
• Add or update tests proving overlay state does not affect final rendered output.
• Run rg -n "debug overlay|overlay|DebugOverlay" crates specs discussion/workflow and inspect remaining references.

Risks

• Removing overlay code can accidentally remove useful telemetry; keep non-render diagnostics intact.
• The word overlay may also refer to Game HUD/primitives; distinguish those from host debug overlay.

Affected Artifacts

• Host desktop modules under crates/
• Host/render tests