feat(clients): HDR Steps 2-3 — apply mastering metadata + display capability-gate

Continues docs/hdr-pipeline-plan.md. Steps 0/1 + Step 2 (Windows/Android) already
landed in 3526517; this is Step 2 (Apple) + Step 3 (all clients). Client-only — no
core/host/ABI change (the 0xCE/next_hdr_meta/color_info surfaces shipped in Step 0).

Step 2 — clients APPLY the host's HDR metadata (each remaps from the wire form: ST.2086
G,B,R order, mastering luminance in 0.0001 cd/m2):
- Apple: connect via punktfunk_connect_ex5 (resurrects the previously-dead HDR pipeline);
  nextHdrMeta/colorInfo wrappers + HdrMeta SEI-blob builders; the pump drains nextHdrMeta
  -> VideoDecoder.setHdrMeta -> CVBufferSetAttachment of MasteringDisplayColorVolume (24B
  BE) + ContentLightLevelInfo (4B BE) on each HDR pixel buffer (correct for the
  itur_2100_PQ layer; CAEDRMetadata avoided as ambiguous there).

Step 3 — capability-gate: advertise HDR caps ONLY when the display can present it, so an
SDR display gets a proper BT.709 stream instead of PQ it would mis-tone-map; an HDR
display self-tone-maps from the Step-1/2 mastering metadata.
- Windows: present::display_supports_hdr() (DXGI any IDXGIOutput6 colour space == G2084),
  ANDed with the user HDR setting in session.rs; logs the SDR drop.
- Apple: NSScreen.maximumExtendedDynamicRangeColorComponentValue>1 (macOS) /
  UIScreen.main.potentialEDRHeadroom>1 (iOS) in SessionModel.
- Android: Settings.displaySupportsHdr (Display.getHdrCapabilities HDR10/HDR10+) passed
  through a new hdr_enabled jboolean on nativeConnect; session.rs gates the caps.

Validation: Android native (incl. the jboolean gate) builds + clippy clean via cargo-ndk;
fmt clean. Windows (MSVC), Apple (Swift) and the Kotlin side are CI/on-glass validated —
not compilable on the Linux dev box. Deferred to the RTX box: mid-session Reconfigure
SDR-downgrade on monitor move, and confirming the host emits SDR for an SDR client off an
HDR desktop.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

clients/apple/Sources/PunktfunkKit/PunktfunkConnection.swift

@@ -532,6 +532,11 @@ public final class PunktfunkConnection {
         }
     }
 
+    /// Video-capability bit: the client can decode a 10-bit (Main10) HEVC stream.
+    public static let videoCap10Bit: UInt8 = UInt8(PUNKTFUNK_VIDEO_CAP_10BIT)
+    /// Video-capability bit: the client can present BT.2020 PQ HDR10 (implies 10-bit).
+    public static let videoCapHDR: UInt8 = UInt8(PUNKTFUNK_VIDEO_CAP_HDR)
+
     /// Static HDR mastering metadata (SMPTE ST.2086 + content light level) the host sent for an HDR
     /// session. Mirrors the wire/ABI `PunktfunkHdrMeta`; primaries are in ST.2086 **G, B, R** order,
     /// 1/50000 units; mastering luminance in 0.0001 cd/m²; MaxCLL/MaxFALL in nits.

clients/apple/Sources/PunktfunkKit/Stage2Pipeline.swift

@@ -128,6 +128,11 @@ public final class Stage2Pipeline {
                         lastFramesDropped = dropped
                         recovery.request()
                     }
+                    // Drain any HDR mastering-metadata update (0xCE) and hand it to the decoder, which
+                    // attaches it to subsequent HDR frames. Non-blocking; only HDR sessions emit these.
+                    if connection.isHDR, let meta = try? connection.nextHdrMeta(timeoutMs: 0) {
+                        decoder.setHdrMeta(meta)
+                    }
                     guard let au = try connection.nextAU(timeoutMs: 100) else { continue }
                     onFrame?(au)
                     if let f = AnnexB.formatDescription(fromIDR: au.data) {

clients/apple/Sources/PunktfunkKit/VideoDecoder.swift

@@ -49,6 +49,12 @@ public final class VideoDecoder: @unchecked Sendable {
     /// pump can re-gate on the next IDR.
     private let onDecodeError: @Sendable (OSStatus) -> Void
 
+    /// Latest source HDR mastering metadata (from `PunktfunkConnection.nextHdrMeta`), attached to
+    /// each decoded HDR pixel buffer so the compositor tone-maps from the real grade. Guarded by its
+    /// own lock — written by the pump thread, read on the VT decode callback.
+    private let metaLock = NSLock()
+    private var hdrMeta: PunktfunkConnection.HdrMeta?
+
     public init(
         onDecoded: @escaping @Sendable (ReadyFrame) -> Void,
         onDecodeError: @escaping @Sendable (OSStatus) -> Void = { _ in }
@@ -59,6 +65,14 @@ public final class VideoDecoder: @unchecked Sendable {
 
     deinit { teardown() }
 
+    /// Set the source HDR mastering metadata (drained from `PunktfunkConnection.nextHdrMeta`). It's
+    /// attached to subsequent decoded HDR pixel buffers. Thread-safe; cheap to call on each update.
+    public func setHdrMeta(_ meta: PunktfunkConnection.HdrMeta) {
+        metaLock.lock()
+        hdrMeta = meta
+        metaLock.unlock()
+    }
+
     /// Submit one AU for asynchronous decode, (re)creating the session if `format` changed. The
     /// caller resolves `format` from the IDR exactly as stage-1 does (`AnnexB.formatDescription`).
     /// Returns false if the session couldn't be created or the frame couldn't be submitted.
@@ -185,6 +199,22 @@ public final class VideoDecoder: @unchecked Sendable {
         let isHDR =
             CVPixelBufferGetPixelFormatType(imageBuffer)
             == kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange
+        // Attach the source's mastering display + content light level (ST.2086 / CEA-861.3) so the
+        // compositor tone-maps from the real grade rather than inferring from the PQ colourspace
+        // alone. The SEI byte payloads map 1:1 to these CVImageBuffer attachment keys.
+        if isHDR {
+            metaLock.lock()
+            let meta = hdrMeta
+            metaLock.unlock()
+            if let meta {
+                CVBufferSetAttachment(
+                    imageBuffer, kCVImageBufferMasteringDisplayColorVolumeKey,
+                    meta.masteringDisplayColorVolume() as CFData, .shouldPropagate)
+                CVBufferSetAttachment(
+                    imageBuffer, kCVImageBufferContentLightLevelInfoKey,
+                    meta.contentLightLevelInfo() as CFData, .shouldPropagate)
+            }
+        }
         onDecoded(
             ReadyFrame(ptsNs: ptsNs, decodedNs: decodedNs, pixelBuffer: imageBuffer, isHDR: isHDR))
     }