[bilipp]

Summary

App side of #207, round 2a. It pairs with bilipp/LumeEngine#33, which carries the picture fixes:

• Dolby Vision profile 5 / 20 / 10.0 no longer render pink/green; the engine now reshapes the IPT base layer to HDR10 on the GPU.
• CPU-decoded HDR is no longer washed out.

This PR makes sure LumeEngine gets the right audio output width, and that its diagnostics reach the exported report.

Audio: negotiate the width before the lane is built

Before this PR, LumeEngine read AVAudioSession.outputNumberOfChannels when it built its audio lane. That lost an ordering race: LumeEngineEngineView starts the session from .onAppear, but FullScreenPlayerView only activated and widened the route from a later .task. A session opens exactly one URL with no rebuild-in-place, so a width resolved too early stays for the whole stream. The result: a 5.1 track could reach a surround receiver as stereo.

• New PlaybackAudioRoute owns playback audio-session setup. activateForPlayback() is idempotent and is called from LumeEngineCoordinator.makeConfiguration. Whichever caller runs first negotiates and the other reuses the result, so ordering can no longer clamp the lane to stereo.
• It activates the session before reading channel counts. An inactive session reports 2 even on a route that can carry more.
• negotiatedWidth is min(granted, maximum), and nil at or below stereo. It never passes maximumOutputNumberOfChannels through: that is what the route could carry, not what was granted, and over-shooting fails AVSampleBufferAudioRenderer outright (silence, wedged pipeline).
• macOS asks CoreAudio for the default output device's width, instead of the engine's flat 2-channel fallback.
• MultiViewScreen keeps a deliberately stereo session via activateStereo(). Only one tile is audible, so a surround layout for a muted grid would be wrong.

Diagnostics

• The exported diagnostic report now includes engine.lume/diagnostics, so the engine's once-per-stream readouts survive into a report a user sends:

  • stream-open (DV profile, object audio)
  • video-format
  • dv-reshape
  • audio-width

  The raw engine.lume/ffmpeg bridge stays excluded, because some streams log to it per frame.

Docs

• AGENTS.md: Dolby word marks must never appear in user-facing UI, String Catalogs or store copy; use technical labels (HDR10, DV P8.1, E-AC-3 JOC, …). It also records the host-stated audio-width contract.

Refs #207. This PR does not close it: the technical-label UI badges (round 2b) are still to come.

What was measured

• DV P8.1 on Apple TV 4K: already correct on the VideoToolbox path (all three colour keys present, picture clean).
• DV P20 (DVprofile20.mp4): tinted on every path, Apple's own decoder included. Fixed in LumeEngine#33 and verified on macOS; still needs a run on Apple TV / iPhone.
• Audio width on hardware: not validated yet. The Apple TV run used AirPlay (2 ch), where stereo is correct. An HDMI run should show widthSource=configured with route=HDMIOutput(…).

Type of change

• feat — new feature

Platforms verified

• iOS / iPadOS
• macOS
• tvOS
• visionOS

visionOS is not verified. No simulator runtime is installed, and main does not build for it independently of this PR: PictureInPictureBridge is gated #if os(iOS) || os(macOS) || os(tvOS) in LumeEngine, while LumeEngineCoordinator references it ungated.

Screenshots / recordings

None; no UI changes.

Checklist

• Issue linked (feat: Dolby Vision and Dolby Atmos support in the internal engines #207).
• Conventional Commits.
• Pre-commit hooks pass (SwiftFormat, SwiftLint --strict, String Catalog normalization).
• LumeTests green (iPhone 17 Pro / iOS 26.4, -parallel-testing-enabled NO). LumeUITests not run.
• Builds for the iOS and tvOS Simulators against the current LumeEngine#33 branch.
• Localization: n/a, no user-facing text.
• Tests: PlaybackAudioRouteTests (stereo route ⇒ nil; granted 6 / maximum 8 ⇒ 6, never 8; ungranted preference ⇒ nil; clamping) and DebugLogExporterTests.
• No credentials, stream URLs or other content.