# GUI Information Architecture

Date: 2026-06-20

Audio Path Tone Tester is a Windows audio-path diagnostic tool. The GUI should
make the diagnostic sequence visible while keeping expert controls available
without presenting every parameter at once.

The default presentation is Japanese, light themed, and intentionally calm:
closer to a manufacturer/support utility than a developer demo. See
`docs/UI_JAPANESE_LIGHT_THEME.md` for the tone, language, three-tab workflow,
and font policy.

When English is selected, application-owned visible UI text is expected to be
English-only. Device names and raw driver-supplied strings may remain exactly
as reported by the operating system or driver.

## Layout

The main window is organized into three visible regions:

- Top status ribbon: app version, active backend, selected device, available
  format state, selected test condition, current state, safety/hold mode, last
  backend error, diagnostic bundle path, language control, and Japanese font
  status.
- Three functional tabs:
  - Output Path / `出力経路`: target API, API-scoped refresh, output device,
    automatic device compatibility check, and PCM/DSD compatibility matrices.
  - Test Conditions / `テスト条件`: selected test condition, signal/run
    settings, API-specific buffer and scheduling controls, lifecycle policy,
    start/stop/release actions, export, and automation planning.
  - Logs / `ログ`: logging/safety details, runtime counters, recent logs,
    playback log, error summary, and diagnostic evidence.
- Bottom action bar: a single-row refresh, start, stop/keep-warm, release after
  drain, and export bundle toolbar.

## Workflow Steps

The GUI uses one device-first checker workflow distributed across the three
functional tabs. Low-level controls remain inside that workflow and do not
provide a format-first shortcut.

1. Target Device / `対象デバイス`
   Choose the target API, refresh only that API, and select the sound device to
   inspect from that API list. If physical identity is uncertain, the GUI shows
   separate API rows; changing the target API clears the selected device.

2. Automatic Compatibility Check / `対応状況確認`
   Selecting a target device automatically builds a bounded capability matrix
   for that API/device. The current implementation reuses fresh discovery/probe
   evidence when available; otherwise it performs bounded, non-playback
   compatibility checks before filling the matrix. The automatic check does not
   start playback. MME uses `WAVE_FORMAT_QUERY`, DirectSound creates and releases
   probe buffers, WASAPI calls `IsFormatSupported` without stream
   initialization, Kernel Streaming opens only the selected filter/pin probe
   scope and checks data ranges without setting a stream to RUN, and ASIO uses
   bounded driver queries without opening the control panel or starting a
   stream.

3. Test Matrix / `検査マトリックス`
   Show sample rates as columns and bit/format rows for the selected target API.
   PCM and DSD are shown as separate matrices. This section is named as
   compatibility/status rather than confirmed playback, because some APIs can
   expose candidate-only evidence. Cell statuses include available, unsupported,
   in use, reference information, error, and not applicable.
   Kernel Streaming also uses `範囲一致`, `pin作成OK`, and `開始確認OK`
   to distinguish data-range candidates from stronger verification.
   Kernel Streaming cells also expose the streaming model:
   `KS標準パケット`, `KSループ`, `WaveRT循環バッファ`, or `未確認`.
   `KS標準パケット` and `WaveRT循環バッファ` are implemented playback
   paths when the selected matrix cell has compatible evidence. `KSループ`
   and WaveRT BasicSupport-only detections without an accepted notification
   buffer are displayed as `検出済み / 再生未実装`.
   Selecting a non-stale selectable cell creates the `SelectedTestCondition`.

4. Test Condition / `テスト条件`
   Show the selected device, backend/API path, requested format, accepted
   playback format, signal level/duration, and hold behavior. Signal amplitude,
   duration, and channel-shaping settings do not invalidate the capability
   matrix.

5. Run & Export / `実行 / 書き出し`
   Start only from a current `SelectedTestCondition`, stop to valid
   silence/idle where supported, release explicitly, or export the diagnostic
   bundle.

