---
id: PLN-0006
ticket: perf-host-debug-overlay-isolation
title: PR/Plan - [PERF] Host Debug Overlay Isolation
status: open
created: 2026-04-10
updated: 2026-04-10
decisions: [DEC-0007]
tags: [performance, host, gfx]
---

# PR/Plan - [PERF] Host Debug Overlay Isolation

## Briefing
Implementação do isolamento total do overlay de debug no Host Desktop (`prometeu-host-desktop-winit`), removendo o acoplamento com o runtime e o pipeline de `gfx` emulado.

## Decisions de Origem
- `DEC-0007`: [PERF] Host Debug Overlay Isolation.
- `DEC-0005`: [PERF] Push-based Telemetry Model (base para extração de dados).

## Alvo
- `crates/host/prometeu-host-desktop-winit`: Implementação da camada nativa de HUD.
- `crates/runtime`: Exposição de campos de telemetria via API.
- `docs/specs/runtime`: Atualização das especificações de debug e portabilidade.

## Escopo
- **Spec Work:**
    - Atualizar `docs/specs/runtime/10-debug-inspection-and-profiling.md` para remover menções ao HUD emulado.
    - Atualizar `docs/specs/runtime/11-portability-and-cross-platform-execution.md` para reforçar a separação de responsabilidades (Host-side HUD).
- **Code Work:**
    - Expansão da API de telemetria no runtime para incluir todos os dados necessários (Cycles, Memory, Logs).
    - Remoção do código de desenho de texto legado no `runner.rs`.
    - Integração de biblioteca nativa (ex: `egui` ou composição via `pixels`) para renderização do novo overlay no Host.
    - Implementação do toggle via tecla **F1** no `HostRunner`.

## Fora de Escopo
- Implementação de overlay visual em outros hosts (mobile, handheld).
- Alterações na lógica de emulação central (loop de execução).

## Plano de Execucao
1. **Fase 1: Especificações (Spec)**
    - Revisar e atualizar os arquivos de especificação (`10-debug` e `11-portability`).
2. **Fase 2: Runtime Telemetry API (Code)**
    - Garantir que todos os campos de telemetria estejam expostos via atômicos/push-based conforme `DEC-0005`.
3. **Fase 3: Host HUD Implementation (Code)**
    - Integrar o novo motor de HUD no `prometeu-host-desktop-winit`.
    - Conectar os dados da API de telemetria à visualização do HUD.
4. **Fase 4: Cleanup (Code)**
    - Remover hotspots de formatação de strings e draw calls do overlay antigo no Host.

## Criterios de Aceite
- O overlay de debug é ativado/desativado via tecla **F1**.
- O overlay utiliza fontes TrueType (monospaced) nítidas e fundo semi-transparente.
- O framebuffer emulado não contém pixels do HUD (composição nativa pós-upscaling).
- O custo de ciclos do runtime é idêntico com o overlay ligado ou desligado.

## Tests / Validacao
- **Verificação Visual:** Confirmar a qualidade das fontes e a transparência do novo HUD.
- **Benchmarking:** Comparar os ciclos consumidos por frame com e sem o HUD ativo para provar isolamento.
- **Teste de Regressão:** Garantir que o F1 toggle não afeta a estabilidade do loop de emulação.

## Riscos
- **Overhead no Host:** A renderização nativa (ex: `egui`) pode introduzir overhead no Host Desktop em máquinas muito fracas (geralmente aceitável em Desktop).
- **Sincronização de Telemetria:** Pequeno atraso visual entre o frame renderizado e os dados exibidos se a coleta for puramente assíncrona (aceitável para telemetria de debug).