---
id: PLN-0084
ticket: render-frame-packet-boundary
title: Host Debug Overlay Removal
status: done
created: 2026-05-25
ref_decisions: [DEC-0030]
tags: [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