6. Automation / `自動診断`
   Plan or run only the selected device/test condition. Multi-step stress plans
   remain plan-only unless explicitly implemented in a later task.

7. Logging & Safety / `記録・安全`
   Review diagnostic log settings, safety notes, and selected low-level IDs.
   These settings are part of the same workflow and do not select formats.

## Three Functional Tabs

There is no Standard/Detail/Expert display-mode switch. A control may be
disabled or marked cautionary, but it still belongs to the same target API ->
refresh -> device -> automatic check -> matrix -> test condition -> run/export
sequence.
The tab split is functional, not a mode split: Output Path decides what can be
played, Test Conditions decides how the selected condition will be driven, and
Logs shows what happened. The UI should avoid showing every technical control
at once, but it should also avoid hiding the primary path behind a sidebar step
selector or a separate expert screen.

## Visibility Rules

- The first visible tab is Output Path / `出力経路`.
- Major sections are grouped by function in the three tabs instead of hidden
  behind a sidebar step selector or spread across separate display modes.
- The Output Path tab remains device-first: target API, refresh, target device,
  automatic compatibility check, and matrix selection come before any startable
  test condition.
- Device discovery results use a compact selection table with status, default
  marker, device name, and action columns. API and full ID are shown in the
  selected-device summary instead of repeated in every row.
- The capability matrix is the only format-selection UI. Playback starts from a
  selected test condition rather than from a raw device or format alone.
- The format compatibility matrix is split into PCM and DSD sections. Each section
  keeps the format column frozen, uses sample-rate columns, uses short cell
  labels for density, and exposes the full requested/accepted format details in
  tooltips and the selected-format summary.
- Kernel Streaming `範囲一致` cells are KSDATARANGE candidates, not confirmed
  playback support. They may be selected with an explicit warning, but the UI
  must not label them as `使用可能`. `pin作成OK` means exact pin creation was
  checked without starting playback; `開始確認OK` is reserved for start-verified
  evidence.
- Kernel Streaming standard-packet cells and WaveRT cyclic-buffer cells are
  currently implemented KS playback models when the selected probe evidence
  marks `ks_playback_implementation=implemented`. WaveRT cyclic-buffer cells
  require both a looped KS interface and
  `accepts_wavert_notification_buffer=true` from the bounded no-RUN probe.
  Pure looped-streaming detections, and BasicSupport-only WaveRT detections
  without an accepted notification buffer, remain visible as
  diagnostics/tooltips, are non-selectable, and must not be collapsed into
  generic unsupported cells.
- Kernel Streaming device rows should show the driver/device-friendly name in
  the main table. Filter symbolic links and pin IDs remain in tooltips,
  selected-device IDs, logs, and bundles rather than dominating the first table
  label.
- When the matrix is built from a selected device that has no fresh probe rows,
  applicable cells should be filled from bounded non-playback checks as
  available, unsupported, in use, warning, error, or reference information.
  Applicable checked cells should not remain unchecked simply because only
  discovery data was present before device selection.
- The matrix must not ask the user to pick a requested playback format first.
  It should present the formats and result levels found by the compatibility
  scan. Closest-match or fallback evidence may remain visible as raw diagnostic
  evidence, but the matrix cell itself is a confirmed playable format, a
  candidate, a non-playable result, reference information, or not applicable.
- The capability matrix is scoped to the selected target API. Other API paths
  are not checked or selectable until the user changes the target API and
  refreshes that API explicitly.
- Probe rows are tied to the `format_revision` that produced them. If a
  format-affecting setting changes afterward, the old rows remain visible only
  as stale/read-only evidence and cannot be selected as the accepted playback
  format.
- Probe-row freshness is established only when an actual compatibility probe
  result is loaded for the current requested format. Device selection and
  device reselection never update the probe-row revision and cannot make stale
  rows current again.
- WASAPI shared/exclusive switches clear the selected endpoint and matrix
  condition. The user must refresh the new WASAPI mode, select the endpoint,
  let the automatic compatibility check complete, and select a fresh matrix
  cell.
