# 0003 - GUI Framework Decision

Date: 2026-06-19

Status: accepted for full diagnostic UI planning

## Decision

Keep the current dependency-free Win32 skeleton for bootstrap and build
verification.

Use Dear ImGui with the Win32/DX11 backend as the planned framework for the full
diagnostic UI, subject to a later explicit dependency-vendoring task.

## Rationale

Audio Path Tone Tester is a diagnostic instrument, not a consumer music player.
It needs dense, inspectable controls and realtime diagnostic surfaces:

- Backend/device/format/signal/buffer/scheduling controls.
- Collapsible advanced panels for WASAPI, MME, DirectSound, ASIO, DoP, and DSD.
- Tables for device capabilities and format probes.
- Realtime stats panes.
- Initialization and playback logs.
- Error summaries.
- Export buttons and diagnostic bundle status.

Dear ImGui is well suited to this style of tool because it makes dense
instrumentation UI faster to build and easier to iterate than hand-written
Win32 controls, while still fitting a native single-exe style application.

## Guardrails

- Do not add Dear ImGui as part of this decision record.
- Add it only in an explicit queued task.
- Prefer vendoring under a project-local third-party directory or documenting an
  approved dependency retrieval method.
- Preserve one-exe packaging goals.
- Keep audio backend code independent from the GUI framework.
- Do not let GUI convenience hide low-level diagnostic parameters.
- Do not add UI automation as part of the initial ImGui integration.

## Packaging Notes

- Dear ImGui source can be compiled into the executable.
- Win32/DX11 backend uses Windows system components.
- Release builds should remain a single primary `.exe`, aside from system DLLs
  and user-installed audio drivers.

## Rejected Alternatives

### Pure Win32 Controls For Full UI

Rejected for the full diagnostic surface because it would slow iteration and
make dense realtime controls/log panes more cumbersome. The bootstrap skeleton
still uses pure Win32.

### Qt / wxWidgets

Deferred because they add larger framework and packaging decisions before audio
diagnostics are proven.

### Electron / WebView

Rejected for now because this is a native low-level Windows audio diagnostic
tool with one-exe packaging goals.

## Follow-Up

Create a queued task to vendor or otherwise integrate Dear ImGui, build a
non-audio diagnostic UI shell, and prove the app still builds and tests with no
audio-device access.