- WASAPI `IAudioClient::GetMixFormat` rows are shown as reference rows with a
  localized reference note and no playable row action. The result column
  identifies them as mix-format references instead of normal supported rows.
- Long device IDs are truncated in tables but remain copyable for the selected
  device.
- Disabled action buttons explain the reason by tooltip or visible text.
- ASIO actions in ASIO-disabled builds are disabled with an explicit
  build-disabled reason.
- A next-required-action banner shows the current workflow gate.
- Recent log rendering is bounded for UI responsiveness. The full log remains
  available in the diagnostic bundle.

## Settings Wiring Rules

- Requested PCM format is built from GUI settings and is included first in
  MME, DirectSound, WASAPI shared, and WASAPI exclusive PCM probe candidates.
- Requested DoP carrier format is built from GUI DSD rate and channel count and
  is included first in WASAPI DoP and ASIO DoP probes.
- Requested native DSD format is built from GUI DSD rate, channel count, and
  supported DSD sample type and is passed to ASIO native DSD probe.
- ASIO PCM probe still reports the driver-current PCM output format; the GUI
  PCM request is logged as a requested setting and displayed as a preview.
- WASAPI probes check the GUI-requested format before mix-format fallback
  candidates. The `GetMixFormat` row is displayed as reference-only. A separate
  IsFormatSupported-tested `mix_format_fallback` candidate may still be
  explicitly selected when supported.
- Matrix construction uses the same non-playback compatibility checks as the
  explicit probe paths when fresh evidence is absent. The matrix remains scoped
  to the selected target API and shows unsupported/not-applicable cells rather
  than hiding candidate rows.
- Exact GUI-requested formats may be selected automatically after a probe.
  Fallback and closest-match rows require the user to explicitly choose the row
  before playback can use them.
- Automatic exact-format selection uses only fresh probe rows produced by an
  actual probe result for the current format revision. Plain discovery data,
  imported old snapshots, and stale rows are never auto-selected.
- PCM backend probes reject non-PCM signal requests. MME, DirectSound, WASAPI
  shared PCM, WASAPI exclusive PCM, and ASIO PCM checks cannot be used while
  DoP or ASIO native DSD is the requested signal.
- ASIO native DSD is ASIO-only. It cannot be checked or started under MME,
  DirectSound, WASAPI shared, or WASAPI exclusive.
- WASAPI DoP checks require both DoP signal mode and WASAPI exclusive as the
  requested backend.
- Playback starts only from a current `SelectedTestCondition`. A raw selected
  device or accepted format is not sufficient by itself.
- The requested backend, selected device backend, and selected playback backend
  must agree before matrix/start actions are enabled. Changing the requested
  backend clears selected devices, accepted formats, and matrix conditions.
  Old rows from the previous API mode cannot be used to create an accepted
  playback format, and the accepted playback backend must match the current
  requested backend.
- If a format-affecting setting changes after a format is accepted, that
  accepted format is stale and start/automation remain blocked until an
  automatic recheck or reselection from current probe results.
- Signal/run settings such as amplitude, duration, phase offset, buffer,
  lifecycle, and logging settings do not stale the accepted format. They are
  applied and logged when playback starts.

## Active Backend Interlock

Any active backend locks state-changing GUI operations. While a stream/session
is running, draining, held-open, or otherwise active, the GUI and state model
block backend changes, device selection changes, refresh, probe, automation
planning/running, and new start commands. The stop, keep-warm,
release-after-drain, log, and export paths remain available where safe.

## Runtime Status

`DiagnosticUiState::Tick()` is called once per GUI frame before rendering. It
polls active backend stats and appends newly emitted backend events without
starting, stopping, reopening, or releasing any device.

Updated counters include generated/submitted/accepted frames, callback count,
underruns/starvations, discontinuities, device invalidation count, and latest
backend error summary where available.